Merge pull request #49 from PerformanceEstimation/prepare_for_release_0.1.0

Prepare for release 0.1.0

Author: bgoujaud

PEPit/__init__.py

@@ -1,17 +1,17 @@
 from .constraint import Constraint
-from .expression import Expression
+from .expression import Expression, null_expression
 from .function import Function
 from .pep import PEP
-from .point import Point
+from .point import Point, null_point
 
 __all__ = ['examples',
            'functions',
            'operators',
            'primitive_steps',
            'tools',
            'constraint', 'Constraint',
-           'expression', 'Expression',
+           'expression', 'Expression', 'null_expression',
            'function', 'Function',
            'pep', 'PEP',
-           'point', 'Point',
+           'point', 'Point', 'null_point',
            ]

PEPit/expression.py

@@ -401,3 +401,7 @@ def eval(self):
 
         # Return the value
         return self._value
+
+
+# Define a null Expression initialized to 0.
+null_expression = Expression(is_leaf=False, decomposition_dict=dict())

PEPit/pep.py

@@ -22,10 +22,6 @@ class PEP(object):
                                    Typically the initial :class:`Constraint`.
         list_of_performance_metrics (list): list of :class:`Expression` objects.
                                             The pep maximizes the minimum of all performance metrics.
-        null_point (Point): a :class:`Point` initialized to 0,
-                            easily callable to initialize a :class:`Point` before a for loop.
-        null_expression (Expression): a :class:`Expression` initialized to 0,
-                                      easily callable to initialize a :class:`Expression` before a for loop.
         counter (int): counts the number of :class:`PEP` objects.
                        Ideally, only one is defined at a time.
 
@@ -63,10 +59,6 @@ def __init__(self):
         self.list_of_performance_metrics = list()
         self.list_of_psd = list()
 
-        # Add useful attributes of Point and Expression initialized to 0 in their respective space.
-        self.null_point = Point(is_leaf=False, decomposition_dict=dict())
-        self.null_expression = Expression(is_leaf=False, decomposition_dict=dict())
-
     def declare_function(self, function_class, **kwargs):
         """
         Instantiate a leaf :class:`Function` and store it in the attribute `list_of_functions`.
@@ -152,6 +144,7 @@ def add_psd_matrix(self, matrix):
 
         Raises:
             AssertionError: if provided matrix is not a square matrix.
+            TypeError: if provided matrix does not contain only Expressions.
 
         """
 
@@ -165,9 +158,16 @@ def add_psd_matrix(self, matrix):
         # Transform scalars into Expressions
         for i in range(size):
             for j in range(size):
-                # If entry is neither an Expression nor a python scalar,
-                # __radd__ method of class Expression raises an Exception.
-                matrix[i, j] += self.null_expression
+                # The entry must be an Expression ...
+                if isinstance(matrix[i, j], Expression):
+                    pass
+                # ... or a python scalar. If so, store it as an Expression
+                elif isinstance(matrix[i, j], int) or isinstance(matrix[i, j], float):
+                    matrix[i, j] = Expression(is_leaf=False, decomposition_dict={1: matrix[i, j]})
+                # Raise an Exception in any other scenario
+                else:
+                    raise TypeError("PSD matrices contains only Expressions and / or scalar values!"
+                                    "Got {}".format(type(matrix[i, j])))
 
         # Add constraint to the list of self's constraints
         self.list_of_psd.append(matrix)

PEPit/point.py

@@ -276,3 +276,7 @@ def eval(self):
                 self._value = value
 
         return self._value
+
+
+# Define a null Point initialized to 0.
+null_point = Point(is_leaf=False, decomposition_dict=dict())

docs/source/whatsnew.rst

@@ -6,4 +6,4 @@ What's new in PEPit
    :maxdepth: 2
    :caption: Contents:
 
-   whatsnew/0.0.3
+   whatsnew/0.1.0

docs/source/whatsnew/0.0.3.rst

@@ -0,0 +1,59 @@
+What's new in PEPit 0.1.0
+=========================
+
+- Adding general constraints to your problem.
+
+    | The method ``add_constraint`` has been added to the class ``PEP`` for general constraints not necessarily related to a specific function.
+    | For readability of your code,
+      we suggest to use the method ``set_initial_condition`` when the constraint is the initial one,
+      and the method ``add_constraint`` for any other constraint.
+
+- Adding LMI constraints to your problem.
+
+    The method ``add_psd_matrix`` has been added to the class ``PEP`` and must be used to add LMI constraints to your problem.
+
+- CVXPY options.
+
+    | PEPit uses CVXPY to solve the underlying SDP of your problem.
+    | CVXPY solver options can be provided to the method ``PEP.solve``.
+
+- Optimizing dimension of the solution.
+
+    | The ``tracetrick`` option of the method ``PEP.solve`` has been replaced by ``dimension_reduction_heuristic``.
+    | Set to None by default, this option can be set to "`trace`" or "`logdet{followed by a number}`" to use one of those heuristic.
+
+- Granularity of the verbose mode has evolved.
+
+    | The verbose mode of the method ``PEP.solve`` and of the provided examples files are now integers:
+        - 0: No verbose at all
+        - 1: PEPit information is printed but not CVXPY's
+        - 2: Both PEPit and CVXPY details are printed
+
+- Parameters of function classes.
+
+    | The parameters that characterize a function class must be provided directly as arguments of this function class, not through the dict "param" anymore.
+    | Example: ``PEP.declare_function(function_class=SmoothStronglyConvexFunction, mu=.1, L=1.)``
+
+- Initializing a Point or an Expression to 0.
+
+    ``null_point`` and ``null_expression`` have been added to the module ``PEPit`` to facilitate the access to a ``Point`` or an ``Expression`` initialized to 0.
+
+- 3 new function classes have been added:
+
+    - ``ConvexSupportFunction`` for convex support functions (see [1])
+    - ``ConvexQGFunction``, for convex and quadratically upper bounded functions (see [2])
+    - ``RsiEbFunction``, for functions verifying lower restricted secant inequality and upper error bound (see [3])
+
+`[1] A. Taylor, J. Hendrickx, F. Glineur (2017).
+Exact worst-case performance of first-order methods for composite convex optimization.
+SIAM Journal on Optimization, 27(3):1283–1313.
+<https://arxiv.org/pdf/1512.07516.pdf>`_
+
+`[2] B. Goujaud, A. Taylor, A. Dieuleveut (2022).
+Optimal first-order methods for convex functions with a quadratic upper bound.
+<https://arxiv.org/pdf/2205.15033.pdf>`_
+
+`[3] C. Guille-Escuret, B. Goujaud, A. Ibrahim, I. Mitliagkas (2022).
+Gradient Descent Is Optimal Under Lower Restricted Secant Inequality And Upper Error Bound.
+arXiv 2203.00342.
+<https://arxiv.org/pdf/2203.00342.pdf>`_

docs/source/whatsnew/0.1.0.rst

@@ -3,7 +3,7 @@
 with open("README.md", "r", encoding="utf-8") as fh:
     long_description = fh.read()
 
-version = "0.0.3a1"
+version = "0.1.0"
 
 setuptools.setup(
     name="PEPit",