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: _HitenBasePipeline, 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:

config (CenterManifoldMapConfig)
engine (_CenterManifoldEngine)
interface (_CenterManifoldInterface)
backend (_CenterManifoldBackend)

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, options)[source]

Compute the section using configured engine.

Parameters:

domain_obj (DomainT) – The domain object to compute the map for.
options (CenterManifoldMapOptions) – Runtime options for the map pipeline.

Returns:

The computed section results.

Return type:

CenterManifoldMapResults

Configuration Classes

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(request)[source]

Propagate center manifold seeds until the next Poincare section crossing.

Parameters:: request (CenterManifoldBackendRequest) – Structured request containing seeds and integration parameters.
Returns:: Structured response containing center manifold states, times, flags, and metadata.
Return type:: CenterManifoldBackendResponse

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:

backend (_CenterManifoldBackend) – Backend providing numerical integration and section crossing detection.
seed_strategy (_CenterManifoldSeedingBase) – Strategy for generating initial conditions on the center manifold.
map_config (CenterManifoldMapConfig) – Configuration specifying computation parameters.
interface (_CenterManifoldInterface)

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:

recompute (bool, default=False) – If True, force recomputation even if cached results exist.
problem (_CenterManifoldMapProblem)

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, CenterManifoldBackendResponse]

create_problem(*, domain_obj, config, options)[source]

Compose an immutable problem payload for the backend.

Parameters:

config (ConfigT | None, optional) – The configuration to use for the problem
options (Any, optional) – The options 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, domain_payload=None)[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:

section_coord (str)
kwargs (float)

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:

varname (str)
fixed_vals (dict[str, float])
h0 (float)
initial_guess (float)
expand_factor (float)
max_expand (int)
symmetric (bool)
xtol (float)

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:

q_or_p (str)
h0 (float)
initial_guess (float)
expand_factor (float)
max_expand (int)
symmetric (bool)
xtol (float)

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:

plane (Tuple[float, float])
section_coord (str)
h0 (float)
initial_guess (float)
expand_factor (float)
max_expand (int)
symmetric (bool)
xtol (float)

Return type:

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

enforce_section_coordinate(states, *, section_coord)[source]

Parameters:

states (ndarray)
section_coord (str)

Return type:

ndarray

plane_points_from_states(states, *, section_coord)[source]

Parameters:

states (ndarray)
section_coord (str)

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:

points (ndarray)
states (ndarray)
labels (Tuple[str, str])
times (ndarray | None)

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 (str)
energy (float)
dt (float)
n_iter (int)
n_workers (int)
jac_H (List[ndarray])
H_blocks (List[ndarray])
clmo_table (List[ndarray])
max_steps (int)
method (str)
order (int)
c_omega_heuristic (float)
solve_missing_coord_fn (Callable[[str, dict[str, float]], float | None] | None)
find_turning_fn (Callable[[str], float] | None)

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

max_steps

Maximum number of integration steps per trajectory.

Type:: int

method

Integration method (‘fixed’, ‘adaptive’, or ‘symplectic’).

Type:: str

order

Integration order for RK methods.

Type:: int

c_omega_heuristic

Heuristic parameter for symplectic integration.

Type:: float

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]

max_steps: int = 2000

method: str = 'adaptive'

order: int = 8

c_omega_heuristic: float = 20.0

solve_missing_coord_fn: Callable[[str, dict[str, float]], float | None] | None = None

find_turning_fn: Callable[[str], float] | None = None