picos.expressions.data¶

Functions to load and work with raw numeric data.

Functions

picos.expressions.data.blend_shapes(baseShape, defaultShape)[source]¶

Replace wildcards in one shape with entries of the other.

Parameters

baseShape (tuple(int or None)) – Primary shape, usually with wildcards.
defaultShape (tuple(int or None)) – Secondary shape with fallback entries.

picos.expressions.data.convert_and_refine_arguments(*which, refine=True, allowNone=False)[source]¶

Convert selected function arguments to PICOS expressions.

If the selected arguments are already PICOS expressions, they are refined unless disabled. If they are not already PICOS expressions, an attempt is made to load them as constant expressions.

Decorator guarantee

All specified arguments are refined PICOS expressions when the function is exectued.

Parameters

refine (bool) – Whether to refine arguments that are already PICOS expressions.
allowNone (bool) – Whether None is passed through to the function.

picos.expressions.data.convert_operands(sameShape=False, diagBroadcast=False, scalarLHS=False, scalarRHS=False, rMatMul=False, lMatMul=False, horiCat=False, vertCat=False, allowNone=False)[source]¶

Convert binary operator operands to PICOS expressions.

A decorator for a binary operator that converts any operand that is not already a PICOS expression or set into a constant one that fulfills the given shape requirements, if possible. See load_data for broadcasting and reshaping rules that apply to raw data.

If both operands are already PICOS expressions and at least one of them is an affine expression, there is a limited set of broadcasting rules to fix a detected shape mismatch. If this does not succeed, an exception is raised. If no operand is affine, the operation is performed even if shapes do not match. The operation is responsible for dealing with this case.

If either operand is a PICOS set, no broadcasting or reshaping is applied as set instances have, in general, variable dimensionality. If a set type can not have arbitrary dimensions, then it must validate the element’s shape on its own. In particular, no shape requirement may be given when this decorator is used on a set method.

Decorator guarantee

This decorator guarantees to the binary operator using it that only PICOS expression or set types will be passed as operands and that any affine expression already has the proper shape for the operation, based on the decorator arguments.

Broadcasting rules for affine expressions

Currently, only scalar affine expressions are broadcasted to the next smallest matching shape. This is more limited than the broadcasting behavior when one of the operands is raw data, but it ensures a symmetric behavior in case both operands are affine. An exception is the case of diagBroadcast, where a vector affine expression may be extended to a matrix.

Parameters

sameShape (bool) – Both operands must have the exact same shape.
diagBroadcast (bool) – Both operands must be square matrices of same shape. If one operand is a square matrix and the other is a scalar or vector, the latter is put into the diagonal of a square matrix.
scalarLHS (bool) – The left hand side operand must be scalar.
scalarRHS (bool) – The right hand side operand must be scalar.
rMatMul (bool) – The operation has the shape requirements of normal matrix multiplication with the second operand on the right side.
lMatMul (bool) – The operation has the shape requirements of reversed matrix multiplication with the second operand on the left side.
horiCat (bool) – The operation has the shape requirements of horizontal matrix concatenation.
vertCat (bool) – The operation has the shape requirements of vertical matrix concatenation.
allowNone (bool) – An operand of None is passed as-is.

Raises

TypeError – If matching shapes cannot be produced despite one of the operands being raw data or an affine expression.

Note

Matrix multiplication includes scalar by matrix multiplication, so either operand may remain a scalar.

picos.expressions.data.cvx2csc(A)[source]¶: Convert a CVXOPT matrix to a SciPy sparse matrix in CSC format.

picos.expressions.data.cvx2csr(A)[source]¶: Convert a CVXOPT matrix to a SciPy sparse matrix in CSR format.

picos.expressions.data.cvx2np(A, reshape=None)[source]¶

Convert a CVXOPT (sparse) matrix to a NumPy two-dimensional array.

Parameters

A – The CVXOPT dense or sparse matrix to convert.
reshape (bool) – Optional new shape for the converted matrix.

Returns

Converted NumPy array.

picos.expressions.data.cvxopt_equals(A, B, absTol=None, relTol=None)[source]¶

Whether two CVXOPT (sparse) matrices are numerically equal or close.

