Skip to main content

healpix-analyse

Documentation License Python DOI

A Python toolkit for analysing signals defined on HEALPix spherical grids, with a focus on Earth Observation data. All operators are implemented in PyTorch and are fully differentiable through torch.autograd.

Read the full documentation


Features

  • Spherical harmonic transforms — local ALM coefficients, ring-based full-sky SHT (spin-0, 1, 2), power spectra
  • Local 2D FFT — pole-safe gnomonic projection, fast FFT/IFFT, CUDA and autograd
  • FFT large-kernel convolution — zero-padded local HealPixFFTConv with CUDA and autograd
  • Gauge-equivariant convolution — HealPixConv with configurable kernel size, gauge types, and number of gauges
  • Large-kernel convolution — matched Down/Up hierarchy with a compact learned kernel
  • Multi-resolution operators — HealPixDown (smooth / max-pool) and HealPixUp (adjoint upsampling), NESTED ordering
  • Masked multiscale decomposition — exactly reconstructing local HealPixDecomp pyramids
  • Multiscale divergence and curl — gauge-aware local derivatives of HEALPix velocity fields
  • HEALPix resampling — local Up/Down conversion between full or partial NESTED domains
  • Differentiable by default — all hot-path operations are autograd-compatible
  • NumPy and Torch interoperability — accepts both array types, returns the same type

Package map

healpix_analyse/
├── alm.py               # Local complex spherical harmonic coefficients
├── alm_latlon.py         # SHT for arbitrary iso-latitude grids
├── healpix_sht.py        # Ring-based full-sky SHT for HEALPix
├── fft_local.py          # Gnomonic 2D FFT for local HEALPix patches
├── fft_conv.py           # FFT-accelerated large-kernel local convolution
├── convol.py             # Gauge-equivariant spherical convolution (HealPixConv)
├── large_conv.py         # Multiresolution large-receptive-field convolution
├── dino.py               # DINOv3 SAT-493M embeddings of NESTED blocks (backbone loaded at run time, DINOv3 License)
├── down.py               # Resolution reduction (HealPixDown)
├── up.py                 # Resolution increase (HealPixUp)
├── decomp.py             # Exact local multiscale pyramid (HealPixDecomp)
├── divcurl.py            # Gauge-aware divergence/curl at every pyramid scale
├── powerspectra.py        # Isotropic power spectrum on HEALPix patches
├── powerspectra_lonlat.py # Power spectrum on irregular lon/lat grids
├── healpix_interp.py      # Bilinear interpolation on HEALPix (NESTED)
├── make_rectangle.py      # Rectangular HEALPix patches from bounding boxes
├── resample.py            # HEALPix level/domain resampling and regular lat/lon conversion
└── ps.py                  # Power spectrum utilities

Quick start

All HEALPix-facing public interfaces use the Grid4Earth level convention; the internal HEALPix resolution is always nside = 2**level.

import numpy as np
import healpy as hp
from healpix_analyse.alm_latlon import build_rings_from_latlon, anafast_latlon

nside = 64
npix  = 12 * nside**2
lmax  = 3 * nside

# Random test map
im = np.random.randn(npix)

# Build ring structure from HEALPix coordinates
theta, phi = hp.pix2ang(nside, np.arange(npix))
ring_theta, ring_phi_list, ring_counts, sort_idx = build_rings_from_latlon(
    theta, phi, convention="colatitude_rad"
)

# Compute angular power spectrum
cl = anafast_latlon(
    im[sort_idx], ring_theta, ring_phi_list, ring_counts,
    lmax=lmax, quadrature="equal_area",
)
print(cl.shape)   # torch.Size([193])

Local flat-sky FFT

from healpix_analyse import LocalFFT

transform = LocalFFT(cell_ids, level, device="cuda")
spectrum = transform.fft(data)
reconstructed = transform.ifft(spectrum)
frequency, power = transform.ps(spectrum)

The transform accepts local NESTED HEALPix patches up to a configurable angular radius (10 degrees by default). Its three-dimensional tangent-frame construction works at the poles and across 0/360 degrees. See the detailed local FFT documentation for geometry, normalisation, reconstruction accuracy and Sentinel-2 examples.

FFT-accelerated large kernels

from healpix_analyse import HealPixFFTConv

layer = HealPixFFTConv(
    level=12,
    in_channels=4,
    out_channels=8,
    kernel_sz=65,
    cell_ids=cell_ids,
    device="cuda",
)
y = layer(x)

The layer performs a zero-padded linear convolution on the same pole-safe gnomonic grid used by LocalFFT. See the FFT convolution documentation.

Large receptive-field convolution

from healpix_analyse import LargeConv

layer = LargeConv(
    level=8,  # nside = 2**level = 256
    in_channels=8,
    out_channels=16,
    kernel_sz=33,
    max_compact_kernel_sz=7,
)
y = layer(x)

This example automatically uses three smooth Down operations, a compact 5×5 convolution, and the three exactly paired Up operations. See the LargeConv documentation for kernel planning, partial patches, gradients and limitations.

