forked from coin-or/MibS
-
Notifications
You must be signed in to change notification settings - Fork 0
/
generate_readme
119 lines (98 loc) · 4.84 KB
/
generate_readme
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
#!/usr/bin/env bash
# Exit when command fails
set -e
#Attempt to use undefined variable outputs error message, and forces an exit
set -u
#Causes a pipeline to return the exit status of the last command in the pipe
#that returned a non-zero return value.
set -o pipefail
#set -x
source $COINBREW_HOME/scripts/generate_readme
pushd . > /dev/null
cd $(dirname $0)
SCRIPT_DIR=$PWD
popd > /dev/null
create_variables $SCRIPT_DIR/config.yml
make_header
echo "MibS is a solver for stochastic mixed integer bilevel linear optimization
problems. For an introduction to bilevel optimization, see [this slide
deck](http://coral.ie.lehigh.edu/~ted/files/talks/BILEVEL-IWOBIP16.pdf). A
somewhat outdated but still useful introduction to MibS is
[here](http://coral.ie.lehigh.edu/~ted/files/talks/BILEVEL-INFORMS11.pdf).
A paper that contains a complete technical description of the algorithms in
MibS is [here](http://coral.ie.lehigh.edu/~ted/files/papers/MIBLP16.pdf).
A paper that discusses the cuts employed by MibS is
[here](http://coral.ie.lehigh.edu/~ted/files/papers/MibSCuts20.pdf).
More detailed documentation is available [here](https://coin-or.github.io/MibS).
"
make_build_info_no_packages
echo "## USING
### Modelling Systems
MibS has interfaces to the following modelling systems that allow the user to
conveniently build the bilevel model in a high-level modelling language and
pass the model to MibS through the interface for solution.
- Pyomo (Python) through the
[PAO](https://pao.readthedocs.io/en/latest/index.html#) package,
see [here](https://pao.readthedocs.io/en/latest/solvers.html)
- JuMP (Julia) through the [BilevelJuMP](https://github.com/joaquimg/BilevelJuMP.jl) package, see
[here](https://github.com/joaquimg/BilevelJuMP.jl/blob/master/docs/src/examples/MibS_example1.jl)
for an example.
### Command Line
To solve a deterministic mixed integer bilevel linear optimization problem,
you must provide both an MPS file and an auxiliary information file that
specifies which variables and constraints are associated with the each level
(see a description of the file format
[here](https://coin-or.github.io/MibS/input.html)).
Then call \`mibs\` like this:
\`\`\`
<build_or_install_dir>/bin/mibs -Alps_instance file.mps -MibS_auxiliaryInfoFile aux_file.txt
\`\`\`
It is also possible to
specify additional settings in a parameter file with, e.g.,
\`\`\`
<build_or_install_dir>/bin/mibs -param <build_or_install_dir>/MibS/src/mibs.par
\`\`\`
MibS has many parameters. See the
example parameter file \`mibs.par\` and the header file \`MibParams.hpp\` for
explanations. You can also find a detailed description of MibS
[here](http://www.optimization-online.org/DB_FILE/2017/04/5977.pdf).
Furthermore, to conduct the experiments illustrated in this report, see the
\`README\` file in the directory \`scripts\`.
\`MibS\` is also capable of solving two-stage mixed integer stochastic bilevel
linear optimization problems. To solve these problems, there are two ways:
* Provide an MPS file, a time file and a stoch file in the same way as the
SMPS format. The second-stage objective coefficients should be defined at
the end of the time file (see
[here](https://github.com/tkralphs/BilevelLib/blob/master/stochastic/sslp/bilevel_nonZeroSum_sslp_10_50_50.tim)).
Then call \`mibs\` like this:
\`\`\`
<build_or_install_dir>/bin/mibs -Alps_instance file.mps -MibS_auxiliaryTimFile file.tim -MibS_auxiliaryStoFile file.sto -MibS_stochasticityType stochasticWithoutSAA -MibS_isSMPSFormat 1 -MibS_isA2Random 1
\`\`\`
The parameter \`MibS_isA2Random\` should be set to 0 in case the coefficients of
the first-stage variables in the second-stage problem are not random
variables.
* Provide an MPS file and an auxiliary information file in the same way as
deterministic bilevel problems. The probability distributions of the
random variables also should be specified by setting the values of
corresponding parameters (MibS currently supports only the discrete
uniform distribution). For a sample parameter file, see
[src/mibsStochastic.par.in].
"
echo "
## Project Links
* [Additional documentation](https://coin-or.github.io/MibS)
* [Code of Conduct](https://www.coin-or.org/code-of-conduct/)
* [COIN-OR Web Site](http://www.coin-or.org/)
* [Discussion forum](https://github.com/coin-or/$Description_Slug/discussions)
* [Report a bug](https://github.com/coin-or/$Description_Slug/issues/new)
"
echo "## ACKNOWLEDGEMENT
MibS was developed with support from
* Office of Naval Research (Grant N000141912330)
* National Science Foundation (Grants CMMI-1435453, CMMI-0728011, ACI-0102687)
* Lehigh University
* Zuse Institute Berlin
* Research Campus Modal \"Mathematical Optimization and Data Analysis
Laboratories\" funded by the German Federal Ministry of Education and Research
(BMBF Grant 05M14ZAM) and by the DFG SFB/Transregio 154
"