Orbits Module

The orbits module provides high-level utilities for representing and analyzing periodic orbits in the circular restricted three-body problem.

This module provides the fundamental classes for representing different types of periodic orbits, including halo orbits, Lyapunov orbits, and vertical orbits.

Base Classes

The base module provides the core periodic orbit framework.

PeriodicOrbit()

Base class for periodic orbits.

class hiten.system.orbits.base.PeriodicOrbit[source]

Bases: _HitenBase

Abstract base-class that encapsulates a CR3BP periodic orbit.

The constructor either accepts a user supplied initial state or derives an analytical first guess via _initial_guess() (to be implemented by subclasses). All subsequent high-level operations (propagation, plotting, stability analysis, differential correction) build upon this initial description.

Parameters:

libration_point (LibrationPoint) – The libration point instance that anchors the family.
initial_state (Sequence[float] or None, optional) – Initial condition in rotating canonical units [x, y, z, vx, vy, vz]. When None an analytical approximation is attempted.

family

Orbit family name (settable property with class-specific defaults).

Type:: str

libration_point

Libration point anchoring the family.

Type:: LibrationPoint

system

Parent CR3BP system.

Type:: System

mu

Mass ratio of the system, accessed as system.mu (dimensionless).

Type:: float

initial_state

Current initial condition in nondimensional units.

Type:: ndarray, shape (6,)

period

Orbit period, set after a successful correction (nondimensional units).

Type:: float or None

trajectory

Stored trajectory after propagate().

Type:: ndarray or None, shape (N, 6)

times

Time vector associated with trajectory (nondimensional units).

Type:: ndarray or None, shape (N,)

stability_info

Output of _stability_indices().

Type:: tuple or None

Notes

Instantiating the class does not perform any propagation. Users must call correct() (or manually set period) followed by propagate().

property amplitude: float

(Read-only) Current amplitude of the orbit.

Returns:: The orbit amplitude in nondimensional units, or None if not set.
Return type:: float or None

property family: str

Get the orbit family name.

Returns:: The orbit family name.
Return type:: str

property initial_state: ndarray[tuple[int, ...], dtype[float64]]

Get the initial state vector of the orbit.

Returns:: The initial state vector [x, y, z, vx, vy, vz] in nondimensional units.
Return type:: numpy.ndarray, shape (6,)

property stability_indices: Tuple | None: The stability indices of the orbit.

property eigenvalues: Tuple | None: The eigenvalues of the orbit.

property eigenvectors: Tuple | None: The eigenvectors of the orbit.

property energy: float

Orbit energy.

Returns:: The energy value in nondimensional units.
Return type:: float

property jacobi: float

Jacobi constant.

Returns:: The Jacobi constant value (dimensionless).
Return type:: float

property system: System

Get the parent CR3BP system.

Returns:: The parent CR3BP system.
Return type:: System

property libration_point: LibrationPoint

Get the libration point around which the orbit is computed.

Returns:: The libration point around which the orbit is computed.
Return type:: LibrationPoint

property mu: float

Mass ratio of the system.

Returns:: The mass ratio (dimensionless).
Return type:: float

property period: float | None

Orbit period.

Returns:: The orbit period in nondimensional units, or None if not set.
Return type:: float or None

property trajectory: Trajectory | None: The trajectory of the orbit.

property trajectories: List[Trajectory]: List of trajectories (for SynodicMap compatibility).

property monodromy: ndarray

Compute the monodromy matrix of the orbit.

Returns:: The monodromy matrix.
Return type:: numpy.ndarray, shape (6, 6)
Raises:: ValueError – If period is not set.

property correction_config: _OrbitCorrectionConfig | None

Provides the differential correction configuration.

For GenericOrbit, this must be set via the correction_config property to enable differential correction.

Returns:: The correction configuration.
Return type:: _OrbitCorrectionConfig
Raises:: NotImplementedError – If correction_config is not set.

property continuation_config: _OrbitContinuationConfig | None

Get or set the continuation parameter for this orbit.

Returns:: The continuation configuration, or None if not set.
Return type:: _OrbitContinuationConfig or None

correct(**kwargs)[source]

Differential correction wrapper.

Parameters:

**kwargs –

Additional keyword arguments passed to the correction method.

tol: float
Convergence tolerance for the residual norm.
max_attempts: int
Maximum number of Newton iterations to attempt before declaring convergence failure.
max_delta: float
Maximum allowed infinity norm of Newton steps.
line_search_config: _LineSearchConfig
Configuration for line search behavior.
finite_difference: bool
Force finite-difference approximation of Jacobians even when analytic Jacobians are available.
forward: int
Integration direction (1 for forward, -1 for backward).

Returns:

The corrected state and period.

Return type:

tuple[np.ndarray, float]

generate(**kwargs)[source]

Generate a family of periodic orbits.

Return type:: tuple[ndarray, float]

propagate(steps=1000, method='adaptive', order=8)[source]

Propagate the orbit.

Parameters:

steps (int, default 1000) – Number of integration steps. Default is 1000.
method (Literal["fixed", "adaptive", "symplectic"]) – Integration method. Default is “adaptive”.
order (int, default 8) – Integration order.

Returns:

The propagated trajectory.

Return type:

Trajectory

manifold(stable=True, direction='positive')[source]

Create a manifold object for this orbit.

Parameters:

stable (bool, optional) – Whether to create a stable manifold. Default is True.
direction (Literal["positive", "negative"], optional) – Direction of the manifold (“positive” or “negative”). Default is “positive”.

Returns:

The manifold object.

