docplex optimizers (#57)

* fix typo in readme * update docplex requirements, and add dependency to qiskit_optimization * add optimizers' wrappers * add simple test * documentation * flake8 * missing modification in requirements.txt * Update test_docplex.py add comments to `test_get_square_cont_var` * Update test_docplex.py * Update requirements.txt * Update setup.py * Update requirements.txt * Update test_docplex.py typo * Update docplex.py Add description of module docplex.ply Co-authored-by: toncho11 <toncho11@gmail.com> Co-authored-by: gcattan <gregoire.cattan@ibm.com> Co-authored-by: toncho11 <toncho11@gmail.com>
pyRiemann · Jul 18, 2022 · 84e4d5f · 84e4d5f
1 parent e24bb6f
commit 84e4d5f
Show file tree

Hide file tree

Showing 8 changed files with 318 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -92,7 +92,7 @@ Full documentation, including API description, is available at <https://pyrieman
 To run a specific example on your local machine, you should install first dependencies for the documentation:
 
 ```
-pip install .[doc]
+pip install .[docs]
 ```
 
 Then you can run the python example of your choice like:
@@ -143,7 +143,7 @@ Code contribution (pull request) can be either on core functionalities, document
 - Automation is based on `GitHub Action` and `pytest`. It consists in two automated workflows for running the example and the tests. To run the tests on your local machine, you should first install the dependencies for testing:
 
     ```
-    pip install .[test]
+    pip install .[tests]
     ```
 
     and then type `pytest` from the root repository. You can also specify a file like:

diff --git a/doc/api.rst b/doc/api.rst
@@ -58,6 +58,9 @@ Docplex
     square_cont_mat_var
     square_int_mat_var
     square_bin_mat_var
+    pyQiskitOptimizer
+    ClassicalOptimizer
+    NaiveQAOAOptimizer
 
 Datasets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -10,7 +10,8 @@ pandas
 cvxpy==1.1.12
 qiskit_machine_learning==0.4.0
 qiskit-ibmq-provider==0.19.1
+qiskit-optimization==0.4.0
 scipy==1.7.3
 moabb>=0.4.6
 git+https://github.com/pyRiemann/pyRiemann#egg=pyriemann
-docplex
+docplex>=2.21.207
diff --git a/pyriemann_qiskit/utils/__init__.py b/pyriemann_qiskit/utils/__init__.py
@@ -1,12 +1,16 @@
 from . import hyper_params_factory, filtering
 from .docplex import (square_cont_mat_var,
                       square_int_mat_var,
-                      square_bin_mat_var)
+                      square_bin_mat_var,
+                      ClassicalOptimizer,
+                      NaiveQAOAOptimizer)
 
 __all__ = [
     'hyper_params_factory',
     'filtering',
     'square_cont_mat_var',
     'square_int_mat_var',
-    'square_bin_mat_var'
+    'square_bin_mat_var',
+    'ClassicalOptimizer',
+    'NaiveQAOAOptimizer'
 ]
diff --git a/pyriemann_qiskit/utils/docplex.py b/pyriemann_qiskit/utils/docplex.py
@@ -1,4 +1,19 @@
+"""This module contains both classic and quantum optimizers, and some helper
+functions. The quantum optimizer allows an optimization problem with
+constraints (in the form of docplex model) to be run on a quantum computer.
+It is for example suitable for:
+- MDM optimization problem;
+- computation of matrices mean.
+"""
 from docplex.mp.vartype import ContinuousVarType, IntegerVarType, BinaryVarType
