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)

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]

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)

Form a diagonal matrix from the column-major vectorization of .

If , then the vectorization is repeated times.

picos.expressions.algebra.diag_vect(x)

Extract the diagonal of as a column vector.

Deprecated since version 2.0: Use picos.maindiag instead.

picos.expressions.algebra.exp(x)

Denote the exponential.

picos.expressions.algebra.expcone(*args, **kwargs)

Shorthand for ExponentialCone.

picos.expressions.algebra.flow_Constraint(*args, **kwargs)

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)

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)

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>

picos.expressions.algebra.lambda_min(x)

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>

picos.expressions.algebra.log(x)

Denote the natural logarithm.

picos.expressions.algebra.logsumexp(*args, **kwargs)

Legacy shorthand for LogSumExp.

Deprecated since version 2.0: Use picos.lse instead.

picos.expressions.algebra.lse(*args, **kwargs)

Shorthand for LogSumExp.

picos.expressions.algebra.maindiag(x)

Extract the diagonal of as a column vector.

picos.expressions.algebra.max(lst)

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)

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)

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)

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)

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)

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)

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 and 1 denotes the sum of the columns as a column vector. If summing multiple expressions, any value other than None raises a ValueError.

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)

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>

picos.expressions.algebra.sum_k_largest_lambda(x, k)

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>

picos.expressions.algebra.sum_k_smallest(x, k)

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>

picos.expressions.algebra.sum_k_smallest_lambda(x, k)

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>

picos.expressions.algebra.sumexp(*args, **kwargs)

Shorthand for SumExponentials.

picos.expressions.algebra.trace(x)

Denote the trace of a square matrix.

picos.expressions.algebra.tracepow(exp, num=1, denom=1, coef=None)

Legacy shorthand for PowerTrace.

Deprecated since version 2.0: Use picos.PowerTrace instead.

picos.expressions.algebra.truncated_simplex(gamma, sym=False)

Create a truncated simplex of radius .

Deprecated since version 2.0: Use picos.Simplex instead.

Objects

picos.expressions.algebra.I

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 0x7f9e4686bcc0>

picos.expressions.algebra.J

Create a matrix of all ones.

Example

>>> from picos import J
>>> print(J(2, 3))
[ 1.00e+00  1.00e+00  1.00e+00]
[ 1.00e+00  1.00e+00  1.00e+00]

Default value

<functools._lru_cache_wrapper object at 0x7f9e4686bc10>

picos.expressions.algebra.O

Create a zero matrix.

Example

>>> from picos import O
>>> print(O(2, 3))
[0 0 0]
[0 0 0]

Default value

<functools._lru_cache_wrapper object at 0x7f9e4680fed0>