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
, andnp2d
attributes do not raise this exception, but returnNone
instead.
Classes
- class picos.valuable.Valuable[source]¶
Bases:
abc.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 byObjective
and, referencing the latter, byProblem
instances.- __array__(dtype=None)[source]¶
Return the value as a
NumPy array
.
- property np¶
Value of the object as a NumPy type, or
None
.Refer to
value
for when it is defined (notNone
).- Returns
A one- or two-dimensional
numpy.ndarray
, if the value is a vector or a matrix, respectively, or a NumPy scalar type such asnumpy.float64
, if the value is a scalar, orNone
, if the value is not defined.- Distinction
Like
value
andnp2d
, an undefined value is returned asNone
.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 (notNone
).- Returns
The value as a two-dimensional
numpy.ndarray
, orNone
, if the value is not defined.- Distinction
- 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
- 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
- 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 ofcvxopt.spmatrix
, then this returns the value as aSciPy sparse matrix in CSC format
. Otherwise, this property is equivalent tonp2d
and returns a two-dimensional NumPy array, orNone
, 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
Unlike
safe_value
andsafe_value_as_matrix
, an undefined value is returned asNone
.Unlike
value_as_matrix
andsafe_value_as_matrix
, scalars are returned as scalar types.For uncertain expressions, see also
worst_case_value
.
- 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 (notNone
).- Returns
The value as a CVXOPT matrix, or
None
if it is not defined.- Distinction
- property valued¶
Whether the object is valued.
Note
Querying this attribute is not faster than immediately querying
value
and checking whether it isNone
. 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.