Estimator-Eingaben und -Ausgaben

Paketversionen

Der Code auf dieser Seite wurde mit den folgenden Anforderungen entwickelt. Wir empfehlen, diese Versionen oder neuere zu verwenden.

qiskit[all]~=2.5.2
qiskit-ibm-runtime~=0.47.0

Diese Seite gibt einen Überblick über die Eingaben und Ausgaben des IBM Quantum Estimator-Primitives, das Workloads auf IBM-Quantum®-Rechenressourcen ausführt. Der Estimator ermöglicht es dir, vektorisierte Workloads effizient zu definieren, indem du eine Datenstruktur namens Primitive Unified Bloc (PUB) verwendest. Diese werden als Eingaben für die run()-Methode des Estimator-Primitives verwendet, die den definierten Workload als Job ausführt. Nachdem der Job abgeschlossen ist, werden die Ergebnisse in einem Format zurückgegeben, das sowohl von den verwendeten PUBs als auch von den vom Primitive angegebenen Laufzeitoptionen abhängt.

Eingaben

Jeder PUB hat dieses Format:

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

Die optionalen parameter values können eine Liste oder ein einzelner Parameter sein. Elemente aus den Observablen und Parameterwerten werden gemäß den NumPy-Broadcasting-Regeln kombiniert, wie im Thema Primitive inputs and outputs beschrieben, und für jedes Element der gebroadcasteten Form wird eine Erwartungswertschätzung zurückgegeben.

info

Wenn die Eingabe Messungen enthält, werden diese ignoriert.

Für das Estimator-Primitive kann ein PUB höchstens vier Werte enthalten:

Einen einzelnen QuantumCircuit, der ein oder mehrere Parameter-Objekte enthalten kann
Eine Liste von einer oder mehreren Observablen, die die zu schätzenden Erwartungswerte angeben, in ein Array angeordnet (zum Beispiel eine einzelne Observable als 0-dimensionales Array, eine Liste von Observablen als 1-dimensionales Array usw.). Die Daten können in einem der ObservablesArrayLike-Formate wie Pauli, SparsePauliOp, PauliList oder str vorliegen.
Kommutierende Observablen
- Kommutierende Observablen im selben PUB werden mit dieser Methode gruppiert.
- Kommutierende Observablen in verschiedenen PUBs, auch wenn sie denselben Circuit haben, werden nicht mit derselben Messung geschätzt. Jeder PUB stellt eine andere Messbasis dar, daher sind für jeden PUB separate Messungen erforderlich.
- Um sicherzustellen, dass kommutierende Observablen mit derselben Messung geschätzt werden, gruppiere sie innerhalb desselben PUBs.
Eine Sammlung von Parameterwerten, an die der Circuit gebunden wird. Dies kann als einzelnes array-ähnliches Objekt angegeben werden, bei dem der letzte Index über Circuit-Parameter-Objekte geht, oder weggelassen (oder äquivalent auf None gesetzt) werden, wenn der Circuit keine Parameter-Objekte hat.
(Optional) Eine Zielpräzision für die zu schätzenden Erwartungswerte

Der folgende Code zeigt ein Beispielset vektorisierter Eingaben für das Estimator-Primitive und führt sie auf einem IBM®-Backend als einzelnes RuntimeJobV2 -Objekt aus.

# Added by doQumentation — installs the packages this notebook needs if they are missing
import importlib.util

_needed = {"numpy": "numpy", "qiskit": "qiskit", "qiskit_ibm_runtime": "qiskit-ibm-runtime"}
_missing = [pip for module, pip in _needed.items()
            if importlib.util.find_spec(module) is None]
# One at a time, so a package that fails to install does not block the others
for _pip in _missing:
    %pip install -q {_pip}
if not _missing:
    print("\u2713 All required packages are installed")

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

# Legacy server-side primitive before qiskit-ibm-runtime 0.50.0
# from qiskit_ibm_runtime import Estimator

# Client-side primitive introduced in qiskit-ibm-runtime 0.50.0
from qiskit_ibm_runtime.executor_estimator import 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()

Ausgaben

Nachdem ein oder mehrere PUBs zur Ausführung an eine QPU gesendet wurden und ein Job erfolgreich abgeschlossen wurde, werden die Daten als PrimitiveResult-Container-Objekt zurückgegeben, auf das durch Aufrufen der RuntimeJobV2.result()-Methode zugegriffen wird.

Das PrimitiveResult enthält eine iterierbare Liste von PubResult-Objekten, die die Ausführungsergebnisse für jeden PUB enthalten.

Jedes Element dieser Liste entspricht einem der PUBs, die an die run()-Methode des Primitives übergeben wurden (zum Beispiel gibt ein Job, der mit 20 PUBs übermittelt wurde, ein PrimitiveResult-Objekt zurück, das eine Liste von 20 PubResult-Objekten enthält, eines für jeden PUB).

