picos.expressions.data

Functions to load and work with raw numeric data.

Outline

Functions

blend_shapes

Replace wildcards in one shape with entries of the other.

convert_and_refine_arguments

Convert selected function arguments to PICOS expressions.

convert_operands

Convert binary operator operands to PICOS expressions.

cvx2np

Convert a CVXOPT (sparse) matrix to a NumPy matrix.

cvxopt_equals

Whether two CVXOPT (sparse) matrices are numerically close.

cvxopt_hcat

Concatenate the given CVXOPT (sparse) matrices horizontally.

cvxopt_hpsd

Whether the given CVXOPT matrix is hermitian positive semidefinite.

cvxopt_maxdiff

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

cvxopt_vcat

Concatenate the given CVXOPT (sparse) matrices vertically.

left_kronecker_I

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

load_data

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

load_dense_data

See load_data with sparse = False.

load_shape

Parse the argument as a matrix shape.

load_sparse_data

See load_data with sparse = True.

make_fraction

Convert a float p to a limited precision fraction.

right_kronecker_I

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

should_be_sparse

Decide whether a matrix is considered sparse.

sparse_quadruple

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

value

Convert (nested) PICOS objects to their current value.

Functions

blend_shapes

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.

convert_and_refine_arguments

picos.expressions.data.convert_and_refine_arguments(*which, **kwargs)[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.

convert_operands

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.

  • 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.

cvx2np

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

Convert a CVXOPT (sparse) matrix to a NumPy matrix.

Parameters
  • A – The CVXOPT dense or sparse matrix to convert.

  • reshape (bool) – Optional new shape for the converted matrix.

Returns

Converted NumPy matrix.

cvxopt_equals

picos.expressions.data.cvxopt_equals(A, B, tolerance=None)[source]

Whether two CVXOPT (sparse) matrices are numerically close.

Parameters

tolerance (float) – Maximum entrywise absolute deviation allowed. Defaults to TOLERANCE.

cvxopt_hcat

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.

cvxopt_hpsd

picos.expressions.data.cvxopt_hpsd(matrix)[source]

Whether the given CVXOPT matrix is hermitian positive semidefinite.

Note that the matrix must be exactly hermitian, no tolerance is applied.

cvxopt_maxdiff

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.

cvxopt_vcat

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.

left_kronecker_I

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.

load_data

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 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')

load_dense_data

picos.expressions.data.load_dense_data(value, shape=None, typecode=None, alwaysCopy=True)[source]

See load_data with sparse = False.

load_shape

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.

load_sparse_data

picos.expressions.data.load_sparse_data(value, shape=None, typecode=None, alwaysCopy=True)[source]

See load_data with sparse = True.

make_fraction

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.

right_kronecker_I

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.

should_be_sparse

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.

sparse_quadruple

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.

value

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 variable, 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}

Data

picos.expressions.data.TOLERANCE

Maximum entrywise absolute deviation allowed for numeric equality checks.