Перейти до основного вмісту

Входи та виходи Estimator

Версії пакетів

Код на цій сторінці було розроблено з використанням таких вимог. Рекомендуємо використовувати ці або новіші версії.

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

Ця сторінка дає огляд входів та виходів примітива Qiskit Runtime Estimator, який виконує навантаження на обчислювальних ресурсах IBM Quantum®. Estimator дозволяє ефективно визначати векторизовані навантаження, використовуючи структуру даних, що називається Primitive Unified Bloc (PUB). Вони використовуються як вхідні дані для методу run() примітива Estimator, який виконує визначене навантаження як завдання. Потім, після завершення завдання, результати повертаються у форматі, що залежить від обох PUB, використовуваних як вхідні дані, а також від опцій середовища виконання, вказаних примітивом.

Входи​

Кожен PUB має такий формат:

(<одна схема>, <один або кілька спостережуваних>, <необов'язкові одне або кілька значень параметрів>, <необов'язкова точність>),

Необов'язкові parameter values можуть бути списком або одним параметром. Елементи зі спостережуваних та значень параметрів комбінуються відповідно до правил трансляції NumPy, як описано в темі Входи та виходи примітивів, і одна оцінка очікуваного значення повертається для кожного елемента транслюваної форми.

інформація

Якщо вхідні дані містять вимірювання, вони ігноруються.

Для примітива Estimator PUB може містити не більше чотирьох значень:

  • Одна QuantumCircuit, яка може містити один або кілька об'єктів Parameter
  • Список одного або кількох спостережуваних, що вказують очікувані значення для оцінки, впорядковані в масив (наприклад, одне спостережуване, представлене як 0-d масив, список спостережуваних як 1-d масив тощо). Дані можуть бути в будь-якому з форматів ObservablesArrayLike, таких як Pauli, SparsePauliOp, PauliList або str.
    Комутуючі спостережувані
    • Комутуючі спостережувані в одному і тому ж PUB групуються разом за допомогою цього методу.
    • Комутуючі спостережувані в різних PUB, навіть якщо вони мають однакову схему, не оцінюються за допомогою одного вимірювання. Кожен PUB представляє різний базис для вимірювання, і тому для кожного PUB потрібні окремі вимірювання.
    • Щоб гарантувати, що комутуючі спостережувані оцінюються за допомогою одного вимірювання, групуй їх у тому ж PUB.
  • Колекція значень параметрів для прив'язки схеми. Це може бути вказано як єдиний об'єкт, схожий на масив, де останній індекс — над об'єктами Parameter схеми, або пропущено (або еквівалентно, встановлено на None), якщо схема не має об'єктів Parameter.
  • (Необов'язково) Цільова точність для оцінки очікуваних значень

Наступний код демонструє приклад набору векторизованих входів до примітива Estimator та виконує їх на backend IBM® як єдиний об'єкт 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 для виконання та успішного завершення завдання дані повертаються як об'єкт-контейнер PrimitiveResult, доступний шляхом виклику методу RuntimeJobV2.result().

PrimitiveResult містить ітерований список об'єктів PubResult, що містять результати виконання для кожного PUB.

Кожен елемент цього списку відповідає кожному PUB, надісланому до методу run() примітива (наприклад, завдання, надіслане з 20 PUB, поверне об'єкт PrimitiveResult, що містить список з 20 об'єктів PubResult, кожен відповідний своєму PUB).

Кожен PubResult для примітива Estimator містить щонайменше масив очікуваних значень (PubResult.data.evs) та пов'язані стандартні відхилення (або PubResult.data.stds, або PubResult.data.ensemble_standard_error залежно від використовуваного resilience_level), але може містити більше даних залежно від вказаних опцій пом'якшення помилок.

Кожен об'єкт PubResult має як атрибут data, так і атрибут metadata.

  • Атрибут data — це налаштований DataBin, що містить фактичні значення вимірювань, стандартні відхилення тощо.
  • DataBin має різні атрибути залежно від форми або структури пов'язаного PUB, а також від опцій пом'якшення помилок, вказаних примітивом, використовуваним для надсилання завдання (наприклад, ZNE або PEC).
  • Атрибут metadata містить інформацію про опції середовища виконання та пом'якшення помилок, використовувані (пояснено пізніше в розділі Метадані результату цієї сторінки).

Нижче наведено візуальний контур структури даних PrimitiveResult для виходу Estimator:

└── 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 та містить список з одного або кількох об'єктів 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 (поле evs DataBin), Estimator також намагається надати оцінку помилки, пов'язаної з цими очікуваними значеннями. Всі запити до Estimator заповнюватимуть поле stds величиною, схожою на стандартну помилку середнього для кожного очікуваного значення, але деякі опції пом'якшення помилок виробляють додаткову інформацію, наприклад ensemble_standard_error.

Розглянемо одне спостережуване O\mathcal{O}. За відсутності ZNE, можна думати про кожен знімок виконання Estimator як про надання точкової оцінки очікуваного значення ⟨O⟩\langle \mathcal{O} \rangle. Якщо точкові оцінки знаходяться у векторі Os, то значення, що повертається в ensemble_standard_error, еквівалентне такому (де σO\sigma_{\mathcal{O}} — стандартне відхилення оцінки очікуваного значення, а NshotsN_{shots} — кількість знімків):

σONshots,\frac{ \sigma_{\mathcal{O}} }{ \sqrt{N_{shots}} },

що розглядає всі знімки як частину єдиного ансамблю. Якщо запитано gate twirling (twirling.enable_gates = True), можна відсортувати точкові оцінки ⟨O⟩\langle \mathcal{O} \rangle у набори, що мають спільний twirl. Назвемо ці набори оцінок O_twirls, їх є num_randomizations (кількість twirl). Тоді stds є стандартною помилкою середнього O_twirls, як у

σONtwirls,\frac{ \sigma_{\mathcal{O}} }{ \sqrt{N_{twirls}} },

де σO\sigma_{\mathcal{O}} — стандартне відхилення O_twirls, а NtwirlsN_{twirls} — кількість twirl. Коли twirling не увімкнено, 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.metatada, тоді як метадані, специфічні для кожного 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,
Джерело: IBM Quantum docs — оновлено 10 черв. 2026 р.
Англійська версія на doQumentation — оновлено 10 черв. 2026 р.
Цей переклад базується на англійській версії від 13 трав. 2026 р.
Проблема із сайтом чи перекладом?Проблема з вмістом? Редагувати в IBM Quantum docs