healpix_analyse.pyramid_conv#

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

See 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 healpix_analyse.validation.

Classes#

HealPixPyramidConv

Apply a HealPixKernelPyramid

Module Contents#

class healpix_analyse.pyramid_conv.HealPixPyramidConv(decomp: healpix_analyse.decomp.HealPixDecomp, kernel_pyramid: healpix_analyse.kernel_pyramid.HealPixKernelPyramid, *, mode: str = 'normalized')[source]#

Bases: torch.nn.Module

Apply a HealPixKernelPyramid through a matched HealPixDecomp.

Parameters:

  • decomp (HealPixDecomp) – Must be the same decomposition the kernel pyramid was built from (same levels, cell-id domains).

  • kernel_pyramid (HealPixKernelPyramid)

  • mode ({"normalized", "signed"}, default "normalized") – "normalized" (default): NaN/weight-aware. Internally runs 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 compute()/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.

decomp#
kernel_pyramid#
mode = 'normalized'#
apply_pyramid(pyramid: healpix_analyse.decomp.HealPixPyramid | healpix_analyse.decomp.HealPixWeightedPyramid) → healpix_analyse.decomp.HealPixPyramid | healpix_analyse.decomp.HealPixWeightedPyramid[source]#

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

Does not synthesize or divide – use forward() (or invert()) for that. Accepts either a plain HealPixPyramid or a 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).

forward(x: ArrayLike, weights: ArrayLike | None = None, *, return_support: bool = False, restore_mask: bool = True, eps: float = 1e-08)[source]#

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.