Core Poincare Infrastructure

The core module provides the fundamental infrastructure for Poincare return map computation.

Backend Classes

Defines the backend for Poincare map computation.

class hiten.algorithms.poincare.core._ReturnMapBackend[source]

Bases: _HitenBaseBackend

Abstract base class for Poincare return map backends.

This class defines the interface that all concrete return map backends must implement. It provides common functionality for numerical integration, section crossing detection, and root finding.

Parameters:

forward (int, default=1) – Integration direction (1 for forward, -1 for backward).
method ({'fixed', 'symplectic', 'adaptive'}, default='adaptive') – Integration method to use.
order (int, default=8) – Integration order for Runge-Kutta methods.
pre_steps (int, default=1000) – Number of pre-integration steps for trajectory stabilization.
refine_steps (int, default=3000) – Number of refinement steps for root finding.
bracket_dx (float, default=1e-10) – Initial bracket size for root finding.
max_expand (int, default=500) – Maximum bracket expansion iterations.

Notes

Subclasses must implement the step_to_section method to define how trajectories are integrated from one section crossing to the next. The backend handles the numerical integration and section crossing detection, while the engine layer manages iteration, caching, and parallel processing.

All time units are in nondimensional units unless otherwise specified.

abstractmethod run(seeds, *, dt=0.01, forward=1, method='adaptive', order=8, pre_steps=1000, refine_steps=3000, bracket_dx=1e-10, max_expand=500)[source]

Propagate seeds to the next surface crossing.

This abstract method must be implemented by concrete backends to define how trajectories are integrated from initial seeds to their next intersection with the Poincare section.

Parameters:

seeds (ndarray, shape (m, n)) – Array of initial states. The shape depends on the backend: - Center manifold backends: (m, 4) for [q2, p2, q3, p3] - Full state backends: (m, 6) for [q1, q2, q3, p1, p2, p3]
dt (float, default=1e-2) – Integration time step (nondimensional units). Meaningful for Runge-Kutta methods, ignored for adaptive methods.
forward (int)
method (Literal['fixed', 'adaptive', 'symplectic'])
order (int)
pre_steps (int)
refine_steps (int)
bracket_dx (float)
max_expand (int)

Returns:

points (ndarray, shape (k, 2)) – Crossing coordinates in the section plane.
states (ndarray, shape (k, n)) – State representation at the crossings. Shape matches input seeds but may have fewer rows if some trajectories don’t reach the section.

Return type:

tuple[ndarray, ndarray]

Notes

This method performs a single step of the Poincare map, taking initial conditions and returning their next intersection with the section. The engine layer handles iteration and caching.

Engine Classes

Defines the engine for Poincare map computation.

class hiten.algorithms.poincare.core._ReturnMapEngine[source]

Bases: _HitenBaseEngine[ProblemT, ResultT, OutputsT], Generic[ProblemT, ResultT, OutputsT]

Abstract base class for Poincare return map engines.

This class defines the interface that all concrete return map engines must implement. It coordinates backends and seeding strategies to compute complete return maps efficiently.

Parameters:

backend (_ReturnMapBackend) – The backend for numerical integration and section crossing detection.
seed_strategy (_SeedingStrategyBase) – The seeding strategy for generating initial conditions on the section plane.
map_config (_ReturnMapBaseConfig) – Configuration object containing engine parameters such as iteration count, time step, and worker count.

_backend

The numerical integration backend.

Type:: _ReturnMapBackend

_strategy

The seeding strategy for initial conditions.

Type:: _SeedingStrategyBase

_map_config

The engine configuration.

Type:: _ReturnMapBaseConfig

_n_iter

Number of return map iterations to compute.

Type:: int

_dt

Integration time step (nondimensional units).

Type:: float

_n_workers

Number of parallel workers for computation.

Type:: int

_section_cache

Cache for the computed section to avoid redundant computation.

Type:: _Section or None

Notes

The engine coordinates the computation process by: 1. Using the seeding strategy to generate initial conditions 2. Using the backend to integrate trajectories and find section crossings 3. Iterating the process to build up the complete return map 4. Managing caching and parallel computation for efficiency

All time units are in nondimensional units unless otherwise specified.

abstractmethod solve(problem)[source]

Compute and return the section (or Results that inherit _Section).

Return type:: _Section

Configuration Classes

Defines the base configuration for Poincare map computation.

class hiten.algorithms.poincare.core._ReturnMapBaseConfig[source]

Bases: ABC

Base configuration for Poincare return map implementations.

This abstract base class defines the minimal configuration parameters that are universally applicable to all return map implementations. It contains only orchestration fields that control the overall behavior of the computation.

Parameters:: n_workers (int or None, default=None) – Number of parallel workers for computation. If None, uses the default number of workers (typically the number of CPU cores).

Notes

