DSP DocumentationRelease 0.2.1

Kibaek Kim and Victor M. Zavala

Oct 09, 2017

Contents

1 DSP Overview 31.1 Decomposition of SMIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2 Design of the DSP Development Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3 General Dual Decomposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Installation 92.1 Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3 Build and Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.4 Julia Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3 Quick Start Guide 133.1 Modeling in JuMP.jl and Dsp.jl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.2 Modeling General Decomposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4 Julia Interface Functions 17

5 C Interface Functions 19

Bibliography 21

i

ii

DSP Documentation, Release 0.2.1

DSP is an object-oriented open-source software package written in C++ for solving structured programming problemssuch as stochastic mixed-integer programming (SMIP). The current version of DSP has implemented decompositionmethods for solving SMIP problems:

• Dual decomposition – DSP has implemented new dual decomposition methods

– Interior-point cutting-plane method with early termination criteria

– Eliminating infeasible first-stage solutions

– Cutting-plane method

– Subgradient method

• Benders decomposition

• Extensive form solution

Credits

DSP has been developed and is maintained by:

• Kibaek Kim, Mathematics and Computer Science Division, Argonne National Laboratory.

• Victor M. Zavala, Department of Chemical and Biological Engineering, University of Wisconsin-Madison.

Publication

• Kibaek Kim and Victor M. Zavala. Algorithmic innovations and software for the dual decomposition methodapplied to stochastic mixed-integer programs Optimization Online, 2015

Acknowledgements

This material is based upon work supported by the U.S. Department of Energy, Office of Science, under contractnumber DE-AC02-06CH11357. We gratefully acknowledge the computing resources provided on Blues, a high-performance computing cluster operated by the Laboratory Computing Resource Center at Argonne National Labora-tory. We thank E. Michael Gertz and Stephen Wright for providing the OOQP software package.

Contents:

Contents 1

DSP Documentation, Release 0.2.1

2 Contents

CHAPTER 1

DSP Overview

This section provides an introduction to DSP: Decompositions for Structured Programming. DSP is an object-orientedopen-source software package written in C++ for solving structured programming problems. DSP implements differ-ent solution methods for solving stochastic mixed-integer programming (SMIP) problems. The constraint matrix ofSMIP problem has a block-angular structure as follows:⎡⎢⎢⎢⎢⎢⎣

𝐴𝑇1 𝑊1

𝑇2 𝑊2

.... . .

𝑇𝑆 𝑊𝑆

⎤⎥⎥⎥⎥⎥⎦

⎡⎢⎢⎢⎢⎢⎣𝑥𝑦1𝑦2...𝑦𝑆

⎤⎥⎥⎥⎥⎥⎦ =

⎡⎢⎢⎢⎢⎢⎣𝑏ℎ1

ℎ2

...ℎ𝑆

⎤⎥⎥⎥⎥⎥⎦The block-angular structure leads to different decomposition methods that enable large-scale optimization problems(e.g., stochastic programming problmes) to be efficiently solved or approximated particularly on high-performancecomputing systems. DSP exploits the block-angular structure of SMIP and provides the following methods:

• Parallel dual decomposition methods

– Different dual update methods:

* Interior-point cutting-plane method with early termination criteria

* Cutting-plane method

* Subgradient method

– Effectively eliminating infeasible first-stage solution and thus aids to obtain upper bounds.

– Significant reductions in number of iterations and solution time, as compared with standard dual decom-position methods.

– Parallel runs on high performance computing systems using MPI

– Scaling in number of scenarios with many computing cores

• Parallel Benders decomposition methods

– Solving stochastic program with first-stage mixed-integer variables

3

DSP Documentation, Release 0.2.1

– Parallel runs with many cores using OpenMP

• Subgradient method

• Extensive form solution

Note: The methods implemented in DSP are formally described in [KZ15].

Additional features of DSP include:

• Interface for the JuMP.jl package in Julia

– JuMP.jl – an algebraic modeling package for mathematical programming in Julia

– User can run DSP in parallel via Julia without coding any MPI codes.

• Solver independence

– Any external solvers can be used in DSP through the SolverInterface class

– Current support: SCIP, SOPLEX, CLP, OOQP

• Parallel dual decomposition with general coupling constraints

Decomposition of SMIP

