picos.expressions.uncertain.pert_conic¶

Implements ConicPerturbationSet.

Classes

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

Bases: 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[source]¶

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]

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

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

Fork me on GitLab