Add executor information

docs/guides/_toc.json

@@ -215,27 +215,138 @@
             }
           ]
         },
-        {
-          "title": "Primitives",
-          "children": [
-            {
-              "title": "Introduction to primitives",
-              "url": "/docs/guides/primitives"
-            },
-            {
-              "title": "Get started with primitives",
-              "url": "/docs/guides/get-started-with-primitives"
-            },
-            {
-              "title": "Primitive inputs and outputs",
-              "url": "/docs/guides/primitive-input-output"
-            },
-            {
-              "title": "Exact simulation with Qiskit SDK primitives",
-              "url": "/docs/guides/simulate-with-qiskit-sdk-primitives"
-            }
-          ]
-        },
+                {
+                    "title": "Execute with primitives",
+                    "children": [
+                        {
+                            "title": "Introduction to primitives",
+                            "url": "/docs/guides/primitives"
+                        },
+                        {
+                            "title": "Introduction to PUBs",
+                            "url": "/docs/guides/pubs"
+                        },
+                        {
+                            "title": "Introduction to broadcasting",
+                            "url": "/docs/guides/broadcasting"
+                        },
+                    {
+                    "title": "Estimator",
+                    "children": [
+                            {
+                            "title": "Get started",
+                            "url": "/docs/guides/get-started-with-estimator"
+                            },
+                            {
+                            "title": "Inputs and outputs",
+                            "url": "/docs/guides/estimator-input-output"
+                            },
+                            {
+                            "title": "Broadcasting",
+                            "url": "/docs/guides/estimator-broadcasting"
+                            },
+                            {
+                            "title": "Options",
+                            "url": "/docs/guides/estimator-options"
+                            },
+                            {
+                            "title": "Examples",
+                            "url": "/docs/guides/estimator-examples"
+                            },
+                            {
+                            "title": "REST API",
+                            "url": "/docs/guides/estimator-rest-api"
+                            }
+                        ]
+                    },
+                    {
+                    "title": "Sampler",
+                    "children": [
+                            {
+                            "title": "Get started",
+                            "url": "/docs/guides/get-started-with-sampler"
+                            },
+                            {
+                            "title": "Inputs and outputs",
+                            "url": "/docs/guides/sampler-input-output"
+                            },
+                            {
+                            "title": "Options",
+                            "url": "/docs/guides/sampler-options"
+                            },
+                            {
+                            "title": "Examples",
+                            "url": "/docs/guides/sampler-examples"
+                            },
+                            {
+                            "title": "REST API",
+                            "url": "/docs/guides/sampler-rest-api"
+                            }
+                        ]
+                    },
+                    {
+                    "title": "Executor",
+                    "children": [
+                            {
+                            "title": "Get started",
+                            "url": "/docs/guides/get-started-with-executor"
+                            },
+                            {
+                            "title": "Inputs and outputs",
+                            "url": "/docs/guides/executor-input-output"
+                            },
+                            {
+                            "title": "Broadcasting",
+                            "url": "/docs/guides/executor-broadcasting"
+                            },
+                            {
+                            "title": "Options",
+                            "url": "/docs/guides/executor-options"
+                            },
+                            {
+                            "title": "Examples",
+                            "url": "/docs/guides/executor-examples"
+                            }                        ]
+                    },
+                    {
+                    "title": "Manage noise",
+                    "children": [
+                        {
+                            "title": "Error mitigation and suppression",
+                            "url": "/docs/guides/error-mitigation-and-suppression-techniques"
+                        },
+                        {
+                            "title": "Noise learning",
+                            "url": "/docs/guides/noise-learning"
+                        },
+                        {
+                            "title": "Configure error mitigation",
+                            "url": "/docs/guides/configure-error-mitigation"
+                        },
+                        {
+                            "title": "Configure error suppression",
+                            "url": "/docs/guides/configure-error-suppression"
+                        }
+                    ]
+                },
+                        {
+                            "title": "Directed execution model (beta)",
+                            "url": "/docs/guides/directed-execution-model"
+                        },
+                        {
+                            "title": "Introduction to options",
+                            "url": "/docs/guides/runtime-options-overview"
+                        },
+                        {
+                            "title": "Specify options",
+                            "url": "/docs/guides/specify-runtime-options"
+                        },
+                        {
+                            "title": "Qiskit Runtime local testing mode",
+                            "url": "/docs/guides/local-testing-mode"
+                        }
+                    ]
+                },
         {
           "title": "Debugging",
           "children": [
@@ -250,6 +361,10 @@
                   "title": "Exact and noisy simulation with Qiskit Aer primitives",
                   "url": "/docs/guides/simulate-with-qiskit-aer"
                 },
+                {
+              "title": "Exact simulation with Qiskit SDK primitives",
+              "url": "/docs/guides/simulate-with-qiskit-sdk-primitives"
+                },
                 {
                   "title": "Build noise models",
                   "url": "/docs/guides/build-noise-models"
@@ -916,4 +1031,4 @@
       "url": "/docs/guides/composer"
     }
   ]
