Circuits

The divi.circuits module provides circuit abstractions for quantum program generation, execution, and error mitigation.

Core Circuit Classes

Warning

Developer-Facing Classes: The core circuit classes (Circuit and MetaCircuit) are intended for advanced users and developers. Most users should interact with circuits through higher-level APIs in the divi.qprog module.

class Circuit(main_circuit, tags, qasm_circuits=None)

Bases: object

Represents a quantum circuit with its QASM representation and metadata.

This class encapsulates a PennyLane quantum circuit along with its OpenQASM serialization and associated tags for identification. Each circuit instance is assigned a unique ID for tracking purposes.

main_circuit

The PennyLane quantum circuit/tape object.

tags

List of string tags for circuit identification.

Type:

list[str]

qasm_circuits

List of OpenQASM string representations.

Type:

list[str]

circuit_id

Unique identifier for this circuit instance.

Type:

int

Initialize a Circuit instance.

Parameters:

• main_circuit – A PennyLane quantum circuit or tape object to be wrapped.

• tags (list[str]) – List of string tags for identifying this circuit.

• qasm_circuits (list[str], optional) – Pre-computed OpenQASM string representations. If None, they will be generated from main_circuit. Defaults to None.

__init__(main_circuit, tags, qasm_circuits=None)

Initialize a Circuit instance.

Parameters:

• main_circuit – A PennyLane quantum circuit or tape object to be wrapped.

• tags (list[str]) – List of string tags for identifying this circuit.

• qasm_circuits (list[str], optional) – Pre-computed OpenQASM string representations. If None, they will be generated from main_circuit. Defaults to None.

__str__()

Return a string representation of the circuit.

Returns:

String in format “Circuit: {circuit_id}”.

Return type:

str

class MetaCircuit(main_circuit, symbols, grouping_strategy=None, qem_protocol=None)

Bases: object

A parameterized quantum circuit template for batch circuit generation.

MetaCircuit represents a symbolic quantum circuit that can be instantiated multiple times with different parameter values. It handles circuit compilation, observable grouping, and measurement decomposition for efficient execution.

main_circuit

The PennyLane quantum circuit with symbolic parameters.

symbols

Array of sympy symbols used as circuit parameters.

qem_protocol

Quantum error mitigation protocol to apply.

Type:

QEMProtocol

compiled_circuits_bodies

QASM bodies without measurements.

Type:

list[str]

measurements

QASM measurement strings.

Type:

list[str]

measurement_groups

Grouped observables for each circuit variant.

Type:

list[list]

postprocessing_fn

Function to combine measurement results.

Initialize a MetaCircuit with symbolic parameters.

Parameters:

• main_circuit – A PennyLane quantum circuit/tape with symbolic parameters.

• symbols – Array of sympy Symbol objects representing circuit parameters.

• grouping_strategy (str, optional) – Strategy for grouping commuting observables. Options are “wires”, “default”, or “qwc” (qubit-wise commuting). Defaults to None.

• qem_protocol (QEMProtocol, optional) – Quantum error mitigation protocol to apply to the circuits. Defaults to None.

__init__(main_circuit, symbols, grouping_strategy=None, qem_protocol=None)

Initialize a MetaCircuit with symbolic parameters.

Parameters:

• main_circuit – A PennyLane quantum circuit/tape with symbolic parameters.

• symbols – Array of sympy Symbol objects representing circuit parameters.

• grouping_strategy (str, optional) – Strategy for grouping commuting observables. Options are “wires”, “default”, or “qwc” (qubit-wise commuting). Defaults to None.

• qem_protocol (QEMProtocol, optional) – Quantum error mitigation protocol to apply to the circuits. Defaults to None.

__getstate__()

Prepare the MetaCircuit for pickling.

Serializes the postprocessing function using dill since regular pickle cannot handle certain PennyLane function objects.

Returns:

State dictionary with serialized postprocessing function.

Return type:

dict

__setstate__(state)

Restore the MetaCircuit from a pickled state.

Deserializes the postprocessing function that was serialized with dill during pickling.

Parameters:

state (dict) – State dictionary from pickling with serialized postprocessing function.

initialize_circuit_from_params(param_list, tag_prefix='', precision=8)

Instantiate a concrete Circuit by substituting symbolic parameters with values.

