IBM Circuit function

注意

• Qiskit Functionsは、IBM Quantum® Premium Plan、Flex Plan、およびOn-Prem（IBM Quantum Platform API経由）Planのユーザーのみが利用できる実験的な機能です。プレビューリリースの状態であり、変更される可能性があります。

概要

IBM® Circuit functionは、抽象PUBを入力として受け取り、緩和された期待値を出力として返します。このCircuit functionには、研究者がアルゴリズムやアプリケーションの発見に集中できるよう、自動化されたカスタマイズパイプラインが含まれています。

説明

PUBを送信すると、抽象Circuitとオブザーバブルが自動的にトランスパイルされ、ハードウェア上で実行され、後処理によって緩和された期待値が返されます。これを実現するために、以下のツールを組み合わせています：

• Qiskit Transpiler Service：AIによるトランスパイルパスとヒューリスティックなトランスパイルパスの自動選択により、抽象Circuitをハードウェア最適化されたISA Circuitに変換します
• ユーティリティスケールの計算に必要なエラー抑制と緩和：測定とゲートのtwirling、ダイナミカルデカップリング、Twirled Readout Error eXtinction（TREX）、Zero-Noise Extrapolation（ZNE）、Probabilistic Error Amplification（PEA）を含みます
• Qiskit Runtime Estimator：ISA PUBをハードウェア上で実行し、緩和された期待値を返します

はじめに

APIキーを使って認証を行い、以下のようにQiskit Functionを選択します。（このスニペットは、すでにアカウントを保存済みであることを前提としています。）

# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-catalog qiskit-ibm-runtime

from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

function = catalog.load("ibm/circuit-function")

例

まず、この基本的な例を試してみてください：

from qiskit.circuit.random import random_circuit
from qiskit_ibm_runtime import QiskitRuntimeService

# You can skip this step if you have a target backend, e.g.
# backend_name = "ibm_brisbane"
# You'll need to specify the credentials when initializing QiskitRuntimeService, if they were not previously saved.
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

circuit = random_circuit(num_qubits=2, depth=2, seed=42)
observable = "Z" * circuit.num_qubits
pubs = [(circuit, observable)]

job = function.run(
    # Use `backend_name=backend_name` if you didn't initialize a backend object
    backend_name=backend.name,
    pubs=pubs,
)

Qiskit Functionワークロードのステータスを確認したり、以下のように結果を取得したりできます：

print(job.status())
result = job.result()

QUEUED

結果はEstimatorの結果と同じ形式です：

print(f"The result of the submitted job had {len(result)} PUB\n")
print(
    f"The associated PubResult of this job has the following DataBins:\n {result[0].data}\n"
)
print(f"And this DataBin has attributes: {result[0].data.keys()}")
print(
    f"The expectation values measured from this PUB are: \n{result[0].data.evs}"
)

The result of the submitted job had 1 PUB

The associated PubResult of this job has the following DataBins:
 DataBin(evs=np.ndarray(<shape=(), dtype=float64>), stds=np.ndarray(<shape=(), dtype=float64>), ensemble_standard_error=np.ndarray(<shape=(), dtype=float64>))

And this DataBin has attributes: dict_keys(['evs', 'stds', 'ensemble_standard_error'])
The expectation values measured from this PUB are:
1.02116704805492

入力

IBM Circuit functionが受け付けるすべての入力パラメーターについては、以下の表を参照してください。続くオプションセクションでは、利用可能なoptionsについて詳しく説明します。

名前	型	説明	必須	デフォルト	例
backend_name	str	クエリを実行するBackendの名前。	はい	なし	ibm_fez
pubs	Iterable[EstimatorPubLike]	(circuit, observables) または (circuit, observables, parameter_values) のようなタプルなど、抽象PUBライク（primitive unified bloc）オブジェクトのイテラブル。詳しくはPUBの概要を参照してください。Circuitは抽象（非ISA）でも構いません。	はい	なし	(circuit, observables, parameter_values)
options	dict	入力オプション。詳細はオプションセクションを参照してください。	いいえ	詳細はオプションセクションを参照してください。	{"optimization_level": 3}
instance	str	使用するインスタンスのクラウドリソース名（その形式で指定）。	いいえ	アカウントが複数のインスタンスにアクセスできる場合、ランダムに1つ選択されます。	CRN

