Tori Module

The tori module provides high-level utilities for computing invariant tori in the circular restricted three-body problem.

Base Classes

The base module provides comprehensive tools for computing 2D invariant tori that bifurcate from periodic orbits.

Torus()

The Torus class provides immutable representation of a 2-D invariant torus.

class hiten.system.torus.Torus[source]

Bases: object

Immutable representation of a 2-D invariant torus.

This class represents a 2D invariant torus in the circular restricted three-body problem, parameterized by two angular coordinates theta1 and theta2. The torus is defined by a grid of state vectors and fundamental frequencies.

Parameters:

  • grid (numpy.ndarray) – Real 6-state samples of shape (n_theta1, n_theta2, 6). Each point represents a state vector on the torus surface.

  • omega (numpy.ndarray) – Fundamental frequencies (omega_1, omega_2) in nondimensional units. omega_1 is the longitudinal frequency, omega_2 is the latitudinal frequency.

  • C0 (float) – Jacobi constant (fixed along the torus family) in nondimensional units.

  • system (System) – Parent CR3BP system (useful for downstream algorithms).

Notes

The torus is parameterized by two angles: - theta1: longitudinal angle along the periodic orbit - theta2: latitudinal angle in the transverse direction

The fundamental frequencies determine the quasi-periodic motion on the torus.

grid: ndarray
omega: ndarray
C0: float
system: System

InvariantTori()

The InvariantTori class provides linear approximation of a 2-D invariant torus bifurcating from a centre component of a periodic orbit.

class hiten.system.torus.InvariantTori[source]

Bases: _HitenBase

Linear approximation of a 2-D invariant torus bifurcating from a centre component of a periodic orbit.

This class implements the computation of invariant tori in the circular restricted three-body problem using linear approximation methods. The torus is constructed from a periodic orbit by analyzing the monodromy matrix and computing the associated eigenvector field.

Parameters:

  • orbit (PeriodicOrbit) – Corrected periodic orbit about which the torus is constructed. The orbit must expose a valid period attribute - no propagation is performed here; we only integrate the variational equations to obtain the state-transition matrices required by the algorithm.

  • angles (The invariant torus is parameterized by two)

  • theta1 (-)

  • theta2 (-)

  • by (The torus surface is given)

  • u(theta1

  • Im(y(theta1))) (theta2) = ubar(theta1) + epsilon * (cos(theta2) * Re(y(theta1)) - sin(theta2) *)

  • field. (where ubar is the periodic orbit trajectory and y is the complex eigenvector)

References

Szebehely, V. (1967). Theory of Orbits. Academic Press.

property orbit: PeriodicOrbit

Periodic orbit about which the torus is constructed.

property libration_point: LibrationPoint

Libration point anchoring the family.

property system: System

Parent CR3BP system.

property dynsys

Dynamical system.

property var_dynsys: _DynamicalSystem

Variational equations system.

property jacobian_dynsys: _DynamicalSystem

Jacobian evaluation system.

property period: float

Orbit period.

property jacobi: float

Jacobi constant.

property energy: float

Orbit energy.

property grid: ndarray

Invariant torus grid.

compute(*, epsilon, n_theta1, n_theta2, method='adaptive', order=8)[source]

Compute the invariant torus grid.

Parameters:

  • epsilon (float) – Torus amplitude used in the linear approximation.

  • n_theta1 (int) – Number of discretisation points along theta1.

  • n_theta2 (int) – Number of discretisation points along theta2.

  • method (Literal['fixed', 'adaptive', 'symplectic'])

  • order (int)

Returns:

Invariant torus grid.

Return type:

numpy.ndarray

Notes

This method computes the invariant torus grid using the linear approximation. The grid is computed using the cached STM samples and the complex eigenvector field. The grid is cached for subsequent plotting and state export.

plot(*, figsize=(10, 8), save=False, dark_mode=True, filepath='invariant_torus.svg', **kwargs)[source]

Render the invariant torus using plot_invariant_torus().

Parameters:

  • figsize (Tuple[int, int], default (10, 8)) – Figure size in inches.

  • save (bool, default False) – Whether to save the plot to a file.

  • dark_mode (bool, default True) – Whether to use dark mode styling.

  • filepath (str, default "invariant_torus.svg") – File path for saving the plot.

  • **kwargs (dict) – Additional keyword arguments accepted by plot_invariant_torus().

Returns:

The generated figure object.

Return type:

matplotlib.figure.Figure

__setstate__(state)[source]

Restore the InvariantTori instance after unpickling.

The heavy, non-serialisable dynamical system is reconstructed lazily using the stored value of orbit.

Parameters:

state (dict) – Dictionary containing the serialized state of the InvariantTori.

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

Load an invariant torus from disk using the adapter.

Parameters:

filepath (str | Path)

Return type:

InvariantTori

load_inplace(filepath, **kwargs)[source]

Load invariant torus data from a file in place.

Parameters:

filepath (str)

Return type:

None