picos.expressions.algebra¶

Implements functions that create or modify algebraic expressions.

Outline¶

Functions¶

`ball`	Legacy shorthand for `Ball`.
`block`	Create an affine block matrix expression.
`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.
`exp`	Denote the exponential.
`expcone`	Shorthand for `ExponentialCone`.
`flow_Constraint`	Legacy shorthand for `FlowConstraint`.
`geomean`	Shorthand for `GeometricMean`.
`kldiv`	Shorthand for `NegativeEntropy`.
`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`.
`maindiag`	Extract the diagonal of $x$ as a column vector.
`max`	Denote the maximum over a collection of convex scalar expressions.
`min`	Denote the minimum over a collection of concave scalar expressions.
`new_param`	Create a constant or a list or dict or tuple thereof.
`norm`	Legacy shorthand for `Norm`.
`partial_trace`	See `expressions.BiaffineExpression.partial_trace`.
`partial_transpose`	See `expressions.BiaffineExpression.partial_transpose`.
`rsoc`	Shorthand for `RotatedSecondOrderCone`.
`simplex`	Create a standard simplex of radius $\gamma$ .
`soc`	Shorthand for `SecondOrderCone`.
`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.expressions.algebra.ball(*args, **kwargs)¶: Legacy shorthand for Ball.

Deprecated since version 2.0: Use Ball instead.

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" or 0 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

nested (tuple(tuple) or list(list)) – The blocks.
shapes (tuple(tuple) or list(list)) – A pair (rows, columns) where rows defines the number of rows for each block row and columns defines the number of columns for each block column. You can put a 0 or None 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¶

picos.expressions.algebra.detrootn(*args, **kwargs)¶: Legacy shorthand for DetRootN.

Deprecated since version 2.0: Use DetRootN instead.

diag¶

picos.expressions.algebra.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.expressions.algebra.diag_vect(x)[source]¶: Extract the diagonal of $x$ as a column vector.

Deprecated since version 2.0: Use maindiag instead.

exp¶

picos.expressions.algebra.exp(x)[source]¶: Denote the exponential.

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¶

picos.expressions.algebra.kron(x, y)[source]¶

Denote the kronecker product.

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

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 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.expressions.algebra.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.expressions.algebra.log(x)[source]¶: Denote the natural logarithm.

logsumexp¶

picos.expressions.algebra.logsumexp(*args, **kwargs)¶: Legacy shorthand for LogSumExp.

Deprecated since version 2.0: Use lse instead.

lse¶

picos.expressions.algebra.lse(*args, **kwargs)¶: Shorthand for LogSumExp.

maindiag¶

picos.expressions.algebra.maindiag(x)[source]¶: Extract the diagonal of $x$ as a column vector.

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¶

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 Constant instead.

norm¶

picos.expressions.algebra.norm(*args, **kwargs)¶: Legacy shorthand for Norm.

Deprecated since version 2.0: Use Norm instead.

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¶

picos.expressions.algebra.simplex(gamma)[source]¶: Create a standard simplex of radius $\gamma$ .

Deprecated since version 2.0: Use Simplex instead.

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 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.expressions.algebra.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.expressions.algebra.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.expressions.algebra.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.expressions.algebra.sumexp(*args, **kwargs)¶: Shorthand for SumExponentials.

trace¶

picos.expressions.algebra.trace(x)[source]¶: Denote the trace of a square matrix.

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.

truncated_simplex¶

picos.expressions.algebra.truncated_simplex(gamma, sym=False)[source]¶: Create a truncated simplex of radius $\gamma$ .

Deprecated since version 2.0: Use Simplex instead.