healpix_analyse.divcurl ======================= .. py:module:: healpix_analyse.divcurl .. autoapi-nested-parse:: Local, gauge-aware divergence and curl on multiscale HEALPix maps. The differential stencil is evaluated by :class:`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 ------- .. autoapisummary:: healpix_analyse.divcurl.HealPixDivCurlPyramid healpix_analyse.divcurl.HealPixDivCurl healpix_analyse.divcurl.HealPixMultiScaleDivCurl Module Contents --------------- .. py:class:: HealPixDivCurlPyramid Bases: :py:obj:`Sequence`\ [\ :py:obj:`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]``. .. py:attribute:: bands :type: tuple[ArrayLike, ...] .. py:attribute:: cell_ids :type: tuple[numpy.ndarray, ...] .. py:attribute:: levels :type: tuple[int, ...] .. py:attribute:: pixel_spacing_m :type: tuple[float, ...] .. py:attribute:: gauge_reduce :type: str .. py:property:: div :type: tuple[ArrayLike, ...] Divergence maps ordered from fine to coarse. .. py:property:: curl :type: tuple[ArrayLike, ...] Outward-normal scalar-curl maps ordered from fine to coarse. .. py:class:: HealPixDivCurl(level: int, cell_ids=None, *, kernel_sz: int = 3, sigma_pix: Optional[float] = 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: Optional[Union[str, torch.device]] = None, cache_dir=_DEFAULT_CACHE_DIR) Bases: :py:obj:`torch.nn.Module` Estimate divergence and curl at one HEALPix resolution. :Parameters: * **level** (:py:class:`int`) -- Grid4Earth/HEALPix level, with ``nside = 2**level``. * **cell_ids** (:py:class:`array-like`, *optional*) -- NESTED identifiers in the same order as the input velocity samples. ``None`` selects the full sphere. * **kernel_sz** (:py:class:`int`, *default* ``3``) -- Odd derivative-of-Gaussian stencil size. Must be at least three. * **sigma_pix** (:py:class:`float`, *optional*) -- Gaussian width in native pixels. The default is ``kernel_sz / 3``. * **n_gauges** (:py:class:`int`, *default* ``1``) -- Number of rotated HealPixConv gauges. Multiple gauges provide orientation-averaged estimates when ``gauge_reduce="mean"``. * **gauge_type** (:py:class:`str`, *default* ``"phi"``) -- Gauge convention passed directly to :class:`HealPixConv`. * **gauge_reduce** (``{"mean", "none"}``, *default* ``"mean"``) -- Average the gauge estimates or retain an explicit gauge dimension. * **radius_m** (:py:class:`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. .. admonition:: 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. .. py:attribute:: level .. py:attribute:: nside .. py:attribute:: kernel_sz :value: 3 .. py:attribute:: sigma_pix .. py:attribute:: n_gauges :value: 1 .. py:attribute:: gauge_type :value: '' .. py:attribute:: gauge_reduce :value: 'mean' .. py:attribute:: radius_m .. py:attribute:: ellipsoid :value: '' .. py:attribute:: dtype :value: Ellipsis .. py:attribute:: partial .. py:attribute:: n_pixels .. py:attribute:: pixel_spacing_rad .. py:attribute:: pixel_spacing_m .. py:attribute:: conv .. py:property:: device :type: torch.device .. py:property:: cell_ids :type: numpy.ndarray .. py:property:: derivative_kernels :type: tuple[torch.Tensor, torch.Tensor] Fixed physical derivative kernels along the two gauge axes. .. py:method:: forward(velocity: ArrayLike) -> ArrayLike Return divergence/curl for eastward/northward velocity channels. .. py:method:: compute(velocity: ArrayLike) -> ArrayLike Alias for :meth:`forward`. .. py:method:: 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. .. py:class:: HealPixMultiScaleDivCurl(decomp: healpix_analyse.decomp.HealPixDecomp, *, kernel_sz: int = 3, sigma_pix: Optional[float] = 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: Optional[str] = None, dtype: Optional[torch.dtype] = None, device: Optional[Union[str, torch.device]] = None, cache_dir=_DEFAULT_CACHE_DIR) Bases: :py:obj:`torch.nn.Module` Apply :class:`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. .. py:attribute:: levels .. py:attribute:: cell_ids_per_scale .. py:attribute:: n_bands .. py:attribute:: gauge_reduce :value: 'mean' .. py:attribute:: layers .. py:attribute:: pixel_spacing_m .. py:method:: forward(pyramid: Union[healpix_analyse.decomp.HealPixPyramid, Sequence[ArrayLike]]) -> HealPixDivCurlPyramid Return one divergence/curl map for every native-resolution band. .. py:method:: compute(pyramid: Union[healpix_analyse.decomp.HealPixPyramid, Sequence[ArrayLike]]) -> HealPixDivCurlPyramid Alias for :meth:`forward`. .. py:method:: 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.