Use cross-references to Terra and QML objects in docstrings (#700)

* quantum_kernel class redirection * Remove TypeError; Add ValueError on C * quantum_kernel class reference * References circuit.library classes * Reference quantum_kernel acceptable types * Fix reference to ZZFeatureMap * Improve reference to Statevector.data * Fix references * Fix quantum_kernel reference * Resolve unnecessary class info * Resolve unnecessary class info * Add condition to default; Harmonize * Resolve unnecessary class info * Fix strict attribute info * Fix wrong class info * Fix typo * Fix missing space Co-authored-by: Steve Wood <40241007+woodsp-ibm@users.noreply.github.com> --------- Co-authored-by: Steve Wood <40241007+woodsp-ibm@users.noreply.github.com>
qiskit-community · Oct 26, 2023 · 299c672 · 299c672
1 parent b4402c2
commit 299c672
Show file tree

Hide file tree

Showing 8 changed files with 30 additions and 24 deletions.
diff --git a/qiskit_machine_learning/algorithms/classifiers/pegasos_qsvc.py b/qiskit_machine_learning/algorithms/classifiers/pegasos_qsvc.py
@@ -67,29 +67,28 @@ def __init__(
     ) -> None:
         """
         Args:
-            quantum_kernel: a quantum kernel to be used for classification. Has to be ``None`` when
-                a precomputed kernel is used.
+            quantum_kernel: A quantum kernel to be used for classification.
+                Has to be ``None`` when a precomputed kernel is used. If None,
+                and ``precomputed`` is ``False``, the quantum kernel will default to
+                :class:`~qiskit_machine_learning.kernels.FidelityQuantumKernel`.
             C: Positive regularization parameter. The strength of the regularization is inversely
                 proportional to C. Smaller ``C`` induce smaller weights which generally helps
                 preventing overfitting. However, due to the nature of this algorithm, some of the
                 computation steps become trivial for larger ``C``. Thus, larger ``C`` improve
                 the performance of the algorithm drastically. If the data is linearly separable
                 in feature space, ``C`` should be chosen to be large. If the separation is not
                 perfect, ``C`` should be chosen smaller to prevent overfitting.
-
-            num_steps: number of steps in the Pegasos algorithm. There is no early stopping
+            num_steps: The number of steps in the Pegasos algorithm. There is no early stopping
                 criterion. The algorithm iterates over all steps.
-            precomputed: a boolean flag indicating whether a precomputed kernel is used. Set it to
+            precomputed: A boolean flag indicating whether a precomputed kernel is used. Set it to
                 ``True`` in case of precomputed kernel.
-            seed: a seed for the random number generator
+            seed: A seed for the random number generator.
 
         Raises:
             ValueError:
                 - if ``quantum_kernel`` is passed and ``precomputed`` is set to ``True``. To use
                 a precomputed kernel, ``quantum_kernel`` has to be of the ``None`` type.
-            TypeError:
-                - if ``quantum_kernel`` neither instance of
-                  :class:`~qiskit_machine_learning.kernels.BaseKernel` nor ``None``.
+                - if C is not a positive number.
         """
 
         if precomputed:

diff --git a/qiskit_machine_learning/algorithms/classifiers/qsvc.py b/qiskit_machine_learning/algorithms/classifiers/qsvc.py
@@ -45,7 +45,9 @@ class QSVC(SVC, SerializableModelMixin):
     def __init__(self, *, quantum_kernel: Optional[BaseKernel] = None, **kwargs):
         """
         Args:
-            quantum_kernel: Quantum kernel to be used for classification.
+            quantum_kernel: A quantum kernel to be used for classification.
+                Has to be ``None`` when a precomputed kernel is used. If None,
+                default to :class:`~qiskit_machine_learning.kernels.FidelityQuantumKernel`.
             *args: Variable length argument list to pass to SVC constructor.
             **kwargs: Arbitrary keyword arguments to pass to SVC constructor.
         """

diff --git a/qiskit_machine_learning/algorithms/classifiers/vqc.py b/qiskit_machine_learning/algorithms/classifiers/vqc.py
@@ -65,11 +65,13 @@ def __init__(
                 The number of qubits in the feature map and ansatz are adjusted to this
                 number if required.
             feature_map: The (parametrized) circuit to be used as a feature map for the underlying
-                QNN. If ``None`` is given, the ``ZZFeatureMap`` is used if the number of qubits
-                is larger than 1. For a single qubit classification problem the ``ZFeatureMap``
+                QNN. If ``None`` is given, the :class:`~qiskit.circuit.library.ZZFeatureMap`
+                is used if the number of qubits is larger than 1. For a single qubit
+                classification problem the :class:`~qiskit.circuit.library.ZFeatureMap`
                 is used by default.
-            ansatz: The (parametrized) circuit to be used as an ansatz for the underlying
-                QNN. If ``None`` is given then the ``RealAmplitudes`` circuit is used.
+            ansatz: The (parametrized) circuit to be used as an ansatz for the underlying QNN.
+                If ``None`` is given then the :class:`~qiskit.circuit.library.RealAmplitudes`
+                circuit is used.
             loss: A target loss function to be used in training. Default value is ``cross_entropy``.
             optimizer: An instance of an optimizer or a callable to be used in training.
                 Refer to :class:`~qiskit_algorithms.optimizers.Minimizer` for more information on

diff --git a/qiskit_machine_learning/algorithms/regressors/qsvr.py b/qiskit_machine_learning/algorithms/regressors/qsvr.py
@@ -44,7 +44,8 @@ class QSVR(SVR, SerializableModelMixin):
     def __init__(self, *, quantum_kernel: Optional[BaseKernel] = None, **kwargs):
         """
         Args:
-            quantum_kernel: Quantum kernel to be used for regression.
+            quantum_kernel: A quantum kernel to be used for regression. If None,
+                default to :class:`~qiskit_machine_learning.kernels.FidelityQuantumKernel`.
             *args: Variable length argument list to pass to SVR constructor.
             **kwargs: Arbitrary keyword arguments to pass to SVR constructor.
         """

diff --git a/qiskit_machine_learning/datasets/ad_hoc.py b/qiskit_machine_learning/datasets/ad_hoc.py
@@ -37,7 +37,7 @@ def ad_hoc_data(
     np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray
 ]:
     r"""Generates a toy dataset that can be fully separated with
-    ``qiskit.circuit.library.ZZ_Feature_Map`` according to the procedure
+    :class:`~qiskit.circuit.library.ZZFeatureMap` according to the procedure
     outlined in [1]. To construct the dataset, we first sample uniformly
     distributed vectors :math:`\vec{x} \in (0, 2\pi]^{n}` and apply the
     feature map

diff --git a/qiskit_machine_learning/kernels/fidelity_statevector_kernel.py b/qiskit_machine_learning/kernels/fidelity_statevector_kernel.py
@@ -40,7 +40,8 @@ class FidelityStatevectorKernel(BaseKernel):
 
         K(x,y) = |\langle \phi(x) | \phi(y) \rangle|^2.
 
-    In this implementation, :math:`|\phi(y)\rangle` is given by a ``Statevector.data`` array. These
+    In this implementation, :math:`|\phi(y)\rangle` is given by the ``data`` attribute of a
+    :class:`~qiskit.quantum_info.Statevector` object or one of its subclasses. These
     arrays are stored in a statevector cache to avoid repeated evaluation of the quantum circuit.
     This cache can be cleared using :meth:`clear_cache`. By default the cache is cleared when
     :meth:`evaluate` is called, unless ``auto_clear_cache`` is ``False``.

diff --git a/qiskit_machine_learning/utils/adjust_num_qubits.py b/qiskit_machine_learning/utils/adjust_num_qubits.py
@@ -30,16 +30,17 @@ def derive_num_qubits_feature_map_ansatz(
     Derives a correct number of qubits, feature map, and ansatz from the parameters.
 
     If the number of qubits is not ``None``, then the feature map and ansatz are adjusted to this
-    number of qubits if required. If such an adjustment fails, an error is raised.
-    Also, if the feature map or ansatz or both are ``None``, then ``ZZFeatureMap`` and
-    ``RealAmplitudes`` are created respectively. If there's just one qubit, ``ZFeatureMap`` is
-    created instead.
+    number of qubits if required. If such an adjustment fails, an error is raised. Also, if the
+    feature map or ansatz or both are ``None``, then :class:`~qiskit.circuit.library.ZZFeatureMap`
+    and :class:`~qiskit.circuit.library.RealAmplitudes` are created respectively. If there's just
+    one qubit, :class:`~qiskit.circuit.library.ZFeatureMap` is created instead.
 
     If the number of qubits is ``None``, then the number of qubits is derived from the feature map
     or ansatz. Both the feature map and ansatz in this case must have the same number of qubits.
     If the number of qubits of the feature map is not the same as the number of qubits of
     the ansatz, an error is raised. If only one of the feature map and ansatz are ``None``, then
-    ``ZZFeatureMap`` or ``RealAmplitudes`` are created respectively.
+    :class:`~qiskit.circuit.library.ZZFeatureMap` or :class:`~qiskit.circuit.library.RealAmplitudes`
+    are created respectively.
 
     If all the parameters are none an error is raised.
 

diff --git a/qiskit_machine_learning/utils/loss_functions/kernel_loss_functions.py b/qiskit_machine_learning/utils/loss_functions/kernel_loss_functions.py
@@ -54,8 +54,8 @@ def evaluate(
         An abstract method for evaluating the loss of a kernel function on a labeled dataset.
 
         Args:
-            parameter_values: an array of values to assign to the user params
-            quantum_kernel: A ``QuantumKernel`` object to evaluate
+            parameter_values: An array of values to assign to the user params
+            quantum_kernel: A trainable quantum kernel object to evaluate
             data: An ``(N, M)`` matrix containing the data
                     ``N = # samples, M = dimension of data``
             labels: A length-N array containing the truth labels