# picos.uncertain¶

Tools for handling uncertain data.

## Outline¶

### Classes¶

 ConicPerturbationSet A conic description of a Perturbation. MomentAmbiguitySet A moment-uncertain description of a random perturbation parameter. ScenarioPerturbationSet A scenario description of a Perturbation. 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.

## Classes¶

### ConicPerturbationSet¶

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

A conic description of a Perturbation.

Definition

An instance of this class defines a perturbation parameter

where , , , , and is a (product) cone for some .

Usage

Obtaining is done in a number of steps:

1. Create an instance of this class (see __init__).

2. Access element to obtain a regular, fresh RealVariable representing .

3. Define through any number of regular PICOS constraints that depend only on and that have a conic representation by passing the constraints to bound.

4. Call compile to obtain a handle to the Perturbation .

5. You can now use to build instances of UncertainAffineExpression and derived constraint types.

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

Alternatively, you can obtain a compiled from the factory method from_constraints and access 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 .

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 , you may add the bound (via picos.Norm(t, 1) <= b) which can be represented in conic form as

The auxiliary variable then plays the role of (a slice of) in the formal definition of .

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

Raises

RuntimeError – If the set was already compiled.

compile(validate_feasibility=False)[source]

Compile the set and return .

Internally, this computes the matrices and , the vector and the (product) cone .

Parameters

validate_feasibility (bool) – Whether to solve the feasibility problem associated with the bounds on to verify that 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 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 . 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 .

Raises

RuntimeError – If the set has not been compiled.

property B

The compiled matrix or None if .

Raises

RuntimeError – If the set has not been compiled.

property K

The compiled (product) cone .

Raises

RuntimeError – If the set has not been compiled.

property c

The compiled vector .

Raises

RuntimeError – If the set has not been compiled.

property distributional

Implement for PerturbationUniverse.

property element

The perturbation element 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 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 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.uncertain.MomentAmbiguitySet(parameter_name, shape, nominal_mean=0, nominal_covariance='I', alpha=0, beta=1, sample_space=None)[source]

A moment-uncertain description of a random perturbation parameter.

Model of uncertainty

As a distributional ambiguity set, an instance of this class

1. represents a safety region for a partially known (ambiguous) probability distribution and

2. provides a random, ambiguously distributed perturbation parameter that can be used to define worst-case-expectation expressions of the form

for a selection of functions and a decision variable .

Definition

Formally, this class can describe ambiguity sets of the form

where

1. is the set of all Borel probability measures on ,

2. the sample space bounds the support of and may be given as either or as an -dimensional ellipsoid,

3. and with are the nominal mean and covariance matrix of , respectively, and

4. and are meta-parameters bounding the uncertainty concerning the mean and the covariance matrix, respectively.

Unless , this class can also represent the limit cases of and denoting an unbounded mean and covariance matrix, respectively.

Note

While denotes that the nominal mean is certain, there is a subtle difference between setting 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

1. A squared norm where is biaffine in and . This can be written as abs(A)**2 in Python.

2. A convex piecewise linear function where is biaffine in and for all . This can be written as picos.max([a_1, ..., a_k]) in Python.

3. A concave piecewise linear function where is biaffine in and for all . This can be written as picos.min([a_1, ..., a_k]) in Python.

Example

We show that for unbounded mean and support (i.e. and ) and for a finite samples space , 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 .

• shape (anything recognized by load_shape) – Shape of . 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 of the ambiguous distribution .

• nominal_covariance (anything recognized by load_data) – The nominal covariance matrix of the ambiguous distribution .

• alpha (float) – The parameter bounding the uncertain mean. The values None and float("inf") denote an unbounded mean.

• beta (float) – The parameter bounding the uncertain covariance matrix. The values None and float("inf") denote unbounded covariances.

• sample_space (None or TheField or Ellipsoid) – The sample space . If this is None or an instance of TheField (i.e. ), then the support of is unbounded. If this is an -dimensional instance of Ellipsoid, then the support of is a subset of that ellipsoid.

property alpha

The parameter .

A value of None denotes .

property beta

The parameter .

A value of None denotes .

property dim

The dimension of the sample space.

property distributional

Implement for PerturbationUniverse.

property nominal_covariance

The nominal covariance matrix .

property nominal_mean

The nominal mean of the ambiguous distribution.

property parameter

The random perturbation parameter .

property sample_space

The sample space (bound on support) .

A value of None means .

### ScenarioPerturbationSet¶

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

A scenario description of a Perturbation.

Definition

An instance of this class defines a perturbation parameter

where is a finite set of scenarios and denotes the convex hull.

Usually, the scenarios are observed or projected realizations of the uncertain data and 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 .

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

### UnitBallPerturbationSet¶

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

Represents perturbation in an Euclidean or Frobenius unit norm ball.

This is a ConicPerturbationSet with fixed form

After initialization, you can obtain the parameter using parameter.

__init__(parameter_name, shape=(1, 1))[source]
property unit_ball_form

Overwrite ConicPerturbationSet.unit_ball_form.

### WassersteinAmbiguitySet¶

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

A wasserstein ambiguity set centered at a discrete distribution.

Model of uncertainty

As a distributional ambiguity set, an instance of this class

1. represents a safety region for a partially known (ambiguous) probability distribution and

2. provides a random, ambiguously distributed perturbation parameter that can be used to define worst-case-expectation expressions of the form

for a selection of functions and a decision variable .

Definition

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

where discrepancy from the discrete nominal distribution

is measured with respect to the Wasserstein distance of order ,

where

1. is the set of all Borel probability measures on for some ,

2. denotes the set of all couplings of and ,

3. for all are the samples comprising the support of ,

4. are weights denoting the nominal probabilitiy mass at for all ,

5. denotes the Dirac delta function with unit mass at for all and where

6. controls the radius of the ambiguity set.

Supported functions

For :

1. A convex piecewise linear function where is biaffine in and for all . This can be written as picos.max([a_1, ..., a_k]) in Python.

2. A concave piecewise linear function where is biaffine in and for all . This can be written as picos.min([a_1, ..., a_k]) in Python.

For :

1. A squared norm where is biaffine in and . 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 .

• p (float) – The Wasserstein type/order parameter .

• eps (float) – The Wasserstein ball radius .

• samples (aynthing recognized by Samples) – The support of the discrete distribution given as the samples . The original shape of the samples determines the shape of .

• 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

property p

The Wasserstein order .

property parameter

The random perturbation parameter .

property samples

The registered samples as a Samples object.

property weights

The sample weights a constant PICOS vector.

## Exceptions¶

### IntractableWorstCase¶

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