orbix.equations.lambert

orbix.equations.lambert#

Lambert boundary-value problem: elliptic, multi-revolution, differentiable.

Given two position vectors and the time of flight between them, solve for the terminal velocities of the connecting Keplerian orbit. This is the classical Lambert boundary-value problem (Lancaster & Blanchard 1969; Battin 1999, ch. 7; Izzo 2015), distinct from the Lambertian scattering phase function in orbix.equations.phase.

The transfer is parameterized by x = cos(alpha/2) on the open interval (-1, 1), where alpha is the Lagrange angle: the semi-major axis is a = s / (2 (1 - x^2)), both classical alpha branches collapse into the sign of x, and the time of flight T(x) is strictly decreasing for N = 0 and U-shaped (two roots per achievable TOF) for N >= 1 revolutions. Roots are bracketed by a fixed-iteration ternary search for the TOF minimum, then bisected, then polished with Newton steps that carry implicit-function-theorem gradients (the bracketing itself runs under stop_gradient).

Every solution family is indexed by three discrete choices:

  • N: number of complete revolutions on the arc.

  • long_way: transfer angle above pi (opposite orbit normal).

  • high_branch: for N >= 1, the larger-x (larger period) of the two roots; flagged invalid for N = 0.

Units are any consistent set (orbix convention: AU, days, and mu = G * Ms_kg in AU^3/day^2). All functions are scalar-core: vmap over batches of positions, times, N, or branch flags.

Degenerate geometries: transfer angles of exactly 0 or pi leave the orbit plane undefined and the returned velocities blow up there; callers sample past these measure-zero configurations.

Attributes#

_X_EPS

_DTOF_FLOOR

Functions#

_geometry(r1, r2, long_way)

Chord/semi-perimeter geometry shared by every Lambert routine.

_tof_of_x(x, s, lam, mu, N)

Elliptic Lagrange time of flight at x = cos(alpha/2).

_tof_argmin_x(s, lam, mu, N, iters)

Locate the x minimizing T(x) via fixed-iteration ternary search.

_bisect_x(tof, s, lam, mu, N, lo, hi, iters)

Bisection root of T(x) = tof on a monotone bracket [lo, hi].

_newton_polish(x, tof, s, lam, mu, N, steps)

Differentiable Newton refinement of a gradient-stopped root.

_terminal_velocities(r1, r2, x, s, lam, mu, long_way, ...)

Terminal velocities from the converged x via Lagrange f and g.

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.

Module Contents#

orbix.equations.lambert._X_EPS = 1e-09#
orbix.equations.lambert._DTOF_FLOOR = 1e-30#
orbix.equations.lambert._geometry(r1, r2, long_way)[source]#

Chord/semi-perimeter geometry shared by every Lambert routine.

Parameters:

  • r1 (jaxtyping.Array) – First position vector, shape (3,).

  • r2 (jaxtyping.Array) – Second position vector, shape (3,).

  • long_way – Whether the transfer angle exceeds pi.

Returns:

the two radii, chord length, semi-perimeter, and the signed Lambert parameter lam = +/- sqrt((s - c) / s) (negative on the long way).

Return type:

Tuple (r1n, r2n, c, s, lam)

orbix.equations.lambert._tof_of_x(x, s, lam, mu, N)[source]#

Elliptic Lagrange time of flight at x = cos(alpha/2).

alpha = 2 arccos(x) spans (0, 2 pi) as x spans (-1, 1), so both classical alpha branches are covered without a flag; beta = 2 arcsin(lam sqrt(1 - x^2)) carries the transfer-way sign through lam.

Return type:

jaxtyping.Array

orbix.equations.lambert._tof_argmin_x(s, lam, mu, N, iters)[source]#

Locate the x minimizing T(x) via fixed-iteration ternary search.

For N >= 1 the minimum is interior (the double-root point); for N = 0, where T is strictly decreasing, the search converges to the upper domain edge, whose TOF is the near-parabolic elliptic infimum. Runs on values only – callers wrap in stop_gradient.

Parameters:

iters (int)

Return type:

jaxtyping.Array

orbix.equations.lambert._bisect_x(tof, s, lam, mu, N, lo, hi, iters)[source]#

Bisection root of T(x) = tof on a monotone bracket [lo, hi].

Parameters:

iters (int)

Return type:

jaxtyping.Array

orbix.equations.lambert._newton_polish(x, tof, s, lam, mu, N, steps)[source]#

Differentiable Newton refinement of a gradient-stopped root.

Refines T(x) = tof and, because the incoming x carries no gradients, attaches the implicit-function gradients of the root to every upstream input.

Parameters:

steps (int)

Return type:

jaxtyping.Array

orbix.equations.lambert._terminal_velocities(r1, r2, x, s, lam, mu, long_way, r1n, r2n, c)[source]#

Terminal velocities from the converged x via Lagrange f and g.

Return type:

tuple

orbix.equations.lambert.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:

v1

orbix.equations.lambert.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