Libration Points Module

The libration module provides abstract helpers to model Libration points of the Circular Restricted Three-Body Problem (CR3BP).

Base Classes

The base module provides the core libration point framework.

LibrationPoint()

Abstract base class for Libration points of the CR3BP.

class hiten.system.libration.base.LibrationPoint[source]

Bases: _HitenBase, ABC

Abstract base class for Libration points of the CR3BP.

Parameters:: system (System) – Parent CR3BP model providing the mass ratio mu and utility functions.

mu

Mass ratio mu of the primaries (copied from system, dimensionless).

Type:: float

system

Reference to the owner system.

Type:: System

position

Cartesian coordinates in the synodic rotating frame (nondimensional units). Evaluated on first access and cached thereafter.

Type:: numpy.ndarray, shape (3,)

energy

Dimensionless mechanical energy evaluated via crtbp_energy().

Type:: float

jacobi_constant

Jacobi integral CJ = -2E corresponding to energy (dimensionless).

Type:: float

is_stable

True if all eigenvalues returned by is_stable() lie inside the unit circle (discrete case) or have non-positive real part (continuous case).

Type:: bool

eigenvalues

Arrays of stable, unstable and centre eigenvalues.

Type:: tuple(numpy.ndarray, numpy.ndarray, numpy.ndarray)

eigenvectors

Bases of the corresponding invariant subspaces.

Type:: tuple(numpy.ndarray, numpy.ndarray, numpy.ndarray)

linear_data

Record with canonical invariants and symplectic basis returned by the normal-form computation.

Type:: LinearData

Notes

The class is abstract. Concrete subclasses must implement:

idx()
_calculate_position()
_get_linear_data()
normal_form_transform()

Heavy algebraic objects produced by the centre-manifold normal-form procedure are cached inside a dedicated CenterManifold instance to avoid memory bloat.

Examples

>>> from hiten.system.base import System
>>> sys = System(mu=0.0121505856)   # Earth-Moon system
>>> L1 = sys.libration_points['L1']
>>> L1.position
array([...])

property system: System: The system this libration point belongs to.

property mu: float: The mass parameter of the system.

property dynsys

Underlying vector field instance.

Returns:: The underlying vector field instance.
Return type:: _DynamicalSystemProtocol

property var_dynsys

Underlying variational equations system.

Returns:: The underlying variational equations system.
Return type:: _DynamicalSystemProtocol

property jacobian_dynsys

Underlying Jacobian evaluation system.

Returns:: The underlying Jacobian evaluation system.
Return type:: _DynamicalSystemProtocol

abstract property idx: int

Get the libration point index.

Returns:: The libration point index (1-5 for L1-L5).
Return type:: int

property energy: float

Get the energy of the Libration point.

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

property jacobi: float

Get the Jacobi constant of the Libration point.

Returns:: The Jacobi constant in nondimensional units.
Return type:: float

property is_stable: bool

Check if the Libration point is linearly stable.

A libration point is considered stable if its linear analysis yields no unstable eigenvalues. The check is performed on the continuous-time system by default.

Returns:: True if the libration point is linearly stable.
Return type:: bool

property eigenvalues: Tuple[ndarray, ndarray, ndarray]

Get the eigenvalues of the linearized system at the Libration point.

Returns:: (stable_eigenvalues, unstable_eigenvalues, center_eigenvalues) Each array contains eigenvalues in nondimensional units.
Return type:: tuple

property eigenvectors: Tuple[ndarray, ndarray, ndarray]

Get the eigenvectors of the linearized system at the Libration point.

Returns:: (stable_eigenvectors, unstable_eigenvectors, center_eigenvectors) Each array contains eigenvectors as column vectors.
Return type:: tuple

create_orbit(family, /, **kwargs)[source]

Parameters:: family (str | type[PeriodicOrbit])
Return type:: PeriodicOrbit

get_center_manifold(degree)[source]

Return (and lazily construct) a CenterManifold of given degree.

Heavy polynomial data (Hamiltonians in multiple coordinate systems, Lie generators, etc.) are cached inside the returned CenterManifold, not in the LibrationPoint itself.

Parameters:: degree (int) – The maximum degree of the center manifold expansion.
Returns:: The center manifold instance.
Return type:: CenterManifold

hamiltonian(max_deg, form='physical')[source]

Return a Hamiltonian object from the associated CenterManifold.

Parameters:

