PyROS Solver Interface

Instantiation 

The PyROS solver is invoked through the solve() method of an instance of the PyROS solver class, which can be instantiated as follows:

import pyomo.environ as pyo
import pyomo.contrib.pyros as pyros  # register the PyROS solver
pyros_solver = pyo.SolverFactory("pyros")

PyROS is designed to operate on a single-objective deterministic model (implemented as a ConcreteModel), from which the robust optimization counterpart is automatically inferred. All variables of the model should be continuous, as mixed-integer problems are not supported.

First-Stage and Second-Stage Variables 

A model may have either first-stage variables, second-stage variables, or both. PyROS automatically considers all other variables participating in the active model components to be state variables. Further, PyROS assumes that the state variables are uniquely defined by the equality constraints.

Uncertain Parameters 

Uncertain parameters can be represented by either mutable Param or fixed Var objects. Uncertain parameters cannot be directly represented by Python literals that have been hard-coded into the deterministic model.

A Param object can be made mutable at construction by passing the argument mutable=True to the Param constructor. If specifying/modifying the mutable argument is not straightforward in your context, then add the following lines of code to your script before setting up your deterministic model:

import pyomo.environ as pyo
pyo.Param.DefaultMutable = True

All Param objects declared after the preceding code statements will be made mutable by default.

Uncertainty Set 

The uncertainty set is represented by an UncertaintySet object. See the Uncertainty Sets documentation for more information.

Subordinate NLP Solvers 

PyROS requires at least one subordinate local nonlinear programming (NLP) solver (e.g., Ipopt or CONOPT) and subordinate global NLP solver (e.g., BARON or SCIP) to solve subproblems.

Note

In advance of invoking the PyROS solver, check that your deterministic model can be solved to optimality by either your subordinate local or global NLP solver.

Optional Arguments 

The optional arguments are enumerated in the documentation of the solve() method.

Like other Pyomo solver interface methods, the PyROS solve() method accepts the keyword argument options, which must be a dict mapping names of optional arguments to solve() to their desired values. If an argument is passed directly by keyword and indirectly through options, then the value passed directly takes precedence over the value passed through options.

Warning

All required arguments to the PyROS solve() method must be passed directly by position or keyword, or else an exception is raised. Required arguments passed indirectly through the options setting are ignored.

Separation Priority Ordering 

The PyROS solver supports custom prioritization of the separation subproblems (and, thus, the constraints) that are automatically derived from a given model for robust optimization. Users may specify separation priorities through:

(Recommended) Suffix components with local name pyros_separation_priority, declared on the model or any of its sub-blocks. Each entry of every such Suffix should map a Var or Constraint component to a value that specifies the separation priority of all constraints derived from that component
The optional argument separation_priority_order to the PyROS solve() method. The argument should be castable to a dict, of which each entry maps the full name of a Var or Constraint component to a value that specifies the separation priority of all constraints derived from that component

Specification via Suffix components takes precedence over specification via the solver argument separation_priority_order. Moreover, the precedence ordering among Suffix components is handled by the Pyomo SuffixFinder utility.

A separation priority can be either a (real) number (i.e., of type int, float, etc.) or None. A higher number indicates a higher priority. The default priority for all constraints is 0. Therefore a constraint can be prioritized [or deprioritized] over the default by mapping the constraint to a positive [or negative] number. In practice, critical or dominant constraints are often prioritized over algorithmic or implied constraints.

Constraints that have been assigned a priority of None are enforced subject to only the nominal uncertain parameter realization provided by the user. Therefore, these constraints are not imposed robustly and, in particular, are excluded from the separation problems.

Overview of Outputs 

Results Object 

The solve() method returns an ROSolveResults object.

When the PyROS solve() method has successfully solved a given robust optimization problem, the pyros_termination_condition attribute of the returned ROSolveResults object is set to robust_optimal if and only if:

Master problems are solved to global optimality (by passing solve_master_globally=True)
A worst-case objective focus is chosen (by setting objective_focus to worst_case)

Otherwise, the termination condition is set to robust_feasible.

The final_objective_value attribute of the results object depends on the value of the optional objective_focus argument to the solve() method:

If objective_focus is set to nominal, then the objective is evaluated subject to the nominal uncertain parameter realization
If objective_focus is set to worst_case, then the objective is evaluated subject to the uncertain parameter realization that induces the worst-case objective value

The second-stage variable and state variable values in the solution loaded to the model are evaluated similarly.

Final Solution 

PyROS automatically loads the final solution found to the model (i.e., updates the values of the variables of the deterministic model) if and only if:

The argument load_solution=True has been passed to PyROS (occurs by default)
The pyros_termination_condition attribute of the returned ROSolveResults object is either robust_optimal or robust_feasible

Otherwise, the solution is lost.

If a solution is loaded to the model, then, as mentioned in our discussion of the results object, the second-stage variables and state variables of the model are updated according to the value of the optional objective_focus argument to the solve() method. The uncertain parameter objects are left unchanged.

Solver Output Log 

When the PyROS solve() method is invoked to solve an RO problem, the progress and final result are reported through a highly configurable logging system. See the Solver Output Log documentation for more information.