{ "cells": [ { "cell_type": "markdown", "id": "066d7e4d-a975-4519-b56f-095f861be3ac", "metadata": {}, "source": [ "---\n", "title: \"Dati in entrata e in uscita del programma di preventivazione\"\n", "description: \"Comprendere il formato di input e output della primitiva Estimator\"\n", "---\n", "\n", "\n", "\n", "# Dati in entrata e in uscita del programma di preventivazione\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", " Il codice presente in questa pagina è stato sviluppato sulla base dei seguenti requisiti.\n", " Si consiglia di utilizzare queste versioni o quelle più recenti.\n", "\n", " ```\n", " qiskit[all]~=2.5.1\n", " qiskit-ibm-runtime~=0.47.0\n", " ```\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "90d0c1e0-28e7-48da-a35f-6016fddea82c", "metadata": {}, "source": [ "Questa pagina offre una panoramica degli input e degli output della primitiva \" IBM Quantum Estimator\", che esegue carichi di lavoro sulle risorse di calcolo dell' IBM Quantum®. Estimator consente di definire in modo efficiente carichi di lavoro vettorializzati utilizzando una struttura dati denominata \" [**Primitive Unified Bloc\" ( PUB )**](/docs/guides/primitive-input-output#pubs). Vengono utilizzati come input per il metodo [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) della primitiva Estimator, che esegue il carico di lavoro definito come un’attività. Una volta completata l'operazione, i risultati vengono restituiti in un formato che dipende sia dai PUB utilizzati sia dalle opzioni di esecuzione specificate nella primitiva.\n", "\n" ] }, { "cell_type": "markdown", "id": "83a5fdd8-6547-47c7-9441-a7458edc7896", "metadata": {}, "source": [ "\n", "\n", "## Input\n", "\n", "Ogni file « PUB » ha il seguente formato:\n", "\n", "(``, ``, ``, ``),\n", "\n", "L'opzione `parameter values` può essere un elenco o un singolo parametro. Gli elementi provenienti dagli osservabili e i valori dei parametri vengono combinati seguendo le regole di diffusione descritte all'indirizzo NumPy, come illustrato nell'argomento \"[Ingressi e uscite primitivi](primitive-input-output#broadcasting-rules) \", e per ciascun elemento della struttura diffusa viene restituita una stima del valore atteso.\n", "\n", "\n", " Se l'input contiene valori numerici, questi vengono ignorati.\n", "\n", "\n", "Per la primitiva Estimator, un oggetto di tipo « PUB » può contenere al massimo quattro valori:\n", "\n", "* Un singolo elemento `QuantumCircuit`, che può contenere uno o più [`Parameter`](/docs/api/qiskit/qiskit.circuit.Parameter) oggetti\n", "* Un elenco di una o più grandezze osservabili, che specificano i valori attesi da stimare, organizzato in un array (ad esempio, una singola grandezza osservabile rappresentata come un array a 0 dimensioni, un elenco di grandezze osservabili come un array a 1 dimensione e così via). I dati possono essere in uno qualsiasi dei seguenti `ObservablesArrayLike` formati: `Pauli` `SparsePauliOp`, `PauliList`,, o `str`.\n", " \n", " * Con [questo metodo,](/docs/api/qiskit/qiskit.quantum_info.PauliList#group_qubit_wise_commuting) le grandezze osservabili correlate **nello stesso sistema di riferimento ( PUB )** vengono raggruppate.\n", " * Le grandezze osservabili relative agli spostamenti casa-lavoro in diversi PUB, anche se appartengono allo stesso circuito, non vengono stimate utilizzando la stessa misurazione. Ogni PUB rappresenta una base di misurazione diversa; pertanto, per ogni PUB sono necessarie misurazioni separate.\n", " * Per garantire che le variabili relative agli spostamenti casa-lavoro vengano stimate utilizzando lo stesso metodo di misurazione, raggrupparle all’interno dello stesso « PUB ».\n", " \n", "* Una raccolta di valori dei parametri a cui associare il circuito. Questo può essere specificato come un singolo oggetto di tipo array in cui l'ultimo indice indica il numero di oggetti del `Parameter` circuito, oppure può essere omesso (o, in modo equivalente, impostato a `None`) se il circuito non contiene `Parameter` oggetti.\n", "* (Facoltativo) Una precisione target per i valori attesi da stimare\n", "\n" ] }, { "cell_type": "markdown", "id": "846b3109-02a1-4783-ad3f-1c22f753c324", "metadata": {}, "source": [ "***\n", "\n", "Il codice seguente mostra un esempio di insieme di input vettorializzati per la `Estimator` primitiva e li esegue su un backend IBM® e come un unico `RuntimeJobV2 ` oggetto.\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 (\n", " QiskitRuntimeService,\n", " EstimatorV2 as Estimator,\n", ")\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", "## Output\n", "\n", "Dopo che uno o più PUB sono stati inviati a una QPU per l'esecuzione e un processo è stato completato con successo, i dati vengono restituiti sotto forma di un oggetto [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) contenitore a cui si accede chiamando il `RuntimeJobV2.result()` metodo.\n", "\n", "L'oggetto `PrimitiveResult` contiene un elenco iterabile di [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) oggetti che contengono i risultati dell'esecuzione per ciascun `PUB`.\n", "\n", "Ogni elemento di questo elenco corrisponde a ciascun PUB inviato al metodo della `run()` primitiva (ad esempio, un lavoro inviato con 20 PUB restituirà un `PrimitiveResult` oggetto contenente un elenco di 20 `PubResult` oggetti, uno per ciascun PUB ).\n", "\n", "Ogni primitiva `PubResult` dello stimatore contiene almeno un array di valori attesi (`PubResult.data.evs`) e le relative deviazioni standard (o `PubResult.data.stds` o `PubResult.data.ensemble_standard_error` , a seconda del `resilience_level` utilizzato), ma può contenere ulteriori dati a seconda delle opzioni di mitigazione dell'errore specificate.\n", "\n", "Ogni `PubResult` oggetto possiede sia un attributo `data` che un `metadata` attributo.\n", "\n", "* L'attributo `data` è un campo personalizzato [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) che contiene i valori effettivi delle misurazioni, le deviazioni standard e così via.\n", "* Il `DataBin` presenta diverse caratteristiche a seconda della forma o della struttura dell' PUB a associata, nonché delle opzioni di mitigazione degli errori specificate dalla primitiva utilizzata per inviare il lavoro (ad esempio, [ZNE](/docs/guides/error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) o [PEC](/docs/guides/error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec) ).\n", "* L'attributo `metadata` contiene informazioni relative alle opzioni di esecuzione e di mitigazione degli errori utilizzate (come spiegato più avanti nella sezione \"[Metadati del](#result-metadata) risultato\" di questa pagina).\n", "\n", "Di seguito è riportata una rappresentazione schematica della struttura `PrimitiveResult` dei dati relativa all'output dello Stima:\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", "In parole povere, un singolo job restituisce un `PrimitiveResult` oggetto e contiene un elenco di uno o più `PubResult` oggetti. Questi `PubResult` oggetti memorizzano quindi i dati di misurazione relativi a ciascun « PUB » inviato al processo.\n", "\n", "Il frammento di codice riportato di seguito descrive il `PrimitiveResult` formato (e i relativi `PubResult`) del processo creato in precedenza.\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", "#### Come la primitiva Estimator calcola l'errore\n", "\n", "Oltre alla stima della media delle grandezze osservabili passate nei PUB di input (il `evs` campo del `DataBin`), Estimator cerca anche di fornire una stima dell'errore associato a tali valori attesi. Tutte le query di Estimator inseriranno nel `stds` campo un valore pari all'errore standard della media per ciascun valore atteso, ma alcune opzioni di mitigazione dell'errore forniscono ulteriori informazioni, come ad esempio `ensemble_standard_error`.\n", "\n", "Si consideri un singolo osservabile $\\mathcal{O}$. In assenza di [ZNE](/docs/guides/error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne), si può pensare che ogni iterazione dell'esecuzione dello stimatore fornisca una stima puntuale del valore atteso $\\langle \\mathcal{O} \\rangle$. Se le stime puntuali sono contenute in un vettore `Os`, allora il valore restituito in `ensemble_standard_error` è equivalente al seguente (dove $\\sigma_{\\mathcal{O}}$ è la [deviazione standard della](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2) stima del valore atteso e $N_{shots}$ è il numero di iterazioni):\n", "\n", "$\\frac{ \\sigma_{\\mathcal{O}} }{ \\sqrt{N_{shots}} },$\n", "\n", "che considera tutte le inquadrature come parte di un unico insieme. Se hai richiesto [il](/docs/guides/error-mitigation-and-suppression-techniques#pauli-twirling) \"gate twirling\" (`twirling.enable_gates = True`), puoi raggruppare le stime puntuali di $\\langle \\mathcal{O} \\rangle$ in insiemi che condividono un \"twirl\" comune. Chiamiamo queste serie di stime `O_twirls`, e ce ne sono `num_randomizations` (numero di giri). Allora `stds` è l'errore standard della media di `O_twirls`, come in\n", "\n", "$\\frac{ \\sigma_{\\mathcal{O}} }{ \\sqrt{N_{twirls}} },$\n", "\n", "dove $\\sigma_{\\mathcal{O}}$ è la deviazione standard di `O_twirls` e $N_{twirls}$ è il numero di rotazioni. Quando non si attiva l'effetto rotatorio, `stds` e `ensemble_standard_error` sono uguali.\n", "\n", "Se si abilita ZNE, i `stds` parametri sopra descritti diventano i pesi in una regressione non lineare applicata a un modello di estrapolazione. Ciò che viene infine restituito in questo `stds` caso è l'incertezza del modello di adattamento valutata con un fattore di rumore pari a zero. Quando l'adattamento è inadeguato o presenta un elevato grado di incertezza, il valore riportato `stds` può diventare molto elevato. Quando ZNE è abilitato, `pub_result.data.evs_noise_factors` anche e `pub_result.data.stds_noise_factors` vengono compilati, in modo da poter effettuare la propria estrapolazione.\n", "\n" ] }, { "cell_type": "markdown", "id": "c4341184-a41a-4442-bc05-838c90ea93b8", "metadata": {}, "source": [ "\n", "\n", "## Metadati dei risultati\n", "\n", "Oltre ai risultati dell'esecuzione, entrambi gli `PrimitiveResult` oggetti `PubResult` e contengono un attributo di metadati relativo al processo inviato. I metadati contenenti le informazioni relative a tutti i PUB inviati (come le varie [opzioni di esecuzione](/docs/api/qiskit-ibm-runtime/options) disponibili) sono disponibili nel file `PrimitiveResult.metatada`, mentre i metadati specifici per ciascun PUB si trovano nel file `PubResult.metadata`.\n", "\n", "\n", " Nel campo dei metadati, le implementazioni delle primitive possono restituire qualsiasi informazione relativa all'esecuzione che ritengano pertinente, e non esistono coppie chiave-valore garantite dalla primitiva di base. Pertanto, i metadati restituiti potrebbero variare a seconda delle diverse implementazioni delle primitive.\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 }