More updates

Author: beckykd

docs/guides/_toc.json

@@ -347,6 +347,10 @@
                             "title": "Introduction to primitives",
                             "url": "/docs/guides/primitives"
                         },
+                        {
+                            "title": "Introduction to PUBs",
+                            "url": "/docs/guides/ppubs"
+                        },
                     {
                     "title": "Estimator",
                     "children": [

docs/guides/directed-execution-model.mdx

@@ -52,7 +52,7 @@ To learn more about Samplomatic, visit the [guides](https://qiskit.github.io/sam
 
 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. 
 
-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 the [Executor input and output topic](/docs/guides/executor-input-output.ipynb) 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.
 
 ### NoiseLearnerV3
 

docs/guides/estimator-input-output.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "---\n",
     "title: Inputs and outputs\n",
-    "description: Understand the inputs and outputs to the Executor primitive\n",
+    "description: Understand the inputs and outputs to the Executor primitive.\n",
     "---\n",
     "\n",
     "\n",
@@ -45,31 +45,29 @@
   },
   {
    "cell_type": "markdown",
-   "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b",
    "metadata": {},
    "source": [
-    "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Sampler and Estimator primitives, which execute the defined workload as a job. Then, after the job has completed, the results are returned in a format that is dependent on both the PUBs used as well as the runtime options specified from the Sampler or Estimator primitives."
+    "The inputs and output of the Executor primitive are very different from those of the Sampler and Estimator primitives. As part of the [directed execution model,](/docs/guides/directed-execution-model) the Executor primitive helps provide more flexibility when customizing your error mitigation workflow.  This primitive takes a `QuantumProgram` as input, and outputs a Qiskit Runtime job, which is then run on an IBM quantum computer."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The inputs to the Executor: Quantum Programs\n",
-    "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n",
+    "## Quantum programs\n",
     "\n",
-    "A :class:`~.QuantumProgram` is an iterable of\n",
-    ":class:`~.qiskit_ibm_runtime.quantum_program.QuantumProgramItem`\\s. Each of these items represents a\n",
-    "different task for the :class:`~.Executor` to perform. Typically, each item owns:\n",
+    "The input to Executor primitives is a  [`QuantumProgram`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgram.html#qiskit_ibm_runtime.quantum_program.QuantumProgram), which is an iterable of a \n",
+    "`qiskit_ibm_runtime.quantum_program.QuantumProgramItem`. Each of these items represents a\n",
+    "different task for the Executor to perform. Typically, each item owns:\n",
     "\n",
-    "* a :class:`~qiskit.circuit.QuantumCircuit` with static, non-parametrized gates;\n",
-    "* or a parametrized :class:`~qiskit.circuit.QuantumCircuit`, together with an array of parameter values;\n",
-    "* or a parametrized :class:`~qiskit.circuit.QuantumCircuit`, together with a\n",
-    "  :class:`~samplomatic.samplex.Samplex` to generate randomize arrays of parameter values.\n",
+    "* a `qiskit.circuit.QuantumCircuit` with static, non-parametrized gates;\n",
+    "* or a parametrized `qiskit.circuit.QuantumCircuit`, together with an array of parameter values;\n",
+    "* or a parametrized `qiskit.circuit.QuantumCircuit`, together with a\n",
+    "  `samplomatic.samplex.Samplex` to generate randomize arrays of parameter values.\n",
     "\n",
-    "Let us take a closer look at each of these items and how to add them to a :class:`~.QuantumProgram`\\.\n",
+    "Let us take a closer look at each of these items and how to add them to a `QuantumProgram`\\.\n",
     "\n",
-    "In the cell below, we initialize a :class:`~.QuantumProgram` and specify that we wish to perform ``1024``\n",
+    "In the cell below, we initialize a `QuantumProgram` and specify that we wish to perform ``1024``\n",
     "shots for every configuration of each item in the program. Next, we append a version of our target circuit with set parameters,\n",
     "transpiled according to the backend's ISA.\n",
     "\n",
@@ -102,7 +100,7 @@
     "    # Append the circuit to the program\n",
     "    program.append_circuit_item(isa_circuit)\n",
     "\n",
-    "We proceed to append a second item that contains a parametrized :class:`~qiskit.circuit.QuantumCircuit`\n",
+    "We proceed to append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit`\n",
     "and an array containing ``10`` sets of parameter values. This amounts to a circuit task requiring a total\n",
     "of ``10240`` shots (namely ``1024`` per set of parameter values).\n",
     "\n",
@@ -135,18 +133,18 @@
     "        circuit_arguments=np.random.rand(10, 3),  # 10 sets of parameter values\n",
     "    )\n",
     "\n",
-    "Finally, in the next cell we append a parametrized :class:`~qiskit.circuit.QuantumCircuit` and a\n",
-    ":class:`~samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of\n",
-    "parameters for the given circuit. As part of the :class:`~samplomatic.samplex.Samplex` arguments,\n",
+    "Finally, in the next cell we append a parametrized `qiskit.circuit.QuantumCircuit` and a\n",
+    "`samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of\n",
+    "parameters for the given circuit. As part of the `samplomatic.samplex.Samplex` arguments,\n",
     "we provide ``10`` sets of parameters for the parametric gates in the original circuit.\n",
     "Additionally, we use the ``shape`` request argument to request an extension of the implicit shape\n",
-    "defined by the :class:`~samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape``\n",
+    "defined by the `samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape``\n",
     "to ``(2, 14, 10)`` we request to randomize each of the ``10`` sets of parameters ``28`` times, and\n",
     "to arrange the randomized parameter sets in an array of be arranged in an array of shape\n",
     "``(2, 14, 10)``.\n",
     "\n",
-    "    We refer the reader to :mod:`~samplomatic` and its documentation for more details on the\n",
-    "    :class:`~samplomatic.samplex.Samplex` and its arguments.\n",
+    "    We refer the reader to :mod`~samplomatic` and its documentation for more details on the\n",
+    "    `samplomatic.samplex.Samplex` and its arguments.\n",
     "\n",
     ".. code-block:: python\n",
     "\n",
@@ -190,7 +188,7 @@
     "        shape=(2, 14, 10),\n",
     "    )\n",
     "\n",
-    "Now that we have populated our :class:`~.QuantumProgram`, we can proceed with execution."
+    "Now that we have populated our `QuantumProgram`, we can proceed with execution."
    ]
   }
  ],

docs/guides/executor-input-output.ipynb

@@ -49,7 +49,7 @@
    "metadata": {},
    "source": [
     "<Admonition type=\"note\" title=\"New execution model, now in beta release\">\n",
-    "The beta release of a new execution model is now available. The directed execution model provides more flexibility when customizing your error mitigation workflow. See the [Directed execution model](/docs/guides/directed-execution-model) guide for more information.\n",
+    "The beta release of a new execution model ([Directed execution model](/docs/guides/directed-execution-model)) is now available. This model provides more flexibility when customizing your error mitigation workflow. The [Executor primitive](#executor) is part of this model, but is very different from the Estimator and Sampler primatives.  Most of the information in this topic applies to those primitives.\n",
     "</Admonition>\n",
     "\n",
     "\n",
@@ -264,6 +264,18 @@
     ")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<span id=\"executor\"></span>\n",
+    "### Executor (beta)\n",
+    "\n",
+    "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.  The Executor primitive is part of the [directed execution model.](/docs/guides/directed-execution-model.mdx)\n",
+    "\n",
+    "The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor input and output topic](/docs/guides/executor-input-output.ipynb) for more information."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "02dbbc7d-76e7-4a89-8739-ba7f3a5a05b8",
@@ -272,11 +284,10 @@
     "## Next steps\n",
     "\n",
     "<Admonition type=\"tip\" title=\"Recommendations\">\n",
-    "    - Read [Get started with primitives](get-started-with-primitives) to implement primitives in your work.\n",
-    "    - Review detailed [primitives examples.](primitives-examples)\n",
+    "    - Read [Get started with Estimator,](get-started-with-estimator) [Get started with Sampler,](get-started-with-sampler) and [Get started with Executor,](get-started-with-executor) to implement primitives in your work.\n",
     "    - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n",
-    "    - See the [EstimatorV2 API reference](/docs/api/qiskit-ibm-runtime/estimator-v2) and [SamplerV2 API reference](/docs/api/qiskit-ibm-runtime/sampler-v2).\n",
-    "    - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n",
+    "    - See the [EstimatorV2 API reference](/docs/api/qiskit-ibm-runtime/estimator-v2), [SamplerV2 API reference](/docs/api/qiskit-ibm-runtime/sampler-v2), and [Executor API reference.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.Executor.html)\n",
+    "    - Read [Migrate to V2 primitives.](/docs/guides/v2-primitives)\n",
     "</Admonition>"
    ]
   }