HEALPixSHT — API reference#

Every public method of HEALPixSHT, and what the transform costs. The guide is HEALPixSHT — spherical harmonics on the full sky; the conventions are HEALPixSHT — conventions and algorithm.

Methods#

HEALPixSHT(level, lmax, dtype, device, ellipsoid)#

Instantiate the transform and precompute all geometry.

Parameter

Type

Default

Description

level

int

—

Grid4Earth/HEALPix level, integer ≥ 0. Internally, nside = 2**level.

lmax

int or None

3·2**level - 1

Maximum multipole ℓ.

dtype

torch.dtype

torch.float32

Real dtype for maps. Use torch.float64 for high-precision work.

device

str or torch.device or None

auto

Computation device. Defaults to CUDA when available.

ellipsoid

str

"sphere"

Geometry model: "sphere" or "WGS84".

Read-only attributes

Attribute

Description

sht.nside

HEALPix nside

sht.lmax

Maximum multipole

sht.n_pix

Total pixels: 12·nside²

sht.n_rings

Number of iso-latitude rings: 4·nside − 1

sht.n_alm

Number of alm coefficients: (lmax+1)·(lmax+2)//2

sht.map2alm(im, nest=False) → Tensor[..., K]#

Analysis transform: HEALPix map → spherical harmonic coefficients.

a_lm = ∫ f(θ,φ) · Y_lm*(θ,φ) dΩ

Parameter

Description

im

(..., N) real array-like or Tensor. RING ordering by default.

nest

bool. Set True for NESTED input.

Returns a complex Tensor of shape (..., K) where K = (lmax+1)·(lmax+2)//2.

alm layout (same as healpy):

[m=0: l=0..lmax | m=1: l=1..lmax | … | m=lmax: l=lmax]

sht.alm2map(alm, nest=False) → Tensor[..., N]#

Synthesis transform: a_lm → HEALPix map.

f(θ,φ) = Σ_{l,m} a_lm · Y_lm(θ,φ)

Parameter

Description

alm

(..., K) complex array-like or Tensor.

nest

bool. Set True for NESTED output.

Returns a real Tensor of shape (..., N).

sht.map2alm_spin(Q, U, spin, nest=False) → (almE, almB)#

Spin-s analysis: (Q, U) → E-mode and B-mode spherical harmonic coefficients.

spin

Physical interpretation

0

Scalar pair: almE = map2alm(Q), almB = map2alm(U)

1

Vector field: almE = divergent part, almB = rotational part

2

CMB polarisation: almE = E-modes, almB = B-modes

Parameter

Description

Q

(..., N) real Tensor — first component (east / Stokes Q).

U

(..., N) real Tensor — second component (north / Stokes U).

spin

int. Spin weight: 0, 1, or 2.

nest

bool. NESTED ordering.

Returns (almE, almB), each a complex Tensor of shape (..., K).

Requires quaternionic and spherical packages for spin > 0.

sht.alm2map_spin(almE, almB, spin, nest=False) → (Q, U)#

Spin-s synthesis: adjoint of map2alm_spin.

Parameter

Description

almE

(..., K) complex Tensor.

almB

(..., K) complex Tensor.

spin

int. Spin weight: 0, 1, or 2.

nest

bool. NESTED output.

Returns (Q, U), each a real Tensor of shape (..., N).

sht.uv_to_curl_div(u, v, nest=False) → (div, curl)#

One-call Helmholtz–Hodge decomposition of a tangent-plane vector field.

Internally calls map2alm_spin(u, v, spin=1) and alm2map_spin(almE, almB, spin=1).

Parameter

Description

u

(..., N) real Tensor — east component.

v

(..., N) real Tensor — north component.

nest

bool. NESTED ordering.

Returns:

Output

Description

div

Divergence map ∇·v — sources and sinks of the flow.

curl

Vorticity map ∇×v — rotation intensity of the flow.

sht.anafast(im, map2=None, spin=0, nest=False) → Tensor#

Angular power spectrum C_ℓ.

Parameter

Description

im

(..., N) for spin=0, or (..., 2, N) for spin>0 with [Q, U] on axis -2.

map2

Same shape as im. If given, computes the cross-spectrum.

spin

int. 0 for scalar; 1 or 2 for E/B modes.

nest

bool. NESTED ordering.

Returns

  • spin=0 → (..., lmax+1) real Tensor.

  • spin>0 → (..., 3, lmax+1) real Tensor with [C_l^EE, C_l^BB, C_l^EB].

Formula (spin=0):

C_l = 1/(2l+1) × [ |a_{l0}|² + 2 Σ_{m=1}^{l} |a_{lm}|² ]

Cost and tuning#

  • Precomputation: the Legendre tables and phase matrix are computed once at HEALPixSHT(level=...) time. At level=6 (nside=64) this takes ~0.5 s; subsequent calls to map2alm / alm2map are fast.

  • Spin harmonics are computed lazily on the first call to map2alm_spin for a given spin value and cached for all subsequent calls.

  • dtype: use torch.float32 for speed-critical applications (training, large batches). Use torch.float64 when comparing against healpy or when high numerical accuracy matters.

  • GPU: pass device="cuda" at construction time. All hot-path operations (fft, einsum) run natively on GPU.

  • Batch size: process many maps at once with a leading batch dimension im.shape = (B, N) for an effective B× throughput increase on GPU.