picos.tools¶
Backwards compatibility version of an older module.
Outline¶
Functions¶
Legacy shorthand for |
|
Return a Python range mirroring the given integer sequence. |
|
Legacy shorthand for |
|
Form a diagonal matrix from the column-major vectorization of |
|
Extract the diagonal of |
|
Evaluate all values of a dictionary. |
|
Denote the exponential. |
|
Shorthand for |
|
Legacy shorthand for |
|
Shorthand for |
|
Create a |
|
Denote the kronecker product. |
|
Legacy shorthand for |
|
Wrapper for |
|
Wrapper for |
|
Denote the natural logarithm. |
|
Legacy shorthand for |
|
Shorthand for |
|
Create a constant or a list or dict or tuple thereof. |
|
Legacy shorthand for |
|
Find a string template for the given (algebraic) strings. |
|
Legacy wrapper around |
|
Create a standard simplex of radius |
|
Sum PICOS expressions and give the result a meaningful description. |
|
Wrapper for |
|
Wrapper for |
|
Wrapper for |
|
Wrapper for |
|
Shorthand for |
|
Denote the trace of a square matrix. |
|
Legacy shorthand for |
|
Create a truncated simplex of radius |
Data¶
Functions¶
ball¶
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
tolen(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¶
diag¶
diag_vect¶
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.
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 sectionsCON
andPSDCON
.- Returns
A tuple
(P, x, X, params)
whereP
is the imported picosProblem
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, andparams
is a dictionary containing PICOS cosntants used to define the problem. Indexing is with respect to the blocks of variables as defined in the sectionsVAR
andCON
of the file.
kron¶
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
andeigenvalues = 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
andeigenvalues = 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>
logsumexp¶
new_param¶
norm¶
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¶
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
andeigenvalues = 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
andeigenvalues = 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
andeigenvalues = 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
andeigenvalues = 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
.
tracepow¶
-
picos.tools.
tracepow
(exp, num=1, denom=1, coef=None)[source]¶ Legacy shorthand for
PowerTrace
.Deprecated since version 2.0: Use
PowerTrace
instead.