Dynamical System Protocols

The protocols module provides abstract interfaces for dynamical systems using Python protocols.

_DynamicalSystemProtocol()

The _DynamicalSystemProtocol class defines the minimal interface that any dynamical system must implement to be compatible with the integrator framework.

class hiten.algorithms.dynamics.protocols._DynamicalSystemProtocol

Bases: Protocol

Define the protocol for the minimal interface for dynamical systems.

This protocol specifies the required attributes that any dynamical system must implement to be compatible with the integrator framework. It uses structural typing to allow duck typing while maintaining type safety.

dim

Dimension of the state space (number of state variables).

Type:

int

rhs

Right-hand side function f(t, y) that computes the time derivative dy/dt given time t and state vector y.

Type:

Callable[[float, ndarray], ndarray]

Notes

The @runtime_checkable decorator allows isinstance() checks against this protocol at runtime, enabling flexible type validation.

property dim: int

Dimension of the state space.

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

Right-hand side function for ODE integration.

_HamiltonianSystemProtocol()

The _HamiltonianSystemProtocol class extends the base dynamical system protocol with Hamiltonian-specific methods required by symplectic integrators.

class hiten.algorithms.dynamics.protocols._HamiltonianSystemProtocol

Bases: _DynamicalSystemProtocol, Protocol

Define the protocol for the interface for Hamiltonian dynamical systems.

Extends the base dynamical system protocol with Hamiltonian-specific methods required by symplectic integrators. Provides access to partial derivatives and polynomial representation of the Hamiltonian.

See also

_DynamicalSystemProtocol

Base protocol

_HamiltonianSystem

Concrete implementation

property n_dof: int

Number of degrees of freedom.

Returns:

Degrees of freedom count. Total state dimension is 2 * n_dof.

Return type:

int

dH_dQ(Q, P)

Compute partial derivatives of Hamiltonian with respect to positions.

Parameters:

• Q (ndarray, shape (n_dof,)) – Position coordinates.

• P (ndarray, shape (n_dof,)) – Momentum coordinates.

Returns:

Partial derivatives dH/dQ.

Return type:

ndarray, shape (n_dof,)

dH_dP(Q, P)

Compute partial derivatives of Hamiltonian with respect to momenta.

Parameters:

• Q (ndarray, shape (n_dof,)) – Position coordinates.

• P (ndarray, shape (n_dof,)) – Momentum coordinates.

Returns:

Partial derivatives dH/dP.

Return type:

ndarray, shape (n_dof,)

poly_H()

Return polynomial representation of the Hamiltonian.

Returns:

Nested list structure containing polynomial coefficients organized by degree and variable.

Return type:

List[List[ndarray]]

property rhs_params: tuple

Return low-level RHS parameters for parametric kernels.

Returns:

A 3-tuple (jac_H, clmo_H, n_dof) suitable for passing to compiled Hamiltonian RHS kernels. jac_H and clmo_H are sequence-like containers of numpy arrays; n_dof is an int.

Return type:

tuple