Torus Services

Services for invariant torus objects in the Hiten framework.

Torus Persistence Service

_TorusPersistenceService()

Handle persistence for invariant torus objects.

class hiten.algorithms.types.services.torus._TorusPersistenceService[source]

Bases: _PersistenceServiceBase

Persistence helpers for invariant tori.

Parameters:

  • save_fn (Callable[..., Any]) – The function to save the object.

  • load_fn (Callable[..., Any]) – The function to load the object.

  • load_inplace_fn (Callable[..., Any]) – The function to load the object in place.

Torus Dynamics Service

_TorusDynamicsService()

Provide numerical operations for invariant torus computations.

class hiten.algorithms.types.services.torus._TorusDynamicsService(torus)[source]

Bases: _DynamicsServiceBase

Provide STM preparation and torus construction helpers.

Parameters:
latest_grid

The latest computed grid.

Type:

np.ndarray | None

latest_params

The latest computed parameters.

Type:

dict | None

property orbit: PeriodicOrbit

The generating periodic orbit.

property initial_state: ndarray

The initial state of the generating periodic orbit.

property period: float

The period of the generating periodic orbit.

property jacobi: float

The Jacobi constant of the generating periodic orbit.

property energy: float

The energy of the generating periodic orbit.

property libration_point: LibrationPoint

The libration point around which the invariant torus is constructed.

property system: System

The parent CR3BP system.

property mu: float

The mass parameter of the parent CR3BP system.

property dynsys: _DynamicalSystem

The dynamical system of the parent CR3BP system.

property var_dynsys: _DynamicalSystem

The variational dynamical system of the parent CR3BP system.

property jacobian_dynsys: _DynamicalSystem

The Jacobian dynamical system of the parent CR3BP system.

property monodromy: ndarray

The monodromy matrix of the generating periodic orbit.

property eigenvalues: ndarray

The eigenvalues of the monodromy matrix of the generating periodic orbit.

property eigenvectors: ndarray

The eigenvectors of the monodromy matrix of the generating periodic orbit.

property grid: ndarray

Return the latest computed grid.

Returns:

The most recently computed torus grid.

Return type:

np.ndarray

Raises:

ValueError – If no grid has been computed yet.

property params: dict

The parameters of the latest computed grid.

eigen_data()[source]

The monodromy matrix, eigenvalues, and eigenvectors of the generating periodic orbit.

Return type:

Tuple[ndarray, ndarray, ndarray]

prepare(*, n_theta1, method, order)[source]

Prepare STM and eigen data for invariant torus construction.

Parameters:

  • n_theta1 (int) – The number of points in the theta1 direction.

  • method (str) – The method to use for the integration.

  • order (int) – The order of the method to use for the integration.

Returns:

  • theta1 (np.ndarray) – Theta1 values for the torus parameterization.

  • ubar (np.ndarray) – State series along the periodic orbit.

  • y_series (np.ndarray) – Complex eigenvector series.

  • phi_mats (np.ndarray) – State transition matrices.

  • monodromy (np.ndarray) – Monodromy matrix.

  • eigenvalues (np.ndarray) – Eigenvalues of the monodromy matrix.

  • eigenvectors (np.ndarray) – Eigenvectors of the monodromy matrix.

Return type:

Tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray]

state(theta1, theta2, *, epsilon, n_theta1, method, order)[source]

The state of the invariant torus at the given theta1 and theta2 values.

Parameters:

  • theta1 (float) – The theta1 value.

  • theta2 (float) – The theta2 value.

  • epsilon (float) – The amplitude of the invariant torus.

  • n_theta1 (int) – The number of points in the theta1 direction.

  • method (str) – The method to use for the integration.

  • order (int) – The order of the method to use for the integration.

Return type:

ndarray

compute_grid(*, epsilon, n_theta1, n_theta2, method, order)[source]

Compute the invariant torus grid.

Parameters:

  • epsilon (float) – The amplitude of the invariant torus.

  • n_theta1 (int) – The number of points in the theta1 direction.

  • n_theta2 (int) – The number of points in the theta2 direction.

  • method (str) – The method to use for the integration.

  • order (int) – The order of the method to use for the integration.

Returns:

The invariant torus grid.

Return type:

np.ndarray

initial_section_curve(*, epsilon, n_theta2, phi_idx, n_theta1, method, order)[source]

Compute the initial section curve of the invariant torus.

Parameters:

  • epsilon (float) – The amplitude of the invariant torus.

  • n_theta2 (int) – The number of points in the theta2 direction.

  • phi_idx (int) – The index of the phi point.

  • n_theta1 (int) – The number of points in the theta1 direction.

  • method (str) – The method to use for the integration.

  • order (int) – The order of the method to use for the integration.

Returns:

The initial section curve and the phase of the complex unit-circle eigenvalue.

Return type:

Tuple[np.ndarray, float]

as_torus(*, epsilon, n_theta1, n_theta2, method, order)[source]

Return an immutable Torus view of the current grid.

The fundamental frequencies are derived from the generating periodic orbit: omega_1 = 2 * pi / T (longitudinal) and omega_2 = arg(lambda) / T where lambda is the complex unit-circle eigenvalue of the monodromy matrix.

Parameters:

  • epsilon (float) – Amplitude parameter for the torus.

  • n_theta1 (int) – Number of points in the theta1 direction.

  • n_theta2 (int) – Number of points in the theta2 direction.

  • method (str) – Integration method.

  • order (int) – Integration order.

Returns:

Immutable torus representation with computed fundamental frequencies.

Return type:

Torus

Raises:

RuntimeError – If no suitable complex eigenvalue is found in the monodromy matrix.

Torus Services

_TorusServices()

Encapsulate services for invariant torus objects.

class hiten.algorithms.types.services.torus._TorusServices(domain_obj, dynamics, persistence)[source]

Bases: _ServiceBundleBase

Bundle all torus services together.

Parameters:
classmethod default(torus)[source]

Create a default service bundle.

Parameters:

torus (InvariantTori) – The domain object.

Returns:

The service bundle.

Return type:

_TorusServices

classmethod with_shared_dynamics(dynamics)[source]

Create a service bundle with a shared dynamics service.

Parameters:

dynamics (_TorusDynamicsService) – The dynamics service.

Returns:

The service bundle.

Return type:

_TorusServices