Add outputs section for ibm circuit function (#2019)

Closes #1980. --------- Co-authored-by: Eric Arellano <[email protected]> Co-authored-by: abbycross <[email protected]>
Qiskit · Sep 24, 2024 · 55319ff · 55319ff
1 parent 7d088da
commit 55319ff
Showing 1 changed file with 43 additions and 2 deletions.
diff --git a/docs/guides/ibm-circuit-function.ipynb b/docs/guides/ibm-circuit-function.ipynb
@@ -138,7 +138,7 @@
    "id": "73815ae7",
    "metadata": {},
    "source": [
-    "## Parameters\n",
+    "## Inputs\n",
     "\n",
     "See the following table for all input parameters the IBM Circuit function accepts. The subsequent [Options](#options) section goes into more details about the available `options`."
    ]
@@ -151,7 +151,8 @@
     "| Name      | Type                       | Description                                                                                                                                                                                                                         | Required | Default                                                                  | Example                                  |\n",
     "|-----------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------------------------------------------------------|------------------------------------------|\n",
     "| backend_name   | str                        | Name of the backend to make the query.                                                                                                                                                                                              | Yes      | N/A                                                                      | `ibm_fez`                                |\n",
-    "| pubs      | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/guides/primitive-input-output#overview-of-pubs) for more information. The circuits don’t need to be ISA circuits. | Yes      | N/A                                                                      | (circuit, observables, parameter_values) |\n",
+    "| pubs      | Iterable[EstimatorPubLike] | An iterable of abstract PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/guides/primitive-input-output#overview-of-pubs) for more information. The circuits can be abstract (non-ISA). | Yes      | N/A                                                                      | (circuit, observables, parameter_values) |\n",
+    "| precision | float                      | The target precision for expectation value estimates of each run Estimator PUB that does not specify its own precision.                                                                                                             | No       | 0.015625                                                                 | 0.1                                      |\n",
     "| options   | dict                       | Input options. See the **Options** section for more details.                                                                                                                                                                                | No       | See the **Options** section for details.                                                   | `{\"optimization_level\": 3}`                |\n",
     "| instance  | str                        | The hub/group/project to use in that format.                                                                                                                                                                                        | No       | One is randomly picked if your account has access to multiple instances. | `hub1/group1/project1`                   |"
    ]
@@ -249,6 +250,46 @@
     "}"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "997c3779",
+   "metadata": {},
+   "source": [
+    "## Outputs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "75d7cbba",
+   "metadata": {},
+   "source": [
+    "The output of a Circuit function is a [PrimitiveResult](/api/qiskit/qiskit.primitives.PrimitiveResult), which contains two fields:\n",
+    "\n",
+    "- One or more [PubResult](/api/qiskit/qiskit.primitives.PubResult) objects. These can be indexed directly from the `PrimitiveResult`.\n",
+    "\n",
+    "- Job-level metadata.\n",
+    "\n",
+    "Each `PubResult` contains a `data` and a `metadata` field. \n",
+    "\n",
+    "- The `data` field contains at least an array of expectation values (`PubResult.data.evs`) and an array of standard errors (`PubResult.data.stds`). It can also contain more data, depending on the options used.\n",
+    "\n",
+    "- The `metadata` field contains PUB-level metadata (`PubResult.metadata`).\n",
+    "\n",
+    "The following code snippet describes the `PrimitiveResult` (and associated `PubResult`) format."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6e3f86aa",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(f'The result of the submitted job had {len(result)} PUB and has a value:\\n {result}\\n')\n",
+    "print(f'The expectation values measured from this PUB are: \\n{result[0].data.evs}')\n",
+    "print(f'And the associated metadata is: \\n{result[0].metadata}')"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "02295f5d",