オプション

構造

Qiskit Runtimeプリミティブと同様に、IBM Circuit functionのオプションはネストされた辞書として指定できます。optimization_level や mitigation_level などのよく使われるオプションは第1レベルにあります。その他のより高度なオプションは、resilience などのカテゴリにまとめられています。

デフォルト値

オプションの値を指定しない場合、サービスによって定義されたデフォルト値が使用されます。

緩和レベル

IBM Circuit functionはmitigation_levelもサポートしています。緩和レベルは、ジョブに適用するエラー抑制および緩和の量を指定します。レベルが高いほど精度の高い結果が得られますが、処理時間が長くなります。エラー削減の程度は適用される手法によって異なります。緩和レベルは、エラー緩和と抑制の手法の詳細な選択を抽象化し、ユーザーがアプリケーションに適したコストと精度のトレードオフを判断できるようにします。以下の表は、各レベルに対応する手法を示しています。

備考

名前は似ていますが、mitigation_levelはEstimatorのresilience_levelとは異なるテクニックを適用します。

Qiskit Runtime Estimatorのresilience_levelと同様に、mitigation_levelはキュレートされたオプションの基本セットを指定します。緩和レベルに加えて手動で指定したオプションは、緩和レベルによって定義された基本オプションセットの上に適用されます。そのため、原則として、緩和レベルを1に設定しながら測定緩和をオフにすることも可能ですが、これは推奨されません。

緩和レベル	テクニック
1 [デフォルト]	ダイナミカルデカップリング + 測定twirling + TREX
2	レベル1 + ゲートtwirling + ゲートフォールディングによるZNE
3	レベル1 + ゲートtwirling + PEAによるZNE

以下の例は、緩和レベルの設定方法を示しています：

options = {"mitigation_level": 2}

job = function.run(backend_name=backend.name, pubs=pubs, options=options)

利用可能なすべてのオプション

mitigation_levelに加えて、IBM Circuit functionはコストと精度のトレードオフを細かく調整できる高度なオプションも提供しています。以下の表はすべての利用可能なオプションを示しています：

オプション	サブオプション	サブサブオプション	説明	選択肢	デフォルト
default_precision			精度を指定しないPUBまたはrun()呼び出しに使用するデフォルトの精度。 各入力PUBは独自の精度を指定できます。run()メソッドに精度が指定された場合、その値は独自の精度を指定していないrun()呼び出し内のすべてのPUBに使用されます。	float > 0	0.015625
max_execution_time			秒単位の最大実行時間。QPU使用量（ウォールクロック時間ではなく）に基づきます。QPU使用量は、QPUがジョブの処理に専念する時間です。ジョブがこの時間制限を超えた場合、強制的にキャンセルされます。	秒単位の整数、範囲 [1, 10800]
mitigation_level			適用するエラー抑制と緩和の量。各レベルで使用される手法の詳細については、緩和レベルセクションを参照してください。	1 / 2 / 3	1
optimization_level			Circuitに対して実行する最適化の量。高いレベルほど最適化されたCircuitが生成されますが、トランスパイル時間が長くなります。	1 / 2 / 3	2
dynamical_decoupling	enable		ダイナミカルデカップリングを有効にするかどうか。手法の説明についてはエラー抑制と緩和テクニックを参照してください。	True/False	True
	sequence_type		使用するダイナミカルデカップリングシーケンス。 * XX：シーケンス tau/2 - (+X) - tau - (+X) - tau/2 を使用 * XpXm：シーケンス tau/2 - (+X) - tau - (-X) - tau/2 を使用 * XY4：シーケンス tau/2 - (+X) - tau - (+Y) - tau (-X) - tau - (-Y) - tau/2 を使用	'XX'/'XpXm'/'XY4'	'XX'
twirling	enable_gates		2-Qubit Cliffordゲートのtwirlingを適用するかどうか。	True/False	False
	enable_measure		測定のtwirlingを有効にするかどうか。	True/False	True
