Anotaciones de circuitos

qiskit.circuit.annotation

Este módulo contiene la infraestructura para trabajar con anotaciones de circuitos personalizados.

qiskit.circuit.AnnotationLa clase principal a la que acceden los usuarios es la clase base, que también se reexporta desde este módulo.

Subclases de anotaciones personalizadas

La Annotation clase está pensada para que se creen subclases a partir de ella. Las subclases deben establecer su namespace campo. Esto puede ser específico de una instancia o estático para toda una subclase. El espacio de nombres se utiliza como parte del mecanismo de distribución, tal y como se describe en «Espacios de nombres ».

Las comprobaciones de igualdad de circuitos también comparan las anotaciones de los objetos en función del orden. Es probable que desee implementar el método __eq__() en cualquier subclase.

Si desea que su anotación pueda serializarse a través de QPY o :ref:` OpenQASM 3 <qiskit-qasm3> `, debe proporcionar implementaciones separadas de los métodos de serialización y deserialización, tal y como se explica en Serialización y deserialización.

Espacio de nombres

El "espacio de nombres" de una anotación se utiliza como clave de búsqueda cuando cualquier consumidor está decidiendo qué manejador invocar. Esto incluye en contextos de serialización QPY y OpenQASM 3, pero en general, los pases del transpilador también mirarán los namespaces de las anotaciones para determinar si son relevantes, etc.

Puede tratarse de un identificador estándar de Python (por ejemplo, my_namespace), o una lista de identificadores separados por puntos (p. ej., my_namespace.subnamespace). Todos los usuarios de anotaciones utilizan el espacio de nombres para determinar qué controlador debe invocarse.

Una función independiente permite iterar por los espacios de nombres y los espacios de nombres padre en orden de prioridad de más específico a menos específico.

iter_namespaces

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

Serialización y deserialización

Las anotaciones representan datos completamente personalizados, que pueden persistir tras la compilación. Esto puede incluir datos que deben ser serializados para su posterior consumo, como datos adicionales que son interpretados por un compilador backend. El formato binario nativo QPY de Qiskit (véase qiskit.qpy) admite el concepto de anotaciones arbitrarias en sus cargas útiles a partir de la versión 15. En OpenQASM 3 (véase qiskit.qasm3), las anotaciones son una característica central del lenguaje, y el soporte de importación/exportación de Qiskit para OpenQASM 3 incluye la serialización de anotaciones.

Sin embargo, dado que las anotaciones suelen ser subclases personalizadas y Qiskit no las reconoce, no podemos contar con compatibilidad integrada para la serialización. En lo que respecta a la deserialización, Qiskit no suele disponer de un objeto existente Annotation desde el que llamar a los métodos de deserialización. También se prevé que las anotaciones puedan estar relacionadas con algún estado compartido desconocido para Qiskit dentro del contexto de un circuito determinado.

Por todas estas razones, la serialización y deserialización de anotaciones es manejada por objetos personalizados, que deben ser pasados en los puntos de interfaz de las funciones de serialización relevantes. Por ejemplo, en QPY, el argumento annotation_factories en qpy.dump() y qpy.load() se utilizan para pasar serializadores.

QPYSerializador

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

Ejemplos

Una pasada del transpilador de colección de bloques

Uno de los principales objetivos del marco de anotación es permitir que los análisis y comandos personalizados se almacenen en los circuitos de una manera local a la instrucción, ya sea por el usuario en la entrada al compilador, o para que una pasada del compilador almacene información para su consumo posterior.

Por ejemplo, podemos escribir una pasada sencilla del transpilador que recopile series de operaciones de un solo qubit, coloque cada serie en un BoxOp, calcule la acción unitaria total y la adjunte como una anotación personalizada, de modo que no sea necesario repetir el mismo análisis más adelante, incluso si se optimizan los componentes internos de cada bloque.

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

Para serializar la anotación a OpenQASM 3, debemos definir una lógica personalizada, ya que el análisis en sí es totalmente personalizado. La serialización es independiente de la anotación; puede haber circunstancias en las que la serialización deba hacerse de otra manera.

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

Por último, se puede juntar todo esto, mostrando la salida 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];
}