max_deg (int) – The maximum degree of the Hamiltonian expansion.
form (str) – The Hamiltonian form to get coefficients for. Default is “physical”. Available forms: ‘physical’, ‘real_normal’, ‘complex_normal’, ‘normalized’, ‘center_manifold_complex’, ‘center_manifold_real’.

Returns:

The Hamiltonian object with the specified form and degree.

Return type:

Hamiltonian

hamiltonians(max_deg)[source]

Return all Hamiltonian representations from the associated CenterManifold.

Parameters:: max_deg (int) – The maximum degree of the Hamiltonian expansion.
Returns:: Dictionary with keys: ‘physical’, ‘real_normal’, ‘complex_normal’, ‘normalized’, ‘center_manifold_complex’, ‘center_manifold_real’. Each value is a Hamiltonian object.
Return type:: dict[str, Hamiltonian]

hamiltonian_system(form, max_deg)[source]

Return the Hamiltonian system for the given form.

Parameters:

form (str) – The Hamiltonian form identifier.
max_deg (int) – The maximum degree of the Hamiltonian expansion.

Returns:

The Hamiltonian system instance.

Return type:

_HamiltonianSystem

generating_functions(max_deg)[source]

Return the Lie-series generating functions from CenterManifold.

Parameters:: max_deg (int) – The maximum degree of the generating function expansion.
Returns:: List of LieGeneratingFunction objects.
Return type:: list[LieGeneratingFunction]

property position: ndarray

Get the position of the Libration point in the rotating frame.

Returns:: 3D vector [x, y, z] representing the position in nondimensional units.
Return type:: numpy.ndarray, shape (3,)

property linear_data

Get the linear data for the Libration point.

Returns:: The linear data containing eigenvalues and eigenvectors.
Return type:: _LinearData

property normal_form_transform: Tuple[ndarray, ndarray]

Get the normal form transform for the Libration point.

Returns:: (C, Cinv) where C is the symplectic transformation matrix and Cinv is its inverse.
Return type:: tuple

__setstate__(state)[source]: Restore adapter wiring after unpickling.

load_inplace(filepath)[source]

Load data into this object from a file (in place).

Parameters:

filepath (str or Path) – The path to the file to load the object from.
**kwargs – Additional keyword arguments passed to the load method.

Returns:

The object with loaded data (self).

Return type:

_HitenBase

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

Load the object from a file.

Parameters:

filepath (str or Path) – The path to the file to load the object from.
**kwargs – Additional keyword arguments passed to the load method.

Returns:

The loaded object.

Return type:

_HitenBase

Collinear Points

The collinear module provides collinear libration point classes.

CollinearPoint()

Base class for collinear Libration points (L1, L2, L3).

class hiten.system.libration.collinear.CollinearPoint[source]

Bases: LibrationPoint

Base class for collinear Libration points (L1, L2, L3).

The collinear points lie on the x-axis connecting the two primary bodies. They are characterized by having unstable dynamics with saddle-center stability (one unstable direction, two center directions).

Parameters:: system (System) – The CR3BP system containing the mass parameter mu.

mu

Mass parameter of the CR3BP system (ratio of smaller to total mass, dimensionless).

Type:: float

gamma

Distance ratio from the libration point to the nearest primary (dimensionless).

Type:: float

sign

Sign convention for coordinate transformations (+1 for L3, -1 for L1/L2).

Type:: int

a

Offset along the x-axis used in frame changes (dimensionless).

Type:: float

linear_modes

(lambda1, omega1, omega2) values for the linearized system.

Type:: tuple

property linear_modes

Get the linear modes for the Libration point.

Returns:: (lambda1, omega1, omega2) values in nondimensional units.
Return type:: tuple

property normal_form_transform: Tuple[ndarray, ndarray]

Get the normal form transform for the Libration point.

Returns:: (C, Cinv) where C is the symplectic transformation matrix and Cinv is its inverse.
Return type:: tuple

property linear_data

Get the linear data for the Libration point.

Returns:: The linear data containing eigenvalues and eigenvectors.
Return type:: _LinearData

property gamma: float

Get the gamma value (distance ratio) for the collinear libration point.

Returns:: The gamma value (dimensionless), representing the distance ratio from the libration point to the nearest primary.
Return type:: float

L1Point()

L1 Libration point, located between the two primary bodies.

class hiten.system.libration.collinear.L1Point[source]

Bases: CollinearPoint

