Update Optimization documentation

docs/apidocs/qiskit.optimization.algorithms.rst

@@ -0,0 +1,6 @@
+.. _qiskit-optimization-algorithms:
+
+.. automodule:: qiskit.optimization.algorithms
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/qiskit.optimization.applications.ising.rst

@@ -0,0 +1,6 @@
+.. _qiskit-optimization-applications-ising:
+
+.. automodule:: qiskit.optimization.applications.ising
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/qiskit.optimization.applications.rst

@@ -0,0 +1,6 @@
+.. _qiskit-optimization-applications:
+
+.. automodule:: qiskit.optimization.applications
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/qiskit.optimization.converters.rst

@@ -0,0 +1,6 @@
+.. _qiskit-optimization-converters:
+
+.. automodule:: qiskit.optimization.converters
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/qiskit.optimization.problems.rst

@@ -0,0 +1,6 @@
+.. _qiskit-optimization-problems:
+
+.. automodule:: qiskit.optimization.problems
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

qiskit/optimization/__init__.py

@@ -18,22 +18,75 @@
 
 .. currentmodule:: qiskit.optimization
 
-Contents
-========
+Qiskit Optimization covers the whole stack from high-level modeling of optimization
+problems, with automatic conversion of problems to different required representations,
+to a suite of easy-to-use quantum optimization algorithms that are ready to run on
+classical simulators, as well as on real quantum devices via Qiskit.
+
+Qiskit Optimization enables easy, efficient modeling of optimization problems using `docplex
+<https://developer.ibm.com/docloud/documentation/optimization-modeling/modeling-for-python/>`_
+A uniform interface as well as automatic conversion between different problem representations
+allows users to solve problems using a large set of algorithms, from variational quantum algorithms,
+such as the Quantum Approximate Optimization Algorithm
+(:class:`~qiskit.aqua.algorithms.QAOA`), to
+`Grover Adaptive Search <https://arxiv.org/abs/quant-ph/9607014>`_
+(:class:`~algorithms.GroverOptimizer`), leveraging
+fundamental :mod:`~qiskit.aqua.algorithms` provided by Qiskit Aqua. Furthermore, the modular design
+of Qiskit Optimization allows it to be easily extended and facilitates rapid development and
+testing of new algorithms. Compatible classical optimizers are also provided for testing,
+validation, and benchmarking.
+
+Qiskit Optimization supports Quadratically Constrained Quadratic Programs – for simplicity we refer
+to them just as Quadratic Programs – with binary, integer, and continuous variables, as well as
+equality and inequality constraints. This class of optimization problems has a vast amount of
+relevant applications, while still being efficiently representable by matrices and vectors.
+This class covers some very interesting sub-classes, from Convex Continuous Quadratic Programs,
+which can be solved efficiently by classical optimization algorithms, to Quadratic Unconstrained
+Binary Optimization QUBO) problems, which cover many NP-complete, i.e., classically intractable,
+problems.
 
 .. autosummary::
    :toctree: ../stubs/
    :nosignatures:
 
     QuadraticProgram
+
+Representation of a Quadratically Constrained Quadratic Program supporting inequality and
+equality constraints as well as continuous, binary, and integer variables.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
     QiskitOptimizationError
+
+In addition to standard Python errors Qiskit Optimization will raise this error if circumstances
+are that it cannot proceed to completion.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
     INFINITY
 
+A constant for infinity.
+
+Submodules
+==========
+
+.. autosummary::
+   :toctree:
+
+   algorithms
+   applications
+   converters
+   problems
+
 """
 
 from .infinity import INFINITY  # must be at the top of the file
 from .exceptions import QiskitOptimizationError
-from .problems import QuadraticProgram
+from .problems.quadratic_program import QuadraticProgram
 from ._logging import (get_qiskit_optimization_logging,
                        set_qiskit_optimization_logging)
 

qiskit/optimization/algorithms/__init__.py

@@ -13,11 +13,10 @@
 # that they have been altered from the originals.
 
 """
-===================================================================
-Optimization stack for Aqua (:mod:`qiskit.optimization.algorithms`)
-===================================================================
+Optimization algorithms (:mod:`qiskit.optimization.algorithms`)
+===============================================================
 
-Algorithms for optimization algorithms.
+Algorithms for optimization problems.
 
 .. currentmodule:: qiskit.optimization.algorithms
 

qiskit/optimization/algorithms/admm_optimizer.py

@@ -19,12 +19,13 @@
 from typing import List, Optional, Any
 
 import numpy as np
