healpix_analyse.alm
===================

.. py:module:: healpix_analyse.alm


Attributes
----------

.. autoapisummary::

   healpix_analyse.alm.ArrayLike


Classes
-------

.. autoapisummary::

   healpix_analyse.alm.AlmCoeffs
   healpix_analyse.alm.AlmTransform


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

.. py:data:: ArrayLike

.. py:class:: AlmCoeffs

   Container for local complex spherical harmonic coefficients.

   :Parameters: * **alm** (:py:class:`torch.Tensor`) -- Complex coefficient tensor with shape [K] or [B, K].
                * **l** (:py:class:`torch.Tensor`) -- Degree indices with shape [K].
                * **m** (:py:class:`torch.Tensor`) -- Order indices with shape [K]. Only m >= 0 is stored in V1.
                * **meta** (:py:class:`dict`) -- Metadata associated with the transform.


   .. py:attribute:: alm
      :type:  torch.Tensor


   .. py:attribute:: l
      :type:  torch.Tensor


   .. py:attribute:: m
      :type:  torch.Tensor


   .. py:attribute:: meta
      :type:  Dict[str, Any]


   .. py:property:: n_modes
      :type: int



   .. py:property:: is_batched
      :type: bool



   .. py:method:: clone() -> AlmCoeffs


   .. py:method:: to(device: Optional[Union[str, torch.device]] = None, dtype: Optional[torch.dtype] = None) -> AlmCoeffs


   .. py:method:: cpu() -> AlmCoeffs


   .. py:method:: cuda() -> AlmCoeffs


.. py:class:: AlmTransform(cell_ids: ArrayLike, level: int, indexing_scheme: str = '2D_array', ellipsoid: str = 'sphere', method: str = 'fft', dtype: torch.dtype = torch.float32, device: Optional[Union[str, torch.device]] = None, debug: bool = False, lon: numpy.ndarray = None, lat: numpy.ndarray = None, weights: numpy.array = None)

   Local FFT-oriented spherical harmonic transform on a HEALPix patch.

   This implementation follows a two-stage local solver:

   1. local Fourier analysis on each observed iso-latitude ring,
   2. local Legendre analysis over the observed ring colatitudes.

   The design avoids explicit dense Y_lm evaluation over all pixels. It is
   intended as a practical starting point for large local patches and keeps
   only m >= 0 coefficients.

   :Parameters: * **level** (:py:class:`int`) -- HEALPix level such that nside = 2**level.
                * **cell_ids** (:py:class:`array-like`) -- HEALPix cell identifiers at the given level.
                * **indexing_scheme** (:py:class:`str`, *default* ``"ring"``) -- The indexing scheme for the cell IDs.
                * **ellipsoid** (``{"sphere", "WGS84"}``, *default* ``"sphere"``) -- Geometry model.
                * **method** (``{"fft", "alm"}``, *default* ``"fft"``, :py:class:`Alm approximation`, :py:class:`alm option under development.`) -- Analysis mode used in the Legendre stage.
                * **dtype** (:py:class:`torch.dtype`, *default* :py:class:`torch.float32`) -- Real dtype for maps and geometry.
                * **device** (:py:class:`str` or :py:class:`torch.device`, *optional*) -- Execution device. If None, uses CUDA when available, else CPU.
                * **debug** (:py:class:`bool`, *default* :py:obj:`False`) -- Whether to store diagnostic timing information.

   .. admonition:: Notes

      Current assumptions:
      - all input cells are at the same HEALPix level,
      - reconstruction is only performed on the same input cells,
      - input maps are real-valued.


   .. py:attribute:: level


   .. py:attribute:: indexing_scheme
      :value: ''



   .. py:attribute:: ellipsoid
      :value: ''



   .. py:attribute:: method
      :value: ''



   .. py:attribute:: dtype
      :value: Ellipsis



   .. py:attribute:: cdtype
      :value: Ellipsis



   .. py:attribute:: device


   .. py:attribute:: debug
      :value: False



   .. py:attribute:: cell_ids


   .. py:attribute:: pixel_shift


   .. py:attribute:: phase_shift


   .. py:method:: compute_phase_shift(x0, dim=-1)

      Applique un décalage spatial x0 à un signal via sa FFT déjà calculée.

      :Parameters: * **x0** (:py:class:`float` or :py:class:`torch.Tensor`) -- Décalage à appliquer dans l'espace réel.
                     Convention: f(x - x0) <-> F(k) * exp(-i 2π k x0)
                   * **dim** (:py:class:`int`) -- Dimension correspondant à la FFT 1D.

      :returns: :py:class:`torch.Tensor` -- Facteur de phase.



   .. py:method:: fft(data_: ArrayLike, pbc: bool = True) -> ArrayLike


   .. py:method:: ifft(data: ArrayLike) -> ArrayLike
      :abstractmethod:


      Reconstruct a map on the same local HEALPix cells.

      Not implemented yet. The inverse needs the Legendre-projection stage
      that :meth:`fft` does not currently compute (see the ``TODO`` next to
      its second FFT stage), and relies on ring bookkeeping
      (``self.n_rings``, ``self.idx_ring``, ``self.weights``, ``self.xa``,
      ``self.N_k``) that ``__init__`` does not currently set. Rather
      than fail on a missing attribute or silently return a wrong map, this
      raises explicitly until that work lands.