Stochastic mixed-integer programming (SMIP) is an optimization modeling framework for problems that involvemixed-integer decision variables and uncertain parameters. We consider the following two-stage SMIP problem:

𝑧 := min𝑥

{︀𝑐𝑇𝑥+ E𝜉 [𝑄(𝑥, 𝜉)] : 𝐴𝑥 = 𝑏, 𝑥 ∈ 𝑋

}︀,

where the scenario recourse function

𝑄(𝑥, 𝜉) := min𝑦

{𝑞(𝜉)𝑇 𝑦 : 𝑊 (𝜉)𝑦 = ℎ(𝜉)− 𝑇 (𝜉)𝑥, 𝑦 ∈ 𝑌 }.

We assume that the random parameter 𝜉 follows a discrete distribution with finite support {𝜉1, . . . , 𝜉𝑆} and correspond-ing probabilities 𝑝1, . . . , 𝑝𝑆 (continuous distributions can be handled by using a sample-average approximation).

Note: The sets 𝑋 ⊆ R𝑛1+ and 𝑌 ⊆ R𝑛2

+ represent integer restrictions on a subset of the decision variables 𝑥 and 𝑦,respectively.

The first-stage problem data comprises 𝐴 ∈ R𝑚1×𝑛1 , 𝑏 ∈ R𝑚1 , and 𝑐 ∈ R𝑛1 . The second-stage data are givenby 𝑇 (𝜉𝑠) ∈ R𝑚2×𝑛1 ,𝑊 (𝜉𝑠) ∈ R𝑚2×𝑛2 , ℎ(𝜉𝑠) ∈ R𝑚2 , and 𝑞(𝜉𝑠) ∈ R𝑛2 . For simplicity, we use the notation(𝑇𝑠,𝑊𝑠, ℎ𝑠, 𝑞𝑠) for 𝑠 ∈ 𝒮 := {1, . . . , 𝑆}.

Dual Decomposition

Dual decomposition considers SMIP of the extensive form

𝑧 = min𝑥𝑠,𝑦𝑠

∑︁𝑠∈𝒮

𝑝𝑠(︀𝑐𝑇𝑥𝑠 + 𝑞𝑇𝑠 𝑦𝑠

)︀s.t.

∑︁𝑠∈𝒮

𝐻𝑠𝑥𝑠 = 0 (Nonanticipativity constraint)

(𝑥𝑠, 𝑦𝑠) ∈ 𝐺𝑠, ∀𝑠 ∈ 𝒮

(1.1)

4 Chapter 1. DSP Overview

DSP Documentation, Release 0.2.1

where the scenario feasibility set is defined as

𝐺𝑠 := {(𝑥𝑠, 𝑦𝑠) : 𝐴𝑥𝑠 = 𝑏, 𝑇𝑠𝑥𝑠 +𝑊𝑠𝑦𝑠 = ℎ𝑠, 𝑥𝑠 ∈ 𝑋, 𝑦𝑠 ∈ 𝑌 },

the nonanticipativity constraints represent the equations 𝑥1 = 𝑥𝑆 and 𝑥𝑠 = 𝑥𝑠−1 for 𝑠 = 2, . . . , 𝑆, and 𝐻𝑠 is asuitable 𝑆 · 𝑛1 × 𝑛1 matrix.

Note: SMIP may not have relatively complete recourse. Without this property, there can exist (�̂�, 𝑦) such that(�̂�, 𝑦) ∈ 𝐺𝑠 and (�̂�, 𝑦) /∈ 𝐺𝑠′ for 𝑠 ̸= 𝑠′.

We apply a Lagrangian relaxation of these constraints to obtain the Lagrangian dual function of (1.1):

𝐷(𝜆) := min𝑥𝑠,𝑦𝑠

{︃∑︁𝑠∈𝒮

𝐿𝑠(𝑥𝑠, 𝑦𝑠, 𝜆) : (𝑥𝑠, 𝑦𝑠) ∈ 𝐺𝑠, ∀𝑠 ∈ 𝒮

}︃,

where

𝐿𝑠(𝑥𝑠, 𝑦𝑠, 𝜆) := 𝑝𝑠(︀𝑐𝑇𝑥𝑠 + 𝑞𝑇𝑠 𝑦𝑠

)︀+ 𝜆𝑇 (𝐻𝑠𝑥𝑠).

