picos.expressions.expression

Backend for expression type implementations.

Outline

Classes

Expression

Abstract base class for mathematical expressions, including variables.

ExpressionType

The detailed type of an expression for predicting constraint outcomes.

Functions

refine_operands

Cast refined on both operands.

validate_prediction

Validate that the constraint outcome matches the predicted outcome.

Exceptions

NotValued

The operation cannot be performed due to a variable without a value.

PredictedFailure

Denotes that comparing two expressions will not form a constraint.

Classes

Expression

class picos.expressions.expression.Expression(typeStr, symbStr)[source]

Bases: abc.ABC

Abstract base class for mathematical expressions, including variables.

For variables, this is the secondary base class, with BaseVariable being the primary one.

__init__(typeStr, symbStr)[source]

Perform basic initialization for Expression instances.

Parameters
  • typeStr (str) – Short string denoting the expression type.

  • symbStr (str) – Algebraic string description of the expression.

is_valued()[source]

Whether the expression is valued.

Deprecated since version 2.0: Use valued instead.

classmethod make_type(*args, **kwargs)[source]

Create a detailed expression type from subtype parameters.

replace_variables(new_variables)[source]

Return a copy of the expression concerning different variables.

New variables must have the same shape and vectorization format as the variables that they replace. This means in particular that RealVariable, IntegerVariable and BinaryVariable of same shape are interchangeable.

If the variables to be replaced do not appear in the expression, then the expression is not copied but returned as is.

Parameters

new_variables (tuple or list or dict) – Either a map from variables or variable names to new variables or an iterable of new variables to replace existing variables of same name with.

set_value(value)[source]

Set the value of an expression, usually a variable.

Deprecated since version 2.0: Use value instead.

property concave

Whether the expression is concave.

property convex

Whether the expression is convex.

property refined

A refined version of the expression.

The refined expression can be an instance of a different Expression subclass than the original expression, if that type is better suited for the mathematical object in question.

The refined expression is automatically used instead of the original one whenever a constraint is created, and in some other places.

The idea behind refined expressions is that operations that produce new expressions can be executed quickly without checking for exceptionnel cases. For instance, the sum of two ComplexAffineExpression instances could have the complex part eliminated so that storing the result as an AffineExpression would be prefered, but checking for this case on every addition would be too slow. Refinement is used sparingly to detect such cases at times where it makes the most sense.

property shape

Return the algebraic shape of the expression.

property size

The same as shape.

property string

Symbolic string representation of the expression.

Use this over Python’s str if you want to output the symbolic representation even when the expression is valued.

property subtype

The subtype part of the expression’s detailed type.

Returns a hashable object that, together with the Python class part of the expression’s type, is sufficient to predict the constraint outcome (constraint class and subtype) of any comparison operation with any other expression.

By convention the object returned is a namedtuple instance.

property type

The expression’s detailed type for constraint prediction.

The returned value is suffcient to predict the detailed type of any constraint that can be created by comparing with another expression.

Since constraints are created from refined expressions only, the Python class part of the detailed type may differ from the type of the expression whose type is queried.

property value

Value of the expression.

It is defined (not None) if the expression is constant or if all variables involved in the expression are valued. Variables can be valued directly by writing to their value attribute, or they can be valued by PICOS when an optimization solution is found.

Some expressions can also be valued directly if PICOS can find a minimal norm variable assignment that makes the expression have the desired value. In particular, this works with affine expressions whose linear part has an under- or well-determined coefficient matrix.

Example

>>> from picos import RealVariable
>>> x = RealVariable("x", (1,3))
>>> y = RealVariable("y", (1,3))
>>> e = x - 2*y + 3
>>> print("e:", e)
e: x - 2·y + [3]
>>> e.value = [4, 5, 6]
>>> print("e: ", e, "\nx: ", x, "\ny: ", y, sep = "")
e: [ 4.00e+00  5.00e+00  6.00e+00]
x: [ 2.00e-01  4.00e-01  6.00e-01]
y: [-4.00e-01 -8.00e-01 -1.20e+00]

Unlike value_as_matrix, scalars are returned as scalar types.

property value_as_matrix

Value of the expression, as a CVXOPT matrix type.

Refer to value for when it is defined (not None).

Unlike value, scalars are returned in the form of 1x1 matrices.

property valued

Whether the expression is valued.

Note

Querying this attribute is not faster than immediately querying value and checking whether it is None. Use it only if you do not need to know the value, but only whether it is available.

Example

>>> from picos import RealVariable
>>> x = RealVariable("x", 3)
>>> x.valued
False
>>> x.value
>>> print((x|1))
∑(x)
>>> x.value = [1, 2, 3]
>>> (x|1).valued
True
>>> print((x|1))
6.0
property variables

Return the set of variables that are involved in the expression.

ExpressionType

class picos.expressions.expression.ExpressionType(theClass, subtype)[source]

Bases: picos.containers.DetailedType

The detailed type of an expression for predicting constraint outcomes.

This is suffcient to predict the detailed type of any constraint that can be created by comparing with another expression.

The prediction is done by using the relevant operator on instances of this class, as opposed to the expressions themselves. Note that operators used to create new expressions as opposed to constraints are not handled.

Functions

refine_operands

picos.expressions.expression.refine_operands(stop_at_affine=False)[source]

Cast refined on both operands.

If the left hand side operand (i.e. self) is refined to an instance of a different type, then, instead of the decorated method, the method with the same name on the refined type is invoked with the (refined) right hand side operand as its argument.

This decorator is supposed to be used on all constraint creating binary operator methods so that degenerated instances (e.g. a complex affine expression with an imaginary part of zero) can occur but are not used in constraints. This speeds up many computations involving expressions as these degenerate cases do not need to be detected. Note that Expression.type also refers to the refined version of an expression.

Parameters

stop_at_affine (bool) – Do not refine any affine expressions, in particular do not refine complex affine expressions to real ones.

validate_prediction

picos.expressions.expression.validate_prediction(operator)[source]

Validate that the constraint outcome matches the predicted outcome.

Exceptions

NotValued

exception picos.expressions.expression.NotValued[source]

Bases: RuntimeError

The operation cannot be performed due to a variable without a value.

Note that the value and value_as_matrix attributes do not raise this exception, but return None.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__new__(**kwargs)

Create and return a new object. See help(type) for accurate signature.

PredictedFailure

exception picos.expressions.expression.PredictedFailure[source]

Bases: TypeError

Denotes that comparing two expressions will not form a constraint.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__new__(**kwargs)

Create and return a new object. See help(type) for accurate signature.