Restricted Three-Body Problem

The rtbp module provides Circular Restricted Three-Body Problem (CR3BP) dynamics implementation.

_RTBPRHS()

The _RTBPRHS class defines the Circular Restricted Three-Body Problem equations of motion.

class hiten.algorithms.dynamics.rtbp._RTBPRHS[source]

Bases: _DynamicalSystem

Define the Circular Restricted Three-Body Problem equations of motion.

Implements the full 6-dimensional CR3BP dynamics in the rotating synodic frame, including gravitational forces from both primaries and all rotating frame effects (Coriolis and centrifugal forces).

Parameters:

mu (float) – Mass parameter mu = m2/(m1+m2) where m1, m2 are primary/secondary masses.
name (str, optional) – System identifier. Default is ‘RTBP’.

dim

State space dimension (always 6 for CR3BP).

Type:: int

mu

Mass parameter of the system.

Type:: float

name

System identifier string.

Type:: str

rhs

JIT-compiled CR3BP vector field function.

Type:: Callable[[float, ndarray], ndarray]

Notes

Uses nondimensional units: distance = primary separation, time = orbital period/(2*pi)
Primary m1 located at (-mu, 0, 0), secondary m2 at (1-mu, 0, 0)
Includes all rotating frame effects: Coriolis, centrifugal, gravitational
Suitable for both planar and spatial (3D) motion
Autonomous system (no explicit time dependence)

Examples

>>> # Earth-Moon system (approximate)
>>> em_system = _RTBPRHS(mu=0.01215, name="Earth-Moon CR3BP")
>>> # Compute derivative at L1 point vicinity
>>> state = np.array([0.8, 0, 0, 0, 0.1, 0])
>>> derivative = em_system.rhs(0.0, state)

See also

_crtbp_accel(): Core equations of motion implementation
rtbp_dynsys(): Factory function for creating instances
_VarEqRHS: Variational equations based on this system

_VarEqRHS()

The _VarEqRHS class provides the CR3BP variational equations for state transition matrix propagation.

class hiten.algorithms.dynamics.rtbp._VarEqRHS[source]

Bases: _DynamicalSystem

Provide the CR3BP variational equations for state transition matrix propagation.

Implements the 42-dimensional variational system that simultaneously evolves the 6x6 state transition matrix and the 6-dimensional phase space trajectory. Used for computing fundamental matrix solutions, monodromy matrices, and sensitivity analysis.

Parameters:

mu (float) – Mass parameter mu = m2/(m1+m2) of the CR3BP system.
name (str, optional) – System identifier. Default is ‘CR3BP Variational Equations’.

mu

Mass parameter of the CR3BP system.

Type:: float

name

System identifier string.

Type:: str

rhs

JIT-compiled variational equations function.

Type:: Callable[[float, ndarray], ndarray]

Notes

State dimension is 42: flattened 6x6 STM (36) + phase space state (6)
STM evolution follows d(Phi)/dt = F(x) * Phi where F is Jacobian
Physical state follows standard CR3BP equations of motion
Initialize STM as 6x6 identity matrix for fundamental solution

Examples

>>> # Create variational system
>>> var_sys = _VarEqRHS(mu=0.01215)
>>> # Initialize with identity STM and initial state
>>> PHI0 = np.zeros(42)
>>> PHI0[:36] = np.eye(6).flatten()  # Identity STM
>>> PHI0[36:] = initial_state        # Initial 6D state

See also

_var_equations(): Core variational equations implementation
_compute_stm(): Uses this system for STM computation
_RTBPRHS: Base CR3BP dynamics

_JacobianRHS()

The _JacobianRHS class provides a dynamical system for CR3BP Jacobian matrix evaluation.

class hiten.algorithms.dynamics.rtbp._JacobianRHS[source]

Bases: _DynamicalSystem

Provide a dynamical system for CR3BP Jacobian matrix evaluation.

Provides a dynamical system interface for evaluating the Jacobian matrix of the CR3BP vector field at specified positions. Used for linearization and sensitivity analysis applications.

Parameters:

mu (float) – Mass parameter mu = m2/(m1+m2) where 0 < mu < 1.
name (str, optional) – Human-readable system identifier. Default is ‘CR3BP Jacobian’.

