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(circuit, stream, **kwargs)

Serialize a QuantumCircuit object as a OpenQASM3 stream to file-like object.

Parameters

• circuit (QuantumCircuit) – Circuit to serialize.

• stream (TextIOBase) – stream-like object to dump the OpenQASM3 serialization

• **kwargs – Arguments for the Exporter constructor.

Return type

None

dumps(circuit, **kwargs)

Serialize a QuantumCircuit object in an OpenQASM3 string.

Parameters

• circuit (QuantumCircuit) – Circuit to serialize.

• **kwargs – Arguments for the Exporter constructor.

Returns

The OpenQASM3 serialization

Return type

str

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.

class Exporter(includes=('stdgates.inc',), basis_gates=('U',), disable_constants=False, alias_classical_registers=False, indent='  ')

QASM3 exporter main class.

Parameters

• includes (Sequence[str]) – the filenames that should be emitted as includes. These files will be parsed for gates, and any objects dumped from this exporter will use those definitions where possible.

• basis_gates (Sequence[str]) – the basic defined gate set of the backend.

• disable_constants (bool) – if True, always emit floating-point constants for numeric parameter values. If False (the default), then values close to multiples of QASM 3 constants (pi, euler, and tau) will be emitted in terms of those constants instead, potentially improving accuracy in the output.

• alias_classical_registers (bool) – If True, then classical bit and classical register declarations will look similar to quantum declarations, where the whole set of bits will be declared in a flat array, and the registers will just be aliases to collections of these bits. This is inefficient for running OpenQASM 3 programs, however, and may not be well supported on backends. Instead, the default behaviour of False means that individual classical registers will gain their own bit[size] register; declarations, and loose Clbits will go onto their own declaration. In this form, each Clbit must be in either zero or one ClassicalRegisters.

• indent (str) – the indentation string to use for each level within an indented block. Can be set to the empty string to disable indentation.

dump(circuit, stream)

Convert the circuit to QASM 3, dumping the result to a file or text stream.

dumps(circuit)

Convert the circuit to QASM 3, returning the result as a string.

All of these interfaces will raise QASM3ExporterError on failure.

exception QASM3ExporterError(*message)

An error raised during running the OpenQASM 3 exporter.

Set the error message.

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.

Note

While we are still in the exploratory release period, to use either function, the package qiskit_qasm3_import must be installed. This can be done by installing Qiskit Terra with the qasm3-import extra, such as by:

pip install qiskit-terra[qasm3-import]

We expect that this functionality will eventually be merged into core Terra, and no longer require an optional import, but we do not yet have a timeline for this.

load(filename)

Load an OpenQASM 3 program from the file filename.

Parameters

filename (str) – the filename to load the program from.

Returns

a circuit representation of the OpenQASM 3 program.

Return type

QuantumCircuit

Raises

QASM3ImporterError – if the OpenQASM 3 file is invalid, or cannot be represented by a QuantumCircuit.

loads(program)

Load an OpenQASM 3 program from the given string.

Parameters

program (str) – the OpenQASM 3 program.

Returns

a circuit representation of the OpenQASM 3 program.

Return type

QuantumCircuit

Raises

QASM3ImporterError – if the OpenQASM 3 file is invalid, or cannot be represented by a QuantumCircuit.

Both of these two functions raise QASM3ImporterError on failure.

exception QASM3ImporterError(*message)

An error raised during the OpenQASM 3 importer.

Set the error message.

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")

(Source code)