healpix_analyse.divcurl

Local, gauge-aware divergence and curl on multiscale HEALPix maps.

The differential stencil is evaluated by HealPixConv. Horizontal east/north components are first embedded in a global Cartesian tangent vector. This makes the sampled channels independent of the local coordinate frame. Two fixed derivative-of-Gaussian kernels then estimate directional derivatives along the gauge axes, which are contracted to the intrinsic surface divergence and outward-normal scalar curl.

Classes

HealPixDivCurlPyramid	List-like divergence/curl maps returned for a HEALPix pyramid.
HealPixDivCurl	Estimate divergence and curl at one HEALPix resolution.
HealPixMultiScaleDivCurl	Apply HealPixDivCurl to every band of a decomposition.

Module Contents

class healpix_analyse.divcurl.HealPixDivCurlPyramid

Bases: Sequence[ArrayLike]

List-like divergence/curl maps returned for a HEALPix pyramid.

Every band has shape [..., 2, N_j] after gauge reduction, with channel zero containing divergence and channel one containing curl. With gauge_reduce="none", the shape is [..., G, 2, N_j].

bands: tuple[ArrayLike, ...]

cell_ids: tuple[numpy.ndarray, ...]

levels: tuple[int, ...]

pixel_spacing_m: tuple[float, ...]

gauge_reduce: str

property div: tuple[ArrayLike, ...]

Divergence maps ordered from fine to coarse.

property curl: tuple[ArrayLike, ...]

Outward-normal scalar-curl maps ordered from fine to coarse.

class healpix_analyse.divcurl.HealPixDivCurl(level: int, cell_ids=None, *, kernel_sz: int = 3, sigma_pix: float | None = None, n_gauges: int = 1, gauge_type: str = 'phi', gauge_reduce: str = 'mean', radius_m: float = 6371008.8, singularity_lonlat=None, ref_direction=None, ellipsoid: str = 'sphere', dtype: torch.dtype = torch.float32, device: str | torch.device | None = None, cache_dir=_DEFAULT_CACHE_DIR)

Bases: torch.nn.Module

Estimate divergence and curl at one HEALPix resolution.

Parameters:

• level (int) – Grid4Earth/HEALPix level, with nside = 2**level.

• cell_ids (array-like, optional) – NESTED identifiers in the same order as the input velocity samples. None selects the full sphere.

• kernel_sz (int, default 3) – Odd derivative-of-Gaussian stencil size. Must be at least three.

• sigma_pix (float, optional) – Gaussian width in native pixels. The default is kernel_sz / 3.

• n_gauges (int, default 1) – Number of rotated HealPixConv gauges. Multiple gauges provide orientation-averaged estimates when gauge_reduce="mean".

• gauge_type (str, default "phi") – Gauge convention passed directly to HealPixConv.

• gauge_reduce ({"mean", "none"}, default "mean") – Average the gauge estimates or retain an explicit gauge dimension.

• radius_m (float, default 6371008.8) – Sphere radius used to convert the angular native-pixel spacing to metres. Velocity in m/s then produces divergence and curl in 1/s.

Notes

Input channels are eastward u and northward v. They are embedded as a three-component Cartesian tangent vector before convolution. If a and b are the two oriented gauge axes and V is this vector, the returned scalars are

div = a . d_a(V) + b . d_b(V)

curl = b . d_a(V) - a . d_b(V).

This contraction includes the change of the local vector basis implicitly and is invariant to a simultaneous rotation of the derivative stencil and gauge frame, apart from interpolation/discretisation errors.

level

nside

kernel_sz = 3

sigma_pix

n_gauges = 1

gauge_type = ''

gauge_reduce = 'mean'

radius_m

ellipsoid = ''

dtype = Ellipsis

partial

n_pixels

pixel_spacing_rad

pixel_spacing_m

conv

property device: torch.device

property cell_ids: numpy.ndarray

property derivative_kernels: tuple[torch.Tensor, torch.Tensor]

Fixed physical derivative kernels along the two gauge axes.

forward(velocity: ArrayLike) → ArrayLike

Return divergence/curl for eastward/northward velocity channels.

compute(velocity: ArrayLike) → ArrayLike

Alias for forward().

extra_repr() → str

Return the extra representation of the module.

To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.

class healpix_analyse.divcurl.HealPixMultiScaleDivCurl(decomp: healpix_analyse.decomp.HealPixDecomp, *, kernel_sz: int = 3, sigma_pix: float | None = None, n_gauges: int = 1, gauge_type: str = 'phi', gauge_reduce: str = 'mean', radius_m: float = 6371008.8, singularity_lonlat=None, ref_direction=None, ellipsoid: str | None = None, dtype: torch.dtype | None = None, device: str | torch.device | None = None, cache_dir=_DEFAULT_CACHE_DIR)

Bases: torch.nn.Module

Apply HealPixDivCurl to every band of a decomposition.

The native pixel spacing doubles approximately at every Down operation. Each derivative kernel is divided by its own physical spacing, making the returned values comparable and expressed in the same physical units.

levels

cell_ids_per_scale

n_bands

gauge_reduce = 'mean'

layers

pixel_spacing_m

forward(pyramid: healpix_analyse.decomp.HealPixPyramid | Sequence[ArrayLike]) → HealPixDivCurlPyramid

Return one divergence/curl map for every native-resolution band.

compute(pyramid: healpix_analyse.decomp.HealPixPyramid | Sequence[ArrayLike]) → HealPixDivCurlPyramid

Alias for forward().

extra_repr() → str

Return the extra representation of the module.

To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.