Merge pull request #44 from PerformanceEstimation/feature/doctest

Feature/doctest

Author: bgoujaud

PEPit/functions/convex_indicator.py

@@ -9,7 +9,7 @@ class ConvexIndicatorFunction(Function):
     implementing interpolation constraints for the class of closed convex indicator functions.
 
     Attributes:
-        D (float): upper bound on the diameter of the feasible set
+        D (float): upper bound on the diameter of the feasible set, possibly set to np.inf
 
     Convex indicator functions are characterized by a parameter `D`, hence can be instantiated as
 

PEPit/functions/smooth_convex_function.py

@@ -1,3 +1,4 @@
+import numpy as np
 from PEPit.functions.smooth_strongly_convex_function import SmoothStronglyConvexFunction
 
 
@@ -46,3 +47,9 @@ def __init__(self,
                          reuse_gradient=True,
                          mu=0,
                          L=L)
+
+        if self.L == np.inf:
+            print("\033[96m(PEPit) The class of smooth convex functions is necessarily differentiable.\n"
+                  "To instantiate a convex function, please avoid using the class SmoothConvexFunction with \n"
+                  "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")

PEPit/functions/smooth_function.py

@@ -1,3 +1,4 @@
+import numpy as np
 from PEPit.function import Function
 
 
@@ -53,6 +54,10 @@ def __init__(self,
         # Store L
         self.L = L
 
+        if self.L == np.inf:
+            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 add_class_constraints(self):
         """
         Formulates the list of interpolation constraints for self (smooth (not necessarily convex) function),

PEPit/functions/smooth_strongly_convex_function.py

@@ -1,3 +1,4 @@
+import numpy as np
 from PEPit.function import Function
 
 
@@ -57,6 +58,12 @@ def __init__(self,
         self.mu = mu
         self.L = L
 
+        if self.L == np.inf:
+            print("\033[96m(PEPit) The class of smooth strongly convex functions is necessarily differentiable.\n"
+                  "To instantiate a strongly convex function, please avoid using the class SmoothStronglyConvexFunction\n"
+                  "with L == np.inf. Instead, please use the class StronglyConvexFunction (which accounts for the fact\n"
+                  "that there might be several subgradients at the same point).\033[0m")
+
     def add_class_constraints(self):
         """
         Formulates the list of interpolation constraints for self (smooth strongly convex function); see [1, Theorem 4].

PEPit/operators/cocoercive.py

@@ -1,3 +1,4 @@
+import numpy as np
 from PEPit.function import Function
 
 
@@ -7,7 +8,7 @@ class CocoerciveOperator(Function):
     implementing the interpolation constraints of the class of cocoercive (and maximally monotone) operators.
 
     Note:
-        Operators'values can be requested through `gradient` and `function values` should not be used.
+        Operator values can be requested through `gradient` and `function values` should not be used.
 
     Attributes:
         beta (float): cocoercivity parameter
@@ -56,6 +57,12 @@ def __init__(self,
         # Store the beta parameter
         self.beta = beta
 
+        if self.beta == 0:
+            print("\033[96m(PEPit) The class of cocoercive operators is necessarily continuous. \n"
+                  "To instantiate a monotone opetator, please avoid using the class CocoerciveOperator\n"
+                  "with beta == 0. Instead, please use the class Monotone (which accounts for the fact \n"
+                  "that the image of the operator at certain points might not be a singleton).\033[0m")
+
     def add_class_constraints(self):
         """
         Formulates the list of interpolation constraints for self (cocoercive maximally monotone operator),

PEPit/operators/lipschitz.py

@@ -1,3 +1,4 @@
+import numpy as np
 from PEPit.function import Function
 
 
@@ -7,7 +8,7 @@ class LipschitzOperator(Function):
     implementing the interpolation constraints of the class of Lipschitz continuous operators.
 
     Note:
-        Operators'values can be requested through `gradient` and `function values` should not be used.
+        Operator values can be requested through `gradient` and `function values` should not be used.
 
     Attributes:
         L (float) Lipschitz parameter
@@ -74,6 +75,10 @@ def __init__(self,
         # Store L
         self.L = L
 
+        if self.L == np.inf:
+            print("\033[96m(PEPit) The class of L-Lipschitz operators with L == np.inf implies no constraint: \n"
+                  "it contains all multi-valued mappings. This might imply issues in your code.\033[0m")
+
     def add_class_constraints(self):
         """
         Formulates the list of interpolation constraints for self (Lipschitz operator),

PEPit/operators/lipschitz_strongly_monotone.py

@@ -1,3 +1,4 @@
+import numpy as np
 from PEPit.function import Function
 
 
@@ -8,7 +9,7 @@ class LipschitzStronglyMonotoneOperator(Function):
     for the class of Lipschitz continuous strongly monotone (and maximally monotone) operators.
 
     Note:
-        Operators'values can be requested through `gradient` and `function values` should not be used.
+        Operator values can be requested through `gradient` and `function values` should not be used.
 
     Warning:
         Lipschitz strongly monotone operators do not enjoy known interpolation conditions. The conditions implemented
@@ -67,6 +68,12 @@ def __init__(self,
         self.mu = mu
         self.L = L
 
+        if self.L == np.inf:
+            print("\033[96m(PEPit) The class of Lipschitz strongly monotone operators is necessarily continuous.\n"
+                  "To instantiate an operator, please avoid using the class LipschitzStronglyMonotoneOperator with\n"
+                  " L == np.inf. Instead, please use the class StronglyMonotoneOperator (which accounts for the fact\n"
+                  "that the image of the operator at certain points might not be a singleton).\033[0m")
+
     def add_class_constraints(self):
         """
         Formulates the list of necessary conditions for interpolation of self (Lipschitz strongly monotone and

PEPit/operators/monotone.py

@@ -7,12 +7,13 @@ class MonotoneOperator(Function):
     implementing interpolation constraints for the class of maximally monotone operators.
 
     Note:
-        Operators'values can be requested through `gradient` and `function values` should not be used.
+        Operator values can be requested through `gradient` and `function values` should not be used.
 
     General maximally monotone operators are not characterized by any parameter, hence can be instantiated as
 
     Example:
         >>> from PEPit import PEP
+        >>> from PEPit.operators import MonotoneOperator
         >>> problem = PEP()
         >>> h = problem.declare_function(function_class=MonotoneOperator)
 

PEPit/operators/strongly_monotone.py

@@ -8,7 +8,7 @@ class StronglyMonotoneOperator(Function):
     (maximally monotone) operators.
 
     Note:
-        Operators'values can be requested through `gradient` and `function values` should not be used.
+        Operator values can be requested through `gradient` and `function values` should not be used.
 
     Attributes:
         mu (float): strong monotonicity parameter
@@ -18,6 +18,7 @@ class StronglyMonotoneOperator(Function):
 
     Example:
         >>> from PEPit import PEP
+        >>> from PEPit.operators import StronglyMonotoneOperator
         >>> problem = PEP()
         >>> h = problem.declare_function(function_class=StronglyMonotoneOperator, mu=.1)
 

docs/source/quickstart.rst

@@ -69,6 +69,20 @@ From now, you can declare functions thanks to the `declare_function` method.
 
     func = problem.declare_function(SmoothConvexFunction, L=L)
 
+.. warning::
+    To enforce the same subgradient to be returned each time one is required,
+    we introduced the attribute `reuse_gradient` in the `Function` class.
+    Some classes of functions contain only differentiable functions (e.g. smooth convex function).
+    In those, the `reuse_gradient` attribute is set to True by default.
+
+    When the same subgradient is used several times in the same code and when it is difficult to
+    to keep track of it (through proximal calls for instance), it may be useful to set this parameter
+    to True even if the function is not differentiable. This helps reducing the number of constraints,
+    and improve the accuracy of the underlying semidefinite program. See for instance the code for
+    `improved interior method 
+    <https://pepit.readthedocs.io/en/latest/examples/b.html#improved-interior-method>`_ or
+    `no Lips in Bregman divergence
+    <https://pepit.readthedocs.io/en/latest/examples/b.html#no-lips-in-bregman-divergence>`_.
 
 You can also define a new point with
 
@@ -139,6 +153,14 @@ Finally, you can ask PEPit to solve the system for you and return the worst-case
 
     pepit_tau = problem.solve()
 
+.. warning::
+    Performance estimation problems consist in reformulating the problem of finding a worst-case scenario as a semidefinite
+    program (SDP). The dimension of the corresponding SDP is directly related to the number of function and gradient evaluations
+    in a given code.
+    
+    We encourage the users to perform as few function and subgradient evaluations as possible, as the size of the
+    corresponding SDP grows with the number of subgradient/function evaluations at different points.
+
 
 Derive proofs and adversarial objectives
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -192,25 +214,34 @@ Then, after solving the system, you can require its associated dual variable val
 Output pdf
 ~~~~~~~~~~
 
-In a latter release, we will provide an option to output a pdf file summarizing all those pieces of information.
+In a later release, we will provide an option to output a pdf file summarizing all those pieces of information.
 
-Simplify proofs
-^^^^^^^^^^^^^^^
+Simpler worst-case scenarios
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Sometimes, there are several solutions to the PEP problem.
-In order to simplify the proof, one would prefer a low dimension solution.
-To this end, we provide an **heuristic** based on the trace to reduce the dimension of the provided solution.
+For obtaining simpler worst-case scenarios, one would prefer a low dimension solutions to the SDP.
+To this end, we provide **heuristics** based on the trace norm or log det minimization for reducing
+the dimension of the numerical solution to the SDP.
 
-You can use it  by specifying
+You can use the trace heuristic by specifying
 
 .. code-block::
 
     problem.solve(dimension_reduction_heuristic="trace")
+    
+You can use the n iteration of the log det heuristic by specifying "logdetn". For example, for
+using 5 iterations of the logdet heuristic:
+
+.. code-block::
+
+    problem.solve(dimension_reduction_heuristic="logdet5")
+
 
 Finding Lyapunov
 ^^^^^^^^^^^^^^^^
 
-In a latter release, we will provide tools to help finding good Lyapunov functions to study a given method.
+In a later release, we will provide tools to help finding good Lyapunov functions to study a given method.
 
 This tool will be based on the very recent work [7].