Merge pull request #817 from woodsp-ibm/moredocs

Updating component documentation

.pylintdict

@@ -37,6 +37,7 @@ baseoperator
 bb
 bergholm
 bfgs
+binom
 bitstr
 bitstring
 bitstrings
@@ -49,6 +50,7 @@ boolean
 bpa
 brassard
 bravyi
+broyden
 cargs
 ccphase
 cct
@@ -122,13 +124,15 @@ discretization
 discretize
 discretized
 discriminative
+disjoined
 disjunction
 disp
 distro
 dj
 dnf
 docplex
 dp
+ecc
 ee
 eigen
 eigensolver
@@ -163,6 +167,7 @@ filepath
 fm
 fock
 formatter
+formulae
 fortran
 fourier
 ftol
@@ -181,6 +186,7 @@ getattr
 getter
 github
 gogolin
+goldfarb
 gfortran
 globals
 graycode
@@ -250,19 +256,23 @@ kth
 kumar
 kwargs
 labelled
+ldots
 len
 leq
 lhs
 lih
 lijh
 lin
 lmin
+lnot
 loglikelihood
 logn
 lognormal
+lor
 lr
 lst
 majorana
+mathbb
 mathsf
 matrixoperator
 maxcut
@@ -285,6 +295,7 @@ minibatch
 minibatched
 minibatches
 minibatching
+minima
 mintert
 minwidth
 mitarai
@@ -315,6 +326,7 @@ negoro
 nelder
 neq
 nevals
+newtons's
 nfev
 nk
 nlopt
@@ -344,6 +356,7 @@ optim
 optimizer's
 optimizers
 org
+overfit
 params
 parentname
 pauli
@@ -427,6 +440,7 @@ rohf
 rosen
 rsgtu
 rtype
+runarsson
 RunConfig
 ry
 rz
@@ -443,9 +457,11 @@ scipy
 sd
 sdg
 sdk
+seealso
 seeley
 setia
 sgn
+shanno
 shor
 shor's
 sigmoid
@@ -512,6 +528,7 @@ uncompiled
 uncompute
 uncomputed
 uncomputing
+unentangled
 unitaries
 unittest
 univariate
@@ -544,15 +561,18 @@ xatol
 xc
 xixj
 xopt
+xor
 xtol
 xuxv
 xyz
+yao
 yc
 yy
 zi
 zmatrix
 zv
 ZZ
+zzz
 äguivalenzverbot
 über
 ucc

qiskit/aqua/algorithms/__init__.py

@@ -17,9 +17,18 @@
 ==========================================
 Aqua contains a collection of quantum algorithms, for use with quantum computers, to
 carry out research and investigate how to solve problems in different domains on
-near-term quantum devices with short depth circuits. Aqua uses
-`Terra <https://www.qiskit.org/terra>`__ for compilation and execution
-of the quantum circuits required by the algorithm for the specific problems.
+near-term quantum devices with short depth circuits.
+
+Algorithms configuration includes the use of :mod:`~qiskit.aqua.components` which
+were designed to be swappable sub-parts of an algorithm. Any component and may be exchanged for
+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
+`Terra <https://www.qiskit.org/terra>`__ for the actual compilation and execution of the quantum
+circuits created by the algorithm and its components.
 
 .. currentmodule:: qiskit.aqua.algorithms
 

qiskit/aqua/components/__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,7 +15,27 @@
 """
 Components (:mod:`qiskit.aqua.components`)
 ==========================================
-Components form part of an algorithm....
+Components were designed to be swappable sub-parts of an algorithm. Different implementations
+of a component type can thereby be exchanged to potentially alter the behavior and outcome of
+the algorithm. For example :class:`~qiskit.aqua.algorithms.VQE` takes an
+:class:`~qiskit.aqua.components.optimizers.Optimizer` and a
+:class:`~qiskit.aqua.components.variational_forms.VariationalForm` components. There are a
+selection of both different :mod:`~qiskit.aqua.components.optimizers` and
+:mod:`~qiskit.aqua.components.variational_forms` that can be chosen from according the nature of
+the problem. Some optimizers use gradients, others have alternative techniques to finding a
+minimum. Variational forms include heuristic ansatzes such as
+:class:`~qiskit.aqua.components.variational_forms.RYRZ` and types designed for specific problems
+such as :class:`~qiskit.chemistry.components.variational_forms.UCCSD` for chemistry and ground
+state energy computation.
+
+Components may also be used in other components. For example the
+:class:`~qiskit.aqua.components.uncertainty_models.UnivariateVariationalDistribution` takes a
+:class:`~qiskit.aqua.components.variational_forms.VariationalForm`.
+
+Each type of component has a base class that can be extended to provide a new implementation. For
+example the base class for :mod:`~qiskit.aqua.components.variational_forms` is
+:class:`~qiskit.aqua.components.variational_forms.VariationalForm`. For more information refer
+to the component type of interest below.
 
 .. currentmodule:: qiskit.aqua.components
 

qiskit/aqua/components/eigs/__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,7 +15,8 @@
 """
 Eigenvalues (:mod:`qiskit.aqua.components.eigs`)
 ================================================
-Eigenvalue components - principally used by HHL
+These are components designed to find eigenvalues. They were initially designed for use by
+:class:`~qiskit.aqua.algorithms.HHL` which remains their currently principal usage.
 
 .. currentmodule:: qiskit.aqua.components.eigs
 

qiskit/aqua/components/eigs/eigs_qpe.py

@@ -12,7 +12,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-""" PhaseEstimationCircuit for getting the eigenvalues of a matrix. """
+""" Quantum Phase Estimation for getting the eigenvalues of a matrix. """
 
 from typing import Optional, List
 import numpy as np
@@ -28,12 +28,13 @@
 
 
 class EigsQPE(Eigenvalues):
