Skip to content

Commit bdbfa89

Browse files
kaelynjabbycross
kaelynj
and
abbycross
authored
Add data structure tree of primitive output (#3013)
Closes #2650 The improvements made by #2612 I think will also help a lot with the feedback we've been getting about confusion around the `PrimitiveResult` data structure. --------- Co-authored-by: abbycross <[email protected]>
1 parent 1af36e1 commit bdbfa89

File tree

2 files changed

+126
-62
lines changed

2 files changed

+126
-62
lines changed

‎docs/guides/primitive-input-output.ipynb

+125-61
Original file line numberDiff line numberDiff line change
@@ -193,14 +193,22 @@
193193
"Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n",
194194
"\n",
195195
"\n",
196-
"Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates. Example 1 (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array. Example 2 (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array. Example 3 (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output. Example 4 (Standard nd generalization) has a 3x6 parameter value set array and two 3x1 observables array. These combine to create two 3x6 output arrays in a similar manner to the previous example.\n",
196+
"Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n",
197+
"\n",
198+
" - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n",
199+
"\n",
200+
" - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n",
201+
"\n",
202+
" - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n",
203+
"\n",
204+
" - *Example 4*: (Standard nd generalization) has a 3x6 parameter value set array and two 3x1 observables array. These combine to create two 3x6 output arrays in a similar manner to the previous example.\n",
197205
"\n",
198206
"![This image illustrates several visual representations of array broadcasting](/images/guides/primitive-input-output/broadcasting.svg \"Visual representation of broadcasting\")"
199207
]
200208
},
201209
{
202210
"cell_type": "code",
203-
"execution_count": 2,
211+
"execution_count": null,
204212
"id": "fcfaaab7-83f3-494a-8dee-67012435ab54",
205213
"metadata": {},
206214
"outputs": [],
@@ -239,7 +247,8 @@
239247
" [SparsePauliOp([\"IZI\"])],\n",
240248
" [SparsePauliOp([\"IIZ\"])],\n",
241249
" ],\n",
242-
"] # shape (2, 3, 1)"
250+
"]\n",
251+
"# >> pub result has shape (2, 3, 1)"
243252
]
244253
},
245254
{
@@ -270,15 +279,70 @@
270279
"id": "dfbaa52f-be7a-406d-b1d7-950daf90fd7f",
271280
"metadata": {},
272281
"source": [
273-
"## Overview of primitive results\n",
282+
"## Overview of primitive outputs\n",
274283
"\n",
275284
"Once one or more PUBs are sent to a QPU for execution and a job successfully completes, the data is returned as a [`PrimitiveResult`](../api/qiskit/qiskit.primitives.PrimitiveResult) container object accessed by calling the `RuntimeJobV2.result()` method. The `PrimitiveResult` contains an iterable list of [`PubResult`](../api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator, or samples of the circuit output in the case of the Sampler.\n",
276285
"\n",
277286
"Each element of this list corresponds to each PUB submitted to the primitive's `run()` method (for example, a job submitted with 20 PUBs will return a `PrimitiveResult` object that contains a list of 20 `PubResults`, one corresponding to each PUB).\n",
278287
"\n",
279288
"Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](../api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `DataBin` has various attributes depending on the shape or structure of the associated PUB as well as the error mitigation options specified by the primitive used to submit the job (for example, [ZNE](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, the `metadata` attribute contains information about the runtime and error mitigation options used (explained later in the [Result metadata](#result-metadata) section of this page).\n",
280289
"\n",
281-
"Put simply, a single job returns a `PrimitiveResult` object and contains a list of one or more `PubResults`. These `PubResults` are where the measurement data is stored for each of the PUBs that were submitted to the job.\n",
290+
"The following is a visual outline of the `PrimitiveResult` data structure:\n",
291+
"\n",
292+
"<Tabs>\n",
293+
" <TabItem value=\"estimator\" label=\"Estimator Output\">\n",
294+
" ```\n",
295+
" └── PrimitiveResult\n",
296+
" ├── PubResult[0]\n",
297+
" │ ├── metadata\n",
298+
" │ └── data ## In the form of a DataBin object\n",
299+
" │ ├── evs\n",
300+
" │ │ └── List of estimated expectation values in the shape\n",
301+
" | | specified by the first pub\n",
302+
" │ └── stds\n",
303+
" │ └── List of calculated standard deviations in the\n",
304+
" | same shape as above\n",
305+
" ├── PubResult[1]\n",
306+
" | ├── metadata\n",
307+
" | └── data ## In the form of a DataBin object\n",
308+
" | ├── evs\n",
309+
" | │ └── List of estimated expectation values in the shape\n",
310+
" | | specified by the second pub\n",
311+
" | └── stds\n",
312+
" | └── List of calculated standard deviations in the\n",
313+
" | same shape as above\n",
314+
" ├── ...\n",
315+
" ├── ...\n",
316+
" └── ...\n",
317+
" ```\n",
318+
" </TabItem>\n",
319+
" <TabItem value=\"sampler\" label=\"Sampler Output\">\n",
320+
" ```\n",
321+
" └── PrimitiveResult\n",
322+
" ├── PubResult[0]\n",
323+
" │ ├── metadata\n",
324+
" │ └── data ## In the form of a DataBin object\n",
325+
" │ ├── NAME_OF_CLASSICAL_REGISTER\n",
326+
" │ │ └── BitArray of count data (default is 'meas')\n",
327+
" | |\n",
328+
" │ └── NAME_OF_ANOTHER_CLASSICAL_REGISTER\n",
329+
" │ └── BitArray of count data (exists only if more than one\n",
330+
" | ClassicalRegister was specified in the circuit)\n",
331+
" ├── PubResult[1]\n",
332+
" | ├── metadata\n",
333+
" | └── data ## In the form of a DataBin object\n",
334+
" | └── NAME_OF_CLASSICAL_REGISTER\n",
335+
" | └── BitArray of count data for second pub\n",
336+
" ├── ...\n",
337+
" ├── ...\n",
338+
" └── ...\n",
339+
" ```\n",
340+
" </TabItem>\n",
341+
"</Tabs>\n",
342+
"\n",
343+
"Put simply, a single job returns a `PrimitiveResult` object and contains a list of one or more `PubResult`s. These `PubResult` objects then store the measurement data for each PUB that was submitted to the job.\n",
344+
"\n",
345+
"Each `PubResult` possesses different formats and attributes based on the type of primitive that was used for the job. The specifics are explained below.\n",
282346
"\n",
283347
"### Estimator output\n",
284348
"\n",
@@ -289,7 +353,7 @@
289353
},
290354
{
291355
"cell_type": "code",
292-
"execution_count": 3,
356+
"execution_count": 2,
293357
"id": "8a4a1929-6191-4061-9fb2-916d2580d1ae",
294358
"metadata": {},
295359
"outputs": [
@@ -304,61 +368,61 @@
304368
" 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))\n",
305369
"\n",
306370
"And this DataBin has attributes: dict_keys(['evs', 'stds', 'ensemble_standard_error'])\n",
307-
"Recall that this shape is due to our array of parameter binding sets having shape (100,), combined with \n",
308-
" our array of observables having shape (3, 1), where 2 is the number of parameters in the circuit.\n",
371+
"Recall that this shape is due to our array of parameter binding sets having shape (100, 2) -- where 2 is the\n",
372+
" number of parameters in the circuit -- combined with our array of observables having shape (3, 1). \n",
309373
"\n",
310374
"The expectation values measured from this PUB are: \n",
311-
"[[ 0.0320919 0.15649727 0.31343372 0.43034266 0.54093333 0.60008745\n",
312-
" 0.62968636 0.64985441 0.61328859 0.58429202 0.53657912 0.44121416\n",
313-
" 0.37848215 0.30865511 0.29711822 0.23220441 0.24198157 0.24600471\n",
314-
" 0.27719773 0.30766055 0.34989018 0.42426401 0.44114193 0.48662379\n",
315-
" 0.48892478 0.50813858 0.47864154 0.45833397 0.39724544 0.36428962\n",
316-
" 0.28327747 0.25002492 0.21327289 0.18641428 0.18263252 0.23691111\n",
317-
" 0.27436409 0.3104848 0.38595233 0.48211139 0.53219223 0.59620128\n",
318-
" 0.62013625 0.63945179 0.60641443 0.55973694 0.46178285 0.33682184\n",
319-
" 0.20623779 0.08093354 -0.07992132 -0.22845959 -0.37225619 -0.4846475\n",
320-
" -0.57825266 -0.60146049 -0.63310735 -0.63726147 -0.61810888 -0.56230607\n",
321-
" -0.48205036 -0.41404728 -0.34573293 -0.3043848 -0.26125055 -0.23243426\n",
322-
" -0.23788575 -0.27932709 -0.29308075 -0.35050398 -0.36333257 -0.43167903\n",
323-
" -0.45836888 -0.49809679 -0.48016876 -0.47620092 -0.46701144 -0.41834716\n",
324-
" -0.37213223 -0.30883286 -0.25630253 -0.23648365 -0.21272311 -0.18266163\n",
325-
" -0.20891224 -0.23607619 -0.2812903 -0.37212598 -0.42855426 -0.5098048\n",
326-
" -0.55252012 -0.6077557 -0.64452219 -0.63772964 -0.58166193 -0.52267364\n",
327-
" -0.41619625 -0.28135055 -0.14058507 0.02163411]\n",
328-
" [ 0.04867314 0.09734628 0.14653722 0.19572816 0.27080906 0.3220712\n",
329-
" 0.37126214 0.45462783 0.46705502 0.54265372 0.63585761 0.64776699\n",
330-
" 0.69592233 0.7238835 0.7963754 0.80414239 0.86472492 0.8807767\n",
331-
" 0.92064725 0.93203883 0.94394822 0.9631068 0.98485437 0.99676375\n",
332-
" 0.98485437 0.99676375 0.98330097 0.98071197 0.9631068 0.95223301\n",
333-
" 0.91029126 0.8818123 0.86834951 0.84815534 0.78705502 0.78653722\n",
334-
" 0.7228479 0.68401294 0.64932039 0.59546926 0.52401294 0.477411\n",
335-
" 0.41320388 0.37177994 0.29669903 0.25838188 0.17605178 0.10925566\n",
336-
" 0.05022654 -0.00724919 -0.06627832 -0.13669903 -0.17812298 -0.2412945\n",
337-
" -0.3179288 -0.32932039 -0.3961165 -0.46446602 -0.54524272 -0.60375405\n",
338-
" -0.6363754 -0.68349515 -0.72699029 -0.76737864 -0.80569579 -0.83262136\n",
339-
" -0.87404531 -0.91339806 -0.92789644 -0.95067961 -0.95482201 -0.98744337\n",
340-
" -0.98278317 -0.99469256 -0.98485437 -0.98692557 -0.97605178 -0.96828479\n",
341-
" -0.957411 -0.92737864 -0.91288026 -0.89475728 -0.8802589 -0.8036246\n",
342-
" -0.802589 -0.75184466 -0.67365696 -0.66019417 -0.62394822 -0.5612945\n",
343-
" -0.49812298 -0.45048544 -0.40543689 -0.34381877 -0.28271845 -0.2412945\n",
344-
" -0.1579288 -0.09838188 -0.02899676 0.03676375]\n",
345-
" [ 0.01551066 0.21564826 0.48033023 0.66495716 0.8110576 0.8781037\n",
346-
" 0.88811058 0.84508099 0.75952217 0.62593033 0.43730064 0.23466133\n",
347-
" 0.06104197 -0.10657327 -0.20213897 -0.33973357 -0.38076177 -0.38876728\n",
348-
" -0.3662518 -0.31671774 -0.24416787 -0.11457877 -0.10257052 -0.02351617\n",
349-
" -0.00700482 0.01951342 -0.02601789 -0.06404403 -0.16861592 -0.22365376\n",
350-
" -0.34373632 -0.38176246 -0.44180374 -0.47532679 -0.42178998 -0.31271499\n",
351-
" -0.17411971 -0.06304334 0.12258428 0.36875352 0.54037151 0.71499156\n",
352-
" 0.82706861 0.90712365 0.91612984 0.861092 0.74751392 0.56438802\n",
353-
" 0.36224905 0.16911627 -0.09356433 -0.32022015 -0.56638939 -0.7280005\n",
354-
" -0.83857652 -0.8736006 -0.87009819 -0.81005691 -0.69097505 -0.52085809\n",
355-
" -0.32772531 -0.14459941 0.03552442 0.15860904 0.2831947 0.36775283\n",
356-
" 0.39827381 0.35474389 0.34173494 0.24967165 0.22815686 0.12408531\n",
357-
" 0.06604541 -0.00150103 0.02451686 0.03452374 0.04202889 0.13159047\n",
358-
" 0.21314654 0.30971293 0.40027519 0.42178998 0.45481268 0.43830133\n",
359-
" 0.38476453 0.27969229 0.11107637 -0.08405779 -0.2331603 -0.45831509\n",
360-
" -0.60691726 -0.76502596 -0.88360748 -0.9316405 -0.88060542 -0.80405279\n",
361-
" -0.67446369 -0.46431922 -0.25217337 0.00650447]]\n"
375+
"[[-0.0019561 0.16085728 0.29698802 0.43606963 0.53121283 0.5969685\n",
376+
" 0.63992115 0.62658207 0.61263437 0.58295469 0.51890186 0.44903681\n",
377+
" 0.36275613 0.31529165 0.24365229 0.22488716 0.2064919 0.21266674\n",
378+
" 0.25266582 0.29227332 0.3383894 0.40124484 0.43668876 0.47124189\n",
379+
" 0.49155435 0.49565102 0.48974114 0.45253285 0.41819314 0.37325363\n",
380+
" 0.31558187 0.27316456 0.232253 0.20801753 0.2241275 0.22673926\n",
381+
" 0.25792105 0.32359987 0.3922956 0.47354181 0.53913202 0.58355338\n",
382+
" 0.61693633 0.63342795 0.62331109 0.55718284 0.48312621 0.34180366\n",
383+
" 0.23067799 0.07914177 -0.08567292 -0.21721504 -0.34511353 -0.47046631\n",
384+
" -0.55091665 -0.61094872 -0.64315868 -0.62915763 -0.59506568 -0.54248624\n",
385+
" -0.47123302 -0.41162141 -0.36772458 -0.28820385 -0.25435428 -0.2259389\n",
386+
" -0.219528 -0.25167104 -0.27170767 -0.32591941 -0.3643576 -0.40906199\n",
387+
" -0.44631549 -0.47730824 -0.50052905 -0.48634353 -0.44816397 -0.4371138\n",
388+
" -0.37407838 -0.33270469 -0.28177482 -0.24099076 -0.23659024 -0.21024583\n",
389+
" -0.22917374 -0.22486458 -0.31567148 -0.37429825 -0.43468671 -0.51994729\n",
390+
" -0.5739583 -0.64162036 -0.63765394 -0.63192947 -0.59171246 -0.51336111\n",
391+
" -0.41120564 -0.31085431 -0.14906647 -0.01122289]\n",
392+
" [ 0.01250163 0.07500977 0.14533142 0.20315145 0.27555671 0.3130616\n",
393+
" 0.38702956 0.41307462 0.46724834 0.55163433 0.60059904 0.63445761\n",
394+
" 0.67925511 0.74697226 0.76832921 0.8073968 0.82979555 0.87198854\n",
395+
" 0.90324261 0.93918479 0.93293398 0.96314624 0.96887616 0.9902331\n",
396+
" 0.97564787 0.98085688 0.98346139 0.97668967 0.95377002 0.93501758\n",
397+
" 0.92512046 0.90793072 0.88032296 0.84229717 0.81781482 0.77926813\n",
398+
" 0.70634197 0.70738377 0.65477276 0.61830968 0.5823675 0.51204584\n",
399+
" 0.4484959 0.40786561 0.35629639 0.28024482 0.23857273 0.12553718\n",
400+
" 0.09428311 0.01354343 -0.04948561 -0.08178148 -0.16200026 -0.23961453\n",
401+
" -0.28910014 -0.34848288 -0.43130616 -0.4500586 -0.50423232 -0.56569866\n",
402+
" -0.61518427 -0.66258627 -0.71207188 -0.76989191 -0.79072796 -0.82094023\n",
403+
" -0.84542258 -0.90324261 -0.90949342 -0.93137127 -0.94856101 -0.95689543\n",
404+
" -0.97668967 -0.97252246 -0.9876286 -0.97616877 -0.97043886 -0.97668967\n",
405+
" -0.96054174 -0.93449668 -0.90376351 -0.89282459 -0.86313322 -0.83083735\n",
406+
" -0.8100013 -0.72926162 -0.74176325 -0.70582107 -0.61570517 -0.58080479\n",
407+
" -0.52767287 -0.495377 -0.41880453 -0.37452793 -0.30055997 -0.23388462\n",
408+
" -0.17033468 -0.15366584 -0.04844381 -0.02344055]\n",
409+
" [-0.01641383 0.2467048 0.44864462 0.66898781 0.78686894 0.8808754\n",
410+
" 0.89281273 0.84008953 0.75802039 0.61427506 0.43720468 0.26361602\n",
411+
" 0.04625715 -0.11638896 -0.28102462 -0.35762248 -0.41681174 -0.44665506\n",
412+
" -0.39791097 -0.35463815 -0.25615519 -0.16065655 -0.09549863 -0.04774932\n",
413+
" 0.00746083 0.01044516 -0.00397911 -0.07162397 -0.11738374 -0.18851032\n",
414+
" -0.29395673 -0.36160159 -0.41581696 -0.42626212 -0.36955981 -0.3257896\n",
415+
" -0.19049988 -0.06018403 0.12981845 0.32877394 0.49589654 0.65506093\n",
416+
" 0.78537677 0.8589903 0.89032579 0.83412087 0.72767968 0.55807013\n",
417+
" 0.36707287 0.14474011 -0.12186023 -0.35264859 -0.52822681 -0.70131808\n",
418+
" -0.81273315 -0.87341457 -0.85501119 -0.80825665 -0.68589903 -0.51927381\n",
419+
" -0.32728177 -0.16065655 -0.02337727 0.19348421 0.2820194 0.36906242\n",
420+
" 0.40636658 0.39990052 0.36607809 0.27953245 0.21984581 0.13877145\n",
421+
" 0.08405869 0.01790599 -0.0134295 0.00348172 0.07411092 0.10246207\n",
422+
" 0.21238498 0.26908729 0.34021388 0.41084307 0.38995275 0.41034569\n",
423+
" 0.35165382 0.27953245 0.11042029 -0.04277543 -0.25366824 -0.45908978\n",
424+
" -0.62024372 -0.78786372 -0.85650336 -0.88933101 -0.88286496 -0.7928376\n",
425+
" -0.6520766 -0.46804278 -0.24968913 0.00099478]]\n"
362426
]
363427
}
364428
],
@@ -371,8 +435,8 @@
371435
")\n",
372436
"print(f\"And this DataBin has attributes: {result[0].data.keys()}\")\n",
373437
"print(\n",
374-
" \"Recall that this shape is due to our array of parameter binding sets having shape (100,), combined with \\n\\\n",
375-
" our array of observables having shape (3, 1), where 2 is the number of parameters in the circuit.\\n\"\n",
438+
" \"Recall that this shape is due to our array of parameter binding sets having shape (100, 2) -- where 2 is the\\n\\\n",
439+
" number of parameters in the circuit -- combined with our array of observables having shape (3, 1). \\n\"\n",
376440
")\n",
377441
"print(\n",
378442
" f\"The expectation values measured from this PUB are: \\n{result[0].data.evs}\"\n",

‎docs/migration-guides/external-providers-primitives-v2.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ The [PrimitiveResult](/api/qiskit/qiskit.primitives.PrimitiveResult)
4747
defines the output of a primitive job. It is comprised of additional data models such as
4848
[PubResult](/api/qiskit/qiskit.primitives.PubResult) and
4949
[DataBin](/api/qiskit/qiskit.primitives.DataBin).
50-
See [Overview of primitive results](/guides/primitive-input-output#overview-of-primitive-results)
50+
See [Overview of primitive results](/guides/primitive-input-output#overview-of-primitive-outputs)
5151
for more information.
5252

5353
## Example of a third-party `Sampler` implementation

0 commit comments

Comments
 (0)