Přeskočit na hlavní obsah
Tento projekt je v betě. Našel jsi chybu? Otevřít issue na GitHubu. Máš otázku nebo nápad? Zeptej se v Discussions — rádi si poslechneme tvou zpětnou vazbu!
Jaká je kvalita překladu na této stránce?

Vstupy a výstupy Estimator

Verze balíčků

Kód na této stránce byl vyvinut s použitím následujících požadavků. Doporučujeme používat tyto nebo novější verze.

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

Tato stránka poskytuje přehled vstupů a výstupů primitivu Estimator od IBM Quantum, který spouští workloady na výpočetních zdrojích IBM Quantum®. Estimator ti umožňuje efektivně definovat vektorizované workloady pomocí datové struktury zvané Primitive Unified Bloc (PUB). Používají se jako vstupy do metody run() pro primitiv Estimator, který spouští definovaný workload jako úlohu. Poté, co je úloha dokončena, jsou výsledky vráceny ve formátu, který závisí jak na použitých PUBech, tak na možnostech runtime zadaných z primitivu.

Vstupy​

Každý PUB je v tomto formátu:

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

Volitelné parameter values mohou být seznam nebo jeden parametr. Prvky z observables a hodnot parametrů jsou kombinovány podle pravidel broadcastingu NumPy popsaných v tématu Vstupy a výstupy primitivu, a pro každý prvek výsledného broadcastovaného tvaru je vrácen jeden odhad očekávané hodnoty.

informace

Pokud vstup obsahuje měření, jsou ignorována.

Pro primitiv Estimator může PUB obsahovat nejvýše čtyři hodnoty:

  • Jeden QuantumCircuit, který může obsahovat jeden nebo více objektů Parameter
  • Seznam jednoho nebo více observables, které specifikují očekávané hodnoty k odhadnutí, uspořádané do pole (například jeden observable reprezentovaný jako 0-d pole, seznam observables jako 1-d pole atd.). Data mohou být v jakémkoli z formátů ObservablesArrayLike, jako je Pauli, SparsePauliOp, PauliList nebo str.
    Komutující observables
    • Komutující observables ve stejném PUBu jsou seskupeny pomocí této metody.
    • Komutující observables v různých PUBech, i když mají stejný Circuit, nejsou odhadovány pomocí stejného měření. Každý PUB představuje jinou měřicí bázi, a proto jsou pro každý PUB vyžadována samostatná měření.
    • Chceš-li zajistit, aby komutující observables byly odhadovány pomocí stejného měření, seskup je v rámci stejného PUBu.
  • Kolekce hodnot parametrů pro vázání Circuit. Lze ji zadat jako jeden objekt podobný poli (array-like), jehož poslední index prochází objekty Parameter Circuit, nebo ji vynechat (nebo ekvivalentně nastavit na None), pokud Circuit nemá objekty Parameter.
  • (Volitelně) Cílová přesnost pro odhadování očekávaných hodnot

Následující kód demonstruje příklad sady vektorizovaných vstupů pro primitiv Estimator a spustí je na backendu IBM® jako jediný objekt RuntimeJobV2 .

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

Výstupy​

Poté, co jsou jeden nebo více PUBů odeslány na QPU ke spuštění a úloha úspěšně dokončena, jsou data vrácena jako kontejnerový objekt PrimitiveResult přístupný voláním metody RuntimeJobV2.result().

PrimitiveResult obsahuje iterovatelný seznam objektů PubResult, které obsahují výsledky spuštění pro každý PUB.

Každý prvek tohoto seznamu odpovídá každému PUBu odeslanému do metody run() primitivu (například úloha odeslaná s 20 PUBy vrátí objekt PrimitiveResult, který obsahuje seznam 20 objektů PubResult, jeden odpovídající každému PUBu).

Každý PubResult pro primitiv Estimator obsahuje alespoň pole očekávaných hodnot (PubResult.data.evs) a přidružené standardní odchylky (buď PubResult.data.stds nebo PubResult.data.ensemble_standard_error v závislosti na použité resilience_level), ale může obsahovat více dat v závislosti na zadaných možnostech zmírňování chyb.

Každý objekt PubResult má atribut data i metadata.

  • Atribut data je přizpůsobený DataBin, který obsahuje skutečné hodnoty měření, standardní odchylky atd.
  • DataBin má různé atributy v závislosti na tvaru nebo struktuře přidruženého PUBu, jakož i na možnostech zmírňování chyb zadaných primitivem použitým k odeslání úlohy (například ZNE nebo PEC).
  • Atribut metadata obsahuje informace o možnostech běhového prostředí a zmírňování chyb použitých (vysvětleno dále v sekci Metadata výsledku na této stránce).

Následuje vizuální přehled datové struktury PrimitiveResult pro výstup 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
    ├── ...
    ├── ...
    └── ...