For every common entry of A and B, it is sufficient that one of the two tolerances, absTol or relTol, is satisfied.

Parameters

absTol (float) – Maximum allowed entrywise absolute difference.
relTol (float) – Maximum allowed entrywise quotient of absolute difference at the entry divided by the largest absolute value of any entry in both matrices.

picos.expressions.data.cvxopt_hcat(matrices)[source]¶

Concatenate the given CVXOPT (sparse) matrices horizontally.

The resulting matrix is sparse if any input matrix is sparse.

Parameters: matrices (list) – A list of CVXOPT (sparse) matrices.

picos.expressions.data.cvxopt_hpd(matrix)[source]¶

Whether the given CVXOPT matrix is hermitian positive definite.

Uses RELATIVE_HERMITIANNESS_TOLERANCE.

See also cvxopt_hpd.

Warning

The semidefiniteness tolerance allows negative, near-zero eigenvalues.

picos.expressions.data.cvxopt_inverse(matrix)[source]¶

Return the inverse of the given CVXOPT matrix.

Raises: ValueError – If the matrix is not invertible.

picos.expressions.data.cvxopt_maxdiff(A, B)[source]¶

Return the largest absolute difference of two (sparse) CVXOPT matrices.

Raises: TypeError – If the matrices are not of the same shape.

picos.expressions.data.cvxopt_principal_root(matrix)[source]¶

Return the principal square root of a symmetric positive semidef. matrix.

Given a real symmetric positive (semi)definite CVXOPT input matrix, returns its unique positive (semi)definite matrix square root.

Warning

Does not validate that the input matrix is symmetric positive semidefinite and will still return a (useless) matrix if it is not.

picos.expressions.data.cvxopt_vcat(matrices)[source]¶

Concatenate the given CVXOPT (sparse) matrices vertically.

The resulting matrix is sparse if any input matrix is sparse.

Parameters: matrices (list) – A list of CVXOPT (sparse) matrices.

picos.expressions.data.is_scipy_spmat(value)[source]¶: Report whether value is a SciPy sparse matrix without importing scipy.

picos.expressions.data.left_kronecker_I(A, k, reshape=None, preT=False, postT=False)[source]¶

Return $I_k \otimes A$ for a CVXOPT (sparse) matrix $A$ .

In other words, if $A$ is a $m \times n$ CVXOPT (sparse) matrix, returns a $km \times kn$ CVXOPT sparse block matrix with all blocks of size $m \times n$ , the diagonal blocks (horizontal block index equal to vertical block index) equal to $A$ , and all other blocks zero.

Parameters

reshape – If set, then $A$ is reshaped on the fly.
preT (bool) – Transpose $A$ before reshaping.
postT (bool) – Transpose $A$ after reshaping.

Returns

If $A$ is dense and $k = 1$ , a CVXOPT dense matrix, otherwise a CVXOPT sparse matrix.

picos.expressions.data.load_data(value, shape=None, typecode=None, sparse=None, alwaysCopy=True, legacy=False)[source]¶

Load a constant numeric data value as a CVXOPT (sparse) matrix.

As a user, you never need to call this manually, but you should be aware that PICOS uses this function on any raw data you supply as an operand when working with PICOS expressions. For instance, you can just add a NumPy matrix or an algebraic string such as "I" to such an expression without worrying about any conversion.

Supported data types

A NumPy matrix: numpy.ndarray or numpy.matrix.
A SciPy sparse matrix: All from scipy.sparse.
A CVXOPT matrix: cvxopt.matrix or cvxopt.spmatrix.
A constant PICOS expression: AffineExpression or ComplexAffineExpression.
A Python scalar: int, float or complex.
A flat tuple or list containing scalars or a range, all representing a column vector.
A nested tuple or list containing scalars. The outer level represents rows and the inner level represents the rows’ entries. Allows you to define a $2 \times 3$ matrix like this:
```
A = [[1, 2, 3],
     [4, 5, 6]]
```
A verbatim string description, with rows separated by newline and columns separated by whitespace. The same $2 \times 3$ matrix as above:
```
A = '''1 2 3
       4 5 6'''
```

An algebraic string description:

