Hamiltonian Simulation

hamiltonian_simulation() approximates the time-evolution operator $U (t) = e^{- i H t}$ . The unified entry point selects among seven algorithm families and returns a common result-object structure.

Minimal example


import numpy as np
from unitarylab.library import hamiltonian_simulation
 
H = np.array([[0, 1], [1, 0]], dtype=float)
result = hamiltonian_simulation(
    H, t=0.5, method="trotter", target_error=1e-3,
    steps=20, order=1, backend="torch", device="cpu",
)
 
print(result.circuit)
print(result.total_error)
print(result.evolution_result)

Entry signature


hamiltonian_simulation(
    H, t, method="trotter", target_error=1e-6,
    backend="torch", device="cpu", dtype=np.complex128, **kwargs
)

H must be a finite Hermitian square matrix, t must be finite, and target_error must be positive. If the dimension is not $2^{n}$ , the matrix is zero-padded to the next power of two and a notice is emitted; result matrices can still be read at the original dimension.

Methods and method-specific parameters

`method`	Use	Method-specific parameters and defaults
`trotter`	Deterministic product formula	`order=1`, `steps=1000`
`qdrift`	Random sampling of Pauli terms	`steps=5000`
`taylor`	Taylor/Chebyshev approximation	`degree=5`
`qsp` / `qsvt`	Signal transformation with block encoding	`degree=15`, `beta=0.7`, `block_encoding_method="nagy"`
`bessel-lcu`	Bessel expansion and LCU	No method-specific parameters
`cartan-lax`	Cartan–Lax flow for real symmetric matrices	`evol_time`, `lr`, `max_steps`, `reps`
`cartan-optimization`	Numerical Cartan optimization for real symmetric matrices	`evol_time`, `lr`, `max_steps`, `optimizer`

Pass only keyword arguments supported by the selected method. Unknown methods or unsupported parameters raise ValueError. Cartan methods require a real symmetric input matrix.

Result object

HamiltonianSimulationResult provides these lazy properties:

Property	Description
`.circuit`	Construct and cache the simulation circuit
`.evolution_result`	Approximate evolution matrix represented by the circuit
`.total_error`	Operator error between exact $e^{- i H t}$ and the approximation

Accessing a lazy property performs the corresponding construction or matrix calculation. .total_error is the actual approximation error; target_error is the requested accuracy. Do not assume all methods strictly guarantee the requested value in the same way.

Scale recommendations

Start with $2 \times 2$ or $4 \times 4$ matrices to check methods and parameters.
steps, degree, and input dimension can increase circuit length; state-vector and matrix computations grow exponentially with qubit count.
For reproducible experiments, set a seed through the parameters supported by methods that use randomness.
If only the circuit is needed, avoid accessing .evolution_result or .total_error in advance.