Poincare Seeding

The seeding module provides protocols and implementations for generating initial conditions in Poincare return map computation.

Core Seeding Protocol

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

Center Manifold Seeding

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]