Added how-to guides

docs/how_to/compose_quantum_circuits.rst

@@ -0,0 +1,184 @@
+#####################
+Join quantum circuits
+#####################
+
+This guide shows you how to combine different :class:`~.QuantumCircuit` objects.
+
+Create the circuits
+===================
+
+Let's first create two circuits, which will be joined together.
+
+.. testcode::
+
+    from qiskit import QuantumCircuit
+
+    qc1 = QuantumCircuit(2,1)
+    qc1.h(0)
+    qc1.cx(0,1)
+    qc1.measure(1,0)
+
+    qc2 = QuantumCircuit(4,2)
+    qc2.y(0)
+    qc2.x(1)
+    qc2.cx(0,3)
+    qc2.measure(3,1)
+
+    print(qc1.draw()) 
+    print(qc2.draw())
+
+.. testoutput::
+    :options: +NORMALIZE_WHITESPACE
+
+         ┌───┐        
+    q_0: ┤ H ├──■─────
+         └───┘┌─┴─┐┌─┐
+    q_1: ─────┤ X ├┤M├
+              └───┘└╥┘
+    c: 1/═══════════╩═
+                    0 
+         ┌───┐        
+    q_0: ┤ Y ├──■─────
+         ├───┤  │     
+    q_1: ┤ X ├──┼─────
+         └───┘  │     
+    q_2: ───────┼─────
+              ┌─┴─┐┌─┐
+    q_3: ─────┤ X ├┤M├
+              └───┘└╥┘
+    c: 2/═══════════╩═
+                    1 
+
+Join the circuits
+=================
+
+You can join the circuits together using these two methods:
+
+1. Using the :meth:`~.QuantumCircuit.compose` method
+2. Using the :meth:`~.QuantumCircuit.append` method
+
+.. warning::
+
+     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 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
+-------------------------------------------------
+
+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 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::
+
+    qc3 = qc2.compose(qc1)
+    print(qc3.draw())
+
+.. testoutput::
+    :options: +NORMALIZE_WHITESPACE
+
+         ┌───┐     ┌───┐        
+    q_0: ┤ Y ├──■──┤ H ├──■─────
+         ├───┤  │  └───┘┌─┴─┐┌─┐
+    q_1: ┤ X ├──┼───────┤ X ├┤M├
+         └───┘  │       └───┘└╥┘
+    q_2: ───────┼─────────────╫─
+              ┌─┴─┐ ┌─┐       ║ 
+    q_3: ─────┤ X ├─┤M├───────╫─
+              └───┘ └╥┘       ║ 
+    c: 2/════════════╩════════╩═
+                     1        0 
+
+If you want to insert the qubits and bits into specific positions in the bigger circuit, you can use the ``qubits`` and ``bits`` arguments. 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::
+
+    qc4 = qc2.compose(qc1, qubits=[3,1], clbits=[1])
+    print(qc4.draw())
+
+.. testoutput::
+    :options: +NORMALIZE_WHITESPACE
+
+         ┌───┐                     
+    q_0: ┤ Y ├──■──────────────────
+         ├───┤  │          ┌───┐┌─┐
+    q_1: ┤ X ├──┼──────────┤ X ├┤M├
+         └───┘  │          └─┬─┘└╥┘
+    q_2: ───────┼────────────┼───╫─
+              ┌─┴─┐┌─┐┌───┐  │   ║ 
+    q_3: ─────┤ X ├┤M├┤ H ├──■───╫─
+              └───┘└╥┘└───┘      ║ 
+    c: 2/═══════════╩════════════╩═
+                    1            1 
+
+You can also join the smaller circuit in front of the bigger circuit by setting the ``front`` argument to ``True``.
+
+.. testcode::
+
+    qc5 = qc2.compose(qc1, front=True)
+    print(qc5.draw())
+
+.. testoutput::
+    :options: +NORMALIZE_WHITESPACE
+
+         ┌───┐     ┌───┐             
+    q_0: ┤ H ├──■──┤ Y ├───────■─────
+         └───┘┌─┴─┐└┬─┬┘┌───┐  │     
+    q_1: ─────┤ X ├─┤M├─┤ X ├──┼─────
+              └───┘ └╥┘ └───┘  │     
+    q_2: ────────────╫─────────┼─────
+                     ║       ┌─┴─┐┌─┐
+    q_3: ────────────╫───────┤ X ├┤M├
+                     ║       └───┘└╥┘
+    c: 2/════════════╩═════════════╩═
+                     0             1 
+
+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, 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 it is applied to, instead of returning a new circuit.
+
+.. testcode::
+
+    qc2.append(qc1, qargs=[3,1], cargs=[1])
+    qc2.draw(cregbundle=False)
+
+.. code-block:: text
+
+         ┌───┐                        
+    q_0: ┤ Y ├──■─────────────────────
+         ├───┤  │     ┌──────────────┐
+    q_1: ┤ X ├──┼─────┤1             ├
+         └───┘  │     │              │
+    q_2: ───────┼─────┤              ├
+              ┌─┴─┐┌─┐│              │
+    q_3: ─────┤ X ├┤M├┤0 circuit-101 ├
+              └───┘└╥┘│              │
+    c_0: ═══════════╬═╡              ╞
+                    ║ │              │
+    c_1: ═══════════╩═╡0             ╞
+                      └──────────────┘
+
+Unlike :meth:`~.QuantumCircuit.compose`, :meth:`~.QuantumCircuit.append` turns the smaller circuit into a single :class:`~qiskit.circuit.Instruction`. If you prefer joining the circuits using the individual gates, you can use :meth:`~.QuantumCircuit.decompose` to decompose the joint circuit.
+
+.. 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 

