qiskit 1.0.0b1__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

qiskit/qasm2/parse.py

@@ -0,0 +1,403 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Python-space bytecode interpreter for the output of the main Rust parser logic."""
+
+import dataclasses
+import math
+from typing import Iterable, Callable
+
+from qiskit.circuit import (
+    Barrier,
+    CircuitInstruction,
+    ClassicalRegister,
+    Delay,
+    Gate,
+    Instruction,
+    Measure,
+    QuantumCircuit,
+    QuantumRegister,
+    Qubit,
+    Reset,
+    library as lib,
+)
+
+# This is the same C-extension problems as described in the `__init__.py` disable near the
+# `_qasm2` import.
+from qiskit._qasm2 import (  # pylint: disable=no-name-in-module
+    OpCode,
+    UnaryOpCode,
+    BinaryOpCode,
+    CustomClassical,
+    ExprConstant,
+    ExprArgument,
+    ExprUnary,
+    ExprBinary,
+    ExprCustom,
+)
+from .exceptions import QASM2ParseError
+
+# Constructors of the form `*params -> Gate` for the special 'qelib1.inc' include.  This is
+# essentially a pre-parsed state for the file as given in the arXiv paper defining OQ2.
+QELIB1 = (
+    lib.U3Gate,
+    lib.U2Gate,
+    lib.U1Gate,
+    lib.CXGate,
+    # IGate in Terra < 0.24 is defined as a single-cycle delay, so is not strictly an identity.
+    # Instead we use a true no-op stand-in.
+    lambda: lib.UGate(0, 0, 0),
+    lib.XGate,
+    lib.YGate,
+    lib.ZGate,
+    lib.HGate,
+    lib.SGate,
+    lib.SdgGate,
+    lib.TGate,
+    lib.TdgGate,
+    lib.RXGate,
+    lib.RYGate,
+    lib.RZGate,
+    lib.CZGate,
+    lib.CYGate,
+    lib.CHGate,
+    lib.CCXGate,
+    lib.CRZGate,
+    lib.CU1Gate,
+    lib.CU3Gate,
+)
+
+
+@dataclasses.dataclass(frozen=True)
+class CustomInstruction:
+    """Information about a custom instruction that should be defined during the parse.
+
+    The ``name``, ``num_params`` and ``num_qubits`` fields are self-explanatory.  The
+    ``constructor`` field should be a callable object with signature ``*args -> Instruction``, where
+    each of the ``num_params`` ``args`` is a floating-point value.  Most of the built-in Qiskit gate
+    classes have this form.
+
+    There is a final ``builtin`` field.  This is optional, and if set true will cause the
+    instruction to be defined and available within the parsing, even if there is no definition in
+    any included OpenQASM 2 file.
+    """
+
+    name: str
+    num_params: int
+    num_qubits: int
+    # This should be `(float*) -> Instruction`, but the older version of Sphinx we're constrained to
+    # use in the Python 3.9 docs build chokes on it, so relax the hint.
+    constructor: Callable[..., Instruction]
+    builtin: bool = False
+
+
+def _generate_delay(time: float):
+    # This wrapper is just to ensure that the correct type of exception gets emitted; it would be
+    # unnecessarily spaghetti-ish to check every emitted instruction in Rust for integer
+    # compatibility, but only if its name is `delay` _and_ its constructor wraps Qiskit's `Delay`.
+    if int(time) != time:
+        raise QASM2ParseError("the custom 'delay' instruction can only accept an integer parameter")
+    return Delay(int(time), unit="dt")
+
+
+class _U0Gate(Gate):
+    def __init__(self, count):
+        if int(count) != count:
+            raise QASM2ParseError("the number of single-qubit delay lengths must be an integer")
+        super().__init__("u0", 1, [int(count)])
+
+    def _define(self):
+        self._definition = QuantumCircuit(1)
+        for _ in [None] * self.params[0]:
+            self._definition.id(0)
+
+
+LEGACY_CUSTOM_INSTRUCTIONS = (
+    CustomInstruction("u3", 3, 1, lib.U3Gate),
+    CustomInstruction("u2", 2, 1, lib.U2Gate),
+    CustomInstruction("u1", 1, 1, lib.U1Gate),
+    CustomInstruction("cx", 0, 2, lib.CXGate),
+    # The Qiskit parser emits IGate for 'id', even if that is not strictly accurate in Terra < 0.24.
+    CustomInstruction("id", 0, 1, lib.IGate),
+    CustomInstruction("u0", 1, 1, _U0Gate, builtin=True),
+    CustomInstruction("u", 3, 1, lib.UGate, builtin=True),
+    CustomInstruction("p", 1, 1, lib.PhaseGate, builtin=True),
+    CustomInstruction("x", 0, 1, lib.XGate),
+    CustomInstruction("y", 0, 1, lib.YGate),
+    CustomInstruction("z", 0, 1, lib.ZGate),
+    CustomInstruction("h", 0, 1, lib.HGate),
+    CustomInstruction("s", 0, 1, lib.SGate),
+    CustomInstruction("sdg", 0, 1, lib.SdgGate),
+    CustomInstruction("t", 0, 1, lib.TGate),
+    CustomInstruction("tdg", 0, 1, lib.TdgGate),
+    CustomInstruction("rx", 1, 1, lib.RXGate),
+    CustomInstruction("ry", 1, 1, lib.RYGate),
+    CustomInstruction("rz", 1, 1, lib.RZGate),
+    CustomInstruction("sx", 0, 1, lib.SXGate, builtin=True),
+    CustomInstruction("sxdg", 0, 1, lib.SXdgGate, builtin=True),
+    CustomInstruction("cz", 0, 2, lib.CZGate),
+    CustomInstruction("cy", 0, 2, lib.CYGate),
+    CustomInstruction("swap", 0, 2, lib.SwapGate, builtin=True),
+    CustomInstruction("ch", 0, 2, lib.CHGate),
+    CustomInstruction("ccx", 0, 3, lib.CCXGate),
+    CustomInstruction("cswap", 0, 3, lib.CSwapGate, builtin=True),
+    CustomInstruction("crx", 1, 2, lib.CRXGate, builtin=True),
+    CustomInstruction("cry", 1, 2, lib.CRYGate, builtin=True),
+    CustomInstruction("crz", 1, 2, lib.CRZGate),
+    CustomInstruction("cu1", 1, 2, lib.CU1Gate),
+    CustomInstruction("cp", 1, 2, lib.CPhaseGate, builtin=True),
+    CustomInstruction("cu3", 3, 2, lib.CU3Gate),
+    CustomInstruction("csx", 0, 2, lib.CSXGate, builtin=True),
+    CustomInstruction("cu", 4, 2, lib.CUGate, builtin=True),
+    CustomInstruction("rxx", 1, 2, lib.RXXGate, builtin=True),
+    CustomInstruction("rzz", 1, 2, lib.RZZGate, builtin=True),
+    CustomInstruction("rccx", 0, 3, lib.RCCXGate, builtin=True),
+    CustomInstruction("rc3x", 0, 4, lib.RC3XGate, builtin=True),
+    CustomInstruction("c3x", 0, 4, lib.C3XGate, builtin=True),
+    CustomInstruction("c3sqrtx", 0, 4, lib.C3SXGate, builtin=True),
+    CustomInstruction("c4x", 0, 5, lib.C4XGate, builtin=True),
+    CustomInstruction("delay", 1, 1, _generate_delay),
+)
+
+LEGACY_CUSTOM_CLASSICAL = (
+    CustomClassical("asin", 1, math.asin),
+    CustomClassical("acos", 1, math.acos),
+    CustomClassical("atan", 1, math.atan),
+)
+
+
+def from_bytecode(bytecode, custom_instructions: Iterable[CustomInstruction]):
+    """Loop through the Rust bytecode iterator `bytecode` producing a
+    :class:`~qiskit.circuit.QuantumCircuit` instance from it.  All the hard work is done in Rust
+    space where operations are faster; here, we're just about looping through the instructions as
+    fast as possible, doing as little calculation as we can in Python space.  The Python-space
+    components are the vast majority of the runtime.
+
+    The "bytecode", and so also this Python function, is very tightly coupled to the output of the
+    Rust parser.  The bytecode itself is largely defined by Rust; from Python space, the iterator is
+    over essentially a 2-tuple of `(opcode, operands)`.  The `operands` are fixed by Rust, and
+    assumed to be correct by this function.
+
+    The Rust code is responsible for all validation.  If this function causes any errors to be
+    raised by Qiskit (except perhaps for some symbolic manipulations of `Parameter` objects), we
+    should consider that a bug in the Rust code."""
+    # The method `QuantumCircuit._append` is a semi-public method, so isn't really subject to
+    # "protected access".
+    # pylint: disable=protected-access
+    qc = QuantumCircuit()
+    qubits = []
+    clbits = []
+    gates = []
+    has_u, has_cx = False, False
+    for custom in custom_instructions:
+        gates.append(custom.constructor)
+        if custom.name == "U":
+            has_u = True
+        elif custom.name == "CX":
+            has_cx = True
+    if not has_u:
+        gates.append(lib.UGate)
+    if not has_cx:
+        gates.append(lib.CXGate)
+    # Pull this out as an explicit iterator so we can manually advance the loop in `DeclareGate`
+    # contexts easily.
+    bc = iter(bytecode)
+    for op in bc:
+        # We have to check `op.opcode` so many times, it's worth pulling out the extra attribute
+        # access.  We should check the opcodes in order of their likelihood to be in the OQ2 program
+        # for speed.  Gate applications are by far the most common for long programs.  This function
+        # is deliberately long and does not use hashmaps or function lookups for speed in
+        # Python-space.
+        opcode = op.opcode
+        # `OpCode` is an `enum` in Rust, but its instances don't have the same singleton property as
+        # Python `enum.Enum` objects.
+        if opcode == OpCode.Gate:
+            gate_id, parameters, op_qubits = op.operands
+            qc._append(
+                CircuitInstruction(gates[gate_id](*parameters), [qubits[q] for q in op_qubits])
+            )
+        elif opcode == OpCode.ConditionedGate:
+            gate_id, parameters, op_qubits, creg, value = op.operands
+            gate = gates[gate_id](*parameters).c_if(qc.cregs[creg], value)
+            qc._append(CircuitInstruction(gate, [qubits[q] for q in op_qubits]))
+        elif opcode == OpCode.Measure:
+            qubit, clbit = op.operands
+            qc._append(CircuitInstruction(Measure(), (qubits[qubit],), (clbits[clbit],)))
+        elif opcode == OpCode.ConditionedMeasure:
+            qubit, clbit, creg, value = op.operands
+            measure = Measure().c_if(qc.cregs[creg], value)
+            qc._append(CircuitInstruction(measure, (qubits[qubit],), (clbits[clbit],)))
+        elif opcode == OpCode.Reset:
+            qc._append(CircuitInstruction(Reset(), (qubits[op.operands[0]],)))
+        elif opcode == OpCode.ConditionedReset:
+            qubit, creg, value = op.operands
+            reset = Reset().c_if(qc.cregs[creg], value)
+            qc._append(CircuitInstruction(reset, (qubits[qubit],)))
+        elif opcode == OpCode.Barrier:
+            op_qubits = op.operands[0]
+            qc._append(CircuitInstruction(Barrier(len(op_qubits)), [qubits[q] for q in op_qubits]))
+        elif opcode == OpCode.DeclareQreg:
+            name, size = op.operands
+            register = QuantumRegister(size, name)
+            qubits += register[:]
+            qc.add_register(register)
+        elif opcode == OpCode.DeclareCreg:
+            name, size = op.operands
+            register = ClassicalRegister(size, name)
+            clbits += register[:]
+            qc.add_register(register)
+        elif opcode == OpCode.SpecialInclude:
+            # Including `qelib1.inc` is pretty much universal, and we treat its gates as having
+            # special relationships to the Qiskit ones, so we don't actually parse it; we just
+            # short-circuit to add its pre-calculated content to our state.
+            (indices,) = op.operands
+            for index in indices:
+                gates.append(QELIB1[index])
+        elif opcode == OpCode.DeclareGate:
+            name, num_qubits = op.operands
+            # This inner loop advances the iterator of the outer loop as well, since `bc` is a
+            # manually created iterator, rather than an implicit one from the first loop.
+            inner_bc = []
+            for inner_op in bc:
+                if inner_op.opcode == OpCode.EndDeclareGate:
+                    break
+                inner_bc.append(inner_op)
+            # Technically there's a quadratic dependency in the number of gates here, which could be
+            # fixed by just sharing a reference to `gates` rather than recreating a new object.
+            # Gates can't ever be removed from the list, so it wouldn't get out-of-date, though
+            # there's a minor risk of somewhere accidentally mutating it instead, and in practice
+            # the cost shouldn't really matter.
+            gates.append(_gate_builder(name, num_qubits, tuple(gates), inner_bc))
+        elif opcode == OpCode.DeclareOpaque:
+            name, num_qubits = op.operands
+            gates.append(_opaque_builder(name, num_qubits))
+        else:
+            raise ValueError(f"invalid operation: {op}")
+    return qc
+
+
+class _DefinedGate(Gate):
+    """A gate object defined by a `gate` statement in an OpenQASM 2 program.  This object lazily
+    binds its parameters to its definition, so it is only synthesised when required."""
+
+    def __init__(self, name, num_qubits, params, gates, bytecode):
+        self._gates = gates
+        self._bytecode = bytecode
+        super().__init__(name, num_qubits, list(params))
+
+    def _define(self):
+        # This is a stripped-down version of the bytecode interpreter; there's very few opcodes that
+        # we actually need to handle within gate bodies.
+        # pylint: disable=protected-access
+        qubits = [Qubit() for _ in [None] * self.num_qubits]
+        qc = QuantumCircuit(qubits)
+        for op in self._bytecode:
+            if op.opcode == OpCode.Gate:
+                gate_id, args, op_qubits = op.operands
+                qc._append(
+                    CircuitInstruction(
+                        self._gates[gate_id](*(_evaluate_argument(a, self.params) for a in args)),
+                        [qubits[q] for q in op_qubits],
+                    )
+                )
+            elif op.opcode == OpCode.Barrier:
+                op_qubits = op.operands[0]
+                qc._append(
+                    CircuitInstruction(Barrier(len(op_qubits)), [qubits[q] for q in op_qubits])
+                )
+            else:
+                raise ValueError(f"received invalid bytecode to build gate: {op}")
+        self._definition = qc
+
+    # It's fiddly to implement pickling for PyO3 types (the bytecode stream), so instead if we need
+    # to pickle ourselves, we just eagerly create the definition and pickle that.
+
+    def __getstate__(self):
+        return (self.name, self.num_qubits, self.params, self.definition, self.condition)
+
+    def __setstate__(self, state):
+        name, num_qubits, params, definition, condition = state
+        super().__init__(name, num_qubits, params)
+        self._gates = ()
+        self._bytecode = ()
+        self._definition = definition
+        self._condition = condition
+
+
+def _gate_builder(name, num_qubits, known_gates, bytecode):
+    """Create a gate-builder function of the signature `*params -> Gate` for a gate with a given
+    `name`.  This produces a `_DefinedGate` class, whose `_define` method runs through the given
+    `bytecode` using the current list of `known_gates` to interpret the gate indices.
+
+    The indirection here is mostly needed to correctly close over `known_gates` and `bytecode`."""
+
+    def definer(*params):
+        return _DefinedGate(name, num_qubits, params, known_gates, tuple(bytecode))
+
+    return definer
+
+
+def _opaque_builder(name, num_qubits):
+    """Create a gate-builder function of the signature `*params -> Gate` for an opaque gate with a
+    given `name`, which takes the given numbers of qubits."""
+
+    def definer(*params):
+        return Gate(name, num_qubits, params)
+
+    return definer
+
+
+# The natural way to reduce returns in this function would be to use a lookup table for the opcodes,
+# but the PyO3 enum entities aren't (currently) hashable.
+def _evaluate_argument(expr, parameters):  # pylint: disable=too-many-return-statements
+    """Inner recursive function to calculate the value of a mathematical expression given the
+    concrete values in the `parameters` field."""
+    if isinstance(expr, ExprConstant):
+        return expr.value
+    if isinstance(expr, ExprArgument):
+        return parameters[expr.index]
+    if isinstance(expr, ExprUnary):
+        inner = _evaluate_argument(expr.argument, parameters)
+        opcode = expr.opcode
+        if opcode == UnaryOpCode.Negate:
+            return -inner
+        if opcode == UnaryOpCode.Cos:
+            return math.cos(inner)
+        if opcode == UnaryOpCode.Exp:
+            return math.exp(inner)
+        if opcode == UnaryOpCode.Ln:
+            return math.log(inner)
+        if opcode == UnaryOpCode.Sin:
+            return math.sin(inner)
+        if opcode == UnaryOpCode.Sqrt:
+            return math.sqrt(inner)
+        if opcode == UnaryOpCode.Tan:
+            return math.tan(inner)
+        raise ValueError(f"unhandled unary opcode: {opcode}")
+    if isinstance(expr, ExprBinary):
+        left = _evaluate_argument(expr.left, parameters)
+        right = _evaluate_argument(expr.right, parameters)
+        opcode = expr.opcode
+        if opcode == BinaryOpCode.Add:
+            return left + right
+        if opcode == BinaryOpCode.Subtract:
+            return left - right
+        if opcode == BinaryOpCode.Multiply:
+            return left * right
+        if opcode == BinaryOpCode.Divide:
+            return left / right
+        if opcode == BinaryOpCode.Power:
+            return left**right
+        raise ValueError(f"unhandled binary opcode: {opcode}")
+    if isinstance(expr, ExprCustom):
+        return expr.callable(*(_evaluate_argument(x, parameters) for x in expr.arguments))
+    raise ValueError(f"unhandled expression type: {expr}")

qiskit/qasm3/__init__.py

@@ -0,0 +1,255 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+================================
+OpenQASM 3 (:mod:`qiskit.qasm3`)
+================================
+
+.. currentmodule:: qiskit.qasm3
+
+Qiskit provides some tools for converting between `OpenQASM 3 <https://openqasm.com>`__
+representations of quantum programs, and the :class:`.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 :func:`dump` and :func:`dumps`, which respectively export to a
+file (given as a filename) and to a Python string.
+
+.. autofunction:: dump
+.. autofunction:: dumps
+
+Both of these exporter functions are single-use wrappers around the main :class:`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.
+
+.. autoclass:: Exporter
+    :members:
+
+All of these interfaces will raise :exc:`QASM3ExporterError` on failure.
+
+.. autoexception:: 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 :func:`dump` and :func:`dumps`.  The available feature flags
+are:
+
+.. autoclass:: ExperimentalFeatures
+    :members:
+
+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)
+
+
+.. note::
+
+    All features enabled by the experimental flags are naturally transient.  If it becomes necessary
+    to remove flags, they will be subject to `the standard Qiskit deprecation policy
+    <https://github.com/Qiskit/qiskit/blob/main/DEPRECATION.md>`__.  We will leave these experimental
+    flags in place for as long as is reasonable.
+
+    However, we cannot guarantee any support windows for *consumers* of OpenQASM 3 code generated
+    using these experimental flags, if the OpenQASM 3 language specification changes the proposal
+    that the flag is based on.  It is possible that any tool you are using to consume OpenQASM 3
+    code created using these flags may update or remove their support while Qiskit continues to
+    offer the flag.  You should not rely on the resultant experimental OpenQASM 3 code for long-term
+    storage of programs.
+
+
+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 :func:`load` and :func:`loads`, which are direct counterparts of :func:`dump` and :func:`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:
+
+    .. code-block:: text
+
+        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.
+
+.. autofunction:: load
+.. autofunction:: loads
+
+Both of these two functions raise :exc:`QASM3ImporterError` on failure.
+
+.. autoexception:: QASM3ImporterError
+
+For example, we can define a quantum program using OpenQASM 3, and use :func:`loads` to directly
+convert it into a :class:`.QuantumCircuit`:
+
+.. plot::
+    :include-source:
+
+    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")
+"""
+
+from qiskit.utils import optionals as _optionals
+
+from .experimental import ExperimentalFeatures
+from .exporter import Exporter
+from .exceptions import QASM3Error, QASM3ImporterError, QASM3ExporterError
+
+
+def dumps(circuit, **kwargs) -> str:
+    """Serialize a :class:`~qiskit.circuit.QuantumCircuit` object in an OpenQASM 3 string.
+
+    Args:
+        circuit (QuantumCircuit): Circuit to serialize.
+        **kwargs: Arguments for the :obj:`.Exporter` constructor.
+
+    Returns:
+        str: The OpenQASM 3 serialization
+    """
+    return Exporter(**kwargs).dumps(circuit)
+
+
+def dump(circuit, stream, **kwargs) -> None:
+    """Serialize a :class:`~qiskit.circuit.QuantumCircuit` object as an OpenQASM 3 stream to
+    file-like object.
+
+    Args:
+        circuit (QuantumCircuit): Circuit to serialize.
+        stream (TextIOBase): stream-like object to dump the OpenQASM 3 serialization
+        **kwargs: Arguments for the :obj:`.Exporter` constructor.
+
+    """
+    Exporter(**kwargs).dump(circuit, stream)
+
+
+@_optionals.HAS_QASM3_IMPORT.require_in_call("loading from OpenQASM 3")
+def load(filename: str):
+    """Load an OpenQASM 3 program from the file ``filename``.
+
+    Args:
+        filename: the filename to load the program from.
+
+    Returns:
+        QuantumCircuit: a circuit representation of the OpenQASM 3 program.
+
+    Raises:
+        QASM3ImporterError: if the OpenQASM 3 file is invalid, or cannot be represented by a
+            :class:`.QuantumCircuit`.
+    """
+
+    import qiskit_qasm3_import
+
+    with open(filename, "r") as fptr:
+        program = fptr.read()
+    try:
+        return qiskit_qasm3_import.parse(program)
+    except qiskit_qasm3_import.ConversionError as exc:
+        raise QASM3ImporterError(str(exc)) from exc
+
+
+@_optionals.HAS_QASM3_IMPORT.require_in_call("loading from OpenQASM 3")
+def loads(program: str):
+    """Load an OpenQASM 3 program from the given string.
+
+    Args:
+        program: the OpenQASM 3 program.
+
+    Returns:
+        QuantumCircuit: a circuit representation of the OpenQASM 3 program.
+
+    Raises:
+        QASM3ImporterError: if the OpenQASM 3 file is invalid, or cannot be represented by a
+            :class:`.QuantumCircuit`.
+    """
+
+    import qiskit_qasm3_import
+
+    try:
+        return qiskit_qasm3_import.parse(program)
+    except qiskit_qasm3_import.ConversionError as exc:
+        raise QASM3ImporterError(str(exc)) from exc