Synodic Poincare Maps

The synodic module provides synodic Poincare map computation for precomputed trajectories.

Main Classes

class hiten.algorithms.poincare.synodic.SynodicMapPipeline[source]

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

User-facing interface for synodic Poincare section detection.

This class provides a facade that mirrors the API of other return-map modules while specializing in synodic Poincare section detection on precomputed trajectories. It does not propagate trajectories; callers supply them explicitly through various input methods.

Parameters:

map_cfg (_SynodicMapConfig, optional) – Configuration object containing detection parameters, section geometry, and refinement settings. If None, uses default configuration.
config (_SynodicMapConfig)
engine (_SynodicEngine)
interface (_SynodicInterface)
backend (_SynodicDetectionBackend)

config

The map configuration object.

Type:: _SynodicMapConfig

_engine

The engine that coordinates detection and refinement.

Type:: _SynodicEngine

_sections

Cache of computed sections keyed by section parameters.

Type:: dict[str, _Section]

_section

The most recently computed section.

Type:: _Section or None

Notes

This class implements a facade pattern that provides a consistent interface for synodic Poincare section detection while hiding the complexity of the underlying detection and refinement algorithms.

The class supports multiple input methods: - Custom trajectories via from_trajectories() - Periodic orbits via from_orbit() - Manifold structures via from_manifold()

All time units are in nondimensional units unless otherwise specified.

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 (_SynodicMapConfig) – Configuration object for the synodic map.
interface (_SynodicInterface, optional) – Interface object for the synodic map. If None, uses the default _SynodicInterface.
backend (_SynodicDetectionBackend, optional) – Backend instance for the synodic map. If None, uses the default _SynodicDetectionBackend.

Returns:

A synodic map facade instance with a default engine injected.

Return type:

SynodicMapPipeline

