{ "cells": [ { "cell_type": "markdown", "id": "066d7e4d-a975-4519-b56f-095f861be3ac", "metadata": {}, "source": [ "---\n", "title: \"Eingaben und Ausgaben des Schätzers\"\n", "description: \"Machen Sie sich mit dem Eingabe- und Ausgabeformat der Estimator-Primitive vertraut\"\n", "---\n", "\n", "\n", "\n", "# Eingaben und Ausgaben des Schätzers\n", "\n" ] }, { "cell_type": "markdown", "id": "23e7dff0-fde5-4c2d-89c2-fc5ab99240fe", "metadata": { "tags": [ "version-info" ] }, "source": [ "{/*\n", " DO NOT EDIT THIS CELL!!!\n", " This cell's content is generated automatically by a script. Anything you add\n", " here will be removed next time the notebook is run. To add new content, create\n", " a new cell before or after this one.\n", " */}\n", "\n", "\n", " \n", " Der Code auf dieser Seite wurde unter Berücksichtigung der folgenden Anforderungen entwickelt.\n", " Wir empfehlen, diese Versionen oder neuere zu verwenden.\n", "\n", " ```\n", " qiskit[all]~=2.5.2\n", " qiskit-ibm-runtime~=0.47.0\n", " ```\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "90d0c1e0-28e7-48da-a35f-6016fddea82c", "metadata": {}, "source": [ "Diese Seite bietet einen Überblick über die Ein- und Ausgänge der „ IBM Quantum “-Estimator-Primitive, die Workloads auf Rechenressourcen von „ IBM Quantum® “ ausführt. Mit Estimator können Sie vektorisierte Workloads mithilfe einer Datenstruktur namens [**„Primitive Unified Bloc“ ( PUB )**](/docs/guides/primitive-input-output#pubs) effizient definieren. Sie dienen als Eingaben für die Methode [`run()`](/docs/api/qiskit-ibm-runtime/executor-estimator-estimator#run) der „Estimator“-Primitive, die die definierte Arbeitslast als Job ausführt. Nachdem der Auftrag abgeschlossen ist, werden die Ergebnisse in einem Format zurückgegeben, das sowohl von den verwendeten PUBs als auch von den in der Primitive angegebenen Laufzeitoptionen abhängt.\n", "\n" ] }, { "cell_type": "markdown", "id": "83a5fdd8-6547-47c7-9441-a7458edc7896", "metadata": {}, "source": [ "\n", "\n", "## Eingaben\n", "\n", "Jede „ PUB “-Datei hat dieses Format:\n", "\n", "(``, ``, ``, ``),\n", "\n", "Der optionale `parameter values` Parameter kann eine Liste oder ein einzelner Parameter sein. Elemente aus Observables und Parameterwerten werden gemäß den im Abschnitt [„Primitive Eingaben und Ausgaben“](primitive-input-output#broadcasting-rules) beschriebenen Broadcasting-Regeln für „ NumPy “ kombiniert, und für jedes Element der übertragenen Form wird eine Schätzung des Erwartungswerts zurückgegeben.\n", "\n", "\n", " Wenn die Eingabe Messwerte enthält, werden diese ignoriert.\n", "\n", "\n", "Bei der Primitive „Estimator“ kann ein „ PUB “ höchstens vier Werte enthalten:\n", "\n", "* Ein Einzelobjekt `QuantumCircuit`, das ein oder mehrere [`Parameter`](/docs/api/qiskit/qiskit.circuit.Parameter) Objekte enthalten kann\n", "* Eine Liste aus einer oder mehreren Observablen, die die zu schätzenden Erwartungswerte angeben und in einem Array angeordnet sind (beispielsweise wird eine einzelne Observable als 0-d-Array dargestellt, eine Liste von Observablen als 1-d-Array usw.). Die Daten können in einem der folgenden `ObservablesArrayLike` Formate vorliegen: `Pauli` `SparsePauliOp`, `PauliList`,, oder `str`.\n", " \n", " * Mit [dieser Methode](/docs/api/qiskit/qiskit.quantum_info.PauliList#group_qubit_wise_commuting) werden pendelnde Observables **im selben PUB** gruppiert.\n", " * Beobachtungsgrößen für den Pendelverkehr in verschiedenen PUBs werden nicht anhand derselben Messung geschätzt, selbst wenn sie denselben Schaltkreis haben. Jedes „ PUB “ stellt eine andere Bewertungsgrundlage dar, weshalb für jedes „ PUB “ separate Bewertungen erforderlich sind.\n", " * Um sicherzustellen, dass die Pendlerdaten anhand derselben Messung geschätzt werden, gruppieren Sie sie innerhalb desselben „ PUB “.\n", " \n", "* Eine Sammlung von Parameterwerten, an die die Schaltung angepasst werden soll. Dies kann als einzelnes array-ähnliches Objekt angegeben werden, wobei der letzte Index die Anzahl der `Parameter` Schaltungsobjekte angibt, oder weggelassen werden (bzw. auf `None`gesetzt werden), wenn die Schaltung keine `Parameter` Objekte enthält.\n", "* (Optional) Eine Zielgenauigkeit für die zu schätzenden Erwartungswerte\n", "\n" ] }, { "cell_type": "markdown", "id": "846b3109-02a1-4783-ad3f-1c22f753c324", "metadata": {}, "source": [ "***\n", "\n", "Der folgende Code zeigt ein Beispiel für eine Reihe vektorisierter Eingaben für die `Estimator` Primitive und führt diese auf einem „ IBM® “-Backend als ein einziges `RuntimeJobV2 ` Objekt aus.\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "2f50a9f5-2cc1-4d83-9fe1-1b3a8be0d766", "metadata": {}, "outputs": [], "source": [ "from qiskit.circuit import (\n", " Parameter,\n", " QuantumCircuit,\n", ")\n", "from qiskit.transpiler import generate_preset_pass_manager\n", "from qiskit.quantum_info import SparsePauliOp\n", "\n", "from qiskit_ibm_runtime import QiskitRuntimeService\n", "\n", "# Legacy server-side primitive before qiskit-ibm-runtime 0.50.0\n", "# from qiskit_ibm_runtime import Estimator\n", "\n", "# Client-side primitive introduced in qiskit-ibm-runtime 0.50.0\n", "from qiskit_ibm_runtime.executor_estimator import Estimator\n", "\n", "import numpy as np\n", "\n", "# Instantiate runtime service and get\n", "# the least busy backend\n", "service = QiskitRuntimeService()\n", "backend = service.least_busy(operational=True, simulator=False)\n", "\n", "# Define a circuit with two parameters.\n", "circuit = QuantumCircuit(2)\n", "circuit.h(0)\n", "circuit.cx(0, 1)\n", "circuit.ry(Parameter(\"a\"), 0)\n", "circuit.rz(Parameter(\"b\"), 0)\n", "circuit.cx(0, 1)\n", "circuit.h(0)\n", "\n", "# Transpile the circuit\n", "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", "transpiled_circuit = pm.run(circuit)\n", "layout = transpiled_circuit.layout\n", "\n", "# Now define a sweep over parameter values, the last axis of dimension 2 is\n", "# for the two parameters \"a\" and \"b\"\n", "params = np.vstack(\n", " [\n", " np.linspace(-np.pi, np.pi, 100),\n", " np.linspace(-4 * np.pi, 4 * np.pi, 100),\n", " ]\n", ").T\n", "\n", "# Define three observables. The inner length-1 lists cause this array of\n", "# observables to have shape (3, 1), rather than shape (3,) if they were\n", "# omitted.\n", "observables = [\n", " [SparsePauliOp([\"XX\", \"IY\"], [0.5, 0.5])],\n", " [SparsePauliOp(\"XX\")],\n", " [SparsePauliOp(\"IY\")],\n", "]\n", "# Apply the same layout as the transpiled circuit.\n", "observables = [\n", " [observable.apply_layout(layout) for observable in observable_set]\n", " for observable_set in observables\n", "]\n", "\n", "# Estimate the expectation value for all 300 combinations of observables\n", "# and parameter values, where the pub result will have shape (3, 100).\n", "#\n", "# This shape is due to our array of parameter bindings having shape\n", "# (100, 2), combined with our array of observables having shape (3, 1).\n", "estimator_pub = (transpiled_circuit, observables, params)\n", "\n", "# Instantiate the new Estimator object, then run the transpiled circuit\n", "# using the set of parameters and observables.\n", "estimator = Estimator(mode=backend)\n", "job = estimator.run([estimator_pub])\n", "result = job.result()" ] }, { "cell_type": "markdown", "id": "90dccb20-1848-4367-a12d-434110ad5a5c", "metadata": {}, "source": [ "\n", "\n", "## Ausgaben\n", "\n", "Nachdem ein oder mehrere PUBs zur Ausführung an eine QPU gesendet wurden und ein Job erfolgreich abgeschlossen wurde, werden die Daten als [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) Containerobjekt zurückgegeben, auf das durch Aufruf der `RuntimeJobV2.result()` Methode zugegriffen wird.\n", "\n", "Das `PrimitiveResult` enthält eine iterierbare Liste von [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) Objekten, die die Ausführungsergebnisse für jeden PUB enthalten.\n", "\n", "Jedes Element dieser Liste entspricht einem einzelnen „ PUB “, das an die Methode `run()` der Primitive übergeben wurde (ein Job, der beispielsweise mit 20 PUBs übergeben wurde, gibt ein `PrimitiveResult` Objekt zurück, das eine Liste mit 20 `PubResult` Objekten enthält, wobei jedes Objekt einem einzelnen „ PUB “ entspricht).\n", "\n", "Jede `PubResult` für die Estimator-Primitive enthält mindestens ein Array mit Erwartungswerten (`PubResult.data.evs`) und den zugehörigen Standardabweichungen (entweder `PubResult.data.stds` oder, `PubResult.data.ensemble_standard_error` je nach dem `resilience_level` verwendeten ), kann aber je nach den angegebenen Optionen zur Fehlerminderung weitere Daten enthalten.\n", "\n", "Jedes `PubResult` Objekt verfügt sowohl über ein `data` als auch über ein `metadata` Attribut.\n", "\n", "* Das `data` Attribut ist ein benutzerdefiniertes [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) Feld, das die tatsächlichen Messwerte, Standardabweichungen usw. enthält.\n", "* Die `DataBin` verfügt über verschiedene Attribute, die von der Form oder Struktur des zugehörigen „ PUB “ sowie von den Optionen zur Fehlerbehebung abhängen, die durch die zur Übermittlung des Auftrags verwendete Primitive festgelegt wurden (z. B. [ZNE](/docs/guides/error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) oder [PEC](/docs/guides/error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec) ).\n", "* Das `metadata` Attribut enthält Informationen zur Laufzeit und zu den verwendeten Optionen zur Fehlerbehebung (dies wird später im Abschnitt [„Ergebnis-Metadaten“](#result-metadata) auf dieser Seite erläutert).\n", "\n", "Im Folgenden finden Sie eine grafische Darstellung der `PrimitiveResult` Datenstruktur für die Ausgabe des Schätzers:\n", "\n", "```\n", "└── PrimitiveResult\n", " ├── PubResult[0]\n", " │ ├── metadata\n", " │ └── data ## In the form of a DataBin object\n", " │ ├── evs\n", " │ │ └── List of estimated expectation values in the shape\n", " | | specified by the first pub\n", " │ └── stds\n", " │ └── List of calculated standard deviations in the\n", " | same shape as above\n", " ├── PubResult[1]\n", " | ├── metadata\n", " | └── data ## In the form of a DataBin object\n", " | ├── evs\n", " | │ └── List of estimated expectation values in the shape\n", " | | specified by the second pub\n", " | └── stds\n", " | └── List of calculated standard deviations in the\n", " | same shape as above\n", " ├── ...\n", " ├── ...\n", " └── ...\n", "```\n", "\n", "Einfach ausgedrückt: Eine einzelne Funktion gibt ein `PrimitiveResult` Objekt zurück und enthält eine Liste mit einem oder mehreren `PubResult` Objekten. Diese `PubResult` Objekte speichern dann die Messdaten für jeden „ PUB “, der an den Job übermittelt wurde.\n", "\n", "Der folgende Codeausschnitt beschreibt das Format `PrimitiveResult` (und die zugehörigen Elemente `PubResult`) für den oben erstellten Auftrag.\n", "\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "53a4d5ae-109b-452b-bbc5-2d7940c5182c", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "The result of the submitted job had 1 PUBs and has a value:\n", " PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(), stds=np.ndarray(), ensemble_standard_error=np.ndarray(), 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})\n", "\n", "The associated PubResult of this job has the following data bins:\n", " {result[0].data}\n", "\n", "And this DataBin has attributes: dict_keys(['evs', 'stds', 'ensemble_standard_error'])\n", "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). \n", "\n", "The expectation values measured from this PUB are: \n", "{result[0].data.evs}\n", "\n" ] } ], "source": [ "print(\n", " f\"The result of the submitted job had {len(result)} \"\n", " f\"PUBs and has a value:\\n {result}\\n\"\n", ")\n", "print(\n", " \"The associated PubResult of this job has the following data bins:\\n \"\n", " \"{result[0].data}\\n\"\n", ")\n", "print(f\"And this DataBin has attributes: {result[0].data.keys()}\")\n", "print(\n", " \"Recall that this shape is due to our array of parameter binding sets\"\n", " \"having shape (100, 2), where 2 is the number of parameters in the \"\n", " \"circuit, combined with our array of observables having shape (3, 1). \\n\"\n", ")\n", "with np.printoptions(threshold=200):\n", " print(\n", " \"The expectation values measured from this PUB are: \\n\"\n", " \"{result[0].data.evs}\\n\"\n", " )" ] }, { "cell_type": "markdown", "id": "000ade51-d940-45f9-84ea-16ad283a930f", "metadata": {}, "source": [ "\n", "\n", "#### Wie die Estimator-Primitive den Fehler berechnet\n", "\n", "Neben der Schätzung des Mittelwerts der in den Eingabe-PUBs übergebenen Observablen (dem `evs` Feld von `DataBin`) versucht der Schätzer auch, eine Schätzung des mit diesen Erwartungswerten verbundenen Fehlers zu liefern. Alle Abfragen im Estimator füllen das `stds` Feld mit einem Wert wie dem Standardfehler des Mittelwerts für jeden Erwartungswert, doch einige Optionen zur Fehlerminderung liefern zusätzliche Informationen, wie zum Beispiel `ensemble_standard_error`.\n", "\n", "Betrachten wir eine einzelne beobachtbare Größe $\\mathcal{O}$. Ohne [ZNE](/docs/guides/error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) kann man sich jeden Durchlauf der Schätzerausführung so vorstellen, dass er eine Punktschätzung des Erwartungswerts $\\langle \\mathcal{O} \\rangle$ liefert. Liegen die Punktschätzungen in einem Vektor `Os`, so entspricht der `ensemble_standard_error` in zurückgegebene Wert dem Folgenden (wobei $\\sigma_{\\mathcal{O}}$ die [Standardabweichung der](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2) Erwartungswertschätzung und $N_{shots}$ die Anzahl der Durchläufe ist):\n", "\n", "$\\frac{ \\sigma_{\\mathcal{O}} }{ \\sqrt{N_{shots}} },$\n", "\n", "das alle Aufnahmen als Teil eines einzigen Ensembles behandelt. Wenn Sie „Gate [Twirling](/docs/guides/error-mitigation-and-suppression-techniques#pauli-twirling)“ (`twirling.enable_gates = True`) angefordert haben, können Sie die punktweisen Schätzungen von $\\langle \\mathcal{O} \\rangle$ in Gruppen sortieren, die einen gemeinsamen Twirl aufweisen. Bezeichnen wir diese Schätzungssätze `O_twirls`als und es gibt `num_randomizations` (Anzahl der Drehungen) davon. Dann `stds` ist der Standardfehler des Mittelwerts von `O_twirls`, wie in\n", "\n", "$\\frac{ \\sigma_{\\mathcal{O}} }{ \\sqrt{N_{twirls}} },$\n", "\n", "wobei $\\sigma_{\\mathcal{O}}$ die Standardabweichung von `O_twirls` und $N_{twirls}$ die Anzahl der Drehungen ist. Wenn Sie das Drehen nicht aktivieren, sind `stds` `ensemble_standard_error` und gleich.\n", "\n", "Wenn Sie ZNE aktivieren, werden die oben `stds` beschriebenen Werte zu Gewichten in einer nichtlinearen Regression für ein Extrapolationsmodell. Was in diesem `stds` Fall schließlich zurückgegeben wird, ist die Unsicherheit des Anpassungsmodells, bewertet bei einem Rauschfaktor von Null. Wenn die Anpassung schlecht ist oder große Unsicherheiten bei der Anpassung bestehen, kann der `stds` angegebene Wert sehr groß werden. Wenn ZNE aktiviert ist, werden `pub_result.data.evs_noise_factors` auch `pub_result.data.stds_noise_factors` und ausgefüllt, sodass Sie Ihre eigene Hochrechnung vornehmen können.\n", "\n" ] }, { "cell_type": "markdown", "id": "c4341184-a41a-4442-bc05-838c90ea93b8", "metadata": {}, "source": [ "\n", "\n", "## Metadaten zum Ergebnis\n", "\n", "Zusätzlich zu den Ausführungsergebnissen enthalten sowohl das `PrimitiveResult` als auch `PubResult` das Objekt ein Metadatenattribut zu dem übermittelten Auftrag. Die Metadaten, die Informationen zu allen eingereichten PUBs enthalten (wie beispielsweise die verschiedenen verfügbaren [Laufzeitoptionen](/docs/api/qiskit-ibm-runtime/options) ), finden Sie in der `PrimitiveResult.metatada`, während die für jede einzelne „ PUB “ spezifischen Metadaten in der zu finden `PubResult.metadata` sind.\n", "\n", "\n", " Im Metadatenfeld können Primitivimplementierungen beliebige für sie relevante Informationen zur Ausführung zurückgeben, und es gibt keine Schlüssel-Wert-Paare, die von der Basisprimitive garantiert werden. Daher können sich die zurückgegebenen Metadaten bei verschiedenen Implementierungen der Primitive unterscheiden.\n", "\n", "\n" ] }, { "cell_type": "code", "execution_count": 3, "id": "626ba203-44e2-4b8f-b04d-04388b8b1fa1", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "The metadata of the PrimitiveResult is:\n", "'dynamical_decoupling' : {'enable': False, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'},\n", "'twirling' : {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'},\n", "'resilience' : {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False},\n", "'version' : 2,\n", "\n", "The metadata of the PubResult result is:\n", "'shots' : 4096,\n", "'target_precision' : 0.015625,\n", "'circuit_metadata' : {},\n", "'resilience' : {},\n", "'num_randomizations' : 32,\n" ] } ], "source": [ "# Print out the results metadata\n", "print(\"The metadata of the PrimitiveResult is:\")\n", "for key, val in result.metadata.items():\n", " print(f\"'{key}' : {val},\")\n", "\n", "print(\"\\nThe metadata of the PubResult result is:\")\n", "for key, val in result[0].metadata.items():\n", " print(f\"'{key}' : {val},\")" ] }, { "cell_type": "markdown", "metadata": {}, "id": "a1b8767d", "source": "© IBM Corp., 2017-2026" } ], "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3" } }, "nbformat": 4, "nbformat_minor": 4 }