Add how-to guides about primitives

docs/conf.py

@@ -34,6 +34,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.doctest",
     "reno.sphinxext",
     "sphinx_design",
     "matplotlib.sphinxext.plot_directive",
@@ -62,6 +63,9 @@
 
 intersphinx_mapping = {
     "retworkx": ("https://qiskit.org/documentation/retworkx/", None),
+    "qiskit-ibm-runtime": ("https://qiskit.org/documentation/partners/qiskit_ibm_runtime/", None),
+    "qiskit-aer": ("https://qiskit.org/documentation/aer/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None)
 }
 
 # -- Options for HTML output -------------------------------------------------
@@ -108,3 +112,18 @@
 }
 
 autoclass_content = "both"
+
+# -- Options for Doctest --------------------------------------------------------
+
+import sphinx.ext.doctest
+
+# This option will make doctest ignore whitespace when testing code.
+# It's specially important for circuit representation as it gives an
+# error otherwise
+doctest_default_flags = sphinx.ext.doctest.doctest.NORMALIZE_WHITESPACE
+
+# Leaving this string empty disables testing of doctest blocks from docstrings.
+# Doctest blocks are structures like this one:
+# >> code
+# output
+doctest_test_doctest_blocks = ""

docs/how_to/index.rst

@@ -0,0 +1,15 @@
+.. _how_to:
+
+#############
+How-to Guides
+#############
+
+
+Use the primitives
+==================
+
+.. toctree::
+  :maxdepth: 1
+
+  use_sampler
+  use_estimator

docs/how_to/use_estimator.rst