mu

Mass parameter of the CR3BP system.

Type:: float

name

System identifier string.

Type:: str

rhs

JIT-compiled function returning 6x6 Jacobian matrix.

Type:: Callable[[float, ndarray], ndarray]

Notes

State dimension is 3 (only position coordinates x, y, z needed)
Returns full 6x6 Jacobian matrix flattened or as 2D array
Uses analytical derivatives for high accuracy
JIT-compiled for efficient repeated evaluation

See also

_jacobian_crtbp(): Core Jacobian computation function
_RTBPRHS: Main CR3BP equations of motion
_VarEqRHS: Variational equations using this Jacobian

rtbp_dynsys()

The rtbp_dynsys() function creates CR3BP dynamical system.

hiten.algorithms.dynamics.rtbp.rtbp_dynsys()[source]

Create CR3BP dynamical system.

Factory function for creating CR3BP equations of motion with specified mass parameter. Provides functional interface alternative to direct constructor usage.

Parameters:

mu (float) – Mass parameter mu = m2/(m1+m2) of the CR3BP system.
name (str, optional) – System identifier. Default is “RTBP”.

Returns:

Configured CR3BP dynamical system.

Return type:

_RTBPRHS

See also

_RTBPRHS: Direct constructor interface

variational_dynsys()

The variational_dynsys() function creates CR3BP variational equations system.

hiten.algorithms.dynamics.rtbp.variational_dynsys()[source]

Create CR3BP variational equations system.

Factory function for creating variational equations system for state transition matrix propagation.

Parameters:

mu (float) – Mass parameter of the CR3BP system.
name (str, optional) – System identifier. Default is “VarEq”.

Returns:

Configured variational equations system.

Return type:

_VarEqRHS

See also

_VarEqRHS: Direct constructor interface
_compute_stm(): Uses this system for STM computation

_compute_stm()

The _compute_stm() function propagates state transition matrix (STM) along CR3BP trajectory.

hiten.algorithms.dynamics.rtbp._compute_stm()[source]

Propagate state transition matrix (STM) along CR3BP trajectory.

Integrates the 42-dimensional variational system to compute the fundamental matrix solution (state transition matrix) from initial time to final time. The STM describes how small perturbations to initial conditions evolve along the reference trajectory.

Parameters:

dynsys (_DynamicalSystem) – Variational system implementing 42-dimensional CR3BP variational equations. Typically an instance of _VarEqRHS.
x0 (array_like, shape (6,)) – Initial state vector [x, y, z, vx, vy, vz] in nondimensional rotating frame.
tf (float) – Final integration time in nondimensional units.
steps (int, optional) – Number of equally-spaced output time points. Default is 2000.
forward (int, optional) – Integration direction: +1 for forward, -1 for backward time. Default is 1.
method ({'fixed', 'adaptive', 'symplectic'}, optional) – Numerical integration method. Default is ‘adaptive’.
order (int, optional) – Integration order. Default is 8.
**kwargs – Additional keyword arguments passed to the integrator, including: - rtol: Relative tolerance for integration. If None, uses default from _propagate_dynsys(). - atol: Absolute tolerance for integration. If None, uses default from _propagate_dynsys().

Returns:

x (ndarray, shape (steps, 6)) – Reference trajectory in phase space.
times (ndarray, shape (steps,)) – Time points corresponding to trajectory.
phi_T (ndarray, shape (6, 6)) – State transition matrix Phi(tf) at final time.
PHI (ndarray, shape (steps, 42)) – Complete evolution: flattened STM (36 components) + state (6 components).

Notes

STM initialized as 6x6 identity matrix at t=0
Backward integration uses DirectedSystem with momentum sign flipping
Combined 42D system enables simultaneous trajectory and linearization
STM satisfies d(Phi)/dt = F(x(t)) * Phi(t) where F is the Jacobian

See also

_var_equations(): Variational equations used for integration
_VarEqRHS: Dynamical system for variational equations
_compute_monodromy(): Specialized version for periodic orbits

_compute_monodromy()

