合成プラグイン

qiskit.transpiler.passes.synthesis.plugin

このモジュールはQiskitの合成トランスパイラパスのプラグインインターフェースを定義します。 これらは、外部のpythonパッケージが独自の合成技術を実装するためのフックポイントを提供し、ユーザが以下を実行するときにオプションとしてシームレスに公開されます。 transpile().

プラグインインターフェースは、qiskitの外部パッケージが合成プラグインを含むことを宣伝できるようにするsetuptools エントリポイントを使用して構築されています。

詳細は qiskit.transpiler.preset_passmanagers.plugin トランスパイラ・ステージ用のプラグインの書き方の詳細は、こちらを参照してください。

合成プラグインAPI

ユニタリー合成プラグインAPI

ハイレベル合成プラグインAPI

プラグインの作成

ユニタリー・シンセシス・プラグイン

ユニタリー合成プラグインを書くには、主に2つのステップがある。 最初のステップは、抽象プラグイン・クラスのサブクラスを作成することである： UnitarySynthesisPlugin. プラグイン・クラスは、ユニタリー・シンセシス・プラグインのインターフェースとコントラクトを定義する。 主要なメソッドは run() で、numpy配列としてユニタリー行列を引数に取り、そのユニタリー行列から合成された回路を表す DAGCircuit オブジェクトを返します。 次に、Qiskitトランスパイラにパスに必要な情報を通知するために、プラグインが合成を実行するためにその入力をサポートするか、または必要とするかによって、 supports_basis_gates や supports_coupling_map のように実装する必要があるいくつかの必須プロパティメソッドがあります。 詳細については UnitarySynthesisPlugin ドキュメントを参照してください。 プラグイン・クラスの例は次のようなものだ：

from qiskit.transpiler.passes.synthesis import plugin
from qiskit_plugin_pkg.synthesis import generate_dag_circuit_from_matrix


class SpecialUnitarySynthesis(plugin.UnitarySynthesisPlugin):
    @property
    def supports_basis_gates(self):
        return True

    @property
    def supports_coupling_map(self):
        return False

    @property
    def supports_natural_direction(self):
        return False

    @property
    def supports_pulse_optimize(self):
        return False

    @property
    def supports_gate_lengths(self):
        return False

    @property
    def supports_gate_errors(self):
        return False

    @property
    def supports_gate_lengths_by_qubit(self):
        return False

    @property
    def supports_gate_errors_by_qubit(self):
        return False

    @property
    def min_qubits(self):
        return None

    @property
    def max_qubits(self):
        return None

    @property
    def supported_bases(self):
        return None

    def run(self, unitary, **options):
        basis_gates = options['basis_gates']
        dag_circuit = generate_dag_circuit_from_matrix(unitary, basis_gates)
        return dag_circuit

もし何らかの理由で run() プラグインのインターフェイスを拡張し、将来のリリースに向けて後方互換性のある方法で新しいオプトイン入力を追加できるようにします。 ただし、このプラグインのインターフェイスは安定しており、破壊的な変更がないことが保証されている。 変更が必要な場合（例えば、利用可能なオプション入力オプションを拡張する）、既存のプラグインからの変更を必要としない方法で行われます。

第二のステップは、パッケージのメタデータに UnitarySynthesisPlugin をパッケージメタデータのsetuptoolsエントリポイントとして公開することです。 これは、 qiskit.unitary_synthesis 名前空間の下に必要なエントリー・ポイントを持つプラグイン・パッケージの pyproject.toml に entry-points テーブルを追加するだけで完了する。 例:

[project.entry-points."qiskit.unitary_synthesis"]
"special" = "qiskit_plugin_pkg.module.plugin:SpecialUnitarySynthesis"

各プラグインがユニークな名前である限り、1つのパッケージに含めることができるプラグインの数に制限はありません。 そのため、必要に応じて1つのパッケージで複数のプラグインを公開することができる。 default という名前はQiskit自身が使用するもので、プラグインでは使用できません。

ユニタリー合成プラグイン設定

