Core Data Structures#

Vector#

class pepflow.Vector(is_basis: bool, eval_expression: VectorRepresentation | VectorByBasisRepresentation | ZeroVector | None = None, tags: list[str] = NOTHING, math_expr: MathExpr = NOTHING)#

A Vector object represents an element of a vector space.

Examples include a point or a gradient.

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

The inner product of two Vector objects can also be taken. Let x and y be Vector objects. Then, their inner product is x*y and returns a Scalar object.

Variables:

is_basis (bool) – True if this vector is not formed through a linear combination of other vectors. False otherwise.
tags (list[str]) – A list that contains tags that can be used to identify the Vector object. Tags should be unique.
math_expr (MathExpr) – A MathExpr object with a member variable that contains a mathematical expression represented as a string.

Example

>>> import pepflow as pf
>>> ctx = pf.PEPContext("ctx").set_as_current()
>>> x_0 = pf.Vector(is_basis=True).add_tag("x_0")

Note

Basis Vector objects should be defined using the constructor as shown in the example but composite Vector objects should be created using operations on Vector objects.

add_tag(tag: str) → Vector#

Add a new tag for this Vector object.

Parameters:: tag (str) – The new tag to be added to the tags list.
Returns:: The instance itself.

eval(ctx: PEPContext | None = None, *, resolve_parameters: dict[str, Number | Number] | None = None, sympy_mode: bool = False) → ndarray#

Return the concrete representation of this Vector.

Concrete representations of Vector objects are EvaluatedVector objects.

Parameters:

ctx (PEPContext | None) – The PEPContext object we consider. None if we consider the current global PEPContext object.
resolve_parameters (dict[str, NUMERICAL_TYPE] | None) – A dictionary that maps the name of parameters to the numerical values.
sympy_mode (bool) – If true, then the input should be defined completely in terms of SymPy objects and should not mix Python numeric objects. Will raise an error if sympy_mode is True and the input contains a Python numeric object. By default False.

Returns:

EvaluatedVector – The concrete representation of this Vector.

repr_by_basis(ctx: PEPContext | None = None, *, resolve_parameters: dict[str, Number | Number] | None = None, sympy_mode: bool = False) → str#

Express this Vector object as the linear combination of the basis Vector objects of the given PEPContext.

This linear combination is expressed as a str where, to refer to the basis Vector objects, we use their tags.

Parameters:

ctx (PEPContext) – The PEPContext object whose basis Vector objects we consider. None if we consider the current global PEPContext object.
resolve_parameters (dict[str, NUMERICAL_TYPE] | None) – A dictionary that maps the name of parameters to the numerical values.
sympy_mode (bool) – If true, then the input should be defined completely in terms of SymPy objects and should not mix Python numeric objects. Will raise an error if sympy_mode is True and the input contains a Python numeric object. By default False.

Returns:

str – The representation of this Vector object in terms of the basis Vector objects of the given PEPContext.

simplify(tag: str | None = None) → Vector#

Simplify the mathematical expression of this Vector object.

Returns:: Vector – A new Vector object with the simplified mathematical expression.

property tag#

Returns the most recently added tag.

Returns:: str – The most recently added tag of this Vector object.

static zero() → Vector#

A static method that returns a Vector object that corresponds to zero.

Returns:: Vector – A zero Vector object.

class pepflow.EvaluatedVector(coords: ndarray)#

The concrete representation of the abstract Vector.

Each abstract basis Vector object has a unique concrete representation as a unit vector. The concrete representations of linear combinations of abstract basis Vector objects are linear combinations of the unit vectors. This information is stored in the coords attribute.

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

Variables:: coords (np.ndarray) – The concrete representation of an abstract Vector.

Scalar#

class pepflow.Scalar(is_basis: bool, eval_expression: ScalarRepresentation | ScalarByBasisRepresentation | ZeroScalar | None = None, tags: list[str] = NOTHING, math_expr: MathExpr = NOTHING)#

A Scalar object represents linear combination of functions values, inner products of Point objects, and constant scalar values.

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

Variables:

is_basis (bool) – True if this scalar is not formed through a linear combination of other scalars. False otherwise.
tags (list[str]) – A list that contains tags that can be used to identify the Vector object. Tags should be unique.
math_expr (MathExpr) – A MathExpr object with a member variable that contains a mathematical expression represented as a string.

Example

>>> import pepflow as pf
>>> ctx = pf.PEPContext("cts").set_as_current()
>>> s1 = pf.Scalar(is_basis=True, tags=["s1"])

