From 2f1e42f58b2c1afaa25d386c6d0f54b4511d417c Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Fri, 26 Aug 2022 16:08:05 +0200 Subject: [PATCH 01/84] Added how-to section --- docs/how_to.rst | 14 +++ docs/how_to/create_a_quantum_circuit.rst | 114 +++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 129 insertions(+) create mode 100644 docs/how_to.rst create mode 100644 docs/how_to/create_a_quantum_circuit.rst diff --git a/docs/how_to.rst b/docs/how_to.rst new file mode 100644 index 000000000000..b015683505bb --- /dev/null +++ b/docs/how_to.rst @@ -0,0 +1,14 @@ +.. _how_to: + +====== +How to +====== + +Create quantum circuits +----------------------- + +.. toctree:: + :maxdepth: 1 + + Create a quantum circuit + diff --git a/docs/how_to/create_a_quantum_circuit.rst b/docs/how_to/create_a_quantum_circuit.rst new file mode 100644 index 000000000000..f2073e5569b6 --- /dev/null +++ b/docs/how_to/create_a_quantum_circuit.rst @@ -0,0 +1,114 @@ + +======================== +Create a quantum circuit +======================== + +This guide shows how to initialize a quantum circuit. + +There are two ways to create a :class:`~qiskit.circuit.QuantumCircuit` object: + +* Specifying the number of qubits and bits. +* Creating :class:`~qiskit.circuit.QuantumRegister`\ s and :class:`~qiskit.circuit.ClassicalRegister`\ s + +Create from number of qubits and bits +===================================== + +In order to create a :class:`~qiskit.circuit.QuantumCircuit` by only specifying the number of bits and qubits, you need to follow these steps. + +.. jupyter-execute:: + + from qiskit import QuantumCircuit + + # Initialize number of qubits and classical bits + n_qubits = 3 + n_bits = 2 + + # Create the circuit + qc = QuantumCircuit(n_qubits, n_bits) + qc.draw() + + +If you don't want to include any classical bits, you don't have to write `QuantumCircuit(n_qubits,0)` but you can omit the number of classical bits. + +.. jupyter-execute:: + + from qiskit import QuantumCircuit + + qc = QuantumCircuit(n_qubits) + qc.draw() + +Create from quantum and classical registers +=========================================== + +Create quantum registers +------------------------ + +In order to create a quantum register, you have to define a :class:`~qiskit.circuit.QuantumRegister` object, passing as argument the desired number of qubits. + +.. jupyter-execute:: + + from qiskit import QuantumRegister + + # Create QuantumRegister formed by 2 qubits + qr1 = QuantumRegister(2) + + # Create QuantumRegister formed by 3 qubits + qr2 = QuantumRegister(3) + +Create classical registers +-------------------------- + +Analogously to the quantum registers, a classical register can be created by defining a :class:`~qiskit.circuit.ClassicalRegister` object, passing the number of classical bits as an argument. + +.. jupyter-execute:: + + from qiskit import ClassicalRegister + + # Create classical register with 2 classical bits + cr1 = ClassicalRegister(2) + + # Create classical register with 1 classical bit + cr2 = ClassicalRegister(1) + +Initialize the quantum circuit +------------------------------ + +Now that you have defined the quantum and classical registers, you can define a :class:`~qiskit.circuit.QuantumCircuit` from them. Each register has to be introduced as a separate argument. + +.. jupyter-execute:: + + # Create the quantum circuit from the registers + qc = QuantumCircuit(qr1, qr2, cr1, cr2) + qc.draw() + +You can put the registers in any order, even mixing classical and quantum. However, the relative order of the :class:`~qiskit.circuit.QuantumRegister`\ s does affect the order of the qubits on the final circuit. In particular, the qubits from the first :class:`~qiskit.circuit.QuantumRegister` will be the first and so on. The same applies to the :class:`~qiskit.circuit.ClassicalRegister`\ s. + +.. jupyter-execute:: + + # Both the classical and quantum registers have the same relative order as in qc + qc1 = QuantumCircuit(qr1, cr1, qr2, cr2) + + qc == qc1 + + +.. jupyter-execute:: + + # We change the order of the quantum registers + qc2 = QuantumCircuit(qr2, qr1, cr1, cr2) + + qc == qc2 + + + +.. jupyter-execute:: + + qc2.draw() + + + +.. jupyter-execute:: + + import qiskit.tools.jupyter + %qiskit_version_table + %qiskit_copyright + diff --git a/docs/index.rst b/docs/index.rst index 6461a6e6bb41..5ee79f883f64 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,7 @@ Qiskit Terra documentation :maxdepth: 2 :hidden: + How to API References Circuit Library Release Notes From d39833c8a6186c9983741ef9c0a9d2c42c8297c5 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Fri, 26 Aug 2022 16:43:22 +0200 Subject: [PATCH 02/84] added how to compose circuits guide --- docs/how_to.rst | 1 + docs/how_to/compose_quantum_circuits.rst | 86 ++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 docs/how_to/compose_quantum_circuits.rst diff --git a/docs/how_to.rst b/docs/how_to.rst index b015683505bb..e4203f78d29e 100644 --- a/docs/how_to.rst +++ b/docs/how_to.rst @@ -11,4 +11,5 @@ Create quantum circuits :maxdepth: 1 Create a quantum circuit + Compose quantum circuits diff --git a/docs/how_to/compose_quantum_circuits.rst b/docs/how_to/compose_quantum_circuits.rst new file mode 100644 index 000000000000..4d4b34476431 --- /dev/null +++ b/docs/how_to/compose_quantum_circuits.rst @@ -0,0 +1,86 @@ +======================== +Compose quantum circuits +======================== + +This guide shows how to combine different :class:`~qiskit.circuit.QuantumCircuit` objects. + +Build the circuits +================== + +The first step is creating the circuits we want to combine. + +.. jupyter-execute:: + + from qiskit import QuantumCircuit + qc1 = QuantumCircuit(2,1) + qc1.h(0) + qc1.cx(0,1) + qc1.measure(0,0) + + qc2 = QuantumCircuit(4,2) + qc2.y(1) + qc2.measure(1,1) + +Combine the circuits +==================== + +Now that we have built the circuits, they can be combined with two different methods: + +* :meth:`~qiskit.circuit.QuantumCircuit.compose()` +* :meth:`~qiskit.circuit.QuantumCircuit.append()` + +One detail these two methods have in common is that if the circuits have different sizes, they have to be applied to the one that has the most of both qubits and classical bits. + +:meth:`~qiskit.circuit.QuantumCircuit.compose()` +------------------------------------------------ + +In order to combine two circuits with :meth:`~qiskit.circuit.QuantumCircuit.compose()`, you only have to specify the circuit you want to insert. That way the qubits and bits of the smaller circuit will be included into the first qubits and bits of the bigger one in the original order they had. + +By default, :meth:`~qiskit.circuit.QuantumCircuit.compose()` does not change the circuit to which it is applied but returns the composed circuit. This can be changed by setting the ``inplace`` argument to ``True``. + +.. jupyter-execute:: + + qc3 = qc2.compose(qc1) + qc3.draw() + +If you want to insert the qubits and bits into specific positions in the bigger circuit, you can use the ``qubits`` and ``bits`` arguments. + +.. jupyter-execute:: + + qc4 = qc2.compose(qc1, qubits=[3,1], clbits=[1]) + qc4.draw() + +You can also apply the gates from the smaller circuit before those of the bigger one setting the ``front`` argument to ``True``. + +.. jupyter-execute:: + + qc5 = qc2.compose(qc1, front=True) + qc5.draw() + +:meth:`~qiskit.circuit.QuantumCircuit.append()` +----------------------------------------------- + +In order to combine two circuits with :meth:`~qiskit.circuit.QuantumCircuit.append()`, you have to specify the circuit you want to add and the qubits and classical bits (if there are any) into which you want the circuit to be inserted. + +This method changes the circuit to which it is applied instead of returning another one. + +.. jupyter-execute:: + + qc2.append(qc1, qargs=[3,1], cargs=[1]) + qc2.draw() + +Unlike :meth:`~qiskit.circuit.QuantumCircuit.compose()`, :meth:`~qiskit.circuit.QuantumCircuit.append()` turns the smaller circuit into a single :class:`~qiskit.circuit.Instruction`, so in order to unroll it you can use :meth:`~qiskit.circuit.QuantumCircuit.decompose()` + +.. jupyter-execute:: + + qc2.decompose().draw() + + +.. jupyter-execute:: + + import qiskit.tools.jupyter + %qiskit_version_table + %qiskit_copyright + + + From bb661fdd825fa2bcc2f753a49576bdc06fd6c6f0 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Fri, 26 Aug 2022 18:28:47 +0200 Subject: [PATCH 03/84] added how to visualize circuit guide --- docs/how_to.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how_to.rst b/docs/how_to.rst index e4203f78d29e..26e403134f42 100644 --- a/docs/how_to.rst +++ b/docs/how_to.rst @@ -12,4 +12,5 @@ Create quantum circuits Create a quantum circuit Compose quantum circuits + Visualize a quantum circuit From 59e06f95b9d0a3f46492bcab2e28df4d1a7347ca Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Fri, 26 Aug 2022 19:21:15 +0200 Subject: [PATCH 04/84] add how to create parameterized circuit guide --- docs/how_to.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to.rst b/docs/how_to.rst index 26e403134f42..ec02ce40c8ae 100644 --- a/docs/how_to.rst +++ b/docs/how_to.rst @@ -13,4 +13,4 @@ Create quantum circuits Create a quantum circuit Compose quantum circuits Visualize a quantum circuit - + Create a parameterized circuit From 63d6f8161fe4d6841d6160dc4321a3d11013bb39 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Fri, 26 Aug 2022 20:15:05 +0200 Subject: [PATCH 05/84] add guides --- .../how_to/create_a_parameterized_circuit.rst | 81 ++++++++++++++ docs/how_to/visualize_a_quantum_circuit.rst | 103 ++++++++++++++++++ 2 files changed, 184 insertions(+) create mode 100644 docs/how_to/create_a_parameterized_circuit.rst create mode 100644 docs/how_to/visualize_a_quantum_circuit.rst diff --git a/docs/how_to/create_a_parameterized_circuit.rst b/docs/how_to/create_a_parameterized_circuit.rst new file mode 100644 index 000000000000..92adb01ac56e --- /dev/null +++ b/docs/how_to/create_a_parameterized_circuit.rst @@ -0,0 +1,81 @@ +============================== +Create a parameterized circuit +============================== + +This guide will show how to create a :class:`~qiskit.circuit.QuantumCircuit` that includes parameters. + +Define the parameters +===================== + +In order to define a parameter, you need to create a :class:`~qiskit.circuit.Parameter` object. To do that you only need to choose a ``name``, that can be any unicode string like ``'θ'``. + +.. jupyter-execute:: + + from qiskit.circuit import Parameter + + theta = Parameter('θ') + +Create the parameterized circuit +================================ + +When creating the circuit you can include the :class:`~qiskit.circuit.Parameter` as if it was a defined number. + +.. jupyter-execute:: + + from qiskit import QuantumCircuit + + qc = QuantumCircuit(1) + qc.rx(theta, 0) + qc.draw('mpl') + +Assign values to parameters +=========================== + +You can use these two methods to assign values to the :class:`~qiskit.circuit.Parameter`\ s in your circuit: + +* :meth:`~qiskit.circuit.QuantumCircuit.bind_parameters()` +* :meth:`~qiskit.circuit.QuantumCircuit.assign_parameters()` + +:meth:`~qiskit.circuit.QuantumCircuit.bind_parameters()` +------------------------------------------------------- + +In order to use this method, you have to specify either a dictionary of the form ``{parameter: value,...}`` or an iterable formed only by numeric values, that will be assigned following the order from :attr:`~qiskit.circuit.QuantumCircuit.parameters`. + +.. jupyter-execute:: + + import numpy as np + + theta_values = [0, np.pi/2, np.pi] + qc_bind_list = [qc.bind_parameters({theta: theta_value}) for theta_value in theta_values] + + for i in range(3): + display(qc_bind_list[i].draw('mpl')) + +:meth:`~qiskit.circuit.QuantumCircuit.assign_parameters()` +--------------------------------------------------------- + +This method works identically like :meth:`~qiskit.circuit.QuantumCircuit.bind_parameters()` except that you can also assign other :class:`~qiskit.circuit.Parameter` objects instead of only numbers to the :class:`~qiskit.circuit.Parameter`\ s in your circuit. + +.. jupyter-execute:: + + phi = Parameter('ϕ') + + theta_values = [np.pi/2, phi] + qc_assign_list = [qc.assign_parameters({theta: theta_value}) for theta_value in theta_values] + + for i in range(2): + display(qc_assign_list[i].draw('mpl')) + +Another difference between :meth:`~qiskit.circuit.QuantumCircuit.bind_parameters()` and :meth:`~qiskit.circuit.QuantumCircuit.assign_parameters()` is that for the latter, you can make it change your original circuit instead of creating a new one by setting the ``inplace`` argument to ``True``. + +.. jupyter-execute:: + + qc.assign_parameters({theta: np.pi/4}, inplace=True) + qc.draw('mpl') + + +.. jupyter-execute:: + + import qiskit.tools.jupyter + %qiskit_version_table + %qiskit_copyright diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst new file mode 100644 index 000000000000..bd316cbd51d8 --- /dev/null +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -0,0 +1,103 @@ +=========================== +Visualize a quantum circuit +=========================== + +This guide shows how to get a visual representation of a quantum circuit. + +Build the circuit +================= + +The first step is to create the circuit. + +.. jupyter-execute:: + + from qiskit import QuantumCircuit + + qc = QuantumCircuit(3, 3) + qc.h(range(3)) + qc.cx(0, 1) + qc.measure(range(3), range(3)) + +Visualize the circuit +===================== + +There are three different ways to visualize a circuit. You can use + +* The ``print` function. +* The :meth:`~qiskit.circuit.QuantumCircuit.draw()` method. +* The :func:`~qiskit.visualization.circuit_drawer()` function. + +``print`` +--------- + +If you call the `print` function on a :class:`~qiskit.circuit.QuantumCircuit` object, you will get an `ASCII art version `_ of the circuit diagram. + +.. jupyter-execute:: + + print(qc) + +:meth:`~qiskit.circuit.QuantumCircuit.draw()` +--------------------------------------------- + +You can also call the :meth:`~qiskit.circuit.QuantumCircuit.draw()` method on a :class:`~qiskit.circuit.QuantumCircuit` object to visualize it. If you don't specify any arguments you will get a plain text representation of the circuit. + +.. jupyter-execute:: + + qc.draw() + +However, if you change the ``output`` argument, you can get other different renderings. The available options for this argument are: + +* ``'text'``: renders the circuit with ASCII art. It's the default option. +* ``'mpl'``: uses `matplotlib `_ to render the circuit. +* ``'latex'``: uses :math:`\LaTeX` to render the circuit. +* ``'latex_source'``: outputs the :math:`\LaTeX` source code that creates the ``'latex'`` rendering of the circuit. + +Because this optional or keyword argument is actually the first of this method, one can type ``qc.draw(option)`` instead of ``qc.draw(output=option)``. + +.. note:: + By default, the ``draw()`` method returns the rendered image as an object and does not output anything. The exact class returned depends on the output specified: ``'text'`` (the default) returns a ``TextDrawer`` object, ``'mpl'`` returns a ``matplotlib.figure.Figure`` object, and ``'latex'`` returns a ``PIL.Image`` object. Having the return types enables modifying or directly interacting with the rendered output from the drawers. Jupyter notebooks understand these return types and render them for us in this guide, but when running outside of Jupyter, you do not have this feature automatically. However, the ``draw()`` method has optional arguments to display or save the output. When specified, the ``filename`` kwarg takes a path to which it saves the rendered output. Alternatively, if you're using the ``'mpl'`` or ``'latex'`` outputs, you can leverage the ``interactive`` kwarg to open the image in a new window (this will not always work from within a notebook but will be demonstrated anyway). + + +``'mpl'`` +^^^^^^^^^ + +.. jupyter-execute:: + + qc.draw('mpl') + + +``'latex'`` +^^^^^^^^^^^^ + +.. jupyter-execute:: + + qc.draw('latex') + +``'latex_source'`` +^^^^^^^^^^^^^^^^^^ + +.. jupyter-execute:: + + qc.draw('latex_source') + + +:func:`~qiskit.visualization.circuit_drawer()` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you prefer to use a self-contained function instead of a :class:`~qiskit.circuit.QuantumCircuit` method to draw your circuit, you can do it with :func:`~qiskit.visualization.circuit_drawer()` from ``qiskit.visualization``. It has the exact same behavior as the :meth:`~qiskit.circuit.QuantumCircuit.draw()` method above, except that it requires the circuit to be included as an argument. + +.. note:: + In Qiskit Terra :math:`\leq 0.7`, the default behavior for the ``circuit_drawer()`` function is to use the ``'latex'`` output backend, and in :math:`0.6.x` that includes a fallback to ``'mpl'`` if ``'latex'`` fails for any reason. Starting with release :math:`> 0.7`, the default changes to the ``'text'`` output. + + +.. jupyter-execute:: + + from qiskit.visualization import circuit_drawer + + circuit_drawer(qc, output='mpl') + +.. jupyter-execute:: + + import qiskit.tools.jupyter + %qiskit_version_table + %qiskit_copyright From d28748a7df6e8fd2cd055bc3d19c7be3ea2b02db Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Mon, 29 Aug 2022 10:14:14 +0200 Subject: [PATCH 06/84] removed latex circuit visualization --- docs/how_to/visualize_a_quantum_circuit.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst index bd316cbd51d8..493706609486 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -66,12 +66,6 @@ Because this optional or keyword argument is actually the first of this method, qc.draw('mpl') -``'latex'`` -^^^^^^^^^^^^ - -.. jupyter-execute:: - - qc.draw('latex') ``'latex_source'`` ^^^^^^^^^^^^^^^^^^ From e7b2e4792cb23f37dc1533c7ae9ebc3eda991758 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Mon, 29 Aug 2022 10:43:39 +0200 Subject: [PATCH 07/84] fixed title underlines --- docs/how_to/create_a_parameterized_circuit.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how_to/create_a_parameterized_circuit.rst b/docs/how_to/create_a_parameterized_circuit.rst index 92adb01ac56e..17f7ee3638c9 100644 --- a/docs/how_to/create_a_parameterized_circuit.rst +++ b/docs/how_to/create_a_parameterized_circuit.rst @@ -37,7 +37,7 @@ You can use these two methods to assign values to the :class:`~qiskit.circuit.Pa * :meth:`~qiskit.circuit.QuantumCircuit.assign_parameters()` :meth:`~qiskit.circuit.QuantumCircuit.bind_parameters()` -------------------------------------------------------- +-------------------------------------------------------- In order to use this method, you have to specify either a dictionary of the form ``{parameter: value,...}`` or an iterable formed only by numeric values, that will be assigned following the order from :attr:`~qiskit.circuit.QuantumCircuit.parameters`. @@ -52,7 +52,7 @@ In order to use this method, you have to specify either a dictionary of the form display(qc_bind_list[i].draw('mpl')) :meth:`~qiskit.circuit.QuantumCircuit.assign_parameters()` ---------------------------------------------------------- +---------------------------------------------------------- This method works identically like :meth:`~qiskit.circuit.QuantumCircuit.bind_parameters()` except that you can also assign other :class:`~qiskit.circuit.Parameter` objects instead of only numbers to the :class:`~qiskit.circuit.Parameter`\ s in your circuit. From 352a7c42eed98f92086af4f6338bb219859fe984 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Mon, 29 Aug 2022 11:25:10 +0200 Subject: [PATCH 08/84] Fix typo --- docs/how_to/visualize_a_quantum_circuit.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst index 493706609486..f6f837fabaec 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -23,14 +23,14 @@ Visualize the circuit There are three different ways to visualize a circuit. You can use -* The ``print` function. +* The ``print()`` function. * The :meth:`~qiskit.circuit.QuantumCircuit.draw()` method. * The :func:`~qiskit.visualization.circuit_drawer()` function. -``print`` ---------- +``print()`` +----------- -If you call the `print` function on a :class:`~qiskit.circuit.QuantumCircuit` object, you will get an `ASCII art version `_ of the circuit diagram. +If you call the ``print()`` function on a :class:`~qiskit.circuit.QuantumCircuit` object, you will get an `ASCII art version `_ of the circuit diagram. .. jupyter-execute:: From ba14c2789fb56b8bb254022c55efc266bc6fa424 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Mon, 29 Aug 2022 12:08:01 +0200 Subject: [PATCH 09/84] explicitly set cregbundle to False when appending circuit with classical register --- docs/how_to/compose_quantum_circuits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/compose_quantum_circuits.rst b/docs/how_to/compose_quantum_circuits.rst index 4d4b34476431..6c47de63b419 100644 --- a/docs/how_to/compose_quantum_circuits.rst +++ b/docs/how_to/compose_quantum_circuits.rst @@ -67,7 +67,7 @@ This method changes the circuit to which it is applied instead of returning anot .. jupyter-execute:: qc2.append(qc1, qargs=[3,1], cargs=[1]) - qc2.draw() + qc2.draw(cregbundle=False) Unlike :meth:`~qiskit.circuit.QuantumCircuit.compose()`, :meth:`~qiskit.circuit.QuantumCircuit.append()` turns the smaller circuit into a single :class:`~qiskit.circuit.Instruction`, so in order to unroll it you can use :meth:`~qiskit.circuit.QuantumCircuit.decompose()` From 4cf2634353bcd51cc58e45f47041bf06d5e65ae9 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 30 Aug 2022 13:34:23 +0200 Subject: [PATCH 10/84] Fix typo --- docs/how_to/create_a_quantum_circuit.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/create_a_quantum_circuit.rst b/docs/how_to/create_a_quantum_circuit.rst index f2073e5569b6..28e38453aae0 100644 --- a/docs/how_to/create_a_quantum_circuit.rst +++ b/docs/how_to/create_a_quantum_circuit.rst @@ -28,7 +28,7 @@ In order to create a :class:`~qiskit.circuit.QuantumCircuit` by only specifying qc.draw() -If you don't want to include any classical bits, you don't have to write `QuantumCircuit(n_qubits,0)` but you can omit the number of classical bits. +If you don't want to include any classical bits, you don't have to write ``QuantumCircuit(n_qubits,0)`` but you can omit the number of classical bits. .. jupyter-execute:: From ed2115c9be5500c84ff708e168514b5ada24be28 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 31 Aug 2022 11:58:44 +0200 Subject: [PATCH 11/84] Added explanation about needed latex distribution --- docs/how_to/visualize_a_quantum_circuit.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst index f6f837fabaec..b04274acc106 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -49,7 +49,7 @@ However, if you change the ``output`` argument, you can get other different rend * ``'text'``: renders the circuit with ASCII art. It's the default option. * ``'mpl'``: uses `matplotlib `_ to render the circuit. -* ``'latex'``: uses :math:`\LaTeX` to render the circuit. +* ``'latex'``: uses :math:`\LaTeX` to render the circuit. It requires a full `LaTeX `_ distribution and the package ``pdflatex``. * ``'latex_source'``: outputs the :math:`\LaTeX` source code that creates the ``'latex'`` rendering of the circuit. Because this optional or keyword argument is actually the first of this method, one can type ``qc.draw(option)`` instead of ``qc.draw(output=option)``. From a7b38d8b5cb1a422b3bffbe472fa70a8a7e895c7 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 31 Aug 2022 12:24:57 +0200 Subject: [PATCH 12/84] added link to qiskit.visualization module --- docs/how_to/visualize_a_quantum_circuit.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst index b04274acc106..c55c2be79857 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -78,7 +78,7 @@ Because this optional or keyword argument is actually the first of this method, :func:`~qiskit.visualization.circuit_drawer()` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you prefer to use a self-contained function instead of a :class:`~qiskit.circuit.QuantumCircuit` method to draw your circuit, you can do it with :func:`~qiskit.visualization.circuit_drawer()` from ``qiskit.visualization``. It has the exact same behavior as the :meth:`~qiskit.circuit.QuantumCircuit.draw()` method above, except that it requires the circuit to be included as an argument. +If you prefer to use a self-contained function instead of a :class:`~qiskit.circuit.QuantumCircuit` method to draw your circuit, you can do it with :func:`~qiskit.visualization.circuit_drawer()` from :mod:`qiskit.visualization`. It has the exact same behavior as the :meth:`~qiskit.circuit.QuantumCircuit.draw()` method above, except that it requires the circuit to be included as an argument. .. note:: In Qiskit Terra :math:`\leq 0.7`, the default behavior for the ``circuit_drawer()`` function is to use the ``'latex'`` output backend, and in :math:`0.6.x` that includes a fallback to ``'mpl'`` if ``'latex'`` fails for any reason. Starting with release :math:`> 0.7`, the default changes to the ``'text'`` output. From 861baaa1a469500b9a01dba62080fc4cccf7749e Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Thu, 1 Sep 2022 11:10:37 +0200 Subject: [PATCH 13/84] Simplified references --- docs/how_to/compose_quantum_circuits.rst | 24 ++++++---------- .../how_to/create_a_parameterized_circuit.rst | 28 ++++++++----------- docs/how_to/create_a_quantum_circuit.rst | 22 ++++++--------- docs/how_to/visualize_a_quantum_circuit.rst | 23 ++++++--------- 4 files changed, 37 insertions(+), 60 deletions(-) diff --git a/docs/how_to/compose_quantum_circuits.rst b/docs/how_to/compose_quantum_circuits.rst index 6c47de63b419..290b56c0026b 100644 --- a/docs/how_to/compose_quantum_circuits.rst +++ b/docs/how_to/compose_quantum_circuits.rst @@ -2,7 +2,7 @@ Compose quantum circuits ======================== -This guide shows how to combine different :class:`~qiskit.circuit.QuantumCircuit` objects. +This guide shows how to combine different :class:`~.QuantumCircuit` objects. Build the circuits ================== @@ -26,17 +26,17 @@ Combine the circuits Now that we have built the circuits, they can be combined with two different methods: -* :meth:`~qiskit.circuit.QuantumCircuit.compose()` -* :meth:`~qiskit.circuit.QuantumCircuit.append()` +* :meth:`~.QuantumCircuit.compose` +* :meth:`~.QuantumCircuit.append` One detail these two methods have in common is that if the circuits have different sizes, they have to be applied to the one that has the most of both qubits and classical bits. -:meth:`~qiskit.circuit.QuantumCircuit.compose()` +:meth:`~.QuantumCircuit.compose` ------------------------------------------------ -In order to combine two circuits with :meth:`~qiskit.circuit.QuantumCircuit.compose()`, you only have to specify the circuit you want to insert. That way the qubits and bits of the smaller circuit will be included into the first qubits and bits of the bigger one in the original order they had. +In order to combine two circuits with :meth:`~.QuantumCircuit.compose`, you only have to specify the circuit you want to insert. That way the qubits and bits of the smaller circuit will be included into the first qubits and bits of the bigger one in the original order they had. -By default, :meth:`~qiskit.circuit.QuantumCircuit.compose()` does not change the circuit to which it is applied but returns the composed circuit. This can be changed by setting the ``inplace`` argument to ``True``. +By default, :meth:`~.QuantumCircuit.compose` does not change the circuit to which it is applied but returns the composed circuit. This can be changed by setting the ``inplace`` argument to ``True``. .. jupyter-execute:: @@ -57,10 +57,10 @@ You can also apply the gates from the smaller circuit before those of the bigger qc5 = qc2.compose(qc1, front=True) qc5.draw() -:meth:`~qiskit.circuit.QuantumCircuit.append()` +:meth:`~.QuantumCircuit.append` ----------------------------------------------- -In order to combine two circuits with :meth:`~qiskit.circuit.QuantumCircuit.append()`, you have to specify the circuit you want to add and the qubits and classical bits (if there are any) into which you want the circuit to be inserted. +In order to combine two circuits with :meth:`~.QuantumCircuit.append`, you have to specify the circuit you want to add and the qubits and classical bits (if there are any) into which you want the circuit to be inserted. This method changes the circuit to which it is applied instead of returning another one. @@ -69,18 +69,12 @@ This method changes the circuit to which it is applied instead of returning anot qc2.append(qc1, qargs=[3,1], cargs=[1]) qc2.draw(cregbundle=False) -Unlike :meth:`~qiskit.circuit.QuantumCircuit.compose()`, :meth:`~qiskit.circuit.QuantumCircuit.append()` turns the smaller circuit into a single :class:`~qiskit.circuit.Instruction`, so in order to unroll it you can use :meth:`~qiskit.circuit.QuantumCircuit.decompose()` +Unlike :meth:`~.QuantumCircuit.compose`, :meth:`~.QuantumCircuit.append` turns the smaller circuit into a single :class:`~qiskit.circuit.Instruction`, so in order to unroll it you can use :meth:`~.QuantumCircuit.decompose` .. jupyter-execute:: qc2.decompose().draw() -.. jupyter-execute:: - - import qiskit.tools.jupyter - %qiskit_version_table - %qiskit_copyright - diff --git a/docs/how_to/create_a_parameterized_circuit.rst b/docs/how_to/create_a_parameterized_circuit.rst index 17f7ee3638c9..d411982bd04c 100644 --- a/docs/how_to/create_a_parameterized_circuit.rst +++ b/docs/how_to/create_a_parameterized_circuit.rst @@ -2,12 +2,12 @@ Create a parameterized circuit ============================== -This guide will show how to create a :class:`~qiskit.circuit.QuantumCircuit` that includes parameters. +This guide will show how to create a :class:`~.QuantumCircuit` that includes parameters. Define the parameters ===================== -In order to define a parameter, you need to create a :class:`~qiskit.circuit.Parameter` object. To do that you only need to choose a ``name``, that can be any unicode string like ``'θ'``. +In order to define a parameter, you need to create a :class:`~.Parameter` object. To do that you only need to choose a ``name``, that can be any unicode string like ``'θ'``. .. jupyter-execute:: @@ -18,7 +18,7 @@ In order to define a parameter, you need to create a :class:`~qiskit.circuit.Par Create the parameterized circuit ================================ -When creating the circuit you can include the :class:`~qiskit.circuit.Parameter` as if it was a defined number. +When creating the circuit you can include the :class:`~.Parameter` as if it was a defined number. .. jupyter-execute:: @@ -31,15 +31,15 @@ When creating the circuit you can include the :class:`~qiskit.circuit.Parameter` Assign values to parameters =========================== -You can use these two methods to assign values to the :class:`~qiskit.circuit.Parameter`\ s in your circuit: +You can use these two methods to assign values to the :class:`~.Parameter`\ s in your circuit: -* :meth:`~qiskit.circuit.QuantumCircuit.bind_parameters()` -* :meth:`~qiskit.circuit.QuantumCircuit.assign_parameters()` +* :meth:`~.QuantumCircuit.bind_parameters` +* :meth:`~.QuantumCircuit.assign_parameters` -:meth:`~qiskit.circuit.QuantumCircuit.bind_parameters()` +:meth:`~.QuantumCircuit.bind_parameters` -------------------------------------------------------- -In order to use this method, you have to specify either a dictionary of the form ``{parameter: value,...}`` or an iterable formed only by numeric values, that will be assigned following the order from :attr:`~qiskit.circuit.QuantumCircuit.parameters`. +In order to use this method, you have to specify either a dictionary of the form ``{parameter: value,...}`` or an iterable formed only by numeric values, that will be assigned following the order from :attr:`~.QuantumCircuit.parameters`. .. jupyter-execute:: @@ -51,10 +51,10 @@ In order to use this method, you have to specify either a dictionary of the form for i in range(3): display(qc_bind_list[i].draw('mpl')) -:meth:`~qiskit.circuit.QuantumCircuit.assign_parameters()` +:meth:`~.QuantumCircuit.assign_parameters` ---------------------------------------------------------- -This method works identically like :meth:`~qiskit.circuit.QuantumCircuit.bind_parameters()` except that you can also assign other :class:`~qiskit.circuit.Parameter` objects instead of only numbers to the :class:`~qiskit.circuit.Parameter`\ s in your circuit. +This method works identically like :meth:`~.QuantumCircuit.bind_parameters` except that you can also assign other :class:`~.Parameter` objects instead of only numbers to the :class:`~.Parameter`\ s in your circuit. .. jupyter-execute:: @@ -66,16 +66,10 @@ This method works identically like :meth:`~qiskit.circuit.QuantumCircuit.bind_pa for i in range(2): display(qc_assign_list[i].draw('mpl')) -Another difference between :meth:`~qiskit.circuit.QuantumCircuit.bind_parameters()` and :meth:`~qiskit.circuit.QuantumCircuit.assign_parameters()` is that for the latter, you can make it change your original circuit instead of creating a new one by setting the ``inplace`` argument to ``True``. +Another difference between :meth:`~.QuantumCircuit.bind_parameters` and :meth:`~.QuantumCircuit.assign_parameters` is that for the latter, you can make it change your original circuit instead of creating a new one by setting the ``inplace`` argument to ``True``. .. jupyter-execute:: qc.assign_parameters({theta: np.pi/4}, inplace=True) qc.draw('mpl') - -.. jupyter-execute:: - - import qiskit.tools.jupyter - %qiskit_version_table - %qiskit_copyright diff --git a/docs/how_to/create_a_quantum_circuit.rst b/docs/how_to/create_a_quantum_circuit.rst index 28e38453aae0..992b267ee7a0 100644 --- a/docs/how_to/create_a_quantum_circuit.rst +++ b/docs/how_to/create_a_quantum_circuit.rst @@ -5,15 +5,15 @@ Create a quantum circuit This guide shows how to initialize a quantum circuit. -There are two ways to create a :class:`~qiskit.circuit.QuantumCircuit` object: +There are two ways to create a :class:`~.QuantumCircuit` object: * Specifying the number of qubits and bits. -* Creating :class:`~qiskit.circuit.QuantumRegister`\ s and :class:`~qiskit.circuit.ClassicalRegister`\ s +* Creating :class:`~.QuantumRegister`\ s and :class:`~.ClassicalRegister`\ s. Create from number of qubits and bits ===================================== -In order to create a :class:`~qiskit.circuit.QuantumCircuit` by only specifying the number of bits and qubits, you need to follow these steps. +In order to create a :class:`~.QuantumCircuit` by only specifying the number of bits and qubits, you need to follow these steps. .. jupyter-execute:: @@ -28,7 +28,7 @@ In order to create a :class:`~qiskit.circuit.QuantumCircuit` by only specifying qc.draw() -If you don't want to include any classical bits, you don't have to write ``QuantumCircuit(n_qubits,0)`` but you can omit the number of classical bits. +If you don't want to include any classical bits, you don't have to write `QuantumCircuit(n_qubits,0)` but you can omit the number of classical bits. .. jupyter-execute:: @@ -43,7 +43,7 @@ Create from quantum and classical registers Create quantum registers ------------------------ -In order to create a quantum register, you have to define a :class:`~qiskit.circuit.QuantumRegister` object, passing as argument the desired number of qubits. +In order to create a quantum register, you have to define a :class:`~.QuantumRegister` object, passing as argument the desired number of qubits. .. jupyter-execute:: @@ -58,7 +58,7 @@ In order to create a quantum register, you have to define a :class:`~qiskit.circ Create classical registers -------------------------- -Analogously to the quantum registers, a classical register can be created by defining a :class:`~qiskit.circuit.ClassicalRegister` object, passing the number of classical bits as an argument. +Analogously to the quantum registers, a classical register can be created by defining a :class:`~.ClassicalRegister` object, passing the number of classical bits as an argument. .. jupyter-execute:: @@ -73,7 +73,7 @@ Analogously to the quantum registers, a classical register can be created by def Initialize the quantum circuit ------------------------------ -Now that you have defined the quantum and classical registers, you can define a :class:`~qiskit.circuit.QuantumCircuit` from them. Each register has to be introduced as a separate argument. +Now that you have defined the quantum and classical registers, you can define a :class:`~.QuantumCircuit` from them. Each register has to be introduced as a separate argument. .. jupyter-execute:: @@ -81,7 +81,7 @@ Now that you have defined the quantum and classical registers, you can define a qc = QuantumCircuit(qr1, qr2, cr1, cr2) qc.draw() -You can put the registers in any order, even mixing classical and quantum. However, the relative order of the :class:`~qiskit.circuit.QuantumRegister`\ s does affect the order of the qubits on the final circuit. In particular, the qubits from the first :class:`~qiskit.circuit.QuantumRegister` will be the first and so on. The same applies to the :class:`~qiskit.circuit.ClassicalRegister`\ s. +You can put the registers in any order, even mixing classical and quantum. However, the relative order of the :class:`~.QuantumRegister`\ s does affect the order of the qubits on the final circuit. In particular, the qubits from the first :class:`~.QuantumRegister` will be the first and so on. The same applies to the :class:`~.ClassicalRegister`\ s. .. jupyter-execute:: @@ -106,9 +106,3 @@ You can put the registers in any order, even mixing classical and quantum. Howev -.. jupyter-execute:: - - import qiskit.tools.jupyter - %qiskit_version_table - %qiskit_copyright - diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst index c55c2be79857..7e7ea20ced03 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -24,22 +24,22 @@ Visualize the circuit There are three different ways to visualize a circuit. You can use * The ``print()`` function. -* The :meth:`~qiskit.circuit.QuantumCircuit.draw()` method. -* The :func:`~qiskit.visualization.circuit_drawer()` function. +* The :meth:`~.QuantumCircuit.draw` method. +* The :func:`~.circuit_drawer` function. ``print()`` ----------- -If you call the ``print()`` function on a :class:`~qiskit.circuit.QuantumCircuit` object, you will get an `ASCII art version `_ of the circuit diagram. +If you call the ``print()`` function on a :class:`~.QuantumCircuit` object, you will get an `ASCII art version `_ of the circuit diagram. .. jupyter-execute:: print(qc) -:meth:`~qiskit.circuit.QuantumCircuit.draw()` +:meth:`~.QuantumCircuit.draw` --------------------------------------------- -You can also call the :meth:`~qiskit.circuit.QuantumCircuit.draw()` method on a :class:`~qiskit.circuit.QuantumCircuit` object to visualize it. If you don't specify any arguments you will get a plain text representation of the circuit. +You can also call the :meth:`~.QuantumCircuit.draw` method on a :class:`~.QuantumCircuit` object to visualize it. If you don't specify any arguments you will get a plain text representation of the circuit. .. jupyter-execute:: @@ -55,7 +55,7 @@ However, if you change the ``output`` argument, you can get other different rend Because this optional or keyword argument is actually the first of this method, one can type ``qc.draw(option)`` instead of ``qc.draw(output=option)``. .. note:: - By default, the ``draw()`` method returns the rendered image as an object and does not output anything. The exact class returned depends on the output specified: ``'text'`` (the default) returns a ``TextDrawer`` object, ``'mpl'`` returns a ``matplotlib.figure.Figure`` object, and ``'latex'`` returns a ``PIL.Image`` object. Having the return types enables modifying or directly interacting with the rendered output from the drawers. Jupyter notebooks understand these return types and render them for us in this guide, but when running outside of Jupyter, you do not have this feature automatically. However, the ``draw()`` method has optional arguments to display or save the output. When specified, the ``filename`` kwarg takes a path to which it saves the rendered output. Alternatively, if you're using the ``'mpl'`` or ``'latex'`` outputs, you can leverage the ``interactive`` kwarg to open the image in a new window (this will not always work from within a notebook but will be demonstrated anyway). + By default, the :meth:`~.QuantumCircuit.draw` method returns the rendered image as an object and does not output anything. The exact class returned depends on the output specified: ``'text'`` (the default) returns a ``TextDrawer`` object, ``'mpl'`` returns a `matplotlib.figure.Figure `_ object, and ``'latex'`` returns a ``PIL.Image`` object. Having the return types enables modifying or directly interacting with the rendered output from the drawers. Jupyter notebooks understand these return types and render them for us in this guide, but when running outside of Jupyter, you do not have this feature automatically. However, the :meth:`~.QuantumCircuit.draw` method has optional arguments to display or save the output. When specified, the ``filename`` kwarg takes a path to which it saves the rendered output. Alternatively, if you're using the ``'mpl'`` or ``'latex'`` outputs, you can leverage the ``interactive`` kwarg to open the image in a new window (this will not always work from within a notebook). ``'mpl'`` @@ -75,13 +75,13 @@ Because this optional or keyword argument is actually the first of this method, qc.draw('latex_source') -:func:`~qiskit.visualization.circuit_drawer()` +:func:`~.circuit_drawer` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you prefer to use a self-contained function instead of a :class:`~qiskit.circuit.QuantumCircuit` method to draw your circuit, you can do it with :func:`~qiskit.visualization.circuit_drawer()` from :mod:`qiskit.visualization`. It has the exact same behavior as the :meth:`~qiskit.circuit.QuantumCircuit.draw()` method above, except that it requires the circuit to be included as an argument. +If you prefer to use a self-contained function instead of a :class:`~.QuantumCircuit` method to draw your circuit, you can do it with :func:`~.circuit_drawer` from :mod:`qiskit.visualization`. It has the exact same behavior as the :meth:`~.QuantumCircuit.draw` method above, except that it requires the circuit to be included as an argument. .. note:: - In Qiskit Terra :math:`\leq 0.7`, the default behavior for the ``circuit_drawer()`` function is to use the ``'latex'`` output backend, and in :math:`0.6.x` that includes a fallback to ``'mpl'`` if ``'latex'`` fails for any reason. Starting with release :math:`> 0.7`, the default changes to the ``'text'`` output. + In Qiskit Terra :math:`\leq 0.7`, the default behavior for the :func:`~.circuit_drawer` function is to use the ``'latex'`` output backend, and in :math:`0.6.x` that includes a fallback to ``'mpl'`` if ``'latex'`` fails for any reason. Starting with release :math:`> 0.7`, the default changes to the ``'text'`` output. .. jupyter-execute:: @@ -90,8 +90,3 @@ If you prefer to use a self-contained function instead of a :class:`~qiskit.circ circuit_drawer(qc, output='mpl') -.. jupyter-execute:: - - import qiskit.tools.jupyter - %qiskit_version_table - %qiskit_copyright From 9354aa08305942dbd1f932987d2cedf3465e3c2d Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Mon, 12 Sep 2022 19:35:20 +0200 Subject: [PATCH 14/84] Change 'we' to 'you' --- docs/how_to/compose_quantum_circuits.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how_to/compose_quantum_circuits.rst b/docs/how_to/compose_quantum_circuits.rst index 290b56c0026b..df5e31d2706e 100644 --- a/docs/how_to/compose_quantum_circuits.rst +++ b/docs/how_to/compose_quantum_circuits.rst @@ -7,7 +7,7 @@ This guide shows how to combine different :class:`~.QuantumCircuit` objects. Build the circuits ================== -The first step is creating the circuits we want to combine. +The first step is creating the circuits you want to combine. .. jupyter-execute:: @@ -24,7 +24,7 @@ The first step is creating the circuits we want to combine. Combine the circuits ==================== -Now that we have built the circuits, they can be combined with two different methods: +Now that you have built the circuits, they can be combined with two different methods: * :meth:`~.QuantumCircuit.compose` * :meth:`~.QuantumCircuit.append` From 02298c610a6329da6c04d97e11b54b1141dd192f Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 28 Sep 2022 16:44:00 +0200 Subject: [PATCH 15/84] Changed how_to.rst to how_to/index.rst --- docs/how_to.rst | 16 ---------------- docs/how_to/index.rst | 16 ++++++++++++++++ docs/index.rst | 2 +- 3 files changed, 17 insertions(+), 17 deletions(-) delete mode 100644 docs/how_to.rst create mode 100644 docs/how_to/index.rst diff --git a/docs/how_to.rst b/docs/how_to.rst deleted file mode 100644 index ec02ce40c8ae..000000000000 --- a/docs/how_to.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _how_to: - -====== -How to -====== - -Create quantum circuits ------------------------ - -.. toctree:: - :maxdepth: 1 - - Create a quantum circuit - Compose quantum circuits - Visualize a quantum circuit - Create a parameterized circuit diff --git a/docs/how_to/index.rst b/docs/how_to/index.rst new file mode 100644 index 000000000000..18c91b6f4425 --- /dev/null +++ b/docs/how_to/index.rst @@ -0,0 +1,16 @@ +.. _how_to: + +====== +How to +====== + +Create quantum circuits +----------------------- + +.. toctree:: + :maxdepth: 1 + + Create a quantum circuit + Compose quantum circuits + Visualize a quantum circuit + Create a parameterized circuit diff --git a/docs/index.rst b/docs/index.rst index 5ee79f883f64..043d0526195a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ Qiskit Terra documentation :maxdepth: 2 :hidden: - How to + How to API References Circuit Library Release Notes From 6ad73b056821d22a3b49f332e8390e3b8980bc38 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Tue, 28 Feb 2023 15:55:42 +0100 Subject: [PATCH 16/84] Removed jupyter-execute from create_a_quantum_circuit --- docs/how_to/create_a_quantum_circuit.rst | 91 +++++++++++++++++++----- 1 file changed, 75 insertions(+), 16 deletions(-) diff --git a/docs/how_to/create_a_quantum_circuit.rst b/docs/how_to/create_a_quantum_circuit.rst index 992b267ee7a0..700ea07e74a7 100644 --- a/docs/how_to/create_a_quantum_circuit.rst +++ b/docs/how_to/create_a_quantum_circuit.rst @@ -1,7 +1,7 @@ -======================== +######################## Create a quantum circuit -======================== +######################## This guide shows how to initialize a quantum circuit. @@ -15,7 +15,7 @@ Create from number of qubits and bits In order to create a :class:`~.QuantumCircuit` by only specifying the number of bits and qubits, you need to follow these steps. -.. jupyter-execute:: +.. testcode:: from qiskit import QuantumCircuit @@ -25,17 +25,37 @@ In order to create a :class:`~.QuantumCircuit` by only specifying the number of # Create the circuit qc = QuantumCircuit(n_qubits, n_bits) - qc.draw() + print(qc.draw()) +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + q_0: + + q_1: + + q_2: + + c: 2/ + If you don't want to include any classical bits, you don't have to write `QuantumCircuit(n_qubits,0)` but you can omit the number of classical bits. -.. jupyter-execute:: +.. testcode:: from qiskit import QuantumCircuit qc = QuantumCircuit(n_qubits) - qc.draw() + print(qc.draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + q_0: + + q_1: + + q_2: Create from quantum and classical registers =========================================== @@ -45,7 +65,7 @@ Create quantum registers In order to create a quantum register, you have to define a :class:`~.QuantumRegister` object, passing as argument the desired number of qubits. -.. jupyter-execute:: +.. testcode:: from qiskit import QuantumRegister @@ -60,7 +80,7 @@ Create classical registers Analogously to the quantum registers, a classical register can be created by defining a :class:`~.ClassicalRegister` object, passing the number of classical bits as an argument. -.. jupyter-execute:: +.. testcode:: from qiskit import ClassicalRegister @@ -75,34 +95,73 @@ Initialize the quantum circuit Now that you have defined the quantum and classical registers, you can define a :class:`~.QuantumCircuit` from them. Each register has to be introduced as a separate argument. -.. jupyter-execute:: +.. testcode:: # Create the quantum circuit from the registers qc = QuantumCircuit(qr1, qr2, cr1, cr2) - qc.draw() + print(qc.draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + q0_0: + + q0_1: + + q1_0: + + q1_1: + + q1_2: + + c0: 2/ + + c1: 1/ + You can put the registers in any order, even mixing classical and quantum. However, the relative order of the :class:`~.QuantumRegister`\ s does affect the order of the qubits on the final circuit. In particular, the qubits from the first :class:`~.QuantumRegister` will be the first and so on. The same applies to the :class:`~.ClassicalRegister`\ s. -.. jupyter-execute:: +.. testcode:: # Both the classical and quantum registers have the same relative order as in qc qc1 = QuantumCircuit(qr1, cr1, qr2, cr2) - qc == qc1 + print(qc == qc1) + +.. testoutput:: + True -.. jupyter-execute:: +.. testcode:: # We change the order of the quantum registers qc2 = QuantumCircuit(qr2, qr1, cr1, cr2) - qc == qc2 + print(qc == qc2) +.. testoutput:: + False -.. jupyter-execute:: - qc2.draw() +.. testcode:: + print(qc2.draw()) +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + q1_0: + + q1_1: + + q1_2: + + q0_0: + + q0_1: + + c0: 2/ + + c1: 1/ + From 571db6105fe2bfa9633bc8732fff24f1222fd51c Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Tue, 28 Feb 2023 15:56:30 +0100 Subject: [PATCH 17/84] Removed jupyter-execute from create_a_parameterized_circuit --- .../how_to/create_a_parameterized_circuit.rst | 61 +++++++++++++++---- 1 file changed, 50 insertions(+), 11 deletions(-) diff --git a/docs/how_to/create_a_parameterized_circuit.rst b/docs/how_to/create_a_parameterized_circuit.rst index d411982bd04c..7568ed631861 100644 --- a/docs/how_to/create_a_parameterized_circuit.rst +++ b/docs/how_to/create_a_parameterized_circuit.rst @@ -1,6 +1,6 @@ -============================== +############################## Create a parameterized circuit -============================== +############################## This guide will show how to create a :class:`~.QuantumCircuit` that includes parameters. @@ -9,24 +9,33 @@ Define the parameters In order to define a parameter, you need to create a :class:`~.Parameter` object. To do that you only need to choose a ``name``, that can be any unicode string like ``'θ'``. -.. jupyter-execute:: +.. testcode:: from qiskit.circuit import Parameter theta = Parameter('θ') + Create the parameterized circuit ================================ When creating the circuit you can include the :class:`~.Parameter` as if it was a defined number. -.. jupyter-execute:: +.. testcode:: from qiskit import QuantumCircuit qc = QuantumCircuit(1) qc.rx(theta, 0) - qc.draw('mpl') + print(qc.draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + ┌───────┐ + q: ┤ Rx(θ) ├ + └───────┘ + Assign values to parameters =========================== @@ -41,7 +50,7 @@ You can use these two methods to assign values to the :class:`~.Parameter`\ s in In order to use this method, you have to specify either a dictionary of the form ``{parameter: value,...}`` or an iterable formed only by numeric values, that will be assigned following the order from :attr:`~.QuantumCircuit.parameters`. -.. jupyter-execute:: +.. testcode:: import numpy as np @@ -49,14 +58,27 @@ In order to use this method, you have to specify either a dictionary of the form qc_bind_list = [qc.bind_parameters({theta: theta_value}) for theta_value in theta_values] for i in range(3): - display(qc_bind_list[i].draw('mpl')) + print(qc_bind_list[i].draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + ┌───────┐ + q: ┤ Rx(0) ├ + └───────┘ + ┌─────────┐ + q: ┤ Rx(π/2) ├ + └─────────┘ + ┌───────┐ + q: ┤ Rx(π) ├ + └───────┘ :meth:`~.QuantumCircuit.assign_parameters` ---------------------------------------------------------- This method works identically like :meth:`~.QuantumCircuit.bind_parameters` except that you can also assign other :class:`~.Parameter` objects instead of only numbers to the :class:`~.Parameter`\ s in your circuit. -.. jupyter-execute:: +.. testcode:: phi = Parameter('ϕ') @@ -64,12 +86,29 @@ This method works identically like :meth:`~.QuantumCircuit.bind_parameters` exc qc_assign_list = [qc.assign_parameters({theta: theta_value}) for theta_value in theta_values] for i in range(2): - display(qc_assign_list[i].draw('mpl')) + print(qc_assign_list[i].draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + ┌─────────┐ + q: ┤ Rx(π/2) ├ + └─────────┘ + ┌───────┐ + q: ┤ Rx(ϕ) ├ + └───────┘ + Another difference between :meth:`~.QuantumCircuit.bind_parameters` and :meth:`~.QuantumCircuit.assign_parameters` is that for the latter, you can make it change your original circuit instead of creating a new one by setting the ``inplace`` argument to ``True``. -.. jupyter-execute:: +.. testcode:: qc.assign_parameters({theta: np.pi/4}, inplace=True) - qc.draw('mpl') + print(qc.draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + ┌─────────┐ + q: ┤ Rx(π/4) ├ + └─────────┘ \ No newline at end of file From 2081f4a5217822d092b0b894e3d94132981cbfb7 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Tue, 28 Feb 2023 15:57:23 +0100 Subject: [PATCH 18/84] Removed jupyter-execute from compose_quantum_circuits --- docs/how_to/compose_quantum_circuits.rst | 134 ++++++++++++++++++++--- 1 file changed, 117 insertions(+), 17 deletions(-) diff --git a/docs/how_to/compose_quantum_circuits.rst b/docs/how_to/compose_quantum_circuits.rst index df5e31d2706e..c5a01dbbc963 100644 --- a/docs/how_to/compose_quantum_circuits.rst +++ b/docs/how_to/compose_quantum_circuits.rst @@ -1,6 +1,6 @@ -======================== +######################## Compose quantum circuits -======================== +######################## This guide shows how to combine different :class:`~.QuantumCircuit` objects. @@ -9,17 +9,45 @@ Build the circuits The first step is creating the circuits you want to combine. -.. jupyter-execute:: +.. testcode:: from qiskit import QuantumCircuit + qc1 = QuantumCircuit(2,1) qc1.h(0) qc1.cx(0,1) - qc1.measure(0,0) + qc1.measure(1,0) qc2 = QuantumCircuit(4,2) - qc2.y(1) - qc2.measure(1,1) + qc2.y(0) + qc2.x(1) + qc2.cx(0,3) + qc2.measure(3,1) + + print(qc1.draw()) + print(qc2.draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + ┌───┐ + q_0: ┤ H ├──■───── + └───┘┌─┴─┐┌─┐ + q_1: ─────┤ X ├┤M├ + └───┘└╥┘ + c: 1/═══════════╩═ + 0 + ┌───┐ + q_0: ┤ Y ├──■───── + ├───┤ │ + q_1: ┤ X ├──┼───── + └───┘ │ + q_2: ───────┼───── + ┌─┴─┐┌─┐ + q_3: ─────┤ X ├┤M├ + └───┘└╥┘ + c: 2/═══════════╩═ + 1 Combine the circuits ==================== @@ -38,24 +66,69 @@ In order to combine two circuits with :meth:`~.QuantumCircuit.compose`, you only By default, :meth:`~.QuantumCircuit.compose` does not change the circuit to which it is applied but returns the composed circuit. This can be changed by setting the ``inplace`` argument to ``True``. -.. jupyter-execute:: +.. testcode:: qc3 = qc2.compose(qc1) - qc3.draw() + print(qc3.draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + ┌───┐ ┌───┐ + q_0: ┤ Y ├──■──┤ H ├──■───── + ├───┤ │ └───┘┌─┴─┐┌─┐ + q_1: ┤ X ├──┼───────┤ X ├┤M├ + └───┘ │ └───┘└╥┘ + q_2: ───────┼─────────────╫─ + ┌─┴─┐ ┌─┐ ║ + q_3: ─────┤ X ├─┤M├───────╫─ + └───┘ └╥┘ ║ + c: 2/════════════╩════════╩═ + 1 0 If you want to insert the qubits and bits into specific positions in the bigger circuit, you can use the ``qubits`` and ``bits`` arguments. -.. jupyter-execute:: +.. testcode:: qc4 = qc2.compose(qc1, qubits=[3,1], clbits=[1]) - qc4.draw() + print(qc4.draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + ┌───┐ + q_0: ┤ Y ├──■────────────────── + ├───┤ │ ┌───┐┌─┐ + q_1: ┤ X ├──┼──────────┤ X ├┤M├ + └───┘ │ └─┬─┘└╥┘ + q_2: ───────┼────────────┼───╫─ + ┌─┴─┐┌─┐┌───┐ │ ║ + q_3: ─────┤ X ├┤M├┤ H ├──■───╫─ + └───┘└╥┘└───┘ ║ + c: 2/═══════════╩════════════╩═ + 1 1 You can also apply the gates from the smaller circuit before those of the bigger one setting the ``front`` argument to ``True``. -.. jupyter-execute:: +.. testcode:: qc5 = qc2.compose(qc1, front=True) - qc5.draw() + print(qc5.draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + ┌───┐ ┌───┐ + q_0: ┤ H ├──■──┤ Y ├───────■───── + └───┘┌─┴─┐└┬─┬┘┌───┐ │ + q_1: ─────┤ X ├─┤M├─┤ X ├──┼───── + └───┘ └╥┘ └───┘ │ + q_2: ────────────╫─────────┼───── + ║ ┌─┴─┐┌─┐ + q_3: ────────────╫───────┤ X ├┤M├ + ║ └───┘└╥┘ + c: 2/════════════╩═════════════╩═ + 0 1 :meth:`~.QuantumCircuit.append` ----------------------------------------------- @@ -64,17 +137,44 @@ In order to combine two circuits with :meth:`~.QuantumCircuit.append`, you have This method changes the circuit to which it is applied instead of returning another one. -.. jupyter-execute:: +.. testcode:: qc2.append(qc1, qargs=[3,1], cargs=[1]) qc2.draw(cregbundle=False) -Unlike :meth:`~.QuantumCircuit.compose`, :meth:`~.QuantumCircuit.append` turns the smaller circuit into a single :class:`~qiskit.circuit.Instruction`, so in order to unroll it you can use :meth:`~.QuantumCircuit.decompose` - -.. jupyter-execute:: +.. code-block:: text + + ┌───┐ + q_0: ┤ Y ├──■───────────────────── + ├───┤ │ ┌──────────────┐ + q_1: ┤ X ├──┼─────┤1 ├ + └───┘ │ │ │ + q_2: ───────┼─────┤ ├ + ┌─┴─┐┌─┐│ │ + q_3: ─────┤ X ├┤M├┤0 circuit-101 ├ + └───┘└╥┘│ │ + c_0: ═══════════╬═╡ ╞ + ║ │ │ + c_1: ═══════════╩═╡0 ╞ + └──────────────┘ - qc2.decompose().draw() +Unlike :meth:`~.QuantumCircuit.compose`, :meth:`~.QuantumCircuit.append` turns the smaller circuit into a single :class:`~qiskit.circuit.Instruction`, so in order to unroll it you can use :meth:`~.QuantumCircuit.decompose` +.. testcode:: + print(qc2.decompose().draw()) +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + ┌───────────────┐ + q_0: ┤ U3(π,π/2,π/2) ├──■────────────────── + └─┬───────────┬─┘ │ ┌───┐┌─┐ + q_1: ──┤ U3(π,0,π) ├────┼──────────┤ X ├┤M├ + └───────────┘ │ └─┬─┘└╥┘ + q_2: ───────────────────┼────────────┼───╫─ + ┌─┴─┐┌─┐┌───┐ │ ║ + q_3: ─────────────────┤ X ├┤M├┤ H ├──■───╫─ + └───┘└╥┘└───┘ ║ + c: 2/═══════════════════════╩════════════╩═ + 1 1 From 082b04e4c9cc161b167e33c45bf039ce57c4da04 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Tue, 28 Feb 2023 15:57:48 +0100 Subject: [PATCH 19/84] Removed jupyter-execute from visualize_a_quantum_circuit --- docs/how_to/visualize_a_quantum_circuit.rst | 60 ++++++++++++++++++--- 1 file changed, 54 insertions(+), 6 deletions(-) diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst index 7e7ea20ced03..74bea9d98387 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -9,7 +9,7 @@ Build the circuit The first step is to create the circuit. -.. jupyter-execute:: +.. testcode:: from qiskit import QuantumCircuit @@ -32,19 +32,44 @@ There are three different ways to visualize a circuit. You can use If you call the ``print()`` function on a :class:`~.QuantumCircuit` object, you will get an `ASCII art version `_ of the circuit diagram. -.. jupyter-execute:: +.. testcode:: print(qc) +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + ┌───┐ ┌─┐ + q_0: ┤ H ├──■──┤M├─── + ├───┤┌─┴─┐└╥┘┌─┐ + q_1: ┤ H ├┤ X ├─╫─┤M├ + ├───┤└┬─┬┘ ║ └╥┘ + q_2: ┤ H ├─┤M├──╫──╫─ + └───┘ └╥┘ ║ ║ + c: 3/═══════╩═══╩══╩═ + 2 0 1 + :meth:`~.QuantumCircuit.draw` --------------------------------------------- You can also call the :meth:`~.QuantumCircuit.draw` method on a :class:`~.QuantumCircuit` object to visualize it. If you don't specify any arguments you will get a plain text representation of the circuit. -.. jupyter-execute:: +.. code-block:: python qc.draw() +.. code-block:: text + + ┌───┐ ┌─┐ + q_0: ┤ H ├──■──┤M├─── + ├───┤┌─┴─┐└╥┘┌─┐ + q_1: ┤ H ├┤ X ├─╫─┤M├ + ├───┤└┬─┬┘ ║ └╥┘ + q_2: ┤ H ├─┤M├──╫──╫─ + └───┘ └╥┘ ║ ║ + c: 3/═══════╩═══╩══╩═ + 2 0 1 + However, if you change the ``output`` argument, you can get other different renderings. The available options for this argument are: * ``'text'``: renders the circuit with ASCII art. It's the default option. @@ -61,19 +86,32 @@ Because this optional or keyword argument is actually the first of this method, ``'mpl'`` ^^^^^^^^^ -.. jupyter-execute:: +.. code-block:: python qc.draw('mpl') +.. plot:: + + from qiskit import QuantumCircuit + + qc = QuantumCircuit(3, 3) + qc.h(range(3)) + qc.cx(0, 1) + qc.measure(range(3), range(3)) + qc.draw("mpl") ``'latex_source'`` ^^^^^^^^^^^^^^^^^^ -.. jupyter-execute:: +.. code-block:: python qc.draw('latex_source') +.. code-block:: text + + '\\documentclass[border=2px]{standalone}\n\n\\usepackage[braket, qm]{qcircuit}\n\\usepackage{graphicx}\n\n\\begin{document}\n\\scalebox{1.0}{\n\\Qcircuit @C=1.0em @R=0.2em @!R { \\\\\n\t \t\\nghost{{q}_{0} : } & \\lstick{{q}_{0} : } & \\gate{\\mathrm{H}} & \\ctrl{1} & \\meter & \\qw & \\qw & \\qw\\\\\n\t \t\\nghost{{q}_{1} : } & \\lstick{{q}_{1} : } & \\gate{\\mathrm{H}} & \\targ & \\qw & \\meter & \\qw & \\qw\\\\\n\t \t\\nghost{{q}_{2} : } & \\lstick{{q}_{2} : } & \\gate{\\mathrm{H}} & \\meter & \\qw & \\qw & \\qw & \\qw\\\\\n\t \t\\nghost{\\mathrm{{c} : }} & \\lstick{\\mathrm{{c} : }} & \\lstick{/_{_{3}}} \\cw & \\dstick{_{_{\\hspace{0.0em}2}}} \\cw \\ar @{<=} [-1,0] & \\dstick{_{_{\\hspace{0.0em}0}}} \\cw \\ar @{<=} [-3,0] & \\dstick{_{_{\\hspace{0.0em}1}}} \\cw \\ar @{<=} [-2,0] & \\cw & \\cw\\\\\n\\\\ }}\n\\end{document}' + :func:`~.circuit_drawer` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -84,9 +122,19 @@ If you prefer to use a self-contained function instead of a :class:`~.QuantumCir In Qiskit Terra :math:`\leq 0.7`, the default behavior for the :func:`~.circuit_drawer` function is to use the ``'latex'`` output backend, and in :math:`0.6.x` that includes a fallback to ``'mpl'`` if ``'latex'`` fails for any reason. Starting with release :math:`> 0.7`, the default changes to the ``'text'`` output. -.. jupyter-execute:: +.. code-block:: python from qiskit.visualization import circuit_drawer circuit_drawer(qc, output='mpl') +.. plot:: + + from qiskit import QuantumCircuit + from qiskit.visualization import circuit_drawer + + qc = QuantumCircuit(3, 3) + qc.h(range(3)) + qc.cx(0, 1) + qc.measure(range(3), range(3)) + circuit_drawer(qc, output='mpl') \ No newline at end of file From 205370c5ee7c520d1f07bd09c5e1d6ca15fabe05 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Tue, 28 Feb 2023 20:03:08 +0100 Subject: [PATCH 20/84] Add sphinx.ext.doctest to conf.py --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index 1d74bc42a14a..ceca2dad4c0a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,6 +34,7 @@ "sphinx.ext.viewcode", "sphinx.ext.extlinks", "sphinx.ext.intersphinx", + "sphinx.ext.doctest", "sphinx_autodoc_typehints", "reno.sphinxext", "sphinx_design", From 84f98cf819aff97704f1d546e93cb068944413db Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 1 Mar 2023 11:43:35 +0100 Subject: [PATCH 21/84] Change header symbol for index and visualization guide --- docs/how_to/index.rst | 4 ++-- docs/how_to/visualize_a_quantum_circuit.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how_to/index.rst b/docs/how_to/index.rst index 18c91b6f4425..4b663fb61322 100644 --- a/docs/how_to/index.rst +++ b/docs/how_to/index.rst @@ -1,8 +1,8 @@ .. _how_to: -====== +###### How to -====== +###### Create quantum circuits ----------------------- diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst index 74bea9d98387..142953ed019a 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -1,6 +1,6 @@ -=========================== +########################### Visualize a quantum circuit -=========================== +########################### This guide shows how to get a visual representation of a quantum circuit. From a6053bb0fcc4fab19f527663c3a6290734c14b77 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 1 Mar 2023 11:49:04 +0100 Subject: [PATCH 22/84] Added guides for sampler and estimator and simplified toctree --- docs/how_to/index.rst | 17 +++++-- docs/how_to/use_estimator.rst | 84 ++++++++++++++++++++++++++++++++ docs/how_to/use_sampler.rst | 90 +++++++++++++++++++++++++++++++++++ 3 files changed, 187 insertions(+), 4 deletions(-) create mode 100644 docs/how_to/use_estimator.rst create mode 100644 docs/how_to/use_sampler.rst diff --git a/docs/how_to/index.rst b/docs/how_to/index.rst index 4b663fb61322..13ccdf10b9c9 100644 --- a/docs/how_to/index.rst +++ b/docs/how_to/index.rst @@ -10,7 +10,16 @@ Create quantum circuits .. toctree:: :maxdepth: 1 - Create a quantum circuit - Compose quantum circuits - Visualize a quantum circuit - Create a parameterized circuit + create_a_quantum_circuit + compose_quantum_circuits + visualize_a_quantum_circuit + create_a_parameterized_circuit + +Use the primitives +------------------ + +.. toctree:: + :maxdepth: 1 + + use_sampler + use_estimator \ No newline at end of file diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst new file mode 100644 index 000000000000..66b6340ca7b3 --- /dev/null +++ b/docs/how_to/use_estimator.rst @@ -0,0 +1,84 @@ +########################### +Use the Estimator primitive +########################### + +This guide shows how to get the expected value of an observable for a given quantum circuit with the :class:`~qiskit.primitives.Estimator` primitive. + + +Initialize observable +===================== + +.. testcode:: + + from qiskit.quantum_info import SparsePauliOp + + obs = SparsePauliOp(["II", "XX", "YY", "ZZ"], [1, 1, -1, 1]) + +Initialize quantum circuits +=========================== + +The first step is 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:: + + from qiskit import QuantumCircuit + + qc = QuantumCircuit(2) + qc.h(0) + qc.cx(0,1) + +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, obs) + 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 `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 \ No newline at end of file diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst new file mode 100644 index 000000000000..6bdfcd3d6d8b --- /dev/null +++ b/docs/how_to/use_sampler.rst @@ -0,0 +1,90 @@ +######################### +Use the Sampler primitive +######################### + +This guide shows how to get the probability distribution of a quantum circuit with the :class:`~qiskit.primitives.Sampler` primitive. + +Initialize quantum circuits +=========================== + +The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` from which you want to obtain the probability distribution. + +.. plot:: + :include-source: + + from qiskit import QuantumCircuit + + qc = QuantumCircuit(2) + qc.h(0) + qc.cx(0,1) + qc.measure_all() + qc.draw("mpl") + +.. testsetup:: + + from qiskit import QuantumCircuit + + qc = QuantumCircuit(2) + qc.h(0) + qc.cx(0,1) + qc.measure_all() + +Initialize the ``Sampler`` +========================== + +Then, you need to create a :class:`~qiskit.primitives.Sampler` object. + +.. testcode:: + + from qiskit.primitives import Sampler + + sampler = Sampler() + +Run and get results +=================== + +Now that you have defined ``sampler``, you can create a :class:`~.PrimitiveJob` (subclass of :class:`~qiskit.providers.JobV1`) with the +:meth:`~qiskit.primitives.Sampler.run` method and, then, you can get the results (as a :class:`~qiskit.primitives.SamplerResult` object) with +the results with the :meth:`~qiskit.providers.JobV1.result` method. + +.. testcode:: + + job = sampler.run(qc) + result = job.result() + print(result) + +.. testoutput:: + + SamplerResult(quasi_dists=[{0: 0.4999999999999999, 3: 0.4999999999999999}], metadata=[{}]) + +Get the probability distribution +-------------------------------- + +From these results you can take the probability distributions with the attribute :attr:`~qiskit.primitives.SamplerResult.quasi_dists`. + +Even though there is only one circuit in this example, :attr:`~qiskit.primitives.SamplerResult.quasi_dists` returns a list of :class:`~qiskit.result.QuasiDistribution` s. +Generally ``result.quasi_dists[i]`` would be the quasi-probability distribution of the ``i``-th circuit. + +.. testcode:: + + quasi_dist = result.quasi_dists[0] + print(quasi_dist) + + +.. testoutput:: + + {0: 0.4999999999999999, 3: 0.4999999999999999} + +Probability distribution with binary outputs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you prefer to see the outputs as binary strings instead of decimal, you can use the +:meth:`~qiskit.result.QuasiDistribution.binary_probabilities` method. + +.. testcode:: + + print(quasi_dist.binary_probabilities()) + +.. testoutput:: + + {'00': 0.4999999999999999, '11': 0.4999999999999999} From 3ac6be16ff34e84d51958eb32c45de335fbe20e3 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 1 Mar 2023 12:38:21 +0100 Subject: [PATCH 23/84] Fixed underline --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 66b6340ca7b3..bbc2961eb6db 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -38,7 +38,7 @@ The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` for whic qc.cx(0,1) Initialize the ``Estimator`` -========================== +============================ Then, you need to create an :class:`~qiskit.primitives.Estimator` object. From 3b260e842c9eee78d8be227879846b9f6a42ca79 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 1 Mar 2023 13:38:23 +0100 Subject: [PATCH 24/84] Add links to how-to create circuit --- docs/how_to/use_estimator.rst | 6 +++++- docs/how_to/use_sampler.rst | 1 + 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index bbc2961eb6db..79948c83eb7b 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -8,6 +8,9 @@ This guide shows how to get the expected value of an observable for a given quan 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 @@ -17,7 +20,8 @@ Initialize observable Initialize quantum circuits =========================== -The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` for which you want to obtain the expected value. +Then you need to create the :class:`~qiskit.circuit.QuantumCircuit` for which you want to obtain the expected value. +For more details about this part check out :doc:`this guide `. .. plot:: :include-source: diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 6bdfcd3d6d8b..ce1a2a24b03f 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -8,6 +8,7 @@ Initialize quantum circuits =========================== The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` from which you want to obtain the probability distribution. +For more details about this part check out :doc:`this guide `. .. plot:: :include-source: From 5a3a74a768f43f0fb199d393b32378bfaec3ae10 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Fri, 3 Mar 2023 10:26:29 +0100 Subject: [PATCH 25/84] Added section about parameterized circuits to primitives how-tos --- docs/how_to/use_estimator.rst | 56 +++++++++++++++++++++++++++++++++-- docs/how_to/use_sampler.rst | 55 +++++++++++++++++++++++++++++++++- 2 files changed, 108 insertions(+), 3 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 79948c83eb7b..357aaef4e32a 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -8,7 +8,7 @@ This guide shows how to get the expected value of an observable for a given quan 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`. +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:: @@ -85,4 +85,56 @@ whose ``i``-th element would be the expectation value corresponding to the ``i`` .. testoutput:: - 3.999999999999999 \ No newline at end of file + 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 like in :doc:`this guide ` and follow the steps +of the previous example. + +.. testcode:: + + from qiskit.circuit import Parameter + + theta = Parameter('θ') + qc = QuantumCircuit(2) + qc.ry(theta, 0) + qc.cx(0,1) + print(qc.draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + ┌───────┐ + 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([qc]*3, [obs]*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:: + :options: +NORMALIZE_WHITESPACE + + Parameter: 0.00000 Expectation value: 2.0 + Parameter: 0.52360 Expectation value: 3.0 + Parameter: 1.57080 Expectation value: 4.0 + + diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index ce1a2a24b03f..cb668a7085fa 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -63,7 +63,7 @@ Get the probability distribution From these results you can take the probability distributions with the attribute :attr:`~qiskit.primitives.SamplerResult.quasi_dists`. -Even though there is only one circuit in this example, :attr:`~qiskit.primitives.SamplerResult.quasi_dists` returns a list of :class:`~qiskit.result.QuasiDistribution` s. +Even though there is only one circuit in this example, :attr:`~qiskit.primitives.SamplerResult.quasi_dists` returns a list of :class:`~qiskit.result.QuasiDistribution`\ s. Generally ``result.quasi_dists[i]`` would be the quasi-probability distribution of the ``i``-th circuit. .. testcode:: @@ -89,3 +89,56 @@ If you prefer to see the outputs as binary strings instead of decimal, you can u .. testoutput:: {'00': 0.4999999999999999, '11': 0.4999999999999999} + +Parameterized circuits with ``Sampler`` +========================================= + +The :class:`~qiskit.primitives.Sampler` 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 like in :doc:`this guide ` and follow the steps +of the previous example. + +.. testcode:: + + from qiskit.circuit import Parameter + + theta = Parameter('θ') + qc = QuantumCircuit(2) + qc.ry(theta, 0) + qc.cx(0,1) + qc.measure_all() + print(qc.draw()) + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + ┌───────┐ ░ ┌─┐ + q_0: ┤ Ry(θ) ├──■───░─┤M├─── + └───────┘┌─┴─┐ ░ └╥┘┌─┐ + q_1: ─────────┤ X ├─░──╫─┤M├ + └───┘ ░ ║ └╥┘ + meas: 2/══════════════════╩══╩═ + 0 1 + +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. + +.. testcode:: + + import numpy as np + + parameter_values = [[0], [np.pi/6], [np.pi/2]] + + job = sampler.run([qc]*3, parameter_values=parameter_values) + dists = job.result().quasi_dists + + for i in range(3): + print(f"Parameter: {parameter_values[i][0]:.5f}\t Probabilities: {dists[i]}") + +.. testoutput:: + :options: +NORMALIZE_WHITESPACE + + Parameter: 0.00000 Probabilities: {0: 1.0} + Parameter: 0.52360 Probabilities: {0: 0.9330127018922194, 3: 0.0669872981077807} + Parameter: 1.57080 Probabilities: {0: 0.5000000000000001, 3: 0.4999999999999999} From 5a308739606b8fd7fed101faf00588cdc63e1e21 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Fri, 3 Mar 2023 17:15:54 +0100 Subject: [PATCH 26/84] Remove other how-tos --- docs/how_to/compose_quantum_circuits.rst | 180 ------------------ .../how_to/create_a_parameterized_circuit.rst | 114 ----------- docs/how_to/create_a_quantum_circuit.rst | 167 ---------------- docs/how_to/index.rst | 10 - docs/how_to/visualize_a_quantum_circuit.rst | 140 -------------- 5 files changed, 611 deletions(-) delete mode 100644 docs/how_to/compose_quantum_circuits.rst delete mode 100644 docs/how_to/create_a_parameterized_circuit.rst delete mode 100644 docs/how_to/create_a_quantum_circuit.rst delete mode 100644 docs/how_to/visualize_a_quantum_circuit.rst diff --git a/docs/how_to/compose_quantum_circuits.rst b/docs/how_to/compose_quantum_circuits.rst deleted file mode 100644 index c5a01dbbc963..000000000000 --- a/docs/how_to/compose_quantum_circuits.rst +++ /dev/null @@ -1,180 +0,0 @@ -######################## -Compose quantum circuits -######################## - -This guide shows how to combine different :class:`~.QuantumCircuit` objects. - -Build the circuits -================== - -The first step is creating the circuits you want to combine. - -.. testcode:: - - from qiskit import QuantumCircuit - - qc1 = QuantumCircuit(2,1) - qc1.h(0) - qc1.cx(0,1) - qc1.measure(1,0) - - qc2 = QuantumCircuit(4,2) - qc2.y(0) - qc2.x(1) - qc2.cx(0,3) - qc2.measure(3,1) - - print(qc1.draw()) - print(qc2.draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - ┌───┐ - q_0: ┤ H ├──■───── - └───┘┌─┴─┐┌─┐ - q_1: ─────┤ X ├┤M├ - └───┘└╥┘ - c: 1/═══════════╩═ - 0 - ┌───┐ - q_0: ┤ Y ├──■───── - ├───┤ │ - q_1: ┤ X ├──┼───── - └───┘ │ - q_2: ───────┼───── - ┌─┴─┐┌─┐ - q_3: ─────┤ X ├┤M├ - └───┘└╥┘ - c: 2/═══════════╩═ - 1 - -Combine the circuits -==================== - -Now that you have built the circuits, they can be combined with two different methods: - -* :meth:`~.QuantumCircuit.compose` -* :meth:`~.QuantumCircuit.append` - -One detail these two methods have in common is that if the circuits have different sizes, they have to be applied to the one that has the most of both qubits and classical bits. - -:meth:`~.QuantumCircuit.compose` ------------------------------------------------- - -In order to combine two circuits with :meth:`~.QuantumCircuit.compose`, you only have to specify the circuit you want to insert. That way the qubits and bits of the smaller circuit will be included into the first qubits and bits of the bigger one in the original order they had. - -By default, :meth:`~.QuantumCircuit.compose` does not change the circuit to which it is applied but returns the composed circuit. This can be changed by setting the ``inplace`` argument to ``True``. - -.. testcode:: - - qc3 = qc2.compose(qc1) - print(qc3.draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - ┌───┐ ┌───┐ - q_0: ┤ Y ├──■──┤ H ├──■───── - ├───┤ │ └───┘┌─┴─┐┌─┐ - q_1: ┤ X ├──┼───────┤ X ├┤M├ - └───┘ │ └───┘└╥┘ - q_2: ───────┼─────────────╫─ - ┌─┴─┐ ┌─┐ ║ - q_3: ─────┤ X ├─┤M├───────╫─ - └───┘ └╥┘ ║ - c: 2/════════════╩════════╩═ - 1 0 - -If you want to insert the qubits and bits into specific positions in the bigger circuit, you can use the ``qubits`` and ``bits`` arguments. - -.. testcode:: - - qc4 = qc2.compose(qc1, qubits=[3,1], clbits=[1]) - print(qc4.draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - ┌───┐ - q_0: ┤ Y ├──■────────────────── - ├───┤ │ ┌───┐┌─┐ - q_1: ┤ X ├──┼──────────┤ X ├┤M├ - └───┘ │ └─┬─┘└╥┘ - q_2: ───────┼────────────┼───╫─ - ┌─┴─┐┌─┐┌───┐ │ ║ - q_3: ─────┤ X ├┤M├┤ H ├──■───╫─ - └───┘└╥┘└───┘ ║ - c: 2/═══════════╩════════════╩═ - 1 1 - -You can also apply the gates from the smaller circuit before those of the bigger one setting the ``front`` argument to ``True``. - -.. testcode:: - - qc5 = qc2.compose(qc1, front=True) - print(qc5.draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - ┌───┐ ┌───┐ - q_0: ┤ H ├──■──┤ Y ├───────■───── - └───┘┌─┴─┐└┬─┬┘┌───┐ │ - q_1: ─────┤ X ├─┤M├─┤ X ├──┼───── - └───┘ └╥┘ └───┘ │ - q_2: ────────────╫─────────┼───── - ║ ┌─┴─┐┌─┐ - q_3: ────────────╫───────┤ X ├┤M├ - ║ └───┘└╥┘ - c: 2/════════════╩═════════════╩═ - 0 1 - -:meth:`~.QuantumCircuit.append` ------------------------------------------------ - -In order to combine two circuits with :meth:`~.QuantumCircuit.append`, you have to specify the circuit you want to add and the qubits and classical bits (if there are any) into which you want the circuit to be inserted. - -This method changes the circuit to which it is applied instead of returning another one. - -.. testcode:: - - qc2.append(qc1, qargs=[3,1], cargs=[1]) - qc2.draw(cregbundle=False) - -.. code-block:: text - - ┌───┐ - q_0: ┤ Y ├──■───────────────────── - ├───┤ │ ┌──────────────┐ - q_1: ┤ X ├──┼─────┤1 ├ - └───┘ │ │ │ - q_2: ───────┼─────┤ ├ - ┌─┴─┐┌─┐│ │ - q_3: ─────┤ X ├┤M├┤0 circuit-101 ├ - └───┘└╥┘│ │ - c_0: ═══════════╬═╡ ╞ - ║ │ │ - c_1: ═══════════╩═╡0 ╞ - └──────────────┘ - -Unlike :meth:`~.QuantumCircuit.compose`, :meth:`~.QuantumCircuit.append` turns the smaller circuit into a single :class:`~qiskit.circuit.Instruction`, so in order to unroll it you can use :meth:`~.QuantumCircuit.decompose` - -.. testcode:: - - print(qc2.decompose().draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - ┌───────────────┐ - q_0: ┤ U3(π,π/2,π/2) ├──■────────────────── - └─┬───────────┬─┘ │ ┌───┐┌─┐ - q_1: ──┤ U3(π,0,π) ├────┼──────────┤ X ├┤M├ - └───────────┘ │ └─┬─┘└╥┘ - q_2: ───────────────────┼────────────┼───╫─ - ┌─┴─┐┌─┐┌───┐ │ ║ - q_3: ─────────────────┤ X ├┤M├┤ H ├──■───╫─ - └───┘└╥┘└───┘ ║ - c: 2/═══════════════════════╩════════════╩═ - 1 1 diff --git a/docs/how_to/create_a_parameterized_circuit.rst b/docs/how_to/create_a_parameterized_circuit.rst deleted file mode 100644 index 7568ed631861..000000000000 --- a/docs/how_to/create_a_parameterized_circuit.rst +++ /dev/null @@ -1,114 +0,0 @@ -############################## -Create a parameterized circuit -############################## - -This guide will show how to create a :class:`~.QuantumCircuit` that includes parameters. - -Define the parameters -===================== - -In order to define a parameter, you need to create a :class:`~.Parameter` object. To do that you only need to choose a ``name``, that can be any unicode string like ``'θ'``. - -.. testcode:: - - from qiskit.circuit import Parameter - - theta = Parameter('θ') - - -Create the parameterized circuit -================================ - -When creating the circuit you can include the :class:`~.Parameter` as if it was a defined number. - -.. testcode:: - - from qiskit import QuantumCircuit - - qc = QuantumCircuit(1) - qc.rx(theta, 0) - print(qc.draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - ┌───────┐ - q: ┤ Rx(θ) ├ - └───────┘ - - -Assign values to parameters -=========================== - -You can use these two methods to assign values to the :class:`~.Parameter`\ s in your circuit: - -* :meth:`~.QuantumCircuit.bind_parameters` -* :meth:`~.QuantumCircuit.assign_parameters` - -:meth:`~.QuantumCircuit.bind_parameters` --------------------------------------------------------- - -In order to use this method, you have to specify either a dictionary of the form ``{parameter: value,...}`` or an iterable formed only by numeric values, that will be assigned following the order from :attr:`~.QuantumCircuit.parameters`. - -.. testcode:: - - import numpy as np - - theta_values = [0, np.pi/2, np.pi] - qc_bind_list = [qc.bind_parameters({theta: theta_value}) for theta_value in theta_values] - - for i in range(3): - print(qc_bind_list[i].draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - ┌───────┐ - q: ┤ Rx(0) ├ - └───────┘ - ┌─────────┐ - q: ┤ Rx(π/2) ├ - └─────────┘ - ┌───────┐ - q: ┤ Rx(π) ├ - └───────┘ - -:meth:`~.QuantumCircuit.assign_parameters` ----------------------------------------------------------- - -This method works identically like :meth:`~.QuantumCircuit.bind_parameters` except that you can also assign other :class:`~.Parameter` objects instead of only numbers to the :class:`~.Parameter`\ s in your circuit. - -.. testcode:: - - phi = Parameter('ϕ') - - theta_values = [np.pi/2, phi] - qc_assign_list = [qc.assign_parameters({theta: theta_value}) for theta_value in theta_values] - - for i in range(2): - print(qc_assign_list[i].draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - ┌─────────┐ - q: ┤ Rx(π/2) ├ - └─────────┘ - ┌───────┐ - q: ┤ Rx(ϕ) ├ - └───────┘ - - -Another difference between :meth:`~.QuantumCircuit.bind_parameters` and :meth:`~.QuantumCircuit.assign_parameters` is that for the latter, you can make it change your original circuit instead of creating a new one by setting the ``inplace`` argument to ``True``. - -.. testcode:: - - qc.assign_parameters({theta: np.pi/4}, inplace=True) - print(qc.draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - ┌─────────┐ - q: ┤ Rx(π/4) ├ - └─────────┘ \ No newline at end of file diff --git a/docs/how_to/create_a_quantum_circuit.rst b/docs/how_to/create_a_quantum_circuit.rst deleted file mode 100644 index 700ea07e74a7..000000000000 --- a/docs/how_to/create_a_quantum_circuit.rst +++ /dev/null @@ -1,167 +0,0 @@ - -######################## -Create a quantum circuit -######################## - -This guide shows how to initialize a quantum circuit. - -There are two ways to create a :class:`~.QuantumCircuit` object: - -* Specifying the number of qubits and bits. -* Creating :class:`~.QuantumRegister`\ s and :class:`~.ClassicalRegister`\ s. - -Create from number of qubits and bits -===================================== - -In order to create a :class:`~.QuantumCircuit` by only specifying the number of bits and qubits, you need to follow these steps. - -.. testcode:: - - from qiskit import QuantumCircuit - - # Initialize number of qubits and classical bits - n_qubits = 3 - n_bits = 2 - - # Create the circuit - qc = QuantumCircuit(n_qubits, n_bits) - print(qc.draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - q_0: - - q_1: - - q_2: - - c: 2/ - - -If you don't want to include any classical bits, you don't have to write `QuantumCircuit(n_qubits,0)` but you can omit the number of classical bits. - -.. testcode:: - - from qiskit import QuantumCircuit - - qc = QuantumCircuit(n_qubits) - print(qc.draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - q_0: - - q_1: - - q_2: - -Create from quantum and classical registers -=========================================== - -Create quantum registers ------------------------- - -In order to create a quantum register, you have to define a :class:`~.QuantumRegister` object, passing as argument the desired number of qubits. - -.. testcode:: - - from qiskit import QuantumRegister - - # Create QuantumRegister formed by 2 qubits - qr1 = QuantumRegister(2) - - # Create QuantumRegister formed by 3 qubits - qr2 = QuantumRegister(3) - -Create classical registers --------------------------- - -Analogously to the quantum registers, a classical register can be created by defining a :class:`~.ClassicalRegister` object, passing the number of classical bits as an argument. - -.. testcode:: - - from qiskit import ClassicalRegister - - # Create classical register with 2 classical bits - cr1 = ClassicalRegister(2) - - # Create classical register with 1 classical bit - cr2 = ClassicalRegister(1) - -Initialize the quantum circuit ------------------------------- - -Now that you have defined the quantum and classical registers, you can define a :class:`~.QuantumCircuit` from them. Each register has to be introduced as a separate argument. - -.. testcode:: - - # Create the quantum circuit from the registers - qc = QuantumCircuit(qr1, qr2, cr1, cr2) - print(qc.draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - q0_0: - - q0_1: - - q1_0: - - q1_1: - - q1_2: - - c0: 2/ - - c1: 1/ - - -You can put the registers in any order, even mixing classical and quantum. However, the relative order of the :class:`~.QuantumRegister`\ s does affect the order of the qubits on the final circuit. In particular, the qubits from the first :class:`~.QuantumRegister` will be the first and so on. The same applies to the :class:`~.ClassicalRegister`\ s. - -.. testcode:: - - # Both the classical and quantum registers have the same relative order as in qc - qc1 = QuantumCircuit(qr1, cr1, qr2, cr2) - - print(qc == qc1) - -.. testoutput:: - - True - -.. testcode:: - - # We change the order of the quantum registers - qc2 = QuantumCircuit(qr2, qr1, cr1, cr2) - - print(qc == qc2) - -.. testoutput:: - - False - - -.. testcode:: - - print(qc2.draw()) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - q1_0: - - q1_1: - - q1_2: - - q0_0: - - q0_1: - - c0: 2/ - - c1: 1/ - diff --git a/docs/how_to/index.rst b/docs/how_to/index.rst index 13ccdf10b9c9..d3a79e9ce4d9 100644 --- a/docs/how_to/index.rst +++ b/docs/how_to/index.rst @@ -4,16 +4,6 @@ How to ###### -Create quantum circuits ------------------------ - -.. toctree:: - :maxdepth: 1 - - create_a_quantum_circuit - compose_quantum_circuits - visualize_a_quantum_circuit - create_a_parameterized_circuit Use the primitives ------------------ diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst deleted file mode 100644 index 142953ed019a..000000000000 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ /dev/null @@ -1,140 +0,0 @@ -########################### -Visualize a quantum circuit -########################### - -This guide shows how to get a visual representation of a quantum circuit. - -Build the circuit -================= - -The first step is to create the circuit. - -.. testcode:: - - from qiskit import QuantumCircuit - - qc = QuantumCircuit(3, 3) - qc.h(range(3)) - qc.cx(0, 1) - qc.measure(range(3), range(3)) - -Visualize the circuit -===================== - -There are three different ways to visualize a circuit. You can use - -* The ``print()`` function. -* The :meth:`~.QuantumCircuit.draw` method. -* The :func:`~.circuit_drawer` function. - -``print()`` ------------ - -If you call the ``print()`` function on a :class:`~.QuantumCircuit` object, you will get an `ASCII art version `_ of the circuit diagram. - -.. testcode:: - - print(qc) - -.. testoutput:: - :options: +NORMALIZE_WHITESPACE - - ┌───┐ ┌─┐ - q_0: ┤ H ├──■──┤M├─── - ├───┤┌─┴─┐└╥┘┌─┐ - q_1: ┤ H ├┤ X ├─╫─┤M├ - ├───┤└┬─┬┘ ║ └╥┘ - q_2: ┤ H ├─┤M├──╫──╫─ - └───┘ └╥┘ ║ ║ - c: 3/═══════╩═══╩══╩═ - 2 0 1 - -:meth:`~.QuantumCircuit.draw` ---------------------------------------------- - -You can also call the :meth:`~.QuantumCircuit.draw` method on a :class:`~.QuantumCircuit` object to visualize it. If you don't specify any arguments you will get a plain text representation of the circuit. - -.. code-block:: python - - qc.draw() - -.. code-block:: text - - ┌───┐ ┌─┐ - q_0: ┤ H ├──■──┤M├─── - ├───┤┌─┴─┐└╥┘┌─┐ - q_1: ┤ H ├┤ X ├─╫─┤M├ - ├───┤└┬─┬┘ ║ └╥┘ - q_2: ┤ H ├─┤M├──╫──╫─ - └───┘ └╥┘ ║ ║ - c: 3/═══════╩═══╩══╩═ - 2 0 1 - -However, if you change the ``output`` argument, you can get other different renderings. The available options for this argument are: - -* ``'text'``: renders the circuit with ASCII art. It's the default option. -* ``'mpl'``: uses `matplotlib `_ to render the circuit. -* ``'latex'``: uses :math:`\LaTeX` to render the circuit. It requires a full `LaTeX `_ distribution and the package ``pdflatex``. -* ``'latex_source'``: outputs the :math:`\LaTeX` source code that creates the ``'latex'`` rendering of the circuit. - -Because this optional or keyword argument is actually the first of this method, one can type ``qc.draw(option)`` instead of ``qc.draw(output=option)``. - -.. note:: - By default, the :meth:`~.QuantumCircuit.draw` method returns the rendered image as an object and does not output anything. The exact class returned depends on the output specified: ``'text'`` (the default) returns a ``TextDrawer`` object, ``'mpl'`` returns a `matplotlib.figure.Figure `_ object, and ``'latex'`` returns a ``PIL.Image`` object. Having the return types enables modifying or directly interacting with the rendered output from the drawers. Jupyter notebooks understand these return types and render them for us in this guide, but when running outside of Jupyter, you do not have this feature automatically. However, the :meth:`~.QuantumCircuit.draw` method has optional arguments to display or save the output. When specified, the ``filename`` kwarg takes a path to which it saves the rendered output. Alternatively, if you're using the ``'mpl'`` or ``'latex'`` outputs, you can leverage the ``interactive`` kwarg to open the image in a new window (this will not always work from within a notebook). - - -``'mpl'`` -^^^^^^^^^ - -.. code-block:: python - - qc.draw('mpl') - -.. plot:: - - from qiskit import QuantumCircuit - - qc = QuantumCircuit(3, 3) - qc.h(range(3)) - qc.cx(0, 1) - qc.measure(range(3), range(3)) - qc.draw("mpl") - - -``'latex_source'`` -^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - qc.draw('latex_source') - -.. code-block:: text - - '\\documentclass[border=2px]{standalone}\n\n\\usepackage[braket, qm]{qcircuit}\n\\usepackage{graphicx}\n\n\\begin{document}\n\\scalebox{1.0}{\n\\Qcircuit @C=1.0em @R=0.2em @!R { \\\\\n\t \t\\nghost{{q}_{0} : } & \\lstick{{q}_{0} : } & \\gate{\\mathrm{H}} & \\ctrl{1} & \\meter & \\qw & \\qw & \\qw\\\\\n\t \t\\nghost{{q}_{1} : } & \\lstick{{q}_{1} : } & \\gate{\\mathrm{H}} & \\targ & \\qw & \\meter & \\qw & \\qw\\\\\n\t \t\\nghost{{q}_{2} : } & \\lstick{{q}_{2} : } & \\gate{\\mathrm{H}} & \\meter & \\qw & \\qw & \\qw & \\qw\\\\\n\t \t\\nghost{\\mathrm{{c} : }} & \\lstick{\\mathrm{{c} : }} & \\lstick{/_{_{3}}} \\cw & \\dstick{_{_{\\hspace{0.0em}2}}} \\cw \\ar @{<=} [-1,0] & \\dstick{_{_{\\hspace{0.0em}0}}} \\cw \\ar @{<=} [-3,0] & \\dstick{_{_{\\hspace{0.0em}1}}} \\cw \\ar @{<=} [-2,0] & \\cw & \\cw\\\\\n\\\\ }}\n\\end{document}' - - -:func:`~.circuit_drawer` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you prefer to use a self-contained function instead of a :class:`~.QuantumCircuit` method to draw your circuit, you can do it with :func:`~.circuit_drawer` from :mod:`qiskit.visualization`. It has the exact same behavior as the :meth:`~.QuantumCircuit.draw` method above, except that it requires the circuit to be included as an argument. - -.. note:: - In Qiskit Terra :math:`\leq 0.7`, the default behavior for the :func:`~.circuit_drawer` function is to use the ``'latex'`` output backend, and in :math:`0.6.x` that includes a fallback to ``'mpl'`` if ``'latex'`` fails for any reason. Starting with release :math:`> 0.7`, the default changes to the ``'text'`` output. - - -.. code-block:: python - - from qiskit.visualization import circuit_drawer - - circuit_drawer(qc, output='mpl') - -.. plot:: - - from qiskit import QuantumCircuit - from qiskit.visualization import circuit_drawer - - qc = QuantumCircuit(3, 3) - qc.h(range(3)) - qc.cx(0, 1) - qc.measure(range(3), range(3)) - circuit_drawer(qc, output='mpl') \ No newline at end of file From 54071ee3ba2e6b8ef12ec515ceb0ad9cc86ac3be Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Fri, 3 Mar 2023 17:19:28 +0100 Subject: [PATCH 27/84] Remove links --- docs/how_to/use_estimator.rst | 3 +-- docs/how_to/use_sampler.rst | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 357aaef4e32a..e956f7119cff 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -21,7 +21,6 @@ Initialize quantum circuits =========================== Then you need to create the :class:`~qiskit.circuit.QuantumCircuit` for which you want to obtain the expected value. -For more details about this part check out :doc:`this guide `. .. plot:: :include-source: @@ -91,7 +90,7 @@ 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 like in :doc:`this guide ` and follow the steps +You can also bind values to the parameters of the circuit and follow the steps of the previous example. .. testcode:: diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index cb668a7085fa..eecdae3204c1 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -8,7 +8,6 @@ Initialize quantum circuits =========================== The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` from which you want to obtain the probability distribution. -For more details about this part check out :doc:`this guide `. .. plot:: :include-source: @@ -94,7 +93,7 @@ Parameterized circuits with ``Sampler`` ========================================= The :class:`~qiskit.primitives.Sampler` 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 like in :doc:`this guide ` and follow the steps +You can also bind values to the parameters of the circuit and follow the steps of the previous example. .. testcode:: From 89da1acd11e77a171b81847311269d46d33266c8 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Mon, 6 Mar 2023 13:07:54 +0100 Subject: [PATCH 28/84] Added reference to other implementations of primitives --- docs/conf.py | 3 +++ docs/how_to/use_estimator.rst | 6 ++++++ docs/how_to/use_sampler.rst | 6 ++++++ 3 files changed, 15 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index ceca2dad4c0a..026e2811198a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -64,6 +64,9 @@ intersphinx_mapping = { "retworkx": ("https://qiskit.org/documentation/retworkx/", None), + "qiskit-ibm-runtime": ("https://qiskit.org/documentation/partners/qiskit_ibm_runtime/", None), + "qiskit": ("https://qiskit.org/documentation/", None), + # qiskit included because there isn't a separate page for aer. } # -- Options for HTML output ------------------------------------------------- diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index e956f7119cff..ea4670b09e82 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -4,6 +4,12 @@ Use the Estimator primitive 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 ===================== diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index eecdae3204c1..01ef48c02e2a 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -4,6 +4,12 @@ Use the Sampler primitive This guide shows how to get the probability distribution of a quantum circuit with the :class:`~qiskit.primitives.Sampler` primitive. +.. note:: + + While this guide only uses Qiskit Terra's implementation of the ``Sampler`` primitive, there are other + implementations of this primitive like Qiskit Terra's :class:`~qiskit.primitives.BackendSampler`, Qiskit Aer's :class:`~qiskit_aer.primitives.Sampler` + and Qiskit Runtime's :class:`~qiskit_ibm_runtime.Sampler`. + Initialize quantum circuits =========================== From 130f5ac0d19fb97c7f36f48212c6566253bb8a41 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 7 Mar 2023 17:49:10 +0100 Subject: [PATCH 29/84] Update docs/how_to/use_estimator.rst Co-authored-by: Steve Wood <40241007+woodsp-ibm@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index ea4670b09e82..d7c1f6622ea8 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -21,7 +21,7 @@ Among them it is preferable to use :class:`~qiskit.quantum_info.SparsePauliOp`. from qiskit.quantum_info import SparsePauliOp - obs = SparsePauliOp(["II", "XX", "YY", "ZZ"], [1, 1, -1, 1]) + obs = SparsePauliOp(["II", "XX", "YY", "ZZ"], coeffs=[1, 1, -1, 1]) Initialize quantum circuits =========================== From 8f83d185ea6b63b67aad884f51d38516642cd6fe Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Thu, 9 Mar 2023 10:28:55 +0100 Subject: [PATCH 30/84] Improved titles --- docs/how_to/use_estimator.rst | 6 +++--- docs/how_to/use_sampler.rst | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index d7c1f6622ea8..4513b20432af 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -1,6 +1,6 @@ -########################### -Use the Estimator primitive -########################### +############################################### +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. diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 01ef48c02e2a..f281bc615abe 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -1,6 +1,6 @@ -######################### -Use the Sampler primitive -######################### +##################################################### +Compute circuit output probabilities with ``Sampler`` +##################################################### This guide shows how to get the probability distribution of a quantum circuit with the :class:`~qiskit.primitives.Sampler` primitive. From 6daed2ffcc26bce0c75c58c528294ac43c2fcdfe Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Thu, 9 Mar 2023 12:06:47 +0100 Subject: [PATCH 31/84] set global doctest flags and disable automatic doctests --- docs/conf.py | 15 +++++++++++++++ docs/how_to/use_estimator.rst | 2 -- docs/how_to/use_sampler.rst | 2 -- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 026e2811198a..bf8fcf93de99 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -92,3 +92,18 @@ autosummary_generate = True autosummary_generate_overwrite = False 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 = "" \ No newline at end of file diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 4513b20432af..c50dedd2454b 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -110,7 +110,6 @@ of the previous example. print(qc.draw()) .. testoutput:: - :options: +NORMALIZE_WHITESPACE ┌───────┐ q_0: ┤ Ry(θ) ├──■── @@ -136,7 +135,6 @@ that corresponds to the ``i``-th circuit and observable. print(f"Parameter: {parameter_values[i][0]:.5f}\t Expectation value: {values[i]}") .. testoutput:: - :options: +NORMALIZE_WHITESPACE Parameter: 0.00000 Expectation value: 2.0 Parameter: 0.52360 Expectation value: 3.0 diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index f281bc615abe..e3fe31855f67 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -114,7 +114,6 @@ of the previous example. print(qc.draw()) .. testoutput:: - :options: +NORMALIZE_WHITESPACE ┌───────┐ ░ ┌─┐ q_0: ┤ Ry(θ) ├──■───░─┤M├─── @@ -142,7 +141,6 @@ that corresponds to the ``i``-th circuit. print(f"Parameter: {parameter_values[i][0]:.5f}\t Probabilities: {dists[i]}") .. testoutput:: - :options: +NORMALIZE_WHITESPACE Parameter: 0.00000 Probabilities: {0: 1.0} Parameter: 0.52360 Probabilities: {0: 0.9330127018922194, 3: 0.0669872981077807} From ffbc8ded818d9249c64c164b5ec0f63d79d569e1 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Thu, 9 Mar 2023 20:05:38 +0100 Subject: [PATCH 32/84] Added part about changing options --- docs/how_to/use_estimator.rst | 120 ++++++++++++++++++++++++++++++++-- docs/how_to/use_sampler.rst | 99 ++++++++++++++++++++++++++-- 2 files changed, 206 insertions(+), 13 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index c50dedd2454b..13bb271f610a 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -21,7 +21,7 @@ Among them it is preferable to use :class:`~qiskit.quantum_info.SparsePauliOp`. from qiskit.quantum_info import SparsePauliOp - obs = SparsePauliOp(["II", "XX", "YY", "ZZ"], coeffs=[1, 1, -1, 1]) + observable = SparsePauliOp(["II", "XX", "YY", "ZZ"], coeffs=[1, 1, -1, 1]) Initialize quantum circuits =========================== @@ -66,7 +66,7 @@ the results with the :meth:`~qiskit.providers.JobV1.result` method. .. testcode:: - job = estimator.run(qc, obs) + job = estimator.run(qc, observable) result = job.result() print(result) @@ -104,10 +104,10 @@ of the previous example. from qiskit.circuit import Parameter theta = Parameter('θ') - qc = QuantumCircuit(2) - qc.ry(theta, 0) - qc.cx(0,1) - print(qc.draw()) + param_qc = QuantumCircuit(2) + param_qc.ry(theta, 0) + param_qc.cx(0,1) + print(param_qc.draw()) .. testoutput:: @@ -128,7 +128,7 @@ that corresponds to the ``i``-th circuit and observable. parameter_values = [[0], [np.pi/6], [np.pi/2]] - job = estimator.run([qc]*3, [obs]*3, parameter_values=parameter_values) + job = estimator.run([param_qc]*3, [observable]*3, parameter_values=parameter_values) values = job.result().values for i in range(3): @@ -140,4 +140,110 @@ that corresponds to the ``i``-th circuit and observable. 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 \ No newline at end of file diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index e3fe31855f67..c9d1c8883bbd 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -95,6 +95,8 @@ If you prefer to see the outputs as binary strings instead of decimal, you can u {'00': 0.4999999999999999, '11': 0.4999999999999999} + + Parameterized circuits with ``Sampler`` ========================================= @@ -107,11 +109,11 @@ of the previous example. from qiskit.circuit import Parameter theta = Parameter('θ') - qc = QuantumCircuit(2) - qc.ry(theta, 0) - qc.cx(0,1) - qc.measure_all() - print(qc.draw()) + param_qc = QuantumCircuit(2) + param_qc.ry(theta, 0) + param_qc.cx(0,1) + param_qc.measure_all() + print(param_qc.draw()) .. testoutput:: @@ -134,7 +136,7 @@ that corresponds to the ``i``-th circuit. parameter_values = [[0], [np.pi/6], [np.pi/2]] - job = sampler.run([qc]*3, parameter_values=parameter_values) + job = sampler.run([param_qc]*3, parameter_values=parameter_values) dists = job.result().quasi_dists for i in range(3): @@ -145,3 +147,88 @@ that corresponds to the ``i``-th circuit. Parameter: 0.00000 Probabilities: {0: 1.0} Parameter: 0.52360 Probabilities: {0: 0.9330127018922194, 3: 0.0669872981077807} Parameter: 1.57080 Probabilities: {0: 0.5000000000000001, 3: 0.4999999999999999} + +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.Sampler` +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.Sampler.run` method. +* Modify :class:`~qiskit.primitives.Sampler` options. + +Set keyword arguments for :meth:`~qiskit.primitives.Sampler.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.Sampler.run` method. You can do this by +passing them as keyword arguments. + +.. testcode:: + + job = sampler.run(qc, shots=2048, seed=123) + result = job.result() + print(result) + +.. testoutput:: + + SamplerResult(quasi_dists=[{0: 0.5205078125, 3: 0.4794921875}], metadata=[{'shots': 2048}]) + +Change :class:`~qiskit.primitives.Sampler` options +--------------------------------------------------- + +If you want to keep some configuration values for several runs, it can be better to +change the :class:`~qiskit.primitives.Sampler` options. That way you can use the same +:class:`~qiskit.primitives.Sampler` object as many times as you wish without having to +rewrite the configuration values every time you use :meth:`~qiskit.primitives.Sampler.run`. + +Modify existing :class:`~qiskit.primitives.Sampler` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you prefer to change the options of an already-defined :class:`~qiskit.primitives.Sampler`, you can use +:meth:`~qiskit.primitives.Sampler.set_options` and introduce the new options as keyword arguments. + +.. testcode:: + + sampler.set_options(shots=2048, seed=123) + + job = sampler.run(qc) + result = job.result() + print(result) + +.. testoutput:: + + SamplerResult(quasi_dists=[{0: 0.5205078125, 3: 0.4794921875}], metadata=[{'shots': 2048}]) + + + +Define a new :class:`~qiskit.primitives.Sampler` with the options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you prefer to define a new :class:`~qiskit.primitives.Sampler` 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.Sampler` with the +``options`` argument. + +.. testcode:: + + sampler = Sampler(options=options) + + job = sampler.run(qc) + result = job.result() + print(result) + +.. testoutput:: + + SamplerResult(quasi_dists=[{0: 0.5205078125, 3: 0.4794921875}], metadata=[{'shots': 2048}]) \ No newline at end of file From 8fc6f307ee284bf104dfb2fd96404f28ce5e7c37 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Fri, 10 Mar 2023 18:53:37 +0100 Subject: [PATCH 33/84] Add new aer docs page to intersphinx --- docs/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e52c281ffe81..2db02f359a46 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -65,8 +65,7 @@ intersphinx_mapping = { "retworkx": ("https://qiskit.org/documentation/retworkx/", None), "qiskit-ibm-runtime": ("https://qiskit.org/documentation/partners/qiskit_ibm_runtime/", None), - "qiskit": ("https://qiskit.org/documentation/", None), - # qiskit included because there isn't a separate page for aer. + "qiskit-aer": ("https://qiskit.org/documentation/aer/", None) } # -- Options for HTML output ------------------------------------------------- From e9f7924808ad46f7b0431023de0829ff9e9fb5b7 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Thu, 23 Mar 2023 16:19:14 +0100 Subject: [PATCH 34/84] Added notes about circuit measurements --- docs/how_to/use_estimator.rst | 4 ++++ docs/how_to/use_sampler.rst | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 13bb271f610a..30536910c489 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -46,6 +46,10 @@ Then you need to create the :class:`~qiskit.circuit.QuantumCircuit` for which yo qc.h(0) qc.cx(0,1) +.. note:: + + The :class:`~qiskit.circuit.QuantumCircuit` can't include any measurements. + Initialize the ``Estimator`` ============================ diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index c9d1c8883bbd..1fd1946a6180 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -35,6 +35,10 @@ The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` from whi qc.cx(0,1) qc.measure_all() +.. note:: + + The :class:`~qiskit.circuit.QuantumCircuit` has to include measurements. + Initialize the ``Sampler`` ========================== From cdf67452079cb67d3dc485a44f10c3a6657b66dc Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Thu, 23 Mar 2023 16:55:28 +0100 Subject: [PATCH 35/84] Improved notes about circuit measurements --- docs/how_to/use_estimator.rst | 2 +- docs/how_to/use_sampler.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 30536910c489..857d6ad03e71 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -48,7 +48,7 @@ Then you need to create the :class:`~qiskit.circuit.QuantumCircuit` for which yo .. note:: - The :class:`~qiskit.circuit.QuantumCircuit` can't include any measurements. + The :class:`~qiskit.circuit.QuantumCircuit` you pass to :class:`~qiskit.primitives.Estimator` must not include any measurements. Initialize the ``Estimator`` ============================ diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 1fd1946a6180..0d9912ee5fc5 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -37,7 +37,7 @@ The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` from whi .. note:: - The :class:`~qiskit.circuit.QuantumCircuit` has to include measurements. + The :class:`~qiskit.circuit.QuantumCircuit` you pass to :class:`~qiskit.primitives.Sampler` has to include measurements. Initialize the ``Sampler`` ========================== From 6f837ccd891cbb4cf8cf77721c6cda4d720ae2a3 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Thu, 30 Mar 2023 15:31:49 +0200 Subject: [PATCH 36/84] Update docs/how_to/use_estimator.rst Co-authored-by: Junye Huang --- docs/how_to/use_estimator.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 857d6ad03e71..b903578db5a8 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -91,7 +91,6 @@ whose ``i``-th element would be the expectation value corresponding to the ``i`` exp_value = result.values[0] print(exp_value) - .. testoutput:: 3.999999999999999 From 9ad583a3a4eba29e85da0a1059809a2e8b1c6e4a Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Thu, 30 Mar 2023 15:31:59 +0200 Subject: [PATCH 37/84] Update docs/how_to/use_sampler.rst Co-authored-by: Junye Huang --- docs/how_to/use_sampler.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 0d9912ee5fc5..0e8c99e892fc 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -80,7 +80,6 @@ Generally ``result.quasi_dists[i]`` would be the quasi-probability distribution quasi_dist = result.quasi_dists[0] print(quasi_dist) - .. testoutput:: {0: 0.4999999999999999, 3: 0.4999999999999999} From 1dc2ef7e62628286699629cf6e50f3024f91600e Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Thu, 30 Mar 2023 15:32:09 +0200 Subject: [PATCH 38/84] Update docs/how_to/use_sampler.rst Co-authored-by: Junye Huang --- docs/how_to/use_sampler.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 0e8c99e892fc..9817d0a78697 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -98,8 +98,6 @@ If you prefer to see the outputs as binary strings instead of decimal, you can u {'00': 0.4999999999999999, '11': 0.4999999999999999} - - Parameterized circuits with ``Sampler`` ========================================= From 25141f23121078c781948e777187f3ed11dd1dcf Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Thu, 30 Mar 2023 15:32:19 +0200 Subject: [PATCH 39/84] Update docs/how_to/use_sampler.rst Co-authored-by: Junye Huang --- docs/how_to/use_sampler.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 9817d0a78697..4ac080d17d7b 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -207,8 +207,6 @@ If you prefer to change the options of an already-defined :class:`~qiskit.primit SamplerResult(quasi_dists=[{0: 0.5205078125, 3: 0.4794921875}], metadata=[{'shots': 2048}]) - - Define a new :class:`~qiskit.primitives.Sampler` with the options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 9c92b80494410421c3685b645fcd86df415877c3 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Thu, 30 Mar 2023 15:59:20 +0200 Subject: [PATCH 40/84] Added numpy to intersphinx and note about doctest and plot directive --- docs/conf.py | 3 ++- docs/how_to/use_estimator.rst | 6 +++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index bfc86ff859cf..309d98cd4c73 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -64,7 +64,8 @@ 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) + "qiskit-aer": ("https://qiskit.org/documentation/aer/", None), + "numpy": ("https://numpy.org/doc/stable/", None) } # -- Options for HTML output ------------------------------------------------- diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index b903578db5a8..260f2c5e4dcd 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -40,6 +40,10 @@ Then you need to create the :class:`~qiskit.circuit.QuantumCircuit` for which yo .. 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) @@ -83,7 +87,7 @@ 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 `numpy.ndarray `_ +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:: From bbd57b19006408efcd8cfb3d2b8c84574818f020 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Thu, 30 Mar 2023 16:10:47 +0200 Subject: [PATCH 41/84] Added note about quasi-probabilities --- docs/how_to/use_sampler.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 4ac080d17d7b..7cabb9792568 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -75,6 +75,12 @@ From these results you can take the probability distributions with the attribute Even though there is only one circuit in this example, :attr:`~qiskit.primitives.SamplerResult.quasi_dists` returns a list of :class:`~qiskit.result.QuasiDistribution`\ s. Generally ``result.quasi_dists[i]`` would be the quasi-probability distribution of the ``i``-th circuit. +.. note:: + + A quasi-probability distribution differs from a probability distribution in that negative values are also allowed. + However the quasi-probabilities must sum up to 1 like probabilities. + Negative quasi-probabilities may appear when using error mitigation techniques. + .. testcode:: quasi_dist = result.quasi_dists[0] From 053b7c617cb1674bf8611ea0a4c0ec45ff3877a4 Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Fri, 31 Mar 2023 11:16:37 +0200 Subject: [PATCH 42/84] rename how to to How-to Guides --- docs/how_to/index.rst | 8 ++++---- docs/index.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/how_to/index.rst b/docs/how_to/index.rst index d3a79e9ce4d9..a20d20870d99 100644 --- a/docs/how_to/index.rst +++ b/docs/how_to/index.rst @@ -1,12 +1,12 @@ .. _how_to: -###### -How to -###### +############# +How-to Guides +############# Use the primitives ------------------- +================== .. toctree:: :maxdepth: 1 diff --git a/docs/index.rst b/docs/index.rst index 1911786726ab..c71bcd933122 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ Qiskit Terra documentation :maxdepth: 2 :hidden: - How to + How-to Guides API References Release Notes From cf8def32f3b2c3e7cacebca462628f4fd1ab575b Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 11:59:33 +0200 Subject: [PATCH 43/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 260f2c5e4dcd..5f30caa13560 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -68,9 +68,9 @@ Then, you need to create an :class:`~qiskit.primitives.Estimator` object. 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. +Now that you have defined your ``estimator``, you can run your estimation by calling the :meth:`~qiskit.primitives.Estimator.run` method, +which returns an instance of :class:`~.PrimitiveJob` (subclass of :class:`~qiskit.providers.JobV1`). You can get the results from the job (as a :class:`~qiskit.primitives.EstimatorResult` object) +with the :meth:`~qiskit.providers.JobV1.result` method. .. testcode:: From 1e1044c8a1e8fbc9188dd6ca3f901d4183030f15 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 11:59:50 +0200 Subject: [PATCH 44/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 5f30caa13560..5b407d525ac0 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -85,7 +85,7 @@ with the :meth:`~qiskit.providers.JobV1.result` method. Get the expected value ---------------------- -From these results you can take the expected values with the attribute :attr:`~qiskit.primitives.EstimatorResult.values`. +From these results you can extract 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. From 6a7c92c36ec3b5c8b911dc580342671bbef0f50e Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:00:40 +0200 Subject: [PATCH 45/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 5b407d525ac0..9c8dbdd54dc3 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -57,7 +57,7 @@ Then you need to create the :class:`~qiskit.circuit.QuantumCircuit` for which yo Initialize the ``Estimator`` ============================ -Then, you need to create an :class:`~qiskit.primitives.Estimator` object. +Then, you need to instantiate an :class:`~qiskit.primitives.Estimator`. .. testcode:: From 3d7ee62462d732cc3b6f6690ce0fa119506459fe Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:14:50 +0200 Subject: [PATCH 46/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 9c8dbdd54dc3..e56fae6bd15e 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -88,7 +88,7 @@ Get the expected value From these results you can extract 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. +whose ``i``-th element is the expectation value corresponding to the ``i``-th circuit and ``i``-th observable. .. testcode:: From 215a0a8bc960400f2555e8de560b20dbd995bb77 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:15:13 +0200 Subject: [PATCH 47/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index e56fae6bd15e..5b4de482b042 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -103,7 +103,7 @@ 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 +You can also manually bind values to the parameters of the circuit and follow the steps of the previous example. .. testcode:: From 919e3165638119d0e36495d7a6bd88e76a79851f Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:15:36 +0200 Subject: [PATCH 48/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 5b4de482b042..8cdc8ef765d1 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -126,7 +126,7 @@ of the previous example. 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 +The idea is that the ``i``-th element of the outer``list`` is the set of parameter values that corresponds to the ``i``-th circuit and observable. .. testcode:: From f0dd1ab3de1f6d11753a1e9b1805f5a9b80839f4 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:16:35 +0200 Subject: [PATCH 49/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 7cabb9792568..6894c1a4e572 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -160,10 +160,10 @@ 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.Sampler` -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. +By default, the reference :class:`~qiskit.primitives.Sampler` class performs an exact statevector +calculation based on the :class:`~qiskit.quantum_info.Statevector` class. However, this can be +modified to include shot noise if the number of ``shots`` is set. +For reproducibility purposes, a ``seed`` will also be set in the following examples. There are two main ways of doing this: From 849396f2f4a632969be2020bcf804f69048ed8b4 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:17:12 +0200 Subject: [PATCH 50/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 8cdc8ef765d1..fab508097e22 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -102,7 +102,7 @@ whose ``i``-th element is the expectation value corresponding to the ``i``-th ci Parameterized circuits with ``Estimator`` ========================================= -The :class:`~qiskit.primitives.Estimator` primitive also has the option to include unbound parameterized circuits like the one below. +The :class:`~qiskit.primitives.Estimator` primitive can be run with unbound parameterized circuits like the one below. You can also manually bind values to the parameters of the circuit and follow the steps of the previous example. From d5142162b104ce837d32fc8e95624c924c348808 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:17:54 +0200 Subject: [PATCH 51/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 6894c1a4e572..3b0111269ab5 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -165,7 +165,7 @@ calculation based on the :class:`~qiskit.quantum_info.Statevector` class. Howeve modified to include shot noise if the number of ``shots`` is set. For reproducibility purposes, a ``seed`` will also be set in the following examples. -There are two main ways of doing this: +There are two main ways of setting options in the :class:`~qiskit.primitives.Sampler`: * Setting keyword arguments in the :meth:`~qiskit.primitives.Sampler.run` method. * Modify :class:`~qiskit.primitives.Sampler` options. From 645792f966f8435821f90df2cbb14c64223ca97c Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:18:06 +0200 Subject: [PATCH 52/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 3b0111269ab5..5c7ddfb355f8 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -167,7 +167,7 @@ For reproducibility purposes, a ``seed`` will also be set in the following examp There are two main ways of setting options in the :class:`~qiskit.primitives.Sampler`: -* Setting keyword arguments in the :meth:`~qiskit.primitives.Sampler.run` method. +* Set keyword arguments in the :meth:`~qiskit.primitives.Sampler.run` method. * Modify :class:`~qiskit.primitives.Sampler` options. Set keyword arguments for :meth:`~qiskit.primitives.Sampler.run` From 6d89eb09261f635cd428185f17bb7a8c0c7005a1 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:19:34 +0200 Subject: [PATCH 53/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index fab508097e22..a66bad03eb06 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -124,7 +124,7 @@ of the previous example. q_1: ─────────┤ X ├ └───┘ -The main difference from the previous case is that now you need to include the parameter values +The main difference with the previous case is that now you need to specify the sets of 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 outer``list`` is the set of parameter values that corresponds to the ``i``-th circuit and observable. From f37e2e5b8f9a5e4bba927f54f9476316a606a170 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:20:58 +0200 Subject: [PATCH 54/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index a66bad03eb06..4e1bf7547200 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -152,10 +152,10 @@ 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. +By default, the reference :class:`~qiskit.primitives.Estimator` class performs an exact statevector +calculation based on the :class:`~qiskit.quantum_info.Statevector` class. However, this can be +modified to include shot noise if the number of ``shots`` is set. +For reproducibility purposes, a ``seed`` will also be set in the following examples. There are two main ways of doing this: From f27d7ee4f331eab27124e30472c1a809f8d16961 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:21:40 +0200 Subject: [PATCH 55/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 4e1bf7547200..5d8cca34b4c3 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -157,7 +157,7 @@ calculation based on the :class:`~qiskit.quantum_info.Statevector` class. Howeve modified to include shot noise if the number of ``shots`` is set. For reproducibility purposes, a ``seed`` will also be set in the following examples. -There are two main ways of doing this: +There are two main ways of setting options in the :class:`~qiskit.primitives.Estimator`: * Setting keyword arguments in the :meth:`~qiskit.primitives.Estimator.run` method. * Modify :class:`~qiskit.primitives.Estimator` options. From 1d6e25af5164a63115b71245b05aaab917ee64fe Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:50:34 +0200 Subject: [PATCH 56/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 5c7ddfb355f8..eea17b9b02a8 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -158,7 +158,7 @@ that corresponds to the ``i``-th circuit. Change run options ================== -It is also possible that you may want to change any other option. +Your workflow might require tuning primitive run options, such as shots. By default, the reference :class:`~qiskit.primitives.Sampler` class performs an exact statevector calculation based on the :class:`~qiskit.quantum_info.Statevector` class. However, this can be From bf39db2b0b5490f9c97e59af3dab037752d98e85 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:52:24 +0200 Subject: [PATCH 57/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 5d8cca34b4c3..373c486c0549 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -6,9 +6,7 @@ This guide shows how to get the expected value of an observable for a given quan .. 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`. + While this guide uses Qiskit’s reference implementation, the ``Estimator`` primitive can be run with any provider using :class:`~qiskit.primitives.BackendEstimator` . Initialize observable From bc24efed18e7a823527ed7c2bc96945e8a43d7dc Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:54:31 +0200 Subject: [PATCH 58/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 373c486c0549..509bb1653cf9 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -148,7 +148,7 @@ that corresponds to the ``i``-th circuit and observable. Change run options ================== -It is also possible that you may want to change any other option. +Your workflow might require tuning primitive run options, such as shots. By default, the reference :class:`~qiskit.primitives.Estimator` class performs an exact statevector calculation based on the :class:`~qiskit.quantum_info.Statevector` class. However, this can be From 38ce964b7a76c8de16d100dd7fe4b4ed2c7cfe38 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:55:15 +0200 Subject: [PATCH 59/84] Update docs/how_to/use_estimator.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 509bb1653cf9..72e2a6924f76 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -157,7 +157,7 @@ For reproducibility purposes, a ``seed`` will also be set in the following examp There are two main ways of setting options in the :class:`~qiskit.primitives.Estimator`: -* Setting keyword arguments in the :meth:`~qiskit.primitives.Estimator.run` method. +* Set 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` From 80213cce32ea12345a908e1f54c6f77a3fc73ce9 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:56:42 +0200 Subject: [PATCH 60/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index eea17b9b02a8..76c43d88f011 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -53,9 +53,9 @@ Then, you need to create a :class:`~qiskit.primitives.Sampler` object. Run and get results =================== -Now that you have defined ``sampler``, you can create a :class:`~.PrimitiveJob` (subclass of :class:`~qiskit.providers.JobV1`) with the -:meth:`~qiskit.primitives.Sampler.run` method and, then, you can get the results (as a :class:`~qiskit.primitives.SamplerResult` object) with -the results with the :meth:`~qiskit.providers.JobV1.result` method. +Now that you have defined your ``sampler``, you can run it by calling the :meth:`~qiskit.primitives.Sampler.run` method, +which returns an instance of :class:`~.PrimitiveJob` (subclass of :class:`~qiskit.providers.JobV1`). You can get the results from the job (as a :class:`~qiskit.primitives.SamplerResult` object) +with the :meth:`~qiskit.providers.JobV1.result` method. .. testcode:: From 0e170c375c48b0b35480faf28d0bff222eeaca0a Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:57:09 +0200 Subject: [PATCH 61/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 76c43d88f011..21845a6e313e 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -70,7 +70,7 @@ with the :meth:`~qiskit.providers.JobV1.result` method. Get the probability distribution -------------------------------- -From these results you can take the probability distributions with the attribute :attr:`~qiskit.primitives.SamplerResult.quasi_dists`. +From these results you can extract the quasi-probability distributions with the attribute :attr:`~qiskit.primitives.SamplerResult.quasi_dists`. Even though there is only one circuit in this example, :attr:`~qiskit.primitives.SamplerResult.quasi_dists` returns a list of :class:`~qiskit.result.QuasiDistribution`\ s. Generally ``result.quasi_dists[i]`` would be the quasi-probability distribution of the ``i``-th circuit. From af5aceb944a9c3310b3f2621749046f2ca4c5495 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:57:35 +0200 Subject: [PATCH 62/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 21845a6e313e..1b8d764de5bd 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -73,7 +73,7 @@ Get the probability distribution From these results you can extract the quasi-probability distributions with the attribute :attr:`~qiskit.primitives.SamplerResult.quasi_dists`. Even though there is only one circuit in this example, :attr:`~qiskit.primitives.SamplerResult.quasi_dists` returns a list of :class:`~qiskit.result.QuasiDistribution`\ s. -Generally ``result.quasi_dists[i]`` would be the quasi-probability distribution of the ``i``-th circuit. +``result.quasi_dists[i]`` is the quasi-probability distribution of the ``i``-th circuit. .. note:: From d653451bca6146843405fdfdb7b3135cbebb7b63 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:57:55 +0200 Subject: [PATCH 63/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 1b8d764de5bd..9da87d350133 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -93,7 +93,7 @@ Even though there is only one circuit in this example, :attr:`~qiskit.primitives Probability distribution with binary outputs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you prefer to see the outputs as binary strings instead of decimal, you can use the +If you prefer to see the output keys as binary strings instead of decimal numbers, you can use the :meth:`~qiskit.result.QuasiDistribution.binary_probabilities` method. .. testcode:: From f46be30e25bfe84dfab7c8ce2751a9025a3454cb Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:58:25 +0200 Subject: [PATCH 64/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 9da87d350133..7209754af3ae 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -107,8 +107,8 @@ If you prefer to see the output keys as binary strings instead of decimal number Parameterized circuits with ``Sampler`` ========================================= -The :class:`~qiskit.primitives.Sampler` 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 +The :class:`~qiskit.primitives.Sampler` primitive can be run with unbound parameterized circuits like the one below. +You can also manually bind values to the parameters of the circuit and follow the steps of the previous example. .. testcode:: From 87de7c06542b7be4d65221d9603a1cd149213115 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:59:06 +0200 Subject: [PATCH 65/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 7209754af3ae..a637f87c594b 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -132,7 +132,7 @@ of the previous example. meas: 2/══════════════════╩══╩═ 0 1 -The main difference from the previous case is that now you need to include the parameter values +The main difference from the previous case is that now you need to specify the sets of 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. From 0255ce852d0ba739f8755ea192a91a5939a685cd Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 12:59:27 +0200 Subject: [PATCH 66/84] Update docs/how_to/use_sampler.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com> --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index a637f87c594b..746b16ff8156 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -134,7 +134,7 @@ of the previous example. The main difference from the previous case is that now you need to specify the sets of 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 +The idea is that the ``i``-th element of the outer ``list`` is the set of parameter values that corresponds to the ``i``-th circuit. .. testcode:: From 785bdd2b4bbc82313aff1e2cd657c3d10a974783 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Tue, 4 Apr 2023 13:03:40 +0200 Subject: [PATCH 67/84] Remove generally --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 72e2a6924f76..6db32c783584 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -85,7 +85,7 @@ Get the expected value From these results you can extract the expected values with the attribute :attr:`~qiskit.primitives.EstimatorResult.values`. -Generally, :attr:`~qiskit.primitives.EstimatorResult.values` returns a :class:`numpy.ndarray` +:attr:`~qiskit.primitives.EstimatorResult.values` returns a :class:`numpy.ndarray` whose ``i``-th element is the expectation value corresponding to the ``i``-th circuit and ``i``-th observable. .. testcode:: From 47c4e27de7522d36cb3d03b8ee41552ae6d81ed5 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Tue, 4 Apr 2023 13:06:12 +0200 Subject: [PATCH 68/84] Changed sampler initial note to mention BackendSampler --- docs/how_to/use_sampler.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 746b16ff8156..170e5e7064d3 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -6,9 +6,7 @@ This guide shows how to get the probability distribution of a quantum circuit wi .. note:: - While this guide only uses Qiskit Terra's implementation of the ``Sampler`` primitive, there are other - implementations of this primitive like Qiskit Terra's :class:`~qiskit.primitives.BackendSampler`, Qiskit Aer's :class:`~qiskit_aer.primitives.Sampler` - and Qiskit Runtime's :class:`~qiskit_ibm_runtime.Sampler`. + While this guide uses Qiskit’s reference implementation, the ``Sampler`` primitive can be run with any provider using :class:`~qiskit.primitives.BackendSampler`. Initialize quantum circuits =========================== From 18c90ccdbca4d11674a798d33b15eb12849e9d16 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Tue, 4 Apr 2023 13:23:03 +0200 Subject: [PATCH 69/84] Update docs/how_to/use_sampler.rst Co-authored-by: Luciano Bello --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 170e5e7064d3..ae0c5538127a 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -40,7 +40,7 @@ The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` from whi Initialize the ``Sampler`` ========================== -Then, you need to create a :class:`~qiskit.primitives.Sampler` object. +Then, you need to create a :class:`~qiskit.primitives.Sampler` instance. .. testcode:: From 8906ea85b02896101d67be86099678b2d52a9b52 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 5 Apr 2023 13:33:30 +0200 Subject: [PATCH 70/84] Added code example for backend primitives and link to providers page --- docs/how_to/use_estimator.rst | 11 +++++++++++ docs/how_to/use_sampler.rst | 11 +++++++++++ 2 files changed, 22 insertions(+) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 6db32c783584..ff9304c9ea76 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -7,6 +7,17 @@ This guide shows how to get the expected value of an observable for a given quan .. note:: While this guide uses Qiskit’s reference implementation, the ``Estimator`` primitive can be run with any provider using :class:`~qiskit.primitives.BackendEstimator` . + + .. code-block:: + + from qiskit.primitives import BackendEstimator + from qiskit_provider import QiskitProvider + + provider = QiskitProvider() + backend = provider.get_backend('backend_name') + estimator = BackendEstimator(backend) + + There are some providers that implement primitives natively (see `this page `_ for more details). Initialize observable diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index ae0c5538127a..7ae97e75de43 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -7,6 +7,17 @@ This guide shows how to get the probability distribution of a quantum circuit wi .. note:: While this guide uses Qiskit’s reference implementation, the ``Sampler`` primitive can be run with any provider using :class:`~qiskit.primitives.BackendSampler`. + + .. code-block:: + + from qiskit.primitives import BackendSampler + from qiskit_provider import QiskitProvider + + provider = QiskitProvider() + backend = provider.get_backend('backend_name') + sampler = BackendSampler(backend) + + There are some providers that implement primitives natively (see `this page `_ for more details). Initialize quantum circuits =========================== From 32ab2f3e86b254a87c841d0c8f2936ac45143cdd Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Tue, 18 Apr 2023 17:45:12 +0200 Subject: [PATCH 71/84] Update intersphinx mapping to ecosystem for aer and runtime --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index eb27afa3c47e..d9a5ca92d338 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,8 +66,8 @@ 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), + "qiskit-ibm-runtime": ("https://qiskit.org/ecosystem/ibm-runtime/", None), + "qiskit-aer": ("https://qiskit.org/ecosystem/aer/", None), "numpy": ("https://numpy.org/doc/stable/", None) } From f819ebe2f0b47581045cd9d789d55aa2346a9412 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Tue, 18 Apr 2023 17:55:44 +0200 Subject: [PATCH 72/84] Change rustworkx link --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 6e694e3368db..7ea751088467 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -65,7 +65,7 @@ modindex_common_prefix = ["qiskit."] intersphinx_mapping = { - "retworkx": ("https://qiskit.org/documentation/retworkx/", None), + "rustworkx": ("https://qiskit.org/ecosystem/rustworkx/", None), "qiskit-ibm-runtime": ("https://qiskit.org/ecosystem/ibm-runtime/", None), "qiskit-aer": ("https://qiskit.org/ecosystem/aer/", None), "numpy": ("https://numpy.org/doc/stable/", None) From b352958bea66d520dd01437d607fab47a00968c2 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Wed, 10 May 2023 12:11:25 +0200 Subject: [PATCH 73/84] Add "primitive" to estimator how-to title Co-authored-by: Luciano Bello --- docs/how_to/use_estimator.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index ff9304c9ea76..f4e318608993 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -1,6 +1,6 @@ -############################################### -Compute an expectation value with ``Estimator`` -############################################### +######################################################### +Compute an expectation value with ``Estimator`` primitive +######################################################### This guide shows how to get the expected value of an observable for a given quantum circuit with the :class:`~qiskit.primitives.Estimator` primitive. From 278df5a38ac57a7516bd5436f8904a2c41f41d55 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Wed, 10 May 2023 12:12:25 +0200 Subject: [PATCH 74/84] Change hypothetical import to avoid confusion Co-authored-by: Luciano Bello --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index f4e318608993..25efd04ec524 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -11,7 +11,7 @@ This guide shows how to get the expected value of an observable for a given quan .. code-block:: from qiskit.primitives import BackendEstimator - from qiskit_provider import QiskitProvider + from import QiskitProvider provider = QiskitProvider() backend = provider.get_backend('backend_name') From e51e29e01cc3be9b89b661cc4a2f3938b1cd7e4d Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Wed, 10 May 2023 12:39:45 +0200 Subject: [PATCH 75/84] Update docs/how_to/use_estimator.rst Co-authored-by: Luciano Bello --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 25efd04ec524..3d648b12da5e 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -196,7 +196,7 @@ passing them as keyword arguments. 3.999999998697238 -Change :class:`~qiskit.primitives.Estimator` options +Modify :class:`~qiskit.primitives.Estimator` options ----------------------------------------------------- If you want to keep some configuration values for several runs, it can be better to From 644d8c74bbc59e616c26ef3aa7baac345d8fe004 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Wed, 10 May 2023 12:42:08 +0200 Subject: [PATCH 76/84] Include "primitive" word in sampler how-to title Co-authored-by: Luciano Bello --- docs/how_to/use_sampler.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 7ae97e75de43..a7910b5249e9 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -1,6 +1,6 @@ -##################################################### -Compute circuit output probabilities with ``Sampler`` -##################################################### +############################################################### +Compute circuit output probabilities with ``Sampler`` primitive +############################################################### This guide shows how to get the probability distribution of a quantum circuit with the :class:`~qiskit.primitives.Sampler` primitive. From 1607aace4972175e6115d4d16c9c1f4614c0282d Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Wed, 10 May 2023 12:42:36 +0200 Subject: [PATCH 77/84] Improve phrasing Co-authored-by: Luciano Bello --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index a7910b5249e9..365a9aea7664 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -167,7 +167,7 @@ that corresponds to the ``i``-th circuit. Change run options ================== -Your workflow might require tuning primitive run options, such as shots. +Your workflow might require tuning primitive run options, such as the amount of shots. By default, the reference :class:`~qiskit.primitives.Sampler` class performs an exact statevector calculation based on the :class:`~qiskit.quantum_info.Statevector` class. However, this can be From 36d54f3a625d12fbec8c9c03c4cc93005ff22be2 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 10 May 2023 12:47:32 +0200 Subject: [PATCH 78/84] Include notice about doctest and plot directive incompatibility in sampler guide --- docs/how_to/use_sampler.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 365a9aea7664..7904881a473d 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -37,6 +37,10 @@ The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` from whi .. 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) From 254c8de822ab329082b7efd78b57377c74d2c495 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 10 May 2023 12:52:20 +0200 Subject: [PATCH 79/84] change->modify sampler options --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 7904881a473d..7abc46e8a2d7 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -200,7 +200,7 @@ passing them as keyword arguments. SamplerResult(quasi_dists=[{0: 0.5205078125, 3: 0.4794921875}], metadata=[{'shots': 2048}]) -Change :class:`~qiskit.primitives.Sampler` options +Modify :class:`~qiskit.primitives.Sampler` options --------------------------------------------------- If you want to keep some configuration values for several runs, it can be better to From 3ee61586908b0c6728b06d93d8c90d27c8431fe9 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 10 May 2023 12:53:18 +0200 Subject: [PATCH 80/84] change qiskit_provider to --- docs/how_to/use_sampler.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 7abc46e8a2d7..ff9b06e5b756 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -11,7 +11,7 @@ This guide shows how to get the probability distribution of a quantum circuit wi .. code-block:: from qiskit.primitives import BackendSampler - from qiskit_provider import QiskitProvider + from import QiskitProvider provider = QiskitProvider() backend = provider.get_backend('backend_name') From 004f4ad2b73be085c45db4761d57cb18dc74f7eb Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 10 May 2023 12:54:35 +0200 Subject: [PATCH 81/84] shots->amount of shots in estimator how-to --- docs/how_to/use_estimator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 3d648b12da5e..7aa0c3adb857 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -159,7 +159,7 @@ that corresponds to the ``i``-th circuit and observable. Change run options ================== -Your workflow might require tuning primitive run options, such as shots. +Your workflow might require tuning primitive run options, such as the amount of shots. By default, the reference :class:`~qiskit.primitives.Estimator` class performs an exact statevector calculation based on the :class:`~qiskit.quantum_info.Statevector` class. However, this can be From 3d7e5a8f95e5fc2fcd8326ad59a7c1d1b26f14a6 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 10 May 2023 13:18:18 +0200 Subject: [PATCH 82/84] Add quick explanation about using multiple circuits and observables and adjust plurals --- docs/how_to/use_estimator.rst | 12 ++++++++---- docs/how_to/use_sampler.rst | 5 ++++- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 7aa0c3adb857..a47038e5ded4 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -20,10 +20,10 @@ This guide shows how to get the expected value of an observable for a given quan There are some providers that implement primitives natively (see `this page `_ for more details). -Initialize observable -===================== +Initialize observables +====================== -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`. +The first step is to define the observables whose expected value you want to compute. Each 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:: @@ -35,7 +35,7 @@ Among them it is preferable to use :class:`~qiskit.quantum_info.SparsePauliOp`. Initialize quantum circuits =========================== -Then you need to create the :class:`~qiskit.circuit.QuantumCircuit` for which you want to obtain the expected value. +Then you need to create the :class:`~qiskit.circuit.QuantumCircuit`\ s for which you want to obtain the expected value. .. plot:: :include-source: @@ -91,6 +91,10 @@ with the :meth:`~qiskit.providers.JobV1.result` method. EstimatorResult(values=array([4.]), metadata=[{}]) +While this example only uses one :class:`~qiskit.circuit.QuantumCircuit` and one observable, if you want to get expectation values for multiple circuits and observables you can +pass a ``list`` of :class:`~qiskit.circuit.QuantumCircuit`\ s and a list of ``BaseOperator``\ s to the :meth:`~qiskit.primitives.Estimator.run` method. Both ``list``\ s must have +the same length. + Get the expected value ---------------------- diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index ff9b06e5b756..ce721d5e009b 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -22,7 +22,7 @@ This guide shows how to get the probability distribution of a quantum circuit wi Initialize quantum circuits =========================== -The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` from which you want to obtain the probability distribution. +The first step is to create the :class:`~qiskit.circuit.QuantumCircuit`\ s from which you want to obtain the probability distribution. .. plot:: :include-source: @@ -80,6 +80,9 @@ with the :meth:`~qiskit.providers.JobV1.result` method. SamplerResult(quasi_dists=[{0: 0.4999999999999999, 3: 0.4999999999999999}], metadata=[{}]) +While this example only uses one :class:`~qiskit.circuit.QuantumCircuit`, if you want to sample multiple circuits you can +pass a ``list`` of :class:`~qiskit.circuit.QuantumCircuit` instances to the :meth:`~qiskit.primitives.Sampler.run` method. + Get the probability distribution -------------------------------- From 51a1260fea0cfa9b437af39918555af85fc520d8 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Fri, 19 May 2023 13:18:42 +0200 Subject: [PATCH 83/84] singular --- docs/how_to/use_estimator.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index a47038e5ded4..61a69ab5ffbc 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -32,8 +32,8 @@ Among them it is preferable to use :class:`~qiskit.quantum_info.SparsePauliOp`. observable = SparsePauliOp(["II", "XX", "YY", "ZZ"], coeffs=[1, 1, -1, 1]) -Initialize quantum circuits -=========================== +Initialize quantum circuit +========================== Then you need to create the :class:`~qiskit.circuit.QuantumCircuit`\ s for which you want to obtain the expected value. @@ -112,8 +112,8 @@ whose ``i``-th element is the expectation value corresponding to the ``i``-th ci 3.999999999999999 -Parameterized circuits with ``Estimator`` -========================================= +Parameterized circuit with ``Estimator`` +======================================== The :class:`~qiskit.primitives.Estimator` primitive can be run with unbound parameterized circuits like the one below. You can also manually bind values to the parameters of the circuit and follow the steps @@ -139,7 +139,7 @@ of the previous example. The main difference with the previous case is that now you need to specify the sets of 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 outer``list`` is the set of parameter values +The ``i``-th element of the outer``list`` is the set of parameter values that corresponds to the ``i``-th circuit and observable. .. testcode:: From 973f1e0e18de2ab49dc796c3b587383144f7411a Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Fri, 19 May 2023 13:21:00 +0200 Subject: [PATCH 84/84] singular --- docs/how_to/use_sampler.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index ce721d5e009b..da7257c28fa1 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -120,8 +120,8 @@ If you prefer to see the output keys as binary strings instead of decimal number {'00': 0.4999999999999999, '11': 0.4999999999999999} -Parameterized circuits with ``Sampler`` -========================================= +Parameterized circuit with ``Sampler`` +======================================== The :class:`~qiskit.primitives.Sampler` primitive can be run with unbound parameterized circuits like the one below. You can also manually bind values to the parameters of the circuit and follow the steps @@ -150,7 +150,7 @@ of the previous example. The main difference from the previous case is that now you need to specify the sets of 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 outer ``list`` is the set of parameter values +The ``i``-th element of the outer ``list`` is the set of parameter values that corresponds to the ``i``-th circuit. .. testcode::