Merge pull request qiskit-community/qiskit-aqua#817 from woodsp-ibm/m…

…oredocs

Updating component documentation

qiskit/aqua/components/multiclass_extensions/__init__.py

@@ -2,7 +2,7 @@
 
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2018, 2019.
+# (C) Copyright IBM 2018, 2020.
 #
 # 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
@@ -15,10 +15,14 @@
 """
 Multi-class Extensions (:mod:`qiskit.aqua.components.multiclass_extensions`)
 ============================================================================
-A multiclass extension allows Aqua's binary classifier algorithms to handle
-more than two classes to do
+A multiclass extension allows Aqua's binary classifier algorithms, such as
+:class:`~qiskit.aqua.algorithms.QSVM` and :class:`~qiskit.aqua.algorithms.SVM_Classical`
+to handle more than two classes and do
 `multiclass classification <https://en.wikipedia.org/wiki/Multiclass_classification>`_.
 
+The multiclass extensions use different techniques to perform multiclass classification
+using the underlying binary classifier.
+
 .. currentmodule:: qiskit.aqua.components.multiclass_extensions
 
 Multiclass Extension Base Class

qiskit/aqua/components/multiclass_extensions/all_pairs.py

@@ -13,7 +13,7 @@
 # that they have been altered from the originals.
 
 """
-The multiclass extension based on the all-pairs algorithm.
+The All-Pairs multiclass extension.
 """
 
 from typing import Optional, List, Callable
@@ -32,12 +32,24 @@
 
 class AllPairs(MulticlassExtension):
     """
-    The multiclass extension based on the all-pairs algorithm.
+    The All-Pairs multiclass extension.
+
+    In the **all-pairs** reduction, one trains :math:`k(k−1)/2` binary classifiers for a
+    :math:`k`-way multiclass problem; each receives the samples of a pair of classes from the
+    original training set, and must learn to distinguish these two classes. At prediction time,
+    a **weighted voting scheme** is used: all :math:`k(k−1)/2` classifiers are applied to an unseen
+    sample, and each class gets assigned the sum of all the scores obtained by the various
+    classifiers. The combined classifier returns as a result the class getting the highest value.
     """
 
     def __init__(self,
                  estimator_cls: Callable[[List], Estimator],
                  params: Optional[List] = None) -> None:
+        """
+        Args:
+            estimator_cls: An :class:`Estimator` class
+            params: Params for the estimator
+        """
         super().__init__()
         self.estimator_cls = estimator_cls
         self.params = params if params is not None else []
@@ -46,7 +58,8 @@ def __init__(self,
 
     def train(self, x, y):
         """
-        training multiple estimators each for distinguishing a pair of classes.
+        Training multiple estimators each for distinguishing a pair of classes.
+
         Args:
             x (numpy.ndarray): input points
             y (numpy.ndarray): input labels
@@ -75,7 +88,8 @@ def train(self, x, y):
 
     def test(self, x, y):
         """
-        testing multiple estimators each for distinguishing a pair of classes.
+        Testing multiple estimators each for distinguishing a pair of classes.
+
         Args:
             x (numpy.ndarray): input points
             y (numpy.ndarray): input labels
@@ -92,7 +106,8 @@ def test(self, x, y):
 
     def predict(self, x):
         """
-        applying multiple estimators for prediction
+        Applying multiple estimators for prediction.
+
         Args:
             x (numpy.ndarray): NxD array
         Returns:

qiskit/aqua/components/multiclass_extensions/error_correcting_code.py

@@ -13,7 +13,7 @@
 # that they have been altered from the originals.
 
 """
-the multiclass extension based on the error-correcting-code algorithm.
+The Error Correcting Code multiclass extension.
 """
 
 from typing import Optional, List, Callable
@@ -34,14 +34,45 @@
 
 
 class ErrorCorrectingCode(MulticlassExtension):
