Annotations de circuit

qiskit.circuit.annotation

Ce module contient l'infrastructure nécessaire pour travailler avec des annotations de circuits personnalisées.

qiskit.circuit.AnnotationLa classe principale destinée aux utilisateurs est la classe de base, qui est également réexportée depuis ce module.

Sous-classes d'annotation personnalisées

Cette Annotation classe est destinée à être sous-classée. Les sous-classes doivent définir leur namespace champ. Cela peut être spécifique à une instance ou statique pour l'ensemble d'une sous-classe. L'espace de noms est utilisé dans le cadre du mécanisme de répartition, comme décrit dans la section « Espaces de noms ».

Les contrôles d'égalité des circuits comparent également les annotations sur les objets en fonction de l'ordre. Vous voudrez probablement implémenter la méthode __eq__() dans toutes les sous-classes.

Si vous souhaitez que votre annotation puisse être sérialisée via QPY ou :ref:\N- OpenQASM 3 <qiskit-qasm3> \N-, vous devez fournir des implémentations séparées des méthodes de sérialisation et de désérialisation, comme indiqué dans Sérialisation et désérialisation.

Espaces de noms

L'espace de noms d'une annotation est utilisé comme clé de recherche lorsqu'un consommateur décide du gestionnaire à invoquer. Cela inclut les contextes de sérialisation QPY et OpenQASM 3, mais en général, les passes de transpilation examineront également les espaces de noms des annotations pour déterminer s'ils sont pertinents, et ainsi de suite.

Il peut s'agir d'un identifiant standard de type « Python » (par exemple, my_namespace), ou une liste d'identificateurs séparés par des points (par exemple my_namespace.subnamespace). L'espace de noms est utilisé par tous les utilisateurs d'annotations pour déterminer quel gestionnaire doit être appelé.

Une fonction autonome permet de parcourir les espaces de noms et les espaces de noms parents par ordre de priorité, du plus spécifique au moins spécifique.

iter_namespaces

from qiskit.circuit.annotation import iter_namespaces
assert list(iter_namespaces("hello.world")) == ["hello.world", "hello", ""]

Sérialisation et désérialisation

Les annotations représentent des données entièrement personnalisées, qui peuvent persister après la compilation. Il peut s'agir de données qui doivent être sérialisées en vue d'une consommation ultérieure, telles que des données supplémentaires interprétées par un compilateur dorsal. Le format binaire natif QPY de Qiskit (voir qiskit.qpy) supporte le concept d'annotations arbitraires dans ses données utiles à partir de la version 15. Dans OpenQASM 3 (voir qiskit.qasm3), les annotations sont une caractéristique essentielle du langage, et le support d'importation/exportation de Qiskit pour OpenQASM 3 inclut la sérialisation des annotations.

Cependant, comme les annotations sont généralement des sous-classes personnalisées et inconnues de Qiskit, nous ne pouvons pas disposer d'une prise en charge intégrée de la sérialisation. En ce qui concerne la désérialisation, Qiskit ne disposera généralement pas d'un objet existant Annotation à partir duquel appeler les méthodes de désérialisation. On peut également s'attendre à ce que les annotations se rapportent à un état partagé, inconnu de Qiskit, au sein d'un contexte de circuit donné.

Pour toutes ces raisons, la sérialisation et la désérialisation des annotations sont gérées par des objets personnalisés, qui doivent être transmis aux points d'interface des fonctions de sérialisation concernées. Par exemple, dans QPY, l'argument annotation_factories dans qpy.dump() et qpy.load() sont utilisés pour passer des sérialiseurs.

QPYSerializer

QPYFromOpenQASM3Serializer

import io
from qiskit.circuit import OpenQASM3Serializer, Annotation
from qiskit import qpy

class MyAnnotation(Annotation):
    namespace = "my_namespace"

class MySerializer(OpenQASM3Serializer):
    def dump(self, annotation):
        if not isinstance(annotation, MyAnnotation):
            return NotImplemented
        return ""

    def load(self, namespace, payload):
        assert namespace == "my_namespace"
        assert payload == ""
        return MyAnnotation()

qc = QuantumCircuit(2)
with qc.box(annotations=[MyAnnotation()]):
    qc.cx(0, 1)

with io.BytesIO() as fptr:
    qpy.dump(fptr, qc, annotation_serializers = {"my_namespace": MySerializer().as_qpy()})

OpenQASM3Serializer

Exemples

Une passe de transpileur de collection de blocs

L'un des principaux objectifs du cadre d'annotation est de permettre aux analyses et aux commandes personnalisées d'être stockées sur les circuits de manière locale, soit par l'utilisateur à l'entrée du compilateur, soit pour un passage du compilateur afin de stocker des informations en vue d'une utilisation ultérieure.

Par exemple, nous pouvons écrire un passage de transcompilateur simple qui regroupe les séries d’opérations sur un seul qubit, place chaque série dans un BoxOp, calcule ensuite l’action unitaire totale et l’ajoute sous forme d’annotation personnalisée, de sorte que la même analyse n’ait pas à être répétée par la suite, même si le fonctionnement interne de chaque bloc est optimisé.

from qiskit.circuit import annotation, QuantumCircuit, BoxOp
from qiskit.quantum_info import Operator
from qiskit.transpiler import TransformationPass

class PerformsUnitary(annotation.Annotation):
    namespace = "unitary"
    def __init__(self, matrix):
        self.matrix = matrix

class Collect1qRuns(TransformationPass):
    def run(self, dag):
        for run in dag.collect_1q_runs():
            block = QuantumCircuit(1)
            for node in run:
                block.append(node.op, [0], [])
            box = BoxOp(block, annotations=[PerformsUnitary(Operator(block).data)])
            dag.replace_block_with_op(run, box, {run[0].qargs[0]: 0})
        return dag

Afin de sérialiser l'annotation sur OpenQASM 3, nous devons définir une logique personnalisée, puisque l'analyse elle-même est entièrement personnalisée. La sérialisation est distincte de l'annotation; il peut y avoir des circonstances dans lesquelles la sérialisation doit être effectuée différemment.

import ast
import numpy as np

class Serializer(annotation.OpenQASM3Serializer):
    def dump(self, annotation):
        if annotation.namespace != "unitary":
            return NotImplemented
        line = lambda row: "[" + ", ".join(repr(x) for x in row) + "]"
        return "[" + ", ".join(line(row) for row in annotation.matrix.tolist()) + "]"

    def load(self, namespace, payload):
        if namespace != "unitary":
            return NotImplemented
        return PerformsUnitary(np.array(ast.literal_eval(payload), dtype=complex))

Enfin, le tout peut être assemblé, ce qui donne le résultat OpenQASM 3.

from qiskit import qasm3

qc = QuantumCircuit(3)
qc.s(0)
qc.t(0)
qc.y(1)
qc.x(1)
qc.h(2)
qc.s(2)
collected = Collect1qRuns()(qc)

handlers = {"unitary": Serializer()}
dumped = qasm3.dumps(collected, annotation_handlers=handlers)
print(dumped)

OPENQASM 3.0;
include "stdgates.inc";
qubit[3] q;
@unitary[[(1+0j), 0j], [0j, (-0.7071067811865475+0.7071067811865475j)]]
box {
  s q[0];
  t q[0];
}
@unitary[[1j, 0j], [0j, -1j]]
box {
  y q[1];
  x q[1];
}
@unitary[[(0.7071067811865475+0j), (0.7071067811865475+0j)], [0.7071067811865475j, -0.7071067811865475j]]
box {
  h q[2];
  s q[2];
}