jaxoplanet.starry.ylm
=====================

.. py:module:: jaxoplanet.starry.ylm

.. autoapi-nested-parse::

   A module to manipulate vectors in the spherical harmonic basis.

   The spherical harmonics basis is a set of orthogonal functions defined on the
   unit sphere. In jaxoplanet, this basis is used to represent the intensity at the surface
   of a spherical body, such as a star or a planet. We say that :math:`y` represents the
   intensity of a surface in the spherical harmonics basis if the specific intensity at the
   :math:`(x,y)` on the surface can be written as:

   .. math::

       I(x, y) = \mathbf{\tilde{y}_n^\mathsf{T}} (x, y) \, \mathbf{y}
       \quad,

   where :math:`\tilde{y}_n` is the **spherical harmonic basis**,
   arranged in increasing degree and order:

   .. math::

       \mathbf{\tilde{y}_n} =
       \begin{pmatrix}
           Y_{0, 0} &
           Y_{1, -1} & Y_{1, 0} & Y_{1, 1} &
           Y_{2, -2} & Y_{2, -1} & Y_{2, 0} & Y_{2, 1} & Y_{2, 2} &
           \cdot\cdot\cdot
       \end{pmatrix}^\mathsf{T}
       \quad,

   where :math:`Y_{l, m} = Y_{l, m}(x, y)` is the spherical harmonic of degree :math:`l`
   and order :math:`m`. For reference, in this basis the coefficient of the spherical
   harmonic :math:`Y_{l, m}` is located at the index

   .. math::

       n = l^2 + l + m



Classes
-------

.. autoapisummary::

   jaxoplanet.starry.ylm.Ylm


Functions
---------

.. autoapisummary::

   jaxoplanet.starry.ylm.Bp
   jaxoplanet.starry.ylm.spot_profile
   jaxoplanet.starry.ylm.ylm_spot
   jaxoplanet.starry.ylm.ring_y


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

.. py:class:: Ylm(data: collections.abc.Mapping[tuple[int, int], jaxoplanet.types.Array] | None = None)

   Bases: :py:obj:`equinox.Module`


   Ylm object containing the spherical harmonic coefficients.

   :param data: dictionary of
                spherical harmonic coefficients. Defaults to {(0, 0): 1.0}.
   :type data: Mapping[tuple[int, int], Array], optional


   .. py:attribute:: data
      :type:  dict[tuple[int, int], jaxoplanet.types.Array]

      coefficients of the spherical harmonic expansion of the map in the form
      `{(l, m): coefficient}`


   .. py:attribute:: deg
      :type:  int

      The maximum degree of the spherical harmonic coefficients.


   .. py:attribute:: diagonal
      :type:  bool

      Whether are orders m of the spherical harmonic coefficients are zero.
      Diagonal if only the degrees "l" are non-zero.


   .. py:property:: shape
      :type: tuple[int, Ellipsis]


      The number of coefficients in the basis. This sets the shape of
      the output of `todense`.


   .. py:property:: indices
      :type: list[tuple[int, int]]


      List of (l,m) indices of the spherical harmonic coefficients.


   .. py:method:: index(l: jaxoplanet.types.Array, m: jaxoplanet.types.Array) -> jaxoplanet.types.Array
      :staticmethod:


      Convert the degree and order of the spherical harmonic to the
      corresponding index in the coefficient array.



   .. py:method:: normalize() -> Ylm

      Return a new Ylm instance with coefficients normalized to :math:`Y_{0,0}`.

      :returns: Ylm instance with normalized coefficients.

      :raises ValueError: if the (0, 0) coefficient is zero.



   .. py:method:: tosparse() -> jax.experimental.sparse.BCOO

      Return a sparse (jax.experimental.sparse.BCOO) spherical harmonic
      coefficients vector where the spherical harmonic :math:`Y_{l, m}` is located at
      the index :math:`n = l^2 + l + m`.



   .. py:method:: todense() -> jaxoplanet.types.Array

      Return a dense spherical harmonic coefficients vector where the spherical
      harmonic :math:`Y_{l, m}` is located at the index :math:`n = l^2 + l + m`.



   .. py:method:: from_dense(y: jaxoplanet.types.Array, normalize: bool = True) -> Ylm
      :classmethod:


      Create a Ylm object from a dense array of spherical harmonic coefficients
      where the spherical harmonic :math:`Y_{l, m}` is located at the index
      :math:`n = l^2 + l + m`.



   .. py:method:: __mul__(other: Any) -> Ylm


   .. py:method:: __rmul__(other: Any) -> Ylm


   .. py:method:: __getitem__(key) -> jaxoplanet.types.Array


   .. py:method:: from_limb_darkening(u: jaxoplanet.types.Array) -> Ylm
      :classmethod:


      Spherical harmonics coefficients from limb darkening coefficients.



.. py:function:: Bp(ydeg, npts: int = 1000, eps: float = 1e-09, smoothing=None)

   Return the matrix B+. This expands the
   spot profile `b` in Legendre polynomials. From https://github.com/rodluger/
   mapping_stellar_surfaces/blob/paper2-arxiv/paper2/figures/spot_profile.py and
   _spot_setup in starry/_core/core.py.


.. py:function:: spot_profile(theta, radius, spot_fac=300)

   The sigmoid spot profile.



.. py:function:: ylm_spot(ydeg: int, npts=300, spot_fac=300) -> callable

   spot expansion in the spherical harmonics basis.

   :param ydeg: max degree of the spherical harmonics
   :type ydeg: int

   :returns: function that returns the spherical harmonics coefficients of the spot
   :rtype: callable


.. py:function:: ring_y(l_max, pts=1000, eps=1e-09, smoothing=None)