Operators#

Operator Base Class#

class pepflow.Operator(*, is_basis: bool, composition: AddedOper | ScaledOper | None = None, tags: list[str] = NOTHING, math_expr: MathExpr = NOTHING)#

A Operator object represents an operator.

Operator objects can be constructed as linear combinations of other Operator objects. Let a and b be some numeric data type. Let A and B be Operator objects. Then, we can form a new Operator object: a*A+b*B.

A Operator object should never be explicitly constructed. Only children of Operator such as LinearOperator or MonotoneOperator should be constructed. See their respective documentation to see how.

Every child class needs to implement the get_interpolation_constraints_by_group() method. This returns a ConstraintData object which will store the Operator’s interpolation conditions. See the ConstraintData documentation for details and the LinearOperator or MonotoneOperator for examples.

Let A be a Operator object. The naming convention for a ScalarConstraint object representing an interpolation condition of A between two Vector objects x_0 and x_1 is {A.tag}:{x_0.tag},{x_1.tag}. The naming convention for a ScalarConstraint object representing an interpolation condition of A using only one Vector object x_0 is {A.tag}:{x_0.tag},{x_0.tag}.

If a Operator has multiple ScalarConstraint groups, then the naming convention of the individual ScalarConstraint objects must differ. For example, Lipschitz Strongly Monotone Operators has a group of ScalarConstraint objects representing the interpolation conditions related to Lipschitz Continuity and a group of ScalarConstraint objects representing the interpolation conditions related to Strong Monotonicity. Let A be a Operator object. A possible naming convention for a ScalarConstraint object representing an interpolation condition related to the Lipschitz Continuity of A between two Vector objects x_0 and x_1 is {A.tag}_convex:{x_0.tag},{x_1.tag}. A possible naming convention for a ScalarConstraint object representing an interpolation condition related to the Strong Monotonicity of A between two Vector objects x_0 and x_1 is {A.tag}_SM:{x_0.tag},{x_1.tag}.

Variables:

  • is_basis (bool) – True if this operator is not formed through a linear combination of other operators. False otherwise.

  • tags (list[str]) – A list that contains tags that can be used to identify the Operator object. Tags should be unique.

  • math_expr (MathExpr) – A MathExpr object with a member variable that contains a mathematical expression represented as a string.

add_tag(tag: str) → Operator#

Add a new tag for this Operator object.

Parameters:

tag (str) – The new tag to be added to the tags list.

apply(point: Vector) → Vector#

Returns a Vector object that is the output of the Operator applied on the given Vector.

Parameters:

point (Vector) – Any Vector.

Returns:

Vector – The output that results from applying the Operator on the given Vector.

get_interpolation_constraints_by_group(pep_context: PEPContext | None = None) → ConstraintData#

When implemented, structure the types of constraints as a list of related ScalarConstraint or individual PSDConstraint objects.

resolvent(x: Vector, stepsize: numbers.Number | Parameter, tag: str | None = None) → Vector#

Apply the resolvent of this operator on the input \(x\).

Define the resolvent operator as

\[J_{\gamma A} := (I+\gamma A)^{-1},\]

where \(I\) is the identity operator.

This function returns the output Vector \(u\) found from applying the resolvent of this Operator \(A\) on the input Vector \(x\) with stepsize \(\gamma\).

Parameters:

  • x (Vector) – The input point.

  • stepsize (numbers.Number | Parameter) – The stepsize.

  • tag (str | None) – By default set to None. Pass a tag to add to the output of the resolvent applied the input point.

Returns:

Vector – The output of the resolvent applied on x.

Note

For children of Operator for which the resolvent is not defined, overwrite the function to raise NotImplemented.

set_fixed_point(name: str) → Vector#

Return a fixed point for this Operator object.

A Operator object can only have one fixed point.

Parameters:

name (str) – The tag for the Vector object which will serve as the fixed point.

Returns:

Vector – The fixed point for this Operator object.

