picos.constraints¶

Optimization constraint types.

This package contains the constraint types that are used to express optimization constraints. You do not need to instanciate these constraints directly; it is more convenient to create them by applying Python’s comparison operators to algebraic expressions (see the Cheat Sheet).

Outline¶

Classes¶

`AbsoluteValueConstraint`	Upper bound on an absolute value.
`AffineConstraint`	An equality or inequality between two affine expressions.
`BallUncertainNormConstraint`	An (uncertain) upper bound on a norm with unit ball uncertainty.
`ComplexAffineConstraint`	An equality between affine expressions, at least one being complex.
`ComplexLMIConstraint`	Complex linear matrix inequality.
`ConicConstraint`	Base class for constraints with an immediate conic representation.
`ConicQuadraticConstraint`	Bound on a nearly convex quadratic expression.
`ConicallyUncertainAffineConstraint`	A bound on an affine expression with conic uncertainty.
`Constraint`	Abstract base class for optimization constraints.
`ConstraintConversion`	Recipe for conversion from one constraint to a set of other constraints.
`ConstraintType`	Container for a pair of constraint class type and constraint subtype.
`ConvexQuadraticConstraint`	Bound on a convex quadratic expression.
`DetRootNConstraint`	Lower bound on the $n$ -th root of a matrix determinant.
`DummyConstraint`	An explicit way to not put a bound on an affine expression.
`ExpConeConstraint`	Exponential cone membership constraint.
`ExtremumConstraint`	Bound on a maximum (minimum) over convex (concave) functions.
`FlowConstraint`	Network flow constraint.
`GeometricMeanConstraint`	Lower bound on a geometric mean.
`KullbackLeiblerConstraint`	Upper bound on a Kullback-Leibler divergence.
`LMIConstraint`	Linear matrix inequality.
`LogConstraint`	Lower bound on a logarithm.
`LogSumExpConstraint`	Upper bound on a logarithm of a sum of exponentials.
`MatrixNormConstraint`	Upper bound on a matrix $(p,q)$ -norm.
`MomentAmbiguousExtremumAffineConstraint`	A bound on a moment-ambiguous expected value of a piecewise function.
`MomentAmbiguousSquaredNormConstraint`	A bound on a moment-ambiguous expected value of a squared norm.
`NonconvexQuadraticConstraint`	Bound on a nonconvex quadratic expression.
`NuclearNormConstraint`	Nuclear norm of a matrix.
`PowerTraceConstraint`	Bound on the trace over the $p$ -th power of a matrix.
`ProductConeConstraint`	Confines an element inside a real Cartesian product cone.
`RSOCConstraint`	Rotated second order cone membership constraint.
`SOCConstraint`	Second order ( $2$ -norm, Lorentz) cone membership constraint.
`ScenarioUncertainConicConstraint`	Conic constraint with scenario uncertainty.
`SimplexConstraint`	(Symmetrized, truncated) simplex membership constraint.
`SpectralNormConstraint`	Spectral norm of a matrix.
`SquaredNormConstraint`	Upper bound on a squared Euclidean or Frobenius norm.
`SumExponentialsConstraint`	Upper bound on a sum of exponentials.
`SumExtremesConstraint`	Bound on a sum over extreme (eigen)values.
`VectorNormConstraint`	Bound on a (generalized) vector $p$ -norm.
`WassersteinAmbiguousExtremumAffineConstraint`	A bound on a W_1-ambiguous expected value of a piecewise function.
`WassersteinAmbiguousSquaredNormConstraint`	A bound on a Wasserstein-ambiguous expected value of a squared norm.

Submodules¶

`picos.constraints.con_absolute`	Implementation of `AbsoluteValueConstraint`.
`picos.constraints.con_affine`	Affine constraint types.
`picos.constraints.con_detrootn`	Implementation of `DetRootNConstraint`.
`picos.constraints.con_dummy`	Implementation of `DummyConstraint`.
`picos.constraints.con_expcone`	Implementation of `ExpConeConstraint`.
`picos.constraints.con_extremum`	Implementation of `ExtremumConstraint`.
`picos.constraints.con_flow`	Implementation of `FlowConstraint`.
`picos.constraints.con_geomean`	Implementation of `GeometricMeanConstraint`.
`picos.constraints.con_kldiv`	Implementation of `KullbackLeiblerConstraint`.
`picos.constraints.con_lmi`	Linear matrix inequalities.
`picos.constraints.con_log`	Implementation of `LogConstraint`.
`picos.constraints.con_logsumexp`	Implementation of `LogSumExpConstraint`.
`picos.constraints.con_matnorm`	Implementation of matrix norm constraints.
`picos.constraints.con_powtrace`	Implementation of `PowerTraceConstraint`.
`picos.constraints.con_prodcone`	Implementation of `ProductConeConstraint`.
`picos.constraints.con_quadratic`	Quadratic constraint types.
`picos.constraints.con_rsoc`	Rotated second order cone constraints.
`picos.constraints.con_simplex`	Implementation of `SimplexConstraint`.
`picos.constraints.con_soc`	Second order conce constraints.
`picos.constraints.con_sqnorm`	Implementation of `SquaredNormConstraint`.
`picos.constraints.con_sumexp`	Implementation of `SumExponentialsConstraint`.
`picos.constraints.con_sumxtr`	Implementation of `SumExtremesConstraint`.
`picos.constraints.con_vecnorm`	Implementation of `VectorNormConstraint`.
`picos.constraints.constraint`	Backend for constraint type implementations.
`picos.constraints.uncertain`	Constraint types with an explicit representation of data uncertainty.

