sajax.planet#

planet.py — Keplerian planet orbit and pixel-level transit geometry for sajax.

This module is a standalone companion to sajax/core.py. It can be used independently to compute transit light curves, or integrated with sajax via build_combined_model / compute_combined_light_curve (defined in core.py) to correctly model active-region crossing events — i.e. cases where the planet occultes a starspot or facula during transit.

Architecture#

The module is intentionally geometry-only: it computes where the planet is on the sky at each epoch and which stellar-disc pixels it occults. The flux integration (limb darkening, active-region weighting) is handled by the existing sajax machinery in core.py. This clean separation means that the transit model inherits sajax’s full limb-darkening parametrisation automatically — no extra parameters are required.

Orbital convention (Winn 2010 / Eastman et al. 2013)#

X — sky-plane east-west (positive east) Y — sky-plane north-south (positive north, foreshortened by cos i) Z — line-of-sight toward observer (Z > 0 ⟹ planet in front of star)

All sky positions are in units of the stellar radius R*.

Minimum parameter set#

t0 : mid-transit epoch [days] period : orbital period [days] a_over_rstar : semimajor axis / R* (dimensionless)

May be derived from stellar density via stellar_density_to_a_over_rstar().

inclination : orbital inclination [rad] (90 / π/2 = perfect edge-on) ecc : orbital eccentricity [0, 1) omega_peri : argument of periastron [rad]

(ω = 0° → periapsis at ascending node;
ω = 90° → periapsis at inferior conjunction / transit centre for a circular orbit)

k : planet-to-star radius ratio Rp / R*

Limb darkening#

The same LDC law stored in the sajax model dict is applied automatically to occulted pixels — no separate transit LDC parameters are required.

Public API#

_kepler(M, ecc) — differentiable Kepler solver planet_sky_position(...) — single-epoch sky coords (X, Y, Z) compute_planet_sky_positions(...) — vectorised over an array of times _compute_planet_mask(...) — per-pixel occultation mask build_transit_model(...) — pre-compute positions for all times stellar_density_to_a_over_rstar() — unit-conversion convenience

Functions#

`planet_sky_position`(→ tuple[jax.numpy.ndarray, ...)	Compute the planet's sky-plane position (X, Y, Z) in units of R*.
`compute_planet_sky_positions`(→ jax.numpy.ndarray)	Vectorised wrapper around `planet_sky_position`.
`build_transit_model`(→ dict)	Pre-compute the planet's sky-plane position at every epoch in `times`.
`stellar_density_to_a_over_rstar`(→ float)	Convert mean stellar density and orbital period to a / R* via
`a_over_rstar_to_stellar_density`(→ float)	Inverse of `stellar_density_to_a_over_rstar`:

Module Contents#

sajax.planet.planet_sky_position(time: jax.numpy.ndarray, t0: float, period: float, a_over_rstar: float, inclination: float, ecc: float, omega_peri: float) → tuple[jax.numpy.ndarray, jax.numpy.ndarray, jax.numpy.ndarray][source]#

Compute the planet’s sky-plane position (X, Y, Z) in units of R*.

Parameters:

time (observation epoch [same units as t0 / period, e.g. days])
t0 (mid-transit epoch (inferior conjunction))
period (orbital period)
a_over_rstar (semimajor axis / R* (dimensionless, > 1 for non-grazing))
inclination (orbital inclination [rad] (π/2 = edge-on))
ecc (eccentricity [0, 1))
omega_peri (argument of periastron [rad]) – Measured from the ascending node to periapsis.

Returns:

X, Y, Z – X — east-west (positive east) Y — north-south projected (= r sin(ω+f) cos i) Z — toward observer (Z > 0 ⟹ transit; Z < 0 ⟹ occultation)

Return type:

sky-plane coordinates in units of R*

Notes

The sky-plane separation from the stellar centre is sqrt(X^2 + Y^2). A transit (or occultation) event occurs when sqrt(X^2 + Y^2) < 1 + k, where k = Rp / R*.

sajax.planet.compute_planet_sky_positions(times: jax.numpy.ndarray, t0: float, period: float, a_over_rstar: float, inclination: float, ecc: float, omega_peri: float) → jax.numpy.ndarray[source]#

Vectorised wrapper around planet_sky_position.

Parameters:: times ((ntime,) array of observation epochs)
Returns:: xyz
Return type:: (ntime, 3) array — columns are [X, Y, Z] in units of R*

sajax.planet.build_transit_model(times: numpy.ndarray, t0: float, period: float, a_over_rstar: float, inclination: float, ecc: float = 0.0, omega_peri: float = 0.0, k: float = 0.1) → dict[source]#

Pre-compute the planet’s sky-plane position at every epoch in times.

The returned dict should be stored in the sajax model dict under the key "transit". The combined model builder build_combined_model() (in core.py) does this automatically — end users typically do not need to call this function directly.

Parameters:

times ((ntime,) array of observation epochs [days]) – Must be the oversampled time array when oversampling is active (see build_combined_model).
t0 (mid-transit epoch [days])
period (orbital period [days])
a_over_rstar (semimajor axis / R* (dimensionless))
inclination (orbital inclination [rad])
ecc (eccentricity (default: 0.0 = circular))
omega_peri (argument of periastron [rad] (default: 0.0))
k (planet-to-star radius ratio Rp / R* (default: 0.1))

Returns:

dict with keys
~~~~~~~~~~~~~~
``planet_xyz`` ((ntime, 3) jnp.ndarray — planet (X, Y, Z) per epoch)
``k`` (float — planet-to-star radius ratio)

sajax.planet.stellar_density_to_a_over_rstar(rho_star_gcc: float, period_days: float) → float[source]#

Convert mean stellar density and orbital period to a / R* via Kepler’s third law (Seager & Mallén-Ornelas 2003):

a / R* = ( G ρ★ P^2 / (3π) )^(1/3)

Parameters:

rho_star_gcc (mean stellar density [g cm^-3])
period_days (orbital period [days])

Returns:

a_over_rstar

Return type:

float (dimensionless)

sajax.planet.a_over_rstar_to_stellar_density(a_over_rstar: float, period_days: float) → float[source]#

Inverse of stellar_density_to_a_over_rstar:

ρ★ = 3π / (G P^2) · (a / R*)^3

Parameters:

a_over_rstar (semimajor axis / R* (dimensionless))
period_days (orbital period [days])

Returns:

rho_star_gcc

Return type:

mean stellar density [g cm^-3]