Poincare Strategies

The strategies modules provide different computational approaches for Poincare return map computation.

Core Strategies

class hiten.algorithms.poincare.core.strategies._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.

Center Manifold Strategies

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

Synodic Strategies

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.