-}
+}

docs/guides/algorithmiq-tem.ipynb

@@ -284,7 +284,7 @@
     "\n",
     "Name | Type | Description | Required | Default | Example\n",
     "-- | -- | -- | -- | -- | --\n",
-    "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/primitive-input-output#overview-of-pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n",
+    "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n",
     "`backend_name` | str | Name of the backend to make the query.| No | If not provided, the least-busy backend will be used. | \"ibm_fez\"\n",
     "`options` | dict | Input options. See `Options` section for more details. | No | See `Options` section for more details.| \\{\"max_bond_dimension\": 100\\}\n",
     "\n",

docs/guides/broadcasting.mdx

@@ -0,0 +1,43 @@
+---
+title: Broadcasting
+description: Understand how primitives handle array inputs and outputs using broadcasting semantics
+
+---
+
+# Primitive broadcasting
+
+The primitives aggregate elements from multiple arrays (observables and parameter values) by following the same broadcasting rules as NumPy. This section briefly summarizes those rules.  For a detailed explanation, see the [NumPy broadcasting rules documentation](https://numpy.org/doc/stable/user/basics.broadcasting.html).
+
+## Rules
+
+* Input arrays do not need to have the same number of dimensions.
+  * The resulting array will have the same number of dimensions as the input array with the largest dimension.
+  * The size of each dimension is the largest size of the corresponding dimension.
+  * Missing dimensions are assumed to have size one.
+* Shape comparisons start with the rightmost dimension and continue to the left.
+* Two dimensions are compatible if their sizes are equal or if one of them is 1.
+
+Examples of array pairs that broadcast:
+
+```text
+A1     (1d array):      1
+A2     (2d array):  3 x 5
+Result (2d array):  3 x 5
+
+
+A1     (3d array):  11 x 2 x 7
+A2     (3d array):  11 x 1 x 7
+Result (3d array):  11 x 2 x 7
+```
+
+Examples of array pairs that do not broadcast:
+
+```text
+A1     (1d array):  5
+A2     (1d array):  3
+
+A1     (2d array):      2 x 1
+A2     (3d array):  6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.
+```
+
+The primitives return one value for each element of the broadcasted shape.

docs/guides/directed-execution-model.mdx

@@ -1,5 +1,5 @@
 ---
-title: Directed execution model (beta)
+title: Directed execution model
 description: Use this composable, explicit execution model with your utility-scale experiments to fine-tune error mitigation and other techniques.
 
 ---
@@ -26,7 +26,7 @@ To apply error mitigation to a circuit under the framework, your workflow will t
 
 3. Build the template circuit and samplex from the boxed circuit.
 
-4. Run the template circuit and samplex with the [Executor](#executor-primitive) primitive, which will generate and execute the circuit variants as instructed. 
+4. Run the template circuit and samplex with the [Executor](#executor) primitive, which will generate and execute the circuit variants as instructed. 
 
 5. Post-process execution results. For example, you can apply post-selection, or extrapolate mitigated expectation values from the execution results.
 
@@ -41,22 +41,18 @@ The following tools can be used together to implement an error mitigation techni
 
 ![Example of using boxes and twirling annotations](/docs/images/guides/directed-execution-model/execution-model.avif)
 
-A circuit with annotated boxes can then be used to generate a *template circuit* and a *samplex*. The output template circuit is a parameterized circuit that will be executed without further alteration (other than having different parameter values assigned to it). The samplex, which is the core type of the Samplomatic library, represents a parametric probability distribution over the parameters of the template circuit and other array-valued fields. These fields can be used to post-process data collected from executing the bound template circuit. In other words, the template circuit and samplex pair tells the Executor primitive (described below) exactly what parameters to generate and what bound circuits to run. Because these two constructs are created on the client side, you can do local inspection and sampling to verify the outputs prior to sending it for hardware execution. 
+A circuit with annotated boxes can then be used to generate a *template circuit* and a *samplex*. The output template circuit is a parameterized circuit that will be executed without further alteration (other than having different parameter values assigned to it). The samplex, which is the core type of the Samplomatic library, represents a parametric probability distribution over the parameters of the template circuit and other array-valued fields. These fields can be used to post-process data collected from executing the bound template circuit. In other words, the template circuit and samplex pair tells the [Executor primitive](#executor) exactly what parameters to generate and what bound circuits to run. Because these two constructs are created on the client side, you can do local inspection and sampling to verify the outputs prior to sending it for hardware execution. 
 
 To simplify the process of generating annotated boxes, the Samplomatic library also provides transpiler passes that automatically group circuit instructions into annotated boxes, based on the strategies you provide.
 
 To learn more about Samplomatic, visit the [guides](https://qiskit.github.io/samplomatic/guides/index.html) and [API reference](https://qiskit.github.io/samplomatic/) documentation. Feel free to submit feedback and report bugs in its [GitHub](https://github.com/Qiskit/samplomatic) repository.
 
+<span id="executor"></span>
 ### Executor primitive
 
 Executor is a new Qiskit Runtime primitive that takes the template circuit and samplex pair as the input, generates and binds parameter values according to the samplex, executes the bound circuits on the hardware, and returns the execution results and metadata. It follows the directives of the input pair and does not make any implicit decisions for you, so that the process is transparent yet performant. 
 
-To access `Executor`, install the `executor_preview` branch from `qiskit-ibm-runtime`:
-
-```bash
-pip install -U git+https://github.com/Qiskit/qiskit-ibm-runtime.git@executor_preview
-```
-The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor API reference](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.Executor.html) for more information. In addition, the [Executor quickstart guide](https://qiskit.github.io/qiskit-ibm-runtime/guides/executor_basic.html) provides an overview and code examples.
+The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to [Get started with Executor](/docs/guides/get-started-with-executor) for more information.
 
 ### NoiseLearnerV3
 

docs/guides/estimator-broadcasting.mdx

@@ -0,0 +1,93 @@
+---
+title: Broadcasting
+description: How the Estimator handles array inputs and outputs using broadcasting semantics
+
+---
+
+# Estimator broadcasting semantics
+When invoking an Estimator primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a tuple called a [PUB.](/docs/guides/pubs) The data provided to these tuples can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting) This guide explains how the Estimator handles array inputs and outputs using broadcasting semantics.
+
+Following are some examples of common patterns expressed in terms of array broadcasting.  Their accompanying visual representation is shown in the figure that follows:
+
+
+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.
+
+![This image illustrates several visual representations of array broadcasting](/docs/images/guides/pubs/broadcasting.avif "Visual representation of broadcasting")
+
+```python
+# Broadcast single observable
+parameter_values = np.random.uniform(size=(5,))  # shape (5,)
+observables = SparsePauliOp("ZZZ")  # shape ()
+# >> pub result has shape (5,)
+
+# Zip
+parameter_values = np.random.uniform(size=(5,))  # shape (5,)
+observables = [
+    SparsePauliOp(pauli) for pauli in ["III", "XXX", "YYY", "ZZZ", "XYZ"]
+]  # shape (5,)
+# >> pub result has shape (5,)
+
+# Outer/Product
+parameter_values = np.random.uniform(size=(1, 6))  # shape (1, 6)
+observables = [
+    [SparsePauliOp(pauli)] for pauli in ["III", "XXX", "YYY", "ZZZ"]
+]  # shape (4, 1)
+# >> pub result has shape (4, 6)
+
+# Standard nd generalization
+parameter_values = np.random.uniform(size=(3, 6))  # shape (3, 6)
+observables = [
+    [
+        [SparsePauliOp(["XII"])],
+        [SparsePauliOp(["IXI"])],
+        [SparsePauliOp(["IIX"])],
+    ],
+    [
+        [SparsePauliOp(["ZII"])],
+        [SparsePauliOp(["IZI"])],
+        [SparsePauliOp(["IIZ"])],
+    ],
+]  # shape (2, 3, 1)
+# >> pub result has shape (2, 3, 6)
+```
+
+<Admonition type="tip" title="SparsePauliOp">
+Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:
+
+```python
+# shape ()
+a = SparsePauliOp("Z") 
+
+# shape ()
+b = SparsePauliOp("IIIIZXYIZ")
+
+# shape ()
+c = SparsePauliOp.from_list(["XX", "XY", "IZ"]) 
+```
+
+The following lists of operators, while equivalent in terms of information contained, have different shapes:
+
+```python
+# shape ()
+list1 = SparsePauliOp.from_list(["XX", "XY", "IZ"])
+
+# shape (3, )
+list2 = [SparsePauliOp("XX"), SparsePauliOp("XY"), SparsePauliOp("IZ")] 
+```
+</Admonition>
+
+## Next steps
+
+<Admonition type="tip" title="Recommendations">
+    - See the [broadcasting guide](/docs/guides/broadcasting) for an overview of broadcasting.
+    - Learn about [PUBs.](/docs/guides/pubs)
+    - Understand [Estimator inputs and outputs.](/docs/guides/estimator-input-output)
+</Admonition>