generate(domain_obj, override=False, *, section_axis=None, section_offset=None, section_normal=None, plane_coords=None, interp_kind=None, newton_max_iter=4, dedup_point_tol=None, max_hits_per_traj=None, segment_refine=None, tol_on_surface=None, dedup_time_tol=None, n_workers=None, direction=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_axis (str | int | None)
section_offset (float)
section_normal (Sequence[float] | None)
plane_coords (Tuple[str, str])
interp_kind (Literal['linear', 'cubic'])
newton_max_iter (int)
dedup_point_tol (float)
max_hits_per_traj (int | None)
segment_refine (int)
tol_on_surface (float)
dedup_time_tol (float)
n_workers (int | None)
direction (Literal[1, -1, None] | None)

Return type:

SynodicMapResults

Configuration Classes

class hiten.algorithms.poincare.synodic._SynodicMapConfig[source]

Bases: _ReturnMapBaseConfig, _RefineConfig

Configuration for synodic Poincare map detection and refinement.

This configuration class extends the base return map configuration with specialized parameters for synodic Poincare section detection on precomputed trajectories. It includes both geometric parameters for section definition and numerical parameters for detection algorithms.

Parameters:

section_axis (str or int or None, default "x") – Axis for section definition (ignored if section_normal provided). Can be a string (“x”, “y”, “z”, “vx”, “vy”, “vz”) or integer index.
section_offset (float, default 0.0) – Offset for the section hyperplane (nondimensional units).
section_normal (sequence of float or None, optional) – Explicit normal vector for section definition (length 6). If provided, overrides section_axis. Must be in synodic coordinates.
plane_coords (tuple[str, str], default ("y", "vy")) – Coordinate labels for 2D projection of section points.
Parameters (Detection)
-------------------
interp_kind ({"linear", "cubic"}, default "linear") – Interpolation method for crossing refinement. “cubic” provides higher accuracy but requires more computation.
segment_refine (int, default 0) – Number of refinement segments for dense crossing detection. Higher values detect more crossings but increase computation.
tol_on_surface (float, default 1e-12) – Tolerance for considering a point to be on the surface.
dedup_time_tol (float, default 1e-9) – Time tolerance for deduplicating nearby crossings.
dedup_point_tol (float, default 1e-12) – Point tolerance for deduplicating nearby crossings.
max_hits_per_traj (int or None, default None) – Maximum number of hits per trajectory (None for unlimited).
newton_max_iter (int, default 4) – Maximum Newton iterations for root refinement.
n_workers (int | None)
direction (Literal[1, -1, None] | None)

Notes

This configuration class provides comprehensive control over synodic Poincare section detection. The geometric parameters define the section hyperplane, while the detection parameters control the numerical algorithms used for crossing detection and refinement.

The class automatically sets compute_on_init = False since synodic maps require precomputed trajectories to be supplied explicitly via from_orbit(), from_manifold(), or from_trajectories().

All tolerances and offsets are in nondimensional units unless otherwise specified.

section_axis: str | int | None = 'x'

section_offset: float = 0.0

section_normal: Sequence[float] | None = None

plane_coords: Tuple[str, str] = ('y', 'vy')

direction: Literal[1, -1, None] | None = None

Backend Classes

class hiten.algorithms.poincare.synodic.backend._SynodicDetectionBackend[source]

Bases: _ReturnMapBackend

Backend for synodic Poincare section detection on precomputed trajectories.

This backend performs detection and refinement on precomputed trajectory data rather than integrating from initial conditions. It implements advanced numerical techniques for high-accuracy crossing detection in the synodic frame of the circular restricted three-body problem.

Unlike propagating backends, this backend does not integrate forward from seeds. It performs section detection on (time, state) samples supplied by the engine and returns crossings with refined hit states and 2D projections.

Notes

This backend is optimized for synodic Poincare sections and provides high-accuracy detection using cubic Hermite interpolation and Newton refinement. It supports both standard and dense crossing detection modes.

All time units are in nondimensional units unless otherwise specified.

detect_on_trajectory(times, states, *, normal, offset=0.0, plane_coords=('y', 'vy'), interp_kind='linear', segment_refine=0, tol_on_surface=1e-12, dedup_time_tol=1e-09, dedup_point_tol=1e-12, max_hits_per_traj=None, newton_max_iter=4, direction=None, trajectory_index=0)[source]

Detect crossings on a single trajectory.

Parameters:

times (ndarray, shape (n,)) – Array of time points (nondimensional units).
states (ndarray, shape (n, m)) – Array of state vectors at each time point.
normal (array_like, shape (6,)) – Hyperplane normal vector in synodic coordinates.
offset (float, default 0.0) – Hyperplane offset value (nondimensional units).
plane_coords (tuple[str, str], default ("y", "vy")) – Names of the 2D axes for section point projection.
interp_kind ({"linear", "cubic"}, default "linear") – Interpolation method for crossing refinement.
segment_refine (int, default 0) – Number of refinement segments for dense crossing detection.
tol_on_surface (float, default 1e-12) – Tolerance for considering a point to be on the surface.
dedup_time_tol (float, default 1e-9) – Time tolerance for deduplicating nearby crossings.
dedup_point_tol (float, default 1e-12) – Point tolerance for deduplicating nearby crossings.
max_hits_per_traj (int or None, default None) – Maximum number of hits per trajectory (None for unlimited).
newton_max_iter (int, default 4) – Maximum Newton iterations for root refinement.
direction ({1, -1, None}, optional) – Crossing direction filter. If None, no direction filtering is applied.
trajectory_index (int, default 0) – Index of this trajectory within the input trajectory list.

Returns:

List of detected section hits, ordered by time and deduplicated.

Return type:

list[_SectionHit]

Notes

This method performs crossing detection on a single trajectory using the specified detection settings. It supports both standard and dense detection modes and applies the appropriate refinement method (linear or cubic) based on the configuration.

The method automatically handles deduplication and ordering of the detected crossings.

run(trajectories, *, normal, trajectory_indices, offset=0.0, plane_coords=('y', 'vy'), interp_kind='linear', segment_refine=0, tol_on_surface=1e-12, dedup_time_tol=1e-09, dedup_point_tol=1e-12, max_hits_per_traj=None, newton_max_iter=4, direction=None)[source]

Detect crossings on a batch of trajectories.

Parameters:

trajectories (sequence of tuple[ndarray, ndarray]) – Sequence of (times, states) tuples for each trajectory.
normal (array_like, shape (6,)) – Hyperplane normal vector in synodic coordinates.
offset (float, default 0.0) – Hyperplane offset value (nondimensional units).
plane_coords (tuple[str, str], default ("y", "vy")) – Names of the 2D axes for section point projection.
interp_kind ({"linear", "cubic"}, default "linear") – Interpolation method for crossing refinement.
segment_refine (int, default 0) – Number of refinement segments for dense crossing detection.
tol_on_surface (float, default 1e-12) – Tolerance for considering a point to be on the surface.
dedup_time_tol (float, default 1e-9) – Time tolerance for deduplicating nearby crossings.
dedup_point_tol (float, default 1e-12) – Point tolerance for deduplicating nearby crossings.
max_hits_per_traj (int or None, default None) – Maximum number of hits per trajectory (None for unlimited).
newton_max_iter (int, default 4) – Maximum Newton iterations for root refinement.
direction ({1, -1, None}, optional) – Crossing direction filter. If None, no direction filtering is applied.
trajectory_indices (sequence of int) – Global trajectory indices corresponding to each trajectory in the trajectories sequence. Used to label section hits with their originating trajectory index.

Returns:

List of section hit lists, one for each trajectory.

Return type:

list[list[_SectionHit]]

Notes

This method processes multiple trajectories in batch, applying the same detection settings to each trajectory. It’s useful for processing multiple trajectories with the same section configuration.

Each trajectory is processed independently, and the results are returned as a list of lists.

Engine Classes

class hiten.algorithms.poincare.synodic.engine._SynodicEngine[source]

Bases: _ReturnMapEngine

Engine for synodic Poincare section detection on precomputed trajectories.

This engine coordinates the detection and refinement of synodic Poincare sections across multiple precomputed trajectories. It extends the base return map engine to provide specialized functionality for synodic sections while reusing the worker management and caching infrastructure.

Parameters:

backend (_SynodicDetectionBackend) – The detection backend for synodic sections.
seed_strategy (_NoOpStrategy) – The seeding strategy (no-op for synodic maps).
map_config (_SynodicEngineInterface) – The configuration adapter for the engine.
interface (_SynodicInterface)

_trajectories

The precomputed trajectories to analyze.

Type:: sequence of tuple[ndarray, ndarray] or None

_direction

The crossing direction filter for detection.

Type:: int or None

Notes

This engine provides parallel processing capabilities for efficient batch detection across multiple trajectories. It automatically chooses between serial and parallel processing based on the number of workers and trajectories.

The engine caches computed sections to avoid redundant computation and provides a fluent interface for setting trajectories and computing sections.

All time units are in nondimensional units unless otherwise specified.

solve(problem)[source]

Compute the synodic Poincare section from the composed problem.

Parameters:: problem (_SynodicMapProblem)
Return type:: SynodicMapResults

Interface Classes

class hiten.algorithms.poincare.synodic.interfaces._SynodicInterface[source]

Bases: _PoincareBaseInterface[_SynodicMapConfig, _SynodicMapProblem, SynodicMapResults, Tuple[ndarray, ndarray, 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.

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_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

Strategy Classes

class hiten.algorithms.poincare.synodic.strategies._NoOpStrategy[source]

Bases: _SeedingStrategyBase

No-operation seeding strategy for synodic Poincare maps.

This class implements a no-operation seeding strategy that serves as a placeholder to satisfy the engine interface requirements. Since synodic Poincare maps operate on precomputed trajectories rather than generating initial conditions, this strategy raises NotImplementedError when called.

Parameters:: map_cfg (_SynodicMapConfig) – The map configuration (unused).

Notes

This strategy is required by the engine interface but is not used in practice. Synodic Poincare maps receive precomputed trajectories through the engine’s set_trajectories method rather than generating initial conditions from seeds.

The strategy clearly indicates through NotImplementedError that seed generation is not applicable for synodic maps, providing a clear error message if the method is accidentally called.

All time units are in nondimensional units unless otherwise specified.

generate(*, h0, H_blocks, clmo_table, solve_missing_coord_fn, find_turning_fn)[source]

Generate seeds (not implemented for synodic maps).

Parameters:

h0 (float) – Initial energy value (unused).
H_blocks (array_like) – Energy blocks (unused).
clmo_table (array_like) – CLMO table (unused).
solve_missing_coord_fn (callable) – Function to solve missing coordinates (unused).
find_turning_fn (callable) – Function to find turning points (unused).

Raises:

NotImplementedError – Always raised since synodic maps do not generate seeds.

Notes

This method is required by the base seeding strategy interface but is not used for synodic maps. It raises NotImplementedError to clearly indicate that seed generation is not applicable.

Synodic maps operate on precomputed trajectories rather than generating initial conditions from seeds.

Event Classes

class hiten.algorithms.poincare.synodic.events._AffinePlaneEvent[source]

Bases: _SurfaceEvent

Affine hyperplane event in the synodic frame.

This class defines a Poincare section surface as an affine hyperplane in the 6D state space of the circular restricted three-body problem. It extends the base surface event to provide specialized functionality for synodic Poincare sections with arbitrary hyperplane orientations.

The section is defined by the zero level-set of:

g(state) = n * state - c = 0

where state = (x, y, z, vx, vy, vz) and n is a 6D normal vector.

Parameters:

normal (array_like, shape (6,)) – Hyperplane normal in synodic coordinates (nondimensional units). The vector is used as-is (no normalization) so its scale must be consistent with the offset parameter.
offset (float, default 0.0) – Hyperplane offset along the normal (nondimensional units). The section is defined by n * state = offset.
direction ({1, -1, None}, optional) – Crossing direction filter passed to the base surface event. If None, no direction filtering is applied.

Notes

This class provides a flexible way to define Poincare sections in the synodic frame. Unlike axis-aligned planes, it allows arbitrary orientations in the 6D state space, enabling complex section geometries.

The class performs validation to ensure the normal vector has the correct dimensions and contains only finite values.

All geometric parameters are in nondimensional units unless otherwise specified.

value(state)[source]

Compute the surface function value for a given state.

Parameters:: state (ndarray, shape (6,)) – State vector in synodic coordinates (nondimensional units).
Returns:: The surface function value g(state) = n * state - c.
Return type:: float

Notes

This method computes the surface function value for the given state vector. The function returns zero when the state is on the hyperplane, positive when on one side, and negative when on the other side.

The computation uses the dot product of the normal vector with the state vector, minus the offset.

property normal: ndarray

Get the hyperplane normal vector.

Returns:: The hyperplane normal vector in synodic coordinates.
Return type:: ndarray, shape (6,)

property offset: float

Get the hyperplane offset value.

Returns:: The hyperplane offset value (nondimensional units).
Return type:: float

classmethod axis_plane(coord, *, c=0.0, direction=None)[source]

Convenience constructor for axis-aligned planes.

Parameters:

coord (str or int) – Coordinate name or index for the plane normal. String names: “x”, “y”, “z”, “vx”, “vy”, “vz” Integer indices: 0-5 corresponding to the coordinates above.
c (float, default 0.0) – Plane offset value (nondimensional units).
direction ({1, -1, None}, optional) – Crossing direction filter for the surface event.

Returns:

An affine plane event with axis-aligned normal.

Return type:

_AffinePlaneEvent

Raises:

ValueError – If coordinate name is unknown or index is out of range.

Examples

Create a plane at x = 1 - mu:

>>> plane = hiten.algorithms.poincare.synodic.events._AffinePlaneEvent.axis_plane("x", c=1-mu)

Create a plane at y = 0:

>>> plane = hiten.algorithms.poincare.synodic.events._AffinePlaneEvent.axis_plane(1, c=0.0)

Notes

This class method provides a convenient way to create axis-aligned planes without manually constructing the normal vector. It creates a normal vector with a 1 in the specified coordinate position and 0 elsewhere.

All geometric parameters are in nondimensional units.

Type Classes

class hiten.algorithms.poincare.synodic.types.SynodicMapResults[source]

Bases: _MapResults

User-facing results for synodic sections (extends _MapResults).

Parameters:

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

class hiten.algorithms.poincare.synodic.types._SynodicMapProblem[source]

Bases: object

Problem definition for a synodic section run.

Parameters:

plane_coords (Tuple[str, str])
direction (int | None)
n_workers (int)
normal (Sequence[float] | ndarray)
offset (float)
trajectories (Sequence[tuple[ndarray, ndarray]] | None)
interp_kind (Literal['linear', 'cubic'])
segment_refine (int)
tol_on_surface (float)
dedup_time_tol (float)
dedup_point_tol (float)
max_hits_per_traj (int | None)
newton_max_iter (int)

plane_coords

Labels of the plane projection axes.

Type:: tuple[str, str]

direction

Crossing direction filter.

Type:: {1, -1, None}

n_workers

Parallel worker count to use in the engine.

Type:: int

trajectories

Optional pre-bound trajectories.

Type:: Sequence[tuple[np.ndarray, np.ndarray]] | None

normal

Normal vector defining the section plane.

Type:: Sequence[float] | np.ndarray

offset

Offset distance for the section plane.

Type:: float

map_cfg

Map configuration containing detection parameters.

Type:: _SynodicMapConfig

plane_coords: Tuple[str, str]

direction: int | None

n_workers: int

normal: Sequence[float] | ndarray

offset: float

trajectories: Sequence[tuple[ndarray, ndarray]] | None

interp_kind: Literal['linear', 'cubic']

segment_refine: int

tol_on_surface: float

dedup_time_tol: float

dedup_point_tol: float

max_hits_per_traj: int | None

newton_max_iter: int