Estimator の入力と出力

パッケージ・バージョン

このページのコードは、以下の要件を使用して開発されました。 これらのバージョン以降の使用をお勧めします。

qiskit[all]~=2.4.0
qiskit-ibm-runtime~=0.46.1

このページでは、IBM Quantum® コンピュート・リソース上でワークロードを実行する Qiskit Runtime Estimator プリミティブの入力と出力の概要を説明します。Estimator では、プリミティブ統合ブロック（PUB） と呼ばれるデータ構造を使用してベクトル化されたワークロードを効率的に定義できます。これらは Estimator プリミティブの run() メソッドへの入力として使用され、定義されたワークロードをジョブとして実行します。その後、ジョブが完了すると、使用した PUB とプリミティブから指定されたランタイム・オプションの両方に依存する形式で結果が返されます。

入力

各 PUB の形式は次のとおりです。

(<単一回路>, <1 つまたは複数のオブザーバブル>, <オプションの 1 つまたは複数のパラメーター値>, <オプションの精度>),

オプションの parameter values はリストまたは単一のパラメーターです。オブザーバブルとパラメーター値の要素は、プリミティブの入力と出力のトピックで説明されている NumPy ブロードキャスティング・ルールに従って組み合わされ、ブロードキャストされた形状の各要素に対して 1 つの期待値推定が返されます。

情報

入力に測定値が含まれている場合、それらは無視されます。

Estimator プリミティブの PUB には最大で 4 つの値を含めることができます。

• 1 つ以上の Parameter オブジェクトを含む可能性のある単一の QuantumCircuit
• 推定する期待値を指定する 1 つ以上のオブザーバブルのリスト（配列に配置されます。例：0 次元配列として表現される単一のオブザーバブル、1 次元配列としてのオブザーバブルのリスト、など）。データは ObservablesArrayLike 形式（Pauli、SparsePauliOp、PauliList、または str）のいずれかで指定できます。
  可換オブザーバブル

  • 同じ PUB 内の可換オブザーバブルは、このメソッドを使用してグループ化されます。
  • 異なる PUB 内の可換オブザーバブルは、同じ回路を持っていても、同じ測定を使用して推定されません。各 PUB は異なる測定基底を表し、したがって各 PUB に対して個別の測定が必要です。
  • 可換オブザーバブルが同じ測定を使用して推定されるようにするには、同じ PUB 内にグループ化してください。
• 回路に対してバインドするパラメーター値のコレクション。最後のインデックスが回路の Parameter オブジェクトに対応する単一の配列のようなオブジェクトとして指定するか、回路に Parameter オブジェクトがない場合は省略する（または等価に None に設定する）ことができます。
• （オプション）推定する期待値の目標精度

---

以下のコードは、Estimator プリミティブへのベクトル化された入力のセットの例を示し、単一の RuntimeJobV2 オブジェクトとして IBM® バックエンドで実行します。

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

from qiskit.circuit import (
    Parameter,
    QuantumCircuit,
)
from qiskit.transpiler import generate_preset_pass_manager
from qiskit.quantum_info import SparsePauliOp

from qiskit_ibm_runtime import (
    QiskitRuntimeService,
    EstimatorV2 as Estimator,
)

import numpy as np

# Instantiate runtime service and get
# the least busy backend
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

# Define a circuit with two parameters.
circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
circuit.ry(Parameter("a"), 0)
circuit.rz(Parameter("b"), 0)
circuit.cx(0, 1)
circuit.h(0)

# Transpile the circuit
pm = generate_preset_pass_manager(optimization_level=1, backend=backend)
transpiled_circuit = pm.run(circuit)
layout = transpiled_circuit.layout

# Now define a sweep over parameter values, the last axis of dimension 2 is
# for the two parameters "a" and "b"
params = np.vstack(
    [
        np.linspace(-np.pi, np.pi, 100),
        np.linspace(-4 * np.pi, 4 * np.pi, 100),
    ]
).T

# Define three observables. The inner length-1 lists cause this array of
# observables to have shape (3, 1), rather than shape (3,) if they were
# omitted.
observables = [
    [SparsePauliOp(["XX", "IY"], [0.5, 0.5])],
    [SparsePauliOp("XX")],
    [SparsePauliOp("IY")],
]
# Apply the same layout as the transpiled circuit.
observables = [
    [observable.apply_layout(layout) for observable in observable_set]
    for observable_set in observables
]

