qiskit 2.0.3__cp39-abi3-macosx_11_0_arm64.whl → 2.1.0__cp39-abi3-macosx_11_0_arm64.whl

qiskit/qasm3/__init__.py

@@ -226,7 +226,10 @@ available on this module, if you wish to build on top of it:
     ``stdgates.inc`` include file.
 """
 
+from __future__ import annotations
+
 import functools
+import typing
 import warnings
 
 from qiskit._accelerate import qasm3 as _qasm3
@@ -234,11 +237,13 @@ from qiskit.circuit import library
 from qiskit.exceptions import ExperimentalWarning
 from qiskit.utils import optionals as _optionals
 
+from .._accelerate.qasm3 import CustomGate
+from .exceptions import QASM3Error, QASM3ExporterError, QASM3ImporterError
 from .experimental import ExperimentalFeatures
 from .exporter import Exporter
-from .exceptions import QASM3Error, QASM3ImporterError, QASM3ExporterError
-from .._accelerate.qasm3 import CustomGate
 
+if typing.TYPE_CHECKING:
+    from qiskit.circuit import annotation, QuantumCircuit
 
 STDGATES_INC_GATES = (
     CustomGate(library.PhaseGate, "p", 1, 1),
@@ -303,11 +308,15 @@ def dump(circuit, stream, **kwargs) -> None:
 
 
 @_optionals.HAS_QASM3_IMPORT.require_in_call("loading from OpenQASM 3")
-def load(filename: str):
+def load(
+    filename: str, *, annotation_handlers: dict[str, annotation.OpenQASM3Serializer] | None = None
+) -> QuantumCircuit:
     """Load an OpenQASM 3 program from the file ``filename``.
 
     Args:
         filename: the filename to load the program from.
+        annotation_handlers: a mapping whose keys are (parent) namespaces and values are serializers
+            that can handle children of those namesapces.  Requires ``qiskit_qasm3_import>=0.6.0``.
 
     Returns:
         QuantumCircuit: a circuit representation of the OpenQASM 3 program.
@@ -315,24 +324,25 @@ def load(filename: str):
     Raises:
         QASM3ImporterError: if the OpenQASM 3 file is invalid, or cannot be represented by a
             :class:`.QuantumCircuit`.
-    """
-
-    import qiskit_qasm3_import
 
+    .. versionadded:: 2.1
+        The ``annotation_handlers`` argument.  This requires ``qiskit_qasm3_import>=0.6.0``.
+    """
     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
+    return loads(program, annotation_handlers=annotation_handlers)
 
 
 @_optionals.HAS_QASM3_IMPORT.require_in_call("loading from OpenQASM 3")
-def loads(program: str):
+def loads(
+    program: str, *, annotation_handlers: dict[str, annotation.OpenQASM3Serializer] | None = None
+) -> QuantumCircuit:
     """Load an OpenQASM 3 program from the given string.
 
     Args:
         program: the OpenQASM 3 program.
+        annotation_handlers: a mapping whose keys are (parent) namespaces and values are serializers
+            that can handle children of those namesapces.  Requires ``qiskit_qasm3_import>=0.6.0``.
 
     Returns:
         QuantumCircuit: a circuit representation of the OpenQASM 3 program.
@@ -340,12 +350,23 @@ def loads(program: str):
     Raises:
         QASM3ImporterError: if the OpenQASM 3 file is invalid, or cannot be represented by a
             :class:`.QuantumCircuit`.
+
+    .. versionadded:: 2.1
+        The ``annotation_handlers`` argument.  This requires ``qiskit_qasm3_import>=0.6.0``.
     """
 
     import qiskit_qasm3_import
 
+    kwargs = {}
+    if annotation_handlers is not None:
+        if getattr(qiskit_qasm3_import, "VERSION_PARTS", (0, 0)) < (0, 6):
+            raise QASM3ImporterError(
+                "need 'qiskit_qasm3_import>=0.6.0' to handle annotations, but you have "
+                + qiskit_qasm3_import.__version__
+            )
+        kwargs["annotation_handlers"] = annotation_handlers
     try:
-        return qiskit_qasm3_import.parse(program)
+        return qiskit_qasm3_import.parse(program, **kwargs)
     except qiskit_qasm3_import.ConversionError as exc:
         raise QASM3ImporterError(str(exc)) from exc
 
