TimeEvolutionTrajectory

class TimeEvolutionTrajectory(hamiltonian, time_points, *, backend, trotterization_strategy=None, n_steps=1, order=1, initial_state=None, observable=None, seed=None, **kwargs)

Bases: ProgramEnsemble

Run TimeEvolution across multiple time points in parallel.

Creates one TimeEvolution program per time point, executes them via ProgramEnsemble (with optional batch-merged circuit submission), and aggregates results into a time-ordered mapping.

Example:

trajectory = TimeEvolutionTrajectory(
    hamiltonian=to_spo({"XI": 1.0, "IX": 1.0}),
    time_points=[0.0, 0.5, 1.0, 1.5],
    backend=backend,
)
trajectory.create_programs()
trajectory.run(blocking=True)
results = trajectory.aggregate_results()
# results: {0.0: {...}, 0.5: {...}, 1.0: {...}, 1.5: {...}}

Initialize TimeEvolutionTrajectory.

Parameters:

• hamiltonian (SparsePauliOp) – Hamiltonian to evolve under.

• time_points (Sequence[float]) – List of evolution times. One program is created per time point.

• backend (CircuitRunner) – Quantum circuit execution backend.

• trotterization_strategy (TrotterizationStrategy | None) – Strategy for term selection (ExactTrotterization, QDrift). Defaults to ExactTrotterization(). Deep-copied per program for thread safety.

• n_steps (int) – Number of Trotter steps.

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

• initial_state (InitialState | None) – Initial state preparation (InitialState instance). Defaults to ZerosState() if None.

• observable (SparsePauliOp | None) – If None, measure probabilities; else expectation value.

• seed (int | None) – Random seed for reproducible results.

• **kwargs – Forwarded verbatim to every per-time-point TimeEvolution. Use this for grouping_strategy, shot_distribution, precision, and any other QuantumProgram / ObservableMeasuringMixin kwarg that should apply uniformly across the trajectory. program_id and progress_queue are set internally and must not be passed here.

Methods Summary

aggregate_results()	Aggregate results into a time-ordered mapping.
create_programs()	Create one TimeEvolution program per time point.
visualize_results()	Plot the expectation-value trajectory over time.

Methods Documentation

aggregate_results()

Aggregate results into a time-ordered mapping.

Return type:

dict[float, dict | float]

Returns:

dict mapping each time point to its result. The value is a dict[str, float] of probabilities when no observable is set, or a float expectation value otherwise.

create_programs()

Create one TimeEvolution program per time point.

visualize_results()

Plot the expectation-value trajectory over time.

Requires that the trajectory was run with an observable.

Raises:

RuntimeError – If no observable was set (probability mode).