jaxoplanet.starry.surface
=========================

.. py:module:: jaxoplanet.starry.surface


Classes
-------

.. autoapisummary::

   jaxoplanet.starry.surface.Surface


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

.. py:class:: Surface(*, y: jaxoplanet.starry.ylm.Ylm | None = None, inc: jaxoplanet.types.Scalar | None = 0.5 * jnp.pi, obl: jaxoplanet.types.Scalar | None = None, u: collections.abc.Iterable[jaxoplanet.types.Array] = (), period: jaxoplanet.types.Scalar | None = None, amplitude: jaxoplanet.types.Array = 1.0, normalize: bool = True, phase: jaxoplanet.types.Array = 0.0, radius: jaxoplanet.types.Array = 1.0, shear: jaxoplanet.types.Array = None)

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


   Surface map object.

   :param y: spherical harmonic expansion of the map. Defaults to a uniform map with
             amplitude 1.0.
   :type y: Optional(:py:class:`~jaxoplanet.starry.ylm.Ylm`)
   :param inc: inclination of the map relative to line of sight.
               Defaults to pi/2 [angular unit].
   :type inc: Optional[Scalar]
   :param obl: obliquity of the map [angular unit]. Defaults to None.
   :type obl: Optional[Scalar]
   :param u: polynomial limb-darkening coefficients of the map.
   :type u: Optional[Array]
   :param period: rotation period of the map [time unit]. Defaults to
                  None.
   :type period: Optional[Scalar]
   :param amplitude: amplitude of the map; this Scalar is proportional
                     to the luminosity of the map and multiplies all flux-related observables.
                     Defaults to 1.0.
   :type amplitude: Optional[float]
   :param normalize: whether to normalize the coefficients of the
                     spherical harmonics. If True, Ylm is normalized and the amplitude of the map
                     is set to y[(0, 0)]. Defaults to True.
   :type normalize: Optional(bool)
   :param phase: initial phase of the map rotation around the polar
                 axis. Defaults to 0.0.
   :type phase: Optional[float]

   .. rubric:: Example

   .. code-block:: python

       import numpy as np
       import jax
       from jaxoplanet.starry.visualization import show_surface
       from jaxoplanet.starry.surface import Surface
       from jaxoplanet.starry.ylm import Ylm

       jax.config.update("jax_enable_x64", True)

       np.random.seed(30)
       y = Ylm.from_dense(np.random.rand(20))
       m = Surface(y=y, u=[0.5, 0.1], inc=0.9, obl=-0.3)
       show_surface(m)


   .. py:attribute:: y
      :type:  jaxoplanet.starry.ylm.Ylm

      :py:class:`~starry.ylm.Ylm` object representing the spherical harmonic expansion
      of the map


   .. py:attribute:: u
      :type:  tuple[jaxoplanet.types.Array, Ellipsis]

      Tuple of limb darkening coefficients.


   .. py:attribute:: period
      :type:  jaxoplanet.types.Array | None

      Rotation period of the map in days (attribute subject to change). None if not
      rotating.


   .. py:attribute:: amplitude
      :type:  jaxoplanet.types.Array

      Amplitude of the map, a Scalar proportional to map luminosity.


   .. py:attribute:: normalize
      :type:  bool

      Boolean to specify whether the Ylm coefficients should be normalized


   .. py:attribute:: phase
      :type:  jaxoplanet.types.Array

      Initial phase of the map rotation around polar axis


   .. py:attribute:: radius
      :type:  jaxoplanet.types.Array

      Radius of the map in solar radii


   .. py:attribute:: shear
      :type:  jaxoplanet.types.Array

      Differential rotation shear of the map


   .. py:property:: inc


   .. py:property:: obl


   .. py:property:: veq

      Equatorial velocity of the map in Rsun/day.


   .. py:property:: udeg
      :type: int


      Order of the polynomial limb darkening.


   .. py:property:: ydeg
      :type: int



   .. py:property:: vdeg
      :type: int



   .. py:property:: deg

      Total degree of the spherical harmonic expansion (``udeg + ydeg``).


   .. py:method:: render(theta: float | None = None, res: int = 400, rv: bool = False)

      Returns the intensity map projected onto the x-y plane (sky).

      :param theta: rotation angle of the map. Defaults to 0.0.
      :type theta: float, optional
      :param res: resolution of the render. Defaults to 400.
      :type res: int, optional

      :returns: square 2D array representing the intensity map
                (with nans outside the map disk).
      :rtype: ArrayLike



   .. py:method:: intensity(lat: float, lon: float)

      Returns the intensity of the map at a given latitude and longitude.

      :param lat: latitude in the rest frame of the map
      :type lat: float
      :param lon: longitude in the rest frame of the map
      :type lon: float

      :returns: intensity of the map at the given latitude and longitude
      :rtype: float



   .. py:method:: rotational_phase(time: jaxoplanet.types.Array) -> jaxoplanet.types.Array | None

      Returns the rotational phase of the map at a given time.

      :param time: time in same units as the period
      :type time: ArrayLike

      :returns: rotational phase of the map at the given time
      :rtype: ArrayLike