L1 Libration point, located between the two primary bodies.

The L1 point is situated between the two primary bodies on the line connecting them. It is characterized by saddle-center stability with one unstable direction and two center directions.

Parameters:: system (System) – The CR3BP system containing the mass parameter mu.

property idx: int

Get the libration point index.

Returns:: The libration point index (1 for L1).
Return type:: int

L2Point()

L2 Libration point, located beyond the smaller primary body.

class hiten.system.libration.collinear.L2Point[source]

Bases: CollinearPoint

L2 Libration point, located beyond the smaller primary body.

The L2 point is situated beyond the smaller primary body on the line connecting the primaries. It is characterized by saddle-center stability with one unstable direction and two center directions.

Parameters:: system (System) – The CR3BP system containing the mass parameter mu.

property idx: int

Get the libration point index.

Returns:: The libration point index (2 for L2).
Return type:: int

L3Point()

L3 Libration point, located beyond the larger primary body.

class hiten.system.libration.collinear.L3Point[source]

Bases: CollinearPoint

L3 Libration point, located beyond the larger primary body.

The L3 point is situated beyond the larger primary body on the line connecting the primaries. It is characterized by saddle-center stability with one unstable direction and two center directions.

Parameters:: system (System) – The CR3BP system containing the mass parameter mu.

property idx: int

Get the libration point index.

Returns:: The libration point index (3 for L3).
Return type:: int

Triangular Points

The triangular module provides triangular libration point classes.

TriangularPoint()

Abstract helper for the triangular Libration points.

class hiten.system.libration.triangular.TriangularPoint[source]

Bases: LibrationPoint

Abstract helper for the triangular Libration points.

The triangular points form equilateral triangles with the two primary bodies. They behave as centre-type equilibria when the mass ratio mu is below Routh’s critical value.

Parameters:: system (System) – CR3BP model supplying the mass parameter mu.

mu

Mass ratio mu = m2 / (m1 + m2) taken from system (dimensionless).

Type:: float

ROUTH_CRITICAL_MU

Critical value mu_R delimiting linear stability (dimensionless).

Type:: float

sign

+1 for L4Point, -1 for L5Point.

Type:: int

a

Offset used by local <-> synodic frame transformations (dimensionless).

Type:: float

Notes

A warning is logged if mu > mu_R.

ROUTH_CRITICAL_MU = np.float64(0.009346618537341811)

property normal_form_transform

Build the 6x6 symplectic matrix C that sends H2 to normal form.

Returns:: (C, Cinv) where C is the symplectic transformation matrix and Cinv is its inverse.
Return type:: tuple

property linear_modes

Get the linear modes for the Libration point.

Returns:: (omega_1, omega_2, omega_z) where: - omega_1 > 0 with omega_1^2 < 1/2 (small positive planar frequency) - omega_2 < 0 (negative planar frequency) - omega_z = 1.0 (vertical frequency) For triangular points all eigenvalues are purely imaginary so no hyperbolic mode is present.
Return type:: tuple

property linear_data

Get the linear data for the Libration point.

Returns:: The linear data containing eigenvalues and eigenvectors.
Return type:: _LinearData

L4Point()

L4 Libration point, forming an equilateral triangle with the two primary bodies, located above the x-axis (positive y).

class hiten.system.libration.triangular.L4Point[source]

Bases: TriangularPoint

L4 Libration point, forming an equilateral triangle with the two primary bodies, located above the x-axis (positive y).

The L4 point is situated above the x-axis, forming an equilateral triangle with the two primary bodies. It is characterized by center-type stability when the mass ratio is below Routh’s critical value.

Parameters:: system (System) – The CR3BP system containing the mass parameter mu.

property idx: int

Get the libration point index.

Returns:: The libration point index (4 for L4).
Return type:: int

L5Point()

L5 Libration point, forming an equilateral triangle with the two primary bodies, located below the x-axis (negative y).

class hiten.system.libration.triangular.L5Point[source]

Bases: TriangularPoint

L5 Libration point, forming an equilateral triangle with the two primary bodies, located below the x-axis (negative y).

The L5 point is situated below the x-axis, forming an equilateral triangle with the two primary bodies. It is characterized by center-type stability when the mass ratio is below Routh’s critical value.

Parameters:: system (System) – The CR3BP system containing the mass parameter mu.

property idx: int

Get the libration point index.

Returns:: The libration point index (5 for L5).
Return type:: int