picos.reforms

Optimization problem reformulation recipes.

Outline

Classes

AbsoluteValueToAffineReformulation

Reformulation created from AbsoluteValueConstraint.AffineConversion.

ComplexAffineToRealReformulation

Reformulation created from ComplexAffineConstraint.RealConversion.

ComplexLMIToRealReformulation

Reformulation created from ComplexLMIConstraint.RealConversion.

ConicQuadraticReformulation

Reformulation created from ConicQuadraticConstraint.Conversion.

ConvexQuadraticToConicReformulation

Reformulation created from ConvexQuadraticConstraint.ConicConversion.

DetRootNReformulation

Reformulation created from DetRootNConstraint.Conversion.

Dualization

Lagrange dual problem reformulation.

EpigraphReformulation

Epigraph reformulation.

ExtraOptions

Helper reformulation to apply temporary options.

FlowReformulation

Reformulation created from FlowConstraint.Conversion.

GeometricMeanToRSOCReformulation

Reformulation created from GeometricMeanConstraint.RSOCConversion.

KullbackLeiblerToExpConeReformulation

Reformulation created from KullbackLeiblerConstraint.ExpConeConversion.

LogSumExpToExpConeReformulation

Reformulation created from LogSumExpConstraint.ExpConeConversion.

LogToExpConeReformulation

Reformulation created from LogConstraint.ExpConeConversion.

MatrixNormToVectorNormReformulation

Reformulation created from MatrixNormConstraint.VectorNormConversion.

NuclearNormReformulation

Reformulation created from NuclearNormConstraint.Conversion.

PowerTraceReformulation

Reformulation created from PowerTraceConstraint.Conversion.

Reformulation

Base class for problem reformulations.

SimplexToAffineReformulation

Reformulation created from SimplexConstraint.AffineConversion.

SpectralNormReformulation

Reformulation created from SpectralNormConstraint.Conversion.

SumExponentialsToConicReformulation

Reformulation created from SumExponentialsConstraint.ConicConversion.

SumExponentialsToLogSumExpReformulation

Reformulation created from SumExponentialsConstraint.LogSumExpConversion.

SumExtremesReformulation

Reformulation created from SumExtremesConstraint.Conversion.

VectorNormReformulation

Reformulation created from VectorNormConstraint.Conversion.

Submodules

picos.reforms.reform_constraint

Reformulations that concern a particular type of constraint.

picos.reforms.reform_dualize

Implementation of Dualization.

picos.reforms.reform_epigraph

Implementation of EpigraphReformulation.

picos.reforms.reform_options

Implements a helper reformulation to apply temporary options.

picos.reforms.reformulation

Backend for problem reformulation classes.

Classes

AbsoluteValueToAffineReformulation

class picos.reforms.AbsoluteValueToAffineReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from AbsoluteValueConstraint.AffineConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_absolute.AbsoluteValueConstraint

CONVERSION_TYPE

alias of picos.constraints.con_absolute.AbsoluteValueConstraint.AffineConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

ComplexAffineToRealReformulation

class picos.reforms.ComplexAffineToRealReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from ComplexAffineConstraint.RealConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_affine.ComplexAffineConstraint

CONVERSION_TYPE

alias of picos.constraints.con_affine.ComplexAffineConstraint.RealConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

ComplexLMIToRealReformulation

class picos.reforms.ComplexLMIToRealReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from ComplexLMIConstraint.RealConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_lmi.ComplexLMIConstraint

CONVERSION_TYPE

alias of picos.constraints.con_lmi.ComplexLMIConstraint.RealConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

ConicQuadraticReformulation

class picos.reforms.ConicQuadraticReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from ConicQuadraticConstraint.Conversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_quadratic.ConicQuadraticConstraint

CONVERSION_TYPE

alias of picos.constraints.con_quadratic.ConicQuadraticConstraint.Conversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

ConvexQuadraticToConicReformulation

class picos.reforms.ConvexQuadraticToConicReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from ConvexQuadraticConstraint.ConicConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_quadratic.ConvexQuadraticConstraint

CONVERSION_TYPE

alias of picos.constraints.con_quadratic.ConvexQuadraticConstraint.ConicConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

DetRootNReformulation

class picos.reforms.DetRootNReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from DetRootNConstraint.Conversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_detrootn.DetRootNConstraint

CONVERSION_TYPE

alias of picos.constraints.con_detrootn.DetRootNConstraint.Conversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

