State Types

The states module provides comprehensive type definitions and state vector containers for the circular restricted three-body problem.

Reference Frames

ReferenceFrame

Enumeration of available reference frames for state vectors.

class hiten.algorithms.types.states.ReferenceFrame(value)[source]

Bases: Enum

Reference frame container.

INERTIAL: non-rotating barycentric (or system-specific) inertial frame. [x, y, z, vx, vy, vz] ROTATING: synodic frame rotating with primaries. [x, y, z, vx, vy, vz] CENTER_MANIFOLD: center manifold coordinate system. [q1, q2, q3, p1, p2, p3] RESTRICTED_CENTER_MANIFOLD: restricted center manifold coordinate system. [q2, p2, q3, p3]

INERTIAL = 'inertial'

ROTATING = 'rotating'

CENTER_MANIFOLD = 'center_manifold'

RESTRICTED_CENTER_MANIFOLD = 'restricted_center_manifold'

Coordinate Enumerations

SynodicState

Enumeration for synodic frame coordinates. Defines indices for the 6D state vector in the rotating synodic frame.

class hiten.algorithms.types.states.SynodicState(value)[source]

Bases: IntEnum

Enumeration for synodic frame coordinates.

This enumeration defines the indices for the 6D state vector in the rotating synodic frame of the circular restricted three-body problem. The coordinates are ordered as position components followed by velocity components.

X

X position component (index 0)

Type:: int

Y

Y position component (index 1)

Type:: int

Z

Z position component (index 2)

Type:: int

VX

X velocity component (index 3)

Type:: int

VY

Y velocity component (index 4)

Type:: int

VZ

Z velocity component (index 5)

Type:: int

Notes

The synodic frame rotates with the primary bodies, so the coordinates represent position and velocity in the rotating reference frame.

X = 0

Y = 1

Z = 2

VX = 3

VY = 4

VZ = 5

CenterManifoldState

Enumeration for center manifold coordinates. Defines indices for the 6D state vector in the center manifold coordinate system.

class hiten.algorithms.types.states.CenterManifoldState(value)[source]

Bases: IntEnum

Enumeration for center manifold coordinates.

This enumeration defines the indices for the 6D state vector in the center manifold coordinate system. The coordinates are ordered as position components (q1, q2, q3) followed by momentum components (p1, p2, p3).

q1

First position component (index 0)

Type:: int

q2

Second position component (index 1)

Type:: int

q3

Third position component (index 2)

Type:: int

p1

First momentum component (index 3)

Type:: int

p2

Second momentum component (index 4)

Type:: int

p3

Third momentum component (index 5)

Type:: int

Notes

The center manifold coordinates are canonical coordinates that preserve the Hamiltonian structure of the system.

q1 = 0

q2 = 1

q3 = 2

p1 = 3

p2 = 4

p3 = 5

RestrictedCenterManifoldState

Enumeration for restricted center manifold coordinates. Defines indices for the 4D state vector in the restricted center manifold coordinate system.

class hiten.algorithms.types.states.RestrictedCenterManifoldState(value)[source]

Bases: IntEnum

Enumeration for restricted center manifold coordinates.

This enumeration defines the indices for the 4D state vector in the restricted center manifold coordinate system. The coordinates are ordered as position components (q2, q3) followed by momentum components (p2, p3).

q2

Second position component (index 0)

Type:: int

p2

Second momentum component (index 1)

Type:: int

q3

Third position component (index 2)

Type:: int

p3

Third momentum component (index 3)

Type:: int

Notes

The restricted center manifold coordinates are a reduced set of canonical coordinates that capture the essential dynamics while reducing computational complexity.

q2 = 0

p2 = 1

q3 = 2

p3 = 3

State Vector Containers

_BaseStateContainer()

Minimal mutable container for a single state vector, indexed by an IntEnum. Base class for all state vector containers.

class hiten.algorithms.types.states._BaseStateContainer(values=None, *, copy=True, frame=None, **kwargs)[source]

Bases: object

Minimal mutable container for a single state vector, indexed by an IntEnum.

This is the base class for all state vector containers. It provides array-like access, property access, and validation for state vectors in different coordinate systems.

Subclasses must set _enum to the corresponding IntEnum class and can optionally expose convenience properties (e.g., x, y, vx).

Parameters:

values (Sequence[float], optional) – Initial values for the state vector. If None, initializes to zeros.
**kwargs – Named parameters for individual components (e.g., x=1.0, y=2.0).
copy (bool)
frame (ReferenceFrame | None)

_enum

The enumeration class defining the coordinate indices

Type:: type[IntEnum]

_values

