orbix.equations

orbix.equations#

Equations of orbital mechanics.

Submodules#

Functions#

`lambert_solve`(r1, r2, tof, mu[, N, long_way, ...])	Solve the elliptic Lambert problem for one `(N, way, branch)` family.
`lambert_tof_min`(r1, r2, mu[, N, long_way, ternary_iters])	Minimum elliptic time of flight for an `N`-revolution transfer.
`AB_matrices`(a, e, i, W, w)	Compute the A and B matrices for a given set of orbital elements.
`AB_matrices_reduced`(a, sqrt_one_minus_e2, sini, cosi, ...)	Compute the A and B matrices from the trig values of the orbital elements.
`mean_anomaly_t0`(t, n, M0, t0)	Mean anomaly at time t (can be vector) from epoch.
`mean_anomaly_tp`(t, n, tp)	Mean anomaly at time t (can be vector) from periapsis passage.
`mean_motion`(a, mu)	Mean motion from semi-major axis and standard gravitational parameter.
`period_a`(a, mu)	Orbital period from semi-major axis and standard gravitational parameter.
`period_n`(n)	Orbital period from mean motion.
`period_to_sma`(T, Ms)	Semi-major axis from orbital period via Kepler's third law.
`semi_amplitude`(T, Ms, Mp, e, i)	Semi-amplitude of the radial velocity curve from base quantities.
`semi_amplitude_reduced`(T, Ms, minimum_mass, ...)	Semi-amplitude of the radial velocity curve from pre-calculated quantities.
`state_vector_to_keplerian`(r, v, mu)	Convert state vectors (r, v) to Keplerian elements using JAX.
`thiele_innes_constants`(W, i, w)	Compute the Thiele-Innes constants from the orbital angles.
`thiele_innes_constants_reduced`(sinW, cosW, sinw, cosw, ...)	Compute the Thiele-Innes constants from the orbital angles.
`lambert_phase_exact`(cosbeta, sinbeta)	Exact Lambert phase function using an arccos and sqrt call.
`lambert_phase_poly`(c)	Approximate the lambert phase function based on just the cos(beta) value.
`single_r`(A, B, e, sinE, cosE)	Calculate position vectors for a single planet over ntimes times.
`single_r_v`(A, B, e, sinE, cosE, n_orb)	Calculate position and velocity vectors for a single planet at a single time.
`system_r`(A_mat_b, B_mat_b, e_vec_b, sinE_mat, cosE_mat)	Calculate position vectors for n planets over m time steps.
`system_r_v`(A_mat_b, B_mat_b, e_vec_b, sinE_mat, ...)	Calculate position and velocity vectors for n planets over m time steps.

Package Contents#

orbix.equations.lambert_solve(r1, r2, tof, mu, N=0, long_way=False, high_branch=False, *, bisect_iters=64, ternary_iters=104, polish_steps=2)[source]#

Solve the elliptic Lambert problem for one (N, way, branch) family.

Parameters:

r1 (jaxtyping.Array) – Position at the first epoch, shape (3,).
r2 (jaxtyping.Array) – Position at the second epoch, shape (3,).
tof (jaxtyping.Array) – Time of flight between the epochs (same units as mu).
mu (jaxtyping.Array) – Gravitational parameter G * M.
N – Complete revolutions on the arc (int, traceable).
long_way – Transfer angle above pi (flips the orbit normal).
high_branch – For N >= 1, select the larger-x of the two roots. No high branch exists for N = 0 (flagged invalid).
bisect_iters (int) – Fixed bisection iterations (static).
ternary_iters (int) – Fixed ternary-search iterations for the TOF minimum used to bracket and to test existence (static).
polish_steps (int) – Differentiable Newton refinements (static); these carry the implicit-function gradients of the solution.

Returns:

Velocity at r1, shape (3,). v2: Velocity at r2, shape (3,). valid: Boolean; False when no elliptic solution exists for this

(N, long_way, high_branch) family (outputs are then meaningless and must be masked by the caller).

Return type:

orbix.equations.lambert_tof_min(r1, r2, mu, N=0, long_way=False, *, ternary_iters=104)[source]#

Minimum elliptic time of flight for an N-revolution transfer.

For N >= 1 this is the TOF at the double-root point (solutions exist iff tof >= lambert_tof_min); for N = 0 it is the near-parabolic infimum of the elliptic family. Gradients are correct at interior minima by the envelope theorem.

Parameters:

r1 (jaxtyping.Array) – Position at the first epoch, shape (3,).
r2 (jaxtyping.Array) – Position at the second epoch, shape (3,).
mu (jaxtyping.Array) – Gravitational parameter G * M.
N – Complete revolutions on the arc (int, traceable).
long_way – Transfer angle above pi.
ternary_iters (int) – Fixed ternary-search iterations (static).

Returns:

The minimum time of flight (same units as mu).

