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.
- 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.
- picos.expressions.data.convert_operands(sameShape=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.
- Parameters
sameShape (bool) – Both operands must have the exact same shape.
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.
- 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.cvx2np(A, reshape=None)[source]¶
Convert a CVXOPT (sparse) matrix to a NumPy matrix.
- Parameters
- Returns
Converted
NumPy matrix
.
- 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
andB
, it is sufficient that one of the two tolerances,absTol
orrelTol
, is satisfied.
- 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_hpsd
.
- picos.expressions.data.cvxopt_hpsd(matrix)[source]¶
Whether the given CVXOPT matrix is hermitian positive semidefinite.
Uses
RELATIVE_HERMITIANNESS_TOLERANCE
andRELATIVE_SEMIDEFINITENESS_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.left_kronecker_I(A, k, reshape=None, preT=False, postT=False)[source]¶
Return for a CVXOPT (sparse) matrix .
In other words, if is a CVXOPT (sparse) matrix, returns a CVXOPT sparse block matrix with all blocks of size , the diagonal blocks (horizontal block index equal to vertical block index) equal to , and all other blocks zero.
- Parameters
- Returns
If is dense and , a
CVXOPT dense matrix
, otherwise aCVXOPT 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
ornumpy.matrix
.A CVXOPT matrix:
cvxopt.matrix
orcvxopt.spmatrix
.A constant PICOS expression:
AffineExpression
orComplexAffineExpression
.A flat
tuple
orlist
containing scalars or arange
, all representing a column vector.A nested
tuple
orlist
containing scalars. The outer level represents rows and the inner level represents the rows’ entries. Allows you to define a 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 matrix as above:
A = '''1 2 3 4 5 6'''
An algebraic string description:
"|a|"
A matrix with all entries equal to .
"|a|(m,n)"
A matrix with all entries equal to .
"e_i,j(m,n)"
A matrix with a at , indexed from to .
"e_i(m,n)"
A matrix with a single on the -th coordinate, indexed from in column-major order.
"I"
The identity matrix.
"I(n)"
The identiy matrix.
"a…"
The matrix given by
"…"
but multiplied by .
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
orlist
or arange
) is interpreted as a row vector if the target shape is of the form(None, n)
with , 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 isNone
, 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 isNone
, then the output type is chosen based on the input data.sparse (bool or None) – If
True
, a sparse matrix is returned. IfFalse
, a dense matrix is returned. IfNone
, it depends on the sparsity pattern of the input data. If the typecode argument is'i'
, then a value ofTrue
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. IfFalse
, 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 containsNone
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
withsparse = 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
- picos.expressions.data.load_sparse_data(value, shape=None, typecode=None, alwaysCopy=True)[source]¶
See
load_data
withsparse = True
.
- picos.expressions.data.make_fraction(p, denominator_limit)[source]¶
Convert a float to a limited precision fraction.
- Parameters
- Returns tuple
A quadruple
(num, den, pNew, pStr)
withpNew
the limited precision version of ,pStr
a string representation of the fraction, andnum
andden
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 for a CVXOPT (sparse) matrix .
- Parameters
- Returns
If is dense and , a
CVXOPT dense matrix
, otherwise aCVXOPT sparse matrix
.
- picos.expressions.data.should_be_sparse(shape, numNonZero)[source]¶
Decide whether a matrix is considered sparse.
- picos.expressions.data.sparse_quadruple(A, reshape=None, preT=False, postT=False)[source]¶
Return a sparse representation of the given CVXOPT (sparse) matrix.
- 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 amutable
,expression
orProblem
, or a (nested)list
,tuple
ordict
thereof.sparse – If
None
, retrieved multidimensional values can be returned as either CVXOPTsparse
ordense
matrices, whichever PICOS stores internally. IfTrue
orFalse
, multidimensional values are always returned as sparse or dense types, respectively.numpy (bool) – If
True
, retrieved multidimensional values are returned as a NumPyndarray
instead of a CVXOPT type. May not be set in combination withsparse=True
.
- Returns
An object of the same (nested) structure as
obj
, with every occurence of any object with avalue
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 byload_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