# Trotter Product-Formula Simulation
**English** · 简体中文
> Category C2 · Module [`oracq.algorithms.common.hamiltonian`](../../api/algorithms/common/hamiltonian.rst) · Stage V2
## Overview
Given a Pauli decomposition $H = \sum_j c_j P_j$ (each $P_j$ a same-width Pauli word), simulate $e^{-iHt}$ with the first-order product formula:
$$
e^{-iHt} \approx \left(\prod_j e^{-i c_j P_j\, t / r}\right)^{r},
$$
The larger the repetition count $r$, the smaller the product-formula error. A single term $e^{-i\theta P}$ is turned by basis changes into a phase rotation on the computational basis: apply basis changes to the non-identity positions of $P$ (H on X positions; on Y positions a $-\pi/2$ phase gate followed by H), fold the parity of the active positions onto the last position with a CNOT chain, apply the phase rotation to the last position, and then restore in reverse order.
## Interface and input model
```python
trotter_hamsim(terms, final_time, *, steps=2)
```
API entry: {obj}`trotter_hamsim `
- `terms`: a `((coefficient, word), ...)` sequence, with `coefficient` real (internally converted through `float`) and `word` a same-width I/X/Y/Z string; the input model is HAM (Pauli-term decomposition).
- `final_time`: the total evolution time $t$ (a finite real number).
- `steps`: the repetition count $r$, a positive integer, default 2.
Returns an {obj}`Operation ` (a bare operation, not a {obj}`BlockEncoding `), with registers `target = Bits(width)` and `signal = Bits(0)` — the evolution is an exact unitary that requires no post-selection. Module attributes:
| Attribute | Meaning |
|---|---|
| `algorithm` | `"trotter_hamsim"` |
| `validation_stage` | `"paradigm"` |
Generation-time validation: raises {obj}`ValidationError ` when `terms` is empty, `steps < 1`, or the Pauli words have inconsistent widths. An all-I term consumes no qubits and degenerates to the global phase $e^{-i c_j t / r}$.
## Implementation notes
The circuit body is a single {obj}`Repeat(steps) ` block whose interior evolves term by term in input order; it is not expanded during the generation stage, and text serialization and backend lowering keep the Repeat structure. Each term is generated as "basis change → CNOT chain → phase rotation on the last position → restore": the CNOT chain covers only the non-I positions, and the last-position rotation angle is $2 c_j t / r$ (`rz(θ)` follows the $e^{-i\theta Z/2}$ convention, and after the factor of 2 it realizes exactly a phase of the $e^{-i\theta Z^{\otimes k}}$ type).
Applicability boundary: only Pauli-word decompositions are accepted, and no higher-order Suzuki ordering is performed (higher-order formulas require the caller to reorder `terms` itself and use a larger `steps`); coefficients go through `float()` conversion, and complex coefficients raise an error outright. For the protocol-layer entry point see [Hamiltonian simulation protocol](hamiltonian-simulation.md), which routes the per-term evolution of any Trotterizable operator back to this function (`PauliOperator.evolution` calls exactly this function with `steps=1`).
## 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. Three layers of evidence:
- Structure: `tests/core/test_algorithm_protocols.py:AlgorithmProtocolTests.test_trotter_protocol_keeps_phase_and_repeat` pins down the Repeat structure (the first block of the module body has `count == steps`); `test_trotter_validates_each_term` covers term-level validation ({obj}`TrotterTerm ` rejects non-Evolvable operators, and a {obj}`PauliHamiltonian ` with inconsistent widths is rejected at construction).
- Numerical: `test_trotter_protocol_keeps_phase_and_repeat` cross-checks $H = 0.3I + 0.7X$, $t = 0.4$, `steps = 3` amplitude by amplitude against $e^{-0.12i}\bigl(\cos 0.28\,|0\rangle - i\sin 0.28\,|1\rangle\bigr)$ (places = 11), indirectly covering the per-term stage order generated by this function; `test_trotter_only_input_does_not_need_block_encoding` witnesses a single-term Z evolution (coefficient 0.5, $t = 0.2$) outputting $e^{-0.1i}$.
- Binding: no independent binding witness (the input is an explicit Pauli decomposition with no abstract slots).
## Known gaps and planned stages
The Trotter order-error-rate sweep is missing: batch curves of the error versus `steps` / $\Delta t$ are not automated and will be wired in once the stage V2 convergence-scan framework (validation-plan §5) lands; the current numerical witnesses cross-check analytic values at single parameter points only.
## Related links
- Source: `src/oracq/algorithms/common/hamiltonian.py`
- Tutorial: [Supplying your own Hamiltonian decomposition](../../tutorials/hamiltonian.md)
- Same-family pages: [Hamiltonian simulation protocol](hamiltonian-simulation.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, total runtime about 28 s). Experiment design: single-term Pauli evolutions (10 instances, covering Y basis changes, 2–4-qubit CNOT chains, global phases of identity terms, and negative times) are exported via OriginIR-ext, the full unitary is extracted by UniQC `Circuit.to_matrix`, and the result is cross-checked element by element against the independent closed form $\cos(ct)I - i\sin(ct)P$; many-term non-commuting decompositions (1–4 qubits, steps ∈ {1,2,3,5}, t ∈ {0.4, −0.7, 0.9, 1.3}) are cross-checked against the classical product-formula matrix $\bigl(\prod_j e^{-ic_jP_jt/r}\bigr)^r$; a 3-qubit TFIM on a uniform-superposition input is cross-checked across four paths; the convergence order comes from sweeping steps ∈ {1,…,64} at $t = 1.0$ for 2- and 3-qubit TFIMs, taking the spectral-norm error against `scipy.linalg.expm` as an independent oracle and fitting log–log. UniQC `to_matrix` drops trailing gate-free qubits (the case of a Pauli word ending in I); the verification script embeds them back as identity factors before cross-checking (see the `embed_unitary` comment in the script).
| Case | Scale | Backend paths | Metric | Value |
|---|---|---|---|---|
| `trotter-single-term-exact` | 10 instances, 1–4 qubits | originir-ext + UniQC to_matrix | max_error | 4.4e-16 |
| `trotter-product-formula-1q` | 3 terms (including an identity term), steps×t grid | originir-ext + UniQC to_matrix | max_error | 5.7e-16 |
| `trotter-product-formula-2q` | 4 terms, steps ∈ {1,2,5} | originir-ext + UniQC to_matrix | max_error | 1.5e-15 |
| `trotter-product-formula-3q` | 5-term TFIM, steps ∈ {2,3} | originir-ext + UniQC to_matrix | max_error | 1.4e-15 |
| `trotter-product-formula-4q` | 5 terms, steps=3 | originir-ext + UniQC to_matrix | max_error | 1.7e-15 |
| `trotter-superposition-cross-3q` | 5-term TFIM, steps=3, superposition exhaustive | reference, rir-pysparq, adapter-pysparq, originir-ext | max_deviation | 1.2e-15 |
| `trotter-convergence-2q` | $t = 1.0$, $r$ = 1…64 | originir-ext + UniQC to_matrix | fitted convergence order (theory 1) | 1.008 (error 0.7627 → 0.01049) |
| `trotter-convergence-3q` | $t = 1.0$, $r$ = 1…32 | originir-ext + UniQC to_matrix | fitted convergence order (theory 1) | 1.013 (error 1.0680 → 0.02809) |
The product-formula semantics are validated to machine precision (≤ 1.7e-15), and the fitted convergence orders 1.008 / 1.013 of first-order Lie–Trotter agree with the theoretical value 1, closing the gap in this section previously recorded as "missing Trotter order-error-rate sweep".
Reproduction command:
```bash
PYTHONPATH=src /path/to/backend/python tests/verification/verify_hamiltonian.py
```
Artifacts: `out/verification/hamiltonian.json` (including the error sequences over all step counts and the per-word errors).