skyscapes.scene.planet
======================

.. py:module:: skyscapes.scene.planet

.. autoapi-nested-parse::

   scene.Planet -- composes an AbstractOrbit with an AbstractPhysicalModel.

   Planet-intrinsic parameters (radius, mass) live on ``Planet`` itself.
   Submodels receive them as method arguments when needed:

     - ``orbit`` owns orbital elements (a, e, i, ...). Those parameters
       are the orbit's parameterization, not the planet's identity.
     - ``physical_model`` owns spectral physics (albedo, contrast grid,
       ExoJax composition). Planet radius is passed to
       ``physical_model.contrast(..., Rp_Rearth=self.Rp_Rearth)`` rather
       than duplicated as a field.

   Stellar context (``Ms_kg``, ``dist_pc``) is supplied keyword-only at
   call time through a ``Star`` argument -- ``Planet`` never stores a
   reference to its host star, which keeps the PyTree shallow and lets a
   single ``scene.System`` own the one-and-only star.



Classes
-------

.. autoapisummary::

   skyscapes.scene.planet.Planet


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

.. py:class:: Planet

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


   Composed planet: intrinsic params + orbit dynamics + physical-model physics.

   All stellar-context-dependent methods take a ``star`` keyword argument
   rather than holding a reference internally.  This keeps ``System`` as
   the single source of truth for the host star.

   Attributes:
       Rp_Rearth: Planet radius [Earth radii], shape ``(K,)``.
       Mp_Mearth: Planet mass [Earth masses], shape ``(K,)``.
       orbit: Orbital dynamics (trajectory parameterization).
       physical_model: Spectral physics (reflectivity / emission).


   .. py:attribute:: Rp_Rearth
      :type:  jaxtyping.Array


   .. py:attribute:: Mp_Mearth
      :type:  jaxtyping.Array


   .. py:attribute:: orbit
      :type:  orbix.system.orbit.AbstractOrbit


   .. py:attribute:: physical_model
      :type:  skyscapes.physical_model.AbstractPhysicalModel


   .. py:property:: n_planets
      :type: int


      Number of planets ``K`` carried by this composed module.



   .. py:method:: mean_anomaly(t_jd, *, star)

      Mean anomaly mod 360 [deg], shape ``(K, T)``.

      ``t_jd`` must be shape ``(T,)`` -- no rank polymorphism. Callers
      that hold a scalar should wrap it in ``jnp.asarray([t])`` at the
      call site.



   .. py:method:: propagate(trig_solver, t_jd, *, star)

      Delegate to ``orbit.propagate``; returns ``(r_AU, phase_rad, dist_AU)``.



   .. py:method:: position_arcsec(trig_solver, t_jd, *, star)

      On-sky position, shape ``(2, K, T)`` -- (dRA, dDec) in arcsec.



   .. py:method:: alpha_dMag(trig_solver, t_jd, *, star, wavelength_nm = 600.0)

      Projected separation [arcsec] and delta-mag, each ``(K, T)``.

      For ``LambertianPhysicalModel`` (grey), the chosen ``wavelength_nm``
      is irrelevant and the output matches ``orbix.Planets.alpha_dMag``
      by construction. For ``GridPhysicalModel`` / future wavelength-
      dependent models, ``dMag`` is evaluated at ``wavelength_nm``;
      pick a value within the model's spectral grid.



   .. py:method:: contrast(trig_solver, wavelength_nm, t_jd, *, star)

      Planet-to-star contrast at (wavelength, time), shape ``(K, T)``.



   .. py:method:: spec_flux_density(trig_solver, wavelength_nm, t_jd, *, star)

      Planet flux density [ph/s/m^2/nm], shape ``(K, T)``.



   .. py:method:: __repr__()

      Nested summary: planet count + intrinsic params + orbit + physical_model.