The _compute_monodromy() function computes monodromy matrix for periodic CR3BP orbit.

hiten.algorithms.dynamics.rtbp._compute_monodromy()[source]

Compute monodromy matrix for periodic CR3BP orbit.

Calculates the monodromy matrix M = Phi(T) by integrating the variational equations over one complete orbital period. The monodromy matrix describes how small perturbations evolve after one complete orbit.

Parameters:

dynsys (_DynamicalSystem) – Variational system implementing CR3BP variational equations.
x0 (array_like, shape (6,)) – Initial state on the periodic orbit.
period (float) – Orbital period T in nondimensional time units.

Returns:

Monodromy matrix M = Phi(T) describing linearized return map.

Return type:

ndarray, shape (6, 6)

Notes

One eigenvalue is always 1 (tangent to periodic orbit)
For Hamiltonian systems, eigenvalues occur in reciprocal pairs
Stability determined by eigenvalue magnitudes relative to unit circle

See also

_compute_stm(): General STM computation used internally
_stability_indices(): Compute stability indices from monodromy matrix

_stability_indices()

The _stability_indices() function computes Floquet stability indices for periodic orbit analysis.

hiten.algorithms.dynamics.rtbp._stability_indices()[source]

Compute Floquet stability indices for periodic orbit analysis.

Calculates the classical stability indices nu_i = (lambda_i + 1/lambda_i)/2 from the monodromy matrix eigenvalues. These indices characterize the linear stability of periodic orbits in Hamiltonian systems.

Parameters:

monodromy (ndarray, shape (6, 6)) – Monodromy matrix from periodic orbit integration.

Returns:

tuple of float – Stability indices (nu_1, nu_2) corresponding to the two non-trivial eigenvalue pairs. |nu_i| <= 1 indicates stability.
ndarray, shape (6,) – All eigenvalues sorted by absolute value (descending order).

Notes

Uses eigenvalues at indices 2 and 4 (assumes sorted by magnitude)
For Hamiltonian systems, eigenvalues occur in reciprocal pairs
One eigenvalue is always 1 (tangent to periodic orbit)
Stable orbits have |nu_i| <= 1 for all i

See also

_compute_monodromy(): Provides monodromy matrix input
_stability_indices(): More robust version

_crtbp_accel()

The _crtbp_accel() function computes CR3BP equations of motion in rotating synodic frame.

hiten.algorithms.dynamics.rtbp._crtbp_accel()[source]

Compute CR3BP equations of motion in rotating synodic frame.

JIT-compiled function that evaluates the full 6-dimensional equations of motion for the Circular Restricted Three-Body Problem, including gravitational forces from both primaries and Coriolis/centrifugal effects from the rotating frame.

Parameters:

state (ndarray, shape (6,)) – State vector [x, y, z, vx, vy, vz] in nondimensional rotating frame.
mu (float) – Mass parameter mu = m2/(m1+m2) of the CR3BP system.

Returns:

Time derivative [vx, vy, vz, ax, ay, az] where accelerations include gravitational, Coriolis, and centrifugal terms.

Return type:

ndarray, shape (6,)

Notes

Primary m1 located at (-mu, 0, 0)
Secondary m2 located at (1-mu, 0, 0)
Includes 2*Omega x v Coriolis terms and Omega x (Omega x r) centrifugal terms
Uses nondimensional units with primary-secondary separation = 1

See also

_RTBPRHS: Dynamical system wrapper for these equations
_jacobian_crtbp(): Analytical Jacobian of these equations

_jacobian_crtbp()

The _jacobian_crtbp() function computes analytical Jacobian matrix of CR3BP equations of motion.

hiten.algorithms.dynamics.rtbp._jacobian_crtbp()[source]

Compute analytical Jacobian matrix of CR3BP equations of motion.

JIT-compiled function that evaluates the 6x6 Jacobian matrix of the CR3BP vector field with respect to the state variables. Used for linearization, variational equations, and stability analysis.

Parameters:

x (float) – Position coordinates in nondimensional rotating frame.
y (float) – Position coordinates in nondimensional rotating frame.
z (float) – Position coordinates in nondimensional rotating frame.
mu (float) – Mass parameter mu = m2/(m1+m2) of the CR3BP system.

