Documentation fixes and updates (#36)

Co-authored-by: Elena Peña Tapia <[email protected]>
Co-authored-by: Julien Gacon <[email protected]>

docs/apidocs/qiskit_algorithms.AlgorithmError.rst

@@ -0,0 +1,6 @@
+AlgorithmError
+==============
+
+.. currentmodule:: qiskit_algorithms
+
+.. autoexception:: AlgorithmError

docs/apidocs/qiskit_algorithms.gradients.rst

@@ -0,0 +1,6 @@
+.. _qiskit_algorithms-gradients:
+
+.. automodule:: qiskit_algorithms.gradients
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/qiskit_algorithms.optimizers.rst

@@ -0,0 +1,6 @@
+.. _qiskit_algorithms-optimizers:
+
+.. automodule:: qiskit_algorithms.optimizers
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/qiskit_algorithms.state_fidelities.rst

@@ -0,0 +1,6 @@
+.. _qiskit_algorithms-state_fidelities:
+
+.. automodule:: qiskit_algorithms.state_fidelities
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/qiskit_algorithms.time_evolvers.trotterization.rst

@@ -0,0 +1,6 @@
+.. _qiskit_algorithms-time_evolvers-trotterization:
+
+.. automodule:: qiskit_algorithms.time_evolvers.trotterization
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/qiskit_algorithms.time_evolvers.variational.rst

@@ -0,0 +1,6 @@
+.. _qiskit_algorithms-time_evolvers-variational:
+
+.. automodule:: qiskit_algorithms.time_evolvers.variational
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/index.rst

@@ -24,7 +24,7 @@ Next Steps
 
   Overview <self>
   Getting Started <getting_started>
-  API References <apidocs/algorithms>
+  API References <apidocs/qiskit_algorithms>
   Tutorials <tutorials/index>
   Release Notes <release_notes>
   GitHub <https://github.com/qiskit-community/qiskit-algorithms>

qiskit_algorithms/__init__.py

@@ -11,29 +11,47 @@
 # that they have been altered from the originals.
 
 """
-=====================================
-Algorithms (:mod:`qiskit_algorithms`)
-=====================================
-It 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.
-
-Algorithms configuration includes the use of :mod:`~qiskit_algorithms.optimizers` 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.
+============================================
+Qiskit Algorithms (:mod:`qiskit_algorithms`)
+============================================
+Qiskit Algorithms is a library of quantum algorithms for quantum computing with
+`Qiskit <https://qiskit.org>`_.
+These algorithms can be used to carry out research and investigate how to solve
+problems in different domains on simulators and near-term real quantum devices
+using shallow circuits.
+
+The library includes some algorithms, for example the :class:`.NumPyMinimumEigensolver`, which take
+the same input as their quantum counterpart but solve the problem classically. This has utility in
+the near-term, where problems are still tractable classically, to validate and/or act as a reference.
+There are also classical :mod:`.optimizers` for use with variational algorithms such as :class:`.VQE`.
+
+This package also provides common building blocks for algorithms, such quantum circuit
+gradients (:mod:`.gradients`) and fidelities of quantum states (:mod:`.state_fidelities`).
+These elements are frequently used in a variety of applications, such as variational optimization,
+time evolution and quantum machine learning.
+
+The quantum algorithms here all use 
+`Primitives <https://qiskit.org/documentation/apidoc/primitives.html>`__ 
+to execute quantum circuits. This can be an
+``Estimator``, which computes expectation values, or a ``Sampler`` which computes
+probability distributions. Refer to the specific algorithm for more information in this regard.
 
 .. currentmodule:: qiskit_algorithms
 
 Algorithms
 ==========
 
-It contains a variety of quantum algorithms and these have been grouped by logical function such
-as minimum eigensolvers and amplitude amplifiers. These algorithms are based on the Qiskit Primitives.
-
+The algorithms now presented are grouped by logical function, such
+as minimum eigensolvers, amplitude amplifiers, time evolvers etc. Within each group, the
+algorithms conform to an interface that allows them to be used interchangeably
+by different applications. E.g. a Qiskit Nature application may take a minimum 
+eigensolver to solve a ground state problem, and require it to
+conform to the :class:`.MinimumEigensolver` interface. Any algorithm that conforms to
+the interface, for example :class:`.VQE`, can be used by this application.
 
 Amplitude Amplifiers
 --------------------
+Algorithms based on amplitude amplification.
 
 .. autosummary::
    :toctree: ../stubs/
@@ -47,6 +65,7 @@
 
 Amplitude Estimators
 --------------------
+Algorithms based on amplitude estimation.
 
 .. autosummary::
    :toctree: ../stubs/
@@ -67,105 +86,79 @@
 
 Eigensolvers
 ------------
-
 Algorithms to find eigenvalues of an operator. For chemistry these can be used to find excited
 states of a molecule, and ``qiskit-nature`` has some algorithms that leverage chemistry specific
 knowledge to do this in that application domain.
-These algorithms are based on the Qiskit Primitives.
-
-.. autosummary::
-   :toctree: ../stubs/
-
-   eigensolvers
-
-Time Evolvers
--------------
-
-Algorithms to evolve quantum states in time. Both real and imaginary time evolution is possible
-with algorithms that support them. For machine learning, Quantum Imaginary Time Evolution might be
-used to train Quantum Boltzmann Machine Neural Networks for example.
-These algorithms are based on the Qiskit Primitives.
 
 .. autosummary::
    :toctree: ../stubs/
    :nosignatures:
 
-   RealTimeEvolver
-   ImaginaryTimeEvolver
-   TimeEvolutionResult
-   TimeEvolutionProblem
-   PVQD
-   PVQDResult
-   SciPyImaginaryEvolver
-   SciPyRealEvolver
-   VarQITE
-   VarQRTE
-
-Variational Quantum Time Evolution
-++++++++++++++++++++++++++++++++++
-
-Classes used by variational quantum time evolution algorithms - :class:`.VarQITE` and
-:class:`.VarQRTE`.
-
-.. autosummary::
-   :toctree: ../stubs/
-
-   time_evolvers.variational
+   Eigensolver
+   EigensolverResult
+   NumPyEigensolver
+   NumPyEigensolverResult
+   VQD
+   VQDResult
 
 
-Trotterization-based Quantum Real Time Evolution
-++++++++++++++++++++++++++++++++++++++++++++++++
-
-Package for primitives-enabled Trotterization-based quantum time evolution
-algorithm - :class:`~.time_evolvers.TrotterQRTE`.
+Gradients
+---------
+Algorithms to calculate the gradient of a quantum circuit.
 
 .. autosummary::
-   :toctree: ../stubs/
+   :toctree:
 
-   time_evolvers.trotterization
+   gradients
 
 
-Gradients
-----------
+Minimum Eigensolvers
+--------------------
+Algorithms to find the minimum eigenvalue of an operator.
 
-Algorithms to calculate the gradient of a quantum circuit. These algorithms are based
-on the Qiskit Primitives.
+This set of these algorithms take an ``Estimator`` primitive and can
+solve for a general Hamiltonian.
 
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
-   gradients
-
-
-Minimum Eigensolvers
----------------------
+   MinimumEigensolver
+   MinimumEigensolverResult
+   NumPyMinimumEigensolver
+   NumPyMinimumEigensolverResult
+   VQE
+   VQEResult
+   AdaptVQE
+   AdaptVQEResult
 
-Algorithms that can find the minimum eigenvalue of an operator. These algorithms are
-based on the Qiskit Primitives.
+This set of algorithms take a ``Sampler`` primitive and can only
+solve for a diagonal Hamiltonian, such as an Ising Hamiltonian of an optimization problem.
 
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
-   minimum_eigensolvers
+   SamplingMinimumEigensolver
+   SamplingMinimumEigensolverResult
+   SamplingVQE
+   SamplingVQEResult
+   QAOA
 
 
 Optimizers
 ----------
-
-Classical optimizers for use by quantum variational algorithms. These algorithms
-are based on the Qiskit Primitives.
+Classical optimizers designed for use by quantum variational algorithms.
 
 .. autosummary::
-   :toctree: ../stubs/
+   :toctree:
 
    optimizers
 
 
 Phase Estimators
 ----------------
-
-Algorithms that estimate the phases of eigenstates of a unitary. These algorithms
-are based on the Qiskit Primitives.
+Algorithms that estimate the phases of eigenstates of a unitary.
 
 .. autosummary::
    :toctree: ../stubs/
@@ -181,21 +174,69 @@
 
 State Fidelities
 ----------------
+Algorithms that compute the fidelity of pairs of quantum states.
 
-Algorithms that compute the fidelity of pairs of quantum states. These algorithms
-are based on the Qiskit Primitives.
+.. autosummary::
+   :toctree:
+
+   state_fidelities
+
+
+Time Evolvers
+-------------
+Algorithms to evolve quantum states in time. Both real and imaginary time evolution is possible
+with algorithms that support them. For machine learning, Quantum Imaginary Time Evolution might be
+used to train Quantum Boltzmann Machine Neural Networks for example.
 
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
-   state_fidelities
+   RealTimeEvolver
+   ImaginaryTimeEvolver
+   TimeEvolutionResult
+   TimeEvolutionProblem
+   PVQD
+   PVQDResult
+   SciPyImaginaryEvolver
+   SciPyRealEvolver
+   VarQITE
+   VarQRTE
+
+Variational Quantum Time Evolution
+++++++++++++++++++++++++++++++++++
+Classes used by variational quantum time evolution algorithms -
+:class:`.VarQITE` and :class:`.VarQRTE`.
+
+.. autosummary::
+   :toctree:
+
+   time_evolvers.variational
+
+
+Trotterization-based Quantum Real Time Evolution
+++++++++++++++++++++++++++++++++++++++++++++++++
+Trotterization-based quantum time evolution algorithms -
+:class:`~.time_evolvers.trotterization.TrotterQRTE`.
+
+.. autosummary::
+   :toctree:
+
+   time_evolvers.trotterization
+
+
+Miscellaneous
+=============
+Various classes used by qiskit-algorithms that are part of and exposed
+by the public API.
 
 
 Exceptions
 ----------
 
 .. autosummary::
-   :toctree: ../stubs/
+   :toctree:
+   :nosignatures:
 
    AlgorithmError
 
@@ -207,6 +248,7 @@
 
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
    AlgorithmJob
 

qiskit_algorithms/eigensolvers/__init__.py

@@ -10,34 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
-=====================================================================
-Eigensolvers Package (:mod:`qiskit_algorithms.eigensolvers`)
-=====================================================================
-
-.. currentmodule:: qiskit_algorithms.eigensolvers
-
-Eigensolvers
-================
-
-.. autosummary::
-   :toctree: ../stubs/
-
-   Eigensolver
-   NumPyEigensolver
-   VQD
-
-Results
-=======
-
- .. autosummary::
-    :toctree: ../stubs/
-
-    EigensolverResult
-    NumPyEigensolverResult
-    VQDResult
-
-"""
+"""The Eigensolvers package"""
 
 from .numpy_eigensolver import NumPyEigensolver, NumPyEigensolverResult
 from .eigensolver import Eigensolver, EigensolverResult