For fixed 𝜆, the Lagrangian dual function can be decomposed as

𝐷(𝜆) =∑︁𝑠∈𝒮

𝐷𝑠(𝜆),

where

𝐷𝑠(𝜆) := min𝑥𝑠,𝑦𝑠

{𝐿𝑠(𝑥𝑠, 𝑦𝑠, 𝜆) : (𝑥𝑠, 𝑦𝑠) ∈ 𝐺𝑠} .

We thus seek to obtain the best lower bound for (1.1) by solving the maximization problem (the Lagrangian dualproblem):

𝑧LD := max𝜆

∑︁𝑠∈𝒮

𝐷𝑠(𝜆).

Benders Decomposition

Benders decomposition considers SMIP of the form

min 𝑐𝑇𝑥+∑︁𝑠∈ ̃︀𝒮

𝑝𝑠𝑞𝑇𝑠 𝑦𝑠 + 𝜃

s.t. 𝐴𝑥 = 𝑏, 𝑥 ∈ 𝑋

𝑇𝑠𝑥+𝑊𝑠𝑦𝑠 = ℎ𝑠, 𝑦𝑠 ∈ 𝑌, ∀𝑠 ∈ ̃︀𝒮,𝜃 ≥

∑︁𝑠∈𝑆∖ ̃︀𝒮

𝑝𝑠𝑄(𝑥, 𝜔𝑠),

where ̃︀𝒮 is a subset of 𝒮 given by user. The method performs outer-approximation of the recourse function 𝑄(𝑥, 𝜔𝑠) byiteratively adding a set of linear inequalities. DSP implements a standard Benders decomposition method for solvingSMIP problems with first-stage mixed-integer variables.

Warning: The second-stage integrality is relaxed in DSP solution.

1.1. Decomposition of SMIP 5

DSP Documentation, Release 0.2.1

Design of the DSP Development Framework

The software design is object-oriented and implemented in C++. It consists of Model classes and Solver classes forhandling optimization models and scenario data.

Model Classes

An abstract Model class is designed to define a generic optimization model data structure. The StoModel class definesthe data structure for generic stochastic programs, including two-stage stochastic programs and multistage stochasticprograms. The underlying data structure of StoModel partially follows the SMPS format. The class also defines corefunctions for problem decomposition. The TssModel class derived defines the member variables and functions specificto two-stage stochastic programs and decompositions. Following the design of the model classes, users are able toderive new classes for their own purposes and efficiently manage model structure provided from several interfaces(e.g., StochJuMP and SMPS).

Solver Classes

An abstract Solver class is designed to provide different algorithms for solving stochastic programming problemsdefined in the Model class. DSP implements the TssSolver class to define solvers specific to two-stage stochasticprograms. From the TssSolver class, three classes are derived for each method: TssDe, TssBd, and TssDd.

• The TssDe class implements a wrapper of external solvers to solve the extensive form of two-stage stochasticprograms. The extensive form is constructed and provided by the TssModel class.

• The TssBd class implements a Benders decomposition method for solving two-stage stochastic programs withcontinuous recourse. A proper decomposition of the model is performed and provided by the TssModel class,while the second-stage integrality restriction is automatically relaxed. Depending on parameters provided, Tss-Model can make a different form of the problem decomposition for TssBd. For example, the user can specify thenumber of cuts added per iteration, which determines the number of auxiliary variables in the master problemof Benders decomposition. Moreover, the Benders master can be augmented for a subset ̃︀𝒮 of scenarios.

• The TssDd class implements the proposed dual decomposition method for solving two-stage stochastic programswith mixed-integer recourse. For this method, an abstract TssDdMaster class is designed to implement methodsfor updating the dual variables. The subgradient method and the cutting-plane method are implemented in suchderived classes. Moreover, a subclass derived from the TssBd is reused for implementing the Benders-typecutting-plane procedure for the subproblems. An 𝑙∞-norm trust region is also applied in order to stabilize thecutting-plane method. The rule of updating the trust region follows that proposed in [LW03]. Users can alsoimplement their own method for updating the dual variables.

External Solver Interface Classes

