picos.tools

Backwards compatibility version of an older module.

Outline

Functions

ball

Legacy shorthand for Ball.

detect_range

Return a Python range mirroring the given integer sequence.

detrootn

Legacy shorthand for DetRootN.

diag

Form a diagonal matrix from the column-major vectorization of x.

diag_vect

Extract the diagonal of x as a column vector.

eval_dict

Evaluate all values of a dictionary.

exp

Denote the exponential.

expcone

Shorthand for ExponentialCone.

flow_Constraint

Legacy shorthand for FlowConstraint.

geomean

Shorthand for GeometricMean.

import_cbf

Create a Problem from a CBF file.

kron

Denote the kronecker product.

kullback_leibler

Legacy shorthand for NegativeEntropy.

lambda_max

Wrapper for SumExtremes.

lambda_min

Wrapper for SumExtremes.

log

Denote the natural logarithm.

logsumexp

Legacy shorthand for LogSumExp.

lse

Shorthand for LogSumExp.

new_param

Create a constant or a list or dict or tuple thereof.

norm

Legacy shorthand for Norm.

parameterized_string

Find a string template for the given (algebraic) strings.

partial_trace

See expressions.ComplexAffineExpression.partial_trace.

partial_transpose

See expressions.ComplexAffineExpression.partial_transpose.

retrieve_matrix

Legacy wrapper around load_data.

simplex

Create a standard simplex of radius \gamma.

sum

Sum PICOS expressions and give the result a meaningful description.

sum_k_largest

Wrapper for SumExtremes.

sum_k_largest_lambda

Wrapper for SumExtremes.

sum_k_smallest

Wrapper for SumExtremes.

sum_k_smallest_lambda

Wrapper for SumExtremes.

sumexp

Shorthand for SumExponentials.

trace

Denote the trace of a square matrix.

tracepow

Legacy shorthand for PowerTrace.

truncated_simplex

Create a truncated simplex of radius \gamma.

Functions

ball

picos.tools.ball(*args, **kwargs)

Legacy shorthand for Ball.

Deprecated since version 2.0: Use Ball instead.

detect_range

picos.tools.detect_range(sequence, asQuadruple=False, asStringTemplate=False, shortString=False)[source]

Return a Python range mirroring the given integer sequence.

Parameters
  • sequence – An integer sequence that can be mirrored by a Python range.

  • asQuadruple (bool) – Whether to return a quadruple with factor, inner shift, outer shift, and length, formally (a, i, o, n) such that [a*(x+i)+o for x in range(n)] mirrors the input sequence.

  • asStringTemplate (bool) – Whether to return a format string that, if instanciated with numbers from 0 to len(sequence) - 1, yields math expression strings that describe the input sequence members.

  • shortString (bool) – Whether to return condensed string templates that are designed to be instanciated with an index character string. Requires asStringTemplate to be True.

Raises
  • TypeError – If the input is not an integer sequence.

  • ValueError – If the input cannot be mirrored by a Python range.

Returns

A range object, a quadruple of numbers, or a format string.

Example

>>> from picos.formatting import detect_range as dr
>>> R = range(7,30,5)
>>> S = list(R)
>>> S
[7, 12, 17, 22, 27]
>>> # By default, returns a matching range object:
>>> dr(S)
range(7, 28, 5)
>>> dr(S) == R
True
>>> # Sequence elements can also be decomposed w.r.t. range(len(S)):
>>> a, i, o, n = dr(S, asQuadruple=True)
>>> [a*(x+i)+o for x in range(n)] == S
True
>>> # The same decomposition can be returned in a string representation:
>>> dr(S, asStringTemplate=True)
'5·({} + 1) + 2'
>>> # Short string representations are designed to accept index names:
>>> dr(S, asStringTemplate=True, shortString=True).format("i")
'5(i+1)+2'
>>> dr(range(0,100,5), asStringTemplate=True, shortString=True).format("i")
'5i'
>>> dr(range(10,100), asStringTemplate=True, shortString=True).format("i")
'i+10'
Example

>>> # This works with decreasing ranges as well.
>>> R2 = range(10,4,-2)
>>> S2 = list(R2)
>>> S2
[10, 8, 6]
>>> dr(S2)
range(10, 5, -2)
>>> dr(S2) == R2
True
>>> a, i, o, n = dr(S2, asQuadruple=True)
>>> [a*(x+i)+o for x in range(n)] == S2
True
>>> T = dr(S2, asStringTemplate=True, shortString=True)
>>> [T.format(i) for i in range(len(S2))]
['-2(0-5)', '-2(1-5)', '-2(2-5)']

detrootn

picos.tools.detrootn(*args, **kwargs)

Legacy shorthand for DetRootN.

Deprecated since version 2.0: Use DetRootN instead.

diag

picos.tools.diag(x, n=1)[source]

Form a diagonal matrix from the column-major vectorization of x.

If n \neq 1, then the vectorization is repeated n times.

diag_vect

