Base Module

The base module provides high-level abstractions for the Circular Restricted Three-Body Problem (CR3BP).

This module bundles the physical information of a binary system, computes the mass parameter mu, instantiates the underlying vector field via rtbp_dynsys(), and pre-computes the five classical Lagrange (libration) points.

System()

The main system class that provides a lightweight wrapper around the CR3BP dynamical system.

class hiten.system.base.System[source]

Bases: _HitenBase

Lightweight wrapper around the CR3BP dynamical system.

The class stores the physical properties of the primaries, computes the dimensionless mass parameter mu = m2 / (m1 + m2), instantiates the CR3BP vector field through rtbp_dynsys(), and caches the five Lagrange points.

Parameters:

primary (Body) – Primary gravitating body.
secondary (Body) – Secondary gravitating body.
distance (float) – Characteristic separation between the bodies in km.

mu

Mass parameter mu (dimensionless).

Type:: float

libration_points

Mapping from integer identifiers {1,…,5} to the corresponding libration point objects.

Type:: dict[int, LibrationPoint]

dynsys

Underlying vector field instance compatible with the integrators defined in integrators.

Type:: _DynamicalSystemProtocol

var_dynsys

Underlying variational equations system.

Type:: _DynamicalSystemProtocol

Notes

The heavy computations reside in the dynamical system and individual libration point classes; this wrapper simply orchestrates them.

property primary: Body

Primary gravitating body.

Returns:: The primary gravitating body.
Return type:: Body

property secondary: Body

Secondary gravitating body.

Returns:: The secondary gravitating body.
Return type:: Body

property distance: float

Characteristic separation between the bodies.

Returns:: The characteristic separation between the bodies in km.
Return type:: float

property mu: float

Mass parameter mu.

Returns:: The mass parameter mu = m2 / (m1 + m2) (dimensionless).
Return type:: float

property libration_points: Dict[int, LibrationPoint]

Mapping from integer identifiers {1,…,5} to libration point objects.

Returns:: Dictionary mapping integer identifiers {1,…,5} to libration point objects.
Return type:: dict[int, LibrationPoint]

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

get_libration_point(index)[source]

Access a pre-computed libration point.

Parameters:: index (int) – Identifier of the desired point in {1, 2, 3, 4, 5}.
Returns:: Requested libration point instance.
Return type:: LibrationPoint
Raises:: ValueError – If index is not in the valid range.

Examples

>>> sys = System(primary, secondary, distance)
>>> L1 = sys.get_libration_point(1)

propagate(initial_conditions, tf=6.283185307179586, *, steps=1000, method='adaptive', order=8, forward=1)[source]

Propagate arbitrary initial conditions in the CR3BP.

This helper is a thin wrapper around _propagate_dynsys() that avoids the need to instantiate a PeriodicOrbit.

Parameters:

initial_conditions (Sequence[float]) – Six-element state vector [x, y, z, vx, vy, vz] expressed in canonical CR3BP units (nondimensional).
tf (float, default 2*pi) – Final time for integration in nondimensional units.
steps (int, default 1000) – Number of output nodes in the returned trajectory.
method ({"fixed", "adaptive", "symplectic"}, default "adaptive") – Integration backend to employ (Hiten integrators).
order (int, default 8) – Formal order of the integrator when applicable.
forward (int)

Returns:

The propagated trajectory.

Return type:

Trajectory

classmethod from_bodies(primary_name, secondary_name)[source]

Factory method to build a System directly from body names.

This helper retrieves the masses, radii and characteristic orbital distance of the selected primary/secondary pair from Constants and instantiates the corresponding Body objects before finally returning the fully-initialised System instance.

Parameters:

primary_name (str) – Name of the primary body (case-insensitive, e.g. “earth”).
secondary_name (str) – Name of the secondary body orbiting the primary (e.g. “moon”).

Returns:

Newly created CR3BP system.

Return type:

System

Raises:

ValueError – If the body names are not found in the constants database.

classmethod from_mu(mu)[source]

Factory method to build a System directly from the mass parameter.

Parameters:: mu (float) – Mass parameter mu = m2 / (m1 + m2) (dimensionless).
Returns:: Newly created CR3BP system with the specified mass parameter.
Return type:: System

__setstate__(state)[source]

Restore the System instance after unpickling.

The heavy, non-serialisable dynamical system is reconstructed lazily using the stored value of mu and the names of the primary and secondary bodies.

Parameters:: state (dict) – Dictionary containing the serialized state of the System.

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

Load a System from a file (new instance).

Parameters:: filepath (str | Path)
Return type:: System