healpix_analyse.up#

HEALPix resolution-increase operator for the healpix_analyse package.

Increases the HEALPix resolution by a factor of 2:

nside_out = nside_in * 2 N_out = N_in * 4

The operation is defined as the adjoint (transpose) of the smooth downsampling matrix from healpix_analyse.down, with an optional diagonal normalisation that improves round-trip consistency.

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#

HealPixUp

HEALPix upsampling: increase resolution by a factor of 2.

Module Contents#

healpix_analyse.up.ArrayLike#
class healpix_analyse.up.HealPixUp(level: int, radius_deg: float | None = None, sigma_deg: float | None = None, weight_norm: str = 'l1', up_norm: str = 'col_l1', eps: float = 1e-12, ellipsoid: str = 'WGS84', cell_ids: ArrayLike | None = None, device: str | torch.device | None = None, dtype: torch.dtype = torch.float32, paired_down: healpix_analyse.down.HealPixDown | None = None)[source]#

Bases: torch.nn.Module

HEALPix upsampling: increase resolution by a factor of 2.

Implements the adjoint of the smooth downsampling operator from healpix_analyse.down.HealPixDown:

x_up = M^T @ x

where M is the (N_coarse × N_fine) downsampling matrix.

Optional diagonal normalisation modes improve amplitude preservation for constant fields or local energy:

  • "adjoint" – raw transpose (M^T x).

  • "col_l1" – divide by column sums of M: preserves constant fields

    when HealPixDown used weight_norm="l1".

  • "diag_l2" – divide by diagonal of M^T M: least-squares diagonal

    preconditioner (local amplitude correction).

Parameters:

  • level (int) – Coarse input Grid4Earth/HEALPix level (integer ≥ 0). Internally, nside_in = 2**level and the output level is level + 1.

  • radius_deg (float or None) – Angular radius passed to HealPixDown for building the transpose matrix. None → default.

  • sigma_deg (float or None) – Gaussian sigma (degrees). None → default.

  • weight_norm ({"l1", "l2", "none"}, default "l1") – Weight normalisation used when building the downsampling matrix. Must match the norm used by the paired HealPixDown.

  • up_norm ({"adjoint", "col_l1", "diag_l2"}, default "col_l1") – Diagonal normalisation applied after the transpose: adjoint – no normalisation. col_l1 – preserve constant fields. diag_l2 – preserve local energy.

  • eps (float, default 1e-12) – Small value added to the denominator to avoid division by zero.

  • cell_ids (array-like of int or None) – Coarse pixel indices (NESTED) for partial-sky operation. If None, the operator covers the full sphere.

  • device (torch.device or str or None) – Device for computation. Defaults to CUDA if available, else CPU.

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

  • paired_down (HealPixDown or None) – Reuse the exact sparse matrix and fine-cell domain of an existing smooth downsampler. This is the strictest way to construct a matched Up operator for a partial patch. cell_ids must then be omitted; the ellipsoid and weight normalisation are inherited.

Examples

Full sphere:

>>> import numpy as np
>>> from healpix_analyse.up import HealPixUp
>>> level = 5
>>> nside = 2**level
>>> x = np.random.randn(12 * nside**2)      # [N_coarse]
>>> up = HealPixUp(level=level)
>>> y, cell_ids_out = up(x)
>>> y.shape
(49152,)   # 12 * 64**2

Partial sky:

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

Output cell ids (fine-resolution NESTED indices).

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

Apply the upsampling operator.

Parameters:

x (numpy.ndarray or torch.Tensor, shape [N] or [B, N]) – Input map(s) at coarse 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]) – Upsampled map(s) at fine resolution nside_out = nside_in * 2.

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