basis
=====

.. py:module:: basis


Functions
---------

.. autoapisummary::

   basis.basis
   basis.A1
   basis.A2_inv
   basis.ptilde
   basis.Alm
   basis.Blmjk
   basis.Cpqk
   basis.Ylm
   basis.p_Y
   basis.gtilde
   basis.p_G
   basis.poly_basis
   basis.utilde
   basis.u_p
   basis.U


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

.. py:function:: basis(lmax)

   Full change of basis matrix from spherical harmonics to Green's basis

   :param lmax: maximum degree of the spherical harmonic basis
   :type lmax: int


.. py:function:: A1(lmax)

   Change of basis matrix from spherical harmonics to polynomial basis.

   :param lmax: Maximum degree of the spherical harmonic basis.
   :type lmax: int

   :returns: Description of the return value.
   :rtype: TODO


.. py:function:: A2_inv(lmax)

   Change of basis matrix from polynomial basis to Green's basis.

   :param lmax: Maximum degree of the spherical harmonic basis.
   :type lmax: int

   :returns: Description of the return value.
   :rtype: TODO


.. py:function:: ptilde(n)

   Compute the x, y, and z powers of the n-th polynomial basis term.

   If the n-th term is x^i y^j z^k, return (i, j, k).

   :param n: Index of the polynomial basis term.
   :type n: int

   :returns: (i, j, k)
   :rtype: tuple

   .. rubric:: Example

   >>> ptilde(2) # z
   (0, 0, 1)

   >>> ptilde(3) # x + y
   (1, 1, 0)


.. py:function:: Alm(l, m)

.. py:function:: Blmjk(l, m, j, k)

.. py:function:: Cpqk(p, q, k)

.. py:function:: Ylm(l, m)

   Compute the coefficients of the spherical harmonic Y_{l,m}.

   :param l: Degree of the spherical harmonic.
   :type l: int
   :param m: Order of the spherical harmonic in the range [-l, l].
   :type m: int

   :returns: {(i, j, k): coeff} where i, j, k are the powers of x, y, z (see `ptilde`).
   :rtype: dict

   .. rubric:: Example

   >>> Ylm(2, 0)
   {(0, 0, 0): 0.6307831305050402,
       (2, 0, 0): -0.9461746957575603,
       (0, 2, 0): -0.9461746957575603}


.. py:function:: p_Y(p, l, m, n)

   Return a representation of Y_{l, m} in the polynomial basis.

   :param p: Powers of xyz as returned by `ptilde`.
   :type p: dict
   :param l: Degree of the spherical harmonic.
   :type l: int
   :param m: Order of the spherical harmonic in the range [-l, l].
   :type m: int
   :param n: Dummy variable.
   :type n: None

   :returns:

             (indices, data) where indices is an np.array of indices of the polynomial
                 basis terms and data is an np.array of the coefficients of the polynomial
                 basis terms.
   :rtype: tuple

   .. rubric:: Example

   >>> p = {ptilde(m): m for m in range(9)}
   >>> p_Y(p, 2, 0, 0)
   (array([0, 4, 8]), array([ 0.63078313, -0.9461747 , -0.9461747 ]))
   # see correspondence with `Ylm` example


.. py:function:: gtilde(n)

   Compute the n-th term of the Green basis in the polynomial basis.

   :param n: Index of the Green basis term.
   :type n: int

   :returns: {(i, j, k): coeff} where i, j, k are the powers of x, y, z (see `ptilde`).
   :rtype: dict

   .. rubric:: Example

   >>> gtilde(50)
   {(4, 0, 1): 5, (4, 2, 1): -5, (6, 0, 1): -8}


.. py:function:: p_G(p, l, m, n)

   Return a representation of Green's basis n-th term in the polynomial basis.

   :param p: Powers of xyz as returned by `ptilde`.
   :type p: dict
   :param l: Dummy variable.
   :type l: None
   :param m: Dummy variable.
   :type m: None
   :param n: Index of the Green basis term.
   :type n: int

   :returns:

             (indices, data) where indices is an np.array of indices of the polynomial
                 basis terms and data is an np.array of the coefficients of the polynomial
                 basis terms.
   :rtype: tuple

   .. rubric:: Example

   >>> p = {ptilde(n): n for n in range(100)}
   >>> p_G(p, None, None, 50)
   (array([26, 50, 54]), array([ 5., -8., -5.]))


.. py:function:: poly_basis(deg)

.. py:function:: utilde(n)

.. py:function:: u_p(p, l, m, n)

.. py:function:: U(udeg: int)

   Change of basis matrix from limb darkening basis to polynomial basis.

   :param udeg: Degree of the limb darkening basis.
   :type udeg: int

   :returns: TODO