Dualization

class picos.reforms.Dualization(theObject)[source]

Bases: picos.reforms.reformulation.Reformulation

Lagrange dual problem reformulation.

backward(solution)[source]

Implement backward.

forward()[source]

Implement forward.

classmethod predict(footprint)[source]

Implement predict.

classmethod supports(footprint)[source]

Implement supports.

update()[source]

Implement update.

SUPPORTED = <Specification: Optimize AffineExpression subject to AffineConstraint, SOCConstraint, RSOCConstraint, LMIConstraint using RealVariable, ComplexVariable, SymmetricVariable, SkewSymmetricVariable, HermitianVariable, LowerTriangularVariable, UpperTriangularVariable and any options.>

EpigraphReformulation

class picos.reforms.EpigraphReformulation(theObject)[source]

Bases: picos.reforms.reformulation.Reformulation

Epigraph reformulation.

backward(solution)[source]

Implement backward.

forward()[source]

Implement forward.

classmethod predict(footprint)[source]

Implement predict.

classmethod supports(footprint)[source]

Implement supports.

update()[source]

Implement update.

NEW_OBJECTIVE = <ExpressionType: AffineExpression[shape=(1, 1)|constant=False|nonneg=False]>

ExtraOptions

class picos.reforms.ExtraOptions(theObject)[source]

Bases: picos.reforms.reformulation.Reformulation

Helper reformulation to apply temporary options.

This reformulation is different from all others in a number of ways:

  • It doesn’t change the footprint of any problem.

  • It is automatically the first reformulation in any strategy.

  • It is the only reformulation whose execute accepts a keyword argument sequence of additional options to use.

  • It is the only reformulation that can be skipped entirely (by setting self.output = self.input).

The job of this reformulation is to apply temporary options passed to Problem.solve so that subsequent reformulations can find their options stored in their input problem.

backward(solution)[source]

Dummy-implement backward.

execute(**extra_options)[source]

Override execute.

Adds the extra_options argument and attempts to perform as little reformulation work as possible.

forward()[source]

Dummy-implement forward.

classmethod predict(footprint)[source]

Implement predict.

classmethod supports(footprint)[source]

Implement supports.

update()[source]

Dummy-implement update.

FlowReformulation

class picos.reforms.FlowReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from FlowConstraint.Conversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_flow.FlowConstraint

CONVERSION_TYPE

alias of picos.constraints.con_flow.FlowConstraint.Conversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

GeometricMeanToRSOCReformulation

class picos.reforms.GeometricMeanToRSOCReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from GeometricMeanConstraint.RSOCConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_geomean.GeometricMeanConstraint

CONVERSION_TYPE

alias of picos.constraints.con_geomean.GeometricMeanConstraint.RSOCConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

KullbackLeiblerToExpConeReformulation

class picos.reforms.KullbackLeiblerToExpConeReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from KullbackLeiblerConstraint.ExpConeConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_kldiv.KullbackLeiblerConstraint

CONVERSION_TYPE

alias of picos.constraints.con_kldiv.KullbackLeiblerConstraint.ExpConeConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

LogSumExpToExpConeReformulation

class picos.reforms.LogSumExpToExpConeReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from LogSumExpConstraint.ExpConeConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_logsumexp.LogSumExpConstraint

CONVERSION_TYPE

alias of picos.constraints.con_logsumexp.LogSumExpConstraint.ExpConeConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

LogToExpConeReformulation

class picos.reforms.LogToExpConeReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from LogConstraint.ExpConeConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_log.LogConstraint

CONVERSION_TYPE

alias of picos.constraints.con_log.LogConstraint.ExpConeConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

MatrixNormToVectorNormReformulation

class picos.reforms.MatrixNormToVectorNormReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from MatrixNormConstraint.VectorNormConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_matnorm.MatrixNormConstraint

CONVERSION_TYPE

alias of picos.constraints.con_matnorm.MatrixNormConstraint.VectorNormConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

NuclearNormReformulation

class picos.reforms.NuclearNormReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from NuclearNormConstraint.Conversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_matnorm.NuclearNormConstraint

CONVERSION_TYPE

alias of picos.constraints.con_matnorm.NuclearNormConstraint.Conversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

PowerTraceReformulation

class picos.reforms.PowerTraceReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from PowerTraceConstraint.Conversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_powtrace.PowerTraceConstraint

