Doc fix ZZ_feature_maps (Qiskit#13231)

* initial formatting changes

* .compose used for concatination of two circuits

* updated docstring data property

* updated entanglement_blocks docstring

* updated docstring of num_parameters

* updates docstring of parameters

* update _zz_feature_map.py documentation

* update changes to ZZ_Feature_Map

* update doc strings matched with parent class

* _zz_feature_map.py reformatted

qiskit/circuit/library/blueprintcircuit.py

@@ -94,6 +94,12 @@ def qregs(self, qregs):
 
     @property
     def data(self):
+        """The circuit data (instructions and context).
+
+        Returns:
+            QuantumCircuitData: a list-like object containing the :class:`.CircuitInstruction`\\ s
+            for each instruction.
+        """
         if not self._is_built:
             self._build()
         return super().data
@@ -110,12 +116,70 @@ def draw(self, *args, **kwargs):
 
     @property
     def num_parameters(self) -> int:
+        """The number of parameter objects in the circuit."""
         if not self._is_built:
             self._build()
         return super().num_parameters
 
     @property
     def parameters(self) -> ParameterView:
+        """The parameters defined in the circuit.
+
+        This attribute returns the :class:`.Parameter` objects in the circuit sorted
+        alphabetically. Note that parameters instantiated with a :class:`.ParameterVector`
+        are still sorted numerically.
+
+        Examples:
+
+            The snippet below shows that insertion order of parameters does not matter.
+
+            .. code-block:: python
+
+                >>> from qiskit.circuit import QuantumCircuit, Parameter
+                >>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant")
+                >>> circuit = QuantumCircuit(1)
+                >>> circuit.rx(b, 0)
+                >>> circuit.rz(elephant, 0)
+                >>> circuit.ry(a, 0)
+                >>> circuit.parameters  # sorted alphabetically!
+                ParameterView([Parameter(a), Parameter(b), Parameter(elephant)])
+
+            Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers.
+            The literal "10" comes before "2" in strict alphabetical sorting.
+
+            .. code-block:: python
+
+                >>> from qiskit.circuit import QuantumCircuit, Parameter
+                >>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")]
+                >>> circuit = QuantumCircuit(1)
+                >>> circuit.u(*angles, 0)
+                >>> circuit.draw()
+                   ┌─────────────────────────────┐
+                q: ┤ U(angle_1,angle_2,angle_10) ├
+                   └─────────────────────────────┘
+                >>> circuit.parameters
+                ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)])
+
+            To respect numerical sorting, a :class:`.ParameterVector` can be used.
+
+            .. code-block:: python
+
+                >>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector
+                >>> x = ParameterVector("x", 12)
+                >>> circuit = QuantumCircuit(1)
+                >>> for x_i in x:
+                ...     circuit.rx(x_i, 0)
+                >>> circuit.parameters
+                ParameterView([
+                    ParameterVectorElement(x[0]), ParameterVectorElement(x[1]),
+                    ParameterVectorElement(x[2]), ParameterVectorElement(x[3]),
+                    ..., ParameterVectorElement(x[11])
+                ])
+
+
+        Returns:
+            The sorted :class:`.Parameter` objects in the circuit.
+        """
         if not self._is_built:
             self._build()
         return super().parameters

qiskit/circuit/library/data_preparation/_zz_feature_map.py

@@ -38,38 +38,60 @@ class ZZFeatureMap(PauliFeatureMap):
 
     Examples:
 
-        >>> from qiskit.circuit.library import ZZFeatureMap
-        >>> prep = ZZFeatureMap(2, reps=1)
-        >>> print(prep.decompose())
-             ┌───┐┌─────────────┐
-        q_0: ┤ H ├┤ P(2.0*x[0]) ├──■──────────────────────────────────────■──
-             ├───┤├─────────────┤┌─┴─┐┌────────────────────────────────┐┌─┴─┐
-        q_1: ┤ H ├┤ P(2.0*x[1]) ├┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├
-             └───┘└─────────────┘└───┘└────────────────────────────────┘└───┘
-
-        >>> from qiskit.circuit.library import EfficientSU2
-        >>> classifier = ZZFeatureMap(3) + EfficientSU2(3)
-        >>> classifier.num_parameters
-        15
-        >>> classifier.parameters  # 'x' for the data preparation, 'θ' for the SU2 parameters
-        ParameterView([
-            ParameterVectorElement(x[0]), ParameterVectorElement(x[1]),
-            ParameterVectorElement(x[2]), ParameterVectorElement(θ[0]),
-            ParameterVectorElement(θ[1]), ParameterVectorElement(θ[2]),
-            ParameterVectorElement(θ[3]), ParameterVectorElement(θ[4]),
-            ParameterVectorElement(θ[5]), ParameterVectorElement(θ[6]),
-            ParameterVectorElement(θ[7]), ParameterVectorElement(θ[8]),
-            ParameterVectorElement(θ[9]), ParameterVectorElement(θ[10]),
-            ParameterVectorElement(θ[11]), ParameterVectorElement(θ[12]),
-            ParameterVectorElement(θ[13]), ParameterVectorElement(θ[14]),
-            ParameterVectorElement(θ[15]), ParameterVectorElement(θ[16]),
-            ParameterVectorElement(θ[17]), ParameterVectorElement(θ[18]),
-            ParameterVectorElement(θ[19]), ParameterVectorElement(θ[20]),
-            ParameterVectorElement(θ[21]), ParameterVectorElement(θ[22]),
-            ParameterVectorElement(θ[23])
-        ])
-        >>> classifier.count_ops()
+    .. code-block::
+
+         from qiskit.circuit.library import ZZFeatureMap
+         prep = ZZFeatureMap(2, reps=1)
+         print(prep.decompose())
+
+    .. parsed-literal::
+              ┌───┐┌─────────────┐
+         q_0: ┤ H ├┤ P(2.0*x[0]) ├──■──────────────────────────────────────■──
+              ├───┤├─────────────┤┌─┴─┐┌────────────────────────────────┐┌─┴─┐
+         q_1: ┤ H ├┤ P(2.0*x[1]) ├┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├
+              └───┘└─────────────┘└───┘└────────────────────────────────┘└───┘
+
+    .. code-block::
+
+         from qiskit.circuit.library import EfficientSU2
+         classifier = ZZFeatureMap(3).compose(EfficientSU2(3))
+         classifier.num_parameters
+
+    .. parsed-literal::
+
+         27
+
+    .. code-block::
+
+         classifier.parameters  # 'x' for the data preparation, 'θ' for the SU2 parameters
+
+    .. parsed-literal::
+
+         ParameterView([
+             ParameterVectorElement(x[0]), ParameterVectorElement(x[1]),
+             ParameterVectorElement(x[2]), ParameterVectorElement(θ[0]),
+             ParameterVectorElement(θ[1]), ParameterVectorElement(θ[2]),
+             ParameterVectorElement(θ[3]), ParameterVectorElement(θ[4]),
+             ParameterVectorElement(θ[5]), ParameterVectorElement(θ[6]),
+             ParameterVectorElement(θ[7]), ParameterVectorElement(θ[8]),
+             ParameterVectorElement(θ[9]), ParameterVectorElement(θ[10]),
+             ParameterVectorElement(θ[11]), ParameterVectorElement(θ[12]),
+             ParameterVectorElement(θ[13]), ParameterVectorElement(θ[14]),
+             ParameterVectorElement(θ[15]), ParameterVectorElement(θ[16]),
+             ParameterVectorElement(θ[17]), ParameterVectorElement(θ[18]),
+             ParameterVectorElement(θ[19]), ParameterVectorElement(θ[20]),
+             ParameterVectorElement(θ[21]), ParameterVectorElement(θ[22]),
+             ParameterVectorElement(θ[23])
+         ])
+
+    .. code-block::
+
+         classifier.count_ops()
+
+    .. parsed-literal::
+
         OrderedDict([('ZZFeatureMap', 1), ('EfficientSU2', 1)])
+
     """
 
     @deprecate_func(

qiskit/circuit/library/data_preparation/pauli_feature_map.py

@@ -522,6 +522,11 @@ def alpha(self, alpha: float) -> None:
 
     @property
     def entanglement_blocks(self):
+        """The blocks in the entanglement layers.
+
+        Returns:
+            The blocks in the entanglement layers.
+        """
         return [self.pauli_block(pauli) for pauli in self._paulis]
 
     @entanglement_blocks.setter