Added how-to guides

docs/how_to.rst

@@ -0,0 +1,16 @@
+.. _how_to:
+
+======
+How to
+======
+
+Create quantum circuits
+-----------------------
+
+.. toctree::
+  :maxdepth: 1
+
+  Create a quantum circuit <how_to/create_a_quantum_circuit>
+  Compose quantum circuits <how_to/compose_quantum_circuits>
+  Visualize a quantum circuit <how_to/visualize_a_quantum_circuit>
+  Create a parameterized circuit <how_to/create_a_parameterized_circuit>

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(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()`
+
+.. jupyter-execute::
+
+    qc2.decompose().draw()
+
+
+.. jupyter-execute::
+
+    import qiskit.tools.jupyter
+    %qiskit_version_table
+    %qiskit_copyright
+
+
+

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

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
+

docs/how_to/visualize_a_quantum_circuit.rst

@@ -0,0 +1,97 @@
+===========================
+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 <https://en.wikipedia.org/wiki/ASCII_art>`_ 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 <https://matplotlib.org/>`_ to render the circuit.
+* ``'latex'``: uses :math:`\LaTeX` to render the circuit. It requires a full `LaTeX <https://latex.org/forum/>`_ distribution and the package ``pdflatex``.
+* ``'latex_source'``: outputs the :math:`\LaTeX` source code that creates the ``'latex'`` rendering of the circuit.
+
+Because this optional or keyword argument is actually the first of this method, one can type ``qc.draw(option)`` instead of ``qc.draw(output=option)``.
+
+.. note::
+    By default, the ``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_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 :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.
+
+
+.. jupyter-execute::
+
+    from qiskit.visualization import circuit_drawer
+
+    circuit_drawer(qc, output='mpl')
+
+.. jupyter-execute::
+
+    import qiskit.tools.jupyter
+    %qiskit_version_table
+    %qiskit_copyright