Annotazioni sui circuiti

qiskit.circuit.annotation

Questo modulo contiene l'infrastruttura per lavorare con le annotazioni dei circuiti personalizzati.

qiskit.circuit.AnnotationLa classe principale a cui si rivolgono gli utenti è la classe base, che viene anche riesportata da questo modulo.

Sottoclassi di annotazione personalizzate

La Annotation classe è pensata per essere sottoclassificata. Le sottoclassi devono impostare il proprio namespace campo. Questo può essere specifico per un'istanza oppure statico per un'intera sottoclasse. Lo spazio dei nomi viene utilizzato nell'ambito del meccanismo di invio, come descritto nella sezione "Spazi dei nomi".

I controlli di uguaglianza dei circuiti confrontano anche le annotazioni sugli oggetti in modo dipendente dall'ordine. Probabilmente si vorrà implementare il metodo __eq__() su tutte le sottoclassi.

Se si vuole che la propria annotazione possa essere serializzata tramite QPY o :ref:` OpenQASM 3 <qiskit-qasm3> `, è necessario fornire implementazioni separate dei metodi di serializzazione e deserializzazione, come discusso in Serializzazione e deserializzazione.

Spazi dei nomi

Lo "spazio dei nomi" di un'annotazione è usato come chiave di ricerca quando un consumatore decide quale gestore invocare. Questo include i contesti di serializzazione QPY e OpenQASM 3, ma in generale i passaggi del transpiler guarderanno anche gli spazi dei nomi delle annotazioni per determinare se sono rilevanti e così via.

Può trattarsi di un identificatore standard di tipo Python (ad es. my_namespace), oppure un elenco di identificatori separati da punti (ad es. my_namespace.subnamespace). Lo spazio dei nomi viene utilizzato da tutti gli utenti delle annotazioni per determinare quale gestore debba essere richiamato.

Una funzione indipendente consente di iterare gli spazi dei nomi e gli spazi dei nomi dei genitori in ordine di priorità, dal più specifico al meno specifico.

iter_namespaces

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

Serializzazione e deserializzazione

Le annotazioni rappresentano dati completamente personalizzati, che possono persistere dopo la compilazione. Questo può includere dati che devono essere serializzati per un consumo successivo, come i dati aggiuntivi che vengono interpretati da un backend-compiler. Il formato binario nativo QPY di Qiskit (vedi qiskit.qpy) supporta il concetto di annotazioni arbitrarie nei suoi payload dalla versione 15 in poi. In OpenQASM 3 (vedere qiskit.qasm3), le annotazioni sono una caratteristica fondamentale del linguaggio e il supporto di importazione/esportazione di Qiskit per OpenQASM 3 include la serializzazione delle annotazioni.

Tuttavia, poiché le annotazioni sono generalmente sottoclassi personalizzate e non sono riconosciute da Qiskit, non è possibile disporre di un supporto integrato per la serializzazione. Per quanto riguarda la deserializzazione, Qiskit, in generale, non disporrà di un oggetto esistente Annotation da cui richiamare i metodi di deserializzazione. Si prevede inoltre che le annotazioni possano riferirsi a uno stato condiviso, sconosciuto a Qiskit, all’interno di un determinato contesto circuitale.

Per tutti questi motivi, la serializzazione e la deserializzazione delle annotazioni è gestita da oggetti personalizzati, che devono essere passati ai punti di interfaccia delle funzioni di serializzazione pertinenti. Ad esempio, in QPY, l'argomento annotation_factories in qpy.dump() e qpy.load() sono usati per passare i serializzatori.

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

Esempi

Un passaggio del transpiler per la raccolta dei blocchi

Un obiettivo principale del framework di annotazione è quello di consentire la memorizzazione di analisi e comandi personalizzati sui circuiti in modo locale alle istruzioni, sia da parte dell'utente all'ingresso del compilatore, sia per un passaggio del compilatore per memorizzare le informazioni da utilizzare successivamente.

Ad esempio, possiamo scrivere un semplice passaggio di transpiler che raccolga sequenze di operazioni su un singolo qubit, inserisca ciascuna sequenza in un BoxOp, calcoli l’azione unitaria totale e la aggiunga come annotazione personalizzata, in modo che non sia necessario ripetere la stessa analisi in seguito, anche se i meccanismi interni di ciascun blocco vengono ottimizzati.

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

Per serializzare l'annotazione in OpenQASM 3, dobbiamo definire una logica personalizzata, poiché l'analisi stessa è interamente personalizzata. La serializzazione è separata dall'annotazione; ci possono essere circostanze in cui la serializzazione deve essere fatta in modo diverso.

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

Infine, il tutto può essere messo insieme, mostrando l'output 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];
}