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.
stateful	Whether this stage invalidates forward-pass reuse from this point.

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

stateful

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:

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