Estimator 입력 및 출력

패키지 버전

이 페이지의 코드는 다음 요구 사항을 사용하여 개발되었습니다. 이 버전 이상을 사용하는 것을 권장합니다.

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

이 페이지에서는 IBM Quantum® 컴퓨팅 자원에서 워크로드를 실행하는 Qiskit Runtime Estimator Primitive의 입력 및 출력에 대한 개요를 제공합니다. Estimator는 Primitive Unified Bloc (PUB)이라는 데이터 구조를 사용하여 벡터화된 워크로드를 효율적으로 정의할 수 있도록 합니다. PUB는 Estimator Primitive의 run() 메서드에 입력으로 사용되며, 정의된 워크로드를 Job으로 실행합니다. Job이 완료된 후에는 사용한 PUB 및 Primitive에서 지정한 런타임 옵션에 따라 결과가 반환됩니다.

입력

각 PUB는 다음 형식을 따릅니다:

(<단일 Circuit>, <하나 이상의 Observable>, <선택적: 하나 이상의 매개변수 값>, <선택적: 정밀도>),

선택적인 매개변수 값은 목록 또는 단일 매개변수가 될 수 있습니다. Observable과 매개변수 값의 요소는 Primitive 입력 및 출력 항목에 설명된 NumPy 브로드캐스팅 규칙에 따라 결합되며, 브로드캐스트된 형태의 각 요소에 대해 하나의 기댓값 추정치가 반환됩니다.

정보

입력에 측정이 포함된 경우 이는 무시됩니다.

Estimator Primitive의 경우 PUB에는 최대 네 가지 값이 포함될 수 있습니다:

• 하나 이상의 Parameter 객체를 포함할 수 있는 단일 QuantumCircuit
• 추정할 기댓값을 지정하는 하나 이상의 Observable 목록으로, 배열로 정렬됩니다(예: 단일 Observable은 0차원 배열, Observable 목록은 1차원 배열 등). 데이터는 Pauli, SparsePauliOp, PauliList, str과 같은 ObservablesArrayLike 형식 중 하나로 제공될 수 있습니다.
  가환 Observable

  • 동일한 PUB 내의 가환 Observable은 이 메서드를 사용하여 그룹화됩니다.
  • 다른 PUB에 있는 가환 Observable은 동일한 Circuit을 가지더라도 동일한 측정을 사용하여 추정되지 않습니다. 각 PUB는 서로 다른 측정 기저를 나타내므로 각 PUB에 대해 별도의 측정이 필요합니다.
  • 가환 Observable이 동일한 측정을 사용하여 추정되도록 하려면 동일한 PUB 내에 그룹화하세요.
• Circuit에 바인딩할 매개변수 값의 컬렉션. 이는 마지막 인덱스가 Circuit의 Parameter 객체에 해당하는 단일 배열 형식 객체로 지정하거나, Circuit에 Parameter 객체가 없는 경우 생략(또는 동등하게 None으로 설정)할 수 있습니다.
• (선택적) 추정할 기댓값의 목표 정밀도

---

다음 코드는 Estimator Primitive에 대한 벡터화된 입력 예제를 보여주고, 이를 IBM® Backend에서 단일 RuntimeJobV2 객체로 실행합니다.

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

출력

하나 이상의 PUB가 QPU로 전송되어 Job이 성공적으로 완료되면, 데이터는 RuntimeJobV2.result() 메서드를 호출하여 접근하는 PrimitiveResult 컨테이너 객체로 반환됩니다.

PrimitiveResult는 각 PUB의 실행 결과를 포함하는 PubResult 객체의 반복 가능한 목록을 포함합니다.

이 목록의 각 요소는 Primitive의 run() 메서드에 제출된 각 PUB에 해당합니다(예: 20개의 PUB와 함께 제출된 Job은 각 PUB에 해당하는 20개의 PubResult 객체 목록을 포함하는 PrimitiveResult 객체를 반환합니다).

Estimator Primitive의 각 PubResult는 최소한 기댓값 배열(PubResult.data.evs)과 관련 표준 편차(사용된 resilience_level에 따라 PubResult.data.stds 또는 PubResult.data.ensemble_standard_error)를 포함하지만, 지정된 오류 완화 옵션에 따라 더 많은 데이터를 포함할 수 있습니다.

각 PubResult 객체는 data와 metadata 속성을 모두 가집니다.

• data 속성은 실제 측정값, 표준 편차 등을 포함하는 사용자 정의 DataBin입니다.
• DataBin은 관련 PUB의 형태나 구조 및 Job을 제출하는 데 사용된 Primitive에서 지정한 오류 완화 옵션(예: 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
    ├── ...
    ├── ...
    └── ...

간단히 말해서, 단일 Job은 PrimitiveResult 객체를 반환하고 하나 이상의 PubResult 객체 목록을 포함합니다. 이 PubResult 객체들은 Job에 제출된 각 PUB의 측정 데이터를 저장합니다.

아래 코드 스니펫은 위에서 생성된 Job의 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 Primitive의 오류 계산 방법

입력 PUB에서 전달된 Observable의 평균 추정치(DataBin의 evs 필드) 외에도, Estimator는 해당 기댓값과 관련된 오류 추정치도 제공합니다. 모든 Estimator 쿼리는 각 기댓값에 대한 평균의 표준 오차와 유사한 양으로 stds 필드를 채우지만, 일부 오류 완화 옵션은 ensemble_standard_error와 같은 추가 정보를 생성합니다.

단일 Observable $\mathcal{O}$를 고려해 보세요. ZNE가 없는 경우, Estimator 실행의 각 샷은 기댓값 $\langle \mathcal{O} \rangle$의 점 추정치를 제공한다고 생각할 수 있습니다. 점별 추정치가 벡터 Os에 있는 경우, ensemble_standard_error에서 반환된 값은 다음과 같습니다(여기서 $\sigma_{\mathcal{O}}$는 기댓값의 표준 편차 추정치이고 $N_{shots}$는 샷 수입니다):

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

이는 모든 샷을 단일 앙상블의 일부로 처리합니다. Gate 트월링(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에 최종적으로 반환되는 것은 노이즈 계수 0에서 평가된 적합 모델의 불확실도입니다. 적합이 좋지 않거나 적합의 불확실도가 크면 보고된 stds가 매우 커질 수 있습니다. ZNE가 활성화된 경우 직접 외삽할 수 있도록 pub_result.data.evs_noise_factors와 pub_result.data.stds_noise_factors도 채워집니다.

결과 메타데이터

실행 결과 외에도, PrimitiveResult와 PubResult 객체 모두 제출된 Job에 대한 메타데이터 속성을 포함합니다. 제출된 모든 PUB에 대한 정보(사용 가능한 다양한 런타임 옵션 등)를 포함하는 메타데이터는 PrimitiveResult.metatada에서 찾을 수 있으며, 각 PUB에 특정한 메타데이터는 PubResult.metadata에서 찾을 수 있습니다.

참고

메타데이터 필드에서 Primitive 구현은 자신과 관련된 실행에 대한 모든 정보를 반환할 수 있으며, 기본 Primitive에 의해 보장되는 키-값 쌍은 없습니다. 따라서 반환된 메타데이터는 다른 Primitive 구현에서 다를 수 있습니다.

# 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,