# Estimate the expectation value for all 300 combinations of observables
# and parameter values, where the pub result will have shape (3, 100).
#
# This shape is due to our array of parameter bindings having shape
# (100, 2), combined with our array of observables having shape (3, 1).
estimator_pub = (transpiled_circuit, observables, params)

# Instantiate the new Estimator object, then run the transpiled circuit
# using the set of parameters and observables.
estimator = Estimator(mode=backend)
job = estimator.run([estimator_pub])
result = job.result()

出力

1 つ以上の PUB が実行のために QPU に送信され、ジョブが正常に完了すると、データは RuntimeJobV2.result() メソッドを呼び出すことでアクセスできる PrimitiveResult コンテナー・オブジェクトとして返されます。

PrimitiveResult には、各 PUB の実行結果を含む PubResult オブジェクトのイテラブル・リストが含まれています。

このリストの各要素は、プリミティブの run() メソッドに送信された各 PUB に対応しています（例えば、20 個の PUB で送信されたジョブは、各 PUB に対応する 20 個の PubResult オブジェクトのリストを含む PrimitiveResult オブジェクトを返します）。

Estimator プリミティブの各 PubResult には、少なくとも期待値の配列（PubResult.data.evs）と関連する標準偏差（使用する resilience_level に応じて PubResult.data.stds または PubResult.data.ensemble_standard_error）が含まれていますが、指定されたエラー緩和オプションによってはより多くのデータが含まれる場合があります。

各 PubResult オブジェクトは data と metadata の両方の属性を持ちます。

• data 属性は実際の測定値、標準偏差などを含むカスタマイズされた DataBin です。
• DataBin は、関連する PUB の形状または構造、およびジョブを送信するために使用されたプリミティブで指定されたエラー緩和オプション（例：ZNE または PEC）に応じてさまざまな属性を持ちます。
• metadata 属性には、使用されたランタイムとエラー緩和オプションに関する情報が含まれています（このページの後半の結果メタデータセクションで説明）。

以下は Estimator 出力の PrimitiveResult データ構造の視覚的な概要です。

└── PrimitiveResult
    ├── PubResult[0]
    │   ├── metadata
    │   └── data  ## In the form of a DataBin object
    │       ├── evs
    │       │   └── List of estimated expectation values in the shape
    |       |         specified by the first pub
    │       └── stds
    │           └── List of calculated standard deviations in the
    |                 same shape as above
    ├── PubResult[1]
    |   ├── metadata
    |   └── data  ## In the form of a DataBin object
    |       ├── evs
    |       │   └── List of estimated expectation values in the shape
    |       |        specified by the second pub
    |       └── stds
    |           └── List of calculated standard deviations in the
    |                same shape as above
    ├── ...
    ├── ...
    └── ...

簡単に言うと、単一のジョブは PrimitiveResult オブジェクトを返し、1 つ以上の PubResult オブジェクトのリストを含みます。これらの PubResult オブジェクトは、ジョブに送信された各 PUB の測定データを格納します。

以下のコード・スニペットは、上記で作成したジョブの PrimitiveResult（および関連する PubResult）の形式を説明しています。

print(
    f"The result of the submitted job had {len(result)} "
    f"PUBs and has a value:\n {result}\n"
)
print(
    "The associated PubResult of this job has the following data bins:\n "
    "{result[0].data}\n"
)
print(f"And this DataBin has attributes: {result[0].data.keys()}")
print(
    "Recall that this shape is due to our array of parameter binding sets"
    "having shape (100, 2), where 2 is the number of parameters in the "
    "circuit, combined with our array of observables having shape (3, 1). \n"
)
with np.printoptions(threshold=200):
    print(
        "The expectation values measured from this PUB are: \n"
        "{result[0].data.evs}\n"
    )

The result of the submitted job had 1 PUB and has a value:
 PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(<shape=(3, 100), dtype=float64>), stds=np.ndarray(<shape=(3, 100), dtype=float64>), ensemble_standard_error=np.ndarray(<shape=(3, 100), dtype=float64>), shape=(3, 100)), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32})], metadata={'dynamical_decoupling': {'enable': False, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'}, 'twirling': {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'}, 'resilience': {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False}, 'version': 2})

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