+from qiskit import BasicAer
+from qiskit.utils import QuantumInstance
+from qiskit.algorithms import QAOA
+from qiskit_optimization.algorithms import (CobylaOptimizer,
+                                            MinimumEigenOptimizer)
+from qiskit_optimization.converters import IntegerToBinary
+from qiskit_optimization.problems import QuadraticProgram
+import numpy as np
 
 
 def square_cont_mat_var(prob, channels,
@@ -16,6 +31,9 @@ def square_cont_mat_var(prob, channels,
     channels : list
         The list of channels. A channel can be any Python object,
         such as channels'name or number but None.
+    name : string
+        An custom name for the variable. The name is used internally by docplex
+        and may appear if your print the model to a file for example.
 
     Returns
     -------
@@ -24,6 +42,10 @@ def square_cont_mat_var(prob, channels,
         Access element (i, j) with square_mat[(i, j)].
         Indices start with 0.
 
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+
     References
     ----------
     .. [1] \
@@ -49,6 +71,9 @@ def square_int_mat_var(prob, channels,
     channels : list
         The list of channels. A channel can be any Python object,
         such as channels'name or number but None.
+    name : string
+        An custom name for the variable. The name is used internally by docplex
+        and may appear if your print the model to a file for example.
 
     Returns
     -------
@@ -57,6 +82,10 @@ def square_int_mat_var(prob, channels,
         Access element (i, j) with square_mat[(i, j)].
         Indices start with 0.
 
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+
     References
     ----------
     .. [1] \
@@ -82,6 +111,9 @@ def square_bin_mat_var(prob, channels,
     channels : list
         The list of channels. A channel can be any Python object,
         such as channels'name or number but None.
+    name : string
+        An custom name for the variable. The name is used internally by docplex
+        and may appear if your print the model to a file for example.
 
     Returns
     -------
@@ -90,6 +122,10 @@ def square_bin_mat_var(prob, channels,
         Access element (i, j) with square_mat[(i, j)].
         Indices start with 0.
 
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+
     References
     ----------
     .. [1] \
@@ -98,3 +134,249 @@ def square_bin_mat_var(prob, channels,
     BinaryVarType.one_letter_symbol = lambda _: 'B'
     return prob.binary_var_matrix(keys1=channels, keys2=channels,
                                   name=name)
+
+
+class pyQiskitOptimizer():
+
+    """Wrapper for Qiskit optimizer.
+
+    This class is an abstract class which provides an interface
+    for running our docplex model independently of the optimizer type
+    (such as classical or quantum optimizer).
+
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+    """
+    def __init__(self):
+        pass
+
+    """Hook to apply some transformation on a covariance matrix.
+
+    Parameters
+    ----------
+    covmat : ndarray, shape (n_features, n_features)
+        The covariance matrix.
+    precision : float
+        Additional parameter for the transformation.
+
+    Returns
+    -------
+    transformed_covmat : ndarray, shape (n_features, n_features)
+        A transformation of the covariance matrix.
+
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+    """
+    def convert_covmat(self, covmat, precision=None):
+        return covmat
+
+    """Helper to create a docplex representation of a
+    covariance matrix variable.
+
+    Parameters
+    ----------
+    prob : Model
+        An instance of the docplex model [1]_
+    channels : list
+        The list of channels. A channel can be any Python object,
+        such as channels'name or number but None.
+    name : string
+        An custom name for the variable. The name is used internally by docplex
+        and may appear if your print the model to a file for example.
+
+    Returns
+    -------
+    docplex_covmat : dict
+        A square matrix of decision variables representing
+        our covariance matrix.
+
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+
+    References
+    ----------
+    .. [1] \
+        http://ibmdecisionoptimization.github.io/docplex-doc/mp/_modules/docplex/mp/model.html#Model
+
+    """
+    def covmat_var(self, prob, channels, name):
+        raise NotImplementedError()
+
+    def _solve_qp(self, qp):
+        raise NotImplementedError()
+
+    """Solve the docplex problem.
+
+    Parameters
+    ----------
+    prob : Model
+        An instance of the docplex model [1]_
+
+    Returns
+    -------
+    result : OptimizationResult
+        The result of the optimization.
+
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+
+    References
+    ----------
+    .. [1] \
+        http://ibmdecisionoptimization.github.io/docplex-doc/mp/_modules/docplex/mp/model.html#Model
+
+    """
+    def solve(self, prob):
+        qp = QuadraticProgram()
+        qp.from_docplex(prob)
+        return self._solve_qp(qp)
+
+
+class ClassicalOptimizer(pyQiskitOptimizer):
+
+    """Wrapper for the classical Cobyla optimizer.
+
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+
+    See Also
+    --------
+    pyQiskitOptimizer
+
+    """
+    def __init__(self):
+        pass
+
+    """Helper to create a docplex representation of a
+    covariance matrix variable.
+
+    Parameters
+    ----------
+    prob : Model
+        An instance of the docplex model [1]_
+    channels : list
+        The list of channels. A channel can be any Python object,
+        such as channels'name or number but None.
+    name : string
+        An custom name for the variable. The name is used internally by docplex
+        and may appear if your print the model to a file for example.
+
+    Returns
+    -------
+    docplex_covmat : dict
+        A square matrix of continuous decision variables representing
+        our covariance matrix.
+
+    See Also
+    -----
+    square_cont_mat_var
+
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+
+    References
+    ----------
+    .. [1] \
+        http://ibmdecisionoptimization.github.io/docplex-doc/mp/_modules/docplex/mp/model.html#Model
+
+    """
+    def covmat_var(self, prob, channels, name):
+        return square_cont_mat_var(prob, channels, name)
+
+    def _solve_qp(self, qp):
+        return CobylaOptimizer(rhobeg=0.01, rhoend=0.0001).solve(qp)
+
+
+class NaiveQAOAOptimizer(pyQiskitOptimizer):
+
+    """Wrapper for the quantum optimizer QAOA.
+
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+
+    See Also
+    --------
+    pyQiskitOptimizer
+    """
+    def __init__(self):
+        pass
+
+    """Transform all values in the covariance matrix
+    to integers.
+
+    Example:
+    0.123 -> 1230
+
+    Parameters
+    ----------
+    covmat : ndarray, shape (n_features, n_features)
+        The covariance matrix.
+    precision : float (default: 10**4)
+        new_value = round(value * `precision`)
+
+    Returns
+    -------
+    transformed_covmat : ndarray, shape (n_features, n_features)
+        A transformation of the covariance matrix.
+
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+
+    """
+    def convert_covmat(self, covmat, precision=10**4):
+        return np.round(covmat * precision, 0)
+
+    """Helper to create a docplex representation of a
+    covariance matrix variable.
+
+    Parameters
+    ----------
+    prob : Model
+        An instance of the docplex model [1]_
+    channels : list
+        The list of channels. A channel can be any Python object,
+        such as channels'name or number but None.
+    name : string
+        An custom name for the variable. The name is used internally by docplex
+        and may appear if your print the model to a file for example.
+
+    Returns
+    -------
+    docplex_covmat : dict
+        A square matrix of integer decision variables representing
+        our covariance matrix.
+
+    See Also
+    -----
+    square_int_mat_var
+
+    Notes
+    -----
+    .. versionadded:: 0.0.2
+
+    References
+    ----------
+    .. [1] \
+        http://ibmdecisionoptimization.github.io/docplex-doc/mp/_modules/docplex/mp/model.html#Model
+
+    """
+    def covmat_var(self, prob, channels, name):
+        return square_int_mat_var(prob, channels, name)
+
+    def _solve_qp(self, qp):
+        conv = IntegerToBinary()
+        qubo = conv.convert(qp)
+        backend = BasicAer.get_backend('statevector_simulator')
+        quantum_instance = QuantumInstance(backend)
+        qaoa_mes = QAOA(quantum_instance=quantum_instance,
+                        initial_point=[0., 0.])
+        qaoa = MinimumEigenOptimizer(qaoa_mes)
+        return qaoa.solve(qubo)
diff --git a/requirements.txt b/requirements.txt
@@ -2,4 +2,6 @@ cython
 git+https://github.com/pyRiemann/pyRiemann#egg=pyriemann
 qiskit_machine_learning==0.4.0
 qiskit-ibmq-provider==0.19.1
-cvxpy==1.1.12
+qiskit-optimization==0.4.0
+cvxpy==1.1.12
+docplex>=2.21.207