picos.expressions.algebra¶
Implements functions that create or modify algebraic expressions.
Outline¶
Functions¶
Legacy shorthand for |
|
Create an affine block matrix expression. |
|
Legacy shorthand for |
|
Form a diagonal matrix from the column-major vectorization of |
|
Extract the diagonal of |
|
Denote the exponential. |
|
Shorthand for |
|
Legacy shorthand for |
|
Shorthand for |
|
Shorthand for |
|
Denote the kronecker product. |
|
Legacy shorthand for |
|
Wrapper for |
|
Wrapper for |
|
Denote the natural logarithm. |
|
Legacy shorthand for |
|
Shorthand for |
|
Extract the diagonal of |
|
Denote the maximum over a collection of convex scalar expressions. |
|
Denote the minimum over a collection of concave scalar expressions. |
|
Create a constant or a list or dict or tuple thereof. |
|
Legacy shorthand for |
|
Shorthand for |
|
Create a standard simplex of radius |
|
Shorthand for |
|
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 |
Functions¶
ball¶
block¶
-
picos.expressions.algebra.
block
(nested, shapes=None, name=None)[source]¶ Create an affine block matrix expression.
Given a two-level nested iterable container (e.g. a list of lists) of PICOS affine expressions or constant data values or a mix thereof, this creates an affine block matrix where each inner container represents one block row and each expression or constant represents one block.
Blocks that are given as PICOS expressions are never reshaped or broadcasted. Their shapes must already be consistent. Blocks that are given as constant data values are reshaped or broadcasted as necessary to match existing PICOS expressions. This means you can specify blocks as e.g.
"I"
or0
and PICOS will load them as matrices with the smallest shape that is consistent with other blocks given as PICOS expressions.Since constant data values are not reshaped or broadcasted with respect to each other, the
shapes
parameter allows a manual clarification of block shapes. It must be consistent with the shapes of blocks given as PICOS expressions (they are still not reshaped or broadcasted).- Parameters
shapes (tuple(tuple) or list(list)) – A pair
(rows, columns)
whererows
defines the number of rows for each block row andcolumns
defines the number of columns for each block column. You can put a0
orNone
as a wildcard.name (str) – Name or string description of the resulting block matrix. If
None
, a descriptive string will be generated.
- Example
>>> from picos import block, Constant, RealVariable >>> C = Constant("C", range(6), (3, 2)) >>> d = Constant("d", 0.5, 2) >>> x = RealVariable("x", 3) >>> A = block([[ C, x ], ... ["I", d ]]); A <5×3 Real Affine Expression: [C, x; I, d]> >>> x.value = [60, 70, 80] >>> print(A) [ 0.00e+00 3.00e+00 6.00e+01] [ 1.00e+00 4.00e+00 7.00e+01] [ 2.00e+00 5.00e+00 8.00e+01] [ 1.00e+00 0.00e+00 5.00e-01] [ 0.00e+00 1.00e+00 5.00e-01] >>> B = block([[ C, x ], # With a shape hint. ... ["I", 0 ]], shapes=((3, 2), (2, 1))); B <5×3 Real Affine Expression: [C, x; I, 0]> >>> print(B) [ 0.00e+00 3.00e+00 6.00e+01] [ 1.00e+00 4.00e+00 7.00e+01] [ 2.00e+00 5.00e+00 8.00e+01] [ 1.00e+00 0.00e+00 0.00e+00] [ 0.00e+00 1.00e+00 0.00e+00]
detrootn¶
diag¶
diag_vect¶
expcone¶
-
picos.expressions.algebra.
expcone
(*args, **kwargs)¶ Shorthand for
ExponentialCone
.
flow_Constraint¶
-
picos.expressions.algebra.
flow_Constraint
(*args, **kwargs)[source]¶ Legacy shorthand for
FlowConstraint
.Deprecated since version 2.0: Use
FlowConstraint
instead.
geomean¶
-
picos.expressions.algebra.
geomean
(*args, **kwargs)¶ Shorthand for
GeometricMean
.
kldiv¶
-
picos.expressions.algebra.
kldiv
(*args, **kwargs)¶ Shorthand for
NegativeEntropy
.
kron¶
kullback_leibler¶
-
picos.expressions.algebra.
kullback_leibler
(*args, **kwargs)¶ Legacy shorthand for
NegativeEntropy
.Deprecated since version 2.0: Use
kldiv
instead.
lambda_max¶
-
picos.expressions.algebra.
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.expressions.algebra.
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¶
maindiag¶
max¶
-
picos.expressions.algebra.
max
(lst)[source]¶ Denote the maximum over a collection of convex scalar expressions.
If instead of a collection of expressions only a single multidimensional affine expression is given, this denotes its largest element instead.
If some individual expressions are uncertain and their uncertainty is not of stochastic but of worst-case nature (robust optimization), then the maximum implicitly goes over their perturbation parameters as well.
- Parameters
lst (list or tuple or AffineExpression) – A list of convex expressions or a single affine expression.
- Example
>>> from picos import RealVariable, max, sum >>> x = RealVariable("x", 5) >>> max(x) <Largest Element: max(x)> >>> max(x) <= 2 # The same as x <= 2. <Largest Element Constraint: max(x) ≤ 2> >>> max([sum(x), abs(x)]) <Maximum of Convex Functions: max(∑(x), ‖x‖)> >>> max([sum(x), abs(x)]) <= 2 # Both must be <= 2. <Maximum of Convex Functions Constraint: max(∑(x), ‖x‖) ≤ 2> >>> from picos.uncertain import UnitBallPerturbationSet >>> z = UnitBallPerturbationSet("z", 5).parameter >>> max([sum(x), x.T*z]) # Also maximize over z. <Maximum of Convex Functions: max(∑(x), max_z xᵀ·z)>
min¶
-
picos.expressions.algebra.
min
(lst)[source]¶ Denote the minimum over a collection of concave scalar expressions.
If instead of a collection of expressions only a single multidimensional affine expression is given, this denotes its smallest element instead.
If some individual expressions are uncertain and their uncertainty is not of stochastic but of worst-case nature (robust optimization), then the minimum implicitly goes over their perturbation parameters as well.
- Parameters
lst (list or tuple or AffineExpression) – A list of concave expressions or a single affine expression.
- Example
>>> from picos import RealVariable, min, sum >>> x = RealVariable("x", 5) >>> min(x) <Smallest Element: min(x)> >>> min(x) >= 2 # The same as x >= 2. <Smallest Element Constraint: min(x) ≥ 2> >>> min([sum(x), -x[0]**2]) <Minimum of Concave Functions: min(∑(x), -x[0]²)> >>> min([sum(x), -x[0]**2]) >= 2 # Both must be >= 2. <Minimum of Concave Functions Constraint: min(∑(x), -x[0]²) ≥ 2> >>> from picos.uncertain import UnitBallPerturbationSet >>> z = UnitBallPerturbationSet("z", 5).parameter >>> min([sum(x), x.T*z]) # Also minimize over z. <Minimum of Concave Functions: min(∑(x), min_z xᵀ·z)>
new_param¶
norm¶
partial_trace¶
-
picos.expressions.algebra.
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.expressions.algebra.
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.
rsoc¶
-
picos.expressions.algebra.
rsoc
(*args, **kwargs)¶ Shorthand for
RotatedSecondOrderCone
.
simplex¶
soc¶
-
picos.expressions.algebra.
soc
(*args, **kwargs)¶ Shorthand for
SecondOrderCone
.
sum¶
-
picos.expressions.algebra.
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.expressions.algebra.
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.expressions.algebra.
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.expressions.algebra.
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.expressions.algebra.
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.expressions.algebra.
sumexp
(*args, **kwargs)¶ Shorthand for
SumExponentials
.
tracepow¶
-
picos.expressions.algebra.
tracepow
(exp, num=1, denom=1, coef=None)[source]¶ Legacy shorthand for
PowerTrace
.Deprecated since version 2.0: Use
PowerTrace
instead.