This class serves as the base for all return map configurations. Concrete implementations should inherit from this class and add their specific configuration parameters.

All time units are in nondimensional units unless otherwise specified.

n_workers: int | None = None

Defines the configuration for integration.

class hiten.algorithms.poincare.core._IntegrationConfig[source]

Bases: ABC

Configuration for numerical integration parameters.

This abstract base class defines the integration-related configuration parameters used by propagating backends and engines for numerical integration of trajectories.

Parameters:

dt (float, default=1e-2) – Integration time step (nondimensional units). Smaller values provide higher accuracy but require more computation.
method ({'fixed', 'adaptive', 'symplectic'}, default='fixed') – Integration method to use: - ‘fixed’: Fixed-step Runge-Kutta methods - ‘symplectic’: Symplectic integrators (preserves Hamiltonian structure) - ‘adaptive’: Adaptive step size methods
order (int, default=8) – Integration order for Runge-Kutta methods. Higher orders provide better accuracy but require more function evaluations.
c_omega_heuristic (float, default=20.0) – Heuristic parameter for adaptive integration, controlling the relationship between step size and frequency content.
max_steps (int)

Notes

All time units are in nondimensional units unless otherwise specified.

dt: float = 0.01

method: Literal['fixed', 'adaptive', 'symplectic'] = 'fixed'

order: int = 8

c_omega_heuristic: float | None = 20.0

max_steps: int = 2000

Defines the configuration for iteration.

class hiten.algorithms.poincare.core._IterationConfig[source]

Bases: ABC

Configuration for iteration control in return map computation.

This abstract base class defines the iteration-related configuration parameters that control how many return map steps are computed for each initial condition.

Parameters:: n_iter (int, default=40) – Number of return map iterations to compute for each initial condition. More iterations provide a more complete picture of the dynamics but require more computation.

Notes

The number of iterations determines how many times each trajectory is mapped back to the section. This parameter should be chosen based on the desired resolution of the return map and the computational resources available.

For chaotic systems, more iterations may be needed to reveal the full structure of the attractor.

n_iter: int = 40

Defines the configuration for seeding.

class hiten.algorithms.poincare.core._SeedingConfig[source]

Bases: ABC

Configuration for seeding strategies in return map computation.

This abstract base class defines the seeding-related configuration parameters that control how initial conditions are generated for return map computation.

Parameters:: n_seeds (int, default=20) – Number of initial seeds to generate for return map computation. More seeds provide better coverage of the section plane but require more computation.

Notes

The seeding strategy determines how initial conditions are distributed on the section plane. The number of seeds affects the resolution and coverage of the computed return map. More seeds provide better statistical coverage but increase computational cost.

The choice of seeding strategy depends on the specific dynamical system and the desired analysis goals.

n_seeds: int = 20

Defines the configuration for refinement.

Defines the configuration for Poincare map computation.

class hiten.algorithms.poincare.core._ReturnMapConfig[source]

Bases: _ReturnMapBaseConfig, _IntegrationConfig, _RefineConfig, _IterationConfig, _SeedingConfig

Complete configuration for Poincare return map computation.

This class combines all configuration mixins into a single comprehensive configuration class. It inherits from all the abstract configuration base classes, providing a complete set of parameters for return map computation.

This class serves as a backward-compatible umbrella configuration that includes all available parameters for return map computation.

Notes

This class inherits all parameters from: - _ReturnMapBaseConfig: Base orchestration parameters - _IntegrationConfig: Numerical integration parameters - _RefineConfig: Refinement parameters - _IterationConfig: Iteration control parameters - _SeedingConfig: Seeding strategy parameters

All time units are in nondimensional units unless otherwise specified.

Parameters:

n_seeds (int)
n_iter (int)
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)
dt (float)
method (Literal['fixed', 'adaptive', 'symplectic'])
order (int)
c_omega_heuristic (float | None)
max_steps (int)
n_workers (int | None)

Event Classes

Defines the event for surface computation.

class hiten.algorithms.poincare.core._SurfaceEvent[source]

Bases: ABC

Abstract base class for Poincare section surface events.

This abstract base class defines the interface for surface events that detect trajectory crossings through Poincare sections. Concrete subclasses specify a signed scalar function g(x) whose zeros define the hypersurface in phase space that serves as the Poincare section.

The class stores the direction of admissible crossings to avoid duplicating this logic in the generic crossing detection code.

Parameters:: direction ({1, -1, None}, default=None) – Select which zero-crossings are accepted: - 1: negative -> positive sign change - -1: positive -> negative sign change - None: either direction

Notes

The surface is defined by the equation g(x) = 0, where g(x) is a signed scalar function. The direction parameter controls which sign changes are considered valid crossings.

All time units are in nondimensional units unless otherwise specified.

abstractmethod value(state)[source]

Return the value of the surface function g(state).

