Skip to content

How to use DSP

There are two ways to use algorithms in DSP:

  • Executable binary file runDsp
  • Callable C functions in shared library libDsp.so (or libDsp.dylib for Mac)

Building the DSP source files creates an executable file ./bin/runDsp and a shared library file ./lib/libDsp.*.

Executable file

The executable file ./bin/runDsp can be run as a command-line tool with the following arguments:

Argument Description
--algo A required argument for the choice of algorithms from one of the following:
  • de: deterministic equivalent form
  • bd: (integer) Benders decomposition
  • dd: dual decomposition
  • drbd: distributionally robust (integer) Bender decomposition
  • drdd: distributionally robust dual decomposition
  • dw: Dantzig-Wolfe decomposition with branch-and-bound
--wassnorm Wasserstein distance norm (>= 1.0). This argument should be used with --wasseps argument when --algo drbd or --algo drdd.
--wasseps Wasserstein distance limit (>= 0.0). This argument should be used with --wassnorm argument when --algo drbd or --algo drdd.
--smps SMPS file name without extensions.
For example, if your SMPS files are ../test/farmer.cor, ../test/farmer.sto, and ../test/farmer.tim, this value should be ../test/farmer
--mps MPS file name. This argument should be used with --dec argument.
--dec DEC file name. This argument should be used with --mps argument.
--quad Quadratic file name without extension. The Quadratic file should extend the parsed SMPS file and its suffix needs to be .txt in the current version. For example, if your Quadratic file is ../test/farmer.txt, this value should be ../test/farmer.
--soln An optional argument for solution file prefix.
For example, For example, if --soln mysoln is given, runDsp will write the following solution files:
  • mysoln.primobj.txt for primal objective value
  • mysoln.dualobj.txt for dual objective value
  • mysoln.primal.txt for primal variable values in the order of variables defined in the input file, if the primal objective value is less than 1e+20.
  • mysoln.dual.txt for dual variable values if --algo dd is given.
--param An optional paramater for parameter file name (see Parameters section)

Your first example!

This examples solves the two-stage stochastic mixed-integer linear program (MILP) of farmer example by using the (parallel) dual decomposition.

1
./bin/runDsp --algo dd --smps ../examples/smps/farmer

1
mpiexec -np 3 ./bin/runDsp --algo dd --smps ../examples/smps/farmer

Attention

Of course, Parallel Run is available only if you build DSP with MPI library.

More examples

Here we give some examples for running DSP with the executable file. The examples are given with --algo dd (i.e., using the dual decomposition), but can be easily modified to use the other algorithms (e.g., bd, dw) with argument --algo.

Example: Wasserstein DRO

This example solves the distributionall robust optimization (DRO) of farmer example, where the Wasserstein ambiguity set is of order 2 with the size 0.1.

1
2
3
4
5
6
./bin/runDsp --algo drdd \
             --smps ../examples/farmer \
             --wassnorm 2.0 \
             --wasseps 0.1 \
             --soln mysoln \
             --param myparam.txt

1
2
3
4
5
6
mpiexec -np 3 ./bin/runDsp --algo drdd \
                           --smps ../examples/farmer \
                           --wassnorm 2.0 \
                           --wasseps 0.1 \
                           --soln mysoln \
                           --param myparam.txt

Example: Stochastic MIQCP

This examples solves the two-stage stochastic mixed-integer quadratically constrained program (MIQCP) of farmer example. The quadratic constraints are defined in ../example/farmer.txt.

1
2
3
4
5
./bin/runDsp --algo dd \
             --smps ../examples/farmer \
             --quad ../example/farmer \
             --soln mysoln \
             --param myparam.txt

1
2
3
4
5
mpiexec -np 3 ./bin/runDsp --algo dd \
                           --smps ../examples/farmer \
                           --quad ../example/farmer \
                           --soln mysoln \
                           --param myparam.txt

Info

As a special case, the stochastic mixed-integer linear program can be set by omitting argument --quad.

Example: Generic structured program

This example solves a generic block-angular structure problem written in files noswot.mps and noswot.dec.

1
2
3
4
5
./bin/runDsp --algo dw \
             --mps ../examples/mps-dec/noswot.mps \
             --dec ../examples/mps-dec/noswot.dec \
             --soln mysoln \
             --param myparam.txt

1
2
3
4
5
mpiexec -np 3 ./bin/runDsp --algo dw \
                           --mps ../examples/mps-dec/noswot.mps \
                           --dec ../examples/mps-dec/noswot.dec \
                           --soln mysoln \
                           --param myparam.txt

Shared library

The shared library provides access to C API functions. The library needs to be placed in the searchable path. For example,

1
export LD_LIBRARY_PATH=/path/to/lib/libDsp.so:$LD_LIBRARY_PATH

1
export DYLD_LIBRARY_PATH=/path/to/lib/libDsp.dylib:$DYLD_LIBRARY_PATH

Using the library can be useful to interface with other (high-level) langauges such as Julia. We strongly recomment to check our Julia interface DSPopt.jl.

Last update: 2022-03-01