Add support for overriding instructions

This supports users overriding the objects that get emitted for any
given quantum instruction in an OpenQASM 2 input.  This includes both
"custom" instructions that still need to be defined by the OpenQASM 2
file (with a matching signature, but gate bodies are ignored), and
"builtins", which are automatically available, but will not raise an
error if a compatible signature declaration is given.

This allows us to expose a `QISKIT_CUSTOM_INSTRUCTIONS` tuple, which
contains all the `qelib1.inc` additions that Terra currently makes as
built-ins.  This is not _quite_ the same behaviour as Terra (since it
technically still needs to see a declaration for each custom gate to
make it available), but in practice will be largely the same.

This implementation retains type safety in the custom instructions,
unlike Terra.  Terra will ignore whatever the signature of the
definition is, and still attempt to use the same custom objects.  This
can cause them to raise exceptions due to being constructed incorrectly.

Author: jakelishman

docs/changelog.rst

@@ -2,6 +2,19 @@
 Changelog
 =========
 
+Unreleased
+==========
+
+* Added support for specifying custom instructions, both builtin and requiring definitions
+  inside the OpenQASM 2 file.  This is the `custom_instructions` parameter to :func:`.load`
+  and :func:`.loads`.
+
+* Added a data element :data:`.QISKIT_CUSTOM_INSTRUCTIONS` that can be passed to
+  `custom_instructions` to cause :mod:`qiskit_qasm2` to :ref:`mostly emulate the behaviour of the
+  Qiskit methods <qiskit-compatibility>` :meth:`QuantumCircuit.from_qasm_str()
+  <qiskit.circuit.QuantumCircuit.from_qasm_str>` and
+  :meth:`~qiskit.circuit.QuantumCircuit.from_qasm_file`.
+
 0.2.0 (2023-01-09)
 ==================
 

docs/parse.rst

@@ -20,8 +20,102 @@ specially; it is always found before looking in the include path, and contains e
 of the `paper describing the OpenQASM 2 language <https://arxiv.org/abs/1707.03429>`__.  The gates
 in this include file are mapped to standard gates provided by Qiskit.
 
+You can extend the OpenQASM 2 language by passing an iterable of information on custom instructions
+as the argument `custom_instructions`.  In files that have compatible definitions for these
+instructions, the given `constructor` will be used in place of whatever other handling
+:mod:`qiskit_qasm` would have done.  These instructions may optionally be marked as `builtin`, which
+causes them to not require an ``opaque`` or ``gate`` declaration, but they will silently ignore a
+compatible declaration.  Either way, it is an error to provide a custom instruction that has a
+different number of parameters or qubits as a defined instruction in a parsed program.  Each element
+of the argument iterable should be a particular data class:
+
+.. autoclass:: CustomInstruction
+
 In cases where the lexer or parser fails due to an invalid OpenQASM 2 file, the conversion functions
 will raise an error with a message explaining what the failure is, and where in the file it
 occurred.
 
 .. autoexception:: QASM2ParseError
