TrotterSpecStage

class TrotterSpecStage(trotterization_strategy, meta_circuit_factory)

Bases: SpecStage[SparsePauliOp]

SpecStage that turns a Hamiltonian into a batch of MetaCircuits via a TrotterizationStrategy.

Accepts a SparsePauliOp, runs the strategy to obtain one or more SPO samples, and invokes meta_circuit_factory(processed_spo, ham_id) for each.

Parameters:

• trotterization_strategy (TrotterizationStrategy) – Strategy for term selection/sampling (e.g. ExactTrotterization, QDrift).

• meta_circuit_factory (Callable[..., MetaCircuit]) – Factory callable (TrotterizationResult, ham_id) -> MetaCircuit.

Attributes Summary

axis_name

Axis name introduced by this stage.

Methods Summary

cache_key_extras(env)	Invalidate the forward-pass cache per evaluation for QDrift.
dry_expand(batch, env)	Analytic path: build one prototype MetaCircuit, fan it out n_samples times.
expand(batch, env)	Transform Hamiltonian into a keyed batch of MetaCircuits (one per strategy output).
introspect(batch, env, token)	Return stage-specific metadata for dry-run reporting.
reduce(results, env, token)	Identity by default; override if this stage reduces results.

Attributes Documentation

axis_name

Methods Documentation

cache_key_extras(env)

Invalidate the forward-pass cache per evaluation for QDrift.

QDrift re-samples a fresh batch each optimizer evaluation, seeded deterministically from env.evaluation_counter; folding the counter into the cache key reuses one sample across the cost and gradient passes of a single evaluation, then resamples on the next. Deterministic strategies (e.g. ExactTrotterization) declare no extras and stay cached for the pipeline’s lifetime.

Return type:

tuple[Hashable, ...]

dry_expand(batch, env)

Analytic path: build one prototype MetaCircuit, fan it out n_samples times.

For stochastic strategies (e.g. QDrift) each sample would in principle produce a slightly different DAG. Dry runs only count circuits, so a single prototype from ham_id=0 is reused — saving (n_samples - 1) expensive factory invocations. For the dominant deterministic case (ExactTrotterization with n_samples=1) this reduces to the same single factory call as expand().

Return type:

StageOutput[dict[tuple[tuple[str, Hashable], ...], MetaCircuit]]

expand(batch, env)

Transform Hamiltonian into a keyed batch of MetaCircuits (one per strategy output).

Return type:

StageOutput[dict[tuple[tuple[str, Hashable], ...], MetaCircuit]]

introspect(batch, env, token)

Return stage-specific metadata for dry-run reporting.

Override in subclasses to provide richer introspection data. Called by the dry-run tool after expand with the post-expand batch, the pipeline env, and the stage’s token.

Return type:

dict[str, Any]

reduce(results, env, token)

Identity by default; override if this stage reduces results.

Return type:

dict[Any, Any]