orbix.equations =============== .. py:module:: orbix.equations .. autoapi-nested-parse:: Equations of orbital mechanics. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/orbix/equations/lambert/index /autoapi/orbix/equations/orbit/index /autoapi/orbix/equations/phase/index /autoapi/orbix/equations/propagation/index Functions --------- .. autoapisummary:: orbix.equations.lambert_solve orbix.equations.lambert_tof_min orbix.equations.AB_matrices orbix.equations.AB_matrices_reduced orbix.equations.mean_anomaly_t0 orbix.equations.mean_anomaly_tp orbix.equations.mean_motion orbix.equations.period_a orbix.equations.period_n orbix.equations.period_to_sma orbix.equations.semi_amplitude orbix.equations.semi_amplitude_reduced orbix.equations.state_vector_to_keplerian orbix.equations.thiele_innes_constants orbix.equations.thiele_innes_constants_reduced orbix.equations.lambert_phase_exact orbix.equations.lambert_phase_poly orbix.equations.single_r orbix.equations.single_r_v orbix.equations.system_r orbix.equations.system_r_v Package Contents ---------------- .. py:function:: lambert_solve(r1, r2, tof, mu, N=0, long_way=False, high_branch=False, *, bisect_iters = 64, ternary_iters = 104, polish_steps = 2) Solve the elliptic Lambert problem for one ``(N, way, branch)`` family. :param r1: Position at the first epoch, shape ``(3,)``. :param r2: Position at the second epoch, shape ``(3,)``. :param tof: Time of flight between the epochs (same units as ``mu``). :param mu: Gravitational parameter ``G * M``. :param N: Complete revolutions on the arc (int, traceable). :param long_way: Transfer angle above pi (flips the orbit normal). :param high_branch: For ``N >= 1``, select the larger-x of the two roots. No high branch exists for ``N = 0`` (flagged invalid). :param bisect_iters: Fixed bisection iterations (static). :param ternary_iters: Fixed ternary-search iterations for the TOF minimum used to bracket and to test existence (static). :param polish_steps: 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). :rtype: v1 .. py:function:: lambert_tof_min(r1, r2, mu, N=0, long_way=False, *, ternary_iters = 104) 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. :param r1: Position at the first epoch, shape ``(3,)``. :param r2: Position at the second epoch, shape ``(3,)``. :param mu: Gravitational parameter ``G * M``. :param N: Complete revolutions on the arc (int, traceable). :param long_way: Transfer angle above pi. :param ternary_iters: Fixed ternary-search iterations (static). :returns: The minimum time of flight (same units as ``mu``). .. py:function:: AB_matrices(a, e, i, W, w) 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. :param a: Array Semi-major axis :param e: Array Eccentricity :param i: Array Inclination :param W: Array Longitude of the ascending node :param w: Array Argument of periapsis :returns: jnp.ndarray A matrix B: jnp.ndarray B matrix :rtype: A .. py:function:: AB_matrices_reduced(a, sqrt_one_minus_e2, sini, cosi, sinW, cosW, sinw, cosw) Compute the A and B matrices from the trig values of the orbital elements. :param a: Semi-major axis :param sqrt_one_minus_e2: Square root of (1 - eccentricity^2) :param sini: Sine of the inclination :param cosi: Cosine of the inclination :param sinW: Sine of the longitude of the ascending node :param cosW: Cosine of the longitude of the ascending node :param sinw: Sine of the argument of periapsis :param cosw: Cosine of the argument of periapsis :returns: jnp.ndarray A matrix B: jnp.ndarray B matrix :rtype: A .. py:function:: mean_anomaly_t0(t, n, M0, t0) 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). :param t: Array Time :param n: Array Mean motion :param M0: Array Mean anomaly at epoch :param t0: Array Epoch :returns: Array Mean anomaly at time t :rtype: M .. py:function:: mean_anomaly_tp(t, n, tp) Mean anomaly at time t (can be vector) from periapsis passage. :param t: Array Time :param n: Array Mean motion :param tp: Array Time of periapsis passage :returns: Array Mean anomaly at time t :rtype: M .. py:function:: mean_motion(a, mu) Mean motion from semi-major axis and standard gravitational parameter. :param a: Array Semi-major axis :param mu: Array Standard gravitational parameter :returns: Array Mean motion :rtype: n .. py:function:: period_a(a, mu) Orbital period from semi-major axis and standard gravitational parameter. :param a: Array Semi-major axis :param mu: Array Standard gravitational parameter :returns: Array Orbital period :rtype: T .. py:function:: period_n(n) Orbital period from mean motion. :param n: Array Mean motion :returns: Array Orbital period :rtype: T .. py:function:: period_to_sma(T, Ms) Semi-major axis from orbital period via Kepler's third law. :param T: Orbital period (days). Scalar or array. :param Ms: Stellar mass (kg). Scalar or array. :returns: Semi-major axis (AU). Scalar or array. :rtype: a .. py:function:: semi_amplitude(T, Ms, Mp, e, i) Semi-amplitude of the radial velocity curve from base quantities. :param T: Array Orbital period :param Ms: Array Mass of the star :param Mp: Array Mass of the planet :param e: Array Eccentricity :param i: Array Inclination :returns: Array Semi-amplitude of the radial velocity curve :rtype: K .. py:function:: semi_amplitude_reduced(T, Ms, minimum_mass, sqrt_one_minus_e2) Semi-amplitude of the radial velocity curve from pre-calculated quantities. :param T: Array Orbital period :param Ms: Array Mass of the star :param minimum_mass: Array Mass of the planet multiplied by sin(i) :param sqrt_one_minus_e2: Array Square root of (1 - eccentricity^2) :returns: Array Semi-amplitude of the radial velocity curve :rtype: K .. py:function:: state_vector_to_keplerian(r, v, mu) 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``. :param r: Stellar-centric position vector ``(3,)``. :param v: Stellar-centric velocity vector ``(3,)``. :param 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]. :rtype: tuple .. py:function:: thiele_innes_constants(W, i, w) Compute the Thiele-Innes constants from the orbital angles. :param W: Longitude of the ascending node :param i: Inclination :param w: Argument of periapsis :returns: A constant B: B constant F: F constant G: G constant :rtype: A .. py:function:: thiele_innes_constants_reduced(sinW, cosW, sinw, cosw, sinwcosi, coswcosi) Compute the Thiele-Innes constants from the orbital angles. :param sinW: Sine of the longitude of the ascending node :param cosW: Cosine of the longitude of the ascending node :param sinw: Sine of the argument of periapsis :param cosw: Cosine of the argument of periapsis :param sinwcosi: Sine of the argument of periapsis times cosine of the inclination :param coswcosi: Cosine of the argument of periapsis times cosine of the inclination :returns: A constant B: B constant F: F constant G: G constant :rtype: A .. py:function:: lambert_phase_exact(cosbeta, sinbeta) Exact Lambert phase function using an arccos and sqrt call. :param cosbeta: The cosine of the phase angle. :param sinbeta: The sine of the phase angle. :returns: The Lambert phase function value, clipped to be non-negative. .. py:function:: lambert_phase_poly(c) Approximate the lambert phase function based on just the cos(beta) value. .. py:function:: single_r(A, B, e, sinE, cosE) Calculate position vectors for a single planet over ntimes times. :param A: A matrix. Shape (3,). :type A: jax.Array :param B: B matrix. Shape (3,). :type B: jax.Array :param e: eccentricity (scalar). :type e: float :param sinE: sine of the eccentric anomaly. Shape (ntimes,). :type sinE: jax.Array :param cosE: cosine of the eccentric anomaly. Shape (ntimes,). :type cosE: jax.Array :returns: position vectors. Shape (3, ntimes). :rtype: r (jax.Array) .. py:function:: single_r_v(A, B, e, sinE, cosE, n_orb) Calculate position and velocity vectors for a single planet at a single time. :param A: A matrix (3) :type A: jax.Array :param B: B matrix (3) :type B: jax.Array :param e: eccentricity () :type e: float :param sinE: sine of the eccentric anomaly (ntimes) :type sinE: float :param cosE: cosine of the eccentric anomaly (ntimes) :type cosE: float :param n_orb: mean orbital motion (ntimes) :type n_orb: float :returns: position vector (3, 1) v (jax.Array): velocity vector (3, 1) :rtype: r (jax.Array) .. py:function:: 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. 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. :param A_mat_b: Pre-broadcasted A vectors. Shape (3, n, 1). :type A_mat_b: jax.Array :param B_mat_b: Pre-broadcasted B vectors. Shape (3, n, 1). :type B_mat_b: jax.Array :param e_vec_b: Pre-broadcasted eccentricity. Shape (n, 1). :type e_vec_b: jax.Array :param sinE_mat: Sine(Eccentric Anomaly). Shape (n, m). :type sinE_mat: jax.Array :param cosE_mat: Cosine(Eccentric Anomaly). Shape (n, m). :type cosE_mat: jax.Array :returns: Position vectors. Shape (3, n, m). :rtype: r (jax.Array) .. py:function:: system_r_v(A_mat_b, B_mat_b, e_vec_b, sinE_mat, cosE_mat, n_orb_vec_b) 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. :param A_mat_b: Pre-broadcasted A vectors. Shape (3, n, 1). :type A_mat_b: jax.Array :param B_mat_b: Pre-broadcasted B vectors. Shape (3, n, 1). :type B_mat_b: jax.Array :param e_vec_b: Pre-broadcasted eccentricity. Shape (n, 1). :type e_vec_b: jax.Array :param sinE_mat: Sine(Eccentric Anomaly). Shape (n, m). :type sinE_mat: jax.Array :param cosE_mat: Cosine(Eccentric Anomaly). Shape (n, m). :type cosE_mat: jax.Array :param n_orb_vec_b: Pre-broadcasted mean orbital motion. Shape (n, 1). :type n_orb_vec_b: jax.Array :returns: A tuple containing: - r (jax.Array): Position vectors. Shape (3, n, m). - v (jax.Array): Velocity vectors. Shape (3, n, m). :rtype: tuple[jax.Array, jax.Array]