回路注釈

qiskit.circuit.annotation

このモジュールには、カスタム回路アノテーションを扱うためのインフラが含まれています。

ユーザー向けのメイン・クラスはベース・クラス qiskit.circuit.Annotationで、これもこのモジュールから再エクスポートされます。

カスタム注釈サブクラス

この Annotation クラスはサブクラス化されることを意図している。 サブクラスは namespace フィールドを設定しなければならない。 これはインスタンス固有のものでも、サブクラス全体の静的なものでもよい。 名前空間は、「 Namespacing 」で説明されているように、ディスパッチ・メカニズムの一部として使用される。

回路の等価検査は、順序に依存した方法でオブジェクトのアノテーションも比較する。 どのサブクラスでも __eq__() magic メソッドを実装したいことでしょう。

アノテーションを QPY または:ref: ` OpenQASM 3 <qiskit-qasm3> ￭でシリアライズできるようにする場合は、 シリアライズとデシリアライズの項 で説明したように、シリアライズとデシリアライズのメソッドを別々に実装する必要があります。

名前空間

アノテーションの "namespace "は、コンシューマがどのハンドラを呼び出すかを決定する際のルックアップ・キーとして使用される。 これにはQPYや OpenQASM 3シリアライゼーションのコンテキストも含まれますが、一般的にトランスパイラ・パスはアノテーションの名前空間も見て、関連性があるかどうかなどを判断します。

これは、標準的な Python 識別子（例： my_namespace）である可能性があります または、ドットで区切られた識別子のリスト（例： my_namespace.subnamespace）。 この名前空間は、アノテーションを利用するすべてのコンポーネントが、どのハンドラを呼び出すべきかを判断するために使用されます。

スタンドアロン関数により、名前空間と親名前空間を、最も特定的なものから最も特定的でないものへと優先順位をつけて反復処理することができる。

iter_namespaces

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

シリアライゼーションおよびデシリアライゼーション

アノテーションは完全にカスタム化されたデータを表し、コンパイル後も持続する可能性がある。 これには、バックエンド・コンパイラによって解釈される追加データなど、後で消費するためにシリアライズされるべきデータが含まれることがある。 QiskitのネイティブバイナリQPYフォーマット( qiskit.qpy参照)は、バージョン15以降、ペイロード内の任意の注釈の概念をサポートしています。 OpenQASM 3 ( qiskit.qasm3)では、アノテーションはコア言語機能であり、Qiskitの OpenQASM 3に対するインポート/エクスポートサポートにはアノテーションのシリアライズが含まれています。

しかし、アノテーションは一般的にカスタムサブクラスであり、Qiskitにとっては未知のものであるため、シリアライゼーションをビルトインでサポートすることはできません。 デシリアライズの面では、一般的にQiskitは既存の Annotation オブジェクトからデシリアライズメソッドを呼び出すことはできません。 また、アノテーションは、与えられた回路コンテキスト内のQiskitに未知の共有状態に関連する可能性があることも予想される。

これらの理由から、アノテーションのシリアライズとデシリアライズはカスタムオブジェクトによって処理され、関連するシリアライズ関数のインターフェイスポイントで渡されなければならない。 例えばQPYでは、 annotation_factories の引数は qpy.dump() と qpy.load() はシリアライザを渡すために使われます。

QPYシリアライザ

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

例

ブロックコレクショントランスパイラパス

アノテーション・フレームワークの主な目標は、カスタム解析とコマンドを命令ローカルな方法で回路上に保存できるようにすることである。

例えば、単一量子ビット演算の実行を収集する単純なトランスパイラ・パスを書くことができます。 BoxOpそして、ユニタリーアクションの合計を計算し、カスタムアノテーションとして添付することで、各ブロックの内部が最適化されても、同じ解析を後で繰り返す必要がなくなります。

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

アノテーションを OpenQASM 3にシリアライズするには、カスタムロジックを定義しなければならない。 シリアライゼーションはアノテーションとは別個のものであり、シリアライゼーションを別の方法で行うべき状況があるかもしれない。

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

最後に、この出力をまとめて、 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];
}