+    """
+    Eigenvalues using Quantum Phase Estimation
 
-    """ This class embeds a PhaseEstimationCircuit for getting the eigenvalues of a matrix.
-
-    Specifically, this class is based on PhaseEstimationCircuit with no measurements and additional
-    handling of negative eigenvalues, e.g. for HHL. It uses many parameters
-    known from plain QPE. It depends on QFT and IQFT.
+    Specifically, this class is based on PhaseEstimationCircuit with no measurements and
+    has additional handling of negative eigenvalues, e.g. for :class:`~qiskit.aqua.algorithms.HHL`.
+    It depends on :mod:`QFT <qiskit.aqua.components.qfts>` and
+    :mod:`IQFT <qiskit.aqua.components.iqfts>` components.
     """
 
     def __init__(self,
@@ -46,19 +47,20 @@ def __init__(self,
                  evo_time: Optional[float] = None,
                  negative_evals: bool = False,
                  ne_qfts: Optional[List] = None) -> None:
-        """Constructor.
-
+        """
         Args:
-            operator: the hamiltonian Operator object
-            iqft: the Inverse Quantum Fourier Transform component
-            num_time_slices: the number of time slices, has a min. value of 1.
-            num_ancillae: the number of ancillary qubits to use for the measurement,
-                            has a min. value of 1.
-            expansion_mode: the expansion mode (trotter|suzuki)
-            expansion_order: the suzuki expansion order, has a min. value of 1.
-            evo_time: the evolution time
-            negative_evals: indicate if negative eigenvalues need to be handled
-            ne_qfts: the QFT and IQFT components for handling negative eigenvalues
+            operator: The Hamiltonian Operator object
+            iqft: The Inverse Quantum Fourier Transform component
+            num_time_slices: The number of time slices, has a minimum value of 1.
+            num_ancillae: The number of ancillary qubits to use for the measurement,
+                has a minimum value of 1.
+            expansion_mode: The expansion mode ('trotter' | 'suzuki')
+            expansion_order: The suzuki expansion order, has a minimum value of 1.
+            evo_time: An optional evolution time which should scale the eigenvalue onto the range
+                :math:`(0,1]` (or :math:`(-0.5,0.5]` for negative eigenvalues). Defaults to
+                ``None`` in which case a suitably estimated evolution time is internally computed.
+            negative_evals: Set ``True`` to indicate negative eigenvalues need to be handled
+            ne_qfts: The QFT and IQFT components for handling negative eigenvalues
         """
         super().__init__()
         ne_qfts = ne_qfts if ne_qfts is not None else [None, None]

qiskit/aqua/components/feature_maps/__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,7 +15,27 @@
 """
 Feature Maps (:mod:`qiskit.aqua.components.feature_maps`)
 =========================================================
-Feature Maps...
+In machine learning, pattern recognition and image processing, a **feature map**
+starts from an initial set of measured data and builds derived values (also known as
+**features**) intended to be informative and non-redundant, facilitating the subsequent
+learning and generalization steps, and in some cases leading to better human
+interpretations.
+
+A feature map is related to **dimensionality reduction**; it involves reducing the amount of
+resources required to describe a large set of data. When performing analysis of complex data,
+one of the major problems stems from the number of variables involved. Analysis with a large
+number of variables generally requires a large amount of memory and computation power, and may
+even cause a classification algorithm to overfit to training samples and generalize poorly to new
+samples.
+
+When the input data to an algorithm is too large to be processed and is suspected to be redundant
+(for example, the same measurement is provided in both pounds and kilograms), then it can be
+transformed into a reduced set of features, named a **feature vector**.
+
+The process of determining a subset of the initial features is called **feature selection**.
+The selected features are expected to contain the relevant information from the input data,
+so that the desired task can be performed by using the reduced representation instead
+of the complete initial data.
 
 .. currentmodule:: qiskit.aqua.components.feature_maps
 

qiskit/aqua/components/feature_maps/feature_map.py

@@ -23,11 +23,12 @@
 
 class FeatureMap(ABC):
 
-    """Base class for FeatureMap.
+    """
+    Base class for FeatureMap.
 
-        This method should initialize the module and
-        use an exception if a component of the module is not
-        available.
+    This method should initialize the module and
+    use an exception if a component of the module is not
+    available.
     """
 
     @abstractmethod

qiskit/aqua/components/feature_maps/first_order_expansion.py

@@ -12,8 +12,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 """
-This module contains the definition of a base class for
-feature map. Several types of commonly used approaches.
+First Order Expansion feature map.
 """
 
 from typing import Callable
@@ -25,21 +24,22 @@
 
 class FirstOrderExpansion(PauliZExpansion):
     """
-    Mapping data with the first order expansion without entangling gates.
+    First Order Expansion feature map.
 
-    Refer to https://arxiv.org/pdf/1804.11326.pdf for details.
+    This is a sub-class of :class:`PauliZExpansion` where *z_order* is fixed at 1.
+    As a result the first order expansion will be a feature map without entangling gates.
     """
 
     def __init__(self,
                  feature_dimension: int,
                  depth: int = 2,
                  data_map_func: Callable[[np.ndarray], float] = self_product) -> None:
-        """Constructor.
-
+        """
         Args:
-            feature_dimension: number of features
-            depth: the number of repeated circuits, has a min. value of 1.
-            data_map_func: a mapping function for data x
+            feature_dimension: The number of features
+            depth: The number of repeated circuits. Defaults to 2, has a minimum value of 1.
+            data_map_func: A mapping function for data x which can be supplied to override the
+                default mapping from :meth:`self_product`.
         """
         validate_min('depth', depth, 1)
         super().__init__(feature_dimension, depth, z_order=1, data_map_func=data_map_func)