Hamiltonian evolution¶

oracq.algorithms.common.hamiltonian

Hamiltonian decomposition, Pauli evolution, Trotter and truncated Taylor encoding.

oracq.algorithms.common.hamiltonian.trotter_hamsim(terms, final_time, *, steps=2)[source]¶

First-order Trotter product-formula simulation of the evolution under a Pauli-decomposed Hamiltonian.

For H = sum_j c_j P_j it synthesizes exp(-i*H*t) as the steps-th power of prod_j exp(-i*c_j*P_j*t/steps): each Pauli word is folded, through basis changes and a CNOT chain, into a phase rotation on the last active qubit and then restored in reverse order. The circuit body is a single Repeat(steps) block and is not expanded per step at generation or serialization time; an all-I word consumes no qubits and degenerates to a global phase.

Parameters:

terms – Sequence of (coefficient, Pauli word) pairs; the coefficients are real numbers, converted through float, and the Pauli words are equal-width strings of I/X/Y/Z.
final_time – Total evolution time t.
steps – Number of repeated steps, at least 1; more steps give a smaller product-formula error.

Returns:

A bare unitary operation rather than a block encoding; the registers are target, of word width, and a zero-width signal, and the whole approximates exp(-i*H*t).

Return type:

Operation

Raises:

ValidationError – The term sequence is empty, steps is below 1, or the Pauli word widths differ.

oracq.algorithms.common.hamiltonian.taylor_hamiltonian(hamiltonian, time, *, degree=2)[source]¶

A closable plain Hamiltonian-function block encoding; replaceable by a QSP/HamSim protocol.

Parameters:

hamiltonian – Block encoding of the operator.
time – Evolution time, a finite real number.
degree – Taylor truncation order, an integer not less than 0; order 0 keeps only the identity term.

Returns:

LCU block encoding of the truncated Taylor series, with correctness marked pending.

Return type:

BlockEncoding

class oracq.algorithms.common.hamiltonian.HermitianProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Access protocol by which the host declares the Hermiticity of an operator.

property hermitian¶: Whether the operator is declared Hermitian; hamiltonian_simulation accepts only True.

class oracq.algorithms.common.hamiltonian.EvolvableProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Access protocol by which the host declares that an operator can produce its own unitary evolution.

evolution(time)[source]¶

Return the unitary Operation of this operator for the given evolution time.

The Trotter path requires the returned evolution to need no postselection: apart from target, all public registers are zero width.

Parameters:: time – Evolution time, a finite real number.
Returns:: The unitary evolution operation of this operator for the given duration.
Return type:: Operation

class oracq.algorithms.common.hamiltonian.TrotterizableProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Access protocol by which the host declares that an operator decomposes into a Trotter term list.

trotter_list()[source]¶

Return the TrotterTerm sequence constituting the Hamiltonian; hamiltonian_simulation requires it to be nonempty.

Returns:: The product-formula term sequence constituting the Hamiltonian, required to be nonempty.
Return type:: Sequence[TrotterTerm]

class oracq.algorithms.common.hamiltonian.TrotterTerm(coefficient, operator)[source]¶

Bases: object

A single Hamiltonian term of a product formula: a real coefficient combined with an evolvable operator.

Variables:

coefficient (float) – Real coefficient of the term; the Trotter path calls operator.evolution with duration coefficient * time / steps.
operator (object) – An operator satisfying EvolvableProtocol.

Raises:

ValidationError – coefficient is not a finite real number, or operator does not satisfy EvolvableProtocol.

coefficient¶

operator¶

class oracq.algorithms.common.hamiltonian.PauliOperator(word)[source]¶

Bases: object

A single Pauli word operator; satisfies HermitianProtocol and EvolvableProtocol.

Variables:

word (str) – A nonempty string of I/X/Y/Z with width at most 64.
hermitian – Always True; this is the HermitianProtocol declaration.

Raises:

ValidationError – word is not a nonempty I/X/Y/Z string, or its width exceeds 64.

word¶

hermitian = True¶

block_encoding()[source]¶

Return the alpha=1.0 block encoding of this Pauli word: per-qubit single-qubit gates plus a zero-width signal.

Returns:: The Pauli word block encoding with scale 1.0.
Return type:: BlockEncoding

evolution(time)[source]¶

Return the exact unitary evolution of exp(-1j*word*time) (a single term in a single step, with no product-formula error).

Parameters:: time – Evolution time, a finite real number.
Returns:: The exact unitary evolution operation synthesized in a single term and single step.
Return type:: Operation

class oracq.algorithms.common.hamiltonian.PauliHamiltonian(terms)[source]¶

Bases: object

A real-coefficient linear combination of equal-width Pauli words; supports both block-encoding and Trotter decomposition access.

Variables:

terms (tuple[tuple[float, str], ...]) – Tuple of (coefficient, Pauli word) pairs; the coefficients are finite real numbers and all words have equal width.
hermitian – Always True; this is the HermitianProtocol declaration.

Raises:

ValidationError – The term list is empty, a coefficient is not a finite real number, a Pauli word is invalid, or the widths differ.

terms¶

hermitian = True¶

block_encoding()[source]¶

Return the LCU block encoding of the nonzero-coefficient terms; with no nonzero term it degenerates to the zero-operator block encoding.

Returns:: LCU block encoding with scale equal to the sum of absolute coefficient values, or the zero operator with no nonzero term.
Return type:: BlockEncoding

trotter_list()[source]¶

Wrap each (coefficient, word) into a TrotterTerm and return the tuple.

Returns:: Tuple of Trotter terms wrapping each coefficient and Pauli word one by one.
Return type:: tuple[TrotterTerm, …]

class oracq.algorithms.common.hamiltonian.EncodedOperator(encoding, hermitian)[source]¶

Bases: object

Host declaration of matrix properties; may represent non-Hermitian operators and does not claim to itself be a unitary.

encoding¶

hermitian¶

block_encoding()[source]¶

Return the block encoding carried at construction.

Returns:: The block encoding passed at construction, adapted and validated.
Return type:: BlockEncoding

oracq.algorithms.common.hamiltonian.hamiltonian_simulation(operator, time, *, method='auto', steps=2, qsp=None)[source]¶

Currently prefers the decomposable Trotter path; QSP requires the caller to supply an actual implementation.

Parameters:

operator – An operator declaring Hermitian, which must additionally satisfy the Trotter-decomposable or block-encodable protocol.
time – Evolution time, a finite real number.
method – Path selection, one of auto, trotter or qsp; auto picks by the operator protocol.
steps – Number of repeated segments of the Trotter product formula, a positive integer.
qsp – An actual implementation of the form qsp(BE, time) returning a BlockEncoding; needed only by the qsp path.

Returns:

Block encoding of the evolution exp(-iHt); the Trotter path has scale 1.0.

Return type:

BlockEncoding