picos.expressions.uncertain¶

Expression types with an explicit representation of data uncertainty.

Outline¶

Classes¶

`ConicPerturbationSet`	A conic description of a `Perturbation`.
`MomentAmbiguitySet`	A moment-uncertain description of a random perturbation parameter.
`Perturbation`	A parameter that can be used to describe (random) noise in data.
`PerturbationUniverse`	Base class for uncertain perturbation sets and distributions.
`RandomExtremumAffine`	Base class for random convex or concave piecewise linear expressions.
`RandomMaximumAffine`	The maximum over a set of random affine expressions.
`RandomMinimumAffine`	The minimum over a set of random affine expressions.
`ScenarioPerturbationSet`	A scenario description of a `Perturbation`.
`UncertainAffineExpression`	A multidimensional uncertain affine expression.
`UncertainExpression`	Primary base class for uncertainty affected expression types.
`UncertainNorm`	Euclidean or Frobenius norm of an uncertain affine expression.
`UncertainSquaredNorm`	Squared Euclidean or Frobenius norm of an uncertain affine expression.
`UnitBallPerturbationSet`	Represents perturbation in an Euclidean or Frobenius unit norm ball.
`WassersteinAmbiguitySet`	A wasserstein ambiguity set centered at a discrete distribution.

Exceptions¶

IntractableWorstCase

Computing a worst-case (expected) value is hard and not supported.

Submodules¶

`picos.expressions.uncertain.pert_conic`	Implements `ConicPerturbationSet`.
`picos.expressions.uncertain.pert_moment`	Implements `MomentAmbiguitySet`.
`picos.expressions.uncertain.pert_scenario`	Implements `ScenarioPerturbationSet`.
`picos.expressions.uncertain.pert_wasserstein`	Implements `WassersteinAmbiguitySet`.
`picos.expressions.uncertain.perturbation`	Implements a parameterization for (random) noise in data.
`picos.expressions.uncertain.uexp_affine`	Implements `UncertainAffineExpression`.
`picos.expressions.uncertain.uexp_norm`	Implements `UncertainNorm`.
`picos.expressions.uncertain.uexp_rand_pwl`	Implements `RandomExtremumAffine`.
`picos.expressions.uncertain.uexp_sqnorm`	Implements `UncertainSquaredNorm`.
`picos.expressions.uncertain.uexpression`	Implements the `UncertainExpression` base class.

Classes¶

ConicPerturbationSet¶

class picos.expressions.uncertain.ConicPerturbationSet(parameter_name, shape=(1, 1))[source]¶

Bases: picos.expressions.uncertain.perturbation.PerturbationUniverse

A conic description of a Perturbation.

Definition

An instance $\Theta$ of this class defines a perturbation parameter

$\theta \in \Theta = \{t \in \mathbb{R}^{m \times n} \mid \exists u \in \mathbb{R}^l : A\operatorname{vec}(t) + Bu + c \in K\}$

where $m, n \in \mathbb{Z}_{\geq 1}$ , $l \in \mathbb{Z}_{\geq 0}$ , $A \in \mathbb{R}^{k \times mn}$ , $B \in \mathbb{R}^{k \times l}$ , $c \in \mathbb{R}^k$ and $K \subseteq \mathbb{R}^k$ is a (product) cone for some $k \in \mathbb{Z}_{\geq 1}$ .

Usage

Obtaining $\theta$ is done in a number of steps:

Create an instance of this class (see __init__).
Access element to obtain a regular, fresh RealVariable representing $t$ .
Define $\Theta$ through any number of regular PICOS constraints that depend only on $t$ and that have a conic representation by passing the constraints to bound.
Call compile to obtain a handle to the Perturbation $\theta$ .
You can now use $\theta$ to build instances of UncertainAffineExpression and derived constraint types.

It is best practice to assign $t$ to a Python variable and overwrite that variable with $\theta$ on compilation.

Alternatively, you can obtain a compiled $\Theta$ from the factory method from_constraints and access $\theta$ via parameter.

Example

