Hamiltonian Simulation Protocol

English · 简体中文

Category C2 · Module oracq.algorithms.common.hamiltonian · 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), 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

hamiltonian_simulation(operator, time, *, method="auto", steps=2, qsp=None)

API entry: hamiltonian_simulation

  • operator: a Hermitian operator, which must satisfy 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 TrotterizableProtocol: trotter_list() returns a non-empty sequence of TrotterTerm(coefficient, operator), each term’s operator satisfying EvolvableProtocol (evolution(time) returns an Operation). Returns a 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: PauliOperator(word) (whose evolution is exactly a single term and single step of trotter_hamsim), PauliHamiltonian(terms) (providing both BE and trotter_list() access), and 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 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.

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 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.

Reproduction command:

PYTHONPATH=src /path/to/backend/python tests/verification/verify_hamiltonian.py

Artifacts: out/verification/hamiltonian.json.