-from qiskit.optimization import QiskitOptimizationError
-from qiskit.optimization.algorithms.cplex_optimizer import CplexOptimizer
-from qiskit.optimization.algorithms.optimization_algorithm import (OptimizationAlgorithm,
-                                                                   OptimizationResult)
-from qiskit.optimization.converters import IntegerToBinary
-from qiskit.optimization.problems import QuadraticProgram, Variable, Constraint, QuadraticObjective
+from ..exceptions import QiskitOptimizationError
+from .cplex_optimizer import CplexOptimizer
+from .optimization_algorithm import OptimizationAlgorithm, OptimizationResult
+from ..problems.quadratic_program import QuadraticProgram
+from ..problems.variable import Variable
+from ..problems.constraint import Constraint
+from ..problems.quadratic_objective import QuadraticObjective
 
 UPDATE_RHO_BY_TEN_PERCENT = 0
 UPDATE_RHO_BY_RESIDUALS = 1
@@ -251,6 +252,7 @@ def solve(self, problem: QuadraticProgram) -> ADMMOptimizationResult:
         self._log.debug("Initial problem: %s", problem.export_as_lp_string())
 
         # map integer variables to binary variables
+        from ..converters.integer_to_binary import IntegerToBinary
         int2bin = IntegerToBinary()
         problem = int2bin.encode(problem)
 

qiskit/optimization/algorithms/cobyla_optimizer.py

@@ -20,20 +20,24 @@
 import numpy as np
 from scipy.optimize import fmin_cobyla
 
-from qiskit.optimization.algorithms import OptimizationAlgorithm, OptimizationResult
-from qiskit.optimization.problems import QuadraticProgram, Constraint
-from qiskit.optimization import QiskitOptimizationError, INFINITY
+from .optimization_algorithm import OptimizationAlgorithm, OptimizationResult
+from ..problems.quadratic_program import QuadraticProgram
+from ..problems.constraint import Constraint
+from ..exceptions import QiskitOptimizationError
+from ..infinity import INFINITY
 
 
 class CobylaOptimizer(OptimizationAlgorithm):
-    """The SciPy COBYLA optimizer wrapped as an Qiskit ``OptimizationAlgorithm``.
+    """The SciPy COBYLA optimizer wrapped as an Qiskit :class:`OptimizationAlgorithm`.
 
     This class provides a wrapper for ``scipy.optimize.fmin_cobyla``
     (https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.optimize.fmin_cobyla.html)
     to be used within Qiskit Optimization.
     The arguments for ``fmin_cobyla`` are passed via the constructor.
 
     Examples:
+        >>> from qiskit.optimization.problems import QuadraticProgram
+        >>> from qiskit.optimization.algorithms import CobylaOptimizer
         >>> problem = QuadraticProgram()
         >>> # specify problem here
         >>> optimizer = CobylaOptimizer()

qiskit/optimization/algorithms/cplex_optimizer.py

@@ -33,12 +33,14 @@
 
 
 class CplexOptimizer(OptimizationAlgorithm):