>>> from picos import Constant, Norm, RealVariable
>>> from picos.uncertain import ConicPerturbationSet
>>> S = ConicPerturbationSet("P", (4, 4))
>>> P = S.element; P  # Obtain a temporary parameter to describe S with.
<4×4 Real Variable: P>
>>> S.bound(Norm(P, float("inf")) <= 1)  # Confine each element to [-1,1].
>>> S.bound(Norm(P, 1) <= 4); S  # Allow a perturbation budget of 4.
<4×4 Conic Perturbation Set: {P : ‖P‖_max ≤ 1 ∧ ‖P‖_sum ≤ 4}>
>>> P = S.compile(); P  # Compile the set and obtain the actual parameter.
<4×4 Perturbation: P>
>>> A = Constant("A", range(16), (4, 4))
>>> U = A + P; U  # Define an uncertain data matrix.
<4×4 Uncertain Affine Expression: A + P>
>>> x = RealVariable("x", 4)
>>> U*x  # Define an uncertain affine expression.
<4×1 Uncertain Affine Expression: (A + P)·x>

__init__(parameter_name, shape=(1, 1))[source]¶

Create a ConicPerturbationSet.

Parameters

parameter_name (str) – Name of the parameter that lives in the set.
shape (int or tuple or list) – The shape of a vector or matrix perturbation.

bound(constraint)[source]¶

Add a constraint that bounds $t$ .

The constraints do not need to be conic but they need to have a conic representation, which may involve any number of auxiliary variables. For instance, given a constant uncertainty budget $b$ , you may add the bound $\lVert t \rVert_1 \leq b$ (via picos.Norm(t, 1) <= b) which can be represented in conic form as

$&\exists v \in \mathbb{R}^{\operatorname{dim}(t)} : -t \leq v \land t \leq v \land \mathbf{1}^Tv \leq b \\ \Longleftrightarrow~ &\exists v \in \mathbb{R}^{\operatorname{dim}(t)} : \begin{pmatrix} v + t \\ v - t \\ b - \mathbf{1}^Tv \end{pmatrix} \in \mathbb{R}_{\geq 0}^{2\operatorname{dim}(t) + 1}.$

The auxiliary variable $v$ then plays the role of (a slice of) $u$ in the formal definition of $\Theta$ .

When you are done adding bounds, you can obtain $\theta$ using compile.

Raises: RuntimeError – If the set was already compiled.

compile(validate_feasibility=False)[source]¶

Compile the set and return $\theta$ .

Internally, this computes the matrices $A$ and $B$ , the vector $c$ and the (product) cone $K$ .

Parameters

validate_feasibility (bool) – Whether to solve the feasibility problem associated with the bounds on $t$ to verify that $\Theta$ is nonempty.

Returns

An instance of Perturbation.

Raises

RuntimeError – If the set was already compiled.
TypeError – If the bound constraints could not be put into conic form.
ValueError – If $\Theta$ could not be verified to be nonempty (needs validate_feasibility=True).

classmethod from_constraints(parameter_name, *constraints)[source]¶

Create a ConicPerturbationSet from constraints.

The constraints must concern a single regular decision variable that plays the role of the element $t$ . This variable is not stored or modified and can be reused in a different context.

Parameters

parameter_name (str) – Name of the parameter that lives in the set.
constraints – A parameter sequence of constraints that concern a single regular decision variable whose internal vectorization is trivial (its dimension must match the product over its shape) and that have a conic representation.

Raises

ValueError – If the constraints do not all concern the same single variable.
TypeError – If the variable uses a nontrivial vectorization format or if the constraints do not all have a conic representation.

Example

>>> from picos.expressions.uncertain import ConicPerturbationSet
>>> from picos import RealVariable
>>> x = RealVariable("x", 4)
>>> T = ConicPerturbationSet.from_constraints("t", abs(x) <= 2, x >= 0)
>>> print(T)
{t : ‖t‖ ≤ 2 ∧ t ≥ 0}
>>> print(repr(T.parameter))
<4×1 Perturbation: t>

worst_case(scalar, direction)[source]¶: Implement for PerturbationUniverse.

property A¶

The compiled matrix $A$ .

Raises: RuntimeError – If the set has not been compiled.

property B¶

The compiled matrix $B$ or None if $l = 0$ .

Raises: RuntimeError – If the set has not been compiled.

property K¶

The compiled (product) cone $K$ .

Raises: RuntimeError – If the set has not been compiled.

property c¶

The compiled vector $c$ .

Raises: RuntimeError – If the set has not been compiled.

property distributional¶: Implement for PerturbationUniverse.

property element¶

The perturbation element $t$ describing the set.

This is a regular RealVariable that you can use to create constraints to pass to bound. You can then obtain the “actual” perturbation parameter $\theta$ to use in expressions alongside your decision variaiables using compile.

Warning

If you use this object instead of parameter to define a decision problem then it will act as a regular decision variable, which is probably not what you want.

Raises: RuntimeError – If the set was already compiled.

property ellipsoidal¶

Whether the perturbation set is an ellipsoid.

