picos.expressions.algebra¶
Implements functions that create or modify algebraic expressions.
Functions
- picos.expressions.algebra.ball(*args, **kwargs)¶
Legacy shorthand for
Ball
.Deprecated since version 2.0: Use
picos.Ball
instead.
- 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]
- picos.expressions.algebra.detrootn(*args, **kwargs)¶
Legacy shorthand for
DetRootN
.Deprecated since version 2.0: Use
picos.DetRootN
instead.
- picos.expressions.algebra.diag(x, n=1)[source]¶
Form a diagonal matrix from the column-major vectorization of
.
If
, then the vectorization is repeated
times.
- picos.expressions.algebra.diag_vect(x)[source]¶
Extract the diagonal of
as a column vector.
Deprecated since version 2.0: Use
picos.maindiag
instead.
- picos.expressions.algebra.expcone(*args, **kwargs)¶
Shorthand for
ExponentialCone
.
- picos.expressions.algebra.flow_Constraint(*args, **kwargs)[source]¶
Legacy shorthand for
FlowConstraint
.Deprecated since version 2.0: Use
picos.FlowConstraint
instead.
- picos.expressions.algebra.geomean(*args, **kwargs)¶
Shorthand for
GeometricMean
.
- picos.expressions.algebra.kldiv(*args, **kwargs)¶
Shorthand for
NegativeEntropy
.
- picos.expressions.algebra.kron(x, y)[source]¶
Denote the kronecker product.
Deprecated since version 2.2: Ensure that one operand is a PICOS expression and use infix @ instead.
- picos.expressions.algebra.kullback_leibler(*args, **kwargs)¶
Legacy shorthand for
NegativeEntropy
.Deprecated since version 2.0: Use
picos.kldiv
instead.
- 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>
- 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>
- picos.expressions.algebra.logsumexp(*args, **kwargs)¶
Legacy shorthand for
LogSumExp
.Deprecated since version 2.0: Use
picos.lse
instead.
- 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)>
- 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)>
- picos.expressions.algebra.new_param(name, value)[source]¶
Create a constant or a list or dict or tuple thereof.
Deprecated since version 2.0: Use
picos.Constant
instead.
- picos.expressions.algebra.norm(*args, **kwargs)¶
Legacy shorthand for
Norm
.Deprecated since version 2.0: Use
picos.Norm
instead.
- picos.expressions.algebra.partial_trace(x, subsystems=0, dimensions=2, k=None, dim=None)[source]¶
See
exp_biaffine.BiaffineExpression.partial_trace
.The parameters k and dim are for backwards compatibility.
- picos.expressions.algebra.partial_transpose(x, subsystems=0, dimensions=2, k=None, dim=None)[source]¶
See
exp_biaffine.BiaffineExpression.partial_transpose
.The parameters k and dim are for backwards compatibility.
- picos.expressions.algebra.rsoc(*args, **kwargs)¶
Shorthand for
RotatedSecondOrderCone
.
- picos.expressions.algebra.simplex(gamma)[source]¶
Create a standard simplex of radius
.
Deprecated since version 2.0: Use
picos.Simplex
instead.
- picos.expressions.algebra.soc(*args, **kwargs)¶
Shorthand for
SecondOrderCone
.
- picos.expressions.algebra.sum(lst, axis=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, and in some cases a speedup, when summing over multiple PICOS expressions. Additionally, this can be used to denote the (complete, column- or row-) sum over a single matrix expression.- Parameters
axis (None or int) – If summing over a single matrix expression, this is the axis over which the sum is performed:
None
denotes the sum over all elements,0
denotes the sum of the rows as a row vector and1
denotes the sum of the columns as a column vector. If summing multiple expressions, any value other thanNone
raises aValueError
.- Example
>>> import builtins, picos, numpy >>> 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.sum or (x|1). <1×1 Real Linear Expression: ∑(x)> >>> A = picos.Constant("A", range(20), (4, 5)) >>> picos.sum(A, axis=0) # The same as A.rowsum <1×5 Real Constant: [1]ᵀ·A> >>> picos.sum(A, axis=1) # The same as A.colsum <4×1 Real Constant: A·[1]> >>> numpy.allclose( # Same axis convention as NumPy. ... numpy.sum(A.np, axis=0), picos.sum(A, axis=0).np) True
- 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>
- 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>
- 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>
- 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>
- picos.expressions.algebra.sumexp(*args, **kwargs)¶
Shorthand for
SumExponentials
.
- picos.expressions.algebra.tracepow(exp, num=1, denom=1, coef=None)[source]¶
Legacy shorthand for
PowerTrace
.Deprecated since version 2.0: Use
picos.PowerTrace
instead.
- picos.expressions.algebra.truncated_simplex(gamma, sym=False)[source]¶
Create a truncated simplex of radius
.
Deprecated since version 2.0: Use
picos.Simplex
instead.
Objects
- picos.expressions.algebra.I[source]¶
Create an identity matrix.
- Example
>>> from picos import I >>> print(I(3)) [ 1.00e+00 0 0 ] [ 0 1.00e+00 0 ] [ 0 0 1.00e+00]
- Default value
<functools._lru_cache_wrapper object at 0x7f4ee13cd170>