Note

Basis Scalar objects should be defined using the constructor as shown in the example but composite Scalar objects should be created using operations on Scalar objects.

add_tag(tag: str) → Scalar#

Add a new tag for this Scalar object.

Parameters:: tag (str) – The new tag to be added to the tags list.
Returns:: The instance itself.

eq(other: Scalar | float | int, name: str) → ScalarConstraint#

Generate a ScalarConstraint object that represents the inequality self = other.

Parameters:

other (Scalar | float | int) – The other side of the relation.
name (str) – The name of the generated ScalarConstraint object.

Returns:

ScalarConstraint – An object that represents the inequality self = other.

eval(ctx: PEPContext | None = None, *, resolve_parameters: dict[str, Number | Number] | None = None, sympy_mode: bool = False) → EvaluatedScalar#

Return the concrete representation of this Scalar.

Concrete representations of Scalar objects are EvaluatedScalar objects.

Parameters:

ctx (PEPContext | None) – The PEPContext object we consider. None if we consider the current global PEPContext object.
resolve_parameters (dict[str, NUMERICAL_TYPE] | None) – A dictionary that maps the name of parameters to the numerical values.
sympy_mode (bool) – If true, then the input should be defined completely in terms of SymPy objects and should not mix Python numeric objects. Will raise an error if sympy_mode is True and the input contains a Python numeric object. By default False.

Returns:

EvaluatedScalar – The concrete representation of this Scalar.

ge(other: Scalar | float | int, name: str) → ScalarConstraint#

Generate a ScalarConstraint object that represents the inequality self >= other.

Parameters:

other (Scalar | float | int) – The other side of the relation.
name (str) – The name of the generated ScalarConstraint object.

Returns:

ScalarConstraint – An object that represents the inequality self >= other.

gt(other: Scalar | float | int, name: str) → ScalarConstraint#

Generate a ScalarConstraint object that represents the inequality self > other.

Parameters:

other (Scalar | float | int) – The other side of the relation.
name (str) – The name of the generated ScalarConstraint object.

Returns:

ScalarConstraint – An object that represents the inequality self > other.

le(other: Scalar | float | int, name: str) → ScalarConstraint#

Generate a ScalarConstraint object that represents the inequality self <= other.

Parameters:

other (Scalar | float | int) – The other side of the relation.
name (str) – The name of the generated ScalarConstraint object.

Returns:

ScalarConstraint – An object that represents the inequality self <= other.

lt(other: Scalar | float | int, name: str) → ScalarConstraint#

Generate a ScalarConstraint object that represents the inequality self < other.

Parameters:

other (Scalar | float | int) – The other side of the relation.
name (str) – The name of the generated ScalarConstraint object.

Returns:

ScalarConstraint – An object that represents the inequality self < other.

repr_by_basis(ctx: PEPContext | None = None, *, greedy_square: bool = False, resolve_parameters: dict[str, Number | Number] | None = None, sympy_mode: bool = False) → str#

Express this Scalar object in terms of the basis Vector and Scalar objects of the given PEPContext.

A Scalar can be formed by linear combinations of basis Scalar objects. A Scalar can also be formed through the inner product of two basis Vector objects. This function returns the representation of this Scalar object in terms of the basis Vector and Scalar objects as a str.

Parameters:

ctx (PEPContext) – The PEPContext object whose basis Vector and Scalar objects we consider. None if we consider the current global PEPContext object.
greedy_square (bool) – If greedy_square is true, the function will try to return \(\|a-b\|^2\) whenever possible. If not, the function will return \(\|a\|^2 - 2 * \langle a, b \rangle + \|b\|^2\) instead. True by default.
resolve_parameters (dict[str, NUMERICAL_TYPE] | None) – A dictionary that maps the name of parameters to the numerical values.
sympy_mode (bool) – If true, then the input should be defined completely in terms of SymPy objects and should not mix Python numeric objects. Will raise an error if sympy_mode is True and the input contains a Python numeric object. By default False.

Returns:

str – The representation of this Scalar object in terms of the basis Vector and Scalar objects of the given PEPContext.

Example

>>> import pepflow as pf
>>> import sympy as sp
>>> ctx = pf.PEPContext("ctx").set_as_current()
>>> xi = pf.Vector(is_basis=True, tags=["x_i"])
>>> xj = pf.Vector(is_basis=True, tags=["x_j"])
>>> em = pf.ExpressionManager(ctx)
>>> term = 2 / sp.S(3) * (xi + xj) ** 2 + 1 / sp.S(3) * (xi - xj) ** 2
>>> term_str = term.repr_by_basis(ctx, sympy_mode=True)
>>> pf.pprint_str(term_str)

