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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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/43] 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 afa30d97fa0d513420e332755d660eb6d18e2a33 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 10 May 2023 16:43:36 +0200 Subject: [PATCH 26/43] add quantum to parameterized circuits how-to title --- docs/how_to/create_a_parameterized_circuit.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how_to/create_a_parameterized_circuit.rst b/docs/how_to/create_a_parameterized_circuit.rst index 7568ed631861..fb1a3a8dadee 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 -############################## +###################################### +Create a parameterized quantum circuit +###################################### This guide will show how to create a :class:`~.QuantumCircuit` that includes parameters. From 6a10dd1fbfc67feb2a2cfa4da54cf10f397ee214 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 10 May 2023 16:59:19 +0200 Subject: [PATCH 27/43] change compose to join in title --- docs/how_to/compose_quantum_circuits.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how_to/compose_quantum_circuits.rst b/docs/how_to/compose_quantum_circuits.rst index c5a01dbbc963..5fe0c3a5a9c2 100644 --- a/docs/how_to/compose_quantum_circuits.rst +++ b/docs/how_to/compose_quantum_circuits.rst @@ -1,6 +1,6 @@ -######################## -Compose quantum circuits -######################## +##################### +Join quantum circuits +##################### This guide shows how to combine different :class:`~.QuantumCircuit` objects. From 6d60a2761ac724c29d26ae5c3c0411282568193a Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Wed, 10 May 2023 17:00:29 +0200 Subject: [PATCH 28/43] Added warning about + operator not supported to combine circuits --- docs/how_to/compose_quantum_circuits.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/how_to/compose_quantum_circuits.rst b/docs/how_to/compose_quantum_circuits.rst index 5fe0c3a5a9c2..0ba955b5ff3b 100644 --- a/docs/how_to/compose_quantum_circuits.rst +++ b/docs/how_to/compose_quantum_circuits.rst @@ -57,6 +57,11 @@ Now that you have built the circuits, they can be combined with two different me * :meth:`~.QuantumCircuit.compose` * :meth:`~.QuantumCircuit.append` +.. warning:: + + The usage of the ``+`` operator to combine :class:`~.QuantumCircuit`\ s is no longer supported so if you try to define + a circuit as ``composed_qc = qc1 + qc2`` you will get an error. + 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` From 20fd583e2cd491a88ed3c8781fab1dab07878d9d Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Fri, 12 May 2023 18:35:48 +0200 Subject: [PATCH 29/43] Apply suggestions from code review Co-authored-by: Junye Huang --- docs/how_to/create_a_quantum_circuit.rst | 32 ++++++++++++------------ 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/how_to/create_a_quantum_circuit.rst b/docs/how_to/create_a_quantum_circuit.rst index 700ea07e74a7..93fd84fcf664 100644 --- a/docs/how_to/create_a_quantum_circuit.rst +++ b/docs/how_to/create_a_quantum_circuit.rst @@ -3,17 +3,17 @@ Create a quantum circuit ######################## -This guide shows how to initialize a quantum circuit. +This guide shows you how to create 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. +1. Specifying the number of qubits and classical bits. +2. Creating :class:`~.QuantumRegister`\ s and :class:`~.ClassicalRegister`\ s and use the registers to initialize a :class:`~.QuantumCircuit` -Create from number of qubits and bits +Specifying the number of qubits and classical bits ===================================== -In order to create a :class:`~.QuantumCircuit` by only specifying the number of bits and qubits, you need to follow these steps. +You can create a :class:`~.QuantumCircuit` by only specifying the number of qubits and classical bits. For example: .. testcode:: @@ -39,7 +39,7 @@ In order to create a :class:`~.QuantumCircuit` by only specifying the number of 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. +You can also create a :class:`~.QuantumCircuit` with only qubits and no classical bits, by omitting the number of classical bits: .. testcode:: @@ -63,37 +63,37 @@ 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. +You can create a :class:`~.QuantumRegister` object by passing the desired number of qubits as an argument: .. testcode:: from qiskit import QuantumRegister - # Create QuantumRegister formed by 2 qubits + # Create a quantum register with 2 qubits qr1 = QuantumRegister(2) - # Create QuantumRegister formed by 3 qubits + # Create a quantum register with 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. +Similar to the quantum registers, you can create a :class:`~.ClassicalRegister` object by passing the desired number of classical bits as an argument: .. testcode:: from qiskit import ClassicalRegister - # Create classical register with 2 classical bits + # Create a classical register with 2 classical bits cr1 = ClassicalRegister(2) - # Create classical register with 1 classical bit + # Create a 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. +Now that you have defined the quantum and classical registers, you can create a :class:`~.QuantumCircuit` with the registers: .. testcode:: @@ -119,11 +119,11 @@ Now that you have defined the quantum and classical registers, you can define a 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. +You can put the registers in any order, even mixing classical and quantum. However, the relative order of the :class:`~.QuantumRegister`\ s affects the order of the qubits in the final circuit. 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 + # Resulting quantum circuits will be the same if the quantum and classical registers have the same relative order qc1 = QuantumCircuit(qr1, cr1, qr2, cr2) print(qc == qc1) @@ -134,7 +134,7 @@ You can put the registers in any order, even mixing classical and quantum. Howev .. testcode:: - # We change the order of the quantum registers + # Resulting quantum circuits are different if the quantum or classical registers have different relative order qc2 = QuantumCircuit(qr2, qr1, cr1, cr2) print(qc == qc2) From 795b35c28ee86a680840e6487655d27d91800287 Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Fri, 12 May 2023 18:43:37 +0200 Subject: [PATCH 30/43] Apply suggestions from code review Co-authored-by: Junye Huang --- docs/how_to/visualize_a_quantum_circuit.rst | 46 ++++++++++----------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst index 142953ed019a..c58cf83de317 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -4,10 +4,10 @@ Visualize a quantum circuit This guide shows how to get a visual representation of a quantum circuit. -Build the circuit +Create a circuit ================= -The first step is to create the circuit. +Let's first create a quantum circuit for the visualization. .. testcode:: @@ -21,14 +21,14 @@ The first step is to create the circuit. Visualize the circuit ===================== -There are three different ways to visualize a circuit. You can use +You can visualize a quantum circuit in the following ways: -* The ``print()`` function. -* The :meth:`~.QuantumCircuit.draw` method. -* The :func:`~.circuit_drawer` function. +1. Using the ``print()`` function. +2. Using the :meth:`~.QuantumCircuit.draw` method. +3. Using the :func:`~.circuit_drawer` function. -``print()`` ------------ +Using the ``print()`` function +------------------------------ If you call the ``print()`` function on a :class:`~.QuantumCircuit` object, you will get an `ASCII art version `_ of the circuit diagram. @@ -49,10 +49,10 @@ If you call the ``print()`` function on a :class:`~.QuantumCircuit` object, you c: 3/═══════╩═══╩══╩═ 2 0 1 -:meth:`~.QuantumCircuit.draw` ---------------------------------------------- +Using the :meth:`~.QuantumCircuit.draw` method +---------------------------------------------- -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. +You can also use the :meth:`.QuantumCircuit.draw` method to visualize it. The default output style is 'text', which will output a ASCII art version, the same as using the ``print()`` function. .. code-block:: python @@ -70,21 +70,21 @@ You can also call the :meth:`~.QuantumCircuit.draw` method on a :class:`~.Quantu 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: +You can also change the output style using the ``output`` argument. These are the available output styles: -* ``'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. +1. ``'text'``: renders the circuit with ASCII art. It's the default option. +2. ``'mpl'``: uses `matplotlib `_ to render the circuit. +3. ``'latex'``: uses :math:`\LaTeX` to render the circuit. It requires a full `LaTeX `_ distribution and the package ``pdflatex``. +4. ``'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)``. +Because this optional keyword argument is the first of this method, you 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'`` -^^^^^^^^^ +``'mpl'`` ouptut +^^^^^^^^^^^^^^^^ .. code-block:: python @@ -101,8 +101,8 @@ Because this optional or keyword argument is actually the first of this method, qc.draw("mpl") -``'latex_source'`` -^^^^^^^^^^^^^^^^^^ +``'latex_source'`` output +^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: python @@ -113,8 +113,8 @@ Because this optional or keyword argument is actually the first of this method, '\\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` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Using the :func:`~.circuit_drawer` function +------------------------------------------- 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. From 8f8ec2431b44e68f190be958ab9db2a5b282635b Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Fri, 12 May 2023 18:46:45 +0200 Subject: [PATCH 31/43] rephrase visualization how-to intro --- 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 c58cf83de317..bab875312a4d 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -2,7 +2,7 @@ Visualize a quantum circuit ########################### -This guide shows how to get a visual representation of a quantum circuit. +This guide shows you how to visualize a quantum circuit. Create a circuit ================= From 96773722acfcdf50573a367060843e60f9c723ed Mon Sep 17 00:00:00 2001 From: Guillermo-Mijares-Vilarino <106545082+Guillermo-Mijares-Vilarino@users.noreply.github.com> Date: Fri, 12 May 2023 19:16:43 +0200 Subject: [PATCH 32/43] Apply suggestions from code review Co-authored-by: Junye Huang --- docs/how_to/compose_quantum_circuits.rst | 43 ++++++++++++------------ 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/docs/how_to/compose_quantum_circuits.rst b/docs/how_to/compose_quantum_circuits.rst index 0ba955b5ff3b..326fafc47578 100644 --- a/docs/how_to/compose_quantum_circuits.rst +++ b/docs/how_to/compose_quantum_circuits.rst @@ -2,12 +2,12 @@ Join quantum circuits ##################### -This guide shows how to combine different :class:`~.QuantumCircuit` objects. +This guide shows you how to combine different :class:`~.QuantumCircuit` objects. -Build the circuits -================== +Create the circuits +=================== -The first step is creating the circuits you want to combine. +Let's first create two circuits, which will be joint together. .. testcode:: @@ -49,27 +49,26 @@ The first step is creating the circuits you want to combine. c: 2/═══════════╩═ 1 -Combine the circuits -==================== +Join the circuits +================= -Now that you have built the circuits, they can be combined with two different methods: +You can join the circuits together using these two methods: -* :meth:`~.QuantumCircuit.compose` -* :meth:`~.QuantumCircuit.append` +1. Using the :meth:`~.QuantumCircuit.compose` method +2. Using the :meth:`~.QuantumCircuit.append` method .. warning:: - The usage of the ``+`` operator to combine :class:`~.QuantumCircuit`\ s is no longer supported so if you try to define - a circuit as ``composed_qc = qc1 + qc2`` you will get an error. + The ``combine`` and ``extend`` methods have been deprecated in Qiskit Terra 0.17 and removed in 0.23. These methods are replaced by :meth:`~.QuantumCircuit.compose` method which is more powerful. The removal of ``extend`` also means that the ``+`` and ``+=`` operators are no longer defined for :class:`~.QuantumCircuit`. Instead, you can use the ``&`` and ``&=`` operators respectively, which use :meth:`~.QuantumCircuit.compose`. -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. +For both methods, if the two circuits being joint have different sizes, the method needs to be called in the circuit that is bigger (more qubits and more classical bits). -:meth:`~.QuantumCircuit.compose` ------------------------------------------------- +Using the :meth:`~.QuantumCircuit.compose` method +------------------------------------------------- -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. +In order to join 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``. +By default, :meth:`~.QuantumCircuit.compose` does not modify the original circuit to which it is applied but returns a new joint circuit object. This can be changed by setting the ``inplace`` argument to ``True``. .. testcode:: @@ -113,7 +112,7 @@ If you want to insert the qubits and bits into specific positions in the bigger 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``. +You can also join the smaller circuit in front of the bigger circuit by setting the ``front`` argument to ``True``. .. testcode:: @@ -135,12 +134,12 @@ You can also apply the gates from the smaller circuit before those of the bigger c: 2/════════════╩═════════════╩═ 0 1 -:meth:`~.QuantumCircuit.append` ------------------------------------------------ +Using the :meth:`~.QuantumCircuit.append` method +------------------------------------------------ -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. +In order to join two circuits with :meth:`~.QuantumCircuit.append`, you need 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. +Different from :meth:`~.QuantumCircuit.compose`, this method modifies the circuit to which it is applied instead of returning a new circuit. .. testcode:: @@ -163,7 +162,7 @@ This method changes the circuit to which it is applied instead of returning anot 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` +Unlike :meth:`~.QuantumCircuit.compose`, :meth:`~.QuantumCircuit.append` turns the smaller circuit into a single :class:`~qiskit.circuit.Instruction`. If you prefer joining the circuits using the individual gates, you can use :meth:`~.QuantumCircuit.decompose` to decompose the joint circuit. .. testcode:: From c33605eec13ee9b1e8c1e8a2a6ebb2392e983518 Mon Sep 17 00:00:00 2001 From: Guillermo Mijares Vilarino Date: Tue, 16 May 2023 10:18:30 +0200 Subject: [PATCH 33/43] fix underline --- 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 93fd84fcf664..9697329540c6 100644 --- a/docs/how_to/create_a_quantum_circuit.rst +++ b/docs/how_to/create_a_quantum_circuit.rst @@ -11,7 +11,7 @@ There are two ways to create a :class:`~.QuantumCircuit` object: 2. Creating :class:`~.QuantumRegister`\ s and :class:`~.ClassicalRegister`\ s and use the registers to initialize a :class:`~.QuantumCircuit` Specifying the number of qubits and classical bits -===================================== +================================================== You can create a :class:`~.QuantumCircuit` by only specifying the number of qubits and classical bits. For example: From 95537d3b0aa7cc59bacdf67001cd6cbbe1647e81 Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Mon, 10 Jul 2023 15:58:52 +0200 Subject: [PATCH 34/43] Apply suggestions from code review Co-authored-by: Abby Mitchell <23662430+javabster@users.noreply.github.com> --- docs/how_to/compose_quantum_circuits.rst | 10 +++++----- docs/how_to/create_a_parameterized_circuit.rst | 6 +++--- docs/how_to/create_a_quantum_circuit.rst | 6 +++--- docs/how_to/index.rst | 2 +- docs/how_to/use_estimator.rst | 16 ++++++++-------- docs/how_to/use_sampler.rst | 16 ++++++++-------- docs/how_to/visualize_a_quantum_circuit.rst | 2 +- 7 files changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/how_to/compose_quantum_circuits.rst b/docs/how_to/compose_quantum_circuits.rst index 326fafc47578..54955488fb8a 100644 --- a/docs/how_to/compose_quantum_circuits.rst +++ b/docs/how_to/compose_quantum_circuits.rst @@ -7,7 +7,7 @@ This guide shows you how to combine different :class:`~.QuantumCircuit` objects. Create the circuits =================== -Let's first create two circuits, which will be joint together. +Let's first create two circuits, which will be joined together. .. testcode:: @@ -59,9 +59,9 @@ You can join the circuits together using these two methods: .. warning:: - The ``combine`` and ``extend`` methods have been deprecated in Qiskit Terra 0.17 and removed in 0.23. These methods are replaced by :meth:`~.QuantumCircuit.compose` method which is more powerful. The removal of ``extend`` also means that the ``+`` and ``+=`` operators are no longer defined for :class:`~.QuantumCircuit`. Instead, you can use the ``&`` and ``&=`` operators respectively, which use :meth:`~.QuantumCircuit.compose`. + The ``combine`` and ``extend`` methods have been deprecated in Qiskit Terra 0.17 and removed in 0.23. These methods are replaced by the :meth:`~.QuantumCircuit.compose` method which is more powerful. The removal of ``extend`` also means that the ``+`` and ``+=`` operators are no longer defined for :class:`~.QuantumCircuit`. Instead, you can use the ``&`` and ``&=`` operators respectively, which use :meth:`~.QuantumCircuit.compose`. -For both methods, if the two circuits being joint have different sizes, the method needs to be called in the circuit that is bigger (more qubits and more classical bits). +For both methods, if the two circuits being combined have different sizes, the method needs to be called in the circuit that is bigger (more qubits and more classical bits). Using the :meth:`~.QuantumCircuit.compose` method ------------------------------------------------- @@ -137,9 +137,9 @@ You can also join the smaller circuit in front of the bigger circuit by setting Using the :meth:`~.QuantumCircuit.append` method ------------------------------------------------ -In order to join two circuits with :meth:`~.QuantumCircuit.append`, you need 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 join two circuits with :meth:`~.QuantumCircuit.append`, you need to specify the circuit you want to add, as well as the qubits and classical bits (if there are any) onto which you want the circuit to be applied. -Different from :meth:`~.QuantumCircuit.compose`, this method modifies the circuit to which it is applied instead of returning a new circuit. +Different from :meth:`~.QuantumCircuit.compose`, this method modifies the circuit it is applied to, instead of returning a new circuit. .. testcode:: diff --git a/docs/how_to/create_a_parameterized_circuit.rst b/docs/how_to/create_a_parameterized_circuit.rst index fb1a3a8dadee..8b5055f845db 100644 --- a/docs/how_to/create_a_parameterized_circuit.rst +++ b/docs/how_to/create_a_parameterized_circuit.rst @@ -7,7 +7,7 @@ This guide will show how to create a :class:`~.QuantumCircuit` that includes par 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 ``'θ'``. +In order to define a parameter, you need to create a :class:`~.Parameter` object. To do that you only need to choose a ``name``, which can be any unicode string like ``'θ'``. .. testcode:: @@ -19,7 +19,7 @@ In order to define a parameter, you need to create a :class:`~.Parameter` object Create the parameterized circuit ================================ -When creating the circuit you can include the :class:`~.Parameter` as if it was a defined number. +When creating the circuit you can include the :class:`~.Parameter` you just created the same as if it was a defined number. .. testcode:: @@ -48,7 +48,7 @@ You can use these two methods to assign values to the :class:`~.Parameter`\ s in :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`. +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. If using only numeric values they will be bound to their corresponding parameters in according to the order in :attr:`~.QuantumCircuit.parameters`. .. testcode:: diff --git a/docs/how_to/create_a_quantum_circuit.rst b/docs/how_to/create_a_quantum_circuit.rst index 9697329540c6..2fa3f7fdf080 100644 --- a/docs/how_to/create_a_quantum_circuit.rst +++ b/docs/how_to/create_a_quantum_circuit.rst @@ -7,7 +7,7 @@ This guide shows you how to create a quantum circuit. There are two ways to create a :class:`~.QuantumCircuit` object: -1. Specifying the number of qubits and classical bits. +1. Initialize :class:`~.QuantumCircuit` by directly specifying the number of qubits and classical bits you want. 2. Creating :class:`~.QuantumRegister`\ s and :class:`~.ClassicalRegister`\ s and use the registers to initialize a :class:`~.QuantumCircuit` Specifying the number of qubits and classical bits @@ -60,7 +60,7 @@ You can also create a :class:`~.QuantumCircuit` with only qubits and no classica Create from quantum and classical registers =========================================== -Create quantum registers +Creating quantum registers ------------------------ You can create a :class:`~.QuantumRegister` object by passing the desired number of qubits as an argument: @@ -75,7 +75,7 @@ You can create a :class:`~.QuantumRegister` object by passing the desired number # Create a quantum register with 3 qubits qr2 = QuantumRegister(3) -Create classical registers +Creating classical registers -------------------------- Similar to the quantum registers, you can create a :class:`~.ClassicalRegister` object by passing the desired number of classical bits as an argument: diff --git a/docs/how_to/index.rst b/docs/how_to/index.rst index 13ccdf10b9c9..dd4fc97075a6 100644 --- a/docs/how_to/index.rst +++ b/docs/how_to/index.rst @@ -4,7 +4,7 @@ How to ###### -Create quantum circuits +Create a quantum circuit ----------------------- .. toctree:: diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 357aaef4e32a..e9a47bdcaf66 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -9,7 +9,7 @@ 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`. +Out of the available options it is recommended to use :class:`~qiskit.quantum_info.SparsePauliOp`. .. testcode:: @@ -17,10 +17,10 @@ Among them it is preferable to use :class:`~qiskit.quantum_info.SparsePauliOp`. obs = SparsePauliOp(["II", "XX", "YY", "ZZ"], [1, 1, -1, 1]) -Initialize quantum circuits +Initialize the quantum circuit =========================== -Then you need to create the :class:`~qiskit.circuit.QuantumCircuit` for which you want to obtain the expected value. +Next 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:: @@ -44,7 +44,7 @@ For more details about this part check out :doc:`this guide `_ -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:: @@ -113,7 +113,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 between this example and the previous one 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. diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index cb668a7085fa..b73af8413d6b 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -4,7 +4,7 @@ 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 +Initialize the quantum circuit =========================== The first step is to create the :class:`~qiskit.circuit.QuantumCircuit` from which you want to obtain the probability distribution. @@ -33,7 +33,7 @@ For more details about this part check out :doc:`this guide Date: Mon, 10 Jul 2023 17:11:31 +0200 Subject: [PATCH 35/43] reverting to use verb instead of ing form --- docs/how_to/create_a_quantum_circuit.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/how_to/create_a_quantum_circuit.rst b/docs/how_to/create_a_quantum_circuit.rst index 2fa3f7fdf080..12fa877738cd 100644 --- a/docs/how_to/create_a_quantum_circuit.rst +++ b/docs/how_to/create_a_quantum_circuit.rst @@ -10,8 +10,8 @@ There are two ways to create a :class:`~.QuantumCircuit` object: 1. Initialize :class:`~.QuantumCircuit` by directly specifying the number of qubits and classical bits you want. 2. Creating :class:`~.QuantumRegister`\ s and :class:`~.ClassicalRegister`\ s and use the registers to initialize a :class:`~.QuantumCircuit` -Specifying the number of qubits and classical bits -================================================== +Create by specifying the number of qubits and classical bits +============================================================ You can create a :class:`~.QuantumCircuit` by only specifying the number of qubits and classical bits. For example: @@ -60,7 +60,7 @@ You can also create a :class:`~.QuantumCircuit` with only qubits and no classica Create from quantum and classical registers =========================================== -Creating quantum registers +Create quantum registers ------------------------ You can create a :class:`~.QuantumRegister` object by passing the desired number of qubits as an argument: @@ -75,7 +75,7 @@ You can create a :class:`~.QuantumRegister` object by passing the desired number # Create a quantum register with 3 qubits qr2 = QuantumRegister(3) -Creating classical registers +Create classical registers -------------------------- Similar to the quantum registers, you can create a :class:`~.ClassicalRegister` object by passing the desired number of classical bits as an argument: @@ -90,8 +90,8 @@ Similar to the quantum registers, you can create a :class:`~.ClassicalRegister` # Create a classical register with 1 classical bit cr2 = ClassicalRegister(1) -Initialize the quantum circuit ------------------------------- +Create a quantum circuit +------------------------ Now that you have defined the quantum and classical registers, you can create a :class:`~.QuantumCircuit` with the registers: From aa5d2d419a5dfe577efa0b146c0611b676dd1d5c Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Mon, 10 Jul 2023 17:25:35 +0200 Subject: [PATCH 36/43] add back notes for including and excluding measurements --- docs/how_to/use_estimator.rst | 4 ++++ docs/how_to/use_sampler.rst | 3 +++ 2 files changed, 7 insertions(+) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index 9adb8d25b7e3..f2b8ddf8a2be 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -60,6 +60,10 @@ For more details about this part check out :doc:`this guide Date: Mon, 10 Jul 2023 17:28:47 +0200 Subject: [PATCH 37/43] revert necessary code changes in use_estimator --- docs/how_to/use_estimator.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/how_to/use_estimator.rst b/docs/how_to/use_estimator.rst index f2b8ddf8a2be..dc7355efc1c8 100644 --- a/docs/how_to/use_estimator.rst +++ b/docs/how_to/use_estimator.rst @@ -101,7 +101,8 @@ Get the expected value From these results you can extract the expected values with the attribute :attr:`~qiskit.primitives.EstimatorResult.values`. -: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. +: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:: @@ -124,13 +125,12 @@ 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:: - :options: +NORMALIZE_WHITESPACE ┌───────┐ q_0: ┤ Ry(θ) ├──■── @@ -149,14 +149,13 @@ 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): 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 From ec0c28c0348eff3dfa05eb29ec7e229d47adfd46 Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Mon, 10 Jul 2023 17:33:02 +0200 Subject: [PATCH 38/43] revert unnecessary code changes in use_sampler --- docs/how_to/use_sampler.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index 264f513b52d8..f2cb1455d11d 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -22,6 +22,8 @@ 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`\ s from which you want to obtain the probability distribution. + .. plot:: :include-source: @@ -132,14 +134,13 @@ 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:: - :options: +NORMALIZE_WHITESPACE ┌───────┐ ░ ┌─┐ q_0: ┤ Ry(θ) ├──■───░─┤M├─── @@ -159,14 +160,13 @@ The idea is that the ``i``-th element of the bigger ``list`` is the set of param 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): 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 194302c4551104bfd9ea1017658bb34d3b127d95 Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Mon, 10 Jul 2023 17:35:16 +0200 Subject: [PATCH 39/43] change expectation values to sampling probabilities --- 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 f2cb1455d11d..b9a6c6b8223a 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -151,7 +151,7 @@ of the previous example. 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. +for which you want to sample the probabilities 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 .. testcode:: From 65935f3318d9bd0887dbeb5940549205a9772887 Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Mon, 10 Jul 2023 17:38:54 +0200 Subject: [PATCH 40/43] remove note --- docs/how_to/visualize_a_quantum_circuit.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst index 4e24c3c25d6d..11d151876577 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -79,9 +79,6 @@ You can also change the output style using the ``output`` argument. These are th Because this optional keyword argument is the first of this method, you 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'`` ouptut ^^^^^^^^^^^^^^^^ From be801cfb57ac454f73e6b4d6c1d578ca50e9cfdf Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Mon, 10 Jul 2023 17:40:40 +0200 Subject: [PATCH 41/43] remove note --- docs/how_to/visualize_a_quantum_circuit.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/how_to/visualize_a_quantum_circuit.rst b/docs/how_to/visualize_a_quantum_circuit.rst index 11d151876577..81306d75e8c6 100644 --- a/docs/how_to/visualize_a_quantum_circuit.rst +++ b/docs/how_to/visualize_a_quantum_circuit.rst @@ -115,10 +115,6 @@ Using the :func:`~.circuit_drawer` function 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 From 802b53dbd8c534821d49284accd74403c8886dee Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Mon, 10 Jul 2023 17:48:01 +0200 Subject: [PATCH 42/43] add a sentence explaining joining by specifying qubits --- 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 54955488fb8a..c78214196ec2 100644 --- a/docs/how_to/compose_quantum_circuits.rst +++ b/docs/how_to/compose_quantum_circuits.rst @@ -90,7 +90,7 @@ By default, :meth:`~.QuantumCircuit.compose` does not modify the original circui 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. +If you want to insert the qubits and bits into specific positions in the bigger circuit, you can use the ``qubits`` and ``bits`` arguments. The following example joins the two circuits by connecting `q_0` and `q_1` qubits of `qc1` circuit to `q_3` and `q_1` qubits of `qc2` circuit. .. testcode:: From 9f8cd3aad049b49e385fa9a064b5149087e5fc4c Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Tue, 11 Jul 2023 12:35:53 +0200 Subject: [PATCH 43/43] fix indentation --- docs/how_to/create_a_quantum_circuit.rst | 2 ++ docs/how_to/use_sampler.rst | 3 +-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/how_to/create_a_quantum_circuit.rst b/docs/how_to/create_a_quantum_circuit.rst index 12fa877738cd..ca8b27f8760e 100644 --- a/docs/how_to/create_a_quantum_circuit.rst +++ b/docs/how_to/create_a_quantum_circuit.rst @@ -10,6 +10,8 @@ There are two ways to create a :class:`~.QuantumCircuit` object: 1. Initialize :class:`~.QuantumCircuit` by directly specifying the number of qubits and classical bits you want. 2. Creating :class:`~.QuantumRegister`\ s and :class:`~.ClassicalRegister`\ s and use the registers to initialize a :class:`~.QuantumCircuit` +.. _create circuit with qubit numbers: + Create by specifying the number of qubits and classical bits ============================================================ diff --git a/docs/how_to/use_sampler.rst b/docs/how_to/use_sampler.rst index b9a6c6b8223a..e33255630fa5 100644 --- a/docs/how_to/use_sampler.rst +++ b/docs/how_to/use_sampler.rst @@ -67,8 +67,7 @@ Run job 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 :meth:`~qiskit.providers.JobV1.result` method. +:meth:`~qiskit.primitives.Sampler.run` method and then you can get the results (as a :class:`~qiskit.primitives.SamplerResult` object) with the :meth:`~qiskit.providers.JobV1.result` method. .. testcode::