DSP uses external MIP solvers to solve subproblems under different decomposition methods. The SolverInterfaceclass is an abstract class to create interfaces to the decomposition methods implemented. Several classes are derivedfrom the abstract class in order to support specific external solvers. The current implementation supports the followingexternal optimization solvers:

• Linear programming solvers

– Clp [For]

– SoPlex [Wun96]

– OOQP [GW03]

• Mixed-integer programming solver

6 Chapter 1. DSP Overview

DSP Documentation, Release 0.2.1

– SCIP [Ach09]

Users familiar with the COIN-OR Open Solver Interface [SLadanyiR04] should easily be able to use the SolverInter-faceOsi class to derive classes for other solvers (e.g., CPLEX [IBMCorp14], Gurobi [GurobiOptimizationInc15]).

Parallelization

The proposed dual decomposition method can be run on distributed memory and on shared memory computing systemswith multiple cores. The implementation protocol is MPI. In a distributed memory environment, the scenario data andcorresponding Lagrangian subproblems are distributed to multiple processors based on scenario indices. The rootprocessor updates the Lagrangian multipliers and solves a subset of the subproblems. When solving the subproblemsin distributed computing nodes, subproblem solutions and the dual variables must be communicated with the rootprocessor. In addition, each computing node communicates the primal first-stage solutions and the valid inequalitiesgenerated for a subproblem with the rest of the nodes.

General Dual Decomposition

The dual decomposition method for SMIP is a special case of Lagrangian decomposition. DSP implements general La-grangian decomposition with parallelization of the subproblems. More precisely, DSP is able to decompose problemsof the form

min 𝑐𝑇1 𝑥1 + 𝑐𝑇2 𝑥2 + . . .+ 𝑐𝑇𝑘 𝑥𝑘

s.t. 𝐴1𝑥1 = 𝑏1,

𝐴2𝑥2 = 𝑏2,

...𝐴𝑘𝑥𝑘 = 𝑏𝑘,

𝐻1𝑥1 +𝐻2𝑥2 + . . .+𝐻𝑘𝑥𝑘 = 𝑑,

𝑥 ∈ 𝑋

(1.2)

where 𝑥 ∈ 𝑋 represents integrality constraints. Here, 𝐻1𝑥1 + . . . +𝐻𝑘𝑥𝑘 = 𝑑 are the constraints we are interestedin relaxing with Lagrangian relaxation, called coupling constraints. For instance, in the SMIP case, the couplingconstraints are the nonanticipativity constraints. The coupling constraints may include inequalities. Note that when𝑘 = 1, this framework is reduced to standard Lagrangian relaxation.

As with dual decomposition for SMIP, in this general context DSP applies Lagrangian relaxation to the couplingconstraints to obtain the Lagrangian dual function

𝐷(𝜆) := min𝑥𝑠

{︃𝑘∑︁

𝑠=1

𝐿𝑠(𝑥𝑠, 𝜆)− 𝜆𝑇 𝑑 : 𝐴𝑠𝑥𝑠 = 𝑏𝑠, ∀𝑠 = 1, . . . , 𝑘

}︃,

where

𝐿𝑠(𝑥𝑠, 𝜆) := 𝑐𝑇𝑠 𝑥𝑠 + 𝜆𝑇 (𝐻𝑠𝑥𝑠).

Therefore, the Lagrangian dual function can be decomposed for fixed 𝜆 as

𝐷(𝜆) =

(︃𝑘∑︁

𝑠=1

𝐷𝑠(𝜆)

)︃− 𝜆𝑇 𝑑,

where

𝐷𝑠(𝜆) := min𝑥𝑠

{𝐿𝑠(𝑥𝑠, 𝑦𝑠, 𝜆) : 𝐴𝑠𝑥𝑠 = 𝑏𝑠} .

1.3. General Dual Decomposition 7

DSP Documentation, Release 0.2.1

We seek to obtain a dual bound for (1.2) by solving the maximization problem (the Lagrangian dual problem):

𝑧LD := max𝜆

(︃𝑘∑︁

𝑠=1

𝐷𝑠(𝜆)− 𝜆𝑇 𝑑

)︃.

If the coupling constraints include inequalities, additional nonnegativity or nonpositivity constraints are imposed on𝜆.

