Add examples for the NLocal class docstrings (#9080)

qiskit/circuit/library/n_local/n_local.py

@@ -66,6 +66,77 @@ class NLocal(BlueprintCircuit):
 
     If specified, barriers can be inserted in between every block.
     If an initial state object is provided, it is added in front of the NLocal.
+
+    Examples:
+
+        Example 1:
+            * "Blocks" are defined by ``QuantumCircuit`` objects.
+            * The "basic rotation block" consists of a 1-depth 2-qubits ``QuantumCircuit`` object.
+            * The "basic entanglement block" consists of a 3-depth 4-qubits ``QuantumCircuit`` object.
+            * Every "rotation layer" consists of a vertical repetition over the basic rotation block.
+            * Every "entanglement layer" consists of a ``linear`` repetition over
+            the basic entanglement block.
+
+        .. jupyter-execute::
+
+            from qiskit import QuantumCircuit
+            from qiskit.circuit import ParameterVector
+            from qiskit.circuit.library import NLocal
+
+            num_qubits = 6
+
+            # Basic rotation block pre-setting
+            num_qubits_rot_block = 2
+            theta = ParameterVector(name="theta", length=num_qubits_rot_block)
+            rot_block = QuantumCircuit(num_qubits_rot_block)
+            rot_block.ry(theta[0], 0)
+            rot_block.rx(theta[1], 1)
+
+            # Basic entanglement block pre-setting
+            num_qubits_ent_block = 4
+            ent_block = QuantumCircuit(num_qubits_ent_block)
+            for i in range(num_qubits_ent_block - 1):
+                ent_block.cx(i, i + 1)
+
+            # Assembling the pre-defined blocks into layers that form an `NLocal` circuit
+            nloc = NLocal(
+                num_qubits,
+                rotation_blocks=rot_block,
+                entanglement_blocks=ent_block,
+                entanglement="linear",
+                insert_barriers=True
+            )
+
+            display(nloc.decompose().draw(output="mpl"))
+
+        Example 2:
+            * "Blocks" are defined directly by lists of (inherited) ``Gate`` objects.
+            * The "basic rotation block" consists of an $R_y$ gate followed by an $R_x$.
+            * The "basic entanglement block" consists of a single $CZ$ gate.
+            * Every "rotation layer" consists of a vertical repetition over the basic rotation block.
+            * Every "entanglement layer" consists of a ``circular`` repetition over
+            the basic entanglement block.
+
+        .. jupyter-execute::
+
+            from qiskit.circuit import Parameter, ParameterVector
+            from qiskit.circuit.library import NLocal, RYGate, RXGate, CZGate
+
+            num_qubits = 4
+            theta = Parameter("theta")
+
+            nloc = NLocal(
+                num_qubits,
+                rotation_blocks=[RYGate(theta), RXGate(theta)],
+                entanglement_blocks=[CZGate()],
+                entanglement="circular",
+                insert_barriers=True,
+                reps=2,
+                skip_final_rotation_layer=True
+            )
+
+            display(nloc.decompose().draw(output="mpl"))
+
     """
 
     def __init__(
@@ -91,7 +162,7 @@ def __init__(
         initial_state: QuantumCircuit | None = None,
         name: str | None = "nlocal",
     ) -> None:
-        """Create a new n-local circuit.
+        """
 
         Args:
             num_qubits: The number of qubits of the circuit.
@@ -115,9 +186,6 @@ def __init__(
                 state prepended to the NLocal circuit.
             name: The name of the circuit.
 
-        Examples:
-            TODO
-
         Raises:
             ValueError: If ``reps`` parameter is less than or equal to 0.
             TypeError: If ``reps`` parameter is not an int value.