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
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)
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 if 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(mu, 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
Operator 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 >>> from PEPit.operators import StronglyMonotoneOperator >>> problem = PEP() >>> h = problem.declare_function(function_class=StronglyMonotoneOperator, 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
mu (float) – Strong monotonicity parameter.
is_leaf (bool) – True if self is defined from scratch. False if 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(L=1.0, 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
Operator 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 >>> from PEPit.operators import LipschitzOperator >>> problem = PEP() >>> func = problem.declare_function(function_class=LipschitzOperator, 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
L (float) – Lipschitz continuity parameter.
is_leaf (bool) – True if self is defined from scratch. False if 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(mu, L=1.0, 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
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 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 >>> from PEPit.operators import LipschitzStronglyMonotoneOperator >>> problem = PEP() >>> h = problem.declare_function(function_class=LipschitzStronglyMonotoneOperator, mu=.1, L=1.)
References
- Parameters
mu (float) – The strong monotonicity parameter.
L (float) – The Lipschitz continuity parameter.
is_leaf (bool) – True if self is defined from scratch. False if 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(beta=1.0, 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
Operator 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 >>> from PEPit.operators import CocoerciveOperator >>> problem = PEP() >>> func = problem.declare_function(function_class=CocoerciveOperator, beta=1.)
References
- Parameters
beta (float) – The cocoercivity parameter.
is_leaf (bool) – True if self is defined from scratch. False if 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.