If this is true, then a unit_ball_form is available.

property parameter¶

The perturbation parameter $\theta$ living in the set.

This is the object returned by compile.

Raises: RuntimeError – If the set has not been compiled.

property unit_ball_form¶

A recipe to repose from ellipsoidal to unit norm ball uncertainty.

If the set is ellipsoidal, then this is a pair (U, M) where U is a UnitBallPerturbationSet and M is a dictionary mapping the old parameter to an affine expression of the new parameter that can represent the old parameter in an expression (see replace_mutables). The mapping M is empty if and only if the perturbation set is already an instance of UnitBallPerturbationSet.

If the uncertainty set is not ellipsoidal, then this is None.

Example

>>> from picos import Problem, RealVariable, sum
>>> from picos.uncertain import ConicPerturbationSet
>>> # Create a conic perturbation set and a refinement recipe.
>>> T = ConicPerturbationSet("t", (2, 2))
>>> T.bound(abs(([[1, 2], [3, 4]] ^ T.element) + 1) <= 10)
>>> t = T.compile()
>>> U, mapping = T.unit_ball_form
>>> print(U)
{t' : ‖t'‖ ≤ 1}
>>> print(mapping)
{<2×2 Perturbation: t>: <2×2 Uncertain Affine Expression: t(t')>}
>>> # Define and solve a conically uncertain LP.
>>> X = RealVariable("X", (2, 2))
>>> P = Problem()
>>> P.set_objective("max", sum(X))
>>> _ = P.add_constraint(X + 2*t <= 10)
>>> print(repr(P.parameters["t"].universe))
<2×2 Conic Perturbation Set: {t : ‖[2×2]⊙t + [1]‖ ≤ 10}>
>>> _ = P.solve(solver="cvxopt")
>>> print(X)
[-8.00e+00  1.00e+00]
[ 4.00e+00  5.50e+00]
>>> # Refine the problem to a unit ball uncertain LP.
>>> Q = Problem()
>>> Q.set_objective("max", sum(X))
>>> _ = Q.add_constraint(X + 2*mapping[t] <= 10)
>>> print(repr(Q.parameters["t'"].universe))
<2×2 Unit Ball Perturbation Set: {t' : ‖t'‖ ≤ 1}>
>>> _ = Q.solve(solver="cvxopt")
>>> print(X)
[-8.00e+00  1.00e+00]
[ 4.00e+00  5.50e+00]

MomentAmbiguitySet¶

class picos.expressions.uncertain.MomentAmbiguitySet(parameter_name, shape, nominal_mean=0, nominal_covariance='I', alpha=0, beta=1, sample_space=None)[source]¶

Bases: picos.expressions.uncertain.perturbation.PerturbationUniverse

A moment-uncertain description of a random perturbation parameter.

Model of uncertainty

As a distributional ambiguity set, an instance $\mathcal{P}$ of this class

represents a safety region for a partially known (ambiguous) probability distribution $\Xi \in \mathcal{P}$ and
provides a random, ambiguously distributed perturbation parameter $\xi \sim \Xi$ that can be used to define worst-case-expectation expressions of the form

$\mathop{(\max\;\textit{or}\;\min)}_{\Xi \in \mathcal{P}} \mathbb{E}_\Xi[f(x, \xi)]$

for a selection of functions $f$ and a decision variable $x$ .

Definition

Formally, this class can describe ambiguity sets of the form

$\mathcal{P} = \left\{ \Xi \in \mathcal{M} ~\middle|~ \begin{aligned} \mathbb{P}(\xi \in \mathcal{S}) &= 1, \\ \left( \mathbb{E}[\xi] - \mu \right)^T \Sigma^{-1} \left( \mathbb{E}[\xi] - \mu \right) &\leq \alpha, \\ \mathbb{E}[(\xi - \mu)(\xi - \mu)^T] &\preceq \beta \Sigma \end{aligned} \right\}$

where

$\mathcal{M}$ is the set of all Borel probability measures on $\mathbb{R}^n$ ,
the sample space $\mathcal{S} \subseteq \mathbb{R}^n$ bounds the support of $\Xi$ and may be given as either $\mathbb{R}^n$ or as an $n$ -dimensional ellipsoid,
$\mu \in \mathbb{R}^n$ and $\Sigma \in \mathbb{S}^n$ with $\Sigma \succ 0$ are the nominal mean and covariance matrix of $\Xi$ , respectively, and
$\alpha \geq 0$ and $\beta \geq 1$ are meta-parameters bounding the uncertainty concerning the mean and the covariance matrix, respectively.

Unless $\mathcal{S} = \mathbb{R}^n$ , this class can also represent the limit cases of $\alpha \to \infty$ and $\beta \to \infty$ denoting an unbounded mean and covariance matrix, respectively.

Note

While $\alpha = 0$ denotes that the nominal mean $\mu$ is certain, there is a subtle difference between setting $\beta = 1$ on the one hand and assuming a certain form for the covariance matrix on the other hand: In the former case, the worst case covariance matrix may be Lowener smaller than the nominal one. Setting a lower bound on the covarianve matrix is computationally difficult and not supported.

Supported functions

A squared norm $f(x, \xi) = \lVert A(x, \xi) \rVert_F^2$ where $A$ is biaffine in $x$ and $\xi$ . This can be written as abs(A)**2 in Python.
A convex piecewise linear function $f(x, \xi) = max_{i=1}^k a_i(x, \xi)$ where $a$ is biaffine in $x$ and $\xi$ for all $i \in [k]$ . This can be written as picos.max([a_1, ..., a_k]) in Python.
A concave piecewise linear function $f(x, \xi) = min_{i=1}^k a_i(x, \xi)$ where $a$ is biaffine in $x$ and $\xi$ for all $i \in [k]$ . This can be written as picos.min([a_1, ..., a_k]) in Python.

Example

We show that for unbounded mean and support (i.e. $\alpha \to \infty$ and $\beta \to \infty$ ) and for a finite samples space $S$ , this distributional ambiguity set can be used in the context of classical (non-distributional) robust optimization applied to least squares problems.

>>> from picos import Constant, diag, Ellipsoid, Problem, RealVariable
>>> from picos.uncertain import ConicPerturbationSet, MomentAmbiguitySet
>>> import numpy
>>> numpy.random.seed(1)
>>> # Setup data and variables of the nominal least squares problem.
>>> n = 3
>>> A = Constant("A", numpy.random.random((n, n)))
>>> b = Constant("b", numpy.random.random(n))
>>> x = RealVariable("x", n)
>>> # Setup an ellipsoid S bounding the uncertainty in both models.
>>> N = n**2
>>> S = Ellipsoid(N, diag(range(1, N + 1)), range(N))
>>> # Define and solve both robust models.
>>> U1 = ConicPerturbationSet.from_constraints(
...     "Y", RealVariable("Y", N) << S)
>>> U2 = MomentAmbiguitySet("Z", N, alpha=None, beta=None, sample_space=S)
>>> Y = U1.parameter.reshaped((n, n))
>>> Z = U2.parameter.reshaped((n, n))
>>> P1, P2 = Problem(), Problem()
>>> P1.objective = "min", abs((A + Y)*x - b)
>>> P2.objective = "min", abs((A + Z)*x - b)**2
>>> _ = P1.solve(solver="cvxopt")
>>> x1 = ~x  # Save current value of x as a constant PICOS expression x1.
>>> _ = P2.solve(solver="cvxopt")
>>> x2 = ~x
>>> # Verify that both models yield the same robust regression vector.
>>> x1.equals(x2, relTol=1e-4)
True

__init__(parameter_name, shape, nominal_mean=0, nominal_covariance='I', alpha=0, beta=1, sample_space=None)[source]¶

Create a MomentAmbiguitySet.

Parameters

parameter_name (str) – Name of the random parameter $\xi$ .
shape (anything recognized by load_shape) – Shape of $\xi$ . Must characterize a column vector. If None, then the shape is inferred from the nominal mean.
nominal_mean (anything recognized by load_data) – The nominal mean $\mu$ of the ambiguous distribution $\Xi$ .
nominal_covariance (anything recognized by load_data) – The nominal covariance matrix $\Sigma$ of the ambiguous distribution $\Xi$ .
alpha (float) – The parameter $\alpha \geq 0$ bounding the uncertain mean. The values None and float("inf") denote an unbounded mean.
beta (float) – The parameter $\beta \geq 1$ bounding the uncertain covariance matrix. The values None and float("inf") denote unbounded covariances.
sample_space (None or TheField or Ellipsoid) – The sample space $\mathcal{S}$ . If this is None or an instance of TheField (i.e. $\mathbb{R}^n$ ), then the support of $\Xi$ is unbounded. If this is an $n$ -dimensional instance of Ellipsoid, then the support of $\Xi$ is a subset of that ellipsoid.

property alpha¶

The parameter $\alpha$ .

A value of None denotes $\alpha \to \infty$ .

property beta¶

The parameter $\beta$ .

A value of None denotes $\beta \to \infty$ .

property dim¶: The dimension $n$ of the sample space.

property distributional¶: Implement for PerturbationUniverse.

property nominal_covariance¶: The nominal covariance matrix $\Sigma$ .

property nominal_mean¶: The nominal mean $\mu$ of the ambiguous distribution.

property parameter¶: The random perturbation parameter $\xi$ .

property sample_space¶

The sample space (bound on support) $\mathcal{S}$ .

A value of None means $\mathcal{S} = \mathbb{R}^n$ .

Perturbation¶

class picos.expressions.uncertain.Perturbation(universe, name, shape)[source]¶

Bases: picos.expressions.mutable.Mutable, picos.expressions.uncertain.uexp_affine.UncertainAffineExpression

A parameter that can be used to describe (random) noise in data.

This is the initial building block for an UncertainAffineExpression. In particular, an affine transformation of this parameter represents uncertain data.

__init__(universe, name, shape)[source]¶

Create a Perturbation.

Parameters

universe (PerturbationUniverse) – Either the set that the perturbation parameter lives in or the distribution according to which the perturbation is distributed.
name (str) – Symbolic string description of the perturbation, similar to a variable’s name.
shape (int or tuple or list) – Algebraic shape of the perturbation parameter.

This constructor is meant for internal use. As a user, you will want to first define a universe (e.g. ConicPerturbationSet) for the parameter and obtain the parameter from it.

copy(new_name=None)[source]¶: Return an independent copy of the perturbation.

property universe¶: The uncertainty universe that the parameter belongs to.

PerturbationUniverse¶

class picos.expressions.uncertain.PerturbationUniverse[source]¶

Bases: abc.ABC

Base class for uncertain perturbation sets and distributions.

See distributional for a distinction between perturbation sets, random distributions and distributional ambiguity sets, all three of which can be represented by this class.

The naming scheme for implementing classes is as follows:

Perturbation sets (robust optimization) end in PerturbationSet,
random distributions (stochastic programming) end in Distribution,
distributional ambiguity sets (DRO) end in AmbiguitySet.

classmethod make_type(*args, **kwargs)[source]¶: Create a detailed universe type from subtype parameters.

worst_case(scalar, direction)[source]¶

Find a worst-case realization of the uncertainty for an expression.

Parameters

scalar (UncertainExpression) – A scalar uncertain expression that depends only on the perturbation parameter.
direction (str) – Either "min" or "max", denoting the worst-case direction.

Returns

A pair where the first element is the worst-case (expeceted) value as a float and where the second element is a realization of the perturbation parameter that attains this worst case as a float or CVXOPT matrix (or None for stochastic uncertainty).

Raises

TypeError – When the function is not scalar.
ValueError – When the function depends on other mutables than exactly the parameter.
picos.uncertain.IntractableWorstCase – When computing the worst-case (expected) value is not supported, in particular when it would require solving a nonconvex problem.
RuntimeError – When the computation is supported but fails.

abstract property distributional¶

Whether this is a distribution or distributional ambiguity set.

If this is True, then this represents a random distribution (stochastic programming) or an ambiguity set of random distributions (distributionally robust optimization) and any expression that depends on its random parameter, when used in a constraint or as an objective function, is understood as a (worst-case) expected value.

If this is False, then this represents a perturbation set (robust optimization) and any expression that depends on its perturbation parameter, when used in a constraint or as an objective function, is understood as a worst-case value.

abstract property parameter¶: The perturbation parameter.

property subtype¶

property type¶: Detailed type of a perturbation parameter universe.

RandomExtremumAffine¶

class picos.expressions.uncertain.RandomExtremumAffine(expressions)[source]¶

Bases: picos.expressions.exp_extremum.ExtremumBase, picos.expressions.uncertain.uexpression.UncertainExpression, picos.expressions.expression.Expression

Base class for random convex or concave piecewise linear expressions.

Note

Unlike other uncertain expression types, this class is limited to uncertainty of stochastic nature, where using the expression in a constraint or as an objective function implicitly takes the (worst-case) expectation of the expression. Non-stochastic uncertainty is handled within MaximumConvex and MinimumConcave as their behavior, although designed for certain expression types, already encodes the worst-case approach of the robust optimization paradigm.

__init__(expressions)[source]¶

Construct a RandomExtremumAffine.

Parameters: expressions – A collection of uncertain affine expressions whose uncertainty is of stochastic nature.

property expressions¶: The expressions under the extremum.

property perturbation¶: Fast override for UncertainExpression.

RandomMaximumAffine¶

class picos.expressions.uncertain.RandomMaximumAffine(expressions)[source]¶

Bases: picos.expressions.exp_extremum.MaximumBase, picos.expressions.uncertain.uexp_rand_pwl.RandomExtremumAffine

The maximum over a set of random affine expressions.

RandomMinimumAffine¶

class picos.expressions.uncertain.RandomMinimumAffine(expressions)[source]¶

Bases: picos.expressions.exp_extremum.MinimumBase, picos.expressions.uncertain.uexp_rand_pwl.RandomExtremumAffine

The minimum over a set of random affine expressions.

ScenarioPerturbationSet¶

class picos.expressions.uncertain.ScenarioPerturbationSet(parameter_name, scenarios, compute_hull=None)[source]¶

Bases: picos.expressions.uncertain.perturbation.PerturbationUniverse

A scenario description of a Perturbation.

Definition

An instance $\Theta$ of this class defines a perturbation parameter

$\theta \in \Theta = \operatorname{conv}(S)$

where $S \subset \mathbb{R}^{m \times n}$ is a finite set of scenarios and $\operatorname{conv}$ denotes the convex hull.

Usually, the scenarios are observed or projected realizations of the uncertain data and $\theta$ is used to represent the data directly.

Example

>>> from picos.uncertain import ScenarioPerturbationSet
>>> scenarios = [[1, -1], [1, 1], [-1, -1], [-1, 1], [0, 0]]
>>> S = ScenarioPerturbationSet("s", scenarios, False); S
<2×1 Scenario Perturbation Set: conv({5 2×1 scenarios})>
>>> s = S.parameter; s
<2×1 Perturbation: s>
>>> # Compute largest sum of entries over all points in S.
>>> value, realization = S.worst_case(s[0] + s[1], "max")
>>> round(value,  4)
2.0
>>> print(realization)
[ 1.00e+00]
[ 1.00e+00]

__init__(parameter_name, scenarios, compute_hull=None)[source]¶

Create a ScenarioPerturbationSet.

Parameters

parameter_name (str) – Name of the parameter that lives in the set.
scenarios (anything recognized by picos.Samples) – A collection of data points of same shape representing $S$ .
compute_hull (bool) – Whether to use SciPy to compute the convex hull of the data points and discard points in the interior. This can speed up the solution process significantly, in particular when the scenarios come from observations and when the data is low-dimensional. On the other hand, when the given scenarios are known to be on the boundary of their convex hull, then disabling this speeds up initialization of the perturbation set. The default value of None means True when SciPy is available and False otherwise.

worst_case(scalar, direction)[source]¶: Implement for PerturbationUniverse.

property distributional¶: Implement for PerturbationUniverse.

property parameter¶: Implement for PerturbationUniverse.

property scenarios¶: The registered scenarios as a Samples object.

UncertainAffineExpression¶

class picos.expressions.uncertain.UncertainAffineExpression(string, shape=(1, 1), coefficients={})[source]¶

Bases: picos.expressions.uncertain.uexpression.UncertainExpression, picos.expressions.exp_biaffine.BiaffineExpression

A multidimensional uncertain affine expression.

This expression has the form

$A(x,\theta) = B(x,\theta) + P(x) + Q(\theta) + C$

where $B$ , $P$ , $Q$ , $C$ and $x$ are defined as for the BiaffineExpression base class and $\theta$ is an uncertain perturbation parameter confined to (distributed according to) a perturbation set (distribution) $\Theta$ .

If no coefficient matrices defining $B$ and $P$ are provided, then this expression represents uncertain data confined to an uncertainty set $\{Q(\theta) + C \mid \theta \in \Theta\}$ (distributed according to $Q(\Theta) + C$ ) where $C$ can be understood as a nominal data value while $Q(\theta)$ quantifies the uncertainty on the data.

__init__(string, shape=(1, 1), coefficients={})[source]¶

Construct an UncertainAffineExpression.

Extends exp_biaffine.BiaffineExpression.__init__.

This constructor is meant for internal use. As a user, you will want to first define a universe (e.g. ConicPerturbationSet) for a perturbation parameter and use that parameter as a building block to create more complex uncertain expressions.

UncertainExpression¶

class picos.expressions.uncertain.UncertainExpression[source]¶

Bases: object

Primary base class for uncertainty affected expression types.

The secondary base class must be Expression or a subclass thereof.

Uncertain expressions have a distinct behavior when used to form a constraint or when posed as an objective function. The exact behavior depends on the type of uncertainty involved. If the perturbation parameter that describes the uncertainty is confied to a perturbation set, then the worst-case realization of the parameter is assumed when determining feasibility and optimality. If the perturbation parameter is a random variable (whose distribution may itself be ambiguous), then the constraint or objective implicitly considers the expected value of the uncertain expression (under the worst-case distribution). Uncertain expressions are thus used in the contexts of robust optimization, stochastic programming and distributionally robust optimization.

worst_case(direction)[source]¶

Find a worst-case realization of the uncertainty for the expression.

Expressions that are affected by uncertainty are only partially valued once an optimization solution has been applied. While their decision values are populated with a robust optimal solution, the parameter that controls the uncertainty is not valued unless the user assigned it a particular realization by hand. This method computes a worst-case (expected) value of the expression and returns it together with a realization of the perturbation parameter for which the worst case is attained (or None in the case of stochastic uncertainty).

For multidimensional expressions, this method computes the entrywise worst case and returns an attaining realization for each entry.

Parameters

direction (str) – Either "min" or "max", denoting the worst-case direction.

Returns

A pair (value, realization). For a scalar expression, value is its worst-case (expected) value as a float and realization is a realization of the perturbation parameter that attains this worst case as a float or CVXOPT matrix. For a multidimensional expression, value is a CVXOPT dense matrix denoting the entrywise worst-case values and realization is a tuple of attaining realizations corresponding to the expression vectorized in in column-major order. Lastly, realization is None if the expression is certain or when its uncertainty is of stochastic nature.

Raises

picos.NotValued – When the decision variables that occur in the expression are not fully valued.
picos.uncertain.IntractableWorstCase – When computing the worst-case (expected) value is not supported, in particular when it would require solving a nonconvex problem.
RuntimeError – When the computation is supported but fails.

worst_case_string(direction)[source]¶

A string describing the expression within a worst-case context.

Parameters: direction (str) – Either "min" or "max", denoting the worst-case direction.

worst_case_value(direction)[source]¶: A shorthand for the first value returned by worst_case.

property certain¶: Whether the uncertain expression is actually certain.

property perturbation¶: The parameter controlling the uncertainty, or None.

property random¶

Whether the uncertainty is of stochastic nature.

UncertainNorm¶

class picos.expressions.uncertain.UncertainNorm(x)[source]¶

Bases: picos.expressions.uncertain.uexpression.UncertainExpression, picos.expressions.expression.Expression

Euclidean or Frobenius norm of an uncertain affine expression.

__init__(x)[source]¶

Construct an UncertainNorm.

Parameters: x (UncertainAffineExpression) – The uncertain affine expression to denote the norm of.

property x¶: Uncertain affine expression under the norm.

UncertainSquaredNorm¶

class picos.expressions.uncertain.UncertainSquaredNorm(x)[source]¶

Bases: picos.expressions.uncertain.uexpression.UncertainExpression, picos.expressions.expression.Expression

Squared Euclidean or Frobenius norm of an uncertain affine expression.

__init__(x)[source]¶

Construct an UncertainSquaredNorm.

Parameters: x (UncertainAffineExpression) – The uncertain affine expression to denote the squared norm of.

property x¶: Uncertain affine expression under the squared norm.

UnitBallPerturbationSet¶

class picos.expressions.uncertain.UnitBallPerturbationSet(parameter_name, shape=(1, 1))[source]¶

Bases: picos.expressions.uncertain.pert_conic.ConicPerturbationSet

Represents perturbation in an Euclidean or Frobenius unit norm ball.

This is a ConicPerturbationSet with fixed form

$\{t \in \mathbb{R}^{m \times n} \mid \lVert t \rVert_F \leq 1\}.$

After initialization, you can obtain the parameter using parameter.

__init__(parameter_name, shape=(1, 1))[source]¶: See ConicPerturbationSet.__init__.

property unit_ball_form¶: Overwrite ConicPerturbationSet.unit_ball_form.

WassersteinAmbiguitySet¶

class picos.expressions.uncertain.WassersteinAmbiguitySet(parameter_name, p, eps, samples, weights=1)[source]¶

Bases: picos.expressions.uncertain.perturbation.PerturbationUniverse

A wasserstein ambiguity set centered at a discrete distribution.

Model of uncertainty

As a distributional ambiguity set, an instance $\mathcal{P}$ of this class

represents a safety region for a partially known (ambiguous) probability distribution $\Xi \in \mathcal{P}$ and
provides a random, ambiguously distributed perturbation parameter $\xi \sim \Xi$ that can be used to define worst-case-expectation expressions of the form

$\mathop{(\max\;\textit{or}\;\min)}_{\Xi \in \mathcal{P}} \mathbb{E}_\Xi[f(x, \xi)]$

for a selection of functions $f$ and a decision variable $x$ .

Definition

Formally, this class can describe discrepancy-based ambiguity sets of the form

$\mathcal{P} = \left\{ \Xi \in \mathcal{M} ~\middle|~ \operatorname{W}_p(\Xi, \Xi_\text{N}) \leq \epsilon \right\}$

where discrepancy from the discrete nominal distribution

$\Xi_\text{N} = \sum_{i = 1}^N w_i \delta_{\xi_{(i)}} \in \mathcal{M}$

is measured with respect to the Wasserstein distance of order $p \geq 1$ ,

$\operatorname{W}_p(\Xi, \Xi') = {\left( \inf_{\Phi \in \Pi(\Xi, \Xi')} \int_{\mathbb{R}^m \times \mathbb{R}^m} \lVert \phi - \phi' \rVert^p \; \Phi( \mathop{}\!\mathrm{d} \phi \times \mathop{}\!\mathrm{d} \phi') \right)}^{\frac{1}{p}},$

