TimeEvolution

class TimeEvolution(hamiltonian, trotterization_strategy=None, time=1.0, n_steps=1, order=1, initial_state=None, observable=None, _template_meta=None, _template_param=None, **kwargs)

Bases: ObservableMeasuringMixin, QuantumProgram

Quantum program for Hamiltonian time evolution.

Simulates the evolution of a quantum state under a Hamiltonian using Trotter-Suzuki decomposition. Uses Divi’s TrotterizationStrategy (ExactTrotterization, QDrift) for term selection and approximation.

Initialize TimeEvolution.

Parameters:

• hamiltonian (SparsePauliOp) – Hamiltonian to evolve under. Accepts anything to_spo() consumes (SparsePauliOp, PennyLane operator, or a divi-convention Pauli-string dict).

• trotterization_strategy (TrotterizationStrategy | None) – Strategy for term selection (ExactTrotterization, QDrift). Defaults to ExactTrotterization().

• time (float) – Evolution time t (e^(-iHt)).

• n_steps (int) – Number of Trotter steps.

• order (int) – Suzuki-Trotter order (1 or even).

• initial_state (InitialState | None) – Initial state preparation. Pass an InitialState instance (e.g. ZerosState(), SuperpositionState()). Defaults to ZerosState() if None.

• observable (SparsePauliOp | Sequence[SparsePauliOp] | None) –

  One of:

  • None — measure computational-basis probabilities over all qubits.

  • Single observable accepted by to_spo() — one expectation-value measurement; self.results is a float.

  • Sequence of such observables — multiple expectation-value measurements from the same circuit; self.results is a list[float] (one mitigated value per observable). Commuting observables are measured from a shared shot batch via MeasurementStage’s QWC grouping; QuEPP shares the target circuit and dedupes path DAGs across observables.

• **kwargs – Passed to QuantumProgram (backend, seed, progress_queue, etc.). Accepts qem_protocol for quantum error mitigation (requires observable to be set, since QEM operates on expectation values).

Attributes Summary

results

Get the final results.

Methods Summary

expval()	Return expectation-value-mode results.
has_results()	Return True once the program has produced results.
probabilities()	Return probability-mode results.
run(**kwargs)	Execute time evolution.

Attributes Documentation

results

Get the final results.

Returns one of:

• dict[str, float] — probability distribution when no observable was provided.

• float — expectation value for a single observable.

• list[float] — per-observable expectation values when observable is a list/tuple.

Raises:

RuntimeError – If .run() has not yet been called.

Methods Documentation

expval()

Return expectation-value-mode results.

Returns a float when observable was a single operator, or a list[float] (one entry per observable, in input order) when observable was a list/tuple.

Raises:

RuntimeError – If .run() has not yet been called, or if this instance was constructed without an observable (probability mode). Use probabilities() instead.

Return type:

float | list[float]

has_results()

Return True once the program has produced results.

Return type:

bool

probabilities()

Return probability-mode results.

Raises:

RuntimeError – If .run() has not yet been called, or if this instance was constructed with an observable (expectation value mode). Use expval() instead.

Return type:

dict[str, float]

run(**kwargs)

Execute time evolution.

Returns:

Returns self for method chaining.

Return type:

TimeEvolution