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