Exactly reconstructing multiscale decomposition

from healpix_analyse import HealPixDecomp

decomp = HealPixDecomp(level=10, cell_ids=ocean_cell_ids, Jmax=5)
pyramid = decomp.compute(u_v)
u_v_reconstructed = decomp.invert(pyramid)

The pyramid retains the NESTED cell identifiers at every scale and works on irregular masked domains such as ocean fields bounded by coastlines. See the multiscale decomposition documentation.

Convolution with a wide kernel

import numpy as np
from healpix_analyse import HealPixWideConv

conv = HealPixWideConv.from_radial(
    lambda r: np.exp(-r / 500.0),        # r in metres
    level=17, n=64, lon=2.3198, lat=48.8704, Jmax=6,
)
y = conv(x, cell_ids)                    # x: [N] or [..., N] -> same shape

A kernel tens of pixels wide does not fit in a compact stencil. HealPixWideConv decomposes the field into a Laplacian pyramid, convolves each band with its own small (5x5) kernel — fitted automatically from the kernel you supplied — and synthesizes. The kernel can be given as an image on the HEALPix lattice, as a function of x, y or of r in metres, or as a metric raster resampled onto the cells' true positions. See the wide-kernel convolution documentation.

Multiscale divergence and curl

from healpix_analyse import HealPixMultiScaleDivCurl

divcurl = HealPixMultiScaleDivCurl(decomp, kernel_sz=3, n_gauges=2)
diagnostics = divcurl(pyramid)

divergence = diagnostics.div
curl = diagnostics.curl

Each scale uses a fixed derivative-of-Gaussian HealPixConv kernel normalised by that level's physical pixel spacing. See the divergence and curl documentation.

HEALPix-to-HEALPix resampling

from healpix_analyse import resample_healpix

out_data, out_ids = resample_healpix(
    in_data,
    in_level=11,
    out_level=8,
    in_cell_ids=in_cell_ids,
    out_cell_ids=out_cell_ids,
)

The output order follows out_cell_ids; unavailable cells are filled with NaN. See the HEALPix resampling documentation.


Installation

pip install git+https://github.com/GRID4EARTH/healpix-analyse.git

From source (development)

git clone git@github.com:GRID4EARTH/healpix-analyse.git
cd healpix-analyse
pip install -e .

Documentation

Full documentation is available at grid4earth.eu/healpix-analyse.

To build locally:

pip install -e ".[docs]"
cd docs
make html

Relationship to healpix-geo and healpix-ai

  • healpix-geo — HEALPix geometry: pixel coordinates, ellipsoids, coverage queries
  • healpix-analyse — signal analysis: SHT, convolutions, power spectra, multi-resolution operators
  • healpix-ai — deep learning: autoencoders, U-Nets, forecasters built on top of healpix-analyse

Development and contributing

Bug reports, feature requests, and contributions are welcome. See CONTRIBUTING.md for the contribution process and DEVELOPMENT.md for the lightweight branch and cross-repository development workflow.

Citation

GitHub releases are archived by Zenodo. Use the DOI badge at the top of this page to cite the latest archived release, or cite the DOI for the exact version used in your work.

Funding and acknowledgements

Funded by ESA, built by a European consortium.

ESA Contract: 4000147951/25/I-NS — Technical Officer: Vincent Dumoulin.

We also thank all external contributors and the open-source projects on which healpix-analyse depends.

License

Apache 2.0 — see LICENSE.

Metadata

Release files for healpix-analyse 2026.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for healpix-analyse 2026.11.0
File Size Uploaded Provenance Actions
healpix_analyse-2026.11.0.tar.gz 20.0 MB With provenance Details for healpix_analyse-2026.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for healpix-analyse 2026.11.0
File Interpreter ABI Platform Actions
healpix_analyse-2026.11.0-py3-none-any.whl Python 3 none any Details for healpix_analyse-2026.11.0-py3-none-any.whl

Total release size: 20.2 MB

Release files / healpix_analyse-2026.11.0.tar.gz

Download URL healpix_analyse-2026.11.0.tar.gz
Size 20.0 MB
Tags Source
SHA-256 checksum
How to use checksums
33e73770d86f8564e7c297e4bab20193b9f0d3c58e9c702260f66d24b2e63b66
BLAKE2b-256 checksum
How to use checksums
b394c01498f47676305f6e1dc55de5de4ef881ce60afa7481b0a0de902318e79
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / healpix_analyse-2026.11.0-py3-none-any.whl

Download URL healpix_analyse-2026.11.0-py3-none-any.whl
Size 213.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7e735090e41aecd84d5912ceb5ab6b79dd611e941e7754544122152f71ae4adf
BLAKE2b-256 checksum
How to use checksums
7b760867c21ebf01dc7d1c74f76fc1b2d47db355679a065df0f2b4f354f4b01c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for healpix-analyse 2026.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for healpix_analyse-2026.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page