docs/how_to/create_a_parameterized_circuit.rst

@@ -0,0 +1,114 @@
+######################################
+Create a parameterized quantum circuit
+######################################
+
+This guide will show how to create a :class:`~.QuantumCircuit` that includes parameters.
+
+Define the parameters
+=====================
+
+In order to define a parameter, you need to create a :class:`~.Parameter` object. To do that you only need to choose a ``name``, which can be any unicode string like ``'θ'``.
+
+.. testcode::
+
+    from qiskit.circuit import Parameter
+
+    theta = Parameter('θ')
+
+
+Create the parameterized circuit
+================================
+
+When creating the circuit you can include the :class:`~.Parameter` you just created the same as if it was a defined number.
+
+.. testcode::
+
+    from qiskit import QuantumCircuit
+
+    qc = QuantumCircuit(1)
+    qc.rx(theta, 0)
+    print(qc.draw())
+
+.. testoutput::
+    :options: +NORMALIZE_WHITESPACE
+
+       ┌───────┐
+    q: ┤ Rx(θ) ├
+       └───────┘
+
+
+Assign values to parameters
+===========================
+
+You can use these two methods to assign values to the :class:`~.Parameter`\ s in your circuit:
+
+* :meth:`~.QuantumCircuit.bind_parameters` 
+* :meth:`~.QuantumCircuit.assign_parameters` 
+
+:meth:`~.QuantumCircuit.bind_parameters`
+--------------------------------------------------------
+
+In order to use this method, you have to specify either a dictionary of the form ``{parameter: value,...}`` or an iterable formed only by numeric values. If using only numeric values they will be bound to their corresponding parameters in according to the order in  :attr:`~.QuantumCircuit.parameters`.
+
+.. testcode::
+
+    import numpy as np
+
+    theta_values = [0, np.pi/2, np.pi]
+    qc_bind_list = [qc.bind_parameters({theta: theta_value}) for theta_value in theta_values]
+
+    for i in range(3):
+        print(qc_bind_list[i].draw())
+
+.. testoutput::
+    :options: +NORMALIZE_WHITESPACE
+
+       ┌───────┐
+    q: ┤ Rx(0) ├
+       └───────┘
+       ┌─────────┐
+    q: ┤ Rx(π/2) ├
+       └─────────┘
+       ┌───────┐
+    q: ┤ Rx(π) ├
+       └───────┘
+
+:meth:`~.QuantumCircuit.assign_parameters`
+----------------------------------------------------------
+
+This method works identically like :meth:`~.QuantumCircuit.bind_parameters`  except that you can also assign other :class:`~.Parameter` objects instead of only numbers to the :class:`~.Parameter`\ s in your circuit.
+
+.. testcode::
+
+    phi = Parameter('ϕ')
+
+    theta_values = [np.pi/2, phi]
+    qc_assign_list = [qc.assign_parameters({theta: theta_value}) for theta_value in theta_values]
+
+    for i in range(2):
+        print(qc_assign_list[i].draw())
+
+.. testoutput::
+    :options: +NORMALIZE_WHITESPACE
+
+       ┌─────────┐
+    q: ┤ Rx(π/2) ├
+       └─────────┘
+       ┌───────┐
+    q: ┤ Rx(ϕ) ├
+       └───────┘
+
+
+Another difference between :meth:`~.QuantumCircuit.bind_parameters` and :meth:`~.QuantumCircuit.assign_parameters` is that for the latter, you can make it change your original circuit instead of creating a new one by setting the ``inplace`` argument to ``True``.
+
+.. testcode::
+
+    qc.assign_parameters({theta: np.pi/4}, inplace=True)
+    print(qc.draw())
+
+.. testoutput::
+    :options: +NORMALIZE_WHITESPACE
+
+       ┌─────────┐
+    q: ┤ Rx(π/4) ├
+       └─────────┘