プラグイン・インターフェイスには、ユーザーが自由形式の設定辞書を提供するためのオプションがあります。 これは options kwargとして run() メソッドに渡される。 もしあなたのプラグインにこのような設定オプションがあるのであれば、ユーザーがどのようにこの設定オプションを指定すべきか、またフリーフォームのフィールドであるため、どのように使用されるかを明確に文書化する必要があります。

高レベル合成プラグイン

高位合成プラグインの書き方は、概念的にはユニタリー合成プラグインの書き方に似ている。 最初のステップは、抽象プラグイン・クラスのサブクラスを作成することである： HighLevelSynthesisPluginこのクラスは、高レベル合成プラグインのインターフェースとコントラクトを定義している。 主な方法は run(). 位置引数 high_level_object は、合成される「上位レベルのオブジェクト」を指定する。 Operation (を含む）、 LinearFunction または Clifford). キーワード引数 target はターゲット・バックエンドを指定し、プラグインがカップリング・マップやサポートされるゲート・セットなど、ターゲット固有のすべての情報にアクセスできるようにする。 キーワード引数 coupling_map は、カップリング・マップを指定するだけであり、 target が指定されていない場合にのみ使用される。 キーワード引数 qubits は、合成が物理回路上で行われる場合に、上位レベルのオブジェクトが定義される量子ビットのリストを指定する。 値 None は、レイアウトがまだ選択されておらず、このオペレーションが操作されるターゲットまたはカップリング・マップの物理量子ビットがまだ決定されていないことを示す。 さらに、プラグイン固有のオプションや調整項目は、自由形式の設定辞書である options を使って指定することができます。 もしあなたのプラグインにこのような設定オプションがあるのであれば、ユーザーがどのようにこの設定オプションを指定すべきか、またフリーフォームのフィールドであるため、どのように使用されるかを明確に文書化する必要があります。 メソッド run() メソッドは QuantumCircuit オブジェクトを返すことが期待されます。 また、合成メソッドが与えられた上位レベルオブジェクトを合成できないことを表す None 。 高レベル・オブジェクトの実際の合成は HighLevelSynthesis トランスパイラパスによって行われる。 詳細については HighLevelSynthesisPlugin ドキュメントを参照してください。 プラグイン・クラスの例は次のようなものだ：

from qiskit.transpiler.passes.synthesis.plugin import HighLevelSynthesisPlugin
from qiskit.synthesis.clifford import synth_clifford_bm


class SpecialSynthesisClifford(HighLevelSynthesisPlugin):

def run(self, high_level_object, coupling_map=None, target=None, qubits=None, **options):
    if higher_level_object.num_qubits <= 3:
        return synth_clifford_bm(high_level_object)
    else:
        return None

型のオブジェクトを合成するプラグインを作成します。 Cliffordsynth_clifford_bm 型のオブジェクトを合成するプラグインを作成します。

第二のステップは、パッケージのメタデータに HighLevelSynthesisPlugin をパッケージメタデータのsetuptoolsエントリポイントとして公開することです。 これは、 qiskit.synthesis 名前空間の下に必要なエントリーポイントを持つプラグインパッケージの pyproject.toml に entry-points テーブルを追加することで行われる。 例:

[project.entry-points."qiskit.synthesis"]
"clifford.special" = "qiskit_plugin_pkg.module.plugin:SpecialSynthesisClifford"

name はドット". "で区切られた2つの部分で構成されている： のタイプ名 Operationclifford プラグインの名前 (special)。各プラグインがユニークな名前を持っている限り、1つのパッケージに含めることができるプラグインの数に制限はありません。

プラグインの使用

ユニタリー・シンセシス・プラグイン

プラグインを使用するには、合成プラグインを含むパッケージをインストールするだけです。 するとQiskitはインストールされたプラグインを自動的に検出し、 適切な transpile() の有効なオプションとして公開します。 ロード/インポートできないプラグインがインストールされている場合、 Python ロギングに記録されます。

インストールされているユニット合成プラグインのリストを取得するには qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names() 関数を使います。

