Center Manifold Poincare Maps

The centermanifold module provides Poincare map computation restricted to center manifolds of collinear libration points in the CR3BP.

Main Classes

class hiten.algorithms.poincare.centermanifold.CenterManifoldMapPipeline[source]

Bases: _HitenBaseFacade, Generic[DomainT, InterfaceT, ConfigT, ResultT]

Poincare return map restricted to the center manifold of a collinear libration point.

This class provides the main interface for computing and analyzing Poincare maps on center manifolds in the CR3BP. It supports various seeding strategies and provides visualization capabilities for understanding the local dynamics.

Notes

State vectors are ordered as [q1, q2, q3, p1, p2, p3] where q1=0 for center manifold trajectories. All coordinates are in nondimensional units with the primary-secondary separation as the length unit.

Examples

>>> from hiten.system.center import CenterManifold
>>> from hiten.algorithms.poincare.centermanifold.base import CenterManifoldMap
>>>
>>> # Create center manifold for L1 point
>>> cm = CenterManifold("L1")
>>>
>>> # Create Poincare map at specific energy
>>> energy = -1.5
>>> poincare_map = CenterManifoldMap(cm, energy)
>>>
>>> # Compute the map
>>> poincare_map.compute()
>>>
>>> # Plot the results
>>> poincare_map.plot()
Parameters:
classmethod with_default_engine(config, interface=None, backend=None)[source]

Construct a map with a default-wired engine injected.

This mirrors the DI-friendly facades (e.g., ConnectionPipeline) by creating a default engine using the current configuration and injecting it. The engine is wired for the default section coordinate in the config.

Parameters:

  • config (_CenterManifoldMapConfig) – Configuration object for the center manifold map.

  • interface (_CenterManifoldInterface, optional) – Interface object for the center manifold map. If None, uses the default _CenterManifoldInterface.

  • backend (_CenterManifoldBackend, optional) – Backend instance for the center manifold map. If None, uses the default _CenterManifoldBackend.

Returns:

A center manifold map facade instance with a default engine injected.

Return type:

CenterManifoldMapPipeline

generate(domain_obj, override=False, *, section_coord=None, dt=None, n_iter=None, n_workers=None, method=None, order=None, c_omega_heuristic=None)[source]

Compute the section, supporting runtime overrides without mutating config.

If no overrides are provided, this defers to the cached, default setup and persists the result. If any overrides are provided, a temporary engine is assembled for this call and the result is returned without polluting the persistent cache. In all cases, this method returns the 2-D points of the section.

Parameters:

  • domain_obj (DomainT)

  • override (bool)

  • section_coord (str | None)

  • dt (float | None)

  • n_iter (int | None)

  • n_workers (int | None)

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

  • order (int | None)

  • c_omega_heuristic (float | None)

Return type:

CenterManifoldMapResults

Configuration Classes

class hiten.algorithms.poincare.centermanifold._CenterManifoldMapConfig[source]

Bases: _ReturnMapBaseConfig, _IntegrationConfig, _IterationConfig, _SeedingConfig

Configuration for center manifold Poincare maps.

This dataclass combines configuration from multiple base classes to provide comprehensive settings for center manifold map computation, including integration parameters, seeding strategies, and iteration controls.

Parameters:

  • seed_strategy ({'single', 'axis_aligned', 'level_sets', 'radial', 'random'}, default='axis_aligned') – Strategy for generating initial conditions on the center manifold. - ‘single’: Single axis seeding along one coordinate direction - ‘axis_aligned’: Seeding aligned with coordinate axes - ‘level_sets’: Seeding based on level sets of the Hamiltonian - ‘radial’: Radial seeding pattern from the periodic orbit - ‘random’: Random seeding within specified bounds

  • seed_axis ({'q2', 'p2', 'q3', 'p3'}, optional) – Coordinate axis for single-axis seeding strategy. Required when seed_strategy=’single’, ignored otherwise.

  • section_coord ({'q2', 'p2', 'q3', 'p3'}, default='q3') – Coordinate defining the Poincare section (set to zero).

  • n_seeds (int)

  • n_iter (int)

  • dt (float)

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

  • order (int)

  • c_omega_heuristic (float | None)

  • max_steps (int)

  • n_workers (int | None)

Notes

The configuration inherits from multiple base classes: - _ReturnMapBaseConfig: Basic return map settings - _IntegrationConfig: Integration method and parameters - _IterationConfig: Iteration control parameters - _SeedingConfig: Seeding strategy parameters

All coordinates are in nondimensional units with the primary-secondary separation as the length unit.

seed_strategy: Literal['single', 'axis_aligned', 'level_sets', 'radial', 'random'] = 'axis_aligned'
seed_axis: Literal['q2', 'p2', 'q3', 'p3'] | None = None
section_coord: Literal['q2', 'p2', 'q3', 'p3'] = 'q3'