The implementation of dual decomposition in DSP treats the SMIP case as a special case of Lagrangian decomposition.Thus, the same code is used both for SMIP and this general setting. In the parallelization, only the necessary parts of𝜆 are communicated to each subproblem (i.e. 𝜆𝑖‘s with nonzero objective coefficients in the subproblem).

For instructions on how to model general dual decomposition with DSP, see the Quick Start Guide.

Note: The generation of valid inequalities for scenarios and the primal bound heuristic described in [KZ15] arespecific to SMIPs. Therefore, they are not supported in this general framework. Benders decomposition is also notsupported in a general framework.

8 Chapter 1. DSP Overview

CHAPTER 2

Installation

This guide describes the prerequisites for installation and how to install DSP and Julia interface.

Download

You can clone this repository in your preferred directory by typing:

git clone https://github.com/Argonne-National-Laboratory/DSP.git

Prerequisites

We recommend to install and run DSP on a Linux machine with an appropriate MPI library. The software packagesnecessary to build the source code of DSP are listed below.

NOTE: We have also tested installing and running DSP on MacOSX (10.9 or later). We will prepare the documentationfor that soon. For now, please email and consult us for how to install and run DSP on MacOSX.

Build Essentials

You can install the build essential packages by using the shell script ./get.essentials in the DSP project repos-itory or by manually installing the packages.

Using ./get.essentials script

You can run the apt-get commands to install the packages required for DSP:

sudo ./get.essentials

9

DSP Documentation, Release 0.2.1

Manual installation

If you have used ./get.essentials, then you can ignore this section and directly go to External software pack-ages. Before using apt-get, please update the package list:

sudo apt-get update

• CMake – This package is required to build DSP and all the other external software packages. It is availablefrom http://www.cmake.org/download/. On Linux, you can also do:

sudo apt-get install cmake

• BLAS/LAPACK – These linear algebra libraries are required and may already be available on your machine. Ifnot available, the source codes are available from http://www.netlib.org/blas/blas.tgz and http://www.netlib.org/lapack/lapack-3.5.0.tgz. Or on linux you can install them by typing:

sudo apt-get install libblas-devsudo apt-get install liblapack-dev

• svn – A subversion software package is required to download an external package Coin-SMI used in DSP. Youcan install it by:

sudo apt-get install subversion

• GNU Make/Autoconf/Automake – These are required and likely available on any machine. If not available,you can get them as follows:

sudo apt-get install build-essentialsudo apt-get install autoconfsudo apt-get install automake

• bzip2/zlib/xtuils-dev – These packages are required to build one of the external software packages used in DSP:

sudo apt-get install libbz2-devsudo apt-get install zlib1g-devsudo apt-get install xutils-dev

• MPICH – A version of MPICH is optional to build and run DSP. This is available from http://www.mpich.org/downloads/. On Linux, you can also do:

sudo apt-get install libmpich-dev

External software packages

The following packages are also required to build and run DSP and need to be located on ./extra directory beforeDSP may be built. DSP will automatically configure and build the external packages once they are located in theright place.

• MA27 – This is a library for solving sparse symmetric indefinite linear systems. To build OOQP solver, youmust have this installed. This is part of HSL (formerly the Harwell Subroutine Library), a collection of ISOFortran codes for large scale scientific computation.

1. Download: http://www.hsl.rl.ac.uk/download/MA27/1.0.0/a/

2. Unpack the downloaded file.

3. Move and rename the downloaded directory to ./extras/ma27-1.0.0/

10 Chapter 2. Installation

DSP Documentation, Release 0.2.1

• SCIP Optimization Suite – This contains non-commercial solvers for mixed integer programming (MIP) andmixed-integer nonlinear programming (MINLP).

1. Download: http://scip.zib.de/download.php?fname=scipoptsuite-3.1.1.tgz

2. Unpack the downloaded file.

3. Move and rename the downloaded directory to ./extras/scipoptsuite-3.1.1

Build and Setting

If you have all the prerequisite packages installed on your system, then you need to go to the root directory of DSPand type:

cmake .

to configure OOQP. If you wish to install the package in a more permanent location, you may then type:

make install