Classes¶

AbsoluteValueConstraint¶

class picos.constraints.AbsoluteValueConstraint(signedScalar, upperBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Upper bound on an absolute value.

class AffineConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Upper bound on an absolute value to affine inequality conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod dual(auxVarPrimals, auxConDuals, options)[source]¶: Implement dual.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(signedScalar, upperBound)[source]¶

Construct an AbsoluteValueConstraint.

Parameters

signedScalar (AffineExpression) – A scalar expression.
upperBound (AffineExpression) – Upper bound on the expression.

AffineConstraint¶

class picos.constraints.AffineConstraint(lhs, relation, rhs, customString=None)[source]¶

Bases: picos.constraints.constraint.ConicConstraint

An equality or inequality between two affine expressions.

__init__(lhs, relation, rhs, customString=None)[source]¶

Construct an AffineConstraint.

Parameters

lhs (AffineExpression) – Left hand side expression.
relation (str) – Constraint relation symbol.
rhs (AffineExpression) – Right hand side expression.
customString (str) – Optional string description.

bounded_linear_form()[source]¶

Bounded linear form of the constraint.

Separates the constraint into a linear function on the left hand side and a constant bound on the right hand side.

Returns: A pair (linear, bound) where linear is a pure linear expression and bound is a constant expression.

sparse_Ab_rows(varOffsetMap, indexFunction=None)[source]¶

Sparse representation of the constraint’s bounded linear form.

A sparse list representation of the constraint, given a mapping of PICOS variables to column offsets (or alternatively given an index function).

The constraint is brought into a bounded linear form A • b, where • is one of ≤, ≥, or =, depending on the constraint relation, and the rows returned correspond to the matrix [A|b].

Parameters

varOffsetMap (dict) – Maps variables or variable start indices to column offsets.
indexFunction – Instead of adding the local variable index to the value returned by varOffsetMap, use the return value of this function, that takes as argument the variable and its local index, as the “column index”, which need not be an integer. When this parameter is passed, the parameter varOffsetMap is ignored.

Returns

A list of triples (J, V, c) where J contains column indices (representing scalar variables), V contains coefficients for each column index and c is a constant term. Each entry of the list represents a row in a constraint matrix.

property conic_membership_form¶: Implement for ConicConstraint.

property ge0¶

Expression constrained to be greater than or equal to zero.

The expression posed to be greater than or equal to zero in case of an inequality, otherwise the left hand side minus the right hand side.

property greater¶

Greater-or-equal side of the constraint.

The greater-or-equal side expression in case of an inequality, otherwise the right hand side.

property le0¶

Expression constrained to be lower than or equal to zero.

The expression posed to be less than or equal to zero in case of an inequality, otherwise the left hand side minus the right hand side.

property smaller¶

Smaller-or-equal side of the constraint.

The smaller-or-equal side expression in case of an inequality, otherwise the left hand side.

BallUncertainNormConstraint¶

class picos.constraints.BallUncertainNormConstraint(norm, upper_bound)[source]¶

Bases: picos.constraints.constraint.Constraint

An (uncertain) upper bound on a norm with unit ball uncertainty.

class RobustConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Robust counterpart conversion.

classmethod convert(con, options)[source]¶

Implement convert.

Conversion recipe and variable names based on the book Robust Optimization (Ben-Tal, El Ghaoui, Nemirovski, 2009).

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(norm, upper_bound)[source]¶

Construct a BallUncertainNormConstraint.

Parameters

norm (UncertainNorm) – Uncertain norm that is bounded from above.
upper_bound (AffineExpression or UncertainAffineExpression) – (Uncertain) upper bound on the norm.

property ne¶: The uncertain affine expression under the norm.

ComplexAffineConstraint¶

class picos.constraints.ComplexAffineConstraint(lhs, rhs, customString=None)[source]¶

Bases: picos.constraints.constraint.ConicConstraint

An equality between affine expressions, at least one being complex.

class RealConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Complex affine equality to real affine equality conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod dual(auxVarPrimals, auxConDuals, options)[source]¶: Implement dual.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(lhs, rhs, customString=None)[source]¶

Construct a ComplexAffineConstraint.

Parameters

lhs (AffineExpression) – Left hand side expression.
rhs (AffineExpression) – Right hand side expression.
customString (str) – Optional string description.

property conic_membership_form¶: Implement for ConicConstraint.

ComplexLMIConstraint¶

class picos.constraints.ComplexLMIConstraint(lhs, relation, rhs, customString=None)[source]¶

Bases: picos.constraints.con_lmi.LMIConstraint

Complex linear matrix inequality.

class RealConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Complex LMI to real LMI conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod dual(auxVarPrimals, auxConDuals, options)[source]¶: Implement dual.

classmethod predict(subtype, options)[source]¶: Implement predict.

ConicConstraint¶

class picos.constraints.ConicConstraint(typeTerm, customString=None, printSize=False)[source]¶

Bases: picos.constraints.constraint.Constraint

Base class for constraints with an immediate conic representation.

abstract property conic_membership_form¶

The constraint in conic membership form.

For a conic constraint $Ax \succeq_C b \Leftrightarrow Ax - b \in C$ this is the pair $(Ax - b, C)$ where $Ax - b$ is an affine expression and $C$ a basic cone supported by PICOS.

property conic_standard_form¶

The constraint in conic standard form.

For a conic constraint $Ax \succeq_C b$ this is the triple $(Ax, b, C)$ where $Ax$ is a linear expression, $b$ is a constant, and $C$ a basic cone supported by PICOS.

property inverse_conic_standard_form¶

The constraint in inverse conic standard form.

For a conic constraint $Ax \succeq_C b \Leftrightarrow -Ax \preceq_C -b$ this is the triple $(-Ax, -b, C)$ where $Ax$ is a linear expression, $b$ is a constant, and $C$ a basic cone supported by PICOS.

ConicQuadraticConstraint¶

class picos.constraints.ConicQuadraticConstraint(lhs, relation, rhs)[source]¶

Bases: picos.constraints.con_quadratic.NonconvexQuadraticConstraint

Bound on a nearly convex quadratic expression.

Nearly convex means that the bilinear form representing the quadratic part of the expression that the constraint poses to be at most zero has exactly one negative eigenvalue. More precisely, if the constraint is of the form $x^TQx + a^Tx + b \leq x^TRx + b^Tx + c$ , then Q - R needs to have exactly one negative eigenvalue for the constraint to be nearly convex. Such constraints can be posed as conic constraints under an additional assumption that some affine term is nonnegative.

At this point, this class may only be used for nonconvex constraints of the form $x^TQx + p^Tx + q \leq (a^Tx + b)(c^Tx + d)$ with $x^TQx + p^Tx + q$ representable as a squared norm. In this case, the additional assumptions required for a conic reformulation are $a^Tx + b \geq 0$ and $b^Tx + c \geq 0$ .

Whether a constraint of this type is strengthened to a conic constraint or relabeled as a NonconvexQuadraticConstraint depends on the assume_conic option.

Example

>>> from picos import Options, RealVariable
>>> x, y, z = RealVariable("x"), RealVariable("y"), RealVariable("z")
>>> C = x**2 + 1 <= y*z; C
<Conic Quadratic Constraint: x² + 1 ≤ y·z>
>>> P = C.__class__.Conversion.convert(C, Options(assume_conic=True))
>>> list(P.constraints.values())[0]
<4×1 RSOC Constraint: ‖fullroot(x² + 1)‖² ≤ y·z ∧ y ≥ 0>
>>> Q = C.__class__.Conversion.convert(C, Options(assume_conic=False))
>>> list(Q.constraints.values())[0]
<Nonconvex Quadratic Constraint: x² + 1 ≤ y·z>

Note

Solver implementations must not support this constraint type so that the user’s choice for the assume_conic option is respected.

class Conversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Nearly convex quadratic to (rotated) second order cone conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(lhs, relation, rhs)[source]¶

Construct a ConicQuadraticConstraint.

See NonconvexQuadraticConstraint.__init__ for more.

ConicallyUncertainAffineConstraint¶

class picos.constraints.ConicallyUncertainAffineConstraint(le0)[source]¶

Bases: picos.constraints.constraint.Constraint

A bound on an affine expression with conic uncertainty.

class RobustConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Robust counterpart conversion.

classmethod convert(con, options)[source]¶

Implement convert.

Conversion recipe and variable names based on the book Robust Optimization (Ben-Tal, El Ghaoui, Nemirovski, 2009).

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(le0)[source]¶

Construct an ConicallyUncertainAffineConstraint.

Parameters: le0 (UncertainAffineExpression) – Uncertain expression constrained to be at most zero.

Constraint¶

class picos.constraints.Constraint(typeTerm, customString=None, printSize=False)[source]¶

Bases: abc.ABC

Abstract base class for optimization constraints.

Implementations

need to implement at least the abstract methods _str, _expression_names, and _get_slack,

need to implement _get_size, unless duals are not supported, and

are supposed to call Constraint.__init__ from within their own implementation of __init__.

__init__(typeTerm, customString=None, printSize=False)[source]¶

Perform basic initialization for Constraint instances.

Parameters

typeTerm (str) – Short string denoting the constraint type.
customString (str) – Optional string description.
printSize (bool) – Whether to include the constraint’s shape in its representation string.

constring()[source]¶: Return an algebraic string representation of the constraint.

delete()[source]¶

Raise a NotImplementedError.

Formerly this would remove the constraint from the single problem it is assigned to, if any.

Deprecated since version 2.0: Both variables and constraints have been decoupled from problems: Both may safely appear in multiple problems but at the same time they do not know which problems they were added to. To remove a constraint from a problem, you have to call its remove_constraint method.

is_decreasing()[source]¶: Whether the left side is posed greater or equal than the right.

is_equality()[source]¶: Whether the constraints states an equality.

is_increasing()[source]¶: Whether the left side is posed smaller or equal than the right.

is_inequality()[source]¶: Whether the constraints states an inequality.

keyconstring()[source]¶: Return the regular string representation.

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

replace_mutables(new_mutables)[source]¶

Make the constraint concern a different set of mutables.

See replace_mutables for more.

EQ = '='¶

GE = '>'¶

LE = '<'¶

property dual¶: Value of the constraint’s Lagrange dual variable.

property expressions¶: Yield expressions stored with the constraint.

property id¶

The unique ID of the constraint, assigned at creation.

The ID is kept when the constraint is copied via replace_mutables, so that the copy can be identified with the original despite pointing to different expressions and mutable objects.

property mutables¶: All mutables referenced by the constraint.

property parameters¶: All parameters referenced by the constraint.

property size¶

Langrange dual variable shape.

The dimensionality of the constraint, more precisely the dimensionality of its Lagrange dual variable, as a pair.

property slack¶

Value of a slack variable or of the negative constraint violation.

A negative value whose absolute value corresponds to the amount of violation, if the constraint is violated, or a non-negative value that corresponds to the value of a slack variable, otherwise.

property subtype¶

property type¶

Detailed type of the constraint.

The detailed type of the constraint, which is suffcient to predict the outcome (detailed types and quantities of auxilary variables and constraints) of any constraint conversion.

property variables¶: All decision variables referenced by the constraint.

ConstraintConversion¶

class picos.constraints.ConstraintConversion[source]¶

Bases: abc.ABC

Recipe for conversion from one constraint to a set of other constraints.

Implementations of this class are defined within the class body of a Constraint implementation to tell PICOS’ reformulation framework how that constraint can be reformulated into a number of other constraints and auxiliary variables.

Implementation class names must end in Conversion, and in particular may be called just Conversion. If for instance AbsoluteValueConstraint defines AffineConversion, then the reformulation will be coined AbsoluteValueToAffineReformulation. If the conversions was just named Conversion, the result would be a class named AbsoluteValueReformulation.

__init__()[source]¶: Raise a TypeError on instanciation.

abstract classmethod convert(constraint, options)[source]¶

Convert a given constraint.

Returns a temporary problem instance that contains auxilary constraints and variables replacing the given constraint.

classmethod dual(auxVarPrimals, auxConDuals, options)[source]¶

Convert back the dual value of a constraint that was converted.

Given a mapping of auxilary variable names (as named in convert) to primals and a list of auxilary constraint duals (in the order as the constraints were added in convert), returns a dual value for the converted constraint.

Raises: NotImplementedError – When dual format not decided upon or not known. This will be caught by the reformulation’s backward method.

abstract classmethod predict(subtype, options)[source]¶

Predict the outcome of a constraint conversion.

Parameters

subtype (object) – A hashable object as could be returned by the _subtype method of the parent constraint implementation.
options (Options) – Solution options to assume used.

Yields

Records to be added to a problem footprint when an instance of the parent constraint with the given subtype is converted according to this conversion.

ConstraintType¶

class picos.constraints.ConstraintType(theClass, subtype)[source]¶

Bases: picos.containers.DetailedType

Container for a pair of constraint class type and constraint subtype.

ConvexQuadraticConstraint¶

class picos.constraints.ConvexQuadraticConstraint(lhs, relation, rhs)[source]¶

Bases: picos.constraints.con_quadratic.NonconvexQuadraticConstraint

Bound on a convex quadratic expression.

class ConicConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Convex quadratic to (rotated) second order cone conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(lhs, relation, rhs)[source]¶

Construct a ConvexQuadraticConstraint.

See NonconvexQuadraticConstraint.__init__ for more.

DetRootNConstraint¶

class picos.constraints.DetRootNConstraint(detRootN, lowerBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Lower bound on the $n$ -th root of a matrix determinant.

class Conversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

$n$ -th root of a matrix determinant constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(detRootN, lowerBound)[source]¶

Construct a DetRootNConstraint.

Parameters

detRootN (DetRootN) – Constrained expression.
lowerBound (AffineExpression) – Lower bound on the expression.

DummyConstraint¶

class picos.constraints.DummyConstraint(x)[source]¶

Bases: picos.constraints.constraint.ConicConstraint

An explicit way to not put a bound on an affine expression.

This is produced when declaring an expression a member of the trivial TheField cone.

A constraint of this type can be used to pass a variable to a solver that does not otherwise appear in the problem.

__init__(x)[source]¶: Construct a DummyConstraint.

property conic_membership_form¶: Implement for ConicConstraint.

ExpConeConstraint¶

class picos.constraints.ExpConeConstraint(element, customString=None)[source]¶

Bases: picos.constraints.constraint.Constraint

Exponential cone membership constraint.

An exponential cone constraint stating that $(x, y, z)$ fulfills $x \geq y e^{\frac{z}{y}} \land x > 0 \land y > 0$ .

__init__(element, customString=None)[source]¶

Construct an ExpConeConstraint.

Parameters

element (AffineExpression) – Three-dimensional expression representing the vector $(x, y, z)$ .
customString (str) – Optional string description.

property conic_membership_form¶: Implement for ConicConstraint.

property x¶

property y¶

property z¶

ExtremumConstraint¶

class picos.constraints.ExtremumConstraint(extremum, relation, rhs)[source]¶

Bases: picos.constraints.constraint.Constraint

Bound on a maximum (minimum) over convex (concave) functions.

class Conversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Bound on a maximum or minimum of functions conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(extremum, relation, rhs)[source]¶

Construct a ExtremumConstraint.

Parameters

extremum (Extremum) – Left hand side expression.
relation (str) – Constraint relation symbol.
rhs (AffineExpression) – Right hand side expression.

FlowConstraint¶

class picos.constraints.FlowConstraint(G, f, source, sink, flow_value, capacity=None, graphName='')[source]¶

Bases: picos.constraints.constraint.Constraint

Network flow constraint.

Note

Unlike other Constraint implementations, this one is instanciated by the user (via a wrapper function), so it is raising exceptions instead of making assertions.

class Conversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Network flow constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(G, f, source, sink, flow_value, capacity=None, graphName='')[source]¶

Construct a network flow constraint.

Parameters

G (networkx DiGraph.) – A directed graph.
f (dict) – A dictionary of variables indexed by the edges of G.
source – Either a node of G or a list of nodes in case of a multi-source flow.
sink – Either a node of G or a list of nodes in case of a multi-sink flow.
flow_value – The value of the flow, or a list of values in case of a single-source/multi-sink flow. In the latter case, the values represent the demands of each sink (resp. of each source for a multi-source/single-sink flow). The values can be either constants or AffineExpression.
capacity – Either None or a string. If this is a string, it indicates the key of the edge dictionaries of G that is used for the capacity of the links. Otherwise, edges have an unbounded capacity.
graphName (str) – Name of the graph as used in the string representation of the constraint.

draw()[source]¶: Draw the graph.

replace_mutables(mapping)[source]¶

property mutables¶

GeometricMeanConstraint¶

class picos.constraints.GeometricMeanConstraint(geoMean, lowerBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Lower bound on a geometric mean.

class RSOCConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Geometric mean to rotated second order cone constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(geoMean, lowerBound)[source]¶

Construct a GeometricMeanConstraint.

Parameters

lhs (GeometricMean) – Constrained expression.
lowerBound (AffineExpression) – Lower bound on the expression.

KullbackLeiblerConstraint¶

class picos.constraints.KullbackLeiblerConstraint(divergence, upperBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Upper bound on a Kullback-Leibler divergence.

This is the upper bound on a negative or relative entropy, both represented by NegativeEntropy.

class ExpConeConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Kullback-Leibler to exponential cone constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(divergence, upperBound)[source]¶

Construct a KullbackLeiblerConstraint.

Parameters

divergence (NegativeEntropy) – Constrained expression.
upperBound (AffineExpression) – Upper bound on the expression.

property denominator¶: The $y$ of the divergence, or $1$ .

property numerator¶: The $x$ of the divergence.

LMIConstraint¶

class picos.constraints.LMIConstraint(lhs, relation, rhs, customString=None)[source]¶

Bases: picos.constraints.constraint.ConicConstraint

Linear matrix inequality.

An inequality with respect to the positive semidefinite cone, also known as a Linear Matrix Inequality (LMI) or an SDP constraint.

__init__(lhs, relation, rhs, customString=None)[source]¶

Construct a LMIConstraint.

Parameters

lhs (AffineExpression) – Left hand side expression.
relation (str) – Constraint relation symbol.
rhs (AffineExpression) – Right hand side expression.
customString (str) – Optional string description.

property conic_membership_form¶: Implement for ConicConstraint.

property greater¶: The greater-or-equal side expression.

property nnd¶: The matrix expression posed to be positive semidefinite.

property npd¶: The matrix expression posed to be negative semidefinite.

property nsd¶: The matrix expression posed to be negative semidefinite.

property psd¶: The matrix expression posed to be positive semidefinite.

property smaller¶: The smaller-or-equal side expression.

LogConstraint¶

class picos.constraints.LogConstraint(log, lowerBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Lower bound on a logarithm.

class ExpConeConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Bound on a logarithm to exponential cone constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(log, lowerBound)[source]¶

Construct a LogConstraint.

Parameters

log (Logarithm) – Constrained expression.
lowerBound (AffineExpression) – Lower bound on the expression.

LogSumExpConstraint¶

class picos.constraints.LogSumExpConstraint(lse, upperBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Upper bound on a logarithm of a sum of exponentials.

class ExpConeConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Bound on a log-sum-exp to exponential cone constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod dual(auxVarPrimals, auxConDuals, options)[source]¶: Implement dual.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(lse, upperBound)[source]¶

Construct a LogSumExpConstraint.

Parameters

lse (LogSumExp) – Constrained expression.
upperBound (AffineExpression) – Upper bound on the expression.

property exponents¶: The affine exponents of the bounded log-sum-exp expression.

property le0¶: The LogSumExp posed to be at most zero.

MatrixNormConstraint¶

class picos.constraints.MatrixNormConstraint(norm, upperBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Upper bound on a matrix $(p,q)$ -norm.

class VectorNormConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Upper bound on a $(p,q)$ -norm constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(norm, upperBound)[source]¶

Construct a MatrixNormConstraint.

Parameters

norm (Norm) – The norm.
upperBound (AffineExpression) – The scalar upper bound.

MomentAmbiguousExtremumAffineConstraint¶

class picos.constraints.MomentAmbiguousExtremumAffineConstraint(extremum, relation, rhs)[source]¶

Bases: picos.constraints.constraint.Constraint

A bound on a moment-ambiguous expected value of a piecewise function.

class DistributionallyRobustConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Distributionally robust counterpart conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(extremum, relation, rhs)[source]¶

Construct a MomentAmbiguousExtremumAffineConstraint.

Parameters

extremum (RandomExtremumAffine) – Left hand side expression.
relation (str) – Constraint relation symbol.
rhs (AffineExpression) – Right hand side expression.

property maximum_form¶: The constraint posed as an upper bound on an expected maximum.

MomentAmbiguousSquaredNormConstraint¶

class picos.constraints.MomentAmbiguousSquaredNormConstraint(sqnorm, upper_bound)[source]¶

Bases: picos.constraints.constraint.Constraint

A bound on a moment-ambiguous expected value of a squared norm.

class DistributionallyRobustConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Distributionally robust counterpart conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(sqnorm, upper_bound)[source]¶

Construct a MomentAmbiguousSquaredNormConstraint.

Parameters

sqnorm (UncertainSquaredNorm) – Uncertain squared norm to upper bound the expectation of.
upper_bound (AffineExpression) – Upper bound on the expected value.

NonconvexQuadraticConstraint¶

class picos.constraints.NonconvexQuadraticConstraint(lhs, relation, rhs)[source]¶

Bases: picos.constraints.constraint.Constraint

Bound on a nonconvex quadratic expression.

__init__(lhs, relation, rhs)[source]¶

Construct a NonconvexQuadraticConstraint.

Parameters

lhs (QuadraticExpression or AffineExpression) – Left hand side quadratic or affine expression.
relation (str) – Constraint relation symbol.
rhs (QuadraticExpression or AffineExpression) – Right hand side quadratic or affine expression.

property greater¶: Greater-or-equal side of the constraint.

property le0¶: Quadratic expression constrained to be at most zero.

property smaller¶: Smaller-or-equal side of the constraint.

NuclearNormConstraint¶

class picos.constraints.NuclearNormConstraint(norm, upperBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Nuclear norm of a matrix.

class Conversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Nuclear norm constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(norm, upperBound)[source]¶

Construct a NuclearNormConstraint.

Parameters

norm (NuclearNorm) – Constrained nuclear norm
upperBound (AffineExpression) – Upper bound on the expression.

PowerTraceConstraint¶

class picos.constraints.PowerTraceConstraint(power, relation, rhs)[source]¶

Bases: picos.constraints.constraint.Constraint

Bound on the trace over the $p$ -th power of a matrix.

For scalar expressions, this is simply a bound on their $p$ -th power.

class Conversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Bound on the $p$ -th power of a trace constraint conversion.

The conversion is based on this paper.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(power, relation, rhs)[source]¶

Construct a PowerTraceConstraint.

Parameters

ower (PowerTrace) – Left hand side expression.
relation (str) – Constraint relation symbol.
rhs (AffineExpression) – Right hand side expression.

is_trace()[source]¶: Whether the bound concerns a trace as opposed to a scalar.

property lhs¶

ProductConeConstraint¶

class picos.constraints.ProductConeConstraint(element, cone)[source]¶

Bases: picos.constraints.constraint.ConicConstraint

Confines an element inside a real Cartesian product cone.

class Conversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Cartesian product cone membership conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod dual(auxVarPrimals, auxConDuals, options)[source]¶: Implement dual.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(element, cone)[source]¶

Construct a ProductConeConstraint.

Parameters

element (AffineExpression) – The element confined in the product cone.
cone (ProductCone) – The product cone.

property conic_membership_form¶: Implement for ConicConstraint.

RSOCConstraint¶

class picos.constraints.RSOCConstraint(normedExpression, upperBoundFactor1, upperBoundFactor2=None, customString=None)[source]¶

Bases: picos.constraints.constraint.ConicConstraint

Rotated second order cone membership constraint.

__init__(normedExpression, upperBoundFactor1, upperBoundFactor2=None, customString=None)[source]¶

Construct a RSOCConstraint.

Parameters

normedExpression (AffineExpression) – Expression under the norm.
upperBoundFactor1 (AffineExpression) – First of the two scalar factors that make the upper bound on the normed expression.
upperBoundFactor2 (AffineExpression) – Second of the two scalar factors that make the upper bound on the normed expression.
customString (str) – Optional string description.

property conic_membership_form¶: Implement for ConicConstraint.

SOCConstraint¶

class picos.constraints.SOCConstraint(normedExpression, upperBound, customString=None)[source]¶

Bases: picos.constraints.constraint.ConicConstraint

Second order ( $2$ -norm, Lorentz) cone membership constraint.

__init__(normedExpression, upperBound, customString=None)[source]¶

Construct a SOCConstraint.

Parameters

normedExpression (AffineExpression) – Expression under the norm.
upperBound (AffineExpression) – Upper bound on the normed expression.
customString (str) – Optional string description.

property conic_membership_form¶: Implement for ConicConstraint.

property unit_ball_form¶

The constraint in Euclidean norm unit ball membership form.

If this constraint has the form $\lVert E(X) \rVert_F \leq c$ with $c > 0$ constant and $E(X)$ an affine expression of a single (matrix) variable $X$ with $y := \operatorname{vec}(E(X)) = A\operatorname{vec}(X) + b$ for some invertible matrix $A$ and a vector $b$ , then we have $\operatorname{vec}(X) = A^{-1}(y - b)$ and we can write the elementwise vectorization of the constraint’s feasible region as

$&\left\{\operatorname{vec}(X) \mid \lVert E(X) \rVert_F \leq c \right\} \\ =~&\left\{\operatorname{vec}(X) \mid \lVert A\operatorname{vec}(X) + b \rVert_2 \leq c \right\} \\ =~&\left\{A^{-1}(y - b) \mid \lVert y \rVert_2 \leq c \right\} \\ =~&\left\{ A^{-1}(y - b) \mid \lVert c^{-1}y \rVert_2 \leq 1 \right\} \\ =~&\left\{A^{-1}(cy - b) \mid \lVert y \rVert_2 \leq 1 \right\}.$

Therefor we can repose the constraint as two constraints:

$\lVert E(X) \rVert_F \leq c \Longleftrightarrow \exists y : \begin{cases} \operatorname{vec}(X) = A^{-1}(cy - b) \\ \lVert y \rVert_2 \leq 1. \end{cases}$

This method returns the quadruple $(X, A^{-1}(cy - b), y, B)$ where $y$ is a fresh real variable vector (the same for subsequent calls) and $B$ is the Euclidean norm unit ball.

Returns

A quadruple (X, aff_y, y, B) of type (BaseVariable, AffineExpression, RealVariable, Ball) such that the two constraints X.vec == aff_y and y << B combined are equivalent to this one.

Raises

NotImplementedError – If the expression under the norm does not reference exactly one variable or if that variable does not use a trivial vectorization format internally.
ValueError – If the upper bound is not constant, not positive, or if the matrix $A$ is not invertible.

Example

>>> import picos
>>> A = picos.Constant("A", [[2, 0],
...                          [0, 1]])
>>> x = picos.RealVariable("x", 2)
>>> P = picos.Problem()
>>> P.set_objective("max", picos.sum(x))
>>> C = P.add_constraint(abs(A*x + 1) <= 10)
>>> _ = P.solve(solver="cvxopt")
>>> print(x)
[ 1.74e+00]
[ 7.94e+00]
>>> Q = picos.Problem()
>>> Q.set_objective("max", picos.sum(x))
>>> x, aff_y, y, B, = C.unit_ball_form
>>> _ = Q.add_constraint(x == aff_y)
>>> _ = Q.add_constraint(y << B)
>>> _ = Q.solve(solver="cvxopt")
>>> print(x)
[ 1.74e+00]
[ 7.94e+00]
>>> round(abs(P.value - Q.value), 4)
0.0
>>> round(y[0]**2 + y[1]**2, 4)
1.0

ScenarioUncertainConicConstraint¶

class picos.constraints.ScenarioUncertainConicConstraint(element, cone)[source]¶

Bases: picos.constraints.constraint.Constraint

Conic constraint with scenario uncertainty.

class RobustConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Robust counterpart conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(element, cone)[source]¶

Construct a ScenarioUncertainConicConstraint.

Parameters

element (UncertainAffineExpression) – Uncertain expression constrained to be in the cone.
cone (Cone) – The cone that the uncertain expression is constrained to.

SimplexConstraint¶

class picos.constraints.SimplexConstraint(simplex, element)[source]¶

Bases: picos.constraints.constraint.Constraint

(Symmetrized, truncated) simplex membership constraint.

class AffineConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Simplex membership to affine constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(simplex, element)[source]¶

Construct a SimplexConstraint.

Parameters: element (AffineExpression) – Expression in the simplex.

SpectralNormConstraint¶

class picos.constraints.SpectralNormConstraint(norm, upperBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Spectral norm of a matrix.

class Conversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Spectral norm constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(norm, upperBound)[source]¶

Construct a SpectralNormConstraint.

Parameters

norm (SpectralNorm) – Constrained spectral norm
upperBound (AffineExpression) – Upper bound on the expression.

SquaredNormConstraint¶

class picos.constraints.SquaredNormConstraint(squaredNorm, upperBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Upper bound on a squared Euclidean or Frobenius norm.

class ConicConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Upper bound on a squared norm to conic conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(squaredNorm, upperBound)[source]¶

Construct a SquaredNormConstraint.

Parameters

squaredNorm (SquaredNorm) – The squared norm to bound from above.
upperBound (AffineExpression) – Upper bound on the squared norm.

SumExponentialsConstraint¶

class picos.constraints.SumExponentialsConstraint(theSum, upperBound)[source]¶

Bases: picos.constraints.constraint.Constraint

Upper bound on a sum of exponentials.

class ConicConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Sum of exponentials to exponential cone constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

class LogSumExpConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Sum of exponentials to logarithm of the sum constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(theSum, upperBound)[source]¶

Construct a SumExponentialsConstraint.

Parameters

theSum (SumExponentials) – Constrained expression.
upperBound (AffineExpression) – Upper bound on the expression.

property denominator¶: The $y$ of the sum, or $1$ .

property lse_representable¶: Whether this can be converted to a logarithmic constraint.

property numerator¶: The $x$ of the sum.

SumExtremesConstraint¶

class picos.constraints.SumExtremesConstraint(theSum, relation, rhs)[source]¶

Bases: picos.constraints.constraint.Constraint

Bound on a sum over extreme (eigen)values.

class Conversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Sum over extremes to LMI/affine constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(theSum, relation, rhs)[source]¶

Construct a SumExtremesConstraint.

Parameters

theSum (SumExtremes) – Left hand side expression.
relation (str) – Constraint relation symbol.
rhs (AffineExpression) – Right hand side expression.

VectorNormConstraint¶

class picos.constraints.VectorNormConstraint(norm, relation, rhs)[source]¶

Bases: picos.constraints.constraint.Constraint

Bound on a (generalized) vector $p$ -norm.

class Conversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Bound on a (generalized) $p$ -norm constraint conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(norm, relation, rhs)[source]¶

Construct a VectorNormConstraint.

Parameters

norm (Norm) – Left hand side expression.
relation (str) – Constraint relation symbol.
rhs (AffineExpression) – Right hand side expression.

WassersteinAmbiguousExtremumAffineConstraint¶

class picos.constraints.WassersteinAmbiguousExtremumAffineConstraint(extremum, relation, rhs)[source]¶

Bases: picos.constraints.constraint.Constraint

A bound on a W_1-ambiguous expected value of a piecewise function.

class DistributionallyRobustConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Distributionally robust counterpart conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(extremum, relation, rhs)[source]¶

Construct a WassersteinAmbiguousExtremumAffineConstraint.

Parameters

extremum (RandomExtremumAffine) – Left hand side expression.
relation (str) – Constraint relation symbol.
rhs (AffineExpression) – Right hand side expression.

property maximum_form¶: The constraint posed as an upper bound on an expected maximum.

WassersteinAmbiguousSquaredNormConstraint¶

class picos.constraints.WassersteinAmbiguousSquaredNormConstraint(sqnorm, upper_bound)[source]¶

Bases: picos.constraints.constraint.Constraint

A bound on a Wasserstein-ambiguous expected value of a squared norm.

class DistributionallyRobustConversion[source]¶

Bases: picos.constraints.constraint.ConstraintConversion

Distributionally robust counterpart conversion.

classmethod convert(con, options)[source]¶: Implement convert.

classmethod predict(subtype, options)[source]¶: Implement predict.

__init__(sqnorm, upper_bound)[source]¶

Construct a WassersteinAmbiguousSquaredNormConstraint.

Parameters

sqnorm (UncertainSquaredNorm) – Uncertain squared norm to upper bound the expectation of.
upper_bound (AffineExpression) – Upper bound on the expected value.