@@ -0,0 +1,256 @@
+###############################################
+Compute an expectation value with ``Estimator``
+###############################################
+
+This guide shows how to get the expected value of an observable for a given quantum circuit with the :class:`~qiskit.primitives.Estimator` primitive.
+
+.. note::
+
+    While this guide only uses Qiskit Terra's implementation of the ``Estimator`` primitive, there are other
+    implementations of this primitive like Qiskit Terra's :class:`~qiskit.primitives.BackendEstimator`, Qiskit Aer's :class:`~qiskit_aer.primitives.Estimator`
+    and Qiskit Runtime's :class:`~qiskit_ibm_runtime.Estimator`.
+
+
+Initialize observable
+=====================
+
+The first step is to define the observable whose expected value you want to compute. This observable can be any ``BaseOperator``, like the operators from :mod:`qiskit.quantum_info`.
+Among them it is preferable to use :class:`~qiskit.quantum_info.SparsePauliOp`.
+
+.. testcode::
+
+    from qiskit.quantum_info import SparsePauliOp
+
+    observable = SparsePauliOp(["II", "XX", "YY", "ZZ"], coeffs=[1, 1, -1, 1])
+
+Initialize quantum circuits
+===========================
+
+Then you need to create the :class:`~qiskit.circuit.QuantumCircuit` for which you want to obtain the expected value.
+
+.. plot::
+    :include-source:
+
+    from qiskit import QuantumCircuit
+
+    qc = QuantumCircuit(2)
+    qc.h(0)
+    qc.cx(0,1)
+    qc.draw("mpl")
+
+.. testsetup::
+
+    # This code is repeated (but hidden) because we will need to use the variables with the extension sphinx.ext.doctest (testsetup/testcode/testoutput directives)
+    # and we can't reuse the variables from the plot directive above because they are incompatible.
+    # The plot directive is used to draw the circuit with matplotlib and the code is shown because of the include-source flag.
+
+    from qiskit import QuantumCircuit
+
+    qc = QuantumCircuit(2)
+    qc.h(0)
+    qc.cx(0,1)
+
+.. note::
+
+    The :class:`~qiskit.circuit.QuantumCircuit` you pass to :class:`~qiskit.primitives.Estimator` must not include any measurements.
+
+Initialize the ``Estimator``
+============================
+
+Then, you need to create an :class:`~qiskit.primitives.Estimator` object.
+
+.. testcode::
+
+    from qiskit.primitives import Estimator
+
+    estimator = Estimator()
+
+Run and get results
+===================
+
+Now that you have defined ``estimator``, you can create a :class:`~.PrimitiveJob` (subclass of :class:`~qiskit.providers.JobV1`) with the
+:meth:`~qiskit.primitives.Estimator.run` method and, then, you can get the results (as a :class:`~qiskit.primitives.EstimatorResult` object) with
+the results with the :meth:`~qiskit.providers.JobV1.result` method.
+
+.. testcode::
+
+    job = estimator.run(qc, observable)
+    result = job.result()
+    print(result)
+
+.. testoutput::
+
+    EstimatorResult(values=array([4.]), metadata=[{}])
+
+Get the expected value
+----------------------
+
+From these results you can take the expected values with the attribute :attr:`~qiskit.primitives.EstimatorResult.values`.
+
+Generally, :attr:`~qiskit.primitives.EstimatorResult.values` returns a :class:`numpy.ndarray`
+whose ``i``-th element would be the expectation value corresponding to the ``i``-th circuit and ``i``-th observable.
+
+.. testcode::
+
+    exp_value = result.values[0]
+    print(exp_value)
+
+.. testoutput::
+
+    3.999999999999999
+
+Parameterized circuits with ``Estimator``
+=========================================
+
+The :class:`~qiskit.primitives.Estimator` primitive also has the option to include unbound parameterized circuits like the one below.
+You can also bind values to the parameters of the circuit and follow the steps
+of the previous example.
+
+.. testcode::
+
+    from qiskit.circuit import Parameter
+
+    theta = Parameter('θ')
+    param_qc = QuantumCircuit(2)
+    param_qc.ry(theta, 0)
+    param_qc.cx(0,1)
+    print(param_qc.draw())
+
+.. testoutput::
+
+         ┌───────┐     
+    q_0: ┤ Ry(θ) ├──■──
+         └───────┘┌─┴─┐
+    q_1: ─────────┤ X ├
+                  └───┘
+
+The main difference from the previous case is that now you need to include the parameter values
+for which you want to evaluate the expectation value as a ``list`` of ``list``\ s of ``float``\ s.
+The idea is that the ``i``-th element of the bigger ``list`` is the set of parameter values
+that corresponds to the ``i``-th circuit and observable.
+
+.. testcode::
+
+    import numpy as np
+
+    parameter_values = [[0], [np.pi/6], [np.pi/2]]
+
+    job = estimator.run([param_qc]*3, [observable]*3, parameter_values=parameter_values)
+    values = job.result().values
+
+    for i in range(3):
+        print(f"Parameter: {parameter_values[i][0]:.5f}\t Expectation value: {values[i]}")
+
+.. testoutput::
+
+    Parameter: 0.00000	 Expectation value: 2.0
+    Parameter: 0.52360	 Expectation value: 3.0
+    Parameter: 1.57080	 Expectation value: 4.0
+
+Change run options
+==================
+
+It is also possible that you may want to change any other option.
+
+For example, in the previous sections the :class:`~qiskit.primitives.Estimator`
+is :class:`~qiskit.quantum_info.Statevector`-based but it can be changed
+to shot-based by setting a number of ``shots``. For reproducibility purposes, in this
+guide a ``seed`` will also be set.
+
+There are two main ways of doing this:
+
+* Setting keyword arguments in the :meth:`~qiskit.primitives.Estimator.run` method.
+* Modify :class:`~qiskit.primitives.Estimator` options.
+
+Set keyword arguments for :meth:`~qiskit.primitives.Estimator.run`
+------------------------------------------------------------------
+
+If you only want to change the settings for a specific run, it can be more convenient to
+set the options inside the :meth:`~qiskit.primitives.Estimator.run` method. You can do this by
+passing them as keyword arguments.
+
+.. testcode::
+
+    job = estimator.run(qc, observable, shots=2048, seed=123)
+    result = job.result()
+    print(result)
+
+.. testoutput::
+
+    EstimatorResult(values=array([4.]), metadata=[{'variance': 3.552713678800501e-15, 'shots': 2048}])
+
+.. testcode::
+
+    print(result.values[0])
+
+.. testoutput::
+
+    3.999999998697238
+
+Change :class:`~qiskit.primitives.Estimator` options
+-----------------------------------------------------
+
+If you want to keep some configuration values for several runs, it can be better to
+change the :class:`~qiskit.primitives.Estimator` options. That way you can use the same 
+:class:`~qiskit.primitives.Estimator` object as many times as you wish without having to
+rewrite the configuration values every time you use :meth:`~qiskit.primitives.Estimator.run`.
+
+Modify existing :class:`~qiskit.primitives.Estimator`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you prefer to change the options of an already-defined :class:`~qiskit.primitives.Estimator`, you can use
+:meth:`~qiskit.primitives.Estimator.set_options` and introduce the new options as keyword arguments.
+
+.. testcode::
+
+    estimator.set_options(shots=2048, seed=123)
+
+    job = estimator.run(qc, observable)
+    result = job.result()
+    print(result)
+
+.. testoutput::
+
+    EstimatorResult(values=array([4.]), metadata=[{'variance': 3.552713678800501e-15, 'shots': 2048}])
+
+.. testcode::
+
+    print(result.values[0])
+
+.. testoutput::
+
+    3.999999998697238
+
+
+Define a new :class:`~qiskit.primitives.Estimator` with the options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you prefer to define a new :class:`~qiskit.primitives.Estimator` with new options, you need to
+define a ``dict`` like this one:
+
+.. testcode::
+
+    options = {"shots": 2048, "seed": 123}
+
+And then you can introduce it into your new :class:`~qiskit.primitives.Estimator` with the
+``options`` argument.
+
+.. testcode::
+
+    estimator = Estimator(options=options)
+
+    job = estimator.run(qc, observable)
+    result = job.result()
+    print(result)
+
+.. testoutput::
+
+    EstimatorResult(values=array([4.]), metadata=[{'variance': 3.552713678800501e-15, 'shots': 2048}])
+
+.. testcode::
+
+    print(result.values[0])
+
+.. testoutput::
+
+    3.999999998697238