อินพุตและเอาต์พุตของ Estimator

เวอร์ชันแพ็กเกจ

โค้ดในหน้านี้พัฒนาโดยใช้ requirements ต่อไปนี้ แนะนำให้ใช้เวอร์ชันเหล่านี้หรือใหม่กว่า

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

หน้านี้ให้ภาพรวมของ inputs และ outputs ของ Qiskit Runtime Estimator primitive ซึ่งรัน workloads บน IBM Quantum® compute resources Estimator ให้คุณกำหนด vectorized workloads ได้อย่างมีประสิทธิภาพโดยใช้โครงสร้างข้อมูลที่เรียกว่า Primitive Unified Bloc (PUB) ซึ่งใช้เป็น inputs ของเมธอด run() สำหรับ Estimator primitive ซึ่งรัน workload ที่กำหนดเป็น job จากนั้น หลังจาก job เสร็จสิ้น ผลลัพธ์จะถูกส่งคืนในรูปแบบที่ขึ้นอยู่กับทั้ง PUBs ที่ใช้และ runtime options ที่ระบุจาก primitive

Inputs

แต่ละ PUB อยู่ในรูปแบบนี้:

(<single circuit>, <one or more observables>, <optional one or more parameter values>, <optional precision>),

parameter values ทางเลือกสามารถเป็น list หรือ parameter เดียว Elements จาก observables และ parameter values จะถูกรวมกันโดยทำตาม NumPy broadcasting rules ตามที่อธิบายในหัวข้อ Primitive inputs and outputs และหนึ่ง expectation value estimate จะถูกส่งคืนสำหรับแต่ละ element ของ broadcasted shape

ข้อมูล

ถ้า input มีการวัด จะถูก ignore

สำหรับ Estimator primitive PUB สามารถมีได้สูงสุดสี่ค่า:

• QuantumCircuit เดียว ซึ่งอาจมี object Parameter หนึ่งรายการหรือมากกว่า
• List ของ observables หนึ่งรายการหรือมากกว่า ซึ่งระบุ expectation values ที่จะประมาณ จัดเป็น array (ตัวอย่างเช่น observable เดียวแสดงเป็น 0-d array, list ของ observables เป็น 1-d array และอื่นๆ) ข้อมูลสามารถอยู่ในรูปแบบ ObservablesArrayLike ใดก็ได้ เช่น Pauli, SparsePauliOp, PauliList หรือ str
  Commuting observables

  • Commuting observables ใน PUB เดียวกัน จะถูกจัดกลุ่มโดยใช้ วิธีนี้
  • Commuting observables ใน PUBs ที่แตกต่างกัน แม้ว่าจะมี circuit เดียวกัน จะไม่ถูกประมาณโดยใช้การวัดเดียวกัน แต่ละ PUB แสดง basis ที่แตกต่างกันสำหรับการวัด ดังนั้น จำเป็นต้องวัดแยกกันสำหรับแต่ละ PUB
  • เพื่อให้แน่ใจว่า commuting observables ถูกประมาณโดยใช้การวัดเดียวกัน จัดกลุ่มไว้ใน PUB เดียวกัน
• คอลเลกชันของค่า parameter เพื่อ bind circuit กับสิ่งนี้ สามารถระบุเป็น single array-like object ที่ last index อยู่เหนือ circuit Parameter objects หรือละเว้น (หรือเทียบเท่ากัน ตั้งเป็น None) ถ้า circuit ไม่มี Parameter objects
• (ทางเลือก) Target precision สำหรับ expectation values ที่จะประมาณ

---

โค้ดต่อไปนี้แสดงตัวอย่างชุด vectorized inputs ให้กับ Estimator primitive และรันบน IBM® backend เป็น RuntimeJobV2 object เดียว

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

Outputs

หลังจากส่ง PUBs หนึ่งรายการหรือมากกว่าไปยัง QPU เพื่อรัน และ job เสร็จสำเร็จ ข้อมูลจะถูกส่งคืนเป็น container object PrimitiveResult ที่เข้าถึงได้โดยการเรียกเมธอด RuntimeJobV2.result()

PrimitiveResult มี iterable list ของ object PubResult ที่มีผลการรันสำหรับแต่ละ PUB

แต่ละ element ของ list นี้สอดคล้องกับแต่ละ PUB ที่ส่งไปยังเมธอด run() ของ primitive (ตัวอย่างเช่น job ที่ส่งกับ 20 PUBs จะส่งคืน PrimitiveResult object ที่มี list ของ PubResult objects 20 รายการ หนึ่งสอดคล้องกับแต่ละ PUB)

แต่ละ PubResult สำหรับ Estimator primitive มีอย่างน้อย array ของ expectation values (PubResult.data.evs) และ standard deviations ที่เกี่ยวข้อง (ไม่ว่าจะเป็น PubResult.data.stds หรือ PubResult.data.ensemble_standard_error ขึ้นอยู่กับ resilience_level ที่ใช้) แต่อาจมีข้อมูลเพิ่มเติมขึ้นอยู่กับ error mitigation options ที่ระบุ

