updated docs

Argonne-National-Laboratory · Dec 10, 2020 · 94f100c · 94f100c
1 parent fb0068b
commit 94f100c
Show file tree

Hide file tree

Showing 8 changed files with 246 additions and 181 deletions.
diff --git a/docs/algorithms.md b/docs/algorithms.md
@@ -1,6 +1,16 @@
-# Algorithms in DSP
+# Algorithms
 
-DSP provides **serial** and **parallel** implementations for the four types of algorithms.
+We describe the algorithm implementations available in `DSP`.
+The following table summarizes the available algorithms with their capabilities.
+
+| Argument | Algorithm                                     | Parallel                  | MILP                      | MIQP                      | MIQCP                     |
+| -------- | --------------------------------------------- | ------------------------- | ------------------------- | ------------------------- | ------------------------- |
+| `bd`     | Integer Benders decomposition                 | :fontawesome-solid-check: | :fontawesome-solid-check: | :fontawesome-solid-check: |                           |
+| `de`     | Extensive form solve                          |                           | :fontawesome-solid-check: | :fontawesome-solid-check: | :fontawesome-solid-check: |
+| `dd`     | Dual decomposition                            | :fontawesome-solid-check: | :fontawesome-solid-check: | :fontawesome-solid-check: | :fontawesome-solid-check: |
+| `drbd`   | Distributionally robust Benders decomposition | :fontawesome-solid-check: | :fontawesome-solid-check: |                           |                           |
+| `drdd`   | Distributionally robust dual decomposition    | :fontawesome-solid-check: | :fontawesome-solid-check: |                           | :fontawesome-solid-check: |
+| `dw`     | Dantzig-Wolfe decomposition                   | :fontawesome-solid-check: | :fontawesome-solid-check: |                           |                           |
 
 ## Dantzig-Wolfe Decomposition
 
