skyscapes

Astrophysical scene modeling for HWO direct imaging.

Public API:

• skyscapes.scene – star + planet + system hierarchy, plus the top-level Scene container.

• skyscapes.disk – extended-source surface brightness maps.

• skyscapes.physical_model – phase/wavelength-dependent planet-to-star contrast (reflective, emissive, future joint models).

• skyscapes.background – field-of-view background sources (zodi, …).

• skyscapes.io – data loaders (e.g. ExoVista FITS).

For convenience, Scene, System, and from_exovista are hoisted to the top level, so common flows can write from skyscapes import Scene, System, from_exovista. Mix-and-match construction goes through the submodules (skyscapes.disk.ExovistaDisk, skyscapes.physical_model.GridPhysicalModel, skyscapes.background.AYOZodi, …).

Submodules

• skyscapes._repr
• skyscapes.background
• skyscapes.datasets
• skyscapes.disk
• skyscapes.io
• skyscapes.physical_model
• skyscapes.scene

Attributes

__version__

Classes

Scene	Field-of-view container: planetary system + named background sources.
System	Astrophysical scene: star + tuple of planets + optional disk.

Functions

from_exovista(fits_file[, planet_indices, only_earths])

Load an ExoVista FITS file into a scene.System.

Package Contents

skyscapes.__version__ = 'unknown'

skyscapes.from_exovista(fits_file, planet_indices=None, only_earths=False)

Load an ExoVista FITS file into a scene.System.

The system’s midplane inclination and position angle (FITS star header keys I and PA) are applied at load time as a frame rotation of each planet’s state vector before its Keplerian elements are computed. The same angles are stored as System.midplane_inc_deg and System.midplane_pa_deg for downstream diagnostic use.

Args:

fits_file: Path to ExoVista FITS file. planet_indices: Planet indices to load (0-based). None = all. only_earths: If True and planet_indices is None, auto-filter Earths.

Returns:

scene.System with star, planets (tuple), disk, and midplane metadata.

Parameters:

• fits_file (str)

• planet_indices (collections.abc.Sequence[int] | None)

• only_earths (bool)

Return type:

skyscapes.scene.System

class skyscapes.Scene

Bases: equinox.Module

Field-of-view container: planetary system + named background sources.

Attributes:

system: The planetary system (star + planets + disk). zodi: Optional zodiacal-light background (any

skyscapes.background zodi variant).

system: skyscapes.scene.system.System

zodi: skyscapes.background.Zodi | None = None

property star

Convenience accessor for the host star.

property planets

Convenience accessor for the planet tuple.

property disk

Convenience accessor for the system’s disk (may be None).

__repr__()

Tree-shaped summary of the contained system + zodi.

Return type:

str

class skyscapes.System

Bases: 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.

star: skyscapes.scene.star.AbstractStar

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

trig_solver: collections.abc.Callable

disk: skyscapes.disk.AbstractDisk | None = None

midplane_inc_deg: float = 0.0

midplane_pa_deg: float = 0.0

property n_planets: int

Total number of planets across all composed Planet modules.

Return type:

int

positions(t_jd)

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

Parameters:

t_jd (jaxtyping.Array)

Return type:

jaxtyping.Array

contrasts(wavelength_nm, t_jd)

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

Parameters:

• wavelength_nm (jaxtyping.Array)

• t_jd (jaxtyping.Array)

Return type:

jaxtyping.Array

planet_flux_densities(wavelength_nm, t_jd)

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

Parameters:

• wavelength_nm (jaxtyping.Array)

• t_jd (jaxtyping.Array)

Return type:

jaxtyping.Array

alpha_dMag(t_jd)

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

Parameters:

t_jd (jaxtyping.Array)

Return type:

tuple[jaxtyping.Array, jaxtyping.Array]

__repr__()

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

Return type:

str