picos.tools.diag_vect(x)[source]

Extract the diagonal of x as a column vector.

Deprecated since version 2.0: Use maindiag instead.

eval_dict

picos.tools.eval_dict(dict_of_variables)[source]

Evaluate all values of a dictionary.

Parameters

dict_of_variables (dict) – A dictionary mapping arbitrary keys to PICOS objects that have a value attribute, such as variables.

Returns

Another dictionary with the original dicitonary’s values replaced by the value of their value attribute.

Deprecated since version 2.0: Write ‘{k: v.value for k, v in x.items()}’ instead.

exp

picos.tools.exp(x)[source]

Denote the exponential.

expcone

picos.tools.expcone(*args, **kwargs)

Shorthand for ExponentialCone.

flow_Constraint

picos.tools.flow_Constraint(*args, **kwargs)[source]

Legacy shorthand for FlowConstraint.

Deprecated since version 2.0: Use FlowConstraint instead.

geomean

picos.tools.geomean(*args, **kwargs)

Shorthand for GeometricMean.

import_cbf

picos.tools.import_cbf(filename)[source]

Create a Problem from a CBF file.

The created problem contains one (multidimensional) variable for each cone specified in the section VAR of the .cbf file, and one (multidimmensional) constraint for each cone specified in the sections CON and PSDCON.

Returns

A tuple (P, x, X, params) where

  • P is the imported picos Problem object,

  • x is a list of multidimensional variables representing the scalar variables found in the file,

  • X is a list of symmetric variables representing the positive semidefinite variables found in the file, and

  • params is a dictionary containing PICOS cosntants used to define the problem. Indexing is with respect to the blocks of variables as defined in the sections VAR and CON of the file.

kron

picos.tools.kron(x, y)[source]

Denote the kronecker product.

Note that with Python 3, you can just write x @ y.

kullback_leibler

picos.tools.kullback_leibler(*args, **kwargs)

Legacy shorthand for NegativeEntropy.

Deprecated since version 2.0: Use kldiv instead.

lambda_max

picos.tools.lambda_max(x)[source]

Wrapper for SumExtremes.

Sets k = 1, largest = True and eigenvalues = True.

Example

>>> from picos import SymmetricVariable, lambda_max
>>> X = SymmetricVariable("X", 5)
>>> lambda_max(X)
<Largest Eigenvalue: λ_max(X)>
>>> lambda_max(X) <= 2
<Largest Eigenvalue Constraint: λ_max(X) ≤ 2>

lambda_min

picos.tools.lambda_min(x)[source]

Wrapper for SumExtremes.

Sets k = 1, largest = False and eigenvalues = True.

Example

>>> from picos import SymmetricVariable, lambda_min
>>> X = SymmetricVariable("X", 5)
>>> lambda_min(X)
<Smallest Eigenvalue: λ_min(X)>
>>> lambda_min(X) >= 2
<Smallest Eigenvalue Constraint: λ_min(X) ≥ 2>

log

picos.tools.log(x)[source]

Denote the natural logarithm.

logsumexp

picos.tools.logsumexp(*args, **kwargs)

Legacy shorthand for LogSumExp.

Deprecated since version 2.0: Use lse instead.

lse

picos.tools.lse(*args, **kwargs)

Shorthand for LogSumExp.

new_param

picos.tools.new_param(name, value)[source]

Create a constant or a list or dict or tuple thereof.

Deprecated since version 2.0: Use Constant instead.

norm

picos.tools.norm(*args, **kwargs)

Legacy shorthand for Norm.

Deprecated since version 2.0: Use Norm instead.

parameterized_string

picos.tools.parameterized_string(strings, replace='-?\\d+', context='\\W', placeholders='ijklpqr', fallback='?')[source]

Find a string template for the given (algebraic) strings.

Given a list of strings with similar structure, finds a single string with placeholders and an expression that denotes how to instantiate the placeholders in order to obtain each string in the list.

The function is designed to take a number of symbolic string representations of math expressions that differ only with respect to indices.

Parameters
  • strings (list) – The list of strings to compare.

  • replace (str) – A regular expression describing the bits to replace with placeholders.

  • context (str) – A regular expression describing context characters that need to be present next to the bits to be replaced with placeholders.

  • placeholders – An iterable of placeholder strings. Usually a string, so that each of its characters becomes a placeholder.

  • fallback (str) – A fallback placeholder string, if the given placeholders are not sufficient.

Returns

A tuple of two strings, the first being the template string and the second being a description of the placeholders used.

Example

>>> from picos.formatting import parameterized_string as ps
>>> ps(["A[{}]".format(i) for i in range(5, 31)])
('A[i+5]', 'i ∈ [0…25]')
>>> ps(["A[{}]".format(i) for i in range(5, 31, 5)])
('A[5(i+1)]', 'i ∈ [0…5]')
>>> S=["A[0]·B[2]·C[3]·D[5]·F[0]",
...    "A[1]·B[1]·C[6]·D[6]·F[0]",
...    "A[2]·B[0]·C[9]·D[9]·F[0]"]
>>> ps(S)
('A[i]·B[-(i-2)]·C[3(i+1)]·D[j]·F[0]', '(i,j) ∈ zip([0…2],[5,6,9])')

partial_trace

picos.tools.partial_trace(x, subsystems=0, dimensions=2, k=None, dim=None)[source]

See expressions.ComplexAffineExpression.partial_trace.

The parameters k and dim are for backwards compatibility.

partial_transpose

picos.tools.partial_transpose(x, subsystems=0, dimensions=2, k=None, dim=None)[source]

See expressions.ComplexAffineExpression.partial_transpose.

The parameters k and dim are for backwards compatibility.

retrieve_matrix

picos.tools.retrieve_matrix(mat, exSize=None)[source]

Legacy wrapper around load_data.

Deprecated since version 2.0: Use picos.expressions.data.load_data instead.

simplex

picos.tools.simplex(gamma)[source]

Create a standard simplex of radius \gamma.

Deprecated since version 2.0: Use Simplex instead.

sum

picos.tools.sum(lst, it=None, indices=None)[source]

Sum PICOS expressions and give the result a meaningful description.

This is a replacement for Python’s sum that produces sensible string representations when summing PICOS expressions.

Parameters
Example

>>> import builtins
>>> import picos
>>> x = picos.RealVariable("x", 5)
>>> e = [x[i]*x[i+1] for i in range(len(x) - 1)]
>>> builtins.sum(e)
<Quadratic Expression: x[0]·x[1] + x[1]·x[2] + x[2]·x[3] + x[3]·x[4]>
>>> picos.sum(e)
<Quadratic Expression: ∑(x[i]·x[i+1] : i ∈ [0…3])>
>>> picos.sum(x)  # The same as (x|1).
<1×1 Real Linear Expression: ∑(x)>

sum_k_largest

picos.tools.sum_k_largest(x, k)[source]

Wrapper for SumExtremes.

Sets largest = True and eigenvalues = False.

Example

>>> from picos import RealVariable, sum_k_largest
>>> x = RealVariable("x", 5)
>>> sum_k_largest(x, 2)
<Sum of Largest Elements: sum_2_largest(x)>
>>> sum_k_largest(x, 2) <= 2
<Sum of Largest Elements Constraint: sum_2_largest(x) ≤ 2>

sum_k_largest_lambda

picos.tools.sum_k_largest_lambda(x, k)[source]

Wrapper for SumExtremes.

Sets largest = True and eigenvalues = True.

Example

>>> from picos import SymmetricVariable, sum_k_largest_lambda
>>> X = SymmetricVariable("X", 5)
>>> sum_k_largest_lambda(X, 2)
<Sum of Largest Eigenvalues: sum_2_largest_λ(X)>
>>> sum_k_largest_lambda(X, 2) <= 2
<Sum of Largest Eigenvalues Constraint: sum_2_largest_λ(X) ≤ 2>

sum_k_smallest

picos.tools.sum_k_smallest(x, k)[source]

Wrapper for SumExtremes.

Sets largest = False and eigenvalues = False.

Example

>>> from picos import RealVariable, sum_k_smallest
>>> x = RealVariable("x", 5)
>>> sum_k_smallest(x, 2)
<Sum of Smallest Elements: sum_2_smallest(x)>
>>> sum_k_smallest(x, 2) >= 2
<Sum of Smallest Elements Constraint: sum_2_smallest(x) ≥ 2>

sum_k_smallest_lambda

picos.tools.sum_k_smallest_lambda(x, k)[source]

Wrapper for SumExtremes.

Sets largest = False and eigenvalues = True.

Example

>>> from picos import SymmetricVariable, sum_k_smallest_lambda
>>> X = SymmetricVariable("X", 5)
>>> sum_k_smallest_lambda(X, 2)
<Sum of Smallest Eigenvalues: sum_2_smallest_λ(X)>
>>> sum_k_smallest_lambda(X, 2) >= 2
<Sum of Smallest Eigenvalues Constraint: sum_2_smallest_λ(X) ≥ 2>

sumexp

picos.tools.sumexp(*args, **kwargs)

Shorthand for SumExponentials.

trace

picos.tools.trace(x)[source]

Denote the trace of a square matrix.

tracepow

picos.tools.tracepow(exp, num=1, denom=1, coef=None)[source]

Legacy shorthand for PowerTrace.

Deprecated since version 2.0: Use PowerTrace instead.

truncated_simplex

picos.tools.truncated_simplex(gamma, sym=False)[source]

Create a truncated simplex of radius \gamma.

Deprecated since version 2.0: Use Simplex instead.

Data

picos.tools.builtin_sum

Return the sum of a ‘start’ value (default: 0) plus an iterable of numbers

When the iterable is empty, return the start value. This function is intended specifically for use with numeric values and may reject non-numeric types.