Backend Classes

class hiten.algorithms.poincare.centermanifold.backend._CenterManifoldBackend[source]

Bases: _ReturnMapBackend

Backend for center manifold computations in the CR3BP.

This backend provides efficient computation of center manifold trajectories using Numba-compiled kernels for Hamiltonian integration and Poincare map evaluation. It supports both Runge-Kutta and symplectic integration methods.

Notes

State vectors are ordered as [q1, q2, q3, p1, p2, p3]. The backend is stateless - all dynamic system data must be passed to the step_to_section method as arguments.

run(seeds, *, dt=0.01, jac_H, clmo_table, section_coord, forward=1, max_steps=2000, method='adaptive', order=8, c_omega_heuristic=20.0)[source]

Propagate center manifold seeds until the next Poincare section crossing.

Parameters:

  • seeds (ndarray, shape (n_seeds, 4)) – Array of initial seeds [q2, p2, q3, p3] (nondimensional units).

  • dt (float, default=1e-2) – Integration time step (nondimensional units).

  • jac_H – Jacobian of the Hamiltonian system.

  • clmo_table – CLMO table for polynomial evaluation.

  • section_coord (str) – Section coordinate identifier (‘q2’, ‘p2’, ‘q3’, or ‘p3’).

  • forward (int)

  • max_steps (int)

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

  • order (int)

  • c_omega_heuristic (float)

Returns:

  • cm_states (ndarray, shape (n_crossings, 4)) – Center manifold coordinates of the crossings.

  • times (ndarray, shape (n_crossings,)) – Times of section crossings.

  • flags (ndarray, shape (n_seeds,)) – Success flags (1 if crossing found, 0 otherwise).

Return type:

tuple[ndarray, ndarray, ndarray]

Notes

This method uses parallel Numba compilation for efficient computation of multiple trajectories. The integration continues until either a section crossing is detected or the maximum number of steps is reached.

Engine Classes

class hiten.algorithms.poincare.centermanifold.engine._CenterManifoldEngine[source]

Bases: _ReturnMapEngine

Engine for center manifold Poincare map computation.

This engine coordinates the computation of Poincare maps restricted to center manifolds in the CR3BP. It manages the seeding strategy, numerical integration, and parallel processing to efficiently generate return maps.

Parameters:

Notes

The engine uses parallel processing to efficiently compute multiple trajectories and their intersections with the Poincare section. It iteratively applies the Poincare map to generate the return map data.

The computation process: 1. Generate initial seeds using the seeding strategy 2. Lift plane points to center manifold states 3. Iteratively apply the Poincare map using parallel workers 4. Collect and combine results from all workers 5. Cache the computed section for reuse

All coordinates are in nondimensional units with the primary-secondary separation as the length unit.

solve(problem)[source]

Compute the Poincare section for the center manifold.

This method generates the Poincare map by iteratively applying the return map to initial seeds. It uses parallel processing to efficiently compute multiple trajectories and their intersections with the section.

Parameters:
Returns:

Computed Poincare section containing points, states, and metadata.

Return type:

_Section

Raises:

RuntimeError – If the seeding strategy produces no valid points inside the Hill boundary.

Notes

The computation process involves: 1. Generating initial seeds using the configured seeding strategy 2. Lifting plane points to center manifold states using the backend 3. Iteratively applying the Poincare map using parallel workers 4. Collecting and combining results from all workers 5. Caching the computed section for future use

The method uses ThreadPoolExecutor for parallel processing, with the number of workers determined by the configuration.

Interface Classes

class hiten.algorithms.poincare.centermanifold.interfaces._CenterManifoldInterface[source]

Bases: _PoincareBaseInterface[_CenterManifoldMapConfig, _CenterManifoldMapProblem, CenterManifoldMapResults, tuple[ndarray | None, ndarray | None]]

create_problem(*, domain_obj, config)[source]

Compose an immutable problem payload for the backend.

Parameters:

  • config (ConfigT | None, optional) – The configuration to use for the problem

  • *args (Any) – Additional arguments to pass to the problem.

  • domain_obj (CenterManifold)

Returns:

The problem payload.

Return type:

ProblemT

to_backend_inputs(problem)[source]

Translate a problem into backend invocation arguments.

Parameters:

problem (ProblemT) – The problem to translate into backend invocation arguments.

Returns:

The backend invocation arguments.

Return type:

_BackendCall

to_domain(outputs, *, problem)[source]

Optional hook to mutate or derive domain artefacts from outputs.

Parameters:

  • outputs (OutputsT) – The outputs to mutate or derive domain artefacts from.

  • problem (ProblemT) – The problem to mutate or derive domain artefacts from.

Returns:

The domain artefacts.

Return type:

Any

to_results(outputs, *, problem)[source]

Package backend outputs into user-facing result objects.

