MetaCircuit

class MetaCircuit(circuit_bodies, parameters=(), observable=None, measured_wires=None, measurement_qasms=(), qasm_bodies=(), measurement_groups=(), result_format=None, group_shots=None, backend_ham_ops=None, precision=8, _was_multi_obs=False)

Bases: object

Logical circuit IR.

Stores one or more tagged DAGCircuit bodies together with the parameters that appear in them, optional observable / measured-wire metadata, and the (already-serialised) measurement QASM strings produced by MeasurementStage.

The DAGCircuit bodies are the long-lived working IR for all stages that mutate circuits at the gate level (QEM folding, Pauli twirling, QuEPP path enumeration). QASM2 text is produced only once per parametric body — inside ParameterBindingStage when it builds a QASMTemplate — and once at compilation time when bound bodies are concatenated with the pre-serialised measurement QASMs.

Attributes Summary

backend_ham_ops	Observable string handed to the backend for analytic expectation values (_backend_expval grouping); None for counts-based paths.
circuit_bodies	Tagged parametric DAGs.
group_shots	Per-observable-group shot allocation (group_index -> shots) when a shot_distribution is active; None otherwise.
measured_wires	Qubit indices to measure for probs/counts measurements.
measurement_groups	Cached grouped observables set by MeasurementStage.
measurement_qasms	Pre-serialised, non-parametric OpenQASM 2.0 measurement strings (diagonalising gates + measure instructions), one per commuting observable group.
n_qubits	Number of qubits in the circuit (from the first body DAG).
observable	Observable(s) for expectation-value measurements.
parameters	Ordered Qiskit Parameter objects referenced by the DAGs.
precision	Number of decimal places for numeric parameter values in QASM conversion.
qasm_bodies	OpenQASM 2.0 body strings at the current binding level.
result_format	Canonical format the raw backend results should be converted into.

Methods Summary

set_backend_ham_ops(ham_ops)	Return a new MetaCircuit with the backend observable string set.
set_circuit_bodies(bodies)	Return a new MetaCircuit with updated circuit-body DAGs.
set_group_shots(group_shots)	Return a new MetaCircuit with per-group shot allocation set.
set_measurement_bodies(bodies)	Return a new MetaCircuit with updated measurement QASMs.
set_measurement_groups(measurement_groups)	Return a new MetaCircuit with updated measurement groups.
set_qasm_bodies(bodies)	Return a new MetaCircuit with updated QASM body strings.
set_result_format(result_format)	Return a new MetaCircuit with the result format set.

Attributes Documentation

backend_ham_ops: str | None = None

Observable string handed to the backend for analytic expectation values (_backend_expval grouping); None for counts-based paths.

circuit_bodies: tuple[tuple[tuple[tuple[str, Hashable], ...], DAGCircuit], ...] = <dataclasses._MISSING_TYPE object>

Tagged parametric DAGs. Every body shares the same logical qubit layout.

group_shots: Mapping[int, int] | None = None

Per-observable-group shot allocation (group_index -> shots) when a shot_distribution is active; None otherwise.

measured_wires: tuple[int, ...] | None = None

Qubit indices to measure for probs/counts measurements. None for expval.

measurement_groups: tuple[tuple[object, ...], ...] = ()

Cached grouped observables set by MeasurementStage.

measurement_qasms: tuple[tuple[tuple[tuple[str, Hashable], ...], str], ...] = ()

Pre-serialised, non-parametric OpenQASM 2.0 measurement strings (diagonalising gates + measure instructions), one per commuting observable group. Populated by MeasurementStage.set_measurement_bodies.

n_qubits

Number of qubits in the circuit (from the first body DAG).

observable: SparsePauliOp | tuple[SparsePauliOp, ...] | None = None

Observable(s) for expectation-value measurements.

• None — probs/counts measurement (uses measured_wires instead).

• SparsePauliOp — accepted as input; __post_init__ wraps it in a length-1 tuple.

• tuple[SparsePauliOp, ...] — canonical stored form; one mitigated expectation value per entry.

parameters: tuple[Parameter, ...] = ()

Ordered Qiskit Parameter objects referenced by the DAGs. Order matches the flat parameter-values array fed by ParameterBindingStage.

precision: int = 8

Number of decimal places for numeric parameter values in QASM conversion.

qasm_bodies: tuple[tuple[tuple[tuple[str, Hashable], ...], str], ...] = ()

OpenQASM 2.0 body strings at the current binding level.

One slot carries a body through progressive binding by the parameter-binding stages: DataBindingStage parks per-sample partial bodies (data substituted, weight placeholders kept), which ParameterBindingStage consults by body_tag prefix before falling back to serialising circuit_bodies via dag_to_qasm_body(); that stage then renders either fully bound bodies (no placeholders) or template bodies (placeholders preserved for backend substitution). The compilation pass reads this slot when non-empty, else serialises circuit_bodies on the fly.

result_format: ResultFormat | None = None

Canonical format the raw backend results should be converted into. Set by a measurement stage; read by pipeline.run().

Methods Documentation

set_backend_ham_ops(ham_ops)

Return a new MetaCircuit with the backend observable string set.

Return type:

MetaCircuit

set_circuit_bodies(bodies)

Return a new MetaCircuit with updated circuit-body DAGs.

Return type:

MetaCircuit

set_group_shots(group_shots)

Return a new MetaCircuit with per-group shot allocation set.

Return type:

MetaCircuit

set_measurement_bodies(bodies)

Return a new MetaCircuit with updated measurement QASMs.

Return type:

MetaCircuit

set_measurement_groups(measurement_groups)

Return a new MetaCircuit with updated measurement groups.

Return type:

MetaCircuit

set_qasm_bodies(bodies)

Return a new MetaCircuit with updated QASM body strings.

Return type:

MetaCircuit

set_result_format(result_format)

Return a new MetaCircuit with the result format set.

Return type:

MetaCircuit