simplify(tag: str | None = None) → Scalar#

Simplify the mathematical expression of this Scalar object.

Returns:: Scalar – A new Scalar object with the simplified mathematical expression.

property tag#

Returns the most recently added tag.

Returns:: str – The most recently added tag of this Scalar object.

static zero() → Scalar#

A static method that returns a Scalar object that corresponds to zero.

Returns:: Scalar – A zero Scalar object.

class pepflow.EvaluatedScalar(func_coords: ndarray, inner_prod_coords: ndarray, offset: float)#

The concrete representation of the abstract Scalar.

Each abstract basis Scalar object has a unique concrete representation as a unit vector. The concrete representations of linear combinations of abstract basis Scalar objects are linear combinations of the unit vectors. This information is stored in the func_coords attribute.

Abstract Scalar objects can be formed through taking the inner product of two abstract Vector objects. The concrete representation of an abstract Scalar object formed this way is the outer product of the concrete representations of the two abstract Vector objects, i.e., a matrix. This information is stored in the inner_prod_coords attribute.

Abstract Scalar objects can be added or subtracted with numeric data types. This information is stored in the offset attribute.

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

Variables:

func_coords (np.ndarray) – The vector component of the concrete representation of the abstract Scalar.
inner_prod_coords (np.ndarray) – The matrix component of the concrete representation of the abstract Scalar. An alias is matrix.
offset (float) – The constant component of the concrete representation of the abstract Scalar.

property matrix: ndarray#: A short alias for inner_prod_coords.

Parameter#

class pepflow.Parameter(name: str | None, eval_expression: ParameterRepresentation | None = None)#

A Parameter object that represents some numerial value that can be resolved later.

Variables:

name (str | None) – The name of the Parameter object. If name is None, it means it is a composite parameter and eval_expression needs to be provided.
eval_expression (ParameterRepresentation | None) – A datastructure that is used to evaluate the value of parameter.

Example

>>> import pepflow as pf
>>> ctx = pf.PEPContext("example").set_as_current()
>>> v = pf.Vector(is_basis=True, tag=["p1"])
>>> pm = pf.Parameter(name="param")
>>> v2 = pm * v
>>> v2.eval(resolve_parameters={"param": 2})

Note

Basis Parameter objects should be defined using the constructor as shown in the example but composite Parameter objects should be created using operations on Parameter objects.

Scalar Constraint#

class pepflow.ScalarConstraint(lhs: Scalar | float, rhs: Scalar | float, cmp: Comparator, name: str, associated_dual_var_constraints: list[tuple[Comparator, float]] = NOTHING)#

A ScalarConstraint object that represents inequalities and equalities of Scalar objects.

Denote an arbitrary Scalar objects as x and y. ScalarConstraint objects represent: x <= y, x >= y, and x = y.

Variables:

lhs (Scalar) – The Scalar object on the left hand side of the relation.
rhs (Scalar) – The Scalar object on the right hand side of the relation.
cmp (Comparator) – Comparator is an enumeration that can be either GE, LE, or EQ. They represent >=, <=, or = respectively.
name (str) – The unique name of the Comparator object.
associated_dual_var_constraints (list[tuple[Comparator, float]]) – A list of all the constraints imposed on the associated dual variable of this ScalarConstraint object.

Example

>>> s1 = scalar.Scalar(is_basis=True, tags=["s1"])
>>> s2 = scalar.Scalar(is_basis=True, tags=["s2"])
>>> (s1).le(s2, name="constraint_1")

dual_eq(val: float) → None#

Generates a = constraint on the dual variable associated with this constraint.

Denote the associated dual variable of this constraint as lambd. This generates a relation of the form lambd = val.

Parameters:: val (float) – The other object in the relation.

dual_ge(val: float) → None#

Generates a >= constraint on the dual variable associated with this constraint.

Denote the associated dual variable of this constraint as lambd. This generates a relation of the form lambd >= val.

Parameters:: val (float) – The other object in the relation.

dual_le(val: float) → None#

Generates a <= constraint on the dual variable associated with this constraint.

Denote the associated dual variable of this constraint as lambd. This generates a relation of the form lambd <= val.

Parameters:: val (float) – The other object in the relation.

