# 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. ComplexAffineConstraint An equality between affine expressions, at least one being complex. ComplexLMIConstraint Complex linear matrix inequality. ConicQuadraticConstraint Bound on a nearly convex quadratic expression. 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 -th root of a matrix determinant. ExpConeConstraint Exponential cone membership constraint. 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 -norm. NonconvexQuadraticConstraint Bound on a nonconvex quadratic expression. NuclearNormConstraint Nuclear norm of a matrix. PowerTraceConstraint Bound on the trace over the -th power of a matrix. RSOCConstraint Rotated second order cone membership constraint. SOCConstraint Second order (-norm, Lorentz) cone membership constraint. SimplexConstraint (Symmetrized, truncated) simplex membership constraint. SpectralNormConstraint Spectral norm of a matrix. SumExponentialsConstraint Upper bound on a sum of exponentials. SumExtremesConstraint Bound on a sum over extreme (eigen)values. VectorNormConstraint Bound on a (generalized) vector -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_expcone Implementation of ExpConeConstraint. 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_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_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.

## Classes¶

### AbsoluteValueConstraint¶

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

Upper bound on an absolute value.

class AffineConversion[source]

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

### AffineConstraint¶

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

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 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 right hand side minus the left 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.

### ComplexAffineConstraint¶

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

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

class RealConversion[source]

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

### ComplexLMIConstraint¶

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

Complex linear matrix inequality.

class RealConversion[source]

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.

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

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 , 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 with representable as a squared norm. In this case, the additional assumptions required for a conic reformulation are and .

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]

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.

### 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_variables(new_variables)[source]

Make the constraint concern a different set of variables.

See replace_variables 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_variables, so that the copy can be identified with the original despite pointing to different expressions and variable objects.

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 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]

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

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

Bound on a convex quadratic expression.

class ConicConversion[source]

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]

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

class Conversion[source]

-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

### ExpConeConstraint¶

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

Exponential cone membership constraint.

An exponential cone constraint stating that fulfills .

__init__(element, customString=None)[source]

Construct an ExpConeConstraint.

Parameters
• element (AffineExpression) – Three-dimensional expression representing the vector .

• customString (str) – Optional string description.

property x
property y
property z

### FlowConstraint¶

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

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]

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_variables(var_map)[source]
property variables

### GeometricMeanConstraint¶

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

Lower bound on a geometric mean.

class RSOCConversion[source]

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

### KullbackLeiblerConstraint¶

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

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]

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
property denominator

The of the divergence, or .

property numerator

The of the divergence.

### LMIConstraint¶

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

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 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]

Lower bound on a logarithm.

class ExpConeConversion[source]

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

### LogSumExpConstraint¶

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

Upper bound on a logarithm of a sum of exponentials.

class ExpConeConversion[source]

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
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]

Upper bound on a matrix -norm.

class VectorNormConversion[source]

Upper bound on a -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

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

Bound on a nonconvex quadratic expression.

__init__(lhs, relation, rhs)[source]

Construct a NonconvexQuadraticConstraint.

Parameters
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]

Nuclear norm of a matrix.

class Conversion[source]

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

### PowerTraceConstraint¶

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

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

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

class Conversion[source]

Bound on the -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

### RSOCConstraint¶

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

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.

### SOCConstraint¶

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

Second order (-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.

### SimplexConstraint¶

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

(Symmetrized, truncated) simplex membership constraint.

class AffineConversion[source]

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]

Spectral norm of a matrix.

class Conversion[source]

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

### SumExponentialsConstraint¶

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

Upper bound on a sum of exponentials.

class ConicConversion[source]

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]

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
property denominator

The of the sum, or .

property lse_representable

Whether this can be converted to a logarithmic constraint.

property numerator

The of the sum.

### SumExtremesConstraint¶

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

Bound on a sum over extreme (eigen)values.

class Conversion[source]

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]

Bound on a (generalized) vector -norm.

class Conversion[source]

Bound on a (generalized) -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.