Docplex utils methods to generate square matrix variables (#56)

* add docplex utils with covmat genration methods

* complete documentation

* update tests

* flake8

* fix requirements for documentation

Co-authored-by: gcattan <gregoire.cattan@ibm.com>

doc/api.rst

@@ -47,6 +47,18 @@ Filtering
     NoDimRed
     NaiveDimRed
 
+Docplex
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _docplex_api:
+.. currentmodule:: pyriemann_qiskit.utils.docplex
+
+.. autosummary::
+    :toctree: generated/
+
+    square_cont_mat_var
+    square_int_mat_var
+    square_bin_mat_var
+
 Datasets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. _datasets_api:

doc/requirements.txt

@@ -13,3 +13,4 @@ qiskit-ibmq-provider==0.19.1
 scipy==1.7.3
 moabb>=0.4.6
 git+https://github.com/pyRiemann/pyRiemann#egg=pyriemann
+docplex

pyriemann_qiskit/utils/__init__.py

@@ -1,6 +1,12 @@
 from . import hyper_params_factory, filtering
+from .docplex import (square_cont_mat_var,
+                      square_int_mat_var,
+                      square_bin_mat_var)
 
 __all__ = [
     'hyper_params_factory',
-    'filtering'
+    'filtering',
+    'square_cont_mat_var',
+    'square_int_mat_var',
+    'square_bin_mat_var'
 ]

pyriemann_qiskit/utils/docplex.py

@@ -0,0 +1,100 @@
+from docplex.mp.vartype import ContinuousVarType, IntegerVarType, BinaryVarType
+
+
+def square_cont_mat_var(prob, channels,
+                        name='cont_covmat'):
+    """Creates a 2-dimensional dictionary of continuous decision variables,
+    indexed by pairs of key objects.
+    The dictionary represents a square matrix of size
+    len(channels) x len(channels).
+    A key can be any Python object, with the exception of None.
+
+    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.
+
+    Returns
+    -------
+    square_mat : dict
+        A square matrix of continuous decision variables.
+        Access element (i, j) with square_mat[(i, j)].
+        Indices start with 0.
+
+    References
+    ----------
+    .. [1] \
+        http://ibmdecisionoptimization.github.io/docplex-doc/mp/_modules/docplex/mp/model.html#Model
+    """
+    ContinuousVarType.one_letter_symbol = lambda _: 'C'
+    return prob.continuous_var_matrix(keys1=channels, keys2=channels,
+                                      name=name, lb=-prob.infinity)
+
+
+def square_int_mat_var(prob, channels,
+                       name='int_covmat'):
+    """Creates a 2-dimensional dictionary of integer decision variables,
+    indexed by pairs of key objects.
+    The dictionary represents a square matrix of size
+    len(channels) x len(channels).
+    A key can be any Python object, with the exception of None.
+
+    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.
+
+    Returns
+    -------
+    square_mat : dict
+        A square matrix of integer decision variables.
+        Access element (i, j) with square_mat[(i, j)].
+        Indices start with 0.
+
+    References
+    ----------
+    .. [1] \
+        http://ibmdecisionoptimization.github.io/docplex-doc/mp/_modules/docplex/mp/model.html#Model
+    """
+    IntegerVarType.one_letter_symbol = lambda _: 'I'
+    return prob.integer_var_matrix(keys1=channels, keys2=channels,
+                                   name=name, lb=-prob.infinity)
+
+
+def square_bin_mat_var(prob, channels,
+                       name='bin_covmat'):
+    """Creates a 2-dimensional dictionary of binary decision variables,
+    indexed by pairs of key objects.
+    The dictionary represents a square matrix of size
+    len(channels) x len(channels).
+    A key can be any Python object, with the exception of None.
+
+    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.
+
+    Returns
+    -------
+    square_mat : dict
+        A square matrix of binary decision variables.
+        Access element (i, j) with square_mat[(i, j)].
+        Indices start with 0.
+
+    References
+    ----------
+    .. [1] \
+        http://ibmdecisionoptimization.github.io/docplex-doc/mp/_modules/docplex/mp/model.html#Model
+    """
+    BinaryVarType.one_letter_symbol = lambda _: 'B'
+    return prob.binary_var_matrix(keys1=channels, keys2=channels,
+                                  name=name)

tests/test_docplex.py

@@ -1,11 +1,22 @@
-from docplex.mp.vartype import ContinuousVarType
+import pytest
 from docplex.mp.model import Model
+from docplex.mp.vartype import ContinuousVarType, IntegerVarType, BinaryVarType
+from pyriemann_qiskit.utils import (square_cont_mat_var,
+                                    square_int_mat_var,
+                                    square_bin_mat_var)
 
 
-def test_get_square_cont_var():
-    channels = range(4)
+@pytest.mark.parametrize('square_mat_var',
+                         [(square_cont_mat_var, ContinuousVarType),
+                          (square_int_mat_var, IntegerVarType),
+                          (square_bin_mat_var, BinaryVarType)])
+def test_get_square_cont_var(square_mat_var):
+    n = 4
+    channels = range(n)
     prob = Model()
-    ContinuousVarType.one_letter_symbol = lambda _: 'C'
-    mat = prob.continuous_var_matrix(keys1=channels, keys2=channels,
-                                     name='test', lb=-prob.infinity)
-    assert mat is not None
+    handle = square_mat_var[0]
+    expected_result_type = square_mat_var[1]
+    mat = handle(prob, channels, name='test')
+    first_element = mat[(0, 0)]
+    assert len(mat) == n * n
+    assert type(first_element.vartype) is expected_result_type