The underlying state vector data

Type:: npt.NDArray[np.float64]

Notes

The container supports both array-like access (e.g., state[0]) and property access (e.g., state.x) for convenience. All values are stored as 64-bit floating-point numbers.

property array: ndarray[tuple[int, ...], dtype[float64]]: Return a writable 1D numpy array of the state values.

to_numpy(copy=True)[source]

Return the underlying data as numpy array; copy by default.

Parameters:: copy (bool)
Return type:: ndarray[tuple[int, …], dtype[float64]]

copy()[source]: Deep copy of the container preserving the concrete subclass type.

property dim: int: Return the dimension of the state vector.

as_tuple()[source]

Return the state vector as a tuple.

Return type:: Tuple[float, …]

as_dict()[source]

Return the state vector as a dictionary.

Return type:: dict

property frame: ReferenceFrame | None: Reference frame metadata, if available.

classmethod from_array_view(array, *, frame=None)[source]

Construct a container that wraps a 1D NumPy array without copying.

The provided array must be 1D and have length equal to the enum size. Mutations through the container will mutate the original array.

Parameters:

array (ndarray[tuple[int, ...], dtype[float64]])
frame (ReferenceFrame | None)

Return type:

_BaseStateContainer

SynodicStateVector()

Container for synodic frame state vectors. Provides convenient access to 6D state vectors in the rotating synodic frame.

class hiten.algorithms.types.states.SynodicStateVector(values=None, *, copy=True, frame=None, **kwargs)[source]

Bases: _BaseStateContainer

Container for synodic frame state vectors.

This class provides a convenient container for 6D state vectors in the rotating synodic frame of the circular restricted three-body problem. It supports both array-like access and property access for all components.

Parameters:

values (Sequence[float], optional) – Initial values for the state vector. If None, initializes to zeros.
**kwargs – Named parameters for individual components (e.g., x=1.0, y=2.0, vx=0.5).
copy (bool)
frame (ReferenceFrame | None)

x

X position component

Type:: float

y

Y position component

Type:: float

z

Z position component

Type:: float

vx

X velocity component

Type:: float

vy

Y velocity component

Type:: float

vz

Z velocity component

Type:: float

Notes

The synodic frame rotates with the primary bodies, so the coordinates represent position and velocity in the rotating reference frame.

DEFAULT_FRAME = 'rotating'

property x: float: Return the X position component.

property y: float: Return the Y position component.

property z: float: Return the Z position component.

property vx: float: Return the X velocity component.

property vy: float: Return the Y velocity component.

property vz: float: Return the Z velocity component.

CenterManifoldStateVector()

Container for center manifold state vectors. Provides convenient access to 6D state vectors in the center manifold coordinate system.

class hiten.algorithms.types.states.CenterManifoldStateVector(values=None, *, copy=True, frame=None, **kwargs)[source]

Bases: _BaseStateContainer

Container for center manifold state vectors.

This class provides a convenient container for 6D state vectors in the center manifold coordinate system. It supports both array-like access and property access for all canonical coordinates.

Parameters:

values (Sequence[float], optional) – Initial values for the state vector. If None, initializes to zeros.
**kwargs – Named parameters for individual components (e.g., q1=1.0, q2=2.0, p1=0.5).
copy (bool)
frame (ReferenceFrame | None)

q1

First position component

Type:: float

q2

Second position component

Type:: float

q3

Third position component

Type:: float

p1

First momentum component

Type:: float

p2

Second momentum component

Type:: float

p3

Third momentum component

Type:: float

Notes

The center manifold coordinates are canonical coordinates that preserve the Hamiltonian structure of the system.

DEFAULT_FRAME = 'center_manifold'

property q1: float: Return the first position component.

property q2: float: Return the second position component.

property q3: float: Return the third position component.

property p1: float: Return the first momentum component.

property p2: float: Return the second momentum component.

property p3: float: Return the third momentum component.

RestrictedCenterManifoldStateVector()

Container for restricted center manifold state vectors. Provides convenient access to 4D state vectors in the restricted center manifold coordinate system.

class hiten.algorithms.types.states.RestrictedCenterManifoldStateVector(values=None, *, copy=True, frame=None, **kwargs)[source]

Bases: _BaseStateContainer

Container for restricted center manifold state vectors.

This class provides a convenient container for 4D state vectors in the restricted center manifold coordinate system. It supports both array-like access and property access for the reduced set of canonical coordinates.

Parameters:

values (Sequence[float], optional) – Initial values for the state vector. If None, initializes to zeros.
**kwargs – Named parameters for individual components (e.g., q2=1.0, q3=2.0, p2=0.5).
copy (bool)
frame (ReferenceFrame | None)

