picos.valuable

Common interface for objects that can have a numeric value.

Exceptions

exception picos.valuable.NotValued[source]

Bases: RuntimeError

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

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

Classes

class picos.valuable.Valuable[source]

Bases: ABC

Abstract base class for objects that can have a numeric value.

This is used by all algebraic expressions through their Expression base class as well as by Objective and, referencing the latter, by Problem instances.

__array__(dtype=None)[source]

Return the value as a NumPy array.

__complex__()[source]

Cast the value to a complex.

__float__()[source]

Cast the value to a float.

__index__()[source]

Propose the value as an index.

__int__()[source]

Cast the value to an int.

__round__(ndigits=None)[source]

Round the value to a certain precision.

property np

Value of the object as a NumPy type, or None.

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

Returns

A one- or two-dimensional numpy.ndarray, if the value is a vector or a matrix, respectively, or a NumPy scalar type such as numpy.float64, if the value is a scalar, or None, if the value is not defined.

Distinction

  • Like value and np2d, an undefined value is returned as None.

  • Unlike value, scalars are returned as NumPy scalar types as opposed to Python builtin scalar types while vectors and matrices are returned as NumPy arrays as opposed to CVXOPT matrices.

  • Unlike np2d, scalars are returned as NumPy scalar types and vectors are returned as NumPy one-dimensional arrays as opposed to always returning two-dimensional arrays.

Example

>>> from picos import ComplexVariable
>>> Z = ComplexVariable("Z", (3, 3))
>>> Z.value = [i + i*1j for i in range(9)]

Proper matrices are return as 2D arrays:

>>> Z.value  # CVXOPT matrix.
<3x3 matrix, tc='z'>
>>> Z.np  # NumPy 2D array.
array([[0.+0.j, 3.+3.j, 6.+6.j],
       [1.+1.j, 4.+4.j, 7.+7.j],
       [2.+2.j, 5.+5.j, 8.+8.j]])

Both row and column vectors are returned as 1D arrays:

>>> z = Z[:,0]  # First column of Z.
>>> z.value.size  # CVXOPT column vector.
(3, 1)
>>> z.T.value.size  # CVXOPT row vector.
(1, 3)
>>> z.value == z.T.value
False
>>> z.np.shape  # NumPy 1D array.
(3,)
>>> z.T.np.shape  # Same array.
(3,)
>>> from numpy import array_equal
>>> array_equal(z.np, z.T.np)
True

Scalars are returned as NumPy types:

>>> u = Z[0,0]  # First element of Z.
>>> type(u.value)  # Python scalar.
<class 'complex'>
>>> type(u.np)  # NumPy scalar. 
<class 'numpy.complex128'>

Undefined values are returned as None:

>>> del Z.value
>>> Z.value is Z.np is None
True
property np2d

Value of the object as a 2D NumPy array, or None.

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

Returns

The value as a two-dimensional numpy.ndarray, or None, if the value is not defined.

Distinction

  • Like np, values are returned as NumPy types or None.

  • Unlike np, both scalar and vectorial values are returned as two-dimensional arrays. In particular, row and column vectors are distinguished.

property safe_value

Value of the object, if defined.

Refer to value for when it is defined.

Returns

The value as a Python scalar or CVXOPT matrix.

Raises

NotValued – If the value is not defined.

Distinction

  • Unlike value, an undefined value raises an exception.

  • Like value, scalars are returned as scalar types.

property safe_value_as_matrix

Value of the object as a CVXOPT matrix type, if defined.

Refer to value for when it is defined.

Returns

The value as a CVXOPT matrix.

Raises

NotValued – If the value is not defined.

Distinction

  • Unlike value, an undefined value raises an exception.

  • Unlike value, scalars are returned as 1 \times 1 matrices.

property sp

Value as a ScipPy sparse matrix or a NumPy 2D array or None.

If PICOS stores the value internally as a CVXOPT sparse matrix, or equivalently if value_as_matrix returns an instance of cvxopt.spmatrix, then this returns the value as a SciPy sparse matrix in CSC format. Otherwise, this property is equivalent to np2d and returns a two-dimensional NumPy array, or None, if the value is undefined.

Example

>>> import picos, cvxopt
>>> X = picos.RealVariable("X", (3, 3))
>>> X.value = cvxopt.spdiag([1, 2, 3])  # Stored as a sparse matrix.
>>> type(X.value)
<class 'cvxopt.base.spmatrix'>
>>> type(X.sp)
<class 'scipy.sparse._csc.csc_matrix'>
>>> X.value = range(9)  # Stored as a dense matrix.
>>> type(X.value)
<class 'cvxopt.base.matrix'>
>>> type(X.sp)
<class 'numpy.ndarray'>
property value

Value of the object, or None.

For an expression, it is defined if the expression is constant or if all mutables involved in the expression are valued. Mutables can be valued directly by writing to their value attribute. Variables are also valued by PICOS when an optimization solution is found.

Some expressions can also be valued directly if PICOS can find a minimal norm mutable 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.

If you prefer the value as a NumPy, use np instead.

Returns

The value as a Python scalar or CVXOPT matrix, or None if it is not defined.

Distinction

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]
property value_as_matrix

Value of the object as a CVXOPT matrix type, or None.

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

Returns

The value as a CVXOPT matrix, or None if it is not defined.

Distinction

  • Like value, an undefined value is returned as None.

  • Unlike value, scalars are returned as 1 \times 1 matrices.

property valued

Whether the object 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

Functions

picos.valuable.patch_scipy_array_priority()[source]

Monkey-patch scipy.sparse to make it respect __array_priority__.

This works around https://github.com/scipy/scipy/issues/4819 and is inspired by CVXPY’s scipy_wrapper.py.