set_zero_point(name: str) → Vector#

Return a zero point for this Operator object.

A Operator object can only have one zero point.

Parameters:

name (str) – The tag for the Vector object which will serve as the zero point.

Returns:

Vector – The zero point for this Operator object.

property tag#

Returns the most recently added tag.

Returns:

str – The most recently added tag of this Operator object.

Duplet#

class pepflow.Duplet(point: Vector, output: Vector, oper: Operator, name: str | None)#

A data class that represents, for some given operator \(A\), the tuple \(\{x, Ax\}\).

Variables:

  • point (Vector) – A vector \(x\).

  • output (Vector) – A vector that represents \(Ax\).

  • name (str) – The unique name of the Duplet object.

expand() → tuple[Vector, Vector]#

Return the point and output member variables of a Duplet as a tuple.

Linear Operator#

class pepflow.LinearOperator(*, is_basis: bool, composition: AddedOper | ScaledOper | None = None, tags: list[str] = NOTHING, math_expr: MathExpr = NOTHING, M: NUMERICAL_TYPE | Parameter)#

Bases: Operator

The LinearOperator class represents a bounded, linear operator.

The LinearOperator class is a child of Operator.

A bounded linear operator has an operator norm \(M\). We can instantiate a LinearOperator object as follows:

Example

>>> import pepflow as pf
>>> A = pf.LinearOperator(is_basis=True, tags=["A"], M=1)

We can access the transpose of a LinearOperator object as follows:

Example

>>> import pepflow as pf
>>> A = pf.LinearOperator(is_basis=True, tags=["A"], M=1)
>>> A.T
add_tag(tag: str) → Operator#

Add a new tag for this Operator object.

Parameters:

tag (str) – The new tag to be added to the tags list.

get_interpolation_constraints_by_group(pep_context: PEPContext | None = None) → ConstraintData#

Return a ConstraintData object that manages the operator’s groups of interpolation conditions.

References

N. Bousselmi, J. M. Hendrickx, and F. Glineur, Interpolation Conditions for Linear Operators and Applications to Performance Estimation Problems, SIAM Journal on Optimization, 34 (2024), pp. 3033–3063.

resolvent(x: Vector, stepsize: numbers.Number | Parameter, tag: str | None = None) → Vector#

Note

The resolvent is not implemented for LinearOperator.

Monotone Operator#

class pepflow.MonotoneOperator(*, is_basis: bool, composition: AddedOper | ScaledOper | None = None, tags: list[str] = NOTHING, math_expr: MathExpr = NOTHING)#

Bases: Operator

The MonotoneOperator class represents a monotone operator.

The MonotoneOperator class is a child of Operator.

We can instantiate a MonotoneOperator object as follows:

Example

>>> import pepflow as pf
>>> A = pf.MonotoneOperator(is_basis=True, tags=["A"])
add_tag(tag: str) → MonotoneOperator#

Add a new tag for this MonotoneOperator object.

Parameters:

tag (str) – The new tag to be added to the tags list.

get_interpolation_constraints_by_group(pep_context: PEPContext | None = None) → ConstraintData#

Return a ConstraintData object that manages the operator’s groups of interpolation conditions.

interp_ineq(p1: Vector | str, p2: Vector | str, pep_context: PEPContext | None = None) → Scalar#

Generate the interpolation inequality Scalar object between two Vector objects through the objects themselves or their tags.

The interpolation inequality between two points \(p_1, p_2\) for a monotone operator \(A\) is

\[- \langle A(p_1) - A(p_2), p_1 - p_2 \rangle \leq 0.\]

References

H. H. Bauschke and P. L. Combettes, Convex Analysis and Monotone Operator Theory in Hilbert Spaces, 2017.

E. K. Ryu, A. B. Taylor, C. Bergeling, and P. Giselsson, Operator splitting performance estimation: Tight contraction factors and optimal parameter selection, SIAM Journal on Optimization, 30 (2020), pp. 2251–2271.

Parameters: