ParameterBindingStage

class ParameterBindingStage

Bases: BundleStage

Bind env.param_sets into every circuit body.

Two output shapes, selected at pipeline construction via validate():

• Fast path — when no downstream stage reads meta.circuit_bodies (i.e. all subsequent stages declare consumes_dag_bodies=False). Each body DAG is serialised once to a parametric QASM string, wrapped in a QASMTemplate, and rendered per parameter set into meta.qasm_bodies with parameters cleared. The pipeline’s compilation pass then reads the bound strings directly.

• Slow path — when any downstream stage consumes body DAGs (e.g. PauliTwirlStage or QEMStage). For each body variant and parameter set, qiskit.circuit.QuantumCircuit.assign_parameters() emits a bound DAGCircuit written back to meta.circuit_bodies (parameters cleared). Slower, but preserves the DAG IR so downstream stages see concrete gate angles.

A third template path (_run_template(), when the backend implements SupportsCircuitTemplates) renders the parametric body into meta.qasm_bodies without binding, leaving parameters intact so the compilation pass defers substitution to the backend. Bound vs. template is therefore decided downstream by whether parameters survives, not by a dedicated field.

dry_expand() skips the prepare/emit helper entirely and emits shape-correct placeholders directly — the analytic path has no per- variant state to cache, so forcing it through the shared loop would only add dispatch noise.

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 forward pass for dry runs.
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 forward pass for dry runs.

Must emit a batch with the same shape as expand() (same keys, same len(circuit_bodies), same len(measurement_qasms)) and an introspect-compatible token, but without generating expensive per-item content (DAG deep-copies, QASM strings, classical simulations).

The default implementation falls back to expand(), so stages that cannot skip circuit generation keep working unchanged.

Shared-reference contract. Overriding implementations commonly emit the same DAG object across multiple tagged entries in meta.circuit_bodies (true of every built-in dry path today). Consumers may read those DAGs freely, but must not mutate them in place — a mutation on one entry would leak across sibling branches. CircuitPipeline enforces this by demoting such a stage to its real expand() whenever a downstream stage declares consumes_dag_bodies=True and has not overridden dry_expand; a DiviPerformanceWarning is emitted naming both stages. The dry-run circuit count stays correct either way — only the analytic speedup is forfeited for the affected stage.

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