where

$\mathcal{M}$ is the set of all Borel probability measures on $\mathbb{R}^n$ for some $n \in \mathbb{Z}_{\geq 1}$ ,
$\Pi(\Xi, \Xi')$ denotes the set of all couplings of $\Xi$ and $\Xi'$ ,
$\xi_{(i)} \in \mathbb{R}^n$ for all $i \in [N]$ are the $N \in \mathbb{Z}_{\geq 1}$ samples comprising the support of $\Xi_\text{N}$ ,
$w_i \in \mathbb{R}_{\geq 0}$ are weights denoting the nominal probabilitiy mass at $\xi_{(i)}$ for all $i \in [N]$ ,
$\delta_{\xi_{(i)}}$ denotes the Dirac delta function with unit mass at $\xi_{(i)}$ for all $i \in [N]$ and where
$\epsilon \in \mathbb{R}_{\geq 0}$ controls the radius of the ambiguity set.

Supported functions

For $p = 1$ :

A convex piecewise linear function $f(x, \xi) = max_{i=1}^k a_i(x, \xi)$ where $a$ is biaffine in $x$ and $\xi$ for all $i \in [k]$ . This can be written as picos.max([a_1, ..., a_k]) in Python.
A concave piecewise linear function $f(x, \xi) = min_{i=1}^k a_i(x, \xi)$ where $a$ is biaffine in $x$ and $\xi$ for all $i \in [k]$ . This can be written as picos.min([a_1, ..., a_k]) in Python.

For $p = 2$ :

A squared norm $f(x, \xi) = \lVert A(x, \xi) \rVert_F^2$ where $A$ is biaffine in $x$ and $\xi$ . This can be written as abs(A)**2 in Python.

__init__(parameter_name, p, eps, samples, weights=1)[source]¶

Create a WassersteinAmbiguitySet.

Parameters

parameter_name (str) – Name of the random parameter $\xi$ .
p (float) – The Wasserstein type/order parameter $p$ .
eps (float) – The Wasserstein ball radius $\epsilon$ .
samples (aynthing recognized by Samples) – The support of the discrete distribution $\Xi_\text{D}$ given as the samples $\xi_{(i)}$ . The original shape of the samples determines the shape of $\xi$ .
weights – A vector denoting the nonnegative weight (e.g. frequency or probability) of each sample. Its length must match the number of samples provided. The argument will be normalized such that its entries sum to one. Entries of zero will be dropped alongside their associated sample. The default value of 1 denotes the empirical distribution on the samples.

Warning

Duplicate samples are not detected and can impact performance. If duplicate samples are likely, make sure to detect them and encode their frequency in the weight vector.

property distributional¶: Implement for PerturbationUniverse.

property eps¶: The Wasserstein ball radius $\epsilon$ .

property p¶: The Wasserstein order $p$ .

property parameter¶: The random perturbation parameter $\xi$ .

property samples¶: The registered samples as a Samples object.

property weights¶: The sample weights a constant PICOS vector.

Exceptions¶

IntractableWorstCase¶

exception picos.expressions.uncertain.IntractableWorstCase[source]¶

Bases: RuntimeError

Computing a worst-case (expected) value is hard and not supported.

Raised by worst_case and methods that depend on it.

__init__(*args, **kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

__new__(**kwargs)¶: Create and return a new object. See help(type) for accurate signature.