External packages (MA27, OOQP, SCIP Optimization Suite, Smi) used in DSP are built automatically. A sharedobject is installed in ./lib directory. Once the installation has been successfully done, you need to set environmentvariable LD_LIBRARY_PATH. Please add the following line by replacing <DSP_SRC_PATH> with your DSP sourcedirectory in ~/.bash_profile (or ~/.bash_aliases):

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<DSP_SRC_PATH>/lib

Julia Interface

DSP uses Julia as a modeling interface for the computational experiments. Julia is a high level dynamic programminglanguage for technical computing, with syntax that is familiar to users of other technical computing environmentssuch as MATLAB and Python. Julia can be downloaded from http://julialang.org/downloads/ If Julia is successfullyinstalled on your machine, then you can start the Julia command-line tool by typing:

julia

Now we need to install four Julia packages required to run DSP in the Julia environment. The packages should beinstalled in the Julia command-line tool. Please update the package list of Julia by typing:

julia> Pkg.update();

The following packages should be installed.

• JuMP.jl is an algebraic modeling package in Julia for mathematical programming, which can be installed by thefollowing Julia command:

julia> Pkg.add("JuMP");

• The Dsp.jl package provides an interface to JuMP. Dsp.jl can be installed by the Julia command:

julia> Pkg.clone("https://github.com/kibaekkim/Dsp.jl.git");

This package is optional. * MPI.jl is an MPI interface package, which can be installed by the following Julia command.MPICH is required for this package:

2.3. Build and Setting 11

DSP Documentation, Release 0.2.1

julia> Pkg.add("MPI");

12 Chapter 2. Installation

CHAPTER 3

Quick Start Guide

This guide illustrates how to use DSP for solving the following farmer problem taken from [BL11].

min 150𝑥1 + 230𝑥2 + 260𝑥3

+

3∑︁𝑠=1

1

3(238𝑦1𝑠 + 210𝑦2𝑠 − 170𝑦3𝑠 − 150𝑦4𝑠 − 36𝑦5𝑠 − 10𝑦6𝑠)

s.t. 𝑥1 + 𝑥2 + 𝑥3 ≤ 500,

𝑇1𝑠𝑥1 + 𝑦1𝑠 − 𝑦3𝑠 ≥ 200, 𝑠 = 1, 2, 3,

𝑇2𝑠𝑥2 + 𝑦2𝑠 − 𝑦4𝑠 ≥ 240, 𝑠 = 1, 2, 3,

𝑇3𝑠𝑥3 − 𝑦5𝑠 − 𝑦6𝑠 ≥ 0, 𝑠 = 1, 2, 3,

𝑦5𝑠 ≤ 6000, 𝑠 = 1, 2, 3,

𝑥1, 𝑥2, 𝑥3 ≥ 0

𝑦1𝑠, 𝑦2𝑠, 𝑦3𝑠, 𝑦4𝑠, 𝑦5𝑠, 𝑦6𝑠 ≥ 0, 𝑠 = 1, 2, 3,

where 𝑇𝑖𝑠 is an (𝑖, 𝑠)-element of matrix

𝑇 :=

⎡⎣ 3.0 3.6 24.02.5 3.0 20.02.0 2.4 16.0

⎤⎦ .

Modeling in JuMP.jl and Dsp.jl

We model the farmer problem by using the JuMP package [BKSE12][LD13]. JuMP is an algebraic modeling packagefor mathematical programming.

Note: Dsp.jl provides an Julia interface to the DSP software package. The Dsp.jl package defines some convenientfunctions working together with the JuMP.jl package and optionally MPI.jl package.

The farmer problem can be written as follows.

13

DSP Documentation, Release 0.2.1

Listing 3.1: Model file: farmer_model.jl

1 using JuMP2 m = Model();3 @variable(m, x[i=CROPS] >= 0, Int);4 @objective(m, Min, sum{Cost[i] * x[i], i=CROPS});5 @constraint(m, const_budget, sum{x[i], i=CROPS} <= Budget);6 for s = 1:NS7 sb = Model();8 @variable(sb, y[j=PURCH] >= 0);9 @variable(sb, w[k=SELL] >= 0);

10 @objective(sb, Min,11 sum{Purchase[j] * y[j], j=PURCH}12 - sum{Sell[k] * w[k], k=SELL});13 @constraint(sb, const_minreq[j=PURCH],14 Yield[s,j] * x[j] + y[j] - w[j] >= Minreq[j]);15 @constraint(sb, const_minreq_beets,16 Yield[s,3] * x[3] - w[3] - w[4] >= Minreq[3]);17 @constraint(sb, const_aux, w[3] <= 6000);18 @block(m, sb, s, probability[s]);19 end

