Poincare Types

The types module provides core data structures and result containers for Poincare return map computation.

Core Types

class hiten.algorithms.poincare.core.types._Section

Bases: object

Immutable container for a single 2D return map slice.

This class holds the data for a computed Poincare section, including the intersection points, state vectors, axis labels, and optional integration times.

Parameters:

• points (ndarray, shape (n, 2)) – Array of 2D intersection points in the section plane.

• states (ndarray, shape (n, k)) – Array of state vectors at the intersection points. The number of columns k depends on the backend implementation.

• labels (tuple[str, str]) – Labels for the two axes in the section plane (e.g., (“q2”, “p2”)).

• times (ndarray, optional, shape (n,)) – Array of absolute integration times at each intersection point. If None, times are not available.

class hiten.algorithms.poincare.core.types._SectionHit

Bases: NamedTuple

Container for a single trajectory-section intersection.

This named tuple holds all the information about a single intersection between a trajectory and a Poincare section. It provides both the full state vector and the 2D projection for efficient access.

Parameters:

• time (float) – Absolute integration time (nondimensional units), signed according to propagation direction.

• state (ndarray, shape (n,)) – Full state vector at the crossing (immutable copy).

• point2d (ndarray, shape (2,)) – 2D coordinates of the point in the section plane (e.g., (q2, p2) or (x, x_dot)). Stored separately so callers do not have to re-project the full state vector.

• trajectory_index (int) – Index of the trajectory that produced this intersection within the input trajectory list.

Notes

This container is immutable and provides efficient access to both the full state information and the 2D projection. The 2D coordinates are pre-computed to avoid repeated projection operations.

All time units are in nondimensional units unless otherwise specified.

time: float

Alias for field number 0

state: ndarray

Alias for field number 1

point2d: ndarray

Alias for field number 2

trajectory_index: int

Alias for field number 3

class hiten.algorithms.poincare.core.types._MapResults

Bases: _Section

Base results object for Poincare maps.

Acts like _Section while serving as a common base for module-specific results (e.g., CenterManifoldMapResults, SynodicMapResults).

Parameters:

• points (ndarray)

• states (ndarray)

• labels (tuple[str, str])

• times (ndarray | None)

Center Manifold Types

class hiten.algorithms.poincare.centermanifold.types.CenterManifoldMapResults

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)

Parameters:

axes (Tuple[str, str])

Return type:

ndarray

class hiten.algorithms.poincare.centermanifold.types._CenterManifoldMapProblem

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

• 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

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

Synodic Types

class hiten.algorithms.poincare.synodic.types.SynodicMapResults

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

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