QEMStage

class QEMStage(protocol=None)

Bases: BundleStage

BundleStage that applies a QEM protocol to each circuit body.

Threads QEMContext objects through the StageToken so that reduce can pass them back to the protocol together with the quantum results.

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: delegates each body to protocol.dry_expand.
expand(batch, env)	Transform keyed MetaCircuit batch and return expansion lineage plus token.
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.
validate(before, after)	Check this stage's position in the pipeline.

Attributes Documentation

axis_name

stateful

Methods Documentation

dry_expand(batch, env)

Analytic path: delegates each body to protocol.dry_expand.

The default dry_expand() falls back to expand so simple / cheap protocols (e.g. _NoMitigation, ZNE) stay correct unchanged. Expensive protocols such as QuEPP override dry_expand to skip Clifford simulation + per-path DAG cloning while preserving the emitted DAG count.

Return type:

tuple[ExpansionResult, Any]

expand(batch, env)

Transform keyed MetaCircuit batch and return expansion lineage plus token.

Return type:

tuple[ExpansionResult, 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]

validate(before, after)

Check this stage’s position in the pipeline.

Called by CircuitPipeline at construction time after structural validation. Override to inspect neighboring stages and either:

• raise ContractViolation if preconditions are not met, or

• emit DiviPerformanceWarning for legal-but-slow configurations (e.g. expensive internal options, known-bad neighboring stages). Suppressed at the pipeline level via CircuitPipeline(..., suppress_performance_warnings=True).

Parameters:

• before (tuple[Stage, ...]) – Stages before this one in expand order.

• after (tuple[Stage, ...]) – Stages after this one in expand order.

Return type:

None