Return type:

jaxtyping.Array

orbix.equations.AB_matrices(a, e, i, W, w)[source]#

Compute the A and B matrices for a given set of orbital elements.

In keplertools Dmitry defines these as: “inertial frame components of perifocal frame unit vectors scaled by orbit semi-major and semi-minor axes.” and I wouldn’t dare disagree with him on this.

Parameters:

a – Array Semi-major axis
e – Array Eccentricity
i – Array Inclination
W – Array Longitude of the ascending node
w – Array Argument of periapsis

Returns:

jnp.ndarray: A matrix
B: jnp.ndarray: B matrix

Return type:

orbix.equations.AB_matrices_reduced(a, sqrt_one_minus_e2, sini, cosi, sinW, cosW, sinw, cosw)[source]#

Compute the A and B matrices from the trig values of the orbital elements.

Parameters:

a – Semi-major axis
sqrt_one_minus_e2 – Square root of (1 - eccentricity^2)
sini – Sine of the inclination
cosi – Cosine of the inclination
sinW – Sine of the longitude of the ascending node
cosW – Cosine of the longitude of the ascending node
sinw – Sine of the argument of periapsis
cosw – Cosine of the argument of periapsis

Returns:

jnp.ndarray: A matrix
B: jnp.ndarray: B matrix

Return type:

orbix.equations.mean_anomaly_t0(t, n, M0, t0)[source]#

Mean anomaly at time t (can be vector) from epoch.

Requires that all units are consistent and does NOT clip the mean anomaly to the range [0, 2pi).

Parameters:

t – Array Time
n – Array Mean motion
M0 – Array Mean anomaly at epoch
t0 – Array Epoch

Returns:

Array: Mean anomaly at time t

Return type:

orbix.equations.mean_anomaly_tp(t, n, tp)[source]#

Mean anomaly at time t (can be vector) from periapsis passage.

Parameters:

t – Array Time
n – Array Mean motion
tp – Array Time of periapsis passage

Returns:

Array: Mean anomaly at time t

Return type:

orbix.equations.mean_motion(a, mu)[source]#

Mean motion from semi-major axis and standard gravitational parameter.

Parameters:

a – Array Semi-major axis
mu – Array Standard gravitational parameter

Returns:

Array: Mean motion

Return type:

orbix.equations.period_a(a, mu)[source]#

Orbital period from semi-major axis and standard gravitational parameter.

Parameters:

a – Array Semi-major axis
mu – Array Standard gravitational parameter

Returns:

Array: Orbital period

Return type:

orbix.equations.period_n(n)[source]#

Orbital period from mean motion.

Parameters:

n – Array Mean motion

Returns:

Array: Orbital period

Return type:

orbix.equations.period_to_sma(T, Ms)[source]#

Semi-major axis from orbital period via Kepler’s third law.

Parameters:

T – Orbital period (days). Scalar or array.
Ms – Stellar mass (kg). Scalar or array.

Returns:

Semi-major axis (AU). Scalar or array.

Return type:

orbix.equations.semi_amplitude(T, Ms, Mp, e, i)[source]#

Semi-amplitude of the radial velocity curve from base quantities.

Parameters:

T – Array Orbital period
Ms – Array Mass of the star
Mp – Array Mass of the planet
e – Array Eccentricity
i – Array Inclination

Returns:

Array: Semi-amplitude of the radial velocity curve

Return type:

orbix.equations.semi_amplitude_reduced(T, Ms, minimum_mass, sqrt_one_minus_e2)[source]#

Semi-amplitude of the radial velocity curve from pre-calculated quantities.

Parameters:

T – Array Orbital period
Ms – Array Mass of the star
minimum_mass – Array Mass of the planet multiplied by sin(i)
sqrt_one_minus_e2 – Array Square root of (1 - eccentricity^2)

Returns:

Array: Semi-amplitude of the radial velocity curve

Return type:

orbix.equations.state_vector_to_keplerian(r, v, mu)[source]#

Convert state vectors (r, v) to Keplerian elements using JAX.

Robust implementation handling edge cases (circular, equatorial, and non-bound orbits) using jnp.where for JIT compatibility.

Unit-agnostic: r, v, and mu must be expressed in one consistent unit system (e.g. meters / m/s / m^3 s^-2, or the AU / day units used elsewhere in this library); the function does not enforce or convert any particular convention, and a is returned in the same length unit as r.

Parameters:

r – Stellar-centric position vector (3,).
v – Stellar-centric velocity vector (3,).
mu – Gravitational parameter G * M_total.

Returns:

(a, e, i, W, w, M) – semi-major axis (same length: unit as r), eccentricity, inclination [rad], longitude of ascending node [rad], argument of periapsis [rad], mean anomaly [rad].

Return type:

tuple

orbix.equations.thiele_innes_constants(W, i, w)[source]#