`"\|a\|"`	A matrix with all entries equal to $a$ .
`"\|a\|(m,n)"`	A $m \times n$ matrix with all entries equal to $a$ .
`"e_i,j(m,n)"`	A $m \times n$ matrix with a $1$ at $(i,j)$ , indexed from $(1,1)$ to $(m,n)$ .
`"e_i(m,n)"`	A $m \times n$ matrix with a single $1$ on the $i$ -th coordinate, indexed from $1$ in column-major order.
`"I"`	The identity matrix.
`"I(n)"`	The $n \times n$ identiy matrix.
`"a…"`	The matrix given by `"…"` but multiplied by $a$ .

Different matrix operations such as addition or multiplication have different requirements with respect to the operands’ shapes. The shape of any PICOS expression involved will always be maintained. But when an operation involves both a PICOS expression and raw data, then PICOS will try to broadcast or reshape the raw data such that the operation can be performed.

Broadcasting and reshaping rules

An input vector without a second axis (for instance a non-nested tuple or list or a range) is interpreted as a row vector if the target shape is of the form (None, n) with $n > 1$ , otherwise it is interpreted as a column vector.
If the target shape is None or (None, None), then the input’s shape is maintained.
If the target shape contains None exactly once, that occurence is replaced by the respective dimensionality of the input data shape.
A scalar is copied (broadcasted) to fill the target shape.
A column (row) vector is copied horizontally (vertically) if its length matches the target row (column) count.
Reshaping from matrix to vector: A matrix is vectorized in column-major (row-major) order if the target shape is a column (row) vector whose length matches the number of matrix entries.
Reshaping from vector to matrix: A column (row) vector is treated as the column-major (row-major) vectorization of the target matrix if the former’s length matches the number of the latter’s entries.
All other combinations of input and target shape raise an exception.
When an algebraic string description specifies no shape, then the shape argument must be supplied. When both the string and the shape argument specify a shape, then they must be consistent (no broadcasting or reshaping is applied in this case).

Parameters

shape (int or tuple or list or None) – The shape of the resulting matrix. If the input data is of another shape, broadcasting or reshaping is used if possible, otherwise an exception is raised. An integer is treated as the length of a column vector. If this is None, then the target’s shape is the input’s. If only the target number of rows or columns is None, then only that quantity is chosen according to the input.
typecode (str) – The numeric type of the resulting matrix. Either 'd' (float), 'z' (complex) or 'i' (integer). If the input data is not already of this type, then it will be converted if possible. If this is not possible, then an exception is raised. If this is None, then the output type is chosen based on the input data.
sparse (bool or None) – If True, a sparse matrix is returned. If False, a dense matrix is returned. If None, it depends on the sparsity pattern of the input data. If the typecode argument is 'i', then a value of True is not allowed and the returned matrix is dense.
alwaysCopy (bool) – If True, then a copy of the input data is returned even if it already equals the output data. If False, the input value can be returned as such if it is already a CVXOPT matrix of the desired shape, typecode, and sparsity.
legacy (bool) – Be compatible with the old retrieve_matrix function. In particular, if the target shape contains None exactly once and the input data is scalar, treat this as a matrix multiplication case and return the scalar times an identity matrix of appropriate size.

Returns

A tuple whose first entry is the loaded matrix and whose second argument is a short string for representing the data within algebraic expression strings.

Example

>>> from picos.expressions.data import load_data
>>> # Data as (nested) list:
>>> load_data([1,2,3])
(<3x1 matrix, tc='i'>, '[3×1]')
>>> load_data([[1,2,3]])
(<1x3 matrix, tc='i'>, '[1×3]')
>>> A = [[1,2,3],
...      [4,5,6]]
>>> load_data(A)
(<2x3 matrix, tc='i'>, '[2×3]')
>>> # Data as string:
>>> value, string = load_data('e_14(7,2)')
>>> print(string)
[7×2:e_7,2]
>>> print(value) 
[   0        0       ]
[   0        0       ]
[   0        0       ]
[   0        0       ]
[   0        0       ]
[   0        0       ]
[   0        1.00e+00]
>>> load_data('5.3I', (2,2))
(<2x2 sparse matrix, tc='d', nnz=2>, '5.3·I')

picos.expressions.data.load_dense_data(value, shape=None, typecode=None, alwaysCopy=True)[source]¶: See load_data with sparse = False.