-    """The CPLEX optimizer wrapped as an Qiskit ``OptimizationAlgorithm``.
+    """The CPLEX optimizer wrapped as an Qiskit :class:`OptimizationAlgorithm`.
 
     This class provides a wrapper for ``cplex.Cplex`` (https://pypi.org/project/cplex/)
     to be used within Qiskit Optimization.
 
     Examples:
+        >>> from qiskit.optimization.problems import QuadraticProgram
+        >>> from qiskit.optimization.algorithms import CplexOptimizer
         >>> problem = QuadraticProgram()
         >>> # specify problem here
         >>> optimizer = CplexOptimizer()

qiskit/optimization/algorithms/grover_optimizer.py

@@ -22,13 +22,13 @@
 from qiskit import QuantumCircuit
 from qiskit.providers import BaseBackend
 from qiskit.aqua import QuantumInstance
-from qiskit.optimization import QiskitOptimizationError
-from qiskit.optimization.algorithms import OptimizationAlgorithm
-from qiskit.optimization.problems import QuadraticProgram
-from qiskit.optimization.converters import (QuadraticProgramToQubo,
-                                            QuadraticProgramToNegativeValueOracle)
-from qiskit.optimization.algorithms.optimization_algorithm import OptimizationResult
 from qiskit.aqua.algorithms.amplitude_amplifiers.grover import Grover
+from ..exceptions import QiskitOptimizationError
+from .optimization_algorithm import OptimizationAlgorithm, OptimizationResult
+from ..problems.quadratic_program import QuadraticProgram
+from ..converters.quadratic_program_to_qubo import QuadraticProgramToQubo
+from ..converters.quadratic_program_to_negative_value_oracle import \
+    QuadraticProgramToNegativeValueOracle
 
 
 logger = logging.getLogger(__name__)

qiskit/optimization/algorithms/minimum_eigen_optimizer.py

@@ -26,7 +26,7 @@
 from ..problems.quadratic_program import QuadraticProgram
 from ..converters.quadratic_program_to_operator import QuadraticProgramToOperator
 from ..converters.quadratic_program_to_qubo import QuadraticProgramToQubo
-from .. import QiskitOptimizationError
+from ..exceptions import QiskitOptimizationError
 
 
 class MinimumEigenOptimizerResult(OptimizationResult):
@@ -67,9 +67,10 @@ def get_correlations(self):
 
 
 class MinimumEigenOptimizer(OptimizationAlgorithm):
-    """A wrapper for minimum eigen solvers from Qiskit Aqua to be used within Qiskit Optimization.
+    """A wrapper for minimum eigen solvers from Qiskit Aqua.
 
-    This class provides a wrapper for minimum eigen solvers from Qiskit Aqua.
+    This class provides a wrapper for minimum eigen solvers from Qiskit Aqua to be used within
+    Qiskit Optimization.
     It assumes a problem consisting only of binary or integer variables as well as linear equality
     constraints thereof. It converts such a problem into a Quadratic Unconstrained Binary
     Optimization (QUBO) problem by expanding integer variables into binary variables and by adding
@@ -80,12 +81,19 @@ class MinimumEigenOptimizer(OptimizationAlgorithm):
     Hamiltonian to find a good solution for the optimization problem.
 
     Examples:
-        >>> problem = QuadraticProgram()
-        >>> # specify problem here
-        >>> # specify minimum eigen solver to be used, e.g., QAOA
-        >>> qaoa = QAOA(...)
-        >>> optimizer = MinEigenOptimizer(qaoa)
-        >>> result = optimizer.solve(problem)
+        Outline of how to use this class:
+
+    .. code-block::
+
+        from qiskit.aqua.algorithms import QAOA
+        from qiskit.optimization.problems import QuadraticProgram
+        from qiskit.optimization.algorithms import MinimumEigenOptimizer
+        problem = QuadraticProgram()
+        # specify problem here
+        # specify minimum eigen solver to be used, e.g., QAOA
+        qaoa = QAOA(...)
+        optimizer = MinimumEigenOptimizer(qaoa)
+        result = optimizer.solve(problem)
     """
 
     def __init__(self, min_eigen_solver: MinimumEigensolver, penalty: Optional[float] = None

qiskit/optimization/algorithms/recursive_minimum_eigen_optimizer.py

@@ -39,12 +39,19 @@ class RecursiveMinimumEigenOptimizer(OptimizationAlgorithm):
     The algorithm is introduced in [1].
 
     Examples:
-        >>> problem = QuadraticProgram()
-        >>> # specify problem here
-        >>> # specify minimum eigen solver to be used, e.g., QAOA
-        >>> qaoa = QAOA(...)
-        >>> optimizer = RecursiveMinEigenOptimizer(qaoa)
-        >>> result = optimizer.solve(problem)
+        Outline of how to use this class:
+
+    .. code-block::
+
+        from qiskit.aqua.algorithms import QAOA
+        from qiskit.optimization.problems import QuadraticProgram
+        from qiskit.optimization.algorithms import RecursiveMinimumEigenOptimizer
+        problem = QuadraticProgram()
+        # specify problem here
+        # specify minimum eigen solver to be used, e.g., QAOA
+        qaoa = QAOA(...)
+        optimizer = RecursiveMinimumEigenOptimizer(qaoa)
+        result = optimizer.solve(problem)
 
     References:
         [1]: Bravyi et al. (2019), Obstacles to State Preparation and Variational Optimization

qiskit/optimization/applications/__init__.py

@@ -11,3 +11,22 @@
 # 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.
+
+"""
+Optimization applications (:mod:`qiskit.aqua.applications`)
+===========================================================
+
+.. currentmodule:: qiskit.optimization.applications
+
+Applications for Qiskit Optimization. The present set are in the form of
+Ising Hamiltonians.
+
+Submodules
+==========
+
+.. autosummary::
+   :toctree:
+
+   ising
+
+"""

qiskit/optimization/applications/ising/__init__.py

@@ -15,7 +15,7 @@
 """
 Ising Models (:mod:`qiskit.optimization.applications.ising`)
 ============================================================
-Ising models for optimization problems
+Ising models for optimization application problems
 
 .. currentmodule:: qiskit.optimization.applications.ising
 

qiskit/optimization/converters/__init__.py

@@ -13,26 +13,28 @@
 # that they have been altered from the originals.
 
 """
-===================================================================
-Optimization stack for Aqua (:mod:`qiskit.optimization.converters`)
-===================================================================
+Optimization converters (:mod:`qiskit.optimization.converters`)
+===============================================================
 
 .. currentmodule:: qiskit.optimization.converters
 
-Structures for converting optimization problems
-===============================================
+This is selection of converters having encode, decode functionality to go between different
+forms.
+
+Converters
+==========
 
 .. autosummary::
    :toctree: ../stubs/
    :nosignatures:
 
-    InequalityToEquality
-    IntegerToBinary
-    QuadraticProgramToNegativeValueOracle
-    QuadraticProgramToOperator
-    QuadraticProgramToQubo
-    LinearEqualityToPenalty
-    OperatorToQuadraticProgram
+   InequalityToEquality
+   IntegerToBinary
+   QuadraticProgramToNegativeValueOracle
+   QuadraticProgramToOperator
+   QuadraticProgramToQubo
+   LinearEqualityToPenalty
+   OperatorToQuadraticProgram
 
 """