forked from coin-or/SYMPHONY
-
Notifications
You must be signed in to change notification settings - Fork 0
/
generate_readme
252 lines (187 loc) · 9.71 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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
#!/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 "SYMPHONY is an open-source generic MILP solver, callable library, and
extensible framework for implementing customized solvers for mixed-integer
linear programs (MILPs). SYMPHONY can be built in various sequential and
parallel configurations for either distributed or shared memory architectures
and can be used \"out of the box\" as a solver for generic mixed-integer
linear programs or customized through a wide variety of user callback
functions and control parameters. SYMPHONY has a number of advanced
capabilities stemming from the research projects discussed above, including
the ability to solve multi-objective MILPs, the ability to warm start its
solution procedure, and the ability to perform basic sensitivity analyses.
SYMPHONY has has been deployed in a variety of application areas, including
computational biology, wireless telecommunications, supply chain management,
transportation services, and air transportation.
"
make_build_info no_conda
echo "## USING SYMPHONY
### Using SYMPHONY from the command line
To use SYMPHONY as a generic solver, type the executable name on the command
line, followed by one or more of the command-line switches. On the
command-line, there is one required switch---you must specify the location of
the input file by using either \`-F 'filename'\` (MPS file or automatic
detection with file extension) or \`-L 'filename'\` (LP format). If the \`-D\`
switch is also present, the file will be assumed to be a GMPL model file with
the data file specified after the \`-D\` switch. In LINUX, the following command
would solve the instance \`sample.mps\`
\`\`\`symphony -F sample.mps\`\`\`
The remaining switches are used to set SYMPHONY's native parameters on the
command line. Below is a list of these parameters. This list can also be
obtained by executng
\`\`\`symphony -h\`\`\`
Note that all SYMPHONY parameters are denoted by a lowercase letter. Many
other parameters can be set with the use of a parameter file (specified with
-f). These parameters are listed in the SYMPHONY user's manual.
\`\`\`
symphony [ -FL file ] [ -f parameter_file_name ]
[ -hd ] [-a 0/1] [-b 0/1 ] [-s cands] [-l 0/1] [ -q 0/1 ] [ -r 0/1]
[-j 0/1 ] [ -e n ] [ -i iters ] [ -t time ] [ -g gap ] [ -n nodes ]
[ -u ub ] [ -p procs ] [ -k rule ] [ -v level ] [ -c rule ]
[ -m max ] [ -z n ] [-o tree_out_file] [-w 0/1]
-F model: model should be read in from file 'model'
(MPS format is assumed unless -D is also present)
-L model: LP format model should be read in from file 'model'
-D data: model is in AMPL format and data is in file 'data'
-T dir: run test with MIPLIB3 models
-h: help
-f file: read parameters from parameter file 'file'
-d: stop at first feasible solution
-a 0/1: whether to use primal heuristics
-b 0/1: whether to use reliability branching
-s cands: use at most 'cands' candidates for strong branching
-l 0/1: whether to impose a limit on strong branching time
-q 0/1: whether or not to tighten root bounds
-r 0/1: whether or not to do reduced cost tightening
-j 0/1: whether or not to generate cgl cuts
-w 0/1: whether or not to use hot starting in strong branching
-e n: set pre-processing level to 'n'
-i iters: allow a max of 'iters' iterations in presolve
-t time: set wallclock time limit to 'time'
-g gap: set gap limit to 'gap'
-n nodes: set node limit to 'nodes'
-u ub: use initial upper bound 'ub'
-p procs: allow 'procs' additional threads or processors
-k i: use node selection rule 'i'
-v n: set verbosity to level 'n'
-c i: use rule 'i' to compare candidates
-m max: allow a max of 'max' cuts to enter per iteration
-z n: set diving threshold to 'n'
-o file: output vbc-like tree information to file 'file'
\`\`\`
### Using the SYMPHONY interactive optimizer
To use SYMPHONY's Interactive shell, run the executable name without any
command line arguments. Then type \`help\` or \`?\` to see a list of available
commands which are as follows for this version:
\`\`\`
load : read a problem in mps or ampl format
solve : solve the problem
lpsolve : solve the lp relaxation of the problem
set : set a parameter
display : display optimization results and stats
reset : restart the optimizer
help : show the available commands/params/options
quit/exit : leave the optimizer
\`\`\`
So, if you want to load and solve an ampl/gmpl file, you will need to type
\`load sample.mod sample.dat\` and then \`solve\`.
### Using the callable library
To use SYMPHONY as a generic callable library, compile SYMPHONY as described
above. The library that is created along with the solver itself can be linked
to using the API described in the user's manual. For examples of using the
callable library in this way, see the Examples/ subdirectory.
## DEVELOPING CUSTOM APPLICATIONS
To customize SYMPHONY by implementing the custom callback functions, simply
modify the files in the SYMPHONY/Applications/USER/ subdirectory, as described
in the user's manual and follow the compilation procedures in the file
SYMPHONY/Applications/USER/README. There are a number of sample applications
available as examples of how to do this kind of development with SYMPHONY.
These include solvers for the matching problem, the set partitioning problem
(simple and advanced versions), the vehicle routing and traveling salesman
problems, and the mixed postman problem. These applications are distributed as
separate packages and can be downloaded from http://www.branchandcut.org.
There is a white paper that guides the user through the development of the
matching solver.
## CURRENT TESTING STATUS
SYMPHONY can be used in a very large number of possible configurations and
we simply aren't able to test them all. Below is a rough idea of the testing
status of various configurations to date. If you need a certain configuration,
I would be happy to help you get it running. Please let me know.
## LP INTERFACES
**The native interfaces for OSL and CPLEX have been deprecated**
**Only LP solvers with OSI interfaces are supported**
Well tested: CPLEX, CLP
Well tested, but have some stability or other issues: GLPK
Compiled, but not well tested: SPX
## TESTED CONFIGURATIONS
### SEQUENTIAL
Sequential configurations are now automatically built and tested on Linux, OS X, and Windows using Github Actions (see above for status).
### SHARED MEMORY PARLLEL (OpenMP)
Builds and passes unit test with gcc and CLP on LINUX.
### DISTRIBUTED MEMORY PARALLEL (PVM)
Known configurations that build and pass unit test
- gcc on LINUX with PVM 3.4
### APPLICATIONS
- SYMPHONY (used as a generic MILP solver): Well tested.
- MATCH (matching): Tested, but not very extensively.
- MPP (mixed postman problem): Tested, but not very extensively.
- VRP (vehicle routing problem): Well tested.
- CNRP (capacitates network routing problem): Well tested.
- MCKP (multi criteria knapsack problem): Well tested.
- SPP (set partitioning problem): Tested, but not very extensively.
- SPP+CUTS (set partitioning problem with cutting planes): Tested, but not very
extensively.
### CUT GENERATORS
Cut generators are supplied by the Cut Generation Library (CGL). The cut
generators that are turned on by default have been well tested. Two cut
generators that are part ofthe CGL are turned off by default because of known
issues. These are lift and project cuts and the simple rounding cuts. The
generator for Gomory cuts works well, but has somenumerical issues. We found a
few cases where the optimal solution was not found when using the Gomory cut
generator, especially in combination with CPLEX. If the solver is not
performing as it should, try turning off some of the cut generators to see if
that fixes the problem.
## ADDITIONAL DOCUMENTATION
If you have downloaded a source distribution, LaTex source for the full
documentation is available in the SYMPHONY/Doc/ subdirectory. Quick start
guides and pointers to other on-line documentation can be found below.
The PDF version of the manual is available here:
https://coin-or.github.io/SYMPHONY/doc/SYMPHONY-5.7.1-Manual.pdf
An on-line version that is for a slightly earlier release is here:
http://coin-or.github.io/SYMPHONY/man-5.7/
## Project Links
* [Code of Conduct](https://www.coin-or.org/code-of-conduct/)
* [COIN-OR Web Site](http://www.coin-or.org/)
* [Discussion formum](https://github.com/coin-or/SYMPHONY/discussions)
* [Report a bug](https://github.com/coin-or/SYMPHONY/issues/new)
### AUTHORS
SYMPHONY was jointly developed by Ted Ralphs ([email protected]) and Laci Ladanyi
([email protected]). Menal Guzelsoy ([email protected]) and Ashutosh
Mahajan ([email protected]) have been instrumental in development since
version 5.0.
## ACKNOWLEDGEMENT
SYMPHONY was developed with support from
* National Science Foundation grants CMMI-1435453, CMMI-0728011, DMI-0522796,
DMI-0534862, DMS-9527124, and CMMI-1130914.
* Texas ATP Grant 97-3604-010
* Cornell University
* 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
"