classmethod make(lhs: Scalar | float, op: str, rhs: Scalar | float, name: str) → ScalarConstraint#

A static method to construct a ScalarConstraint object.

Parameters:

lhs (Scalar | float) – The Scalar object on the left hand side of the relation.
op (str) – A str which represents the type of relation. Possible options are le, ge, lt, gt, eq, <=, >=, <, >, or ==.
rhs (Scalar | float) – The Scalar object on the right hand side of the relation.
name (str) – The unique name of the constructed Comparator object.

PSD Constraint#

class pepflow.PSDConstraint(lhs: ndarray | float, rhs: ndarray | float, cmp: Comparator, name: str, associated_dual_var_constraints: list[tuple[Comparator, ndarray | float]] = NOTHING)#

A PSDConstraint object that represents positive semidefinite constraints.

Denote matrices as X and Y. PSDConstraint objects represent: X << Y, X >> Y, and X = Y.

Variables:

lhs (np.ndarray | float) – The matrix on the left hand side of the relation. The np.ndarray is composed of Scalar objects.
rhs (np.ndarray | float) – The matrix on the right hand side of the relation. The np.ndarray is composed of Scalar objects.
cmp (Comparator) – Comparator is an enumeration that can be either SEQ, PEQ, or EQ. They represent >>, <<, or = respectively.
name (str) – The unique name of the Comparator object.
associated_dual_var_constraints (list[tuple[Comparator, float]]) – A list of all the constraints imposed on the associated dual variable of this PSDConstraint object.

dual_eq(val: ndarray | float) → None#

Generates a = constraint on the dual variable associated with this constraint.

Denote the associated dual variable of this constraint as lambd. This generates a relation of the form lambd = val.

Parameters:: val (np.ndarray | float) – The other object in the relation.

dual_peq(val: ndarray | float) → None#

Generates a << constraint on the dual variable associated with this constraint.

Denote the associated dual variable of this constraint as lambd. This generates a relation of the form lambd << val.

Parameters:: val (np.ndarray | float) – The other object in the relation.

dual_seq(val: ndarray | float) → None#

Generates a >> constraint on the dual variable associated with this constraint.

Denote the associated dual variable of this constraint as lambd. This generates a relation of the form lambd >> val.

Parameters:: val (np.ndarray | float) – The other object in the relation.

is_compatiable_shape(val: ndarray | float) → None#: Check that if val is a np.ndarray whether it is of the same shape as the LHS and RHS.

classmethod make(lhs: ndarray | float, op: str, rhs: ndarray | float, name: str) → PSDConstraint#

A static method to construct a PSDConstraint object.

Parameters:

lhs (np.ndarray | float) – The np.ndarray object on the left hand side of the relation.
op (str) – A str which represents the type of relation. Possible options are peq, seq, eq, <<, >>, or ==.
rhs (np.ndarray | float) – The np.ndarray object on the right hand side of the relation.
name (str) – The unique name of the constructed Comparator object.

ConstraintData#

class pepflow.ConstraintData(func_or_oper: Function | Operator, sc_dict: dict[str, list[ScalarConstraint]] = NOTHING, psd_dict: dict[str, PSDConstraint] = NOTHING)#

A data class that will store a Function’s or Operator’s interpolation conditions.

Functions and operators can have multiple groups of interpolations conditions. There are typically two types of groups. One group is composed of associated ScalarConstraint objects. The other is an individual PSDConstraint object.

Variables:

func_or_oper (Function | Operator) – The associated Function or Operator.
sc_dict (dict[str, list[ScalarConstraint]]) – A dictionary in which the keys are the name of the groups of ScalarConstraint objects and the values are a list of associated ScalarConstraint objects.
psd_dict (dict[str, PSDConstraint]) – A dictionary in which the keys are the names of the types of the PSDConstraint objects and the values are the PSDConstraint objects.

add_psd_constraint(constraint_type: str, psd_constraint: PSDConstraint) → None#

Add a new PSDConstraint object.

Parameters:

constraint_type (str) – The name to refer to the group of scalar constraints repesented by scal_constraint.
psd_constraint (PSDConstraint) – The new list of ScalarConstraint objects to add.

add_sc_constraint(constraint_type: str, scal_constraint: list[ScalarConstraint]) → None#

Add a new list of ScalarConstraint objects.

Parameters:

constraint_type (str) – The name to refer to the group of scalar constraints repesented by scal_constraint.
scal_constraint (list[ScalarConstraint]) – The new list of ScalarConstraint objects to add.