@@ -21,8 +31,8 @@ For two-stage stochastic programs, each block is represented by a scenario subpr
 Stochastic programs can be read from [SMPS](https://ieeexplore.ieee.org/abstract/document/8142546) files or our C API functions (or Julia package [DSPopt.jl](https://github.com/kibaekkim/DSPopt.jl)).
 For generic optimization problems, each block can be specified by [mps-dec](https://gcg.or.rwth-aachen.de/doc/reader__dec_8h.html) files or our C API functions (or Julia package DSPopt.jl).
 
-!!! Note
-    A **distributionally robust** variant of dual decomposition is available for the problems given in SMPS files and optionally with `.dro` file.
+!!! check
+    A **distributionally robust** variant of dual decomposition is available with argument `--algo drdd`.
 
 For more technical details, please refer the following papers.
 
@@ -36,8 +46,8 @@ For more technical details, please refer the following papers.
 This solves the integer Benders decomposition of stochastic programming problems with the lower bound initialized by the dual decomposition.
 Integer Benders decomposition runs when the first stage is a pure-binary program and the second stage is a mixed-integer program.
 
-!!! Note
-    - A **distributionally robust** variant of Benders decomposition is available for the problems given in SMPS files and optionally with `.dro` file.
+!!! check
+    - A **distributionally robust** variant of Benders decomposition is available with argument `--algo drbd`.
     - When the first stage is not a pure-binary program, any second-stage integer variables will be relaxed.
     - This algorithm requires SCIP and is available only for stochastic programs.
 
@@ -46,5 +56,5 @@ Integer Benders decomposition runs when the first stage is a pure-binary program
 This reformulates the problem into one large optimization problem and uses available external solver.
 Parallel computing is available only through the external solver (i.e., multi-threading).
 
-!!! Note
+!!! attention
     There is no MPI parallelism for this algorithm.
diff --git a/docs/api.md b/docs/api.md
@@ -1,6 +1,6 @@
 # C API Functions
 
 A number of C functions are exported and available for advanced users.
-Please refer the header file `./src/DspCInterface.h`.
+Please refer the header file `/path/to/DSP/src/DspCInterface.h`.
 
 One may want to check out Julia package [DSPopt.jl](https://github.com/kibaekkim/DSPopt.jl) that implements the integerface to DSP by using these C API functions.
diff --git a/docs/examples.md b/docs/examples.md
@@ -3,78 +3,80 @@
 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`.
 
-## 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`.
-
-=== "Serial Run"
-
-    ```
-    ./runDsp --algo drdd \
-             --smps ../examples/farmer \
-             --wassnorm 2.0 \
-             --wasseps 0.1 \
-             --soln mysoln \
-             --param myparam.txt
-    ```
-
-=== "Parallel Run"
-
-    ```
-    mpiexec -np 3 ./runDsp --algo drdd \
-                           --smps ../examples/farmer \
-                           --wassnorm 2.0 \
-                           --wasseps 0.1 \
-                           --soln mysoln \
-                           --param myparam.txt
-    ```
-
-## 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`.
-
-=== "Serial Run"
-
-    ```
-    ./runDsp --algo dd \
-             --smps ../examples/farmer \
-             --quad ../example/farmer \
-             --soln mysoln \
-             --param myparam.txt
-    ```
-
-=== "Parallel Run"
-
-    ```
-    mpiexec -np 3 ./runDsp --algo dd \
-                           --smps ../examples/farmer \
-                           --quad ../example/farmer \
-                           --soln mysoln \
-                           --param myparam.txt
-    ```
-
-!!! Note "Stochastic Mixed-Integer Linear Program"
-    As a special case, the stochastic mixed-integer linear program can be set by omitting argument `--quad`.
-
-## Generic structured program
-
-=== "Serial Run"
-
-    ```
-    ./runDsp --algo dd \
-             --mps ../examples/noswot \
-             --dec ../examples/noswot \
-             --soln mysoln \
-             --param myparam.txt
-    ```
-
-=== "Parallel Run"
-
-    ```
-    mpiexec -np 3 ./runDsp --algo dd \
-                           --mps ../examples/noswot \
-                           --dec ../examples/noswot \
-                           --soln mysoln \
-                           --param myparam.txt
-    ```
+!!! Example "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`.
+
+    === "Serial Run"
+
+        ```
+        ./bin/runDsp --algo drdd \
+                     --smps ../examples/farmer \
+                     --wassnorm 2.0 \
+                     --wasseps 0.1 \
+                     --soln mysoln \
+                     --param myparam.txt
+        ```
+
+    === "Parallel Run"
+
+        ```
+        mpiexec -np 3 ./bin/runDsp --algo drdd \
+                                   --smps ../examples/farmer \
+                                   --wassnorm 2.0 \
+                                   --wasseps 0.1 \
+                                   --soln mysoln \
+                                   --param myparam.txt
+        ```
+
+!!! Example "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`.
+
+    === "Serial Run"
+
+        ```
+        ./bin/runDsp --algo dd \
+                     --smps ../examples/farmer \
+                     --quad ../example/farmer \
+                     --soln mysoln \
+                     --param myparam.txt
+        ```
+
+    === "Parallel Run"
+
+        ```
+        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 "Example: Generic structured program"
+
+    This example solves a generic block-angular structure problem written in files `noswot.mps` and `noswot.dec`.
+
+    === "Serial Run"
+
+        ```
+        ./bin/runDsp --algo dd \
+                     --mps ../examples/noswot \
+                     --dec ../examples/noswot \
+                     --soln mysoln \
+                     --param myparam.txt
+        ```
+
+    === "Parallel Run"
+
+        ```
+        mpiexec -np 3 ./bin/runDsp --algo dd \
+                                   --mps ../examples/noswot \
+                                   --dec ../examples/noswot \
+                                   --soln mysoln \
+                                   --param myparam.txt
+        ```
diff --git a/docs/howto.md b/docs/howto.md
@@ -1,6 +1,11 @@
 # How to Use DSP
 
-Building the DSP source files creates an executable file `./bin/runDsp` and a shared library file.
+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
 
@@ -18,11 +23,32 @@ The executable file `./bin/runDsp` can be run as a command-line tool with the fo
 | `--soln`     | An optional argument for solution file prefix.<br>For example, For example, if `--soln mysoln` is given, `runDsp` will write the following solution files:<ul><li>`mysoln.primobj.txt` for primal objective value</li><li>`mysoln.dualobj.txt` for dual objective value</li><li>`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`.</li><li>`mysoln.dual.txt` for dual variable values if `--algo dd` is given.</li></ul> |
 | `--param`    | An optional paramater for parameter file name (see [Parameters](./parameters.md) section)|
 
+
+!!! Example "Your first example!"
+
+    This examples solves the two-stage stochastic mixed-integer linear program (MILP) of `farmer` example by using the (parallel) dual decomposition.
+
+    === "Serial Run"
+
+        ```
+        ./bin/runDsp --algo dd --smps ../examples/smps/farmer
+        ```
+
+    === "Parallel Run"
+
+        ```
+        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.
+
 ## Shared library
 
 The shared library provides access to C API functions.
 The library needs to be placed in the searchable path.
-For example, (e.g., `LD_LIBRARY_PATH` for linux or `DYLD_LIBRARY_PATH` for Mac).
+For example,
 
 === "Linux"