skyscapes.scene.system
======================

.. py:module:: skyscapes.scene.system

.. autoapi-nested-parse::

   scene.System -- the top-level PyTree container.

   Holds a star, a heterogeneous tuple of planets, an optional disk, and the
   Kepler-solver callable (static so JIT doesn't re-trace). The tuple makes
   the system variadic: a 1-planet system and an 8-planet system have
   compatible shapes as long as per-planet arrays broadcast correctly.



Classes
-------

.. autoapisummary::

   skyscapes.scene.system.System


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

.. py:class:: System

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


   Astrophysical scene: star + tuple of planets + optional disk.

   Attributes:
       star: Host star (``AbstractStar``).
       planets: Variable-length tuple of ``Planet``.
       trig_solver: Scalar Kepler-trig solver (static; see
           ``orbix.kepler.shortcuts.grid.get_grid_solver``). Required --
           callers must provide a built solver, not None.
       disk: Optional extended-source disk (``AbstractDisk | None``).
       midplane_inc_deg: System midplane inclination [deg] in the
           barycentric -> sky frame. Default 0.0 means "midplane = sky"
           and is intentionally indistinguishable from a real face-on
           system at this inclination; this ambiguity is acceptable
           because the field is diagnostic-only after load (no runtime
           hot path consults it). Populated by ``io.from_exovista``
           from the FITS star header. After load, frame rotation has
           already been baked into each ``Planet``'s orbital elements.
       midplane_pa_deg: System midplane position angle [deg]. Same
           semantics as ``midplane_inc_deg``.


   .. py:attribute:: star
      :type:  skyscapes.scene.star.AbstractStar


   .. py:attribute:: planets
      :type:  tuple[skyscapes.scene.planet.Planet, Ellipsis]


   .. py:attribute:: trig_solver
      :type:  collections.abc.Callable


   .. py:attribute:: disk
      :type:  skyscapes.disk.AbstractDisk | None
      :value: None



   .. py:attribute:: midplane_inc_deg
      :type:  float
      :value: 0.0



   .. py:attribute:: midplane_pa_deg
      :type:  float
      :value: 0.0



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


      Total number of planets across all composed ``Planet`` modules.



   .. py:method:: positions(t_jd)

      Concatenated on-sky positions, shape ``(2, K_total, T)``.



   .. py:method:: contrasts(wavelength_nm, t_jd)

      Per-planet contrast, shape ``(K_total, T)``.



   .. py:method:: planet_flux_densities(wavelength_nm, t_jd)

      Per-planet flux density [ph/s/m^2/nm], shape ``(K_total, T)``.



   .. py:method:: alpha_dMag(t_jd)

      Per-planet projected separation + dMag, each shape ``(K_total, T)``.



   .. py:method:: __repr__()

      Tree-shaped summary: star + planets + disk + midplane geometry.