healpix_analyse.down#

HEALPix resolution-reduction operator for the healpix_analyse package.

Reduces the HEALPix resolution by a factor of 2:

nside_out = nside_in // 2 N_out = N_in // 4

Two modes:

“smooth” – weighted Gaussian average over a disc (linear, differentiable). “maxpool” – non-linear max over the 4 direct NESTED children.

Works on the full sphere or on a partial-sky subset. Resolution is exposed through the Grid4Earth level convention, with nside = 2**level.

Accepts numpy arrays or torch tensors of shape [N] or [B, N] and returns an output of the same type and number of dimensions.

Dependencies: numpy, torch, healpy.

Attributes#

ArrayLike

Classes#

HealPixDown

HEALPix downsampling: reduce resolution by a factor of 2.

Module Contents#

healpix_analyse.down.ArrayLike#
class healpix_analyse.down.HealPixDown(level: int, mode: str = 'smooth', ellipsoid: str = 'WGS84', radius_deg: float | None = None, sigma_deg: float | None = None, weight_norm: str = 'l1', cell_ids: ArrayLike | None = None, device: str | torch.device | None = None, dtype: torch.dtype = torch.float32)[source]#

Bases: torch.nn.Module

HEALPix downsampling: reduce resolution by a factor of 2.

Reduces level → level - 1 using either a Gaussian-weighted sparse matrix (mode="smooth") or a max-pooling over the 4 direct NESTED children (mode="maxpool").

Can operate on the full sphere or on a partial-sky subset.

Parameters:

  • level (int) – Input Grid4Earth/HEALPix level. Must be an integer ≥ 1. The corresponding HEALPix resolution is nside_in = 2**level. When cell_ids is None, the input is expected to have N = 12 * nside_in**2 pixels.

  • mode ({"smooth", "maxpool"}, default "smooth") – Downsampling strategy. smooth – differentiable Gaussian-weighted average (linear). maxpool – non-linear max over 4 NESTED children (fast).

  • radius_deg (float or None) – Angular radius of the Gaussian kernel (degrees). Defaults to ~3 times the fine pixel size. Only used for mode="smooth".

  • sigma_deg (float or None) – Gaussian sigma (degrees). Defaults to radius_deg / 2. Only used for mode="smooth".

  • weight_norm ({"l1", "l2", "none"}, default "l1") – Normalisation applied per output pixel in mode="smooth": l1 – sum of weights = 1 (preserves constant fields). l2 – sum of squares = 1 (preserves local energy). none – raw Gaussian weights (not recommended).

  • cell_ids (array-like of int or None) – Pixel indices (NESTED ordering) of the input sub-map. If None, the operator covers the full sphere.

  • device (torch.device or str or None) – Device for the sparse matrix and computations. Defaults to CUDA if available, else CPU.

  • dtype (torch.dtype, default torch.float32) – Floating-point dtype for the sparse matrix values.

Examples

Full sphere:

>>> import numpy as np
>>> from healpix_analyse.down import HealPixDown
>>> level = 6
>>> nside = 2**level
>>> x = np.random.randn(12 * nside**2)          # [N]
>>> down = HealPixDown(level=level)
>>> y, cell_ids_out = down(x)
>>> y.shape
(12288,)   # 12 * 32**2

Partial sky:

>>> import healpy as hp
>>> cell_ids = hp.query_disc(nside, hp.ang2vec(np.pi/2, 0), 0.3, nest=True)
>>> down = HealPixDown(level=level, cell_ids=cell_ids)
>>> y, coarse_ids = down(x[cell_ids])
device#
dtype = Ellipsis#
ellipsoid = ''#
level_in#
level_out#
level#
nside_in#
nside_out#
N_in_full#
N_out_full#
mode = ''#
weight_norm = ''#
partial#
property cell_ids_out: numpy.ndarray#

Output cell ids (coarse-resolution NESTED indices).

forward(x: ArrayLike) → Tuple[ArrayLike, numpy.ndarray][source]#

Apply the downsampling operator.

Parameters:

x (numpy.ndarray or torch.Tensor, shape [N] or [B, N]) – Input map(s) at fine resolution nside_in. When cell_ids was given at construction, N must equal len(cell_ids). Otherwise N = 12 * nside_in**2.

Returns:

  • y (same type as x, shape [N_out] or [B, N_out]) – Downsampled map(s) at coarse resolution nside_out.

  • cell_ids_out (np.ndarray) – NESTED pixel indices of the output pixels at nside_out.