Compute the Thiele-Innes constants from the orbital angles.

Parameters:

W – Longitude of the ascending node
i – Inclination
w – Argument of periapsis

Returns:

A constant B: B constant F: F constant G: G constant

Return type:

orbix.equations.thiele_innes_constants_reduced(sinW, cosW, sinw, cosw, sinwcosi, coswcosi)[source]#

Compute the Thiele-Innes constants from the orbital angles.

Parameters:

sinW – Sine of the longitude of the ascending node
cosW – Cosine of the longitude of the ascending node
sinw – Sine of the argument of periapsis
cosw – Cosine of the argument of periapsis
sinwcosi – Sine of the argument of periapsis times cosine of the inclination
coswcosi – Cosine of the argument of periapsis times cosine of the inclination

Returns:

A constant B: B constant F: F constant G: G constant

Return type:

orbix.equations.lambert_phase_exact(cosbeta, sinbeta)[source]#

Exact Lambert phase function using an arccos and sqrt call.

Parameters:

cosbeta – The cosine of the phase angle.
sinbeta – The sine of the phase angle.

Returns:

The Lambert phase function value, clipped to be non-negative.

orbix.equations.lambert_phase_poly(c)[source]#: Approximate the lambert phase function based on just the cos(beta) value.

orbix.equations.single_r(A, B, e, sinE, cosE)[source]#

Calculate position vectors for a single planet over ntimes times.

Parameters:

A (jax.Array) – A matrix. Shape (3,).
B (jax.Array) – B matrix. Shape (3,).
e (float) – eccentricity (scalar).
sinE (jax.Array) – sine of the eccentric anomaly. Shape (ntimes,).
cosE (jax.Array) – cosine of the eccentric anomaly. Shape (ntimes,).

Returns:

position vectors. Shape (3, ntimes).

Return type:

r (jax.Array)

orbix.equations.single_r_v(A, B, e, sinE, cosE, n_orb)[source]#

Calculate position and velocity vectors for a single planet at a single time.

Parameters:

A (jax.Array) – A matrix (3)
B (jax.Array) – B matrix (3)
e (float) – eccentricity ()
sinE (float) – sine of the eccentric anomaly (ntimes)
cosE (float) – cosine of the eccentric anomaly (ntimes)
n_orb (float) – mean orbital motion (ntimes)

Returns:

position vector (3, 1) v (jax.Array): velocity vector (3, 1)

Return type:

r (jax.Array)

orbix.equations.system_r(A_mat_b, B_mat_b, e_vec_b, sinE_mat, cosE_mat)[source]#

Calculate position vectors for n planets over m time steps.

Propagation is computed as: r = A * (cosE - e) + B * sinE where A, B, e, n_orb are pre-broadcasted outside the function. The sinE and cosE are managed inside the function for vectorization reasons.

Some effort has been made to ensure there isn’t division by zero.

Parameters:

A_mat_b (jax.Array) – Pre-broadcasted A vectors. Shape (3, n, 1).
B_mat_b (jax.Array) – Pre-broadcasted B vectors. Shape (3, n, 1).
e_vec_b (jax.Array) – Pre-broadcasted eccentricity. Shape (n, 1).
sinE_mat (jax.Array) – Sine(Eccentric Anomaly). Shape (n, m).
cosE_mat (jax.Array) – Cosine(Eccentric Anomaly). Shape (n, m).

Returns:

Position vectors. Shape (3, n, m).

Return type:

r (jax.Array)

orbix.equations.system_r_v(A_mat_b, B_mat_b, e_vec_b, sinE_mat, cosE_mat, n_orb_vec_b)[source]#

Calculate position and velocity vectors for n planets over m time steps.

Propagation is computed as: r = A * (cosE - e) + B * sinE v = n_orb / (1 - e * cosE) * (-A * sinE + B * cosE) where A, B, e, n_orb are pre-broadcasted outside the function. The sinE and cosE are managed inside the function for vectorization reasons.

Some effort has been made to ensure there isn’t division by zero.

Parameters:

A_mat_b (jax.Array) – Pre-broadcasted A vectors. Shape (3, n, 1).
B_mat_b (jax.Array) – Pre-broadcasted B vectors. Shape (3, n, 1).
e_vec_b (jax.Array) – Pre-broadcasted eccentricity. Shape (n, 1).
sinE_mat (jax.Array) – Sine(Eccentric Anomaly). Shape (n, m).
cosE_mat (jax.Array) – Cosine(Eccentric Anomaly). Shape (n, m).
n_orb_vec_b (jax.Array) – Pre-broadcasted mean orbital motion. Shape (n, 1).

Returns:

A tuple containing:

r (jax.Array): Position vectors. Shape (3, n, m).
v (jax.Array): Velocity vectors. Shape (3, n, m).

Return type:

tuple[jax.Array, jax.Array]