@@ -370,3 +391,76 @@ def load_experimental(pathlike_or_filelike, /, *, custom_gates=None, include_pat
         category=ExperimentalWarning,
     )
     return _qasm3.load(pathlike_or_filelike, custom_gates=custom_gates, include_path=include_path)
+
+
+@functools.wraps(_qasm3.dumps)
+def dumps_experimental(
+    circuit,
+    *,
+    includes=None,
+    basis_gates=None,
+    disable_constants=True,
+    alias_classical_registers=False,
+    allow_aliasing=False,
+    indent="  ",
+):
+    """<overridden by functools.wraps>"""
+    warnings.warn(
+        "This is an experimental version of serialization of a :class:`~qiskit.circuit.QuantumCircuit`"
+        " object in an OpenQASM 3 string."
+        " Beware that its interface might change, and it might be missing features.",
+        category=ExperimentalWarning,
+    )
+    if includes is None:
+        includes = ["stdgates.inc"]
+    if basis_gates is None:
+        basis_gates = ["U"]
+    return _qasm3.dumps(
+        circuit,
+        {
+            "includes": includes,
+            "basis_gates": basis_gates,
+            "disable_constants": disable_constants,
+            "alias_classical_registers": alias_classical_registers,
+            "allow_aliasing": allow_aliasing,
+            "indent": indent,
+        },
+    )
+
+
+@functools.wraps(_qasm3.dump)
+def dump_experimental(
+    circuit,
+    stream,
+    *,
+    includes=None,
+    basis_gates=None,
+    disable_constants=True,
+    alias_classical_registers=False,
+    allow_aliasing=False,
+    indent="  ",
+):
+    """<overridden by functools.wraps>"""
+    warnings.warn(
+        "This is an experimental version of serialization of a :class:`~qiskit.circuit.QuantumCircuit`"
+        " object in an OpenQASM 3 string."
+        " Beware that its interface might change, and it might be missing features.",
+        category=ExperimentalWarning,
+    )
+    if includes is None:
+        includes = ["stdgates.inc"]
+    if basis_gates is None:
+        basis_gates = ["U"]
+
+    return _qasm3.dump(
+        circuit,
+        stream,
+        {
+            "includes": includes,
+            "basis_gates": basis_gates,
+            "disable_constants": disable_constants,
+            "alias_classical_registers": alias_classical_registers,
+            "allow_aliasing": allow_aliasing,
+            "indent": indent,
+        },
+    )

qiskit/qasm3/ast.py

@@ -54,6 +54,16 @@ class Pragma(ASTNode):
         self.content = content
 
 
+class Annotation(ASTNode):
+    """An annotation."""
+
+    __slots__ = ("namespace", "payload")
+
+    def __init__(self, namespace: str, payload: str):
+        self.namespace = namespace
+        self.payload = payload
+
+
 class CalibrationGrammarDeclaration(Statement):
     """
     calibrationGrammarDeclaration
@@ -701,15 +711,19 @@ class WhileLoopStatement(Statement):
 class BoxStatement(Statement):
     """Like ``box[duration] { statements* }``."""
 
-    __slots__ = ("duration", "body")
+    # TODO: the `annotations` field maybe should move to `Statement` if it becomes more generally
+    # supported.
+    __slots__ = ("annotations", "duration", "body")
 
     def __init__(
         self,
         body: ProgramBlock,
         duration: Expression | None = None,
+        annotations: Sequence[Annotation] = (),
     ):
         self.body = body
         self.duration = duration
+        self.annotations = tuple(annotations)
 
 
 class BreakStatement(Statement):

qiskit/qasm3/exporter.py

@@ -27,6 +27,7 @@ from typing import Iterable, List, Sequence, Union
 from qiskit._accelerate.circuit import StandardGate
 from qiskit.circuit import (
     library,
+    Annotation,
     Barrier,
     CircuitInstruction,
     Clbit,
@@ -42,6 +43,7 @@ from qiskit.circuit import (
     Bit,
     Register,
 )
+from qiskit.circuit.annotation import iter_namespaces, OpenQASM3Serializer
 from qiskit.circuit.classical import expr, types
 from qiskit.circuit.controlflow import (
     BoxOp,
@@ -136,6 +138,7 @@ class Exporter:
         allow_aliasing: bool = None,
         indent: str = "  ",
         experimental: ExperimentalFeatures = ExperimentalFeatures(0),
+        annotation_handlers: dict[str, OpenQASM3Serializer] | None = None,
     ):
         """
         Args:
