picos.expressions.algebra¶

Implements functions that create or modify algebraic expressions.

Outline¶

Functions¶

`ball`	Legacy shorthand for `Ball`.
`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`	Wrapper for `SumExtremes`.
`min`	Wrapper for `SumExtremes`.
`new_param`	Create a constant or a list or dict or tuple thereof.
`norm`	Legacy shorthand for `Norm`.
`partial_trace`	See `expressions.ComplexAffineExpression.partial_trace`.
`partial_transpose`	See `expressions.ComplexAffineExpression.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.

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(x)[source]¶

Wrapper for SumExtremes.

Sets k = 1, largest = True and eigenvalues = False.

Example

>>> from picos import RealVariable, max
>>> x = RealVariable("x", 5)
>>> max(x)
<Largest Element: max(x)>
>>> max(x) <= 2  # The same as x <= 2.
<Largest Element Constraint: max(x) ≤ 2>

min¶

picos.expressions.algebra.min(x)[source]¶

Wrapper for SumExtremes.

Sets k = 1, largest = False and eigenvalues = False.

Example

>>> from picos import RealVariable, min
>>> x = RealVariable("x", 5)
>>> min(x)
<Smallest Element: min(x)>
>>> min(x) >= 2  # The same as x >= 2.
<Smallest Element Constraint: min(x) ≥ 2>

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