Merge pull request #138 from PerformanceEstimation/features/visualization_2nd_version

AdrienTaylor · web-flow · commit ce47e797e818 · 2026-03-11T00:31:47.000+01:00
Features/visualization 2nd version
diff --git a/PEPit/__init__.py b/PEPit/__init__.py
@@ -2,6 +2,7 @@
 from .constraint import Constraint
 from .expression import Expression, null_expression
 from .function import Function
+from .interpolator import Interpolator
 from .psd_matrix import PSDMatrix
 from .wrapper import Wrapper
 from .pep import PEP
@@ -10,13 +11,15 @@
 __all__ = ['block_partition', 'BlockPartition',
            'examples',
            'functions',
+           'interpolators',
            'operators',
            'primitive_steps',
            'tools',
            'wrappers',
            'constraint', 'Constraint',
            'expression', 'Expression', 'null_expression',
            'function', 'Function',
+           'interpolator', 'Interpolator',
            'psd_matrix', 'PSDMatrix',
            'pep', 'PEP',
            'point', 'Point', 'null_point',
diff --git a/PEPit/examples/online_learning/online_follow_leader.py b/PEPit/examples/online_learning/online_follow_leader.py
@@ -9,7 +9,7 @@ def wc_online_follow_leader(M, D, n, wrapper="cvxpy", solver=None, verbose=1):
     """
     Consider the online convex minimization problem, whose goal is to sequentially minimize the regret
 
-    .. math:: R_n \\triangleq \\min_{x\\in Q} \sum_{i=1}^n f_i(x_i)-f_i(x),
+    .. math:: R_n \\triangleq \\max_{x\\in Q} \sum_{i=1}^n f_i(x_i)-f_i(x),
 
     where the functions :math:`f_i` are :math:`M`-Lipschitz and convex, and where :math:`Q` is a
     bounded closed convex set with diameter upper bounded by :math:`D`. We also denote by :math:`x_\\star\\in Q`
diff --git a/PEPit/examples/online_learning/online_follow_regularized_leader.py b/PEPit/examples/online_learning/online_follow_regularized_leader.py
@@ -9,7 +9,7 @@ def wc_online_follow_regularized_leader(M, D, n, wrapper="cvxpy", solver=None, v
     """
     Consider the online convex minimization problem, whose goal is to sequentially minimize the regret
 
-    .. math:: R_n \\triangleq \\min_{x\\in Q} \sum_{i=1}^n f_i(x_i)-f_i(x),
+    .. math:: R_n \\triangleq \\max_{x\\in Q} \sum_{i=1}^n f_i(x_i)-f_i(x),
 
     where the functions :math:`f_i` are :math:`M`-Lipschitz and convex, and where :math:`Q` is a
     bounded closed convex set with diameter upper bounded by :math:`D`. We also denote by :math:`x_\\star\\in Q`
diff --git a/PEPit/examples/online_learning/online_frank_wolfe.py b/PEPit/examples/online_learning/online_frank_wolfe.py
@@ -10,7 +10,7 @@ def wc_online_frank_wolfe(M, D, n, wrapper="cvxpy", solver=None, verbose=1):
     """
     Consider the online convex minimization problem, whose goal is to sequentially minimize the regret
 
-    .. math:: R_n \\triangleq \\min_{x\\in Q} \sum_{i=1}^n f_i(x_i)-f_i(x),
+    .. math:: R_n \\triangleq \\max_{x\\in Q} \sum_{i=1}^n f_i(x_i)-f_i(x),
 
     where the functions :math:`f_i` are :math:`M`-Lipschitz and convex, and where :math:`Q` is a
     bounded closed convex set with diameter upper bounded by :math:`D`. We also denote by :math:`x_\\star\\in Q`
diff --git a/PEPit/examples/online_learning/online_gradient_descent.py b/PEPit/examples/online_learning/online_gradient_descent.py
@@ -9,7 +9,7 @@ def wc_online_gradient_descent(M, D, n, wrapper="cvxpy", solver=None, verbose=1)
     """
     Consider the online convex minimization problem, whose goal is to sequentially minimize the regret
 
-    .. math:: R_n \\triangleq \\min_{x\\in Q} \sum_{i=1}^n f_i(x_i)-f_i(x),
+    .. math:: R_n \\triangleq \\max_{x\\in Q} \sum_{i=1}^n f_i(x_i)-f_i(x),
 
     where the functions :math:`f_i` are :math:`M`-Lipschitz and convex, and where :math:`Q` is a
     bounded closed convex set with diameter upper bounded by :math:`D`. We also denote by :math:`x_\\star\\in Q`
diff --git a/PEPit/function.py b/PEPit/function.py
@@ -157,6 +157,18 @@ def get_is_leaf(self):
         """
         return self._is_leaf
 
+    def get_interpolator(self):
+        """
+        Warnings:
+            Needs to be overwritten with an appropriate interpolator for the class.
+
+        Raises:
+            NotImplementedError: This method must be overwritten in children classes
+
+        """
+
+        raise NotImplementedError("This method must be overwritten in children classes")
+
     def __add__(self, other):
         """
         Add 2 :class:`Function` objects together, leading to a new :class:`Function` object.
diff --git a/PEPit/functions/convex_function.py b/PEPit/functions/convex_function.py
@@ -1,4 +1,6 @@
+import numpy as np
 from PEPit.function import Function
+from PEPit.interpolators import SmoothStronglyConvexInterpolator
 
 
 class ConvexFunction(Function):
@@ -41,6 +43,13 @@ def __init__(self,
                          name=name,
                          )
 
+    def get_interpolator(self, options='lowest'):
+        """
+        Returns: SmoothStronglyConvexInterpolator (with L=np.inf and mu=0) based on self.
+
+        """
+        return SmoothStronglyConvexInterpolator(self, L=np.inf, mu=0, options=options)
+
     @staticmethod
     def set_convexity_constraint_i_j(xi, gi, fi,
                                      xj, gj, fj,
diff --git a/PEPit/functions/smooth_convex_function.py b/PEPit/functions/smooth_convex_function.py
@@ -1,5 +1,6 @@
 import numpy as np
 from PEPit.function import Function
+from PEPit.interpolators import SmoothStronglyConvexInterpolator
 
 
 class SmoothConvexFunction(Function):
@@ -65,6 +66,13 @@ def __init__(self,
                   "L == np.inf. Instead, please use the class ConvexFunction (which accounts for the fact \n"
                   "that there might be several subgradients at the same point).\033[0m")
 
+    def get_interpolator(self, options='lowest'):
+        """
+        Returns: SmoothStronglyConvexInterpolator (with mu=0) based on self.
+
+        """
+        return SmoothStronglyConvexInterpolator(self, L=self.L, mu=0, options=options)
+
     def set_smoothness_convexity_constraint_i_j(self,
                                                 xi, gi, fi,
                                                 xj, gj, fj,
diff --git a/PEPit/functions/smooth_function.py b/PEPit/functions/smooth_function.py
@@ -1,5 +1,6 @@
 import numpy as np
 from PEPit.function import Function
+from PEPit.interpolators import SmoothStronglyConvexInterpolator
 
 
 class SmoothFunction(Function):
@@ -63,6 +64,13 @@ def __init__(self,
             print("\033[96m(PEPit) The class of L-smooth functions with L == np.inf implies no constraint: \n"
                   "it contains all differentiable functions. This might imply issues in your code.\033[0m")
 
+    def get_interpolator(self, options='lowest'):
+        """
+        Returns: SmoothStronglyConvexInterpolator (with mu=-L) based on self.
+
+        """
+        return SmoothStronglyConvexInterpolator(self, L=self.L, mu=-self.L, options=options)
+
     def set_smoothness_i_j(self,
                            xi, gi, fi,
                            xj, gj, fj,
diff --git a/PEPit/functions/smooth_strongly_convex_function.py b/PEPit/functions/smooth_strongly_convex_function.py
@@ -1,5 +1,6 @@
 import numpy as np
 from PEPit.function import Function
+from PEPit.interpolators import SmoothStronglyConvexInterpolator
 
 
 class SmoothStronglyConvexFunction(Function):
@@ -70,6 +71,13 @@ def __init__(self,
                   "L == np.inf. Instead, please use the class StronglyConvexFunction (which accounts for the fact\n"
                   "that there might be several sub-gradients at the same point).\033[0m")
 
+    def get_interpolator(self, options='lowest'):
+        """
+        Returns: SmoothStronglyConvexInterpolator based on self.
+
+        """
+        return SmoothStronglyConvexInterpolator(self, L=self.L, mu=self.mu, options=options)
+
     def set_smoothness_strong_convexity_constraint_i_j(self,
                                                        xi, gi, fi,
                                                        xj, gj, fj,
diff --git a/PEPit/functions/strongly_convex_function.py b/PEPit/functions/strongly_convex_function.py
@@ -1,4 +1,6 @@
+import numpy as np
 from PEPit.function import Function
+from PEPit.interpolators import SmoothStronglyConvexInterpolator
 
 
 class StronglyConvexFunction(Function):
@@ -57,6 +59,13 @@ def __init__(self,
         # Store mu
         self.mu = mu
 
+    def get_interpolator(self, options='lowest'):
+        """
+        Returns: SmoothStronglyConvexInterpolator (with L=np.inf) based on self.
+
+        """
+        return SmoothStronglyConvexInterpolator(self, L=np.inf, mu=self.mu, options=options)
+
     def set_strong_convexity_constraint_i_j(self,
                                             xi, gi, fi,
                                             xj, gj, fj,
diff --git a/PEPit/interpolator.py b/PEPit/interpolator.py
@@ -0,0 +1,66 @@
+import importlib.util
+import cvxpy as cp
+
+from PEPit.point import Point
+
+
+class Interpolator(object):
+    """
+    A :class:`Interpolator` object encodes an interpolating procedure for a function class or an operator.
+
+    Warnings:
+        This class must be overwritten by a child class that encodes one (or more) specific interpolation procedure(s).
+        In particular, the method `evaluate` must be overwritten.
+        See the :class:`PEPit.interpolators` modules.
+        
+    Attributes:
+        func (Function): A :class:`Function` object that contains the samples to be interpolated.
+        d (int): Size of the SDP that it corresponds to (dimension of the space where the interpolation takes place).
+
+    """
+    def __init__(self, func):
+        self.func = func
+        self.d = Point.counter
+        self._solver_choice()
+
+    def evaluate(self, x):
+        """
+        Warnings:
+            Needs to be overwritten with an appropriate evaluation/interpolations procedure for the class.
+
+        Raises:
+            NotImplementedError: This method must be overwritten in children classes
+
+        """
+
+        raise NotImplementedError("This method must be overwritten in children classes")
+        	
+    def __call__(self, x):
+        return self.evaluate(x)
+        
+    def _solver_choice(self):
+        # If MOSEK is installed, CVXPY will run it.
+        # We need to check the presence of a license and handle it in case there is no valid license.
+        is_mosek_installed = importlib.util.find_spec("mosek")
+        self.solver = cp.MOSEK
+        if is_mosek_installed:
+            # Import mosek.
+            import mosek
+            
+            # Create an environment.
+            mosek_env = mosek.Env()
+            
+            # Grab the license if there is one.
+            try:
+                mosek_env.checkoutlicense(mosek.feature.pton)
+            except mosek.Error:
+                pass
+                
+            # Check validity of a potentially found license.
+            if not mosek_env.expirylicenses() >= 0:
+                # In case the license is not valid, ask CVXPY to run SCS.
+                self.solver = cp.SCS
+
+        else:
+            # If mosek is not installed, ask CVXPY to run SCS.
+            self.solver = cp.SCS
diff --git a/PEPit/interpolators/__init__.py b/PEPit/interpolators/__init__.py
@@ -0,0 +1,4 @@
+from .smooth_strongly_convex_interpolator import SmoothStronglyConvexInterpolator
+
+__all__ = ['smooth_strongly_convex_interpolator', 'SmoothStronglyConvexInterpolator',
+           ]
diff --git a/PEPit/interpolators/smooth_strongly_convex_interpolator.py b/PEPit/interpolators/smooth_strongly_convex_interpolator.py
@@ -0,0 +1,93 @@
+import numpy as np
+import cvxpy as cp
+
+from PEPit.interpolator import Interpolator
+
+
+class SmoothStronglyConvexInterpolator(Interpolator):
+    """
+    The class :class:`Interpolator` is designed to help identifying worst-case examples.
+    
+    This class implements the construction [1, Theorem 3.14] that allows to interpolate smooth strongly convex functions.
+    That is, given a set of triplets :math:`(x_i,g_i,f_i)` for which there exists such an interpolating function
+    (see [2, Theorem 4]).
+    
+    Interpolators are interfaced to PEPit via the :class:`Function`. More precisely, functions associated to
+    interpolation conditions and constructive interpolating constructions are featured with the `get_interpolator()`
+    method, that allows to receive an interpolator associated with the triplets of the corresponding solved PEP.
+    
+    A complete demo is available
+    `here <https://github.com/PerformanceEstimation/PEPit/blob/master/ressources/demo/PEPit_demo_extract_worst_case_examples.ipynb>`_.
+
+
+    Attributes:
+        func (Function): PEPit function that contains the list of triplets.
+        L (float): smoothness parameter for the interpolant.
+        mu (float): strong convexity parameter for the interpolant.
+        options (str): Either "lowest" or "highest"; determines whether to use the minimum or maximum possible interpolant.
+
+    References:
+
+    `[1] A. Taylor (2017).
+    Convex interpolation and performance estimation of first-order methods for convex optimization.
+    PhD thesis, UCLouvain.
+    <https://dial.uclouvain.be/pr/boreal/object/boreal%3A182881/>`_
+
+    `[2] A. Taylor, J. Hendrickx, F. Glineur (2017).
+    Smooth strongly convex interpolation and exact worst-case performance of first-order methods.
+    Mathematical Programming, 161(1-2), 307-345.
+    <https://arxiv.org/pdf/1502.05666.pdf>`_
+        
+    """
+    def __init__(self, func, L=np.inf, mu=0, options='lowest'):
+        
+        super().__init__(func=func)
+        self.L = L
+        self.mu = mu
+        self.options = options
+
+    def __set_constraint__(self,
+                           xi, gi, fi,
+                           xj, gj, fj,
+                           ):
+        """
+        Implements the constraints necessary for the construction [1, Theorem 3.14] in the evaluate() method.
+
+        """
+        if self.L is not np.inf:
+            constraint = (0 >= fj - fi + gj @ (xi - xj)
+                          + 1 / 2 / (self.L-self.mu) * cp.norm(gi - gj, 2) ** 2
+                          + self.mu * self.L / 2 / (self.L-self.mu) * cp.norm(xi - xj, 2) ** 2
+                          - self.mu / (self.L - self.mu) * (gi-gj)@(xi-xj))
+        else:
+            constraint = (0 >= fj - fi + gj @ (xi - xj)
+                          + self.mu / 2 * cp.norm(xi - xj, 2) ** 2)
+        
+        return constraint
+                
+    def evaluate(self, x):
+        """
+        Computes the specific (lowest/highest) smooth strongly convex interpolant.
+        The interpolation is formulated and solved as an optimization problem [1, Theorem 3.14].
+        
+        """
+        k = x.shape[0]
+        if k > self.d:
+            raise ValueError("Error: specified input to evaluate has dimension larger than target dimension")
+        x_padded = np.pad(x, (0, self.d - k))
+        
+        fx = cp.Variable(1)
+        gx = cp.Variable((self.d,))
+        cons = []
+        for i, point_i in enumerate(self.func.list_of_points):
+            xi, gi, fi = point_i
+            cons.append(self.__set_constraint__(xi.eval(), gi.eval(), fi.eval(), x_padded, gx, fx))
+            cons.append(self.__set_constraint__(x_padded, gx, fx, xi.eval(), gi.eval(), fi.eval()))
+        
+        if self.options == 'highest':
+            prob = cp.Problem(cp.Maximize(fx), cons)
+        if self.options == 'lowest':
+            prob = cp.Problem(cp.Minimize(fx), cons)
+        prob.solve(verbose=False, solver=self.solver)
+
+        return fx.value.squeeze()
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -7,6 +7,7 @@ API and modules
 
    api/main_modules
    api/functions_and_operators
+   api/interpolators
    api/steps
    api/tools
    api/wrappers
diff --git a/docs/source/api/interpolators.rst b/docs/source/api/interpolators.rst
@@ -0,0 +1,12 @@
+Interpolators
+=============
+
+.. contents::
+   :depth: 1
+   :local:
+
+SmoothStronglyConvexInterpolator
+--------------------------------
+.. autoclass:: PEPit.interpolators.SmoothStronglyConvexInterpolator
+   :members:
+   :show-inheritance:
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
@@ -22,6 +22,9 @@ For people who are more comfortable with Matlab, we report to
 `PESTO
 <https://github.com/AdrienTaylor/Performance-Estimation-Toolbox>`_.
 
+Since early 2026, a Julia version of PEPit is also available at
+`PEPit.jl<https://github.com/PerformanceEstimation/PEPit.jl>`_.
+
 How tu use PEPit?
 ------------------
 
diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst
@@ -7,3 +7,4 @@ Tutorials
 
    Finding worst-case guarantees <notebooks_folder/PEPit_demo.ipynb>
    Extracting a proof <notebooks_folder/PEPit_demo_extracting_a_proof.ipynb>
+   Extracting a worst-case example <notebooks_folder/PEPit_demo_extract_worst_case_examples.ipynb>
diff --git a/docs/source/whatsnew/0.4.1.rst b/docs/source/whatsnew/0.4.1.rst
diff --git a/ressources/demo/PEPit_demo_extract_worst_case_examples.ipynb b/ressources/demo/PEPit_demo_extract_worst_case_examples.ipynb
diff --git a/tests/__init__.py b/tests/__init__.py
diff --git a/tests/test_interpolator.py b/tests/test_interpolator.py