Takes a list of parameter values and creates a fully instantiated Circuit by replacing all symbolic parameters in the QASM representations with their concrete numerical values.

Parameters:

• param_list – Array of numerical parameter values to substitute for symbols. Must match the length and order of self.symbols.

• tag_prefix (str, optional) – Prefix to prepend to circuit tags for identification. Defaults to “”.

• precision (int, optional) – Number of decimal places for parameter values in the QASM output. Defaults to 8.

Returns:

A new Circuit instance with parameters substituted and proper

tags for identification.

Return type:

Circuit

Note

The main_circuit attribute in the returned Circuit still contains symbolic parameters. Only the QASM representations have concrete values.

QASM Integration

to_openqasm(main_qscript, measurement_groups, measure_all=True, precision=None, return_measurements_separately=False, symbols=None, qem_protocol=None)

Serialize the circuit as an OpenQASM 2.0 program.

A modified version of PennyLane’s function that is more compatible with having several measurements and incorporates modifications introduced by splitting transforms, as well as error mitigation through folding.

The measurement outputs can be restricted to only those specified in the script by setting measure_all=False.

Note

The serialized OpenQASM program assumes that gate definitions in qelib1.inc are available.

Parameters:

• main_qscript (QuantumScript) – the quantum circuit to be converted, as a QuantumScript/QuantumTape object.

• measurement_groups (list[list]) – A list of list of commuting observables, generated by the grouping Pennylane transformation.

• measure_all (bool) – whether to perform a computational basis measurement on all qubits or just those specified in the script

• precision (int) – decimal digits to display for parameters

• return_measurements_separately (bool) – whether to not append the measurement instructions and their diagonalizations to the main circuit QASM code and return separately.

• symbols (list) – Sympy symbols present in the circuit. Needed for some QEM routines.

• qem_protocol (QEMProtocol) – An optional QEMProtocol object for error mitigation, which may modify the circuit.

Returns:

OpenQASM serialization of the circuit

Return type:

list[str] or tuple[str, list[str]]

QASM Generation Function

to_openqasm(main_qscript, measurement_groups, measure_all=True, precision=None, return_measurements_separately=False, symbols=None, qem_protocol=None)

Serialize the circuit as an OpenQASM 2.0 program.

A modified version of PennyLane’s function that is more compatible with having several measurements and incorporates modifications introduced by splitting transforms, as well as error mitigation through folding.

The measurement outputs can be restricted to only those specified in the script by setting measure_all=False.

Note

The serialized OpenQASM program assumes that gate definitions in qelib1.inc are available.

Parameters:

• main_qscript (QuantumScript) – the quantum circuit to be converted, as a QuantumScript/QuantumTape object.

• measurement_groups (list[list]) – A list of list of commuting observables, generated by the grouping Pennylane transformation.

• measure_all (bool) – whether to perform a computational basis measurement on all qubits or just those specified in the script

• precision (int) – decimal digits to display for parameters

• return_measurements_separately (bool) – whether to not append the measurement instructions and their diagonalizations to the main circuit QASM code and return separately.

• symbols (list) – Sympy symbols present in the circuit. Needed for some QEM routines.

• qem_protocol (QEMProtocol) – An optional QEMProtocol object for error mitigation, which may modify the circuit.

Returns:

OpenQASM serialization of the circuit

Return type:

list[str] or tuple[str, list[str]]

Error Mitigation Protocols

Divi provides quantum error mitigation (QEM) capabilities to improve the accuracy of quantum computations in the presence of noise.

class QEMProtocol

Bases: ABC

Abstract Base Class for Quantum Error Mitigation (QEM) protocols.

All concrete QEM protocols should inherit from this class and implement the abstract methods and properties. This ensures a consistent interface across different mitigation techniques.

abstract property name: str

abstract modify_circuit(cirq_circuit)

Modifies a given Cirq circuit into one or more new circuits required by the QEM protocol.

For example, a Zero Noise Extrapolation (ZNE) protocol might produce multiple scaled versions of the input circuit. A simple mitigation protocol might return the original circuit unchanged.

Parameters:

cirq_circuit (cirq.Circuit) – The input quantum circuit to be modified.

Returns:

A sequence (e.g., list or tuple) of

Cirq circuits to be executed.

Return type:

Sequence[cirq.Circuit]

abstract postprocess_results(results)

Applies post-processing (e.g., extrapolation, filtering) to the results obtained from executing the modified circuits.

This method takes the raw output from quantum circuit executions (typically a sequence of expectation values or probabilities) and applies the core error mitigation logic to produce a single, mitigated result.

Parameters:

results (Sequence[float]) – A sequence of floating-point results, corresponding to the executions of the circuits returned by modify_circuit.

Returns:

The single, mitigated result after post-processing.

Return type:

float

class ZNE(scale_factors, folding_fn, extrapolation_factory)

Bases: QEMProtocol

Implements the Zero Noise Extrapolation (ZNE) quantum error mitigation protocol.

This protocol uses Mitiq’s functionalities to construct noise-scaled circuits and then extrapolate to the zero-noise limit based on the obtained results.

Initializes a ZNE protocol instance.

Parameters:

• scale_factors (Sequence[float]) – A sequence of noise scale factors to be applied to the circuits. These factors typically range from 1.0 upwards.

• folding_fn (Callable) – A callable (e.g., a functools.partial object) that defines how the circuit should be “folded” to increase noise. This function must accept a cirq.Circuit and a float (scale factor) as its first two arguments.

• extrapolation_factory (mitiq.zne.inference.Factory) – An instance of Mitiq’s Factory class, which provides the extrapolation method.

Raises:

ValueError – If scale_factors is not a sequence of numbers, folding_fn is not callable, or extrapolation_factory is not an instance of mitiq.zne.inference.Factory.

__init__(scale_factors, folding_fn, extrapolation_factory)

Initializes a ZNE protocol instance.

Parameters:

• scale_factors (Sequence[float]) – A sequence of noise scale factors to be applied to the circuits. These factors typically range from 1.0 upwards.

• folding_fn (Callable) – A callable (e.g., a functools.partial object) that defines how the circuit should be “folded” to increase noise. This function must accept a cirq.Circuit and a float (scale factor) as its first two arguments.

• extrapolation_factory (mitiq.zne.inference.Factory) – An instance of Mitiq’s Factory class, which provides the extrapolation method.

Raises:

ValueError – If scale_factors is not a sequence of numbers, folding_fn is not callable, or extrapolation_factory is not an instance of mitiq.zne.inference.Factory.

property name: str

property scale_factors: Sequence[float]

property folding_fn

property extrapolation_factory

modify_circuit(cirq_circuit)

Modifies a given Cirq circuit into one or more new circuits required by the QEM protocol.

For example, a Zero Noise Extrapolation (ZNE) protocol might produce multiple scaled versions of the input circuit. A simple mitigation protocol might return the original circuit unchanged.

Parameters:

cirq_circuit (cirq.Circuit) – The input quantum circuit to be modified.

Returns:

A sequence (e.g., list or tuple) of

Cirq circuits to be executed.

Return type:

Sequence[cirq.Circuit]

postprocess_results(results)

Applies post-processing (e.g., extrapolation, filtering) to the results obtained from executing the modified circuits.

This method takes the raw output from quantum circuit executions (typically a sequence of expectation values or probabilities) and applies the core error mitigation logic to produce a single, mitigated result.

Parameters:

results (Sequence[float]) – A sequence of floating-point results, corresponding to the executions of the circuits returned by modify_circuit.

Returns:

The single, mitigated result after post-processing.

Return type:

float

QEM Protocol Architecture

All error mitigation protocols in Divi inherit from the QEMProtocol base class, providing a consistent interface for different mitigation techniques.

class QEMProtocol

Bases: ABC

Abstract Base Class for Quantum Error Mitigation (QEM) protocols.

All concrete QEM protocols should inherit from this class and implement the abstract methods and properties. This ensures a consistent interface across different mitigation techniques.

abstract property name: str

abstract modify_circuit(cirq_circuit)

Modifies a given Cirq circuit into one or more new circuits required by the QEM protocol.

For example, a Zero Noise Extrapolation (ZNE) protocol might produce multiple scaled versions of the input circuit. A simple mitigation protocol might return the original circuit unchanged.

Parameters:

cirq_circuit (cirq.Circuit) – The input quantum circuit to be modified.

Returns:

A sequence (e.g., list or tuple) of

Cirq circuits to be executed.

Return type:

Sequence[cirq.Circuit]

abstract postprocess_results(results)

Applies post-processing (e.g., extrapolation, filtering) to the results obtained from executing the modified circuits.

