Feat/logeuclid mean and logeuclid distance to convex hull

benchmarks/light_benchmark.py

@@ -82,11 +82,11 @@
 )
 
 pipelines["QMDM_mean"] = QuantumMDMWithRiemannianPipeline(
-    convex_metric="mean", quantum=True
+    cpm_metric="mean", quantum=True
 )
 
 pipelines["QMDM_dist"] = QuantumMDMWithRiemannianPipeline(
-    convex_metric="distance", quantum=True
+    cpm_metric="distance", quantum=True
 )
 
 pipelines["RG_LDA"] = make_pipeline(

doc/api.rst

@@ -96,7 +96,8 @@ Mean
 .. autosummary::
     :toctree: generated/
 
-    fro_mean_convex
+    fro_mean_cpm
+    le_mean_cpm
 
 Distance
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -106,7 +107,7 @@ Distance
 .. autosummary::
     :toctree: generated/
 
-    logeucl_dist_convex
+    logeucl_dist_cpm
 
 Docplex
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/requirements.txt

@@ -10,6 +10,7 @@ imbalanced-learn==0.11.0
 joblib
 pandas
 cvxpy==1.4.1
+qiskit==0.45.0
 qiskit_machine_learning==0.6.1
 qiskit-ibm-provider==0.7.3
 qiskit-optimization==0.5.0

examples/ERP/classify_P300_bi_quantum_mdm.py

@@ -6,8 +6,8 @@
 The mean and the distance in MDM algorithm are formulated as
 optimization problems. These optimization problems are translated
 to Qiskit using Docplex and additional glue code. These optimizations
-are enabled when we use convex mean or convex distance. This is set
-using the 'convex_metric' parameter of the QuantumMDMWithRiemannianPipeline.
+are enabled when we use cpm mean or cpm distance. This is set
+using the 'cpm_metric' parameter of the QuantumMDMWithRiemannianPipeline.
 
 Classification can be run either on emulation or real quantum computer.
 
@@ -43,7 +43,7 @@
 from moabb.evaluations import WithinSessionEvaluation
 from moabb.paradigms import P300
 
-# inject convex distance and mean to pyriemann (if not done already)
+# inject cpm distance and mean to pyriemann (if not done already)
 from pyriemann_qiskit.utils import distance, mean  # noqa
 from pyriemann_qiskit.pipelines import (
     QuantumMDMVotingClassifier,
@@ -107,15 +107,15 @@
 
 pipelines = {}
 
-pipelines["mean=convex/distance=euclid"] = QuantumMDMWithRiemannianPipeline(
-    convex_metric="mean", quantum=quantum
+pipelines["mean=cpm/distance=euclid"] = QuantumMDMWithRiemannianPipeline(
+    cpm_metric="mean", quantum=quantum
 )
 
-pipelines["mean=logeuclid/distance=convex"] = QuantumMDMWithRiemannianPipeline(
-    convex_metric="distance", quantum=quantum
+pipelines["mean=logeuclid/distance=cpm"] = QuantumMDMWithRiemannianPipeline(
+    cpm_metric="distance", quantum=quantum
 )
 
-pipelines["Voting convex"] = QuantumMDMVotingClassifier(quantum=quantum)
+pipelines["Voting cpm"] = QuantumMDMVotingClassifier(quantum=quantum)
 
 ##############################################################################
 # Run evaluation

examples/MI/classify_alexmi_with_quantum_pipeline.py

@@ -20,7 +20,7 @@
 from moabb.evaluations import WithinSessionEvaluation
 from moabb.paradigms import MotorImagery
 
-# inject convex distance and mean to pyriemann (if not done already)
+# inject cpm distance and mean to pyriemann (if not done already)
 from pyriemann_qiskit.utils import distance, mean  # noqa
 from pyriemann_qiskit.pipelines import (
     QuantumMDMWithRiemannianPipeline,
@@ -68,8 +68,8 @@
 pipelines = {}
 
 # Will run QAOA under the hood
-pipelines["mean=logeuclid/distance=convex"] = QuantumMDMWithRiemannianPipeline(
-    convex_metric="distance", quantum=True
+pipelines["mean=logeuclid/distance=cpm"] = QuantumMDMWithRiemannianPipeline(
+    cpm_metric="distance", quantum=True
 )
 
 # Classical baseline for evaluation

pyriemann_qiskit/classification.py

@@ -582,7 +582,7 @@ class QuanticMDM(QuanticClassifierBase):
 
     """Quantum-enhanced MDM classifier
 
-    This class is a convex implementation of the Minimum Distance to Mean (MDM)
+    This class is a cpm implementation of the Minimum Distance to Mean (MDM)
     [1]_, which can run with quantum optimization.
     Only log-Euclidean distance between trial and class prototypes is supported
     at the moment, but any type of metric can be used for centroid estimation.
@@ -597,7 +597,7 @@ class QuanticMDM(QuanticClassifierBase):
 
     Parameters
     ----------
-    metric : string | dict, default={"mean": 'logeuclid', "distance": 'convex'}
+    metric : string | dict, default={"mean": 'logeuclid', "distance": 'cpm'}
         The type of metric used for centroid and distance estimation.
         see `mean_covariance` for the list of supported metric.
         the metric could be a dict with two keys, `mean` and `distance` in
@@ -606,7 +606,7 @@ class QuanticMDM(QuanticClassifierBase):
         the mean in order to boost the computional speed and 'riemann' for the
         distance in order to keep the good sensitivity for the classification.
     quantum : bool (default: True)
-        Only applies if `metric` contains a convex distance or mean.
+        Only applies if `metric` contains a cpm distance or mean.
 
         - If true will run on local or remote backend
           (depending on q_account_token value),
@@ -646,7 +646,7 @@ class QuanticMDM(QuanticClassifierBase):
 
     def __init__(
         self,
-        metric={"mean": "logeuclid", "distance": "convex"},
+        metric={"mean": "logeuclid", "distance": "cpm_le"},
         quantum=True,
         q_account_token=None,
         verbose=True,
@@ -661,7 +661,7 @@ def __init__(
         self.upper_bound = upper_bound
 
     def _init_algo(self, n_features):
-        self._log("Convex MDM initiating algorithm")
+        self._log("cpm MDM initiating algorithm")
         classifier = MDM(metric=self.metric)
         if self.quantum:
             self._log("Using NaiveQAOAOptimizer")

pyriemann_qiskit/pipelines.py

@@ -304,19 +304,19 @@ def _create_pipe(self):
 
 class QuantumMDMWithRiemannianPipeline(BasePipeline):
 
-    """MDM with Riemannian pipeline adapted for convex metrics.
+    """MDM with Riemannian pipeline adapted for cpm metrics.
 
     It can run on classical or quantum optimizer.
 
     Parameters
     ----------
-    convex_metric : string (default: "distance")
+    cpm_metric : string (default: "distance")
         `metric` passed to the inner QuanticMDM depends on the
-        `convex_metric` as follows (convex_metric => metric):
+        `cpm_metric` as follows (cpm_metric => metric):
 
-        - "distance" => {mean=logeuclid, distance=convex},
-        - "mean" => {mean=convex, distance=euclid},
-        - "both" => {mean=convex, distance=convex},
+        - "distance" => {mean=logeuclid, distance=cpm},
+        - "mean" => {mean=cpm, distance=euclid},
+        - "both" => {mean=cpm, distance=cpm},
         - other => same as "distance".
     quantum : bool (default: True)
         - If true will run on local or remote backend
@@ -351,14 +351,14 @@ class QuantumMDMWithRiemannianPipeline(BasePipeline):
 
     def __init__(
         self,
-        convex_metric="distance",
+        cpm_metric="distance",
         quantum=True,
         q_account_token=None,
         verbose=True,
         shots=1024,
         upper_bound=7,
     ):
-        self.convex_metric = convex_metric
+        self.cpm_metric = cpm_metric
         self.quantum = quantum
         self.q_account_token = q_account_token
         self.verbose = verbose
@@ -368,14 +368,14 @@ def __init__(
         BasePipeline.__init__(self, "QuantumMDMWithRiemannianPipeline")
 
     def _create_pipe(self):
-        if self.convex_metric == "both":
-            metric = {"mean": "convex", "distance": "convex"}
-        elif self.convex_metric == "mean":
-            metric = {"mean": "convex", "distance": "euclid"}
+        if self.cpm_metric == "both":
+            metric = {"mean": "cpm_le", "distance": "cpm_le"}
+        elif self.cpm_metric == "mean":
+            metric = {"mean": "cpm_le", "distance": "logeuclid"}
         else:
-            metric = {"mean": "logeuclid", "distance": "convex"}
+            metric = {"mean": "logeuclid", "distance": "cpm_le"}
 
-        if metric["mean"] == "convex":
+        if metric["mean"] == "cpm_le":
             if self.quantum:
                 covariances = XdawnCovariances(
                     nfilter=1, estimator="scm", xdawn_estimator="lwf"
@@ -407,8 +407,8 @@ class QuantumMDMVotingClassifier(BasePipeline):
     Voting classifier with two configurations of
     QuantumMDMWithRiemannianPipeline:
 
-    - with mean = convex and distance = euclid,
-    - with mean = logeuclid and distance = convex.
+    - with mean = cpm and distance = euclid,
+    - with mean = logeuclid and distance = cpm.
 
     Parameters
     ----------
@@ -460,15 +460,15 @@ def __init__(
         BasePipeline.__init__(self, "QuantumMDMVotingClassifier")
 
     def _create_pipe(self):
-        clf_mean_logeuclid_dist_convex = QuantumMDMWithRiemannianPipeline(
+        clf_mean_logeuclid_dist_cpm = QuantumMDMWithRiemannianPipeline(
             "distance",
             self.quantum,
             self.q_account_token,
             self.verbose,
             self.shots,
             self.upper_bound,
         )
-        clf_mean_convex_dist_euclid = QuantumMDMWithRiemannianPipeline(
+        clf_mean_cpm_dist_euclid = QuantumMDMWithRiemannianPipeline(
             "mean",
             self.quantum,
             self.q_account_token,
@@ -480,8 +480,8 @@ def _create_pipe(self):
         return make_pipeline(
             VotingClassifier(
                 [
-                    ("mean_logeuclid_dist_convex", clf_mean_logeuclid_dist_convex),
-                    ("mean_convex_dist_euclid ", clf_mean_convex_dist_euclid),
+                    ("mean_logeuclid_dist_cpm", clf_mean_logeuclid_dist_cpm),
+                    ("mean_cpm_dist_euclid ", clf_mean_cpm_dist_euclid),
                 ],
                 voting="soft",
             )

pyriemann_qiskit/utils/__init__.py

@@ -18,7 +18,7 @@
     add_moabb_dataframe_results_to_caches,
     convert_caches_to_dataframes,
 )
-from .distance import logeucl_dist_convex
+from .distance import logeucl_dist_cpm
 
 __all__ = [
     "hyper_params_factory",
@@ -36,7 +36,7 @@
     "NaiveQAOAOptimizer",
     "set_global_optimizer",
     "get_global_optimizer",
-    "logeucl_dist_convex",
+    "logeucl_dist_cpm",
     "FirebaseConnector",
     "Cache",
     "generate_caches",

pyriemann_qiskit/utils/distance.py

@@ -6,8 +6,8 @@
 from pyriemann.utils.base import logm
 
 
-def logeucl_dist_convex(X, y, optimizer=ClassicalOptimizer()):
-    """Convex formulation of the MDM algorithm with log-Euclidean metric.
+def logeucl_dist_cpm(X, y, optimizer=ClassicalOptimizer()):
+    """Constraint Programming Model (CPM) formulation of the MDM algorithm with log-Euclidean metric.
 
     Parameters
     ----------
@@ -67,9 +67,9 @@ def log_prod(m1, m2):
 
 
 def predict_distances(mdm, X):
-    if mdm.metric_dist == "convex":
+    if mdm.metric_dist == "cpm_le":
         centroids = np.array(mdm.covmeans_)
-        return np.array([logeucl_dist_convex(centroids, x) for x in X])
+        return np.array([logeucl_dist_cpm(centroids, x) for x in X])
     else:
         return _mdm_predict_distances_original(mdm, X)
 
@@ -78,7 +78,7 @@ def predict_distances(mdm, X):
 
 # This is only for validation inside the MDM.
 # In fact, we override the _predict_distances method
-# inside MDM to directly use logeucl_dist_convex when the metric is "convex"
+# inside MDM to directly use logeucl_dist_cpm when the metric is "cpm_le"
 # This is due to the fact the the signature of this method is different from
 # the usual distance functions.
-distance_functions["convex"] = logeucl_dist_convex
+distance_functions["cpm_le"] = logeucl_dist_cpm

pyriemann_qiskit/utils/mean.py

@@ -2,12 +2,14 @@
 from pyriemann.utils.mean import mean_functions
 from pyriemann_qiskit.utils.docplex import ClassicalOptimizer, get_global_optimizer
 from pyriemann.estimation import Shrinkage
+from pyriemann.utils.base import logm, expm
+import numpy as np
 
 
-def fro_mean_convex(
+def fro_mean_cpm(
     covmats, sample_weight=None, optimizer=ClassicalOptimizer(), shrink=True
 ):
-    """Convex formulation of the mean with Frobenius distance.
+    """Constraint Programm Model (CPM) formulation of the mean with Frobenius distance.
 
     Parameters
     ----------
@@ -25,7 +27,7 @@ def fro_mean_convex(
     Returns
     -------
     mean : ndarray, shape (n_channels, n_channels)
-        Convex-optimized Frobenius mean.
+        CPM-optimized Frobenius mean.
 
     Notes
     -----
@@ -66,4 +68,39 @@ def _fro_dist(A, B):
     return result
 
 
-mean_functions["convex"] = fro_mean_convex
+def le_mean_cpm(
+    covmats, sample_weight=None, optimizer=ClassicalOptimizer(), shrink=True
+):
+    """Constraint Programm Model (CPM) formulation of the mean with log-euclidian distance.
+
+    Parameters
+    ----------
+    covmats: ndarray, shape (n_matrices, n_channels, n_channels)
+        Set of SPD matrices.
+    sample_weights:  None | ndarray, shape (n_matrices,), default=None
+        Weights for each matrix. Never used in practice.
+        It is kept only for standardization with pyRiemann.
+    optimizer: pyQiskitOptimizer
+        An instance of pyQiskitOptimizer.
+    shrink: boolean (default: true)
+        If True, it applies shrinkage regularization [2]_
+        of the resulting covariance matrix.
+
+    Returns
+    -------
+    mean : ndarray, shape (n_channels, n_channels)
+        CPM-optimized Frobenius mean.
+
+    Notes
+    -----
+    .. versionadded:: 0.2.0
+
+    """
+
+    log_covmats = logm(covmats)
+    result = fro_mean_cpm(log_covmats, sample_weight, optimizer, shrink)
+    return expm(result)
+
+
+mean_functions["cpm_fro"] = fro_mean_cpm
+mean_functions["cpm_le"] = le_mean_cpm

requirements.txt

@@ -2,6 +2,7 @@ numpy<1.27
 cython
 scikit-learn==1.3.2
 git+https://github.com/pyRiemann/pyRiemann#egg=pyriemann
+qiskit==0.45.0
 qiskit_machine_learning==0.6.1
 qiskit-ibm-provider==0.7.3
 qiskit-optimization==0.5.0