แต่ละ PubResult object มีทั้ง data และ metadata attribute

• Attribute data เป็น DataBin ที่กำหนดเองซึ่งมีค่าการวัดจริง standard deviations และอื่นๆ
• DataBin มี attributes ต่างๆ ขึ้นอยู่กับ shape หรือโครงสร้างของ PUB ที่เกี่ยวข้อง รวมถึง error mitigation options ที่ระบุโดย primitive ที่ใช้ส่ง job (เช่น ZNE หรือ PEC)
• Attribute metadata มีข้อมูลเกี่ยวกับ runtime และ error mitigation options ที่ใช้ (อธิบายในส่วน Result metadata ของหน้านี้)

ต่อไปนี้คือโครงร่างภาพของโครงสร้างข้อมูล PrimitiveResult สำหรับ Estimator output:

└── 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 object และมี list ของ PubResult objects หนึ่งรายการหรือมากกว่า PubResult objects เหล่านี้เก็บข้อมูลการวัดสำหรับแต่ละ PUB ที่ส่งไปยัง job

code snippet ด้านล่างอธิบายรูปแบบ PrimitiveResult (และ PubResult ที่เกี่ยวข้อง) สำหรับ job ที่สร้างด้านบน

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 คำนวณ error

นอกจากการประมาณ mean ของ observables ที่ส่งใน input PUBs (field evs ของ DataBin) Estimator ยังพยายามให้การประมาณ error ที่เกี่ยวข้องกับ expectation values เหล่านั้น Estimator queries ทั้งหมดจะ populate field stds ด้วยปริมาณที่คล้ายกับ standard error of the mean สำหรับแต่ละ expectation value แต่ error mitigation options บางอย่างให้ข้อมูลเพิ่มเติม เช่น ensemble_standard_error

พิจารณา observable เดียว $\mathcal{O}$ ในกรณีที่ไม่มี ZNE คุณสามารถคิดว่าแต่ละ shot ของการรัน Estimator ให้ point estimate ของ expectation value $\langle \mathcal{O} \rangle$ ถ้า pointwise estimates อยู่ใน vector Os ค่าที่ส่งคืนใน ensemble_standard_error เทียบเท่ากับสิ่งต่อไปนี้ (ใน $\sigma_{\mathcal{O}}$ คือ standard deviation ของ expectation value estimate และ $N_{shots}$ คือจำนวน shots):

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

ซึ่งถือว่า shots ทั้งหมดเป็นส่วนหนึ่งของ ensemble เดียว ถ้าคุณร้องขอ gate twirling (twirling.enable_gates = True) คุณสามารถจัด pointwise estimates ของ $\langle \mathcal{O} \rangle$ เป็น sets ที่แบ่งปัน twirl ร่วม เรียก sets ของ estimates เหล่านี้ว่า O_twirls และมี num_randomizations (จำนวน twirls) ของพวกมัน จากนั้น stds คือ standard error of the mean ของ O_twirls ดังใน

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

โดย $\sigma_{\mathcal{O}}$ คือ standard deviation ของ O_twirls และ $N_{twirls}$ คือจำนวน twirls เมื่อคุณไม่เปิดใช้งาน twirling stds และ ensemble_standard_error จะเท่ากัน

ถ้าคุณเปิดใช้งาน ZNE stds ที่อธิบายด้านบนจะกลายเป็น weights ใน non-linear regression ไปยัง extrapolator model สิ่งที่ส่งคืนใน stds ในกรณีนี้คือความไม่แน่นอนของ fit model ที่ประเมินที่ noise factor เป็นศูนย์ เมื่อ fit ไม่ดีหรือมีความไม่แน่นอนในการ fit มาก stds ที่รายงานอาจมีขนาดใหญ่มาก เมื่อเปิดใช้งาน ZNE pub_result.data.evs_noise_factors และ pub_result.data.stds_noise_factors ก็จะ populate ด้วย เพื่อให้คุณสามารถ extrapolate ด้วยตัวเอง

Result metadata

นอกจากผลการรัน ทั้ง PrimitiveResult และ PubResult objects มี metadata attribute เกี่ยวกับ job ที่ส่ง metadata ที่มีข้อมูลสำหรับ PUBs ที่ส่งทั้งหมด (เช่น runtime options ต่างๆ ที่มี) สามารถพบได้ใน PrimitiveResult.metatada ในขณะที่ metadata เฉพาะสำหรับแต่ละ PUB พบได้ใน PubResult.metadata

หมายเหตุ

ในฟิลด์ metadata การ implement primitive สามารถส่งคืนข้อมูลเกี่ยวกับการรันที่เกี่ยวข้องกับพวกเขา และไม่มี key-value pairs ที่รับประกันโดย base primitive ดังนั้น metadata ที่ส่งคืนอาจแตกต่างกันใน implement 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,