-    """
-      the multiclass extension based on the error-correcting-code algorithm.
+    r"""
+    The Error Correcting Code multiclass extension.
+
+    Error Correcting Code (ECC) is an ensemble method designed for the multiclass classification
+    problem.  As for the other multiclass methods, the task is to decide one label from
+    :math:`k > 2` possible choices.
+
+    +-------+------------------------------------------------------------------------+
+    |       |                                Code Word                               |
+    + Class +-----------+------------+-----------+-----------+-----------+-----------+
+    |       |:math:`f_0`|:math:`f_1` |:math:`f_2`|:math:`f_3`|:math:`f_4`|:math:`f_5`|
+    +-------+-----------+------------+-----------+-----------+-----------+-----------+
+    |   1   |     0     |     1      |     0     |     1     |     0     |     1     |
+    +-------+-----------+------------+-----------+-----------+-----------+-----------+
+    |   2   |     1     |     0      |     0     |     1     |     0     |     0     |
+    +-------+-----------+------------+-----------+-----------+-----------+-----------+
+    |   3   |     1     |     1      |     1     |     0     |     0     |     0     |
+    +-------+-----------+------------+-----------+-----------+-----------+-----------+
+
+    The table above shows a 6-bit ECC for a 3-class problem. Each class is assigned a unique
+    binary string of length 6.  The string is also called  a **codeword**.  For example, class 2
+    has codeword ``100100``.  During training, one binary classifier is learned for each column.
+    For example, for the first column, ECC builds a binary classifier to separate :math:`\{2, 3\}`
+    from :math:`\{1\}`. Thus, 6 binary classifiers are trained in this way.  To classify a
+    new data point :math:`\mathbf{x}`, all 6 binary classifiers are evaluated to obtain a 6-bit
+    string. Finally, we choose the class whose bitstring is closest to :math:`\mathbf{x}`’s
+    output string as the predicted label. This implementation of ECC uses the Euclidean distance.
     """
 
     def __init__(self,
                  estimator_cls: Callable[[List], Estimator],
                  params: Optional[List] = None,
                  code_size: int = 4):
+        """
+        Args:
+            estimator_cls: An :class:`Estimator` class
+            params: Params for the estimator
+            code_size: Size of error correcting code
+        """
         validate_min('code_size', code_size, 1)
         super().__init__()
         self.estimator_cls = estimator_cls
@@ -55,6 +86,7 @@ def __init__(self,
     def train(self, x, y):
         """
         Training multiple estimators each for distinguishing a pair of classes.
+
         Args:
             x (numpy.ndarray): input points
             y (numpy.ndarray): input labels
@@ -85,6 +117,7 @@ def train(self, x, y):
     def test(self, x, y):
         """
         Testing multiple estimators each for distinguishing a pair of classes.
+
         Args:
             x (numpy.ndarray): input points
             y (numpy.ndarray): input labels
@@ -100,7 +133,8 @@ def test(self, x, y):
 
     def predict(self, x):
         """
-        Applying multiple estimators for prediction
+        Applying multiple estimators for prediction.
+
         Args:
             x (numpy.ndarray): NxD array
         Returns:

qiskit/aqua/components/multiclass_extensions/multiclass_extension.py

@@ -32,7 +32,8 @@ def __init__(self) -> None:
     @abstractmethod
     def train(self, x, y):
         """
-        training multiple estimators each for distinguishing a pair of classes.
+        Training multiple estimators each for distinguishing a pair of classes.
+
         Args:
             x (numpy.ndarray): input points
             y (numpy.ndarray): input labels
@@ -42,7 +43,8 @@ def train(self, x, y):
     @abstractmethod
     def test(self, x, y):
         """
-        testing multiple estimators each for distinguishing a pair of classes.
+        Testing multiple estimators each for distinguishing a pair of classes.
+
         Args:
             x (numpy.ndarray): input points
             y (numpy.ndarray): input labels
@@ -52,7 +54,8 @@ def test(self, x, y):
     @abstractmethod
     def predict(self, x):
         """
-        applying multiple estimators for prediction
+        Applying multiple estimators for prediction.
+
         Args:
             x (numpy.ndarray): input points
         """

qiskit/aqua/components/multiclass_extensions/one_against_rest.py

@@ -13,7 +13,7 @@
 # that they have been altered from the originals.
 
 """
-the multiclass extension based on the one-against-rest algorithm.
+The One Against Rest multiclass extension.
 """
 
 from typing import Optional, List, Callable
@@ -31,13 +31,24 @@
 
 
 class OneAgainstRest(MulticlassExtension):
-    """
-      the multiclass extension based on the one-against-rest algorithm.
+    r"""
+    The One Against Rest multiclass extension.
+
+    For an :math:`n`-class problem, the **one-against-rest** method constructs :math:`n`
+    SVM classifiers, with the :math:`i`-th classifier separating class :math:`i` from all the
+    remaining classes, :math:`\forall i \in \{1, 2, \ldots, n\}`. When the :math:`n` classifiers
+    are combined to make the final decision, the classifier that generates the highest value from
+    its decision function is selected as the winner and the corresponding class label is returned.
     """
 
     def __init__(self,
                  estimator_cls: Callable[[List], Estimator],
                  params: Optional[List] = None) -> None:
+        """
+        Args:
+            estimator_cls: An :class:`Estimator` class
+            params: Params for the estimator
+        """
         super().__init__()
         self.estimator_cls = estimator_cls
         self.params = params if params is not None else []
@@ -47,7 +58,8 @@ def __init__(self,
 
     def train(self, x, y):
         """
