healpix_analyse.gradient
========================

.. py:module:: healpix_analyse.gradient

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   healpix_analyse.gradient.GradientMethod


Functions
---------

.. autoapisummary::

   healpix_analyse.gradient.gradient
   healpix_analyse.gradient.gradient_magnitude
   healpix_analyse.gradient.directional_derivative


Module Contents
---------------

.. py:data:: GradientMethod

.. py:function:: gradient(values: ArrayLike, cell_ids, refinement_level: int, *, domain=None, method: GradientMethod = 'least_squares') -> tuple[ArrayLike, ArrayLike]

   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: :py:class:`grad_east`, :py:class:`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.

   .. admonition:: 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.


.. py:function:: gradient_magnitude(values: ArrayLike, cell_ids, refinement_level: int, *, domain=None, method: GradientMethod = 'least_squares') -> ArrayLike

   Return the magnitude of the local geographic gradient.


.. py:function:: directional_derivative(values: ArrayLike, cell_ids, refinement_level: int, *, azimuth_rad, domain=None, method: GradientMethod = 'least_squares') -> ArrayLike

   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)