@@ -172,6 +175,10 @@ class Exporter:
                 set to the empty string to disable indentation.
             experimental: any experimental features to enable during the export.  See
                 :class:`ExperimentalFeatures` for more details.
+            annotation_handlers: a mapping of namespaces to annotation serializers.  When an
+                :class:`.Annotation` object is encountered, the most specific namespace in this
+                mapping that matches the annotation's :attr:`~.Annotation.namespace` attribute will
+                be used to serialize it.
         """
         self.basis_gates = basis_gates
         self.disable_constants = disable_constants
@@ -181,6 +188,7 @@ class Exporter:
         self.includes = list(includes)
         self.indent = indent
         self.experimental = experimental
+        self.annotation_handlers = {} if annotation_handlers is None else annotation_handlers
 
     def dumps(self, circuit):
         """Convert the circuit to OpenQASM 3, returning the result as a string."""
@@ -197,6 +205,7 @@ class Exporter:
             disable_constants=self.disable_constants,
             allow_aliasing=self.allow_aliasing,
             experimental=self.experimental,
+            annotation_handlers=self.annotation_handlers,
         )
         BasicPrinter(stream, indent=self.indent, experimental=self.experimental).visit(
             builder.build_program()
@@ -225,43 +234,43 @@ _CANONICAL_CONTROLLED_STANDARD_GATES = {
 # Mapping of symbols defined by `stdgates.inc` to their gate definition source.
 _KNOWN_INCLUDES = {
     "stdgates.inc": {
-        "p": _CANONICAL_STANDARD_GATES[StandardGate.PhaseGate],
-        "x": _CANONICAL_STANDARD_GATES[StandardGate.XGate],
-        "y": _CANONICAL_STANDARD_GATES[StandardGate.YGate],
-        "z": _CANONICAL_STANDARD_GATES[StandardGate.ZGate],
-        "h": _CANONICAL_STANDARD_GATES[StandardGate.HGate],
-        "s": _CANONICAL_STANDARD_GATES[StandardGate.SGate],
-        "sdg": _CANONICAL_STANDARD_GATES[StandardGate.SdgGate],
-        "t": _CANONICAL_STANDARD_GATES[StandardGate.TGate],
-        "tdg": _CANONICAL_STANDARD_GATES[StandardGate.TdgGate],
-        "sx": _CANONICAL_STANDARD_GATES[StandardGate.SXGate],
-        "rx": _CANONICAL_STANDARD_GATES[StandardGate.RXGate],
-        "ry": _CANONICAL_STANDARD_GATES[StandardGate.RYGate],
-        "rz": _CANONICAL_STANDARD_GATES[StandardGate.RZGate],
-        "cx": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CXGate][1],
-        "cy": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CYGate][1],
-        "cz": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CZGate][1],
-        "cp": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CPhaseGate][1],
-        "crx": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CRXGate][1],
-        "cry": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CRYGate][1],
-        "crz": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CRZGate][1],
-        "ch": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CHGate][1],
-        "swap": _CANONICAL_STANDARD_GATES[StandardGate.SwapGate],
-        "ccx": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CCXGate][3],
-        "cswap": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CSwapGate][1],
-        "cu": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CUGate][1],
-        "CX": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CXGate][1],
-        "phase": _CANONICAL_STANDARD_GATES[StandardGate.PhaseGate],
-        "cphase": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CPhaseGate][1],
-        "id": _CANONICAL_STANDARD_GATES[StandardGate.IGate],
-        "u1": _CANONICAL_STANDARD_GATES[StandardGate.U1Gate],
-        "u2": _CANONICAL_STANDARD_GATES[StandardGate.U2Gate],
-        "u3": _CANONICAL_STANDARD_GATES[StandardGate.U3Gate],
+        "p": _CANONICAL_STANDARD_GATES[StandardGate.Phase],
+        "x": _CANONICAL_STANDARD_GATES[StandardGate.X],
+        "y": _CANONICAL_STANDARD_GATES[StandardGate.Y],
+        "z": _CANONICAL_STANDARD_GATES[StandardGate.Z],
+        "h": _CANONICAL_STANDARD_GATES[StandardGate.H],
+        "s": _CANONICAL_STANDARD_GATES[StandardGate.S],
+        "sdg": _CANONICAL_STANDARD_GATES[StandardGate.Sdg],
+        "t": _CANONICAL_STANDARD_GATES[StandardGate.T],
+        "tdg": _CANONICAL_STANDARD_GATES[StandardGate.Tdg],
+        "sx": _CANONICAL_STANDARD_GATES[StandardGate.SX],
+        "rx": _CANONICAL_STANDARD_GATES[StandardGate.RX],
+        "ry": _CANONICAL_STANDARD_GATES[StandardGate.RY],
+        "rz": _CANONICAL_STANDARD_GATES[StandardGate.RZ],
+        "cx": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CX][1],
+        "cy": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CY][1],
+        "cz": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CZ][1],
+        "cp": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CPhase][1],
+        "crx": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CRX][1],
+        "cry": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CRY][1],
+        "crz": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CRZ][1],
+        "ch": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CH][1],
+        "swap": _CANONICAL_STANDARD_GATES[StandardGate.Swap],
+        "ccx": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CCX][3],
+        "cswap": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CSwap][1],
+        "cu": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CU][1],
+        "CX": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CX][1],
+        "phase": _CANONICAL_STANDARD_GATES[StandardGate.Phase],
+        "cphase": _CANONICAL_CONTROLLED_STANDARD_GATES[StandardGate.CPhase][1],
+        "id": _CANONICAL_STANDARD_GATES[StandardGate.I],
+        "u1": _CANONICAL_STANDARD_GATES[StandardGate.U1],
+        "u2": _CANONICAL_STANDARD_GATES[StandardGate.U2],
+        "u3": _CANONICAL_STANDARD_GATES[StandardGate.U3],
     },
 }
 
 _BUILTIN_GATES = {
-    "U": _CANONICAL_STANDARD_GATES[StandardGate.UGate],
+    "U": _CANONICAL_STANDARD_GATES[StandardGate.U],
 }
 
 
@@ -563,6 +572,7 @@ class QASM3Builder:
         disable_constants,
         allow_aliasing,
         experimental=ExperimentalFeatures(0),
+        annotation_handlers=None,
     ):
         self.scope = BuildScope(
             quantumcircuit,
@@ -582,6 +592,7 @@ class QASM3Builder:
         self.includes = includeslist
         self.basis_gates = basis_gates
         self.experimental = experimental
+        self.annotation_handlers = {} if annotation_handlers is None else annotation_handlers
 
     @contextlib.contextmanager
     def new_scope(self, circuit: QuantumCircuit, qubits: Iterable[Qubit], clbits: Iterable[Clbit]):
@@ -991,8 +1002,8 @@ class QASM3Builder:
                 measurement = ast.QuantumMeasurement(
                     [self._lookup_bit(operand) for operand in instruction.qubits]
                 )
-                qubit = self._lookup_bit(instruction.clbits[0])
-                nodes = [ast.QuantumMeasurementAssignment(qubit, measurement)]
+                clbit = self._lookup_bit(instruction.clbits[0])
+                nodes = [ast.QuantumMeasurementAssignment(clbit, measurement)]
             elif isinstance(instruction.operation, Reset):
                 nodes = [
                     ast.QuantumReset(self._lookup_bit(operand)) for operand in instruction.qubits
@@ -1090,10 +1101,13 @@ class QASM3Builder:
         """Build a :class:`.BoxOp` into a :class:`.ast.BoxStatement`."""
         duration = self.build_duration(instruction.operation.duration, instruction.operation.unit)
         body_circuit = instruction.operation.blocks[0]
+        annotations = [
+            self.build_annotation(annotation) for annotation in instruction.operation.annotations
+        ]
         with self.new_scope(body_circuit, instruction.qubits, instruction.clbits):
             # TODO: handle no-op qubits (see https://github.com/openqasm/openqasm/issues/584).
             body = ast.ProgramBlock(self.build_current_scope())
-        return ast.BoxStatement(body, duration)
+        return ast.BoxStatement(body, duration, annotations=annotations)
 
     def build_while_loop(self, instruction: CircuitInstruction) -> ast.WhileLoopStatement:
         """Build a :obj:`.WhileLoopOp` into a :obj:`.ast.WhileLoopStatement`."""
@@ -1129,6 +1143,15 @@ class QASM3Builder:
             body_ast = ast.ProgramBlock(self.build_current_scope())
         return ast.ForLoopStatement(indexset_ast, loop_parameter_ast, body_ast)
 
+    def build_annotation(self, annotation: Annotation) -> ast.Annotation:
+        """Use the custom serializers to construct an annotation object."""
+        for namespace in iter_namespaces(annotation.namespace):
+            if (serializer := self.annotation_handlers.get(namespace, None)) is not None and (
+                payload := serializer.dump(annotation)
+            ) is not NotImplemented:
+                return ast.Annotation(annotation.namespace, payload)
+        raise QASM3ExporterError(f"No configured annotation serializer could handle {annotation}")
+
     def _lookup_variable_for_expression(self, var):
         if isinstance(var, Bit):
             return self._lookup_bit(var)

qiskit/qasm3/printer.py

@@ -205,6 +205,13 @@ class BasicPrinter:
     def _visit_Pragma(self, node: ast.Pragma) -> None:
         self._write_statement(f"#pragma {node.content}")
 
+    def _visit_Annotation(self, node: ast.Annotation) -> None:
+        self._start_line()
+        self.stream.write(f"@{node.namespace}")
+        if node.payload:
+            self.stream.write(f" {node.payload}")
+        self._end_line()
+
     def _visit_CalibrationGrammarDeclaration(self, node: ast.CalibrationGrammarDeclaration) -> None:
         self._write_statement(f'defcalgrammar "{node.name}"')
 
@@ -597,6 +604,11 @@ class BasicPrinter:
         self.stream.write("default")
 
     def _visit_BoxStatement(self, node: ast.BoxStatement) -> None:
+        # The OpenQASM 3 spec doesn't specify any ordering between annotations.  We choose to
+        # write and interpret them like Python decorators, where the "first" annotation is written
+        # closest to the box itself.
+        for annotation in reversed(node.annotations):
+            self.visit(annotation)
         self._start_line()
         self.stream.write("box")
         if node.duration is not None:

qiskit/qpy/__init__.py

@@ -99,6 +99,7 @@ API documentation
 
 .. autofunction:: load
 .. autofunction:: dump
+.. autofunction:: get_qpy_version
 
 These functions will raise a custom subclass of :exc:`.QiskitError` if they encounter problems
 during serialization or deserialization.
@@ -139,6 +140,10 @@ load that QPY file with qiskit-terra 0.19.0 and a hypothetical qiskit-terra
 0.29.0. However, loading that QPY file with 0.18.0 is not supported and may not
 work.
 
+Note that circuit metadata and custom :class:`.Annotation` objects are serialized and deserialized
+by user-supplied classes, as the objects themselves are completely user-custom, so the forwards- and
+backwards-compatibility of these is limited by what the user provides.
+
 If a feature being loaded is deprecated in the corresponding qiskit release, QPY will
 raise a :exc:`~.QPYLoadingDeprecatedFeatureWarning` informing of the deprecation period
 and how the feature will be internally handled.
@@ -194,9 +199,21 @@ of QPY in qiskit-terra 0.18.0.
    * - Qiskit (qiskit-terra for < 1.0.0) version
      - :func:`.dump` format(s) output versions
      - :func:`.load` maximum supported version (older format versions can always be read)
+   * - 2.1.0
+     - 13, 14, 15
+     - 15
+   * - 2.0.2
+     - 13, 14
+     - 14
+   * - 2.0.1
+     - 13, 14
+     - 14
    * - 2.0.0
      - 13, 14
      - 14
+   * - 1.4.3
+     - 10, 11, 12, 13
+     - 13
    * - 1.4.2
      - 10, 11, 12, 13
      - 13
@@ -387,17 +404,175 @@ All values use network byte order [#f1]_ (big endian) for cross platform
 compatibility.
 
 The file header is immediately followed by the circuit payloads.
-Each individual circuit is composed of the following parts:
+Each individual circuit is composed of the following parts in order from top to bottom:
+
+.. code-block:: text
 
-``HEADER | METADATA | REGISTERS | STANDALONE_VARS | CUSTOM_DEFINITIONS | INSTRUCTIONS``
+    HEADER
+    METADATA
+    REGISTERS
+    ANNOTATION_HEADER
+    STANDALONE_VARS
+    CUSTOM_DEFINITIONS
+    INSTRUCTIONS
 
-The ``STANDALONE_VARS`` are new in QPY version 12; before that, there was no data between
-``REGISTERS`` and ``CUSTOM_DEFINITIONS``.
+.. versionchanged:: QPY 15
+    ``ANNOTATION_HEADER`` was added between ``REGISTERS`` and ``STANDALONE_VARS``.
+
+.. versionchanged:: QPY 12
+    ``STANDALONE_VARS`` was added between ``REGISTERS`` and ``CUSTOM_DEFINITIONS``.
 
 There is a circuit payload for each circuit (where the total number is dictated
 by ``num_circuits`` in the file header). There is no padding between the
 circuits in the data.
 
+.. _qpy_version_15:
+
+Version 15
+----------
+
+Version 15 adds the concept of custom annotations to the payload format.  QPY itself does not
+specify how annotations are serialized or deserialized, as they are custom user objects.  The format
+does co-operate with sub-serializers, however.
+
+Version 15 adds the ``ANNOTATION_HEADER`` field between the ``STANDALONE_VARS`` and
+``CUSTOM_DEFINITIONS`` fields in the top level of a single circuit payload.  It modifies the
+interpretation of one field of the ``INSTRUCTION`` struct in an ABI-compatible manner, and adds a
+``INSTRUCTION_ANNOTATIONS`` trailer to ``INSTRUCTION`` which is present conditional on a set bit in
+the ``INSTRUCTION`` payload.
+
+New ANNOTATION_HEADER
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``ANNOTATION_HEADER`` field is a variable-size payload in the header.  It begins with an
+instance of ``ANNOTATION_HEADER_STATIC``, which is the C struct:
+
+.. code-block:: c
+
+    struct ANNOTATION_HEADER_STATIC {
+        uint32_t num_namespaces;
+    }
+
+This is immediately followed by ``num_namespaces`` instances of the ``ANNOTATION_STATE`` payload.
+The order of these is important and should be retained during the deserialization process, as
+subsequent ``INSTRUCTION_ANNOTATION`` payloads will index into it.
+
+The ``ANNOTATION_STATE`` payload begins with the fixed C struct:
+
+.. code-block:: c
+
+    struct ANNOTATION_STATE_HEADER {
+        uint32_t namespace_size;
+        uint64_t state_size;
+    }
+
+This header is immediately followed by ``namespace_size`` bytes of UTF-8 encoded text, which
+comprise the namespace.  Those bytes are immediately followed by ``state_size`` bytes of arbitrary
+data.  The format of this "state" payload is not defined by QPY.  Instead, it is the responsibility
+of an external object associated with the stored namespace.  The format does not dictate how to
+produce these objects; as annotations are entirely custom, the user must supply the serialization
+and deserialization methods.
+
+
+.. _qpy_instruction_v15:
+
+Changes to INSTRUCTION
+~~~~~~~~~~~~~~~~~~~~~~
+
+The ``INSTRUCTION`` struct is modified in an ABI compatible manner to :ref:`its previous definition
+in version 9 <qpy_instruction_v9>`.  The new struct is the C struct (recall that there is no padding
+between any fields, nor at the end of the struct):
+
+.. code-block:: c
+
+    struct INSTRUCTION {
+        uint16_t name_size;
+        uint16_t label_size;
+        uint16_t num_parameters;
+        uint32_t num_qargs;
+        uint32_t num_cargs;
+        uint8_t extras_key;
+        uint16_t conditional_reg_name_size;
+        int64_t conditional_value;
+        uint32_t num_ctrl_qubits;
+        uint32_t ctrl_state;
+    }
+
+where the field ``uint8_t extras_key`` replaces the previous ``uint8_t conditional_key``.  The
+difference is purely in interpretation.  The low two bits of the byte are still interpreted as
+defining the condition and its type.  The high bit of the byte is now a flag, indicated whether an
+``INSTRUCTION_ANNOTATIONS_HEADER`` field is present (if the bit is set) in the trailing data of the
+``INSTRUCTION`` struct.
+
+A complete instruction payload appears in the data stream, including trailing objects and without
+any padding bytes inbetween elements, as:
+
+.. code-block:: text
+
+    struct INSTRUCTION;
+    uint8_t name[name_size];
+    uint8_t label[label_size];
+    uint8_t register[conditional_reg_name_size]; (1)
+    struct INSTRUCTION_PARAM;                    (2)
+    struct INSTRUCTION_ARG[num_qargs];
+    struct INSTRUCTION_ARG[num_cargs];
+    struct INSTRUCTION_PARAM[num_parameters];
+    INSTRUCTION_ANNOTATIONS;                     (3)
+
+The following notes apply:
+
+1. if the two low bits of the ``extras_key`` have the value ``2``, indicating the condition is an
+   ``EXPRESSION``, the ``conditional_reg_name_size`` is always zero.
+2. this field is present if and only if the two low bits of the ``extras_key`` have the value ``2``,
+   indicating the condition is an ``EXPRESSION``.
+3. this field is present if and only if the high bit of the ``extras_key`` is set.  This field has
+   a variable size; see :ref:`qpy_instruction_annotations_v15`.
+
+.. _qpy_instruction_annotations_v15:
+
+New INSTRUCTION_ANNOTATIONS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``INSTRUCTION_ANNOTATIONS`` payload begins with the C struct:
+
+.. code-block:: c
+
+    struct INSTRUCTION_ANNOTATIONS_HEADER {
+        uint32_t num_annotations;
+    }
+
+This payload is immediately followed by ``num_annotations`` instances of the
+``INSTRUCTION_ANNOTATION`` payload, which is of a variable size.
+
+The ``INSRTUCTION_ANNOTATION`` payload is defined by the following C struct plus a trailing number
+of bytes equal to the ``payload_size``, called ``ANNOTATION_PAYLOAD``.
+
+.. code-block:: c
+
+    struct INSTRUCTION_ANNOTATION {
+        uint32_t namespace_index;
+        uint32_t payload_size;
+    }
+
+The ``namespace_index`` is an integer index into the list of defined ``ANNOTATION_NAMESPACE``
+objects in the ``ANNOTATION_HEADER``.  The serialization namespace for an annotation is the UTF-8
+encoded string in the relevant payload.
+
+The format of the ``ANNOTATION_PAYLOAD`` object is not specified by QPY.  It is defined by an
+external serialization object associated with the namespace referred to by the ``namespace_index``
+and its associated serializer state in the ``ANNOTATION_HEADER``.
+
+
+Changes within PARAM_EXPR_ELEM_V13
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The struct itself is unchanged.  However, for a ``PARAM_EXPR_ELEM_V13`` representing a
+:meth:`.ParameterExpression.subs` call (with ``op_code = 15``, and therefore ``lhs_type = 'p'`` and
+``rhs_type = 'n'``), the trailing :ref:`qpy_mapping` now maps keys of the raw bytes of the
+:class:`.Parameter` UUIDs to the substituted values.  Previously (in QPY versions 13 and 14), this
+mapping stored the parameter names as the keys.
+
+
 .. _qpy_version_14:
 
 Version 14
@@ -900,6 +1075,7 @@ Python type  Type code  Payload
 ===========  =========  ============================================================================
 
 
+.. _qpy_instruction_v9:
 
 Changes to INSTRUCTION
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -941,7 +1117,7 @@ Value  Effects
 
 2      The instruction has its ``.condition`` field set to a :class:`~.expr.Expr` node.  The
        ``conditional_reg_name_size`` and ``conditional_value`` fields should be ignored.  The data
-       following the struct is followed (as in QPY versions less than 8) by ``name_size`` bytes of
+       following the struct is followed (as in QPY versions less than 9) by ``name_size`` bytes of
        UTF-8 string data for the class name and ``label_size`` bytes of UTF-8 string data for the
        label (if any). Then, there is one INSTRUCTION_PARAM, which will contain an EXPRESSION. After
        that, parsing continues with the INSTRUCTION_ARG structs, as in previous versions of QPY.
@@ -1952,7 +2128,7 @@ References
 """
 
 from .exceptions import QpyError, UnsupportedFeatureForVersion, QPYLoadingDeprecatedFeatureWarning
-from .interface import dump, load
+from .interface import dump, load, get_qpy_version
 
 # For backward compatibility. Provide, Runtime, Experiment call these private functions.
 from .binary_io import (