healpix_analyse.pyramid_conv
============================

.. py:module:: healpix_analyse.pyramid_conv

.. autoapi-nested-parse::

   Pyramidal convolution on HEALPix maps: block-diagonal kernel pyramid +
   :class:`~healpix_analyse.decomp.HealPixDecomp`, with correct NaN/weight
   propagation.

   See :mod:`healpix_analyse.kernel_pyramid` for the precise sense in which a
   per-band kernel is an *approximation* (block-diagonal in ``B_K``), and for
   the mandatory validation step against :mod:`healpix_analyse.validation`.



Classes
-------

.. autoapisummary::

   healpix_analyse.pyramid_conv.HealPixPyramidConv


Module Contents
---------------

.. py:class:: HealPixPyramidConv(decomp: healpix_analyse.decomp.HealPixDecomp, kernel_pyramid: healpix_analyse.kernel_pyramid.HealPixKernelPyramid, *, mode: str = 'normalized')

   Bases: :py:obj:`torch.nn.Module`


   Apply a :class:`~healpix_analyse.kernel_pyramid.HealPixKernelPyramid`
   through a matched :class:`~healpix_analyse.decomp.HealPixDecomp`.

   :Parameters: * **decomp** (:py:class:`HealPixDecomp`) -- Must be the same decomposition the kernel pyramid was built from
                  (same levels, cell-id domains).
                * **kernel_pyramid** (:py:class:`HealPixKernelPyramid`)
                * **mode** (``{"normalized", "signed"}``, *default* ``"normalized"``) -- ``"normalized"`` (default): NaN/weight-aware. Internally runs
                  :meth:`~healpix_analyse.decomp.HealPixDecomp.compute_weighted` on the input, applies the
                  kernel pyramid identically to the data channel ``q`` and the weight
                  channel ``m``, synthesizes both, and divides **once** --
                  ``y = S(B_K q) / S(B_K m)`` -- never band by band. This is a strict
                  superset of plain filtering: on fully finite data with no
                  ``weights`` given, ``m`` is uniformly 1 and the division is a no-op
                  up to floating-point round-off, so this mode is safe to use as the
                  default even without missing data.
                  ``"signed"``: no masking at all -- runs the kernel pyramid directly
                  on :meth:`~healpix_analyse.decomp.HealPixDecomp.compute`/:meth:`~healpix_analyse.decomp.HealPixDecomp.invert`. Only
                  meaningful on fully finite input; useful for validating kernels that
                  are not required to stay positive (signed kernels), where dividing
                  by a synthesized weight would be the wrong operation.


   .. py:attribute:: decomp


   .. py:attribute:: kernel_pyramid


   .. py:attribute:: mode
      :value: 'normalized'



   .. py:method:: apply_pyramid(pyramid: Union[healpix_analyse.decomp.HealPixPyramid, healpix_analyse.decomp.HealPixWeightedPyramid]) -> Union[healpix_analyse.decomp.HealPixPyramid, healpix_analyse.decomp.HealPixWeightedPyramid]

      Apply the per-band kernels to an already-computed pyramid.

      Does **not** synthesize or divide -- use :meth:`forward` (or
      :meth:`~healpix_analyse.decomp.HealPixDecomp.invert`) for that. Accepts either a plain
      :class:`~healpix_analyse.decomp.HealPixPyramid` or a
      :class:`~healpix_analyse.decomp.HealPixWeightedPyramid` (in which
      case the *same* per-band kernels are applied to both the ``q`` and
      ``m`` channels, as required for a valid normalized-convolution
      result).



   .. py:method:: forward(x: ArrayLike, weights: Optional[ArrayLike] = None, *, return_support: bool = False, restore_mask: bool = True, eps: float = 1e-08)

      Convolve ``x`` through the pyramid.

      In ``"normalized"`` mode (default), returns the masked/weighted
      result ``y = S(B_K q) / S(B_K m)``; when ``return_support=True``,
      also returns the synthesized support map ``S(B_K m)`` (the
      post-convolution confidence/coverage, useful for diagnosing where
      the result is under-supported without being a per-band clip).

      In ``"signed"`` mode, ``weights``/``return_support`` are not
      accepted (raises ``ValueError``) -- there is no weight channel to
      report support from.