picos.expressions.data.load_shape(shape, squareMatrix=False, wildcards=False)[source]¶

Parse the argument as a matrix shape.

PICOS uses this function whenever you supply a shape parameter to a method.

A scalar argument is treated as the length of a column-vector. If the shape contains None, it is treated as a wildcard (any dimensionality).

Parameters

squareMatrix (bool) – If True, a scalar argument is treated as the side/diagonal length of a square matrix, and any other argument is validated to be square. If False, a scalar argument is treated as the length of a column vector.
wildcards (bool) – Whether the wildcard token None is allowed.

picos.expressions.data.load_sparse_data(value, shape=None, typecode=None, alwaysCopy=True)[source]¶: See load_data with sparse = True.

picos.expressions.data.make_fraction(p, denominator_limit)[source]¶

Convert a float $p$ to a limited precision fraction.

Parameters

p (float) – The float to convert, may be positive or negative infinity.
denominator_limit (int) – The largest allowed denominator.

Returns tuple

A quadruple (num, den, pNew, pStr) with pNew the limited precision version of $p$ , pStr a string representation of the fraction, and num and den the numerator and the denominator of the fraction, respectively.

picos.expressions.data.right_kronecker_I(A, k, reshape=None, preT=False, postT=False)[source]¶

Return $A \otimes I_k$ for a CVXOPT (sparse) matrix $A$ .

Parameters

reshape – If set, then $A$ is reshaped on the fly.
preT (bool) – Transpose $A$ before reshaping.
postT (bool) – Transpose $A$ after reshaping.

Returns

If $A$ is dense and $k = 1$ , a CVXOPT dense matrix, otherwise a CVXOPT sparse matrix.

picos.expressions.data.should_be_sparse(shape, numNonZero)[source]¶

Decide whether a matrix is considered sparse.

Parameters

shape (tuple(int)) – The shape of the matrix in question.
numNonZero (int) – Number of non-zero elements of the matrix.

picos.expressions.data.sp2cvx(A)[source]¶: Convert a SciPy sparse matrix to a CVXOPT sparse matrix.

picos.expressions.data.sparse_quadruple(A, reshape=None, preT=False, postT=False)[source]¶

Return a sparse representation of the given CVXOPT (sparse) matrix.

Parameters

reshape – If set, then $A$ is reshaped on the fly.
preT (bool) – Transpose $A$ before reshaping.
postT (bool) – Transpose $A$ after reshaping.

Returns

A quadruple of values, row indices, column indices, and shape.

picos.expressions.data.value(obj, sparse=None, numpy=False)[source]¶

Convert (nested) PICOS objects to their current value.

Parameters

obj – Either a single (PICOS) object that has a value attribute, such as a mutable, expression or Problem, or a (nested) list, tuple or dict thereof.
sparse – If None, retrieved multidimensional values can be returned as either CVXOPT sparse or dense matrices, whichever PICOS stores internally. If True or False, multidimensional values are always returned as sparse or dense types, respectively.
numpy (bool) – If True, retrieved multidimensional values are returned as a NumPy ndarray instead of a CVXOPT type. May not be set in combination with sparse=True.

Returns

An object of the same (nested) structure as obj, with every occurence of any object with a value attribute replaced by that attribute’s current numeric value. In the case of dictionaries, only the dictionary values will be converted.

Raises

TypeError – If some object with a value attribute has a value that cannot be converted to a matrix by load_data. This can only happen if the object in question is not a PICOS object.

Example

>>> from picos import RealVariable, value
>>> from pprint import pprint
>>> x = {key: RealVariable(key) for key in ("foo", "bar")}
>>> x["foo"].value = 2
>>> x["bar"].value = 3
>>> pprint(value(x))
{'bar': 3.0, 'foo': 2.0}

Objects

picos.expressions.data.TOLERANCE¶

Maximum entrywise absolute deviation allowed for numeric equality checks.

Default value

1e-06

picos.expressions.data.cvxopt_K[source]¶

The commutation matrix $K_{(m,n)}$ as a CVXOPT sparse matrix.

Default value

<functools._lru_cache_wrapper object at 0x7f4ee180fab0>

Fork me on GitLab