+
+
+.. _qiskit-compatibility:
+
+Qiskit Compatibility
+====================
+
+Qiskit's :meth:`QuantumCircuit.from_qasm_str() <qiskit.circuit.QuantumCircuit.from_qasm_str>` and
+:meth:`~qiskit.circuit.QuantumCircuit.from_qasm_file` have a few additions on top of the raw
+specification, as Qiskit originally tried to use OpenQASM 2 as a sort of serialisation format, and
+expanded their behaviour as Qiskit expanded.  This parser under all its defaults implements the
+specification more strictly.
+
+In particular, in the Qiskit importers:
+
+* the `include_path` is:
+    1. ``<qiskit>/qasm/lib``, where ``<qiskit>`` is the root of the installed ``qiskit`` package;
+    2. the current working directory.
+
+* there are additional instructions defined in ``qelib1.inc``:
+    ``csx a, b``
+      Controlled :math:`\sqrt X` gate, corresponding to :class:`~qiskit.circuit.library.CSXGate`.
+
+    ``cu(theta, phi, lambda, gamma) c, t``
+      The four-parameter version of a controlled-:math:`U`, corresponding to
+      :class:`~qiskit.circuit.library.CUGate`.
+
+    ``rxx(theta) a, b``
+      Two-qubit rotation arond the :math:`XX` axis, corresponding to
+      :class:`~qiskit.circuit.library.RXXGate`.
+
+    ``rzz(theta) a, b``
+      Two-qubit rotation arond the :math:`ZZ` axis, corresponding to
+      :class:`~qiskit.circuit.library.RZZGate`.
+
+    ``rccx a, b, c``
+      The double-controlled :math:`X` gate, but with relative phase differences over the standard
+      Toffoli gate.  This *should* correspond to the Qiskit gate
+      :class:`~qiskit.circuit.library.RCCXGate`, but the Qiskit converter won't actually output this
+      type.
+
+    ``rc3x a, b, c, d``
+      The triple-controlled :math:`X` gate, but with relative phase differences over the standard
+      definition.  *Should* correspond to :class:`~qiskit.circuit.library.RC3XGate`.
+
+    ``c3x a, b, c, d``
+      The triple-controlled :math:`X` gate, corresponding to :class:`~qiskit.circuit.library.C3XGate`.
+
+    ``c3sqrtx a, b, c, d``
+      The triple-controlled :math:`\sqrt X` gate.  *Should* correspond to
+      :class:`~qiskit.circuit.library.C3SXGate`.
+
+    ``c4x a, b, c, d, e``
+      The quadruple-controlled :math:`X` gate.  *Should* correspond to
+      :class:`~qiskit.circuit.library.C4XGate`.
+
+* if *any* ``opaque`` or ``gate`` definition is given for the name ``delay``, they will attempt to
+  output a :class:`~qiskit.circuit.Delay` instruction at each call.  To function, this expects a
+  definition compatible with ``opaque delay(t) q;``, where the time ``t`` is given in units of
+  ``dt``.  The importer will raise an error on calls to the instruction if there are actually not
+  exactly one parameter and one qubit, or if the parameter is not integer-valued.
+
+You can emulate this behaviour in :func:`load` and :func:`loads` by setting `include_path`
+appropriately (try inspecting the variable ``qiskit.__file__`` to find the installed location), and
+by passing a list of :class:`CustomInstruction` instances for each of the custom gates you care
+about.  To make things easier, we make a tuple available containing all the above instructions
+(using the correspondences that Qiskit forgets as well) that you can supply to
+`custom_instructions`.
+
+.. py:data:: QISKIT_CUSTOM_INSTRUCTIONS
+
+   A tuple containing the extra `custom_instructions` that Qiskit's built-in converters use if
+   ``qelib1.inc`` is included, and there is any definition of a ``delay`` instruction.  The gates
+   in the paper version of ``qelib1.inc`` and ``delay`` all require a compatible declaration
+   statement to be present within the OpenQASM 2 program, but Qiskit's additions are all marked as
+   builtins since they are not actually present in any include file this parser sees.
+
+On *all* the gates defined in Qiskit's version of ``qelib1.inc`` and the ``delay`` instruction, it
+does not matter how the gates are actually defined and used, Qiskit will always attempt to output
+its custom objects for them.  This can result in errors during the circuit construction, even after
+a successful parse.  There is no way to emulate this buggy behaviour in :mod:`qiskit_qasm2`; only an
+``include "qelib1.inc";`` statement or the `custom_instructions` argument can cause built-in Qiskit
+instructions to be used, and the signatures of these match each other.

setup.cfg

@@ -20,6 +20,7 @@ package_dir =
 include_package_data = True
 install_requires =
     qiskit-terra>=0.21.0
+    typing_extensions>=4.1.0
 zip_safe = False
 
 [options.packages.find]

src-python/qiskit_qasm2/__init__.py

@@ -5,8 +5,9 @@
 with open(Path(__file__).parent / "VERSION", "r", encoding="utf-8") as _version_file:
     __version__ = _version_file.read().strip()
 
-from . import core, parse
+from . import core as _core, parse as _parse  # pylint: disable=no-name-in-module
 from .core import QASM2ParseError
+from .parse import CustomInstruction, QISKIT_CUSTOM_INSTRUCTIONS
 
 
 def _normalize_path(path: Union[str, os.PathLike]) -> str:
@@ -21,7 +22,11 @@ def _normalize_path(path: Union[str, os.PathLike]) -> str:
     return str(path)
 
 
-def loads(string: str, include_path: Iterable[Union[str, os.PathLike]] = (".",)):
+def loads(
+    string: str,
+    include_path: Iterable[Union[str, os.PathLike]] = (".",),
+    custom_instructions: Iterable[CustomInstruction] = (),
+):
     """Parse an OpenQASM 2 program from a string into a :class:`~qiskit.circuit.QuantumCircuit`.
 
     :param string: The OpenQASM 2 program in a string.
@@ -30,15 +35,25 @@ def loads(string: str, include_path: Iterable[Union[str, os.PathLike]] = (".",))
     :return: A circuit object representing the same OpenQASM 2 program.
     :rtype: ~qiskit.circuit.QuantumCircuit
     """
