Update documentation (#509)

* Add primitives branch to CI workflow * added pocs * init fixed * more init * Add qnns PoC * Establish qnn branch * Add fwd unit test * Refactor sampler qnn * Undo kernel changes * Start adding new type hint style * Move to neural_networks * Runnable tests * Update typehints, refactor * Add new unittests, fix code * Add gradient unit test * Add torch tests * Remove unwanted change circuitQNN * Remove utils * Fix style, lint * Add VQC * Fix mypy * fix mypy * fix mypy * fix mypy * Restore workflow * Restore workflow * Update .github/workflows/main.yml * Fix mypy * Fix CI (hopefully) * Update requirements * Add sparse support * Fix style etc * Add type ignore * Fix style? * skip test if not sparse * Add type ignore * Fix mypy * Make keyword args * Make keyword args * Apply review comments * Fix tests, final refactor, add docstring * Add Sampler QNN * Update qiskit_machine_learning/algorithms/classifiers/vqc.py Co-authored-by: Steve Wood <[email protected]> * Apply reviews vqc * Apply reviews * Fix neko test * Fix spell check * Update qiskit_machine_learning/neural_networks/sampler_qnn.py * Add try-catch * Add deprecations * Update tests * Fix tests * Filter warnings * Fix filter * fix black, pylint * update docstring * pulled the method up, modern type hints * fix spell * Update qiskit_machine_learning/neural_networks/sampler_qnn.py Co-authored-by: Steve Wood <[email protected]> * Update qiskit_machine_learning/neural_networks/sampler_qnn.py Co-authored-by: Steve Wood <[email protected]> * code review * update readme * update index * fix index * deprecate runtimes * update docs * update kernel docs * updated docs * migration guide * migration * fix spell * fix copyright * Disable running of stable tutorials for now * Disable running of stable tutorials for now * updated migration * fix black * fix spell * Enable CI stable tutorials * code review * fix spell * code review Co-authored-by: Manoel Marques <[email protected]> Co-authored-by: Gian Gentinetta <[email protected]> Co-authored-by: ElePT <[email protected]> Co-authored-by: ElePT <[email protected]> Co-authored-by: Steve Wood <[email protected]>
qiskit-community · Nov 8, 2022 · c6f4216 · c6f4216
1 parent 3c22367
commit c6f4216
Show file tree

Hide file tree

Showing 30 changed files with 1,019 additions and 108 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -238,7 +238,6 @@ jobs:
           wget https://codeload.github.com/Qiskit/qiskit-machine-learning/zip/stable/$version -O /tmp/repo.zip
           unzip /tmp/repo.zip -d /tmp/
           # copy stable tutorials to main tutorials
-          rm -rf docs/tutorials/*
           cp -R /tmp/qiskit-machine-learning-stable-$version/docs/tutorials/* docs/tutorials
           # run tutorials and zip results
           echo "earliest_version: 0.1.0" >> releasenotes/config.yaml

diff --git a/.pylintdict b/.pylintdict
@@ -1,5 +1,6 @@
 adam
 adjoint
+aer
 al
 ancilla
 ancillas
@@ -232,6 +233,7 @@ transpiles
 transpiling
 tunable
 uncompiled
+uncompute
 unitaries
 univariate
 unsymmetric

diff --git a/README.md b/README.md
@@ -9,8 +9,8 @@ without deep quantum computing knowledge. On the other hand, Qiskit Machine Lear
 and users can easily extend it to support cutting-edge quantum machine learning research.
 
 Qiskit Machine Learning provides the
-[QuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.QuantumKernel.html#qiskit_machine_learning.kernels.QuantumKernel)
-class that can be easily used to directly compute
+[FidelityQuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.QuantumKernel.html#qiskit_machine_learning.kernels.FidelityQuantumKernel)
+class that makes use of the [Fidelity](https://qiskit.org/documentation/stubs/qiskit.algorithms.state_fidelities.BaseStateFidelity.html) algorithm introduced in Qiskit and can be easily used to directly compute
 kernel matrices for given datasets or can be passed to a Quantum Support Vector Classifier 
 [QSVC](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.QSVC.html#qiskit_machine_learning.algorithms.QSVC) or
 Quantum Support Vector Regressor
@@ -20,25 +20,17 @@ It also can be used with many other existing kernel-based machine learning algor
 classical frameworks.
 
 Qiskit Machine Learning defines a generic interface for neural networks that is implemented by different
-quantum neural networks. Multiple implementations are readily provided, such as the
-[OpflowQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.OpflowQNN.html#qiskit_machine_learning.neural_networks.OpflowQNN),
-the [TwoLayerQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.TwoLayerQNN.html#qiskit_machine_learning.neural_networks.TwoLayerQNN),
-and the 
-[CircuitQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.CircuitQNN.html#qiskit_machine_learning.neural_networks.CircuitQNN).
-The [OpflowQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.OpflowQNN.html#qiskit_machine_learning.neural_networks.OpflowQNN)
-allows users to combine parametrized quantum circuits
-with quantum mechanical observables. The circuits can be constructed using, for example, building blocks
+quantum neural networks. Two core implementations are readily provided, such as the
+[EstimatorQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html),
+and the [SamplerQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html).
+The [EstimatorQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html)
+leverages the [Estimator](https://qiskit.org/documentation/stubs/qiskit.primitives.BaseEstimator.html) primitive from Qiskit and 
+allows users to combine parametrized quantum circuits with quantum mechanical observables. The circuits can be constructed using, for example, building blocks
 from Qiskit’s circuit library, and the QNN’s output is given by the expected value of the observable.
-The [TwoLayerQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.TwoLayerQNN.html#qiskit_machine_learning.neural_networks.TwoLayerQNN) is a special case of the 
-[OpflowQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.OpflowQNN.html#qiskit_machine_learning.neural_networks.OpflowQNN)
-that takes as input a feature map and an ansatz.
-The [CircuitQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.CircuitQNN.html#qiskit_machine_learning.neural_networks.CircuitQNN) directly takes the quantum circuit’s 
-measurements as output without an observable.
-The output can be used either as a batch of samples, i.e., a list of bitstrings measured from the circuit’s
-qubits, or as a sparse vector of the resulting sampling probabilities for each bitstring. The former is of
-interest in learning distributions resulting from a given quantum circuit, while the latter finds application,
-e.g., in regression or classification. A post-processing step can be used to interpret a given bitstring in
-a particular context, e.g. translating it into a set of classes.
+The [SamplerQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html)
+leverages another primitive introduced in Qiskit, the [Sampler](https://qiskit.org/documentation/stubs/qiskit.primitives.BaseSampler.html) primitive. 
+This neural network translates quasi-probabilities of bitstrings estimated by the primitive into a desired output. This 
+translation step can be used to interpret a given bitstring in a particular context, e.g. translating it into a set of classes.
 
 The neural networks include the functionality to evaluate them for a given input as well as to compute the
 corresponding gradients, which is important for efficient training. To train and use neural networks,
@@ -57,7 +49,7 @@ In addition to the models provided directly in Qiskit Machine Learning, it has t
 [TorchConnector](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.connectors.TorchConnector.html#qiskit_machine_learning.connectors.TorchConnector),
 which allows users to integrate all of our quantum neural networks directly into the
 [PyTorch](https://pytorch.org)
-open source machine learning library. Thanks to Qiskit’s gradient framework, this includes automatic
+open source machine learning library. Thanks to Qiskit’s gradient algorithms, this includes automatic
 differentiation - the overall gradients computed by [PyTorch](https://pytorch.org)
 during the backpropagation take into
 account quantum neural networks, too. The flexible design also allows the building of connectors
@@ -99,10 +91,10 @@ train and test samples from a data set to see how accurately the test set can
 be classified.
 
 ```python
-from qiskit import BasicAer
-from qiskit.utils import QuantumInstance, algorithm_globals
 from qiskit.algorithms.optimizers import COBYLA
 from qiskit.circuit.library import TwoLocal, ZZFeatureMap
+from qiskit.utils import algorithm_globals
+
 from qiskit_machine_learning.algorithms import VQC
 from qiskit_machine_learning.datasets import ad_hoc_data
 
@@ -114,22 +106,19 @@ feature_dim = 2  # dimension of each data point
 training_size = 20
 test_size = 10
 
-# training features, training labels, test features, test labels as np.array,
+# training features, training labels, test features, test labels as np.ndarray,
 # one hot encoding for labels
-training_features, training_labels, test_features, test_labels = \
-    ad_hoc_data(
-            training_size=training_size, test_size=test_size, n=feature_dim, gap=0.3)
+training_features, training_labels, test_features, test_labels = ad_hoc_data(
+    training_size=training_size, test_size=test_size, n=feature_dim, gap=0.3
+)
 
 feature_map = ZZFeatureMap(feature_dimension=feature_dim, reps=2, entanglement="linear")
-ansatz = TwoLocal(feature_map.num_qubits, ['ry', 'rz'], 'cz', reps=3)
-vqc = VQC(feature_map=feature_map,
-          ansatz=ansatz,
-          optimizer=COBYLA(maxiter=100),
-          quantum_instance=QuantumInstance(BasicAer.get_backend('statevector_simulator'),
-                                           shots=1024,
-                                           seed_simulator=seed,
-                                           seed_transpiler=seed)
-          )
+ansatz = TwoLocal(feature_map.num_qubits, ["ry", "rz"], "cz", reps=3)
+vqc = VQC(
+    feature_map=feature_map,
+    ansatz=ansatz,
+    optimizer=COBYLA(maxiter=100),
+)
 vqc.fit(training_features, training_labels)
 
 score = vqc.score(test_features, test_labels)

diff --git a/docs/index.rst b/docs/index.rst
@@ -11,32 +11,30 @@ On the one hand, this design is very easy to use and allows users to rapidly pro
 without deep quantum computing knowledge. On the other hand, Qiskit Machine Learning is very flexible,
 and users can easily extend it to support cutting-edge quantum machine learning research.
 
-Qiskit Machine Learning provides the :class:`~qiskit_machine_learning.kernels.QuantumKernel`
-class that can be easily used to directly compute
-kernel matrices for given datasets or can be passed to a Quantum Support Vector Classifier 
+Qiskit Machine Learning provides the :class:`~qiskit_machine_learning.kernels.FidelityQuantumKernel`
+class class that makes use of the :class:`~qiskit.algorithms.state_fidelities.BaseStateFidelity` algorithm
+introduced in Qiskit and can be easily used to directly compute kernel matrices for given datasets
+or can be passed to a Quantum Support Vector Classifier
 (:class:`~qiskit_machine_learning.algorithms.QSVC`) or
 Quantum Support Vector Regressor (:class:`~qiskit_machine_learning.algorithms.QSVR`)
 to quickly start solving classification or regression problems.
 It also can be used with many other existing kernel-based machine learning algorithms from established
 classical frameworks.
 
 Qiskit Machine Learning defines a generic interface for neural networks that is implemented by different
-quantum neural networks. Multiple implementations are readily provided, such as the
-:class:`~qiskit_machine_learning.neural_networks.OpflowQNN`,
-the :class:`~qiskit_machine_learning.neural_networks.TwoLayerQNN`,
-and the :class:`~qiskit_machine_learning.neural_networks.CircuitQNN`.
-The :class:`~qiskit_machine_learning.neural_networks.OpflowQNN` allows users to combine parametrized quantum circuits
-with quantum mechanical observables. The circuits can be constructed using, for example, building blocks
-from Qiskit’s circuit library, and the QNN’s output is given by the expected value of the observable.
-The :class:`~qiskit_machine_learning.neural_networks.TwoLayerQNN` is a special case of the 
-:class:`~qiskit_machine_learning.neural_networks.OpflowQNN` that takes as input a feature map and an ansatz.
-The :class:`~qiskit_machine_learning.neural_networks.CircuitQNN` directly takes the quantum circuit’s 
-measurements as output without an observable.
-The output can be used either as a batch of samples, i.e., a list of bitstrings measured from the circuit’s
-qubits, or as a sparse vector of the resulting sampling probabilities for each bitstring. The former is of
-interest in learning distributions resulting from a given quantum circuit, while the latter finds application,
-e.g., in regression or classification. A post-processing step can be used to interpret a given bitstring in
-a particular context, e.g. translating it into a set of classes.
+quantum neural networks. Two core implementations are readily provided, such as the
+:class:`~qiskit_machine_learning.neural_networks.EstimatorQNN`
+and the :class:`~qiskit_machine_learning.neural_networks.SamplerQNN`.
+The :class:`~qiskit_machine_learning.neural_networks.EstimatorQNN` leverages
+the :class:`~qiskit.primitives.BaseEstimator` primitive from Qiskit and allows users to combine
+parametrized quantum circuits with quantum mechanical observables. The circuits can be constructed
+using, for example, building blocks from Qiskit's circuit library, and the QNN's output is given
+by the expected value of the observable.
+The :class:`~qiskit_machine_learning.neural_networks.SamplerQNN` leverages another primitive
+introduced in Qiskit, the :class:`~qiskit.primitives.BaseSampler` primitive. This neural network
+translates quasi-probabilities of bitstrings estimated by the primitive into a desired output. This
+translation step can be used to interpret a given bitstring in a particular context, e.g.
+translating it into a set of classes.
 
 The neural networks include the functionality to evaluate them for a given input as well as to compute the
 corresponding gradients, which is important for efficient training. To train and use neural networks,
@@ -53,7 +51,7 @@ In addition to the models provided directly in Qiskit Machine Learning, it has t
 :class:`~qiskit_machine_learning.connectors.TorchConnector`,
 which allows users to integrate all of our quantum neural networks directly into the
 `PyTorch <https://pytorch.org>`__
-open source machine learning library. Thanks to Qiskit’s gradient framework, this includes automatic
+open source machine learning library. Thanks to Qiskit's gradient algorithms, this includes automatic
 differentiation - the overall gradients computed by `PyTorch <https://pytorch.org>`__
 during the backpropagation take into
 account quantum neural networks, too. The flexible design also allows the building of connectors
@@ -66,13 +64,16 @@ Next Steps
 
 `Getting started <getting_started.html>`_
 
+`Migration Guide <migration/index.html>`_
+
 `Tutorials <tutorials/index.html>`_
 
 .. toctree::
     :hidden:
 
     Overview <self>
     Getting Started <getting_started>
+    Migration Guide <migration/index>
     Tutorials <tutorials/index>
     API Reference <apidocs/qiskit_machine_learning>
     Release Notes <release_notes>

diff --git a/docs/migration/01_migration_guide_0.5.ipynb b/docs/migration/01_migration_guide_0.5.ipynb
diff --git a/docs/migration/index.rst b/docs/migration/index.rst
@@ -0,0 +1,16 @@
+#######################################
+Qiskit Machine Learning Migration Guide
+#######################################
+
+
+.. nbgallery::
+    :glob:
+
+    *
+
+
+.. Hiding - Indices and tables
+   :ref:`genindex`
+   :ref:`modindex`
+   :ref:`search`
+
diff --git a/qiskit_machine_learning/algorithms/__init__.py b/qiskit_machine_learning/algorithms/__init__.py
@@ -11,7 +11,10 @@
 # that they have been altered from the originals.
 
 """
-Algorithms (:mod:`qiskit_machine_learning.algorithms`)
+Quantum machine learning algorithms (:mod:`qiskit_machine_learning.algorithms`)
+===============================================================================
+
+The package contains core algorithms such as classifiers and classifiers.
 
 .. currentmodule:: qiskit_machine_learning.algorithms
 

diff --git a/qiskit_machine_learning/algorithms/classifiers/neural_network_classifier.py b/qiskit_machine_learning/algorithms/classifiers/neural_network_classifier.py
@@ -37,9 +37,9 @@
 
 
 class NeuralNetworkClassifier(TrainableModel, ClassifierMixin):
-    """Quantum neural network classifier. Implements Scikit-Learn compatible methods for
-    classification and extends ``ClassifierMixin``. See `Scikit-Learn <https://scikit-learn.org>`__
-    for more details.
+    """Implements a basic quantum neural network classifier. Implements Scikit-Learn compatible
+    methods for classification and extends ``ClassifierMixin``.
+    See `Scikit-Learn <https://scikit-learn.org>`__ for more details.
     """
 
     def __init__(

diff --git a/qiskit_machine_learning/algorithms/classifiers/pegasos_qsvc.py b/qiskit_machine_learning/algorithms/classifiers/pegasos_qsvc.py
@@ -31,8 +31,9 @@
 
 class PegasosQSVC(ClassifierMixin, SerializableModelMixin):
     r"""
-    This class implements Pegasos Quantum Support Vector Classifier algorithm developed in [1]
-    and includes methods ``fit``, ``predict`` and ``decision_function`` following the signatures
+    Implements Pegasos Quantum Support Vector Classifier algorithm. The algorithm has been
+    developed in [1] and includes methods ``fit``, ``predict`` and ``decision_function`` following
+    the signatures
     of `sklearn.svm.SVC <https://scikit-learn.org/stable/modules/generated/sklearn.svm.SVC.html>`_.
     This implementation is adapted to work with quantum kernels.
 

diff --git a/qiskit_machine_learning/algorithms/classifiers/qsvc.py b/qiskit_machine_learning/algorithms/classifiers/qsvc.py
@@ -24,12 +24,13 @@
 
 
 class QSVC(SVC, SerializableModelMixin):
-    r"""Quantum Support Vector Classifier.
+    r"""Quantum Support Vector Classifier that extends the scikit-learn
+    `sklearn.svm.SVC <https://scikit-learn.org/stable/modules/generated/sklearn.svm.SVC.html>`_
+    classifier and introduces an additional `quantum_kernel` parameter.
 
-    This class shows how to use a quantum kernel for classification. The class extends
-    `sklearn.svm.SVC <https://scikit-learn.org/stable/modules/generated/sklearn.svm.SVC.html>`_,
-    and thus inherits its methods like ``fit`` and ``predict`` used in the example below.
-    Read more in the `sklearn user guide
+    This class shows how to use a quantum kernel for classification. The class inherits its methods
+    like ``fit`` and ``predict`` from scikit-learn, see the example below.
+    Read more in the `scikit-learn user guide
     <https://scikit-learn.org/stable/modules/svm.html#svm-classification>`_.
 
     **Example**

diff --git a/qiskit_machine_learning/algorithms/classifiers/vqc.py b/qiskit_machine_learning/algorithms/classifiers/vqc.py
@@ -31,10 +31,10 @@
 
 
 class VQC(NeuralNetworkClassifier):
-    r"""Variational quantum classifier.
+    r"""A convenient Variational Quantum Classifier implementation.
 
     The variational quantum classifier (VQC) is a variational algorithm where the measured
-    expectation value is interpreted as the output of a classifier.
+    bitstrings are interpreted as the output of a classifier.
 
     Constructs a quantum circuit and corresponding neural network, then uses it to instantiate a
     neural network classifier.

diff --git a/qiskit_machine_learning/algorithms/objective_functions.py b/qiskit_machine_learning/algorithms/objective_functions.py
@@ -107,8 +107,8 @@ def _neural_network_forward(self, weights: np.ndarray) -> Union[np.ndarray, Spar
 
 
 class BinaryObjectiveFunction(ObjectiveFunction):
-    """An objective function for binary representation of the output,
-    e.g. classes of ``-1`` and ``+1``."""
+    """An objective function for binary representation of the output. For instance, classes of
+    ``-1`` and ``+1``."""
 
     def objective(self, weights: np.ndarray) -> float:
         # predict is of shape (N, 1), where N is a number of samples
@@ -143,8 +143,8 @@ def gradient(self, weights: np.ndarray) -> np.ndarray:
 
 class MultiClassObjectiveFunction(ObjectiveFunction):
     """
-    An objective function for multiclass representation of the output,
-    e.g. classes of ``0``, ``1``, ``2``, etc.
+    An objective function for multiclass representation of the output. For instance, classes of
+    ``0``, ``1``, ``2``, etc.
     """
 
     def objective(self, weights: np.ndarray) -> float:
@@ -182,8 +182,8 @@ def gradient(self, weights: np.ndarray) -> np.ndarray:
 
 class OneHotObjectiveFunction(ObjectiveFunction):
     """
-    An objective function for one hot encoding representation of the output,
-    e.g. classes like ``[1, 0, 0]``, ``[0, 1, 0]``, ``[0, 0, 1]``.
+    An objective function for one hot encoding representation of the output. For instance, classes
+    like ``[1, 0, 0]``, ``[0, 1, 0]``, ``[0, 0, 1]``.
     """
 
     def objective(self, weights: np.ndarray) -> float:

diff --git a/qiskit_machine_learning/algorithms/regressors/neural_network_regressor.py b/qiskit_machine_learning/algorithms/regressors/neural_network_regressor.py
@@ -26,9 +26,9 @@
 
 
 class NeuralNetworkRegressor(TrainableModel, RegressorMixin):
-    """Quantum neural network regressor. Implements Scikit-Learn compatible methods for
-    regression and extends ``RegressorMixin``. See `Scikit-Learn <https://scikit-learn.org>`__
-    for more details.
+    """Implements a basic quantum neural network regressor. Implements Scikit-Learn compatible
+    methods for regression and extends ``RegressorMixin``.
+    See `Scikit-Learn <https://scikit-learn.org>`__ for more details.
     """
 
     def _fit_internal(

diff --git a/qiskit_machine_learning/algorithms/regressors/qsvr.py b/qiskit_machine_learning/algorithms/regressors/qsvr.py
@@ -23,13 +23,14 @@
 
 
 class QSVR(SVR, SerializableModelMixin):
-    r"""Quantum Support Vector Regressor.
+    r"""Quantum Support Vector Regressor that extends the scikit-learn
+    `sklearn.svm.SVR <https://scikit-learn.org/stable/modules/generated/sklearn.svm.SVR.html>`_
+    regressor and introduces an additional `quantum_kernel` parameter.
 
-    This class shows how to use a quantum kernel for regression. The class extends
-    `sklearn.svm.SVR <https://scikit-learn.org/stable/modules/generated/sklearn.svm.SVR.html>`_,
-    and thus inherits its methods like ``fit`` and ``predict`` used in the example below.
+    This class shows how to use a quantum kernel for regression. The class inherits its methods
+    like ``fit`` and ``predict`` from scikit-learn, see the example below.
     Read more in the
-    `sklearn user guide <https://scikit-learn.org/stable/modules/svm.html#svm-regression>`_.
+    `scikit-learn user guide <https://scikit-learn.org/stable/modules/svm.html#svm-regression>`_.
 
     **Example**