OpenQASM 3

qiskit.qasm3

Qiskit provides some tools for converting between OpenQASM 3 representations of quantum programs, and the QuantumCircuit class. These will continue to evolve as Qiskit’s support for the dynamic-circuit capabilities expressed by OpenQASM 3 increases.

Exporting to OpenQASM 3

The high-level functions are simply dump() and dumps(), which respectively export to a file (given as a filename) and to a Python string.

dump

dumps

Both of these exporter functions are single-use wrappers around the main Exporter class. For more complex exporting needs, including dumping multiple circuits in a single session, it may be more convenient or faster to use the complete interface.

Exporter

All of these interfaces will raise QASM3ExporterError on failure.

QASM3ExporterError

Experimental features

The OpenQASM 3 language is still evolving as hardware capabilities improve, so there is no final syntax that Qiskit can reliably target. In order to represent the evolving language, we will sometimes release features before formal standardization, which may need to change as the review process in the OpenQASM 3 design committees progresses. By default, the exporters will only support standardised features of the language. To enable these early-release features, use the experimental keyword argument of dump() and dumps(). The available feature flags are:

ExperimentalFeatures

switch (i) {
    case 0:
    case 1:
        x $0;
    break;
 
    case 2: {
        z $0;
    }
    break;
 
    default: {
        cx $0, $1;
    }
    break;
}

switch (i) {
    case 0, 1 {
        x $0;
    }
    case 2 {
        z $0;
    }
    default {
        cx $0, $1;
    }
}

If you want to enable multiple experimental features, you should combine the flags using the | operator, such as flag1 | flag2.

For example, to perform an export using the early semantics of switch support:

from qiskit import qasm3, QuantumCircuit, QuantumRegister, ClassicalRegister
 
# Build the circuit
qreg = QuantumRegister(3)
creg = ClassicalRegister(3)
qc = QuantumCircuit(qreg, creg)
with qc.switch(creg) as case:
    with case(0):
        qc.x(0)
    with case(1, 2):
        qc.x(1)
    with case(case.DEFAULT):
        qc.x(2)
 
# Export to an OpenQASM 3 string.
qasm_string = qasm3.dumps(qc, experimental=qasm3.ExperimentalFeatures.SWITCH_CASE_V1)

Importing from OpenQASM 3

Currently only two high-level functions are offered, as Qiskit support for importing from OpenQASM 3 is in its infancy, and the implementation is expected to change significantly. The two functions are load() and loads(), which are direct counterparts of dump() and dumps(), respectively loading a program indirectly from a named file and directly from a given string.

pip install qiskit[qasm3-import]

load

loads

Both of these two functions raise QASM3ImporterError on failure.

QASM3ImporterError

For example, we can define a quantum program using OpenQASM 3, and use loads() to directly convert it into a QuantumCircuit:

import qiskit.qasm3
 
program = """
    OPENQASM 3.0;
    include "stdgates.inc";
 
    input float[64] a;
    qubit[3] q;
    bit[2] mid;
    bit[3] out;
 
    let aliased = q[0:1];
 
    gate my_gate(a) c, t {
      gphase(a / 2);
      ry(a) c;
      cx c, t;
    }
    gate my_phase(a) c {
      ctrl @ inv @ gphase(a) c;
    }
 
    my_gate(a * 2) aliased[0], q[{1, 2}][0];
    measure q[0] -> mid[0];
    measure q[1] -> mid[1];
 
    while (mid == "00") {
      reset q[0];
      reset q[1];
      my_gate(a) q[0], q[1];
      my_phase(a - pi/2) q[1];
      mid[0] = measure q[0];
      mid[1] = measure q[1];
    }
 
    if (mid[0]) {
      let inner_alias = q[{0, 1}];
      reset inner_alias;
    }
 
    out = measure q;
"""
circuit = qiskit.qasm3.loads(program)
circuit.draw("mpl")

Experimental import interface

The import functions given above rely on the ANTLR-based reference parser from the OpenQASM project itself, which is more intended as a language reference than a performant parser. You need to have the extension qiskit-qasm3-import installed to use it.

Qiskit is developing a native parser, written in Rust, which is available as part of the core Qiskit package. This parser is still in its early experimental stages, so is missing features and its interface is changing and expanding, but it is typically orders of magnitude more performant for the subset of OpenQASM 3 it currently supports, and its internals produce better error diagnostics on parsing failures.

You can use the experimental interface immediately, with similar functions to the main interface above:

load_experimental

loads_experimental

These two functions are both experimental, meaning they issue an ExperimentalWarning on usage, and their interfaces may be subject to change within the Qiskit 1.x release series. In particular, the native parser may be promoted to be the default version of load() and loads(). If you are happy to accept the risk of using the experimental interface, you can disable the warning by doing:

import warnings
from qiskit.exceptions import ExperimentalWarning
 
warnings.filterwarnings("ignore", category=ExperimentalWarning, module="qiskit.qasm3")

These two functions allow for specifying include paths as an iterable of paths, and for specifying custom Python constructors to use for particular gates. These custom constructors are specified by using the CustomGate object:

CustomGate

In custom_gates is not given, Qiskit will attempt to use its standard-library gate objects for the gates defined in OpenQASM 3 standard library file stdgates.inc. This sequence of gates is available on this module, if you wish to build on top of it:

qiskit.qasm3.STDGATES_INC_GATES