Jedes PubResult für das Estimator-Primitive enthält mindestens ein Array von Erwartungswerten (PubResult.data.evs) und zugehörige Standardabweichungen (entweder PubResult.data.stds oder PubResult.data.ensemble_standard_error, je nach verwendetem resilience_level), kann aber je nach den angegebenen Fehlerminderungsoptionen mehr Daten enthalten.

Jedes PubResult-Objekt besitzt sowohl ein data- als auch ein metadata-Attribut.

Das data-Attribut ist ein angepasster DataBin, der die tatsächlichen Messwerte, Standardabweichungen usw. enthält.
Der DataBin hat verschiedene Attribute je nach Form oder Struktur des zugehörigen PUBs sowie den Fehlerminderungsoptionen, die durch das Primitive angegeben wurden, das zum Übermitteln des Jobs verwendet wurde (zum Beispiel ZNE oder PEC).
Das metadata-Attribut enthält Informationen über die verwendeten Laufzeit- und Fehlerminderungsoptionen (später im Abschnitt Ergebnis-Metadaten dieser Seite erklärt).

Hier siehst du eine schematische Übersicht der PrimitiveResult-Datenstruktur für die Estimator-Ausgabe:

└── 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
    ├── ...
    ├── ...
    └── ...

Kurz gesagt gibt ein einzelner Job ein PrimitiveResult-Objekt zurück und enthält eine Liste von einem oder mehreren PubResult-Objekten. Diese PubResult-Objekte speichern dann die Messdaten für jeden PUB, der dem Job übergeben wurde.

Der folgende Code-Ausschnitt beschreibt das PrimitiveResult- (und zugehörige PubResult-)Format für den oben erstellten 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 PUBs 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:
 {result[0].data}

And this DataBin has attributes: dict_keys(['evs', 'stds', 'ensemble_standard_error'])
Recall that this shape is due to our array of parameter binding setshaving 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: 
{result[0].data.evs}

Wie das Estimator-Primitive den Fehler berechnet

Zusätzlich zur Schätzung des Mittelwerts der in den Eingabe-PUBs übergebenen Observablen (das Feld evs des DataBin) versucht der Estimator auch, eine Schätzung des mit diesen Erwartungswerten verbundenen Fehlers zu liefern. Alle Estimator-Abfragen füllen das Feld stds mit einer Größe wie dem Standardfehler des Mittelwerts für jeden Erwartungswert, aber einige Fehlerminderungsoptionen erzeugen zusätzliche Informationen, wie ensemble_standard_error.

Betrachte eine einzelne Observable $\mathcal{O}$ . Ohne ZNE kann jeder Shot der Estimator-Ausführung als Punktschätzung des Erwartungswerts $\langle \mathcal{O} \rangle$ betrachtet werden. Wenn die punktweisen Schätzungen in einem Vektor Os sind, dann ist der in ensemble_standard_error zurückgegebene Wert äquivalent zum folgenden (wobei $\sigma_{\mathcal{O}}$ die Standardabweichung der Erwartungswertschätzung und $N_{shots}$ die Anzahl der Shots ist):

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

was alle Shots als Teil eines einzigen Ensembles behandelt. Wenn du Gate-Twirling angefordert hast (twirling.enable_gates = True), kannst du die punktweisen Schätzungen von $\langle \mathcal{O} \rangle$ in Mengen sortieren, die ein gemeinsames Twirl teilen. Nenn diese Mengen von Schätzungen O_twirls, und es gibt num_randomizations (Anzahl der Twirls) davon. Dann ist stds der Standardfehler des Mittelwerts von O_twirls, wie in

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

wobei $\sigma_{\mathcal{O}}$ die Standardabweichung von O_twirls und $N_{twirls}$ die Anzahl der Twirls ist. Wenn du Twirling nicht aktivierst, sind stds und ensemble_standard_error gleich.

Wenn du ZNE aktivierst, werden die oben beschriebenen stds zu Gewichtungen in einer nicht-linearen Regression an ein Extrapolationsmodell. Was schließlich in stds zurückgegeben wird, ist in diesem Fall die Unsicherheit des Fit-Modells, ausgewertet bei einem Rauschfaktor von null. Bei einem schlechten Fit oder großer Unsicherheit im Fit können die gemeldeten stds sehr groß werden. Wenn ZNE aktiviert ist, werden auch pub_result.data.evs_noise_factors und pub_result.data.stds_noise_factors befüllt, sodass du deine eigene Extrapolation durchführen kannst.

Ergebnis-Metadaten

Zusätzlich zu den Ausführungsergebnissen enthalten sowohl die PrimitiveResult- als auch die PubResult-Objekte ein Metadaten-Attribut über den übermittelten Job. Die Metadaten mit Informationen für alle übermittelten PUBs (wie die verschiedenen verfügbaren Laufzeitoptionen) befinden sich in PrimitiveResult.metatada, während die für jeden PUB spezifischen Metadaten in PubResult.metadata zu finden sind.

