BundleStage

class BundleStage(name)

Bases: Stage[dict[tuple[tuple[str, Hashable], …], MetaCircuit], ExpansionResult], ABC

Abstract stage that transforms a keyed MetaCircuit batch.

Subclasses declare two orthogonal contracts via class properties:

• handles_measurement — this stage emits measurement QASMs and sets result_format.

• consumes_dag_bodies — this stage reads (and typically mutates) meta.circuit_bodies during expand.

The pipeline is transformative by design: every BundleStage is expected to either handle measurement or consume body DAGs (or both). Declaring neither is almost always a misuse of the abstraction — metadata-only or logging passes belong outside the Stage ABC — so constructing such a stage emits a UserWarning at instantiation time.

Attributes Summary

consumes_dag_bodies	Whether this stage reads meta.circuit_bodies during expand.
handles_measurement	Whether this stage sets up measurement circuits and result format.

Methods Summary

expand(batch, env)	Transform keyed MetaCircuit batch and return expansion lineage plus token.
reduce(results, env, token)	Identity by default; override if this stage reduces results.

Attributes Documentation

consumes_dag_bodies

Whether this stage reads meta.circuit_bodies during expand.

Default True — the safe assumption. Override with False on stages that only inspect measurement/observable metadata (e.g. MeasurementStage, PCECostStage). Used by ParameterBindingStage to decide whether it can stay on the fast QASM-template render path.

handles_measurement

Whether this stage sets up measurement circuits and result format.

Pipelines must contain at least one stage with this property True.

Methods Documentation

abstractmethod expand(batch, env)

Transform keyed MetaCircuit batch and return expansion lineage plus token.

Return type:

tuple[ExpansionResult, Any]

reduce(results, env, token)

Identity by default; override if this stage reduces results.

Return type:

dict[Any, Any]