Return type:

Manifold

plot(frame='rotating', dark_mode=True, save=False, filepath='orbit.svg', **kwargs)[source]

Plot the orbit trajectory.

Parameters:

frame (str, optional) – Reference frame for plotting (“rotating” or “inertial”). Default is “rotating”.
dark_mode (bool, optional) – Whether to use dark mode for plotting. Default is True.
save (bool, optional) – Whether to save the plot to file. Default is False.
filepath (str, optional) – Path to save the plot. Default is “orbit.svg”.
**kwargs – Additional keyword arguments passed to the plotting function.

Returns:

The plot figure.

Return type:

matplotlib.figure.Figure

Raises:

RuntimeError – If trajectory is not computed.
ValueError – If frame is invalid.

animate(**kwargs)[source]

Create an animation of the orbit trajectory.

Parameters:: **kwargs – Additional keyword arguments passed to the animation function.
Returns:: Animation objects, or None if trajectory is not computed.
Return type:: tuple or None

to_csv(filepath, **kwargs)[source]

Export the orbit trajectory to a CSV file.

Parameters:

filepath (str) – Path to save the CSV file.
**kwargs – Additional keyword arguments passed to pandas.DataFrame.to_csv.

Raises:

ValueError – If trajectory is not computed.

to_df(**kwargs)[source]

Export the orbit trajectory to a pandas DataFrame.

Parameters:: **kwargs – Additional keyword arguments passed to pandas.DataFrame.to_csv.
Return type:: DataFrame

__setstate__(state)[source]: Restore the PeriodicOrbit instance after unpickling.

load_inplace(filepath, **kwargs)[source]

Load orbit data from a file in place.

Parameters:: filepath (str)
Return type:: None

classmethod load(filepath, **kwargs)[source]

Load an orbit from a file.

Parameters:: filepath (str)
Return type:: PeriodicOrbit

Halo Orbits

The halo module provides halo orbit classes.

HaloOrbit()

Halo orbit representation.

class hiten.system.orbits.halo.HaloOrbit[source]

Bases: PeriodicOrbit

Halo orbit class.

Parameters:

libration_point (CollinearPoint) – Target collinear libration point around which the halo orbit is computed.
amplitude_z (float, optional) – z-amplitude of the halo orbit in the synodic frame (nondimensional units). Required if initial_state is None.
zenith ({'northern', 'southern'}, optional) – Indicates the symmetry branch with respect to the xy-plane. Required if initial_state is None.
initial_state (Sequence[float] or None, optional) – Six-dimensional state vector [x, y, z, vx, vy, vz] in the rotating synodic frame. When None an analytical initial guess is generated from amplitude_z and zenith.

amplitude_z

z-amplitude of the halo orbit in the synodic frame (nondimensional units).

Type:: float or None

zenith

Indicates the symmetry branch with respect to the xy-plane.

Type:: {‘northern’, ‘southern’} or None

Raises:

ValueError – If the required amplitude or branch is missing and initial_state is None.
TypeError – If libration_point is not an instance of CollinearPoint.

Parameters:

libration_point (CollinearPoint)
initial_state (Sequence[float] | None)
amplitude_z (float | None)
zenith (Literal['northern', 'southern'] | None)

property zenith: Literal['northern', 'southern']

(Read-only) Current zenith of the orbit.

Returns:: The orbit zenith.
Return type:: Literal[“northern”, “southern”]

Lyapunov Orbits

The lyapunov module provides Lyapunov orbit classes.

LyapunovOrbit()

Lyapunov orbit representation.

class hiten.system.orbits.lyapunov.LyapunovOrbit[source]

Bases: PeriodicOrbit

Planar Lyapunov family around a collinear libration point.

The orbit lies in the (x, y) plane and is symmetric with respect to the x-axis. A linear analytical approximation is used to build the initial guess which is subsequently refined by a differential corrector.

Parameters:

libration_point (CollinearPoint) – Target collinear libration point around which the orbit is computed.
amplitude_x (float, optional) – Requested amplitude Ax along the x-direction in nondimensional units. Required if initial_state is None.
initial_state (Sequence[float] or None, optional) – Six-dimensional state vector (x, y, z, vx, vy, vz) expressed in synodic coordinates in nondimensional units. If None, an analytical guess is generated.

amplitude_x

Requested amplitude Ax along the x-direction (nondimensional units).

Type:: float

libration_point

Equilibrium point about which the orbit is continued.

Type:: CollinearPoint

Raises:

TypeError – If libration_point is not an instance of CollinearPoint.
NotImplementedError – If the selected point corresponds to L3, which is not supported for Lyapunov orbits.
ValueError – If conflicting parameters are provided or required parameters are missing.

Parameters:

libration_point (CollinearPoint)
initial_state (Sequence[float] | None)
amplitude_x (float | None)

Vertical Orbits

The vertical module provides vertical orbit classes.

VerticalOrbit()

Vertical orbit representation.

class hiten.system.orbits.vertical.VerticalOrbit[source]

Bases: PeriodicOrbit

Vertical family about a collinear libration point.

The orbit oscillates out of the synodic plane and is symmetric with respect to the x-z plane. Initial-guess generation is not yet available.

Parameters:

libration_point (CollinearPoint) – Target collinear libration point around which the orbit is computed.
initial_state (Sequence[float] or None, optional) – Six-dimensional initial state vector [x, y, z, vx, vy, vz] in nondimensional units. If None, must be provided manually.

Notes

The implementation of the analytical seed and the Jacobian adjustment for the vertical family is work in progress.