The model file farmer_model.jl shows the JuMP model. In the first line of this script we include JuMP.jlpackage. The first-stage is defined in lines 3 to 5 and the second stage in lines 7 to 17 for each scenario.

Parallel dual decomposition

The following file farmer_run_mpi.jl reads the farmer model and runs the dual decomposition method in par-allel via the MPI.jl package.

Serial dual decomposition

The following file farmer_run.jl reads the farmer model and runs the dual decomposition method in serial.

Benders decomposition

Alternatively, users can use Benders decomposition by replacing line 6 of farmer_run.jl with:

status = solve(m, solve_type = :Benders)

For the parallel Benders decomposition:

status = solve(m, solve_type = :Benders, comm = MPI.COMM_WORLD)

Extensive form solution

Users can also solve the extensive form of the problem by replacing line 6 of farmer_run.jl with:

status = solve(m, solve_type = :Extensive)

14 Chapter 3. Quick Start Guide

DSP Documentation, Release 0.2.1

Reading model in SMPS format

DSP can also read a model provided in SMPS files [BDG+87]. In this format, a model is defined by three files:core, time, and stochastic with file extensions of .cor, .tim, and .sto, respectively. The core file defines thedeterministic version of the model with a single reference scenario, the time file indicates a row and a column that splitthe deterministic data and stochastic data in the constraint matrix, and the stochastic file defines random data. DSPcan read model in SMPS format (e.g., farmer.cor, farmer.tim and farmer.sto) as follows:

readSmps("farmer");

Modeling General Decomposition

As described in the DSP Overview section, DSP allows a user to run the same algorithms for scenario dual decompo-sition for SMIP with other forms of dual decomposition.

To illustrate modeling general dual decomposition in DSP, we replicate the above farmer example except that weexplicitly indicate to the solver the nonanticipativity constraints that need to be relaxed. This model can be found onexamples/farmer/general. Note that this example is for illustration purposes only and SMIPs should notbe modeled in this form: DSP has features that speed up stochastic problems that will not be applied in this setting.

In examples/farmer/general/ext_farmer_model.jl, we explicitly write the extensive form of themodel itself: first, we define a copy of the first-stage variables for each scenario (i.e. x[s=SCENARIOS, i=CROPS]instead of x[i=CROPS]). The constraints and objective are then adapted as in the file. Note that we do not needStochJuMP in this context (only JuMP) since the extensive form can be viewed as deterministic.

Once the extensive form has been modeled, we need to specify to DSP how the decomposition should be performed.We need to indicate:

• which are the coupling constraints, and

• to which subproblem each variable belongs to.

We add the nonanticipativity constraints as coupling constraints as follows:

Listing 3.2: Model file: ext_farmer_model.jl

1 for s in 1:NS-1, i in CROPS2 DSPsolver.addCouplingConstraint(m, @LinearConstraint(x[s,i] == x[s+1,i]))3 end

In addition, the following code associates variables to subproblems:

Listing 3.3: Model file: ext_farmer_model.jl

1 for s in SCENARIOS, i in CROPS2 DSPsolver.setVarSubproblem(m, x[s,i], s)3 end4 for s in SCENARIOS, j in PURCH5 DSPsolver.setVarSubproblem(m, y[s,j], s)6 end7 for s in SCENARIOS, k in SELL8 DSPsolver.setVarSubproblem(m, w[s,k], s)9 end

DSP expects a general decomposition model (rather than a SMIP) whenever either addCouplingConstraintor setVarSubproblem is called. All variables must be associated to a subproblem and the mapping must be

3.2. Modeling General Decomposition 15

DSP Documentation, Release 0.2.1

decomposable: no constraint except coupling constraints may involve variables of different subproblems. DSP willreturn an error if it detects that the mapping is not decomposable.

Loading and solving the problems works as in the SMIP case: the loadProblem and solve functions must becalled after modeling the problem.

