Update algorithms docs for Aqua

.pylintdict

@@ -136,6 +136,7 @@ ecc
 ee
 eigen
 eigensolver
+eigensolvers
 eigenstate
 eigrange
 eigs
@@ -230,6 +231,7 @@ inline
 innerproduct
 inreg
 instantiations
+integercomparator
 intelvem
 interatomic
 ints
@@ -270,6 +272,7 @@ lhs
 lih
 lijh
 lin
+linearpaulirotations
 lmin
 lnot
 loglikelihood
@@ -383,9 +386,11 @@ pdf
 penality
 ph
 piecewise
+piecewiselinearpaulirotations
 plesset
 pmatrix
 polynomially
+polynomialpaulirotations
 postoracle
 powell
 pre

qiskit/aqua/algorithms/__init__.py

@@ -24,9 +24,9 @@
 a different implementation of the same component type in order to potentially alter the behavior
 and outcome of the algorithm.
 
-Algorithms are run via a :class:`~qiskit.aqua.QuantumInstance` which must be set with the desired
-backend where the algorithm's circuits will be executed and be configured with a number of compile
-and runtime parameters controlling circuit compilation and execution. Aqua ultimately uses
+Quantum algorithms are run via a :class:`~qiskit.aqua.QuantumInstance` which must be set with the
+desired backend where the algorithm's circuits will be executed and be configured with a number of
+compile and runtime parameters controlling circuit compilation and execution. Aqua ultimately uses
 `Terra <https://www.qiskit.org/terra>`__ for the actual compilation and execution of the quantum
 circuits created by the algorithm and its components.
 
@@ -42,39 +42,111 @@
    QuantumAlgorithm
    ClassicalAlgorithm
 
-Quantum Algorithms
-==================
+Algorithms
+==========
+
+Aqua contains a variety of quantum algorithms and these have been grouped by logical function such
+as minimum eigensolvers and amplitude amplifiers.
+
+Additionally Aqua includes some classical algorithms. While these algorithms do not use a quantum
+device or simulator, and rely on purely classical approaches, they may be useful in the near term
+to generate reference values while experimenting with, developing and testing quantum algorithms.
+
+The classical algorithms are designed to take the same input data as the quantum algorithms so that
+behavior, data validity and output can be evaluated and compared to a quantum result.
+
+Amplitude Amplifiers
+++++++++++++++++++++
 
 .. autosummary::
    :toctree: ../stubs/
    :nosignatures:
 
-   VQE
-   QAOA
-   VQC
-   QGAN
-   EOH
-   QSVM
    Grover
-   IQPEMinimumEigensolver
-   QPEMinimumEigensolver
+
+Amplitude Estimators
+++++++++++++++++++++
+Algorithms that estimate a value.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
    AmplitudeEstimation
    IterativeAmplitudeEstimation
    MaximumLikelihoodAmplitudeEstimation
-   Simon
-   DeutschJozsa
+
+Classifiers
++++++++++++
+Algorithms for data classification.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   QSVM
+   VQC
+   SklearnSVM
+
+Distribution Learners
++++++++++++++++++++++
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   QGAN
+
+Education
++++++++++
+Algorithms whose main role is educational. These are provided as Aqua algorithms so they can be
+run in the same framework but their existence here is principally for educational reasons.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
    BernsteinVazirani
-   HHL
+   DeutschJozsa
+   EOH
+   Simon
+
+Eigensolvers
+++++++++++++
+Algorithms to find eigenvalues of an operator. For chemistry these can be used to find excited
+states of a molecule and qiskit.chemistry has some algorithms that leverage chemistry specific
+knowledge to do this in that application domain.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   NumPyEigensolver
+
+Factorizers
++++++++++++
+Algorithms to find factors of a number.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
    Shor
 
-Classical Algorithms
-====================
-Aqua includes some classical algorithms. While these algorithms do not use a quantum device or
-simulator, and rely on purely classical approaches, they may be useful in the near term to
-generate reference values while experimenting with, developing and testing quantum algorithms.
+Linear Solvers
+++++++++++++++
+Algorithms to find solutions for linear equations of equations.
 
