Map Services

Services for map objects in the Hiten framework.

Map Persistence Service

_MapPersistenceService()

Handle persistence for map objects.

class hiten.algorithms.types.services.maps._MapPersistenceService[source]

Bases: _PersistenceServiceBase

Handle persistence for map objects.

Parameters:

save_fn (Callable[..., Any]) – The function to save the object.
load_fn (Callable[..., Any]) – The function to load the object.
load_inplace_fn (Optional[Callable[..., Any]] = None) – The function to load the object in place.

Map Dynamics Service Base

_MapDynamicsServiceBase()

Base class for map dynamics services.

class hiten.algorithms.types.services.maps._MapDynamicsServiceBase(domain_obj)[source]

Bases: _DynamicsServiceBase

Base class for map dynamics services with caching.

Parameters:: domain_obj (Any) – The domain object.

section_coord

The section coordinate.

Type:: str

sections

The sections.

Type:: dict[str, _Section]

section

The section.

Type:: _Section

generator

The key for the section.

Type:: str

property generator: str: The pipeline to generate the map.

abstract property map_config: The map configuration.

property section_coord: str: The most recently computed section coordinate.

get_section(section_coord=None)[source]

Get a computed section by coordinate.

Parameters:: section_coord (str) – The section coordinate identifier.
Returns:: The computed section data.
Return type:: _Section
Raises:: KeyError – If the section has not been computed.

Notes

This method returns the full section data including points, states, labels, and times. Use this method when you need access to the complete section information.

list_sections()[source]

List all computed section coordinates.

Returns:: List of section coordinate identifiers that have been computed.
Return type:: list[str]

Notes

This method returns the keys of the internal section cache, indicating which sections are available for access.

has_section(section_coord)[source]

Check if a section has been computed.

Parameters:: section_coord (str) – The section coordinate identifier to check.
Returns:: True if the section has been computed, False otherwise.
Return type:: bool

Notes

This method provides a safe way to check section availability before attempting to access it.

clear()[source]

Clear all cached sections.

Notes

This method clears the internal caches for sections, forcing recomputation on the next access. Use this method to free memory or force fresh computation with updated parameters.

get_points(*, section_coord=None, axes=None)[source]

Return cached points for a section with optional axis projection.

Parameters:

section_coord (str, optional) – Which stored section to retrieve. If None, uses the default section coordinate from the configuration.
axes (tuple[str, str], optional) – Optional tuple of two axis labels (e.g., (“q3”, “p2”)) requesting a different 2D projection of the stored state. If None, returns the raw stored projection.

Returns:

Array of 2D points in the section plane, either the raw points or a projection onto the specified axes.

Return type:

ndarray, shape (n, 2)

Notes

This method provides access to the computed section points with optional axis projection. If the section hasn’t been computed, it triggers computation automatically. The axis projection allows viewing the section data from different coordinate perspectives.

abstractmethod compute(*, section_coord='q3', overrides=None, **kwargs)[source]

Compute or retrieve the return map for the specified section.

Parameters:

section_coord (str)
overrides (dict[str, Any] | None)

Return type:

ndarray

Center Manifold Map Dynamics Service

_CenterManifoldMapDynamicsService()

Provide dynamics services for center manifold maps.

class hiten.algorithms.types.services.maps._CenterManifoldMapDynamicsService(domain_obj)[source]

Bases: _MapDynamicsServiceBase

Dynamics service for center manifold maps with caching.

Parameters:: domain_obj (CenterManifoldMap) – The domain object.

center_manifold

The center manifold.

Type:: CenterManifold

energy

The energy.

Type:: float

generator

The generator.

Type:: CenterManifoldMapPipeline

section_coord

The section coordinate.

Type:: str

property center_manifold: CenterManifold: The center manifold.

property energy: float: The energy.

property hamsys: _HamiltonianSystem: The Hamiltonian system.

compute(*, section_coord='q3', overrides=None, **kwargs)[source]

Compute or retrieve the return map for the specified section.

Parameters:

section_coord (str) – The section coordinate.
overrides (dict[str, Any]) – The overrides.
kwargs (dict[str, Any]) – The keyword arguments.

Returns:

The results of the Poincare map.

Return type:

CenterManifoldMapResults

get_points_with_4d_states(*, section_coord=None, axes=None)[source]

Return 2-D projection of the Poincare map points with 4D state access.

This method extends the base implementation to allow projections mixing plane coordinates with the missing coordinate by using the stored 4-D center manifold states.

Parameters:

section_coord (str) – The section coordinate.
axes (tuple[str, str]) – The axes to project onto.

Return type:

ndarray

to_synodic(poincare_point, section_coord, tol)[source]

Convert the Poincare point to synodic coordinates.

Parameters:

poincare_point (np.ndarray) – The Poincaré point.
section_coord (str) – The section coordinate.
tol (float) – The tolerance.

Returns:

The synodic coordinates.

Return type:

np.ndarray

property map_config: _CenterManifoldMapConfig: The map configuration.

Synodic Map Dynamics Service

_SynodicMapDynamicsService()

Provide dynamics services for synodic maps.

class hiten.algorithms.types.services.maps._SynodicMapDynamicsService(domain_obj)[source]

Bases: _MapDynamicsServiceBase

Dynamics service for synodic maps with detection-based computation.

Parameters:: domain_obj (SynodicMap) – The domain object.

trajectories

The trajectories.

Type:: List[Trajectory]

source

The source.

Type:: Literal[PeriodicOrbit, Manifold]

property trajectories: List[Trajectory]: The trajectories.

property source: Literal[PeriodicOrbit, Manifold]: The source.

compute(*, section_axis, section_offset, plane_coords, direction, overrides=None, **kwargs)[source]

Compute the synodic map.

Parameters:

section_axis (str) – The section axis.
section_offset (float) – The section offset.
plane_coords (tuple[str, str]) – The plane coordinates.
direction (Literal[1, -1, None]) – The direction.
overrides (dict[str, Any]) – The overrides.
kwargs (dict[str, Any]) – The keyword arguments.

property map_config: _SynodicMapConfig: The map configuration.

Map Services

_MapServices()

Encapsulate services for map objects.

class hiten.algorithms.types.services.maps._MapServices(domain_obj, persistence, dynamics)[source]

Bases: _ServiceBundleBase

Bundle all map services together.

Parameters:

domain_obj (Map) – The domain object.
persistence (_MapPersistenceService)
dynamics (_MapDynamicsServiceBase)

dynamics

The dynamics service.

Type:: _MapDynamicsServiceBase

persistence

The persistence service.

Type:: _MapPersistenceService

classmethod default(domain_obj)[source]

Create a default service bundle.

Parameters:: domain_obj (Map) – The domain object.
Returns:: The service bundle.
Return type:: _MapServices

classmethod with_shared_dynamics(dynamics)[source]

Create a service bundle with a shared dynamics service.

Parameters:: dynamics (_MapDynamicsServiceBase) – The dynamics service.
Returns:: The service bundle.
Return type:: _MapServices