Returns:

Jacobian matrix F = df/dy where f is the CR3BP vector field. Upper-right 3x3 block is identity (velocity terms). Lower-left 3x3 block contains gravitational and centrifugal derivatives. Off-diagonal terms (3,4) and (4,3) contain Coriolis coefficients.

Return type:

ndarray, shape (6, 6)

Notes

Analytical derivatives of gravitational potential and frame effects
Includes second derivatives of effective potential for acceleration terms
Coriolis terms appear as F[3,4] = 2, F[4,3] = -2 from rotating frame
Used internally by variational equations and stability analysis

See also

_var_equations(): Uses this Jacobian for STM propagation
_JacobianRHS: Dynamical system wrapper for Jacobian evaluation
_crtbp_accel(): Vector field that this function differentiates

_var_equations()

The _var_equations() function computes CR3BP variational equations for state transition matrix propagation.

hiten.algorithms.dynamics.rtbp._var_equations()[source]

Compute CR3BP variational equations for state transition matrix propagation.

JIT-compiled function that evaluates the 42-dimensional variational system combining the 6x6 state transition matrix (STM) evolution with the base CR3BP dynamics. Used for computing fundamental matrix solutions and monodromy matrices of periodic orbits.

Parameters:

t (float) – Time variable (unused in autonomous system, required for ODE interface).
PHI_vec (ndarray, shape (42,)) – Combined state vector: first 36 components are flattened 6x6 STM, last 6 components are physical state [x, y, z, vx, vy, vz].
mu (float) – Mass parameter mu = m2/(m1+m2) of the CR3BP system.

Returns:

Time derivative of combined state: [d(STM)/dt flattened, dx/dt]. STM evolution follows d(Phi)/dt = F(x) * Phi where F is the Jacobian.

Return type:

ndarray, shape (42,)

Notes

STM initialized as 6x6 identity matrix at t=0
Matrix multiplication F * Phi implemented with explicit loops for Numba compatibility
Physical state evolution uses same equations as _crtbp_accel
Combined system enables simultaneous propagation of trajectory and linearization

See also

_jacobian_crtbp(): Provides Jacobian matrix F for STM evolution
_crtbp_accel(): Base dynamics for physical state evolution
_VarEqRHS: Dynamical system wrapper for these equations
_compute_stm(): Uses this function for STM propagation

rtbp_dynsys()

The rtbp_dynsys() function creates CR3BP dynamical system.

hiten.algorithms.dynamics.rtbp.rtbp_dynsys()[source]

Create CR3BP dynamical system.

Factory function for creating CR3BP equations of motion with specified mass parameter. Provides functional interface alternative to direct constructor usage.

Parameters:

mu (float) – Mass parameter mu = m2/(m1+m2) of the CR3BP system.
name (str, optional) – System identifier. Default is “RTBP”.

Returns:

Configured CR3BP dynamical system.

Return type:

_RTBPRHS

See also

_RTBPRHS: Direct constructor interface

variational_dynsys()

The variational_dynsys() function creates CR3BP variational equations system.

hiten.algorithms.dynamics.rtbp.variational_dynsys()[source]

Create CR3BP variational equations system.

Factory function for creating variational equations system for state transition matrix propagation.

Parameters:

mu (float) – Mass parameter of the CR3BP system.
name (str, optional) – System identifier. Default is “VarEq”.

Returns:

Configured variational equations system.

Return type:

_VarEqRHS

See also

_VarEqRHS: Direct constructor interface
_compute_stm(): Uses this system for STM computation

jacobian_dynsys()

The jacobian_dynsys() function creates CR3BP Jacobian evaluation system.

hiten.algorithms.dynamics.rtbp.jacobian_dynsys()[source]

Create CR3BP Jacobian evaluation system.

Factory function for creating Jacobian matrix evaluation system with specified mass parameter.

Parameters:

mu (float) – Mass parameter of the CR3BP system.
name (str, optional) – System identifier. Default is “Jacobian”.

Returns:

Configured Jacobian evaluation system.

Return type:

_JacobianRHS

See also

_JacobianRHS: Direct constructor interface