Der clientseitige Estimator reicht seinen Workload als Executor-Job ein. Die Metadaten des zugrunde liegenden Executor-Ergebnisses, die Informationen zum Ausführungszeitverlauf namens Ausführungsspannen enthalten, sind unter dem Schlüssel "executor" von PrimitiveResult.metadata verfügbar.

hinweis

Im Metadatenfeld können Primitive-Implementierungen beliebige für sie relevante Informationen über die Ausführung zurückgeben, und es gibt keine Schlüssel-Wert-Paare, die durch das Basis-Primitive garantiert werden. Daher können die zurückgegebenen Metadaten in verschiedenen Primitive-Implementierungen unterschiedlich sein.

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

Ausführungsspannen anzeigen

Der clientseitige Estimator läuft als Executor-Job, der seine Arbeit in Chunks auf der QPU ausführt. Das Timing jedes Chunks steht in result.metadata["executor"].chunk_timing, einer Liste von ChunkSpan-Objekten. Jedes ChunkSpan hat die Zeitstempel start und stop sowie eine Liste von parts, wobei jeder Teil einen Item-Index (idx_item) und die Anzahl der Konfigurationen aus diesem Item (size) angibt, die im Chunk ausgeführt wurden.

idx_item ist der Index eines Items im Executor-Programm, das Estimator aus deinen PUBs erstellt. Er stimmt nicht unbedingt mit einem PUB-Index überein, weil Estimator je nach Optionen zur Fehlerminderung Programm-Items hinzufügen kann. Zum Beispiel fügt er Circuits zur Kalibrierung von Messfehlern hinzu, wenn TREX aktiviert ist.

Um die Zeitverläufe zu visualisieren, übergib die Liste an draw_chunk_timings, wie im folgenden Beispiel gezeigt.

Was die Zeitstempel der Chunks bedeuten, wie du das Diagramm liest und warum zwischen Chunks Lücken auftreten können, erfährst du unter Ausführungsspannen anzeigen im Leitfaden zu Executor-Ein- und -Ausgaben.

from qiskit_ibm_runtime.visualization import draw_chunk_timings

# Note the "executor" key: the timing comes from the underlying Executor job
chunk_timing = result.metadata["executor"].chunk_timing

for idx, span in enumerate(chunk_timing):
    duration = (span.stop - span.start).total_seconds()
    print(f"Chunk {idx}: {span.start} to {span.stop} ({duration:.3f} s)")
    for part in span.parts:
        print(f"  Item {part.idx_item}: {part.size} configurations")

fig = draw_chunk_timings(chunk_timing, names="Estimator job")

# Uncomment the following line to display the figure
# fig.show(renderer="notebook")

# Save to a file
# fig.write_html("chunk_timings.html")

Chunk 0: 2026-11-06 01:39:01.509471+00:00 to 2026-11-06 01:39:35.171288+00:00 (33.662 s)
  Item 0: 800 configurations
  Item 1: 4 configurations
Chunk 1: 2026-11-06 01:39:48.299074+00:00 to 2026-11-06 01:40:21.826190+00:00 (33.527 s)
  Item 0: 800 configurations
  Item 1: 4 configurations
Chunk 2: 2026-11-06 01:40:22.855454+00:00 to 2026-11-06 01:40:53.781896+00:00 (30.926 s)
  Item 0: 800 configurations
  Item 1: 4 configurations
Chunk 3: 2026-11-06 01:40:54.993867+00:00 to 2026-11-06 01:41:26.068319+00:00 (31.074 s)
  Item 0: 800 configurations
  Item 1: 4 configurations
Chunk 4: 2026-11-06 01:41:41.019968+00:00 to 2026-11-06 01:42:15.956573+00:00 (34.937 s)
  Item 0: 800 configurations
  Item 1: 4 configurations
Chunk 5: 2026-11-06 01:42:47.834717+00:00 to 2026-11-06 01:43:21.436255+00:00 (33.602 s)
  Item 0: 800 configurations
  Item 1: 4 configurations
Chunk 6: 2026-11-06 01:43:22.698235+00:00 to 2026-11-06 01:43:53.647547+00:00 (30.949 s)
  Item 0: 800 configurations
  Item 1: 4 configurations
Chunk 7: 2026-11-06 01:43:54.710995+00:00 to 2026-11-06 01:44:25.762574+00:00 (31.052 s)
  Item 0: 800 configurations
  Item 1: 4 configurations

Eingaben​

Ausgaben​

Wie das Estimator-Primitive den Fehler berechnet​

Ergebnis-Metadaten​

Ausführungsspannen anzeigen​

Eingaben

Ausgaben

Wie das Estimator-Primitive den Fehler berechnet

Ergebnis-Metadaten

Ausführungsspannen anzeigen