-The algorithms are designed to take the same input data as the quantum algorithms so that
-behavior, data validity and output can be evaluated and compared to a quantum result.
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   HHL
+   NumPyLSsolver
+
+Minimum Eigensolvers
+++++++++++++++++++++
+Algorithms that can find the minimum eigenvalue of an operator.
 
 Note: The :class:`ClassicalCPLEX` algorithm requires `IBM ILOG CPLEX Optimization Studio
 <https://www.ibm.com/support/knowledgecenter/SSSA5P_12.10.0/COS_KC_home.html>`__
@@ -89,11 +161,19 @@
    :toctree: ../stubs/
    :nosignatures:
 
-   NumPyEigensolver
-   NumPyMinimumEigensolver
-   NumPyLSsolver
-   SklearnSVM
+   MinimumEigensolver
+   MinimumEigensolverResult
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
    ClassicalCPLEX
+   IQPEMinimumEigensolver
+   NumPyMinimumEigensolver
+   QAOA
+   QPEMinimumEigensolver
+   VQE
 
 """
 

qiskit/aqua/algorithms/classifiers/qsvm/qsvm.py

@@ -12,7 +12,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Quantum SVM algorithm."""
+"""The Quantum SVM algorithm."""
 
 from typing import Dict, Optional, Union
 import logging
@@ -42,7 +42,7 @@
 
 class QSVM(QuantumAlgorithm):
     """
-    Quantum SVM algorithm.
+    The Quantum SVM algorithm.
 
     A key concept in classification methods is that of a kernel. Data cannot typically be
     separated by a hyperplane in its original space. A common technique used to find such a

qiskit/aqua/algorithms/classifiers/sklearn_svm/sklearn_svm.py

@@ -13,7 +13,7 @@
 # that they have been altered from the originals.
 
 """
-The Sklearn SVM algorithm.
+The Sklearn SVM algorithm (classical).
 """
 
 from typing import Dict, Optional
@@ -36,12 +36,12 @@
 
 class SklearnSVM(ClassicalAlgorithm):
     """
-    The Sklearn SVM algorithm.
+    The Sklearn SVM algorithm (classical).
 
-    SVM Classical uses a classical approach to experiment with feature map classification
-    problems. See also the quantum classifier :class:`QSVM`.
+    This scikit-learn based SVM algorithm uses a classical approach to experiment with feature map
+    classification problems. See also the quantum classifier :class:`QSVM`.
 
-    Internally, SVM Classical will run the binary classification or multiclass classification
+    Internally, this algorithm will run the binary classification or multiclass classification
     based on how many classes the data has. If the data has more than 2 classes then a
     *multiclass_extension* is required to be supplied. Aqua provides several
     :mod:`~qiskit.aqua.components.multiclass_extensions`.

qiskit/aqua/algorithms/linear_solvers/numpy_ls_solver.py

@@ -11,7 +11,7 @@
 # Any modifications or derivative works of this code must retain this
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
-"""The Numpy LinearSystem algorithm."""
+"""The Numpy LinearSystem algorithm (classical)."""
 
 from typing import List, Union
 import logging
@@ -25,7 +25,7 @@
 
 class NumPyLSsolver(ClassicalAlgorithm):
     r"""
-    The Numpy LinearSystem algorithm.
+    The Numpy LinearSystem algorithm (classical).
 
     This linear system solver computes the eigenvalues of a complex-valued square
     matrix :math:`A` of dimension :math:`n \times n` and the solution to the systems of linear

qiskit/aqua/algorithms/minimum_eigen_solvers/cplex/classical_cplex.py

@@ -34,7 +34,7 @@
 
 class ClassicalCPLEX(ClassicalAlgorithm):
     """
-    The Classical CPLEX algorithm.
+    The Classical CPLEX algorithm (classical).
 
     This algorithm uses the `IBM ILOG CPLEX Optimization Studio` along with its separately
     installed `Python API` to solve optimization problems modeled as an Ising Hamiltonian.

qiskit/aqua/circuits/__init__.py

