Base Dynamical Systems

The base module provides the core framework for dynamical systems.

_DynamicalSystem()

The _DynamicalSystem class provides the abstract base class for implementing concrete dynamical systems that can be integrated numerically. It defines the minimal interface required for compatibility with the integrator framework and includes utilities for state validation and dimension checking.

class hiten.algorithms.dynamics.base._DynamicalSystem[source]

Bases: _SerializeBase, ABC

Provide an abstract base class for dynamical systems.

Provides common functionality and interface definition for concrete dynamical system implementations. Handles state space dimension validation and provides utilities for state vector checking.

Parameters:

dim (int) – Dimension of the state space (must be positive).

Raises:

ValueError – If dim is not positive.

Notes

Subclasses must implement the abstract rhs property to provide the vector field function compatible with _DynamicalSystemProtocol.

See also

_DynamicalSystemProtocol

Interface specification

_DirectedSystem

Directional wrapper implementation

property dim: int

Dimension of the state space.

property rhs: Callable[[float, ndarray], ndarray]

Return compiled and cached right-hand side f(t, y).

validate_state(y)[source]

Validate state vector dimension.

Parameters:

y (ndarray) – State vector to validate.

Raises:

ValueError – If state vector length differs from system dimension.

Return type:

None

See also

_validate_initial_state()

Module-level validation utility

_DirectedSystem()

The _DirectedSystem class provides a directional wrapper for forward/backward time integration. It wraps another dynamical system to enable forward or backward time integration with selective component sign handling. Particularly useful for Hamiltonian systems where momentum variables change sign under time reversal.

class hiten.algorithms.dynamics.base._DirectedSystem[source]

Bases: _DynamicalSystem

Provide a directional wrapper for forward/backward time integration.

Wraps another dynamical system to enable forward or backward time integration with selective component sign handling. Particularly useful for Hamiltonian systems where momentum variables change sign under time reversal.

Parameters:

  • base_or_dim (_DynamicalSystem or int) – Either a concrete system instance to wrap, or the state dimension for subclasses that implement their own rhs property.

  • fwd (int, optional) – Direction flag. Positive values integrate forward in time, negative values integrate backward. Default is 1.

  • flip_indices (slice or Sequence[int] or None, optional) – Indices of state components whose derivatives should be negated when fwd < 0. If None, all components are flipped. Default is None.

dim

Dimension of the underlying system.

Type:

int

_fwd

Normalized direction flag (+1 or -1).

Type:

int

_base

Wrapped system instance (None for subclass usage).

Type:

_DynamicalSystem or None

_flip_idx

Component indices to flip for backward integration.

Type:

slice or Sequence[int] or None

Raises:

AttributeError – If rhs is accessed when no base system was provided and the subclass doesn’t implement its own rhs property.

Parameters:

Notes

  • The wrapper post-processes vector field output without modifying

    the original system

  • Supports both composition (wrapping existing systems) and inheritance

    (subclassing with custom rhs implementation)

  • Attribute access is delegated to the wrapped system when available

Examples

>>> # Forward integration (default)
>>> forward_sys = _DirectedSystem(base_system)
>>> # Backward integration
>>> backward_sys = _DirectedSystem(base_system, fwd=-1)
>>> # Backward with selective momentum flipping
>>> hamiltonian_backward = _DirectedSystem(ham_sys, fwd=-1, flip_indices=[3,4,5])

See also

_DynamicalSystem

Base class for dynamical systems

_propagate_dynsys()

Generic propagation using DirectedSystem

__repr__()[source]

String representation of DirectedSystem.

Returns:

Formatted string showing system parameters.

Return type:

str

__getattr__(item)[source]

Delegate attribute access to wrapped system.

Parameters:

item (str) – Attribute name to access.

Returns:

Attribute value from wrapped system.

Return type:

Any

Raises:

AttributeError – If no wrapped system exists or attribute not found.

_propagate_dynsys()

The _propagate_dynsys() function provides a generic propagation function for dynamical systems. It handles state validation, directional wrapping, and delegation to various integration backends. Supports multiple numerical methods with consistent interface.

hiten.algorithms.dynamics.base._propagate_dynsys()[source]

Generic trajectory propagation for dynamical systems.

Internal utility that handles state validation, directional wrapping, and delegation to various integration backends. Supports multiple numerical methods with consistent interface.

Parameters:

  • dynsys (_DynamicalSystemProtocol) – Dynamical system to integrate.

  • state0 (Sequence[float]) – Initial state vector.

  • t0 (float) – Initial time.

  • tf (float) – Final time.

  • forward (int, optional) – Integration direction (+1 forward, -1 backward). Default is 1.

  • steps (int, optional) – Number of time steps for output. Default is 1000.

  • method ({'fixed', 'adaptive', 'symplectic'}, optional) – Integration method to use. Default is ‘adaptive’.

  • order (int, optional) – Integration order. Default is 8.

  • flip_indices (Sequence[int] or None, optional) – State component indices to flip for backward integration. Default is None.

  • **kwargs – Additional keyword arguments passed to the integrator, including: - event_fn: Numba-compiled scalar event function g(t, y) - event_cfg: _EventConfig with direction/tolerances

Returns:

Integration solution containing times and states.

Return type:

_Solution

Notes

  • Automatically applies _DirectedSystem wrapper for direction handling

  • Validates initial state dimension against system requirements

  • Supports multiple backends: fixed-step Runge-Kutta, adaptive RK, symplectic

  • Time array is adjusted for integration direction in output

See also

_DirectedSystem

Directional wrapper used internally

_validate_initial_state()

State validation utility

_validate_initial_state()

The _validate_initial_state() function validates and normalizes initial state vectors for dynamical systems.

hiten.algorithms.dynamics.base._validate_initial_state()[source]

Validate and normalize initial state vector.

Converts input to numpy array and validates dimension against expected system requirements. Used internally by propagation routines.

Parameters:

  • state (array_like) – Initial state vector to validate.

  • expected_dim (int, optional) – Expected state vector dimension. Default is 6 (typical for CR3BP).

Returns:

Validated state vector as float64 numpy array.

Return type:

numpy.ndarray

Raises:

ValueError – If state vector dimension doesn’t match expected_dim.

See also

validate_state()

Instance method for validation

_propagate_dynsys()

Uses this function for state validation