PauliTwirlStage

class PauliTwirlStage(n_twirls=100, seed=None)

Bases: BundleStage

Fan out each DAG body into Pauli-twirled copies and average on reduce.

Parameters:

• n_twirls (int) – Number of randomized copies per circuit body.

• seed (int | None) – Optional seed for deterministic twirl sampling (useful in tests).

Attributes Summary

axis_name	Axis name introduced by this stage.
volatile	Whether this stage's output must be recomputed on every forward pass (rather than reused from cache), invalidating reuse from this point on.

Methods Summary

dry_expand(batch, env)	Analytic path: emit n_bodies × n_twirls shape-correct placeholders.
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

volatile

Methods Documentation

dry_expand(batch, env)

Analytic path: emit n_bodies × n_twirls shape-correct placeholders.

Skips label sampling, topology grouping, deep-copying, and QASM rendering entirely — twirling is a purely multiplicative fan-out, so the circuit count is exact from n_twirls alone. Matches the output slot (qasm_bodies vs circuit_bodies) of the real path so downstream dry stages and _compile_batch-aware counters see the right shape.

Return type:

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

expand(batch, env)

Transform keyed MetaCircuit batch and return expansion lineage plus token.

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]

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