[Docs] Fix TOCs and update QNN derived primitives (#862)

* Fix docs and update QNN derived primitives

* Fix LearningRate in TOCs

* Fix string formatting

* Fix spelling

* Fix spelling

* Fix spelling

* Fix copyright

(cherry picked from commit 698b9f0)

Author: edoaltamura

.pylintdict

@@ -123,6 +123,7 @@ dp
 dt
 dω
 eda
+edaspy
 egger
 eigen
 eigenphase
@@ -576,6 +577,7 @@ vatan
 vec
 vectorized
 veeravalli
+vicente
 vicentini
 vigo
 ville

docs/apidocs/qiskit_machine_learning.gradients.rst

@@ -0,0 +1,6 @@
+.. _qiskit-machine-learning-gradients:
+
+.. automodule:: qiskit_machine_learning.gradients
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/qiskit_machine_learning.optimizers.rst

@@ -0,0 +1,6 @@
+.. _qiskit-machine-learning-optimizers:
+
+.. automodule:: qiskit_machine_learning.optimizers
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/qiskit_machine_learning.state_fidelities.rst

@@ -0,0 +1,6 @@
+.. _qiskit-machine-learning-state_fidelities:
+
+.. automodule:: qiskit_machine_learning.state_fidelities
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

qiskit_machine_learning/__init__.py

@@ -37,8 +37,11 @@
    circuit.library
    connectors
    datasets
+   gradients
    kernels
    neural_networks
+   optimizers
+   state_fidelities
    utils
 
 """

qiskit_machine_learning/algorithms/__init__.py

@@ -53,18 +53,8 @@
 
    PegasosQSVC
    QSVC
-   NeuralNetworkClassifier
    VQC
-
-Inference
-+++++++++++
-Algorithms for inference.
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   QBayesian
+   NeuralNetworkClassifier
 
 Regressors
 ++++++++++
@@ -75,9 +65,18 @@
    :nosignatures:
 
    QSVR
-   NeuralNetworkRegressor
    VQR
+   NeuralNetworkRegressor
+
+Inference
++++++++++++
+Algorithms for inference.
 
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   QBayesian
 """
 from .trainable_model import TrainableModel
 from .serializable_model import SerializableModelMixin

qiskit_machine_learning/algorithms/trainable_model.py

@@ -32,7 +32,7 @@
 
 
 class TrainableModel(SerializableModelMixin):
-    """Base class for ML model that defines a scikit-learn like interface for Estimators."""
+    """Base class for ML model that defines a scikit-learn-like interface for `Estimator` instances."""
 
     # pylint: disable=too-many-positional-arguments
     def __init__(
@@ -46,10 +46,10 @@ def __init__(
     ):
         """
         Args:
-            neural_network: An instance of an quantum neural network. If the neural network has a
+            neural_network: An instance of a quantum neural network. If the neural network has a
                 one-dimensional output, i.e., `neural_network.output_shape=(1,)`, then it is
                 expected to return values in [-1, +1] and it can only be used for binary
-                classification. If the output is multi-dimensional, it is assumed that the result
+                classification. If the output is multidimensional, it is assumed that the result
                 is a probability distribution, i.e., that the entries are non-negative and sum up
                 to one. Then there are two options, either one-hot encoding or not. In case of
                 one-hot encoding, each probability vector resulting a neural network is considered

qiskit_machine_learning/circuit/library/__init__.py

@@ -1,6 +1,6 @@
 # This code is part of a Qiskit project.
 #
-# (C) Copyright IBM 2020, 2023.
+# (C) Copyright IBM 2020, 2024.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -19,7 +19,7 @@
 
 .. currentmodule:: qiskit_machine_learning.circuit.library
 
-Feature Maps
+Feature maps
 ------------
 
 .. autosummary::
@@ -29,7 +29,7 @@
 
    RawFeatureVector
 
-Helper Circuits
+Helper circuits
 ---------------
 
 .. autosummary::

qiskit_machine_learning/connectors/__init__.py

@@ -1,6 +1,6 @@
 # This code is part of a Qiskit project.
 #
-# (C) Copyright IBM 2021, 2023.
+# (C) Copyright IBM 2021, 2024.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -14,7 +14,7 @@
 Connectors (:mod:`qiskit_machine_learning.connectors`)
 ======================================================
 
-Connectors from Qiskit Machine Learning to other frameworks.
+"Connector" tools to couple Qiskit Machine Learning to other frameworks.
 
 .. currentmodule:: qiskit_machine_learning.connectors
 

qiskit_machine_learning/datasets/__init__.py

@@ -1,6 +1,6 @@
 # This code is part of a Qiskit project.
 #
-# (C) Copyright IBM 2019, 2023.
+# (C) Copyright IBM 2019, 2024.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -14,7 +14,7 @@
 Datasets (:mod:`qiskit_machine_learning.datasets`)
 ==================================================
 
-A set of sample datasets suitable for machine learning problems
+A set of sample datasets to test machine learning algorithms.
 
 .. currentmodule:: qiskit_machine_learning.datasets
 

qiskit_machine_learning/gradients/__init__.py

@@ -10,10 +10,11 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
+r"""
 Gradients (:mod:`qiskit_machine_learning.gradients`)
-==============================================
-Algorithms to calculate the gradient of a quantum circuit.
+====================================================
+
+Algorithms to calculate the gradient of a cost landscape to optimize a given objective function.
 
 .. currentmodule:: qiskit_machine_learning.gradients
 
@@ -29,7 +30,7 @@
    EstimatorGradientResult
    SamplerGradientResult
 
-Linear Combination of Unitaries
+Linear combination of unitaries
 -------------------------------
 
 .. autosummary::
@@ -39,7 +40,7 @@
    LinCombEstimatorGradient
    LinCombSamplerGradient
 
-Parameter Shift Rules
+Parameter-shift rules
 ---------------------
 
 .. autosummary::
@@ -49,7 +50,7 @@
    ParamShiftEstimatorGradient
    ParamShiftSamplerGradient
 
-Simultaneous Perturbation Stochastic Approximation
+Simultaneous perturbation stochastic approximation
 --------------------------------------------------
 
 .. autosummary::

qiskit_machine_learning/neural_networks/__init__.py

@@ -1,6 +1,6 @@
 # This code is part of a Qiskit project.
 #
-# (C) Copyright IBM 2019, 2023.
+# (C) Copyright IBM 2019, 2024.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -36,7 +36,7 @@
 
    NeuralNetwork
 
-Neural Networks
+Neural networks
 ---------------
 
 .. autosummary::
@@ -46,8 +46,8 @@
    EstimatorQNN
    SamplerQNN
 
-Neural Network Metrics
-----------------------
+Metrics for neural networks
+---------------------------
 
 .. autosummary::
    :toctree: ../stubs/

qiskit_machine_learning/neural_networks/estimator_qnn.py

@@ -120,16 +120,25 @@ def __init__(
     ):
         r"""
         Args:
-            estimator: The estimator used to compute neural network's results.
-                If ``None``, a default instance of the reference estimator,
-                :class:`~qiskit.primitives.Estimator`, will be used.
             circuit: The quantum circuit to represent the neural network. If a
                 :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is passed, the
-                `input_params` and `weight_params` do not have to be provided, because these two
+                ``input_params`` and ``weight_params`` do not have to be provided, because these two
                 properties are taken from the
                 :class:`~qiskit_machine_learning.circuit.library.QNNCircuit`.
+            estimator: The estimator used to compute neural network's results.
+                If ``None``, a default instance of the reference estimator,
+                :class:`~qiskit.primitives.Estimator`, will be used.
+
+                .. warning::
+
+                    The assignment ``estimator=None`` defaults to using
+                    :class:`~qiskit.primitives.Estimator`, which points to a deprecated estimator V1
+                    (as of Qiskit 1.2). ``EstimatorQNN`` will adopt Estimator V2 as default no later than
+                    Qiskit Machine Learning 0.9.
+
             observables: The observables for outputs of the neural network. If ``None``,
-                use the default :math:`Z^{\otimes num\_qubits}` observable.
+                use the default :math:`Z^{\otimes n}` observable, where :math:`n`
+                is the number of qubits.
             input_params: The parameters that correspond to the input data of the network.
                 If ``None``, the input data is not bound to any parameters.
                 If a :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is provided the
@@ -139,9 +148,10 @@ def __init__(
                 If ``None``, the weights are not bound to any parameters.
                 If a :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is provided the
                 `weight_params` value here is ignored. Instead, the value is taken from the
-                :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` weight_parameters.
+                `weight_parameters` associated with
+                :class:`~qiskit_machine_learning.circuit.library.QNNCircuit`.
             gradient: The estimator gradient to be used for the backward pass.
-                If None, a default instance of the estimator gradient,
+                If ``None``, a default instance of the estimator gradient,
                 :class:`~qiskit_machine_learning.gradients.ParamShiftEstimatorGradient`, will be used.
             input_gradients: Determines whether to compute gradients with respect to input data.
                 Note that this parameter is ``False`` by default, and must be explicitly set to
@@ -152,7 +162,6 @@ def __init__(
                 Defaults to ``None``, as some primitives do not need transpiled circuits.
         Raises:
             QiskitMachineLearningError: Invalid parameter values.
-            QiskitMachineLearningError: Gradient is required if
         """
         if estimator is None:
             estimator = Estimator()

qiskit_machine_learning/neural_networks/sampler_qnn.py

@@ -143,39 +143,52 @@ def __init__(
         input_gradients: bool = False,
         pass_manager: BasePassManager | None = None,
     ):
-        """
-        Args: sampler: The sampler primitive used to compute the neural network's results. If
-        ``None`` is given, a default instance of the reference sampler defined by
-        :class:`~qiskit.primitives.Sampler` will be used. circuit: The parametrized quantum
-        circuit that generates the samples of this network. If a
-        :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is passed,
-        the `input_params` and `weight_params` do not have to be provided, because these two
-        properties are taken from the :class:`~qiskit_machine_learning.circuit.library.QNNCircuit
-        `. input_params: The parameters of the circuit corresponding to the input. If a
-        :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is provided the
-        `input_params` value here is ignored. Instead, the value is taken from the
-        :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` input_parameters.
-        weight_params: The parameters of the circuit corresponding to the trainable weights. If a
-        :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is provided the
-        `weight_params` value here is ignored. Instead, the value is taken from the
-        :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` weight_parameters. sparse:
-        Returns whether the output is sparse or not. interpret: A callable that maps the measured
-        integer to another unsigned integer or tuple of unsigned integers. These are used as new
-        indices for the (potentially sparse) output array. If no interpret function is passed,
-        then an identity function will be used by this neural network. output_shape: The output
-        shape of the custom interpretation. For SamplerV1, it is ignored if no custom interpret
-        method is provided where the shape is taken to be ``2^circuit.num_qubits``. gradient: An
-        optional sampler gradient to be used for the backward pass. If ``None`` is given,
-        a default instance of
-        :class:`~qiskit_machine_learning.gradients.ParamShiftSamplerGradient` will be used.
-        input_gradients: Determines whether to compute gradients with respect to input data. Note
-        that this parameter is ``False`` by default, and must be explicitly set to ``True`` for a
-        proper gradient computation when using
-        :class:`~qiskit_machine_learning.connectors.TorchConnector`.
-        pass_manager: The pass manager to transpile the circuits, if necessary.
-        Defaults to ``None``, as some primitives do not need transpiled circuits.
+        r"""
+        Args:
+            circuit: The parametrized quantum
+                circuit that generates the samples of this network. If a
+                :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is passed,
+                the `input_params` and `weight_params` do not have to be provided, because these two
+                properties are taken from the
+                :class:`~qiskit_machine_learning.circuit.library.QNNCircuit`.
+            sampler: The sampler primitive used to compute the neural network's results. If
+                ``None`` is given, a default instance of the reference sampler defined by
+                :class:`~qiskit.primitives.Sampler` will be used.
+
+                .. warning::
+
+                    The assignment ``sampler=None`` defaults to using
+                    :class:`~qiskit.primitives.Sampler`, which points to a deprecated Sampler V1
+                    (as of Qiskit 1.2). ``SamplerQNN`` will adopt Sampler V2 as default no later than
+                    Qiskit Machine Learning 0.9.
+
+            input_params: The parameters of the circuit corresponding to the input. If a
+                :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is provided the
+                `input_params` value here is ignored. Instead, the value is taken from the
+                :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` input_parameters.
+            weight_params: The parameters of the circuit corresponding to the trainable weights. If a
+                :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is provided the
+                `weight_params` value here is ignored. Instead, the value is taken from the
+                :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` ``weight_parameters``.
+            sparse: Returns whether the output is sparse or not.
+            interpret: A callable that maps the measured integer to another unsigned integer or tuple
+                of unsigned integers. These are used as new indices for the (potentially sparse)
+                output array. If no interpret function is passed, then an identity function will be
+                used by this neural network.
+            output_shape: The output shape of the custom interpretation. For SamplerV1, it is ignored
+                if no custom interpret method is provided where the shape is taken to be
+                ``2^circuit.num_qubits``.
+            gradient: An optional sampler gradient to be used for the backward pass. If ``None`` is
+                given, a default instance of
+                :class:`~qiskit_machine_learning.gradients.ParamShiftSamplerGradient` will be used.
+            input_gradients: Determines whether to compute gradients with respect to input data. Note
+                that this parameter is ``False`` by default, and must be explicitly set to ``True``
+                for a proper gradient computation when using
+                :class:`~qiskit_machine_learning.connectors.TorchConnector`.
+            pass_manager: The pass manager to transpile the circuits, if necessary.
+                Defaults to ``None``, as some primitives do not need transpiled circuits.
         Raises:
-        QiskitMachineLearningError: Invalid parameter values.
+            QiskitMachineLearningError: Invalid parameter values.
         """
         # set primitive, provide default
         if sampler is None: