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.BiaffineExpression.partial_trace`.
`partial_transpose`	See `expressions.BiaffineExpression.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$ .

Data¶

builtin_sum

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

lst (list or tuple or ComplexAffineExpression) – A list of ComplexAffineExpression, or a single affine expression whose elements shall be summed.
it – DEPRECATED
indices – DEPRECATED

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.