Note: If the supplied model is a stochastic model (modeled using StochJuMP), then the model will automatically beconverted to its extensive form before decomposition. This may be useful to test other ways to decompose a stochasticproblem without rewriting it explicitly in extensive form. DSP does not currently support general decomposition toscenario subproblems, but this is a feature that might be implemented in the future.

16 Chapter 3. Quick Start Guide

CHAPTER 4

Julia Interface Functions

We describe Julia interface functions.

readSmps(filename)Read SMPS files from files filename.cor, filename.tim and filename.sto.

getblocksolution(model::JuMP.Model)Return second-stage solutions from stochastic model model::JuMP.Model.

JuMP.solve(model::JuMP.Model; suppress_warnings = false, comm = nothing, options...)Solve the model and returns solution status. Argument comm may have a communicator from MPI.jl. This canalso have arguments solve_type and param. Possible values of solve_type are :Dual, :Benders,and :Extensive. param may have a parameter file name.

optimize(;suppress_warnings = false, comm = nothing, options...)Same as JuMP.solve, but this is used when model is read from SMPS files.

getprimobjval()Returns primal objective value. The value can also be available from Dsp.model.primVal.

getdualobjval()Returns dual objective value. The value can also be available from Dsp.model.dualVal.

getsolutiontime()Returns solution time in seconds.

getblockids()Returns block IDs required for the current processor when MPI.jl is initialized.

17

DSP Documentation, Release 0.2.1

18 Chapter 4. Julia Interface Functions

CHAPTER 5

C Interface Functions

This will be available soon.

19

DSP Documentation, Release 0.2.1

20 Chapter 5. C Interface Functions

Bibliography

[Ach09] Tobias Achterberg. SCIP: solving constraint integer programs. Mathematical Programming Computation,1(1):1–41, 2009.

[For] John Forrest. Clp. URL: https://projects.coin-or.org/Clp.

[GW03] E Michael Gertz and Stephen J Wright. Object-oriented software for quadratic programming. ACM Transac-tions on Mathematical Software (TOMS), 29(1):58–81, 2003.

[KZ15] Kibaek Kim and Victor M Zavala. Algorithmic innovations and software for the dual decomposition methodapplied to stochastic mixed-integer programs. Optimization Online, 2015.

[LW03] Jeff Linderoth and Stephen Wright. Decomposition algorithms for stochastic programming on a computa-tional grid. Computational Optimization and Applications, 24(2-3):207–250, 2003.

[SLadanyiR04] Matthew Saltzman, László Ladányi, and Ted Ralphs. The COIN-OR open solver interface: technol-ogy overview. In CORS/INFORMS Conference. Banff. 2004.

[Wun96] Roland Wunderling. Paralleler und objektorientierter Simplex-Algorithmus. PhD thesis, Technische Univer-sität Berlin, 1996. http://www.zib.de/Publications/abstracts/TR-96-09/.

[GurobiOptimizationInc15] Gurobi Optimization, Inc. Gurobi optimizer reference manual. 2015. URL: http://www.gurobi.com.

[IBMCorp14] IBM Corp. IBM ILOG CPLEX Optimization Studio 12.6.1. 2014. URL: http://www-01.ibm.com/software/commerce/optimization/cplex-optimizer/index.html.

[BKSE12] Jeff Bezanson, Stefan Karpinski, Viral B Shah, and Alan Edelman. Julia: a fast dynamic language fortechnical computing. arXiv preprint arXiv:1209.5145, 2012.

[BDG+87] John R Birge, Michael AH Dempster, Horand I Gassmann, Eldon A Gunn, Alan J King, and Stein WWallace. A standard input format for multiperiod stochastic linear programs. IIASA Laxenburg Austria, 1987.

[BL11] John R Birge and Francois Louveaux. Introduction to stochastic programming. Springer, 2011.

[LD13] Miles Lubin and Iain Dunning. Computing in operations research using Julia. arXiv preprintarXiv:1312.1431, 2013.

21

DSP Documentation, Release 0.2.1

22 Bibliography

Index

Ggetblockids() (built-in function), 17getblocksolution() (built-in function), 17getdualobjval() (built-in function), 17getprimobjval() (built-in function), 17getsolutiontime() (built-in function), 17

JJuMP.solve() (built-in function), 17

Ooptimize() (built-in function), 17

RreadSmps() (built-in function), 17

23