picos.expressions.uncertain.pert_conic

Implements ConicPerturbationSet.

Outline

Classes

ConicPerturbationSet

A conic description of a Perturbation.

UnitBallPerturbationSet

Represents perturbation in an Euclidean or Frobenius unit norm ball.

Classes

ConicPerturbationSet

class picos.expressions.uncertain.pert_conic.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:

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

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

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

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

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

See also SOCConstraint.unit_ball_form.

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]

UnitBallPerturbationSet

class picos.expressions.uncertain.pert_conic.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.