Parameters:: state (ndarray, shape (n,)) – State vector at which to evaluate the surface function.
Returns:: The value of g(state), where g(x) = 0 defines the section.
Return type:: float

Notes

This method must be implemented by concrete subclasses to define the specific surface function. The sign of the returned value determines which side of the surface the state is on.

is_crossing(prev_val, curr_val)[source]

Check if a trajectory has crossed the section.

Parameters:

prev_val (float) – Previous value of the surface function.
curr_val (float) – Current value of the surface function.

Returns:

True if the trajectory has crossed the section in the requested direction, False otherwise.

Return type:

bool

Notes

This method implements the crossing detection logic based on the direction parameter. It checks for sign changes that indicate a trajectory has passed through the section.

property direction: Literal[1, -1, None]

Get the crossing direction for this surface event.

Returns:: The crossing direction: - 1: negative -> positive sign change - -1: positive -> negative sign change - None: either direction
Return type:: {1, -1, None}

Notes

This property returns the direction parameter that was set during initialization. It controls which sign changes are considered valid crossings.

Defines the event for plane computation.

class hiten.algorithms.poincare.core._PlaneEvent[source]

Bases: _SurfaceEvent

Concrete surface event representing a hyperplane coord = value.

This class implements a surface event for hyperplanes defined by setting a single coordinate to a constant value. It supports both coordinate name-based and index-based specification.

Parameters:

coord (str or int) – Coordinate identifier. A string is resolved via a built-in name-to-index map (supports both synodic and center manifold names such as ‘x’, ‘q3’, ‘p2’, etc.). An int is interpreted directly as an index into the state vector.
value (float, default=0.0) – Plane offset along the chosen coordinate (nondimensional units).
direction ({1, -1, None}, optional) – Crossing direction filter, passed to the parent class. Controls which sign changes are considered valid crossings.

Notes

The surface is defined by the equation coord - value = 0. The coordinate can be specified either by name (using the built-in mapping) or by direct index into the state vector.

Supported coordinate names: - Synodic frame: ‘x’, ‘y’, ‘z’, ‘vx’, ‘vy’, ‘vz’ - Center manifold: ‘q2’, ‘p2’, ‘q3’, ‘p3’

All time units are in nondimensional units unless otherwise specified.

value(state)[source]

Return the value of the plane function coord - value.

Parameters:: state (ndarray, shape (n,)) – State vector at which to evaluate the plane function.
Returns:: The value of coord - value, where coord is the specified coordinate and value is the plane offset.
Return type:: float

Notes

This method implements the surface function for a hyperplane. The sign of the returned value indicates which side of the plane the state is on.

property index: int

Get the state vector index of the plane coordinate.

Returns:: The index into the state vector for the coordinate that defines this plane.
Return type:: int

Notes

This property returns the resolved index, whether it was specified directly or resolved from a coordinate name.

property offset: float

Get the plane offset value.

Returns:: The offset value along the chosen coordinate (nondimensional units).
Return type:: float

Notes

This property returns the value that was set during initialization. The plane is defined by coord = offset.

property name: str | None

Return the original coordinate name if provided, else None.

Notes

This can be used by fast-path backends to detect simple synodic planes like ‘x’, ‘y’, or ‘z’.

Interface Classes

Defines the interface for section computation.

class hiten.algorithms.poincare.core._SectionInterface[source]: Bases: ABC

Defines the interface for Poincare map computation.

Strategy Classes

Defines the base class for seeding strategies.

class hiten.algorithms.poincare.core._SeedingStrategyBase[source]

Bases: ABC

Abstract base class for Poincare section seeding strategies.

This abstract base class defines the interface that all concrete seeding strategies must implement. It provides common functionality for configuration management and defines the contract for seed generation.

Parameters:

section_cfg (_SectionInterface) – Section configuration containing section coordinate and plane coordinate information.
map_cfg (_SeedingConfig) – Seeding configuration containing parameters such as the number of seeds to generate.

_section_cfg

The section configuration.

Type:: _SectionInterface

_map_cfg

The seeding configuration.

Type:: _SeedingConfig

_cached_limits

Class-level cache for computed limits, keyed by (h0, n_seeds) to avoid redundant computation.

Type:: dict[tuple[float, int], list[float]]

Notes

Concrete subclasses must implement the generate method to define how initial conditions are generated. The base class provides convenient access to configuration parameters and common functionality.

All time units are in nondimensional units unless otherwise specified.

property config: _SeedingConfig

Get the map configuration.

Returns:: The map configuration containing global parameters.
Return type:: _SeedingConfig

Notes

This property provides access to the map configuration which contains information about the global parameters used for seeding.

property map_config: _ReturnMapConfig

Get the seeding configuration.

Returns:: The seeding configuration containing parameters such as the number of seeds to generate.
Return type:: _MapConfig

Notes

