Operators
Monotone
- class PEPit.operators.MonotoneOperator(_, is_leaf=True, decomposition_dict=None, reuse_gradient=False)[source]
Bases:
Function
The
MonotoneOperator
class overwrites the add_class_constraints method ofFunction
, 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.
General maximally monotone operators are not characterized by any parameter, hence can be instantiated as
Example
>>> from PEPit import PEP >>> problem = PEP() >>> h = problem.declare_function(function_class=MonotoneOperator, param=dict())
References
[1] H. H. Bauschke and P. L. Combettes (2017). Convex Analysis and Monotone Operator Theory in Hilbert Spaces. Springer New York, 2nd ed.
- Parameters
is_leaf (bool) – True if self is defined from scratch. False is self is defined as linear combination of leaf .
decomposition_dict (dict) – decomposition of self as linear combination of leaf
Function
objects. Keys areFunction
objects and values are their associated coefficients.reuse_gradient (bool) – If True, the same subgradient is returned when one requires it several times on the same
Point
. If False, a new subgradient is computed each time one is required.
Strongly monotone
- class PEPit.operators.StronglyMonotoneOperator(param, is_leaf=True, decomposition_dict=None, reuse_gradient=False)[source]
Bases:
Function
The
StronglyMonotoneOperator
class overwrites the add_class_constraints method ofFunction
, implementing interpolation constraints of the class of strongly monotone (maximally monotone) operators.Note
Operators’values can be requested through gradient and function values should not be used.
- Attributes
mu (float) – strong monotonicity parameter
Strongly monotone (and maximally monotone) operators are characterized by the parameter \(\mu\), hence can be instantiated as
Example
>>> from PEPit import PEP >>> problem = PEP() >>> h = problem.declare_function(function_class=StronglyMonotoneOperator, param={'mu': .1})
References
Discussions and appropriate pointers for the problem of interpolation of maximally monotone operators can be found in: [1] E. Ryu, A. Taylor, C. Bergeling, P. Giselsson (2020). Operator splitting performance estimation: Tight contraction factors and optimal parameter selection. SIAM Journal on Optimization, 30(3), 2251-2271.
- Parameters
param (dict) – contains the values of mu.
is_leaf (bool) – True if self is defined from scratch. False is self is defined as linear combination of leaf .
decomposition_dict (dict) – decomposition of self as linear combination of leaf
Function
objects. Keys areFunction
objects and values are their associated coefficients.reuse_gradient (bool) – If True, the same subgradient is returned when one requires it several times on the same
Point
. If False, a new subgradient is computed each time one is required.
Lipschitz continuous
- class PEPit.operators.LipschitzOperator(param, is_leaf=True, decomposition_dict=None, reuse_gradient=True)[source]
Bases:
Function
The
LipschitzOperator
class overwrites the add_class_constraints method ofFunction
, 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.
- Attributes
L (float)
Cocoercive operators are characterized by the parameter \(L\), hence can be instantiated as
Example
>>> from PEPit import PEP >>> problem = PEP() >>> func = problem.declare_function(function_class=LipschitzOperator, param={'L': 1})
Notes
By setting L=1, we define a non expansive operator.
By setting L<1, we define a contracting operator.
References
[1] M. Kirszbraun (1934). Uber die zusammenziehende und Lipschitzsche transformationen. Fundamenta Mathematicae, 22 (1934).
[2] F.A. Valentine (1943). On the extension of a vector function so as to preserve a Lipschitz condition. Bulletin of the American Mathematical Society, 49 (2).
[3] F.A. Valentine (1945). A Lipschitz condition preserving extension for a vector function. American Journal of Mathematics, 67(1).
Discussions and appropriate pointers for the interpolation problem can be found in: [4] E. Ryu, A. Taylor, C. Bergeling, P. Giselsson (2020). Operator splitting performance estimation: Tight contraction factors and optimal parameter selection. SIAM Journal on Optimization, 30(3), 2251-2271.
- Parameters
param (dict) – contains the values of L.
is_leaf (bool) – True if self is defined from scratch. False is self is defined as linear combination of leaf .
decomposition_dict (dict) – decomposition of self as linear combination of leaf
Function
objects. Keys areFunction
objects and values are their associated coefficients.reuse_gradient (bool) – If True, the same subgradient is returned when one requires it several times on the same
Point
. If False, a new subgradient is computed each time one is required.
Note
Lipschitz continuous operators are necessarily continuous, hence reuse_gradient is set to True.
Strongly monotone and Lipschitz continuous
- class PEPit.operators.LipschitzStronglyMonotoneOperator(param, is_leaf=True, decomposition_dict=None, reuse_gradient=True)[source]
Bases:
Function
The
LipschitzStronglyMonotoneOperator
class overwrites the add_class_constraints method ofFunction
, implementing some constraints (which are not necessary and sufficient for interpolation) 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.
Warning
Lipschitz strongly monotone operators do not enjoy known interpolation conditions. The conditions implemented in this class are necessary but a priori not sufficient for interpolation. Hence the numerical results obtained when using this class might be non-tight upper bounds (see Discussions in [1, Section 2]).
- Attributes
mu (float) – strong monotonicity parameter
L (float) – Lipschitz parameter
Lipschitz continuous strongly monotone operators are characterized by parameters \(\mu\) and L, hence can be instantiated as
Example
>>> from PEPit import PEP >>> problem = PEP() >>> h = problem.declare_function(function_class=LipschitzStronglyMonotoneOperator, param={'mu': .1, 'L': 1})
References
- Parameters
param (dict) – contains the values of mu and L.
is_leaf (bool) – True if self is defined from scratch. False is self is defined as linear combination of leaf .
decomposition_dict (dict) – decomposition of self as linear combination of leaf
Function
objects. Keys areFunction
objects and values are their associated coefficients.reuse_gradient (bool) – If True, the same subgradient is returned when one requires it several times on the same
Point
. If False, a new subgradient is computed each time one is required.
Note
Lipschitz continuous strongly monotone operators are necessarily continuous, hence reuse_gradient is set to True.
Cocoercive
- class PEPit.operators.CocoerciveOperator(param, is_leaf=True, decomposition_dict=None, reuse_gradient=True)[source]
Bases:
Function
The
CocoerciveOperator
class overwrites the add_class_constraints method ofFunction
, 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.
- Attributes
beta (float) – cocoercivity parameter
Cocoercive operators are characterized by the parameter \(\beta\), hence can be instantiated as
Example
>>> from PEPit import PEP >>> problem = PEP() >>> func = problem.declare_function(function_class=CocoerciveOperator, param={'beta': 1})
References
- Parameters
param (dict) – contains the values of beta.
is_leaf (bool) – True if self is defined from scratch. False is self is defined as linear combination of leaf .
decomposition_dict (dict) – decomposition of self as linear combination of leaf
Function
objects. Keys areFunction
objects and values are their associated coefficients.reuse_gradient (bool) – If True, the same subgradient is returned when one requires it several times on the same
Point
. If False, a new subgradient is computed each time one is required.
Note
Cocoercive operators are necessarily continuous, hence reuse_gradient is set to True.