@@ -2,7 +2,7 @@
 
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2019.
+# (C) Copyright IBM 2019, 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
@@ -16,7 +16,15 @@
 Circuits (:mod:`qiskit.aqua.circuits`)
 ======================================
 Collection of circuits and gates that may be used to build quantum algorithms
-and components...
+and components.
+
+Note:
+    As of Aqua 0.7.0 Gates that were formerly here such as `mct` etc., that were initially built
+    out to facilitate the development of Aqua algorithms, have been moved into Terra.
+
+    Likewise there are Circuits here, that are now deprecated, which have been moved and have
+    updated versions in Terra `qiskit.circuit.library` which should be used for any future work.
+    The circuit documentation here indicates the corresponding replacement circuit in the library.
 
 .. currentmodule:: qiskit.aqua.circuits
 

qiskit/aqua/circuits/fixed_value_comparator.py

@@ -25,7 +25,10 @@
 
 
 class FixedValueComparator(CircuitFactory):
-    r"""Fixed Value Comparator.
+    r"""*DEPRECATED.* Fixed Value Comparator
+
+    .. deprecated:: 0.7.0
+       Use Terra's qiskit.circuit.library.IntegerComparator instead.
 
     Operator compares basis states \|i>_n against a classically
     given fixed value L and flips a target qubit if i >= L (or < depending on parameters):

qiskit/aqua/circuits/linear_rotation.py

@@ -21,7 +21,10 @@
 
 
 class LinearRotation(CircuitFactory):
-    r"""Linearly-controlled X, Y or Z rotation.
+    r"""*DEPRECATED.* Linearly-controlled X, Y or Z rotation.
+
+    .. deprecated:: 0.7.0
+       Use Terra's qiskit.circuit.library.LinearPauliRotations instead.
 
     For a register of state qubits \|x> and a target qubit \|0> this operator acts as:
 
@@ -45,7 +48,7 @@ def __init__(self, slope, offset, num_state_qubits, basis='Y', i_state=None, i_t
         """
         warnings.warn('The qiskit.aqua.circuits.LinearRotation object is deprecated and will be '
                       'removed no earlier than 3 months after the 0.7.0 release of Qiskit Aqua. '
-                      'You should use qiskit.circuit.library.arithmetic.LinearRotation instead.',
+                      'You should use qiskit.circuit.library.LinearPauliRotations instead.',
                       DeprecationWarning, stacklevel=2)
 
         super().__init__(num_state_qubits + 1)

qiskit/aqua/circuits/piecewise_linear_rotation.py

@@ -24,7 +24,10 @@
 
 
 class PiecewiseLinearRotation(CircuitFactory):
-    """Piecewise-linearly-controlled rotation.
+    """*DEPRECATED.* Piecewise-linearly-controlled rotation.
+
+    .. deprecated:: 0.7.0
+       Use Terra's qiskit.circuit.library.PiecewiseLinearPauliRotations instead.
 
     For a piecewise linear (not necessarily continuous) function f(x).
     The function f(x) is defined through breakpoints, slopes and offsets as follows.
@@ -42,10 +45,6 @@ class PiecewiseLinearRotation(CircuitFactory):
     def __init__(self, breakpoints, slopes, offsets, num_state_qubits,
                  basis='Y', i_state=None, i_target=None):
         """
-        Constructor.
-
-        Construct piecewise-linearly-controlled Y-rotation.
-
         Args:
             breakpoints (Union(list, numpy.ndarray)): breakpoints to define
                                                         piecewise-linear function

qiskit/aqua/circuits/polynomial_rotation.py

@@ -25,7 +25,10 @@
 
 
 class PolynomialRotation(CircuitFactory):
-    r"""Polynomial rotation.
+    r"""*DEPRECATED.* Polynomial rotation.
+
+    .. deprecated:: 0.7.0
+       Use Terra's qiskit.circuit.library.PolynomialPauliRotations instead.
 
     | For a polynomial p(x), a basis state \|i> and a target qubit \|0> this operator acts as:
     |    \|i>\|0> --> \|i>( cos(p(i))\|0> + sin(p(i))\|1> )