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 (hamiltonian, ham_id) -> MetaCircuit.

Attributes Summary

axis_name	Axis name introduced by this stage.
stateful	Whether this stage invalidates forward-pass reuse from this point.

Methods Summary

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

stateful

Methods Documentation

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:

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

expand(batch, env)

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

Return type:

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

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]