# Hamiltonian Simulation Protocol
**English** · 简体中文
> Category C2 · Module [`oracq.algorithms.common.hamiltonian`](../../api/algorithms/common/hamiltonian.rst) · Stage V2
## Overview
Selects the Hamiltonian simulation route according to the access the input operator actually has: decomposable operators go through the Trotter product formula (the per-term evolution is generated by [Trotter product-formula simulation](trotter.md)), while operators available only as block encodings go through a caller-injected QSP kernel. The mathematical goal of both routes is to approximate $e^{-iHt}$; the accuracy semantics of the two routes differ — Trotter is a product-formula approximation, QSP is a polynomial approximation — so the returned object carries an explicit label such as `correctness = "product formula approximation pending"` and does not claim to be verified.
## Interface and input model
```python
hamiltonian_simulation(operator, time, *, method="auto", steps=2, qsp=None)
```
API entry: {obj}`hamiltonian_simulation `
- `operator`: a Hermitian operator, which must satisfy {obj}`HermitianProtocol ` (the `hermitian` attribute is `True`); the input model is HAM (Pauli/decomposable representation) or BE (block encoding).
- `time`: the evolution time, a finite real number.
- `method`: one of `"auto"` (default; Trotterizable goes to trotter, otherwise qsp), `"trotter"`, `"qsp"`; other values are rejected.
- `steps`: the Trotter step count, a positive integer, default 2.
- `qsp`: a callable implementing `qsp(BE, time) -> BlockEncoding`, which must be injected when `method="qsp"`.
The Trotter path requires `operator` to satisfy {obj}`TrotterizableProtocol `: `trotter_list()` returns a non-empty sequence of {obj}`TrotterTerm(coefficient, operator) `, each term's operator satisfying {obj}`EvolvableProtocol ` (`evolution(time)` returns an {obj}`Operation `). Returns a {obj}`BlockEncoding ` (`alpha = 1.0`) with module attributes:
| Attribute | Meaning |
|---|---|
| `algorithm` | `"trotter_hamiltonian_protocol"` |
| `steps` | repetition count |
| `correctness` | `"product formula approximation pending"` |
Built-in operator types: {obj}`PauliOperator(word) ` (whose evolution is exactly a single term and single step of {obj}`trotter_hamsim `), {obj}`PauliHamiltonian(terms) ` (providing both BE and `trotter_list()` access), and {obj}`EncodedOperator(encoding, hermitian) ` (holding only a BE and a Hermiticity declaration, without a decomposition).
## Implementation notes
The QSP path is an explicit injection point, not an implemented kernel: the library contains no general QSP-HamSim kernel, and a missing `qsp` callable raises an error directly instead of silently degrading; the return value of an injected implementation must be a `BlockEncoding` whose target width matches the input. The Trotter path calls `term.operator.evolution(term.coefficient * time / steps)` term by term and requires each term's evolution to be a unitary that needs no post-selection — registers exposed besides `target` must have zero width, and all terms must share the same width; a general polynomial BE that carries a signal register and requires post-selection cannot masquerade as an exact single-term evolution. The protocol assembly layer references each term's evolution with {obj}`Repeat(steps) ` plus module calls (resource names `term0`, `term1`, ...) and does not expand at generation time.
Applicability boundary: non-Hermitian dynamics are rejected with an explicit pointer to the QODE route; "non-Hermitian input" and "missing qsp implementation" are two independent errors and are never conflated.
## Validation approach
Category C2 (approximately continuous semantics; the acceptance criteria are in `../development/validation-plan.md` §2). Consistent with the `hamiltonian.py` row of the validation coverage matrix:
- Structure: `tests/core/test_algorithm_protocols.py:AlgorithmProtocolTests.test_trotter_protocol_keeps_phase_and_repeat` (Repeat `count == steps`, `alpha == 1`); `test_trotter_validates_each_term` (term-level validation of `TrotterTerm` / `PauliHamiltonian`).
- Numerical: `test_trotter_protocol_keeps_phase_and_repeat` cross-checks $H = 0.3I + 0.7X$, $t = 0.4$, `steps = 3` amplitude by amplitude against the analytic value (places = 11); `test_trotter_only_input_does_not_need_block_encoding` witnesses that a custom operator with only Trotter access and no BE can be solved (a single Z term with coefficient 0.5 and $t = 0.2$ gives $e^{-0.1i}$); `test_nonhermitian_and_missing_qsp_are_distinct_errors` pins down the two failure modes being raised separately.
- Binding: no independent binding witness (the input requires concrete protocol implementations, with no abstract slots).
## Known gaps and planned stages
The Trotter order-error-rate sweep is missing (stage V2 convergence-scan framework, validation-plan §5); the QSP path has only the contract checks and the injection point — the kernel itself is not part of this module. Consistent with the gap column of the `hamiltonian.py` row of the validation coverage matrix.
## Related links
- Source: `src/oracq/algorithms/common/hamiltonian.py`
- Tutorial: [Supplying your own Hamiltonian decomposition](../../tutorials/hamiltonian.md)
- Same-family pages: [Trotter product-formula simulation](trotter.md), [Truncated Taylor block encoding](taylor-block-encoding.md)
- API reference: [Hamiltonian evolution](../../api/algorithms/common/hamiltonian.rst)
- Validation matrix: [Validation coverage matrix](../../development/validation-coverage.md)
## Numerical validation
Paper-grade numerical experiments are in `tests/verification/verify_hamiltonian.py` (real-backend execution, no mock substitutes; all 27 cases PASS). The experiment design covers both routes of the protocol: for Trotter routing, a `PauliHamiltonian` ($H = 0.9\,ZZ + 0.6\,XI + 0.45\,IX$) at steps ∈ {2, 16} has its full unitary extracted via OriginIR-ext + UniQC `to_matrix` and is cross-checked element by element against the classical product-formula matrix, with `scipy.linalg.expm` as an independent oracle reporting the decrease of the Trotter gap with the step count; for the QSP injection path, an `EncodedOperator` ($H = 0.6\,Z + 0.4\,X$, $\alpha = 1.0$, `method="auto"` automatic routing) injects the in-library QSVT kernel {obj}`qsvt_hamiltonian_simulation ` (taking $\tau = -t\cdot\alpha$ to realize $e^{-iHt}$, `error = 0.02`), and the zero-signal block is read out on the three paths reference / rir-pysparq / originir-ext and cross-checked against $e^{-itH}/\text{sim\_scale}$.
| Case | Scale | Backend paths | Metric | Value |
|---|---|---|---|---|
| `hamsim-protocol-trotter-2q` | 3 terms, steps ∈ {2, 16} | originir-ext + UniQC to_matrix | max_error vs product formula | 4.5e-15 |
| same as above | — | — | expm gap r=2 → r=16 | 0.3475 → 0.0420 |
| `hamsim-protocol-qsp-injection` | 1 qubit, $t = 0.5$ | reference, rir-pysparq, originir-ext | zero-signal block max_error | 1.07e-4 |
| same as above | — | — | success probability (signal = 0) | 0.1113 |
For the systematic sweep of the Trotter convergence order (fitted orders 1.008 / 1.013, consistent with first-order theory), see the Numerical validation section of [Trotter product-formula simulation](trotter.md).
Reproduction command:
```bash
PYTHONPATH=src /path/to/backend/python tests/verification/verify_hamiltonian.py
```
Artifacts: `out/verification/hamiltonian.json`.