-        training multiple estimators each for distinguishing a pair of classes.
+        Training multiple estimators each for distinguishing a pair of classes.
+
         Args:
             x (numpy.ndarray): input points
             y (numpy.ndarray): input labels
@@ -71,7 +83,8 @@ def train(self, x, y):
 
     def test(self, x, y):
         """
-        testing multiple estimators each for distinguishing a pair of classes.
+        Testing multiple estimators each for distinguishing a pair of classes.
+
         Args:
             x (numpy.ndarray): input points
             y (numpy.ndarray): input labels
@@ -87,7 +100,8 @@ def test(self, x, y):
 
     def predict(self, x):
         """
-        applying multiple estimators for prediction
+        Applying multiple estimators for prediction.
+
         Args:
             x (numpy.ndarray): NxD array
         Returns:

qiskit/aqua/components/neural_networks/__init__.py

@@ -15,8 +15,13 @@
 """
 Neural Networks (:mod:`qiskit.aqua.components.neural_networks`)
 ===============================================================
-Neural Networks, for example for use with :class:`QGAN` algorithm.
-Neural networks are either a discriminator network or generator network.
+A neural network is a parametrized network which may be defined as a artificial
+neural network - classical neural network - or as parametrized quantum circuits
+- quantum neural network. Furthermore, neural networks can be defined with respect
+to a discriminative or generative task.
+
+Neural Networks may be used, for example, with the
+:class:`~qiskit.aqua.algorithms.QGAN` algorithm.
 
 .. currentmodule:: qiskit.aqua.components.neural_networks
 

qiskit/aqua/components/neural_networks/numpy_discriminator.py

@@ -206,7 +206,7 @@ def single_layer_backward_propagation(da_curr,
 
 class NumpyDiscriminator(DiscriminativeNetwork):
     """
-    Discriminator based on numpy
+    Discriminator based on NumPy
     """
 
     def __init__(self, n_features: int = 1, n_out: int = 1) -> None:

qiskit/aqua/components/neural_networks/pytorch_discriminator.py

@@ -36,7 +36,7 @@
 
 class PyTorchDiscriminator(DiscriminativeNetwork):
     """
-    PyTorchDiscriminator based on PyTorch
+    Discriminator based on PyTorch
     """
 
     def __init__(self, n_features: int = 1, n_out: int = 1) -> None:

qiskit/aqua/components/neural_networks/quantum_generator.py

@@ -14,7 +14,6 @@
 
 """
 Quantum Generator
-
 """
 
 from typing import Optional, List, Union
@@ -38,15 +37,15 @@
 
 class QuantumGenerator(GenerativeNetwork):
     """
-    Quantum Generator
+    Quantum Generator.
+
     The quantum generator is a parametrized quantum circuit which can be trained with the
-    :class:`~qiskit.aqua.algorithms.adaptive.qgan.QGAN` algorithm
+    :class:`~qiskit.aqua.algorithms.QGAN` algorithm
     to generate a quantum state which approximates the probability
     distribution of given training data. At the beginning of the training the parameters will
     be set randomly, thus, the output will is random. Throughout the training the quantum
     generator learns to represent the target distribution.
-    Eventually, the trained generator can be used for state preparation in e.g. QAE.
-
+    Eventually, the trained generator can be used for state preparation e.g. in QAE.
     """
 
     def __init__(self,
@@ -62,10 +61,9 @@ def __init__(self,
             bounds: k min/max data values [[min_1,max_1],...,[min_k,max_k]],
                 given input data dim k
             num_qubits: k numbers of qubits to determine representation resolution,
-            i.e. n qubits enable the representation of 2**n values [n_1,..., n_k]
-            generator_circuit: a
-                :class:`UnivariateVariationalDistribution` for univariate data,
-                a :class:`MultivariateVariationalDistribution` for multivariate data,
+                i.e. n qubits enable the representation of 2**n values [n_1,..., n_k]
+            generator_circuit: a UnivariateVariationalDistribution for univariate data,
+                a MultivariateVariationalDistribution for multivariate data,
                 or a QuantumCircuit implementing the generator.
             init_params: 1D numpy array or list, Initialization for
                 the generator's parameters.