orbix

orbix: differentiable Keplerian orbit propagation in JAX.

Submodules

• orbix.equations
• orbix.kepler
• orbix.observatory
• orbix.orbit
• orbix.viz

Classes

AbstractOrbit	Abstract orbital-motion model.
KeplerianOrbit	Seven-element Keplerian orbit.

Package Contents

class orbix.AbstractOrbit

Bases: equinox.Module

Abstract orbital-motion model.

Subclasses own whatever parameters describe “this kind of orbital motion” (Keplerian, TTV, interpolated ephemeris). Stellar context is threaded in at call time.

abstractmethod propagate(trig_solver=None, t_jd=None, *, Ms_kg)

Propagate to times t_jd.

Parameters:

• trig_solver – Scalar solver for Kepler’s equation, signature (M, e) -> (sinE, cosE). None selects the cached default grid solver.

• t_jd (jaxtyping.Array) – Times in Julian Days, shape (T,). Required; it is keyword-friendly (propagate(t_jd=..., Ms_kg=...)) so callers relying on the default solver need not pass a positional None.

• Ms_kg (jaxtyping.Array) – Stellar mass in kg, shape (K,) or scalar.

Returns:

Position vectors, shape (K, 3, T). phase_angle_rad: Phase angle beta, shape (K, T), measured

from the observer (+z) axis to the position vector. The standard planetary star-planet-observer phase angle is pi minus this; convert before any Lambert phase function.

dist_AU: Star-planet distance, shape (K, T).

Return type:

r_AU

class orbix.KeplerianOrbit

Bases: AbstractOrbit

Seven-element Keplerian orbit.

Owns the orbital elements only; everything derived (AB matrices, mean motion, period) is recomputed per call so that eqx.tree_at updates and gradients through any element are always consistent. All parameter arrays share a leading axis (K,).

a_AU: jaxtyping.Array

e: jaxtyping.Array

W_rad: jaxtyping.Array

i_rad: jaxtyping.Array

w_rad: jaxtyping.Array

M0_rad: jaxtyping.Array

t0_d: jaxtyping.Array

__check_init__()

Validate that all seven elements share one leading (K,) shape.

classmethod from_period(T_d, e, cos_i, W_rad, cos_w, sin_w, tp_d, *, Ms_kg)

Construct from the period parameterization used by orbit-fitting code.

Fitting code samples (T, e, cos i, W, cos w, sin w, tp) rather than the seven fields this class stores, so posterior draws reach the class through this constructor: period converts to semi-major axis via Kepler’s third law (which is why Ms_kg is required here, unlike __init__), and periapsis passage maps exactly to (M0_rad=0, t0_d=tp_d).

Parameters:

• T_d (jaxtyping.Array) – Orbital period in days.

• e (jaxtyping.Array) – Eccentricity.

• cos_i (jaxtyping.Array) – Cosine of the inclination (the fitting basis; the gradient of arccos diverges at |cos_i| = 1, so keep exactly face-on/edge-on samples out of gradients).

• W_rad (jaxtyping.Array) – Longitude of the ascending node in radians.

• cos_w (jaxtyping.Array) – Cosine of the argument of periapsis.

• sin_w (jaxtyping.Array) – Sine of the argument of periapsis.

• tp_d (jaxtyping.Array) – Time of periapsis passage in days (JD in practice).

• Ms_kg (jaxtyping.Array) – Stellar mass in kg.

Returns:

A KeplerianOrbit whose leading axis is the common broadcast shape of the seven inputs, so a batch of posterior draws becomes a (K,)-batched orbit in one call.

Return type:

KeplerianOrbit

_AB()

Compute the AB propagation matrices from the current elements.

Return type:

tuple[jaxtyping.Array, jaxtyping.Array]

propagate(trig_solver=None, t_jd=None, *, Ms_kg)

Propagate Keplerian orbit to times t_jd.

Returns:

(K, 3, T) position vectors. phase_angle_rad: (K, T) phase angle beta = arctan2(rho, r_z),

rho = sqrt(r_x**2 + r_y**2); gradient-safe at conjunction. Measured from the observer (+z) axis, so the standard star-planet-observer phase angle (beta = 0 at full phase) is pi minus this; convert before any Lambert phase function.

dist_AU: (K, T) star-planet distance.

Return type:

r_AU

Parameters:

• t_jd (jaxtyping.Array)

• Ms_kg (jaxtyping.Array)

position_arcsec(trig_solver=None, t_jd=None, *, Ms_kg, dist_pc)

On-sky (RA, Dec) in arcsec, each shape (K, T).

Thin wrapper around propagate for callers that only need projected position.

Parameters:

• t_jd (jaxtyping.Array)

• Ms_kg (jaxtyping.Array)

• dist_pc (jaxtyping.Array)

Return type:

tuple[jaxtyping.Array, jaxtyping.Array]

separation_arcsec(trig_solver=None, t_jd=None, *, Ms_kg, dist_pc)

Projected angular separation in arcsec, shape (K, T).

Parameters:

• t_jd (jaxtyping.Array)

• Ms_kg (jaxtyping.Array)

• dist_pc (jaxtyping.Array)

Return type:

jaxtyping.Array

__repr__()

Compact summary of the seven Keplerian elements.

Angles are converted from radians to degrees for readability. Arrays are summarized inline; if the leading axis K > 3, only the first few entries are shown.

Return type:

str