q2

Second position component

Type:: float

p2

Second momentum component

Type:: float

q3

Third position component

Type:: float

p3

Third momentum component

Type:: float

Notes

The restricted center manifold coordinates are a reduced set of canonical coordinates that capture the essential dynamics while reducing computational complexity.

DEFAULT_FRAME = 'restricted_center_manifold'

property q2: float: Return the second position component.

property p2: float: Return the second momentum component.

property q3: float: Return the third position component.

property p3: float: Return the third momentum component.

Trajectory

Trajectory()

Container for time-series of state vectors. Provides efficient storage and access to trajectory data.

class hiten.algorithms.types.states.Trajectory(times, states, state_vector_cls=None, frame=None)[source]

Bases: object

Lightweight container for trajectory data: a time array and matching state vectors.

This class provides a convenient container for storing trajectory data with time and state arrays. It supports array-like access, slicing, and iteration over time-state pairs.

Parameters:

times (Sequence[float]) – Monotonically ordered time grid of length N.
states (Sequence[Sequence[float]]) – State matrix of shape (N, D) with D-dimensional states corresponding to each time.
state_vector_cls (Type[_BaseStateContainer] | None)
frame (ReferenceFrame | None)

times

Time array of length N

Type:: npt.NDArray[np.float64]

states

State matrix of shape (N, D)

Type:: npt.NDArray[np.float64]

n_samples

Number of stored samples N

Type:: int

dim

State-space dimension D

Type:: int

t0

Initial time

Type:: float

tf

Final time

Type:: float

duration

Total elapsed time tf - t0

Type:: float

Notes

The container is read-only by convention; create a new instance for slices or transformations.
Time values may be strictly increasing or strictly decreasing, but must be strictly monotonic.
All data is stored as 64-bit floating-point numbers for consistency.

property times: ndarray[tuple[int, ...], dtype[float64]]: Return the time array.

property states: ndarray[tuple[int, ...], dtype[float64]]: Return the state array.

property n_samples: int: Number of stored samples N.

property dim: int: State-space dimension D.

property t0: float: Initial time.

property tf: float: Final time.

property duration: float: Total elapsed time tf - t0 (can be negative if times are decreasing).

as_arrays()[source]

Return the underlying arrays as a tuple (times, states).

Return type:: Tuple[ndarray[tuple[int, …], dtype[float64]], ndarray[tuple[int, …], dtype[float64]]]

property state_vector_cls: Type[_BaseStateContainer] | None: The container class used for row views, if any (e.g., SynodicStateVector).

property index_enum: type[IntEnum] | None: Return the IntEnum representing the state indices, if a container class is bound.

property frame: ReferenceFrame | None: Reference frame for the trajectory’s states (e.g., rotating vs inertial).

with_state_vector(cls)[source]

Return a new trajectory referencing the same arrays with a state vector class bound.

Parameters:: cls (Type[_BaseStateContainer])
Return type:: Trajectory

with_frame(frame)[source]

Return a new trajectory referencing the same arrays with a reference frame set.

Parameters:: frame (ReferenceFrame)
Return type:: Trajectory

vector_at(index, *, copy=False)[source]

Return the state at index wrapped as a state-vector container.

If copy=False, the wrapper references the underlying row view.

Parameters:

index (int)
copy (bool)

Return type:

_BaseStateContainer

iter_vectors(*, copy=False)[source]

Iterate over state rows yielding state-vector containers.

If copy=False, each yielded container wraps a view into the underlying array.

Parameters:: copy (bool)
Return type:: Iterator[_BaseStateContainer]

classmethod from_arrays(times, states, *, state_vector_cls=None, frame=None)[source]

Construct from numpy arrays (validated).

Parameters:

times (ndarray[tuple[int, ...], dtype[float64]])
states (ndarray[tuple[int, ...], dtype[float64]])
state_vector_cls (Type[_BaseStateContainer] | None)
frame (ReferenceFrame | None)

Return type:

Trajectory

classmethod from_solution(solution, *, state_vector_cls=None, frame=None)[source]

Construct from an integrator _Solution without copying arrays.

Parameters:

solution (_Solution)
state_vector_cls (Type[_BaseStateContainer] | None)
frame (ReferenceFrame | None)

Return type:

Trajectory

reversed()[source]

Return a new trajectory with reversed time order.

Return type:: Trajectory

to_arrays()[source]

Return the underlying arrays as a tuple (times, states).

Return type:: Tuple[ndarray[tuple[int, …], dtype[float64]], ndarray[tuple[int, …], dtype[float64]]]