This method takes the raw output from quantum circuit executions (typically a sequence of expectation values or probabilities) and applies the core error mitigation logic to produce a single, mitigated result.

Parameters:

results (Sequence[float]) – A sequence of floating-point results, corresponding to the executions of the circuits returned by modify_circuit.

Returns:

The single, mitigated result after post-processing.

Return type:

float

Zero Noise Extrapolation (ZNE)

class ZNE(scale_factors, folding_fn, extrapolation_factory)

Bases: QEMProtocol

Implements the Zero Noise Extrapolation (ZNE) quantum error mitigation protocol.

This protocol uses Mitiq’s functionalities to construct noise-scaled circuits and then extrapolate to the zero-noise limit based on the obtained results.

Initializes a ZNE protocol instance.

Parameters:

• scale_factors (Sequence[float]) – A sequence of noise scale factors to be applied to the circuits. These factors typically range from 1.0 upwards.

• folding_fn (Callable) – A callable (e.g., a functools.partial object) that defines how the circuit should be “folded” to increase noise. This function must accept a cirq.Circuit and a float (scale factor) as its first two arguments.

• extrapolation_factory (mitiq.zne.inference.Factory) – An instance of Mitiq’s Factory class, which provides the extrapolation method.

Raises:

ValueError – If scale_factors is not a sequence of numbers, folding_fn is not callable, or extrapolation_factory is not an instance of mitiq.zne.inference.Factory.

__init__(scale_factors, folding_fn, extrapolation_factory)

Initializes a ZNE protocol instance.

Parameters:

• scale_factors (Sequence[float]) – A sequence of noise scale factors to be applied to the circuits. These factors typically range from 1.0 upwards.

• folding_fn (Callable) – A callable (e.g., a functools.partial object) that defines how the circuit should be “folded” to increase noise. This function must accept a cirq.Circuit and a float (scale factor) as its first two arguments.

• extrapolation_factory (mitiq.zne.inference.Factory) – An instance of Mitiq’s Factory class, which provides the extrapolation method.

Raises:

ValueError – If scale_factors is not a sequence of numbers, folding_fn is not callable, or extrapolation_factory is not an instance of mitiq.zne.inference.Factory.

property name: str

property scale_factors: Sequence[float]

property folding_fn

property extrapolation_factory

modify_circuit(cirq_circuit)

Modifies a given Cirq circuit into one or more new circuits required by the QEM protocol.

For example, a Zero Noise Extrapolation (ZNE) protocol might produce multiple scaled versions of the input circuit. A simple mitigation protocol might return the original circuit unchanged.

Parameters:

cirq_circuit (cirq.Circuit) – The input quantum circuit to be modified.

Returns:

A sequence (e.g., list or tuple) of

Cirq circuits to be executed.

Return type:

Sequence[cirq.Circuit]

postprocess_results(results)

Applies post-processing (e.g., extrapolation, filtering) to the results obtained from executing the modified circuits.

This method takes the raw output from quantum circuit executions (typically a sequence of expectation values or probabilities) and applies the core error mitigation logic to produce a single, mitigated result.

Parameters:

results (Sequence[float]) – A sequence of floating-point results, corresponding to the executions of the circuits returned by modify_circuit.

Returns:

The single, mitigated result after post-processing.

Return type:

float

No Mitigation Protocol

class _NoMitigation

Bases: QEMProtocol

A dummy default mitigation protocol.

property name: str

modify_circuit(cirq_circuit)

Modifies a given Cirq circuit into one or more new circuits required by the QEM protocol.

For example, a Zero Noise Extrapolation (ZNE) protocol might produce multiple scaled versions of the input circuit. A simple mitigation protocol might return the original circuit unchanged.

Parameters:

cirq_circuit (cirq.Circuit) – The input quantum circuit to be modified.

Returns:

A sequence (e.g., list or tuple) of

Cirq circuits to be executed.

Return type:

Sequence[cirq.Circuit]

postprocess_results(results)

Returns the single result provided, ensuring only one result is given.

If multiple results are provided, it raises a RuntimeError, as this protocol expects a single measurement outcome for its input circuit.

Parameters:

results (Sequence[float]) – A sequence containing a single floating-point result.

Returns:

The single result from the sequence.

Return type:

float

Raises:

RuntimeError – If more than one result is provided.