This property provides access to the seeding configuration that controls the seed generation process.

property n_seeds: int

Get the number of seeds to generate.

Returns:: The number of seeds to generate as specified in the seeding configuration.
Return type:: int

Notes

This property provides convenient access to the number of seeds parameter from the configuration.

property plane_coords: Tuple[str, str]

Get the plane coordinate labels.

Returns:: Tuple of two coordinate labels that define the section plane (e.g., (“q2”, “p2”)).
Return type:: tuple[str, str]

Notes

This property provides access to the plane coordinate labels from the section configuration.

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

Generate initial conditions for the Poincare section.

This abstract method must be implemented by concrete subclasses to define how initial conditions are generated for the specific seeding strategy.

Parameters:

h0 (float) – Energy level for the center manifold (nondimensional units).
H_blocks (Any) – Hamiltonian polynomial blocks for energy computation.
clmo_table (Any) – CLMO (Center Manifold Local Orbit) table for polynomial evaluation and coordinate transformation.
solve_missing_coord_fn (callable) – Function to solve for the missing coordinate given constraints and energy level.
find_turning_fn (callable) – Function to find turning points for a given coordinate and energy level.

Returns:

List of initial conditions, each represented as a tuple of four coordinates (q2, p2, q3, p3) in the center manifold coordinate system.

Return type:

list[tuple[float, float, float, float]]

Notes

This method must be implemented by concrete subclasses to define the specific seeding logic. The implementation should generate initial conditions that are likely to intersect with the Poincare section.

The returned coordinates are in the center manifold coordinate system and should satisfy the energy constraint H(q,p) = h0.

All coordinates are in nondimensional units.

__call__(**kwargs)[source]

Call the seeding strategy with the given parameters.

Parameters:: **kwargs – Keyword arguments passed to the generate method.
Returns:: The result of calling the generate method with the provided parameters.
Return type:: list[tuple[float, float, float, float]]

Notes

This method provides a callable interface to the seeding strategy, allowing it to be used as a function. It simply delegates to the generate method.

Defines the protocol for seeding strategies.

class hiten.algorithms.poincare.core._SeedingProtocol[source]

Bases: Protocol

Protocol for seeding strategies in Poincare return map computation.

This protocol defines the interface that all seeding strategies must implement. Seeding strategies are responsible for generating initial conditions whose trajectories will be propagated until they reach the Poincare section defined by a surface event.

The concrete strategy decides how seeds are distributed (axis-aligned rays, random clouds, center manifold turning-point logic, etc.) but not how they are propagated - that is handled by the return map engine.

The interface is intentionally minimal so that existing center manifold strategies can be adapted with a thin wrapper rather than rewritten.

Notes

Seeding strategies play a crucial role in determining the coverage and resolution of the computed return map. Different strategies are appropriate for different dynamical systems and analysis goals.

The protocol supports both problem-agnostic and domain-specific seeding strategies through the flexible parameter system.

All time units are in nondimensional units unless otherwise specified.

generate(*, dynsys, surface, n_seeds, **kwargs)[source]

Generate initial state vectors for return map computation.

This method generates a list of initial conditions that will be propagated until they intersect with the specified Poincare section. The distribution strategy is determined by the concrete implementation.

Parameters:

dynsys (_DynamicalSystemProtocol) – The dynamical system that will be used for propagation. The seeding strategy may use system properties to inform the distribution of initial conditions.
surface (_SurfaceEvent) – Target Poincare section. The generator may use the section definition to align seeds conveniently with the crossing plane or to ensure good coverage of the section.
n_seeds (int) – Desired number of seeds to generate. The actual number returned may be fewer if the strategy cannot generate the requested number (e.g., due to constraints or available space).
**kwargs – Extra implementation-specific parameters. Common examples: - energy level for center manifold seeds - coordinate ranges for random distributions - axis specifications for aligned distributions The core engine passes only dynsys, surface, and n_seeds; domain-specific wrappers supply additional parameters.

Returns:

List of initial state vectors, each with shape (n,) where n is the dimension of the state space. The list may contain fewer than n_seeds elements if the strategy cannot generate the requested number.

Return type:

list[ndarray]

Notes

The seeding strategy should generate initial conditions that are likely to intersect with the specified section. The distribution should provide good coverage of the relevant phase space region for the intended analysis.

Different strategies may use different approaches: - Random sampling for statistical coverage - Grid-based sampling for systematic coverage - Center manifold methods for Hamiltonian systems - Axis-aligned distributions for specific coordinate planes

All state vectors should be in the same coordinate system as expected by the dynamical system.

Type Classes

The section classes are used to store the results of the Poincare map computation.

The section hit class is used to store the results of a single trajectory-section intersection.

class hiten.algorithms.poincare.core._SectionHit[source]

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

The map results class is used to store the results of the Poincare map computation.