picos.expressions.variables

Implements all mathematical variable types.

Outline

Classes

BaseVariable

Primary base class for all variable types.

BinaryVariable

A \{0,1\}-valued variable.

ComplexVariable

A complex-valued variable.

HermitianVariable

A hermitian matrix variable.

IntegerVariable

An integer-valued variable.

LowerTriangularVariable

A lower triangular matrix variable.

RealVariable

A real-valued variable.

SkewSymmetricVariable

A skew-symmetric matrix variable.

SymmetricVariable

A symmetric matrix variable.

UpperTriangularVariable

An upper triangular matrix variable.

VariableType

The detailed type of a variable for predicting reformulation outcomes.

Classes

BaseVariable

class picos.expressions.variables.BaseVariable(name, vectorization, lower=None, upper=None)[source]

Bases: object

Primary base class for all variable types.

Variables need to inherit this class with priority (first class listed) and ComplexAffineExpression or AffineExpression without priority.

class VarSubtype(dim, bnd)

Bases: tuple

static __new__(_cls, dim, bnd)

Create new instance of VarSubtype(dim, bnd)

bnd

Alias for field number 1

dim

Alias for field number 0

__init__(name, vectorization, lower=None, upper=None)[source]

Perform basic initialization for BaseVariable instances.

Parameters
  • name (str) – Name of the variable. A leading “__” denotes a private variable and is replaced by a sequence containing the variable’s unique ID.

  • vectorization (BaseVectorization) – Vectorization format used to store the value.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

copy(new_name=None)[source]

Return an independent copy of the variable.

id_at(index)[source]

Return the unique ID of a scalar entry, assigned at creation.

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

Create a detailed variable type from subtype parameters.

See also var_type.

property bound_constraint

The variable bounds as a PICOS constraint, or None.

property bound_dicts

Variable bounds as a pair of mappings from index to scalar bound.

The indices and bound values are with respect to the internal representation of the variable, whose value can be accessed with internal_value.

Upper and lower bounds set to float("inf") and float("-inf") on variable creation, respectively, are not included.

property dim

The variable’s dimension on the real field.

This corresponds to the length of its vectorized value.

property id

The unique (starting) ID of the variable, assigned at creation.

property internal_value

The internal (special vectorized) value of the variable.

property long_string

Long string representation for printing a Problem.

property name

The name of the variable.

property num_bounds

Number of scalar bounds associated with the variable.

property var_subtype

The subtype part of the detailed variable type.

See also var_type.

property var_type

The detailed variable type.

This intentionally does not override Expression.type so that the variable still behaves as the affine expression that it represents when prediction constraint outcomes.

BinaryVariable

class picos.expressions.variables.BinaryVariable(name, shape=(1, 1))[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

A \{0,1\}-valued variable.

__init__(name, shape=(1, 1))[source]

Create a BinaryVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of a vector or matrix variable.

ComplexVariable

class picos.expressions.variables.ComplexVariable(name, shape=(1, 1))[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.ComplexAffineExpression

A complex-valued variable.

Passed to solvers as a real variable vector with 2mn entries.

__init__(name, shape=(1, 1))[source]

Create a ComplexVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of a vector or matrix variable.

HermitianVariable

class picos.expressions.variables.HermitianVariable(name, shape)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.ComplexAffineExpression

A hermitian matrix variable.

Stored internally and passed to solvers as the horizontal concatenation of a real symmetric vectorization with \frac{n(n+1)}{2} entries and a real skew-symmetric vectorization with \frac{n(n-1)}{2} entries, resulting in a real vector with only n^2 entries total.

__init__(name, shape)[source]

Create a HermitianVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of the matrix.

IntegerVariable

class picos.expressions.variables.IntegerVariable(name, shape=(1, 1), lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

An integer-valued variable.

__init__(name, shape=(1, 1), lower=None, upper=None)[source]

Create an IntegerVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of a vector or matrix variable.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

LowerTriangularVariable

class picos.expressions.variables.LowerTriangularVariable(name, shape=(1, 1), lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

A lower triangular matrix variable.

Stored internally and passed to solvers as a lower triangular vectorization with only \frac{n(n+1)}{2} entries.

__init__(name, shape=(1, 1), lower=None, upper=None)[source]

Create a LowerTriangularVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of the matrix.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

RealVariable

class picos.expressions.variables.RealVariable(name, shape=(1, 1), lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

A real-valued variable.

__init__(name, shape=(1, 1), lower=None, upper=None)[source]

Create a RealVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of a vector or matrix variable.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

SkewSymmetricVariable

class picos.expressions.variables.SkewSymmetricVariable(name, shape=(1, 1), lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

A skew-symmetric matrix variable.

Stored internally and passed to solvers as a skew-symmetric vectorization with only \frac{n(n-1)}{2} entries.

__init__(name, shape=(1, 1), lower=None, upper=None)[source]

Create a SkewSymmetricVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of the matrix.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

SymmetricVariable

class picos.expressions.variables.SymmetricVariable(name, shape=(1, 1), lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

A symmetric matrix variable.

Stored internally and passed to solvers as a symmetric vectorization with only \frac{n(n+1)}{2} entries.

__init__(name, shape=(1, 1), lower=None, upper=None)[source]

Create a SymmetricVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of the matrix.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

UpperTriangularVariable

class picos.expressions.variables.UpperTriangularVariable(name, shape=(1, 1), lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

An upper triangular matrix variable.

Stored internally and passed to solvers as an upper triangular vectorization with only \frac{n(n+1)}{2} entries.

__init__(name, shape=(1, 1), lower=None, upper=None)[source]

Create a UpperTriangularVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of the matrix.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

VariableType

class picos.expressions.variables.VariableType(theClass, subtype)[source]

Bases: picos.containers.DetailedType

The detailed type of a variable for predicting reformulation outcomes.

Data

picos.expressions.variables.CONTINUOUS_VARTYPES

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

picos.expressions.variables.INTEGRALITY_ABS_TOL

Absolute integrality tolerance for integral and binary variables.