And this DataBin has attributes: dict_keys(['evs', 'stds', 'ensemble_standard_error'])
Recall that this shape is due to our array of parameter binding sets having shape (100, 2) -- where 2 is the
         number of parameters in the circuit -- combined with our array of observables having shape (3, 1). 

The expectation values measured from this PUB are: 
[[-0.00369065  0.15107692  0.30110431 ... -0.30159536 -0.15431523
   0.00576586]
 [ 0.00601655  0.04412133  0.1253447  ... -0.12434194 -0.04662823
   0.01153171]
 [-0.01339784  0.2580325   0.47686391 ... -0.47884878 -0.26200223
   0.        ]]

Estimator プリミティブによるエラー計算の方法

入力 PUB で渡されたオブザーバブルの平均推定値（DataBin の evs フィールド）に加えて、Estimator はこれらの期待値に関連するエラーの推定値も提供しようとします。すべての Estimator クエリーは、各期待値の平均の標準誤差に類似した量で stds フィールドを埋めますが、一部のエラー緩和オプションは ensemble_standard_error などの追加情報を生成します。

単一のオブザーバブル $\mathcal{O}$ を考えます。ZNE がない場合、Estimator 実行の各ショットは期待値 $\langle \mathcal{O} \rangle$ の点推定値を提供すると考えることができます。点推定値がベクトル Os にある場合、ensemble_standard_error で返される値は以下と等価です（$\sigma_{\mathcal{O}}$ は期待値の標準偏差の推定値、$N_{shots}$ はショット数）。

$\frac{ \sigma_{\mathcal{O}} }{ \sqrt{N_{shots}} },$

これはすべてのショットを単一のアンサンブルの一部として扱います。ゲートのツワーリング（twirling.enable_gates = True）を要求した場合、$\langle \mathcal{O} \rangle$ の点推定値を共通のツワールを共有するセットに分類できます。これらの推定値のセットを O_twirls と呼び、num_randomizations（ツワールの数）個あります。そして stds は O_twirls の平均の標準誤差です。

$\frac{ \sigma_{\mathcal{O}} }{ \sqrt{N_{twirls}} },$

ここで $\sigma_{\mathcal{O}}$ は O_twirls の標準偏差、$N_{twirls}$ はツワールの数です。ツワーリングを有効にしない場合、stds と ensemble_standard_error は等しくなります。

ZNE を有効にすると、上述の stds は外挿モデルへの非線形回帰の重みになります。この場合に最終的に stds として返されるのは、ノイズ係数ゼロで評価されたフィット・モデルの不確実性です。フィットが悪い場合や、フィットの不確実性が大きい場合、報告される stds は非常に大きくなる可能性があります。ZNE が有効な場合、pub_result.data.evs_noise_factors と pub_result.data.stds_noise_factors も埋められるため、独自の外挿を行うことができます。

結果メタデータ

実行結果に加えて、PrimitiveResult と PubResult の両方のオブジェクトには、送信されたジョブに関するメタデータ属性が含まれています。送信されたすべての PUB に関する情報（利用可能なさまざまなランタイム・オプションなど）を含むメタデータは PrimitiveResult.metadata にあり、各 PUB 固有のメタデータは PubResult.metadata にあります。

備考

メタデータ・フィールドでは、プリミティブの実装は実行に関連する任意の情報を返すことができ、基底プリミティブによって保証されるキー・バリュー・ペアはありません。したがって、返されるメタデータは異なるプリミティブの実装によって異なる場合があります。

# Print out the results metadata
print("The metadata of the PrimitiveResult is:")
for key, val in result.metadata.items():
    print(f"'{key}' : {val},")

print("\nThe metadata of the PubResult result is:")
for key, val in result[0].metadata.items():
    print(f"'{key}' : {val},")

The metadata of the PrimitiveResult is:
'dynamical_decoupling' : {'enable': False, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'},
'twirling' : {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'},
'resilience' : {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False},
'version' : 2,

The metadata of the PubResult result is:
'shots' : 4096,
'target_precision' : 0.015625,
'circuit_metadata' : {},
'resilience' : {},
'num_randomizations' : 32,