Parameters:

  • outputs (OutputsT) – The outputs to package into user-facing result objects.

  • problem (ProblemT) – The problem to package into user-facing result objects.

  • domain_payload (Any, optional) – The domain payload to package into user-facing result objects.

Returns:

The user-facing result objects.

Return type:

ResultT

create_constraints(section_coord, **kwargs)[source]
Parameters:
Return type:

dict[str, float]

solve_missing_coord(varname, fixed_vals, *, h0, H_blocks, clmo_table, initial_guess=0.001, expand_factor=2.0, max_expand=40, symmetric=False, xtol=1e-12)[source]

Solve H(q,p) = h0 for one coordinate given fixed values.

Returns the coordinate value (root) if a valid bracket is found and the root is located; otherwise returns None.

Parameters:
Return type:

float | None

find_turning(q_or_p, *, h0, H_blocks, clmo_table, initial_guess=0.001, expand_factor=2.0, max_expand=40, symmetric=False, xtol=1e-12)[source]

Find absolute turning point for a CM coordinate.

Solves for the maximum absolute value of the coordinate where the energy constraint can be satisfied, with all other CM coordinates set to zero.

Parameters:
Return type:

float

lift_plane_point(plane, *, section_coord, h0, H_blocks, clmo_table, initial_guess=0.001, expand_factor=2.0, max_expand=40, symmetric=False, xtol=1e-12)[source]

Lift a 2D plane point to a 4D center-manifold state.

Returns (q2, p2, q3, p3) on the section if solvable; otherwise None.

Parameters:
Return type:

Tuple[float, float, float, float] | None

enforce_section_coordinate(states, *, section_coord)[source]
Parameters:
Return type:

ndarray

plane_points_from_states(states, *, section_coord)[source]
Parameters:
Return type:

ndarray

plane_labels(section_coord)[source]
Parameters:

section_coord (str)

Return type:

tuple[str, str]

Strategy Classes

class hiten.algorithms.poincare.centermanifold.seeding._CenterManifoldSeedingBase[source]

Bases: _SeedingStrategyBase

Base class for center manifold seeding strategies.

This class provides the common interface and functionality for all seeding strategies used to generate initial conditions on center manifolds. It handles Hill boundary validation and provides caching for turning point limits.

Parameters:

map_config (_CenterManifoldMapConfig) – Configuration for the center manifold map.

Notes

Subclasses must implement the generate method to define how initial conditions are generated. The base class provides: - Hill boundary validation using turning points - Caching of turning point limits per energy level - Common seed validation functionality

All coordinates are in nondimensional units with the primary-secondary separation as the length unit.

property plane_coords: tuple[str, str]

Get the plane coordinate labels from the config’s section coordinate.

Returns:

Tuple of two coordinate labels that define the section plane.

Return type:

tuple[str, str]

hiten.algorithms.poincare.centermanifold.strategies._make_strategy()[source]

Factory returning a concrete seeding strategy.

Parameters:

  • kind (str) – Strategy identifier. Must be one of: ‘single’, ‘axis_aligned’, ‘level_sets’, ‘radial’, or ‘random’.

  • map_config (_CenterManifoldMapConfig) – Map-level configuration containing global parameters such as n_seeds and seed_axis.

  • **kwargs – Additional keyword arguments forwarded to the concrete strategy constructor.

Returns:

Concrete seeding strategy instance.

Return type:

_CenterManifoldSeedingBase

Raises:

ValueError – If kind is not a valid strategy identifier.

Notes

The available strategies are: - ‘single’: Single axis seeding along one coordinate direction - ‘axis_aligned’: Seeding aligned with coordinate axes - ‘level_sets’: Seeding based on level sets of the Hamiltonian - ‘radial’: Radial seeding pattern from the periodic orbit - ‘random’: Random seeding within specified bounds

Type Classes

class hiten.algorithms.poincare.centermanifold.types.CenterManifoldMapResults[source]

Bases: _MapResults

User-facing results that behave as a _Section with extra helpers.

Parameters:
project(axes)[source]
Parameters:

axes (Tuple[str, str])

Return type:

ndarray

class hiten.algorithms.poincare.centermanifold.types._CenterManifoldMapProblem[source]

Bases: object

Immutable problem definition for a center manifold map run.

Parameters:
section_coord

Section coordinate identifier (‘q2’, ‘p2’, ‘q3’, or ‘p3’).

Type:

str

energy

Energy level (nondimensional units).

Type:

float

dt

Integration time step.

Type:

float

n_iter

Number of return-map iterations to compute.

Type:

int

n_workers

Number of parallel workers.

Type:

int

section_coord: str
energy: float
dt: float
n_iter: int
n_workers: int
jac_H: List[ndarray]
H_blocks: List[ndarray]
clmo_table: List[ndarray]
solve_missing_coord_fn: Callable[[str, dict[str, float]], float | None] | None = None
find_turning_fn: Callable[[str], float] | None = None