CONVERSION_TYPE

alias of picos.constraints.con_powtrace.PowerTraceConstraint.Conversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

Reformulation

class picos.reforms.Reformulation(theObject)[source]

Bases: abc.ABC

Base class for problem reformulations.

Abstract base class for a reformulation from one (possibly already reformulated) problem form to another.

__init__(theObject)[source]

Initialize Reformulation instances.

Parameters

theObject (Problem or Reformulation) – The input to work on; either an optimization problem or the (future) output of another reformulation.

abstract backward(solution)[source]

Translate back a solution from reformulated to original problem.

Transforms a single solution to output to a solution of input.

The method is allowed to modify the solution; it is not necessary to work on a copy. In particular, attach_to can be used if forward has created a deep copy of the problem.

execute()[source]

Reformulate the problem and obtain a solution from the result.

For this to work there needs to be a solver instance at the end of the reformulation pipeline, which would implement its own version of this method that actually solves the problem and produces the first solution.

abstract forward()[source]

Perform the initial problem reformulation.

Creates a modified copy or clone of the problem in input and stores it as output.

See copy and clone for the differences between a copy and a clone.

Implementations are supposed to do the necessary bookkeeping so that backward can transform a solution to the new problem back to a solution of the original problem.

abstract classmethod predict(footprint)[source]

Predict the reformulation’s effect on a problem footprint.

Given a problem footprint, returns another problem footprint that a problem with the former one would be reformulated to.

This is used to predict the effects of a reformulation when planning a solution strategy without the cost of actually transforming a problem.

reset()[source]

Reset the pipeline from this reformulation onward.

This is done whenever a reformulation does not implement update so that succeeding reformulations do not attempt to update a problem which was completely rewritten as this may be inefficient.

abstract classmethod supports(footprint)[source]

Whether the reformulation affects problems with the given footprint.

The reformulation must support every problem with such a footprint and the resulting problem should have a changed footprint.

abstract update()[source]

Update a previous problem reformulation.

Updates output and related bookkeeping information with respect to changes in input.

Raises

NotImplementedError – If performing an update is not feasible for the reformulation.

property input

The input problem.

output

The output problem.

successor

The next reformulation in the pipeline.

property verbosity

Verbosity level of the reformulation; same as for input problem.

SimplexToAffineReformulation

class picos.reforms.SimplexToAffineReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from SimplexConstraint.AffineConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_simplex.SimplexConstraint

CONVERSION_TYPE

alias of picos.constraints.con_simplex.SimplexConstraint.AffineConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

SpectralNormReformulation

class picos.reforms.SpectralNormReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from SpectralNormConstraint.Conversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_matnorm.SpectralNormConstraint

CONVERSION_TYPE

alias of picos.constraints.con_matnorm.SpectralNormConstraint.Conversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

SumExponentialsToConicReformulation

class picos.reforms.SumExponentialsToConicReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from SumExponentialsConstraint.ConicConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_sumexp.SumExponentialsConstraint

CONVERSION_TYPE

alias of picos.constraints.con_sumexp.SumExponentialsConstraint.ConicConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

SumExponentialsToLogSumExpReformulation

class picos.reforms.SumExponentialsToLogSumExpReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from SumExponentialsConstraint.LogSumExpConversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_sumexp.SumExponentialsConstraint

CONVERSION_TYPE

alias of picos.constraints.con_sumexp.SumExponentialsConstraint.LogSumExpConversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

SumExtremesReformulation

class picos.reforms.SumExtremesReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from SumExtremesConstraint.Conversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_sumxtr.SumExtremesConstraint

CONVERSION_TYPE

alias of picos.constraints.con_sumxtr.SumExtremesConstraint.Conversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

VectorNormReformulation

class picos.reforms.VectorNormReformulation(theObject)

Bases: picos.reforms.reformulation.Reformulation

Reformulation created from VectorNormConstraint.Conversion.

CONSTRAINT_TYPE

alias of picos.constraints.con_vecnorm.VectorNormConstraint

CONVERSION_TYPE

alias of picos.constraints.con_vecnorm.VectorNormConstraint.Conversion

__init__(theObject)

Implement __init__.

backward(solution)

Implement backward.

forward()

Implement forward.

classmethod predict(footprint)

Implement predict.

classmethod supports(footprint)

Implement supports.

update()

Implement update.

Data

picos.reforms.SORTED_REFORMS

A sequence of reformulations in topological order.