高レベル合成プラグイン

高位合成プラグインを使用するには、まず、さまざまな高位オブジェクトに使用するプラグインの名前を格納するために HLSConfig をインスタンス化し、さまざまな高レベルオブジェクトに使用するプラグインの名前を格納します。 例:

HLSConfig(permutation=["acg"], clifford=["layers"], linear_function=["pmh"])

オブジェクトの合成に acg プラグインを、合成に プラグインを使用する高レベル合成コンフィギュレーションを作成します。 PermutationGate オブジェクトを合成するための layers プラグインと Clifford オブジェクトを合成する pmh プラグインを使用します。 LinearFunction オブジェクトを合成します。 キーワード引数は Operation.name フィールドである。 例えば、すべての Clifford 演算はすべて nameclifford したがって、これがキーワード引数として使われる。 ここには、プラグインがインストールされていれば、カスタム・ユーザー・オブジェクトを含め、処理するプラグインをインストールしたキーワード引数を指定することができる。 各引数内のプラグイン設定の代替フォーマットについては HLSConfig を参照のこと。各引数内のプラグインを設定するための代替フォーマットの詳細については、こちらを参照のこと。

各ハイレベルオブジェクトに対して、与えられたプラグインのリストは、そのうちの1つが成功するまで順番に試される（上の例では、各リストには1つのプラグインしか含まれていない）。 プラグインの名前で指定するだけでなく、 (name, options) タプルを渡すこともできます。タプルの 2 番目の要素は、プラグインのオプションを含む辞書です。

オブジェクトを作成したら、この HLSConfig の hls_config 引数に渡す。 transpile() または generate_preset_pass_manager() の引数にこのオブジェクトを渡すと、指定されたプラグインがより大きなコンパイル・ワークフローの一部として使われる。

インストールされている高位合成プラグインのリストを取得するには Operation.nameに対してインストールされている高位合成プラグインのリストを取得するには high_level_synthesis_plugin_names() 関数を使用し、引数に希望の name を渡します：

high_level_synthesis_plugin_names("clifford")

は、インストールされているすべてのClifford合成プラグインのリストを返します。

使用可能なプラグイン

以下はQiskitで利用可能な合成プラグインクラスです。 これらのクラスは直接使うべきでなく、上に書いたプラグイン・インターフェイスを通して使うべきである。 ここでは、各プラグインのドキュメントを見つけやすくするため、また、あるオブジェクトに対して異なる合成方法を比較しやすくするために、クラスをリストアップしている。

ユニタリー・シンセシス・プラグイン

AQC合成プラグイン

ソロベイ・キタエフ合成プラグイン

ロス・セリンガー合成プラグイン

クリフォード・ユニタリー合成プラグイン

デフォルトのユニタリー合成プラグイン

デフォルトのユニタリー合成プラグインは、トランスパイラパス UnitarySynthesis が回路内のユニタリーゲートを合成する際に使用するデフォルトのアルゴリズムを定義します。 その挙動は、対象ユニタリ演算子の量子ビット数と対象基底に依存する。

連続基底

ターゲット基底が連続的（すなわち Clifford+T ではない）場合、プラグインは以下の分解を使用します：

• 1量子ビットゲート：オイラー角分解（参照 OneQubitEulerDecomposer）。
• 2量子ビットゲート：KAK/カルタン分解（参照： TwoQubitBasisDecomposer TwoQubitControlledUDecomposer,, XXDecomposer）。
• 3量子ビット以上のゲート：量子シャノン分解、参照 qs_decomposition()。

1量子ビットおよび2量子ビットゲートについては、プラグインはターゲットからの基底誤差情報を使用して、期待忠実度を最大化する分解を選択します。

クリフォード＋T基底