-    return parse.from_bytecode(
-        core.bytecode_from_string(string, [_normalize_path(path) for path in include_path])
+    custom_instructions = list(custom_instructions)
+    return _parse.from_bytecode(
+        _core.bytecode_from_string(
+            string,
+            [_normalize_path(path) for path in include_path],
+            [
+                _core.CustomInstruction(x.name, x.n_params, x.n_qubits, x.builtin)
+                for x in custom_instructions
+            ],
+        ),
+        custom_instructions,
     )
 
 
 def load(
     filename: Union[str, os.PathLike],
     include_path: Iterable[Union[str, os.PathLike]] = (".",),
     include_input_directory: Optional[Literal["append", "prepend"]] = "append",
+    custom_instructions: Iterable[CustomInstruction] = (),
 ):
     """Parse an OpenQASM 2 program from a file into a :class:`~qiskit.circuit.QuantumCircuit`.  The
     given path should be ASCII or UTF-8 encoded, and contain the OpenQASM 2 program.
@@ -65,4 +80,15 @@ def load(
             f"unknown value for include_input_directory: '{include_input_directory}'."
             " Valid values are '\"append\"', '\"prepend\"' and 'None'."
         )
-    return parse.from_bytecode(core.bytecode_from_file(_normalize_path(filename), include_path))
+    custom_instructions = tuple(custom_instructions)
+    return _parse.from_bytecode(
+        _core.bytecode_from_file(
+            _normalize_path(filename),
+            include_path,
+            [
+                _core.CustomInstruction(x.name, x.n_params, x.n_qubits, x.builtin)
+                for x in custom_instructions
+            ],
+        ),
+        custom_instructions,
+    )

src-python/qiskit_qasm2/parse.py

@@ -1,15 +1,21 @@
+import dataclasses
 import math
+from typing import Iterable, Callable, Tuple
+
+from typing_extensions import Unpack
 
 from qiskit.circuit import (
-    QuantumCircuit,
-    QuantumRegister,
-    ClassicalRegister,
-    Measure,
-    Reset,
     Barrier,
     CircuitInstruction,
+    ClassicalRegister,
+    Delay,
     Gate,
+    Instruction,
+    Measure,
+    QuantumCircuit,
+    QuantumRegister,
     Qubit,
+    Reset,
     library as lib,
 )
 from .core import (
@@ -20,6 +26,7 @@
     ExprArgument,
     ExprUnary,
     ExprBinary,
+    QASM2ParseError,
 )
 
 # Constructors of the form `*params -> Gate` for the special 'qelib1.inc' include.  This is
@@ -51,7 +58,73 @@
 )
 
 
-def from_bytecode(bytecode):
+@dataclasses.dataclass
+class CustomInstruction:
+    """Information about a custom instruction that should be defined during the parse.
+
+    The `name`, `n_params` and `n_qubits` fields are self-explanatory.  The `constructor` field
+    should be a callable object with signature ``*args -> Instruction``, where each of the
+    `n_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
+    n_params: int
+    n_qubits: int
+    constructor: Callable[[Unpack[Tuple[float, ...]]], Instruction]
+    builtin: bool = False
+
+
+def _generate_delay(t: 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(t) != t:
+        raise QASM2ParseError("the custom 'delay' instruction can only accept an integer parameter")
+    return Delay(int(t), unit="dt")
+
+
+QISKIT_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),
+    CustomInstruction("id", 0, 1, lambda: lib.UGate(0, 0, 0)),
+    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("cz", 0, 2, lib.CZGate),
+    CustomInstruction("cy", 0, 2, lib.CYGate),
+    CustomInstruction("ch", 0, 2, lib.CHGate),
+    CustomInstruction("ccx", 0, 3, lib.CCXGate),
+    CustomInstruction("crz", 1, 2, lib.CRZGate),
+    CustomInstruction("cu1", 1, 2, lib.CU1Gate),
+    CustomInstruction("cu3", 3, 2, lambda a, b, c: lib.CUGate(a, b, c, 0)),
+    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),
+)
+
+
+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
@@ -72,7 +145,18 @@ def from_bytecode(bytecode):
     qc = QuantumCircuit()
     qubits = []
     clbits = []
-    gates = [lib.UGate, lib.CXGate]
+    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)

src-rust/bytecode.rs

@@ -3,7 +3,7 @@ use pyo3::prelude::*;
 use crate::expr::Expr;
 use crate::lex;
 use crate::parse;
-use crate::QASM2ParseError;
+use crate::{CustomInstruction, QASM2ParseError};
 
 /// The Rust parser produces an iterator of these `Bytecode` instructions, which comprise an opcode
 /// integer for operation distinction, and a free-form tuple containing the operands.
@@ -283,12 +283,17 @@ pub struct BytecodeIterator {
 }
 
 impl BytecodeIterator {
-    pub fn new(tokens: lex::TokenStream, include_path: Vec<std::path::PathBuf>) -> Self {
-        BytecodeIterator {
-            parser_state: parse::State::new(tokens, include_path),
+    pub fn new(
+        tokens: lex::TokenStream,
+        include_path: Vec<std::path::PathBuf>,
+        custom_instructions: &[CustomInstruction],
+    ) -> PyResult<Self> {
+        Ok(BytecodeIterator {
+            parser_state: parse::State::new(tokens, include_path, custom_instructions)
+                .map_err(QASM2ParseError::new_err)?,
             buffer: vec![],
             buffer_used: 0,
-        }
+        })
     }
 }