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)

n_dof

Number of degrees of freedom.

Type:

int

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:

int

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

__repr__()[source]

String representation of the Hamiltonian system.

Returns:

Formatted string showing system name and degrees of freedom.

Return type:

str

property rhs_params: tuple

Return low-level RHS parameters for parametric kernels.

Returns:

(jac_H, clmo_H, n_dof) for use with compiled Hamiltonian RHS.

Return type:

tuple

_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:

_HamiltonianSystem

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