healpix_analyse.gradient#

Local scalar-field gradients on NESTED HEALPix grids.

The gradient is estimated in a local geographic tangent basis:

  • positive East

  • positive North

Immediate HEALPix neighbours are discovered topologically using the shared neighbourhood infrastructure. Their actual WGS84 geometry is then used to fit a two-dimensional local linear model.

No Cartesian x/y HEALPix-index directions are assumed.

Domain semantics#

cell_ids identifies all cells for which input values are available.

domain identifies the valid processing/output domain.

If domain is None, the processing domain is exactly cell_ids.

Only cells belonging to domain participate in a local fit. Cells outside domain are absent; they are not interpreted as zero, False, NaN, or any other padding value.

If the remaining finite neighbours do not provide a rank-2 local tangent fit, the gradient for that target cell is NaN.

Attributes#

GradientMethod

Functions#

gradient(→ tuple[ArrayLike, ArrayLike])

Estimate the local geographic gradient of a scalar HEALPix field.

gradient_magnitude(→ ArrayLike)

Return the magnitude of the local geographic gradient.

directional_derivative(→ ArrayLike)

Evaluate the scalar-field derivative along geographic azimuth.

Module Contents#

healpix_analyse.gradient.GradientMethod#
healpix_analyse.gradient.gradient(values: ArrayLike, cell_ids, refinement_level: int, *, domain=None, method: GradientMethod = 'least_squares') → tuple[ArrayLike, ArrayLike][source]#

Estimate the local geographic gradient of a scalar HEALPix field.

Parameters:

  • values – One-dimensional NumPy array or Torch tensor containing scalar values.

  • cell_ids – NESTED HEALPix cell IDs corresponding to values.

  • refinement_level – HEALPix refinement level.

  • domain – Optional processing/output domain.

    Every domain cell must occur in cell_ids.

    Only cells in domain participate in gradient estimation. Cells outside the domain are absent rather than treated as padding.

    Output ordering follows domain exactly. If domain is omitted, output ordering follows cell_ids.

  • method – Gradient estimation method. Currently only "least_squares" is supported.

Returns:

grad_east, grad_north – Local tangent-gradient components.

If input values have units U, outputs have units U / metre.

A cell receives NaN if fewer than two finite domain neighbours are available or if the remaining neighbour geometry does not span a two-dimensional local tangent plane.

Notes

The operator uses the immediate topological HEALPix neighbourhood (ring=1).

HEALPix index directions are not interpreted as geographic directions. East/North are derived from WGS84 centre-to-centre geodesic geometry.

healpix_analyse.gradient.gradient_magnitude(values: ArrayLike, cell_ids, refinement_level: int, *, domain=None, method: GradientMethod = 'least_squares') → ArrayLike[source]#

Return the magnitude of the local geographic gradient.

healpix_analyse.gradient.directional_derivative(values: ArrayLike, cell_ids, refinement_level: int, *, azimuth_rad, domain=None, method: GradientMethod = 'least_squares') → ArrayLike[source]#

Evaluate the scalar-field derivative along geographic azimuth.

azimuth_rad is measured clockwise from geographic North:

  • 0 -> North

  • pi / 2 -> East

  • pi -> South

  • -pi / 2 -> West

The directional derivative is derived from the local tangent gradient:

d/ds = grad_east * sin(azimuth)

  • grad_north * cos(azimuth)