Poincare Events

The events module provides surface event classes for defining Poincare section surfaces.

Core Events

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

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

Synodic Events

class hiten.algorithms.poincare.synodic.events._AffinePlaneEvent[source]

Bases: _SurfaceEvent

Affine hyperplane event in the synodic frame.

This class defines a Poincare section surface as an affine hyperplane in the 6D state space of the circular restricted three-body problem. It extends the base surface event to provide specialized functionality for synodic Poincare sections with arbitrary hyperplane orientations.

The section is defined by the zero level-set of:

g(state) = n * state - c = 0

where state = (x, y, z, vx, vy, vz) and n is a 6D normal vector.

Parameters:

normal (array_like, shape (6,)) – Hyperplane normal in synodic coordinates (nondimensional units). The vector is used as-is (no normalization) so its scale must be consistent with the offset parameter.
offset (float, default 0.0) – Hyperplane offset along the normal (nondimensional units). The section is defined by n * state = offset.
direction ({1, -1, None}, optional) – Crossing direction filter passed to the base surface event. If None, no direction filtering is applied.

Notes

This class provides a flexible way to define Poincare sections in the synodic frame. Unlike axis-aligned planes, it allows arbitrary orientations in the 6D state space, enabling complex section geometries.

The class performs validation to ensure the normal vector has the correct dimensions and contains only finite values.

All geometric parameters are in nondimensional units unless otherwise specified.

value(state)[source]

Compute the surface function value for a given state.

Parameters:: state (ndarray, shape (6,)) – State vector in synodic coordinates (nondimensional units).
Returns:: The surface function value g(state) = n * state - c.
Return type:: float

Notes

This method computes the surface function value for the given state vector. The function returns zero when the state is on the hyperplane, positive when on one side, and negative when on the other side.

The computation uses the dot product of the normal vector with the state vector, minus the offset.

property normal: ndarray

Get the hyperplane normal vector.

Returns:: The hyperplane normal vector in synodic coordinates.
Return type:: ndarray, shape (6,)

property offset: float

Get the hyperplane offset value.

Returns:: The hyperplane offset value (nondimensional units).
Return type:: float

classmethod axis_plane(coord, *, c=0.0, direction=None)[source]

Convenience constructor for axis-aligned planes.

Parameters:

coord (str or int) – Coordinate name or index for the plane normal. String names: “x”, “y”, “z”, “vx”, “vy”, “vz” Integer indices: 0-5 corresponding to the coordinates above.
c (float, default 0.0) – Plane offset value (nondimensional units).
direction ({1, -1, None}, optional) – Crossing direction filter for the surface event.

Returns:

An affine plane event with axis-aligned normal.

Return type:

_AffinePlaneEvent

Raises:

ValueError – If coordinate name is unknown or index is out of range.

Examples

Create a plane at x = 1 - mu:

>>> plane = hiten.algorithms.poincare.synodic.events._AffinePlaneEvent.axis_plane("x", c=1-mu)

Create a plane at y = 0:

>>> plane = hiten.algorithms.poincare.synodic.events._AffinePlaneEvent.axis_plane(1, c=0.0)

Notes

This class method provides a convenient way to create axis-aligned planes without manually constructing the normal vector. It creates a normal vector with a 1 in the specified coordinate position and 0 elsewhere.

All geometric parameters are in nondimensional units.