ターゲット基底がクリフォード+Tである場合、プラグインはソロベイ・キタエフアルゴリズム（参照 SolovayKitaevDecomposition）を用いて1量子ビットユニタリ演算を近似する。 基本的な近似を作成するために使用される設定は, depth=12 および basis_gates=["h", "t", "tdg"] であり recursion_degree=5、近似精度と計算コストのバランスを取るために経験的に選択された。 カスタムパラメータでSolovay-Kitaevを使用する場合、または複数の回路に対して近似値を再計算することを避ける場合、このデフォルトプラグインの代わりにユニタリー合成プラグ SolovayKitaevSynthesis インを呼び出すことができます。

現在、Qiskitはクリフォード+T基底セットにおいて2量子ビット以上のユニタリ演算子を直接近似するアルゴリズムを含んでいません。 したがって、プリセットパス管理者はまずそのようなゲ ["cx", "u"] ートを基底に分解し、得られた1量子ビットユニタリゲートに対してソロベイ・キタエフ法を適用する。

高レベル合成

Qiskitで直接利用可能な高レベル合成プラグインには、オブジェクトを合成するプラグインがあります。 Clifford オブジェクトを合成するプラグインがあります、 LinearFunction オブジェクト PermutationGate オブジェクトを合成するプラグインがあります。 これらのプラグインの中には、暗黙のうちに全対全接続をターゲットにしているものもある。 これは実用的な制限ではない。 HighLevelSynthesis 通常、レイアウトと配線の前に実行され、最終的な回路が追加のSWAPゲートを挿入することでデバイスの接続性を確実に守るからです。 ACGSynthesisPermutation このプラグインは、最大2層のSWAPゲートであらゆる並べ替えを合成できる。 一方、いくつかのプラグインは、暗黙のうちに線形接続をターゲットにしている。 通常、合成回路は奥行きとゲート数が大きくなるが、次のレイアウトパスでデバイスのトポロジー内で連続する量子ビットを選択すれば、追加のSWAPゲートは挿入されない。 この良い例が、 KMSSynthesisPermutation の順列合成プラグインで、 n の量子ビットの任意の順列を、 n の深さで合成することができる。 一般的に、全対全接続の回路を合成してSWAPゲートを挿入するのと、線形接続の回路を合成してSWAPゲートの挿入数を減らすか、あるいは全く挿入しないのとでは、どちらのアプローチが最終的な回路に良い結果をもたらすかを事前に知ることは難しい。 最後に、いくつかのプラグインは特定のコネクティビティをターゲットにすることができるため、レイアウトが設定された後に実行する必要がある。 この場合、合成された回路は自動的にデバイスのトポロジーに従う。 この良い例が、順列合成プラグイン（ TokenSwapperSynthesisPermutation ）である。このプラグインは、任意のカップリング・マップに対して任意の順列を合成することができる。 詳しくは各プラグインの説明をご覧ください。

それぞれの高レベルオブジェクトについて、Qiskitで直接利用可能なすべてのプラグインをリストアップした表を示します。 プラグインの名前、プラグインのクラス、対象となるコネクティビティ・マップ、そしてオプションで追加情報も含まれる。 プラグインは先に説明した方法で使用する必要があります。 HLSConfig例えば

HLSConfig(permutation=["kms"])

オブジェクトの合成に kms プラグインを使用する高レベル合成コンフィギュレーションを作成します。 PermutationGate すなわち、 name = "permutation" を持つオブジェクトを合成するための高レベル合成コンフィギュレーションを作成します。 この場合、プラグイン名は "kms"、プラグインクラスは KMSSynthesisPermutation. この特殊な合成アルゴリズムは、直線的な最近接結合に忠実な回路を作成した。

高レベル合成プラグイン

クリフォード合成

線形関数合成

順列合成

量子場理論の統合

MCX合成

以下の表は、k個の制御量子ビットを持つゲートで利用可能な合成プラグインの一覧です。 MCXGate ゲートで使用可能な合成プラグインの一覧です。 利用可能なクリーン/ダーティ補助量子ビットの数が十分でない場合、対応する合成メソッドは None を返します。

MCMT合成

整数比較器

合計

パウリ進化合成

モジュラー加算器の合成

ハーフアダーの合成

フルアダー合成

乗数合成