EF Directly

If we are speaking carefully, we would say that any method that solves a problem of optimization under undertainty using scenarios is solving the extensive form (EF). Some of the methods solve it by decomposition. When not speaking carefully, we refer to “solving the EF” to mean “passing the EF in its entirety directly to a general-purpose solver.” There are two closely related ways to do this in mpi-sppy.

Preferred method: mpisppy.opt.ef.ExtensiveForm

There is a class for the EF that roughly matches the “look and feel” of a hub class, but does not function as a hub.

class mpisppy.opt.ef.ExtensiveForm(options, all_scenario_names, scenario_creator, scenario_creator_kwargs=None, all_nodenames=None, model_name=None, suppress_warnings=False)

Bases: SPBase

Create and solve an extensive form.

ef

Pyomo model of the extensive form.

Type:

pyomo.environ.ConcreteModel

solver

Solver produced by the Pyomo solver factory.

Parameters:

• options (dict) – Dictionary of options. May include a solver key to specify which solver name to use on the EF.

• all_scenario_names (list) – List of the names of each scenario in the EF (strings).

• scenario_creator (callable) – Scenario creator function, which takes as input a scenario name, and returns a Pyomo model of that scenario.

• scenario_creator_kwargs (dict, optional) – Keyword arguments passed to scenario_creator.

• all_nodenames (list, optional) – List of all node names, incl. leaves. Can be None for two-stage problem.

• model_name (str, optional) – Name of the resulting EF model object.

• suppress_warnings (bool, optional) – Boolean to suppress warnings when building the EF. Default is False.

Note: allowing use of the “solver” option key is for backward compatibility

get_objective_value()

Retrieve the objective value.

Returns:

Objective value.

Return type:

float

Raises:

ValueError – If optimal objective value could not be retrieved.

get_root_solution()

Get the value of the variables at the root node.

Returns:

Dictionary mapping variable name (str) to variable value (float) for all variables at the root node.

Return type:

dict

nonants()

An iterator to give representative Vars subject to non-anticipitivity Args: None

Yields:

tree node name, full EF Var name, Var value

nonants_to_csv(filename)

Dump the nonant vars from an ef to a csv file; truly a dump… :param filename: the full name of the csv output file :type filename: str

scenarios()

An iterator to give the scenario sub-models in an ef Args: None

Yields:

scenario name, scenario instance (str, ConcreteModel)

solve_extensive_form(solver_options=None, tee=False)

Solve the extensive form.

Parameters:

• solver_options (dict, optional) – Dictionary of solver-specific options (e.g. Gurobi options, CPLEX options, etc.).

• tee (bool, optional) – If True, displays solver output. Default False.

Returns:

Result returned by the Pyomo solve method.

Return type:

pyomo.opt.results.results_.SolverResults

Other method: mpisppy.utils.sputils.create_EF

The use of this function does not require the installation of mpi4py. Its use is illustrated in examples.farmer.farmer_ef.py. Here are the arguments to the function:

mpisppy.utils.sputils.create_EF(scenario_names, scenario_creator, scenario_creator_kwargs=None, EF_name=None, suppress_warnings=False, nonant_for_fixed_vars=True)

Create a ConcreteModel of the extensive form.

Parameters:

• scenario_names (list of str) – Names for each scenario to be passed to the scenario_creator function.

• scenario_creator (callable) – Function which takes a scenario name as its first argument and returns a concrete model corresponding to that scenario.

• scenario_creator_kwargs (dict, optional) – Options to pass to scenario_creator.

• EF_name (str, optional) – Name of the ConcreteModel of the EF.

• suppress_warnings (boolean, optional) – If true, do not display warnings. Default False.

• nonant_for_fixed_vars (bool--optional) – If True, enforces non-anticipativity constraints for all variables, including those which have been fixed. Default is True.

Returns:

ConcreteModel of extensive form with explicit non-anticipativity constraints.

Return type:

EF_instance (ConcreteModel)

Note

If any of the scenarios produced by scenario_creator do not have a ._mpisppy_probability attribute, this function displays a warning, and assumes that all scenarios are equally likely.