Jednoduše řečeno, jedna úloha vrátí objekt PrimitiveResult a obsahuje seznam jednoho nebo více objektů PubResult. Tyto objekty PubResult pak uchovávají data měření pro každý PUB odeslaný do úlohy.

Následující úryvek kódu popisuje formát PrimitiveResult (a přidruženého PubResult) pro výše vytvořenou úlohu.

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}

Jak primitiv Estimator počítá chybu​

Kromě odhadu střední hodnoty observables zadaných ve vstupních PUBech (pole evs objektu DataBin) se Estimator také pokouší poskytnout odhad chyby spojené s těmito očekávanými hodnotami. Všechny dotazy Estimator vyplní pole stds hodnotou podobnou standardní chybě průměru pro každou očekávanou hodnotu, ale některé možnosti zmírňování chyb poskytují další informace, jako je ensemble_standard_error.

Uvažujme jeden observable O\mathcal{O}. Bez ZNE si každý shot (jedno opakování) spuštění Estimatoru můžeš představit jako bodový odhad očekávané hodnoty ⟨O⟩\langle \mathcal{O} \rangle. Pokud jsou bodové odhady ve vektoru Os, pak hodnota vrácená v ensemble_standard_error je ekvivalentní následujícímu (kde σO\sigma_{\mathcal{O}} je standardní odchylka odhadu očekávané hodnoty a NshotsN_{shots} je počet shotů):

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

což zachází se všemi snímky jako s jedním souborem. Pokud jsi požádal o twirling Gate (twirling.enable_gates = True), můžeš bodové odhady ⟨O⟩\langle \mathcal{O} \rangle roztřídit do sad sdílejících společný twirl. Nazvi tyto sady odhadů O_twirls a je jich num_randomizations (počet twirlingů). Pak stds je standardní chyba průměru O_twirls, jak v

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

kde σO\sigma_{\mathcal{O}} je standardní odchylka O_twirls a NtwirlsN_{twirls} je počet twirlingů. Když nepovolíš twirling, stds a ensemble_standard_error jsou si rovny.

Pokud povolíš ZNE, pak výše popsané stds se stanou váhami v nelineární regresi k modelu extrapolátoru. To, co je nakonec vráceno v stds v tomto případě, je nejistota modelu fitování vyhodnocená při šumovém faktoru nula. Při špatném fitu nebo velké nejistotě ve fitu mohou nahlášené stds být velmi velké. Když je povoleno ZNE, jsou také naplněny pub_result.data.evs_noise_factors a pub_result.data.stds_noise_factors, takže si můžeš provést vlastní extrapolaci.

Metadata výsledku​

Kromě výsledků provedení obsahují objekty PrimitiveResult i PubResult atribut metadat o odeslané úloze. Metadata obsahující informace pro všechny odeslané PUB (například různé možnosti runtime, které jsou k dispozici) lze najít v PrimitiveResult.metatada, zatímco metadata specifická pro každý PUB se nacházejí v PubResult.metadata.

Estimator na straně klienta odesílá svou úlohu jako úlohu Executor. Metadata podkladového výsledku Executoru, která zahrnují informace o časování provádění zvané execution spans, jsou dostupná pod klíčem "executor" v PrimitiveResult.metadata.

poznámka

V poli metadat mohou implementace primitivů vrátit jakékoli informace o spuštění, které jsou pro ně relevantní, a základní primitiv nezaručuje žádné konkrétní páry klíč-hodnota. Vrácená metadata se tedy mohou lišit v různých implementacích primitivů.

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

Zobrazení execution spans​

Estimator na straně klienta běží jako úloha Executor, která provádí svou práci na QPU po částech (chunks). Časování každé části je v result.metadata["executor"].chunk_timing, což je seznam objektů ChunkSpan. Každý ChunkSpan má časové značky start a stop a seznam parts, kde každá část udává index položky (idx_item) a počet konfigurací z této položky (size), které běžely v dané části.

idx_item je index položky v programu Executor, který Estimator sestavuje z tvých PUB. Nemusí nutně odpovídat indexu PUB, protože Estimator může podle voleb zmírnění chyb přidávat položky programu. Například přidává kalibrační obvody pro chyby měření, když je zapnuto TREX.

Chceš-li časování vizualizovat, předej seznam funkci draw_chunk_timings, jak ukazuje následující příklad.

Co znamenají časové značky částí, jak číst graf a proč mezi částmi mohou vznikat mezery, se dozvíš v části Zobrazení execution spans v průvodci vstupy a výstupy Executoru.

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
Zdroj: Dokumentace IBM Quantum — aktualizováno 7. 11. 2026
Anglická verze na doQumentation — aktualizováno 7. 11. 2026
Problém s webem nebo překladem?Problém v obsahu? Upravit v IBM Quantum docs