Hamiltonian Systems
The hamiltonian module provides polynomial Hamiltonian systems for center manifold dynamics.
_HamiltonianSystemProtocol()
The _HamiltonianSystemProtocol
class extends the base dynamical system protocol with Hamiltonian-specific methods required by symplectic integrators.
_HamiltonianSystem()
The _HamiltonianSystem
class implements a polynomial Hamiltonian system for numerical integration.
- class hiten.algorithms.dynamics.hamiltonian._HamiltonianSystem[source]
Bases:
_DynamicalSystem
Define a polynomial Hamiltonian system for numerical integration.
Implements a dynamical system based on a polynomial Hamiltonian function. Stores the Jacobian in packed form and provides both standard ODE interface (for general integrators) and Hamiltonian-specific methods (for symplectic integrators).
The system automatically computes Hamilton’s equations: dQ/dt = dH/dP, dP/dt = -dH/dQ using JIT-compiled polynomial evaluation.
- Parameters:
H_blocks (List[ndarray]) – Packed coefficient arrays [H_0, H_2, …, H_N] from center-manifold pipeline, where H_k contains degree-k polynomial coefficients.
degree (int) – Maximum polynomial degree N represented in H_blocks.
psi_table (ndarray) – Lookup table mapping monomial exponents to packed array indices.
clmo_table (List[ndarray]) – Coefficient-layout mapping objects for each polynomial degree.
encode_back_dict_list (List[dict]) – Encoder dictionaries for polynomial Jacobian computation.
n_dof (int) – Number of degrees of freedom. Total state dimension is 2 * n_dof.
name (str, optional) – Human-readable system identifier. Default is “Hamiltonian System”.
encode_dict_list (List)
- jac_H
Numba-typed nested list containing Jacobian coefficients.
- Type:
List[List[ndarray]]
- clmo_H
Numba-typed list of coefficient-layout mapping objects.
- Type:
List[ndarray]
- Raises:
ValueError – If n_dof is not positive or polynomial data shapes are inconsistent.
- Parameters:
Notes
RHS function is JIT-compiled on first call for efficiency
Supports both autonomous ODE interface and Hamiltonian-specific methods
Compatible with general ODE solvers and symplectic integrators
Polynomial evaluation uses complex arithmetic internally but returns real derivatives
Examples
>>> # Create system from polynomial data >>> sys = _HamiltonianSystem(H_blocks, degree, psi_table, clmo_table, ... encode_dict_list, n_dof=3) >>> # Use with ODE solver >>> ydot = sys.rhs(0.0, state) # Standard ODE interface >>> # Use with symplectic integrator >>> dH_dQ = sys.dH_dQ(Q, P) # Hamiltonian derivatives
See also
_HamiltonianSystemProtocol
Interface specification
create_hamiltonian_system()
Factory function
_hamiltonian_rhs()
JIT-compiled RHS computation
- property n_dof: int
Number of degrees of freedom.
- Returns:
Degrees of freedom count. Total state dimension is 2 * n_dof.
- Return type:
- property clmo: List[ndarray]
Coefficient-layout mapping objects for polynomial evaluation.
- Returns:
Numba-typed list of coefficient-layout mapping objects.
- Return type:
List[ndarray]
See also
_polynomial_evaluate()
Uses these objects
- dH_dQ(Q, P)[source]
Compute partial derivatives dH/dQ for symplectic integration.
- Parameters:
Q (ndarray, shape (n_dof,)) – Position coordinates.
P (ndarray, shape (n_dof,)) – Momentum coordinates.
- Returns:
Partial derivatives of Hamiltonian with respect to positions.
- Return type:
ndarray, shape (n_dof,)
- Raises:
ValueError – If Q or P dimensions don’t match n_dof.
See also
_eval_dH_dQ()
Implementation
dH_dP()
Momentum derivatives
- dH_dP(Q, P)[source]
Compute partial derivatives dH/dP for symplectic integration.
- Parameters:
Q (ndarray, shape (n_dof,)) – Position coordinates.
P (ndarray, shape (n_dof,)) – Momentum coordinates.
- Returns:
Partial derivatives of Hamiltonian with respect to momenta.
- Return type:
ndarray, shape (n_dof,)
- Raises:
ValueError – If Q or P dimensions don’t match n_dof.
See also
_eval_dH_dP()
Implementation
dH_dQ()
Position derivatives
- poly_H()[source]
Return polynomial coefficient blocks of the Hamiltonian.
- Returns:
Nested list of polynomial coefficient arrays organized by degree. Structure: H_blocks[k] contains degree-k coefficients.
- Return type:
List[List[ndarray]]
See also
create_hamiltonian_system()
Uses these blocks for system creation
_hamiltonian_rhs()
The _hamiltonian_rhs()
function computes Hamilton’s equations for polynomial Hamiltonian systems.
- hiten.algorithms.dynamics.hamiltonian._hamiltonian_rhs()[source]
Compute Hamilton’s equations for polynomial Hamiltonian system.
JIT-compiled function that evaluates the time derivatives (dQ/dt, dP/dt) for a polynomial Hamiltonian system using Hamilton’s canonical equations: dQ/dt = dH/dP, dP/dt = -dH/dQ.
- Parameters:
state6 (ndarray) – State vector [Q1, Q2, Q3, P1, P2, P3] for the 2*n_dof Hamiltonian system.
jac_H (List[List[ndarray]]) – Nested Numba-typed list containing Jacobian coefficients of the Hamiltonian. Structure: jac_H[i][j] contains degree-j coefficients for partial derivative with respect to variable i.
clmo (List[ndarray]) – Numba-typed list of coefficient-layout mapping objects for polynomial evaluation at each degree.
n_dof (int) – Number of degrees of freedom (half the state dimension).
- Returns:
Time derivative vector [dQ/dt, dP/dt] = [dH/dP, -dH/dQ].
- Return type:
ndarray
Notes
Uses JIT compilation for efficient polynomial evaluation
Handles complex arithmetic internally but returns real derivatives
Assumes autonomous Hamiltonian (no explicit time dependence)
See also
_polynomial_evaluate()
Polynomial evaluation
_HamiltonianSystem
Uses this function for RHS computation
create_hamiltonian_system()
The create_hamiltonian_system()
function creates polynomial Hamiltonian system from coefficient data.
- hiten.algorithms.dynamics.hamiltonian.create_hamiltonian_system()[source]
Create polynomial Hamiltonian system from coefficient data.
Factory function that converts packed polynomial coefficient blocks from the center-manifold pipeline into a ready-to-integrate Hamiltonian system. Handles all necessary data structure conversions and validations.
- Parameters:
H_blocks (List[ndarray]) – Packed coefficient arrays [H_0, H_2, …, H_N] from center-manifold reduction, where H_k contains degree-k polynomial coefficients.
degree (int) – Maximum polynomial degree N represented in H_blocks.
psi_table (ndarray) – Lookup table mapping monomial exponents to packed array indices.
clmo_table (List[ndarray]) – Coefficient-layout mapping objects for each polynomial degree.
encode_dict_list (List[dict]) – Encoder dictionaries for polynomial Jacobian computation.
n_dof (int, optional) – Number of degrees of freedom. Default is 3 (typical for CR3BP).
name (str, optional) – Human-readable system identifier. Default is “Center Manifold Hamiltonian”.
- Returns:
Configured Hamiltonian system ready for numerical integration.
- Return type:
Examples
>>> # Create system from center manifold data >>> sys = create_hamiltonian_system(H_blocks, degree, psi_table, ... clmo_table, encode_dict_list, n_dof=3) >>> # Integrate with ODE solver >>> sol = solve_ivp(sys.rhs, [0, 10], initial_state)
See also
_HamiltonianSystem
Underlying system implementation
_polynomial_jacobian()
Jacobian computation