resilience	measure_mitigation		TREXの測定エラー緩和手法を有効にするかどうか。手法の説明についてはエラー抑制と緩和テクニックを参照してください。	True/False	True
	zne_mitigation		Zero Noise Extrapolationエラー緩和手法をオンにするかどうか。手法の説明についてはエラー抑制と緩和テクニックを参照してください。	True/False	False
	zne	amplifier	ノイズを増幅するために使用するテクニック。以下のいずれか： - gate_folding（デフォルト）：ノイズを増幅するために2-QubitゲートフォールディングGateを使用します。ノイズ係数がゲートのサブセットのみを増幅する必要がある場合、これらのゲートはランダムに選択されます。 - gate_folding_front：ノイズを増幅するために2-Qubitゲートフォールディングを使用します。ノイズ係数がゲートのサブセットのみを増幅する必要がある場合、これらのゲートはトポロジー的に順序付けされたDAG Circuitの先頭から選択されます。 - gate_folding_back：ノイズを増幅するために2-Qubitゲートフォールディングを使用します。ノイズ係数がゲートのサブセットのみを増幅する必要がある場合、これらのゲートはトポロジー的に順序付けされたDAG Circuitの末尾から選択されます。 - pea：Probabilistic error amplification（PEA）と呼ばれるテクニックを使用してノイズを増幅します。手法の説明についてはエラー抑制と緩和テクニックを参照してください。	gate_folding / gate_folding_front / gate_folding_back / pea	gate_folding
		noise_factors	ノイズ増幅に使用するノイズ係数。	floatのリスト；各float >= 1	PEAの場合は(1, 1.5, 2)、それ以外は(1, 3, 5)。
		extrapolator	フィット外挿モデルを評価するノイズ係数。このオプションは実行やモデルフィッティングには影響しません；extrapolatorオブジェクトが評価されてevs_extrapolatedとstds_extrapolatedというデータフィールドに返される点のみを決定します。	exponential、linear、double_exponential、polynomial_degree_(1 <= k <= 7) の1つ以上	(exponential, linear)
	pec_mitigation		Probabilistic Error Cancellationエラー緩和手法をオンにするかどうか。手法の説明についてはエラー抑制と緩和テクニックを参照してください。	True/False	False
	pec	max_overhead	許容される最大Circuit samplingオーバーヘッド。最大値なしの場合はNone。	None / 1より大きい整数	100

以下の例では、緩和レベルを1に設定すると最初はZNE緩和がオフになりますが、zne_mitigationをTrueに設定するとmitigation_levelの関連設定が上書きされます。

options = {"mitigation_level": 1, "resilience": {"zne_mitigation": True}}

出力

Circuit functionの出力はPrimitiveResultであり、以下の2つのフィールドが含まれます：

• 1つ以上のPubResultオブジェクト。PrimitiveResultから直接インデックスを指定してアクセスできます。

• ジョブレベルのメタデータ。

各PubResultにはdataフィールドとmetadataフィールドが含まれます。

• dataフィールドには、少なくとも期待値の配列（PubResult.data.evs）と標準誤差の配列（PubResult.data.stds）が含まれます。使用するオプションによっては、さらに多くのデータが含まれることもあります。

• metadataフィールドにはPUBレベルのメタデータ（PubResult.metadata）が含まれます。

以下のコードスニペットはPrimitiveResult（および関連するPubResult）の形式を説明しています。

print(f"The result of the submitted job had {len(result)} PUB")
print(
    f"The expectation values measured from this PUB are: \n{result[0].data.evs}"
)
print(f"And the associated metadata is: \n{result[0].metadata}")

The result of the submitted job had 1 PUB
The expectation values measured from this PUB are:
1.02116704805492
And the associated metadata is:
{'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}

エラーメッセージの取得

ワークロードのステータスがERRORの場合、以下のようにjob.result()を使用してエラーメッセージを取得し、デバッグに役立ててください：

job = function.run(
    backend_name="bad_backend_name", pubs=pubs, options=options
)

print(job.result())

サポートを受ける

IBM Quantumサポートにお問い合わせいただき、以下の情報をご提供ください：

• Qiskit Function ジョブID（qiskit-ibm-catalog）、job.job_id
• 問題の詳細な説明
• 関連するエラーメッセージやコード
• 問題を再現する手順

次のステップ

おすすめ

• IBM Circuit functionを使ったエラー緩和チュートリアルを試してみてください。