source: trunk/Bonmin/doc/BOUM_options.tex @ 54

Last change on this file since 54 was 54, checked in by pbonami, 13 years ago

Included correction in documentation suggested by Claudia

File size: 17.0 KB
Line 
1\PageHead{Setting Options}
2\StartPageSummary
3\PageSection{Passing options to \Bonmin }{sec:opt_opt}
4\PageSection{Getting good solutions to nonconvex problems}{sec:opt_nonconv}
5\PageSection{Notes on \Ipopt\ options}{sec:opt_ipopt}
6\EndPageSummary
7\NavigationPanel
8
9\PageTitle{Options}{sec:opt}
10\subsectionH{Passing options to \Bonmin}{sec:opt_opt}
11Options in \Bonmin\ can be set in several different ways.
12
13First, you can set options by putting them in a file called {\tt
14bonmin.opt} in the directory where {\tt bonmin} is executing. If you
15are familiar with the file
16\href{http://www.coin-or.org/Ipopt/documentation/node38.html}{\tt
17ipopt.opt} (formerly named {\tt PARAMS.DAT}) in {\tt Ipopt}, the
18syntax of the {\tt bonmin.opt} is similar. For those not familiar
19with {\tt ipopt.opt}, the syntax is simply to put the name of the
20option followed by its value, with no more than two options on a
21single line. Anything on a line after a \# symbol is ignored (i.e.,
22treated as a comment).
23
24Note that \Bonmin\ sets options for {\tt
25Ipopt}. If you want to set options for {\tt Ipopt} (when used inside \Bonmin) you have to set them
26in the file {\tt bonmin.opt} (the standard {\tt Ipopt} option file {\tt ipopt.opt}
27is not read by \Bonmin.)
28For a list and a description of all the {\tt Ipopt} options, the
29reader may refer to the
30\footlink{http://www.coin-or.org/Ipopt/documentation/node43.html}{documentation
31of {\tt
32Ipopt}}.
33
34Since {\tt bonmin.opt} contains both {\tt Ipopt} and \Bonmin\ options, for clarity
35all \Bonmin\ options should be preceded with the prefix ``{\tt bonmin.}'' in {\tt bonmin.opt}~.
36Note that some options can also be passed to the MILP subsolver used by \Bonmin\
37in the outer approximation decomposition
38and the hybrid (see Subsection \ref{sec:milp_opt}).\\
39
40The most important option in \Bonmin\ is the choice of the solution
41algorithm. This can be set by using the option named {\tt
42bonmin.algorithm} which can be set to {\tt B-BB}, {\tt B-OA}, {\tt
43B-QG} or {\tt B-Hyb} (it's default value is {\tt B-Hyb}). Depending
44on the value of this option, certain other options may be available
45or not. Table \ref{tab:options} gives the list of options together
46with their types, default values and availability in each of the
47four algorithms. The column labeled `type' indicates the type of the
48parameter (`F' stands for float, `I' for integer, and `S' for
49string). The column labeled default indicates the global default
50value. Then for each of the four algorithm {\tt B-BB}, {\tt B-OA},
51{\tt B-QG} and {\tt B-Hyb}, `$+$' indicates that the option is
52available for that particular algorithm
53while `$-$' indicates that it is not.\\
54
55An example of a {\tt bonmin.opt} file including all the options
56with their default values is located in the {\tt Test}
57sub-directory.
58
59A small example is as follows:
60\begin{verbatim}
61   bonmin.bb_log_level 4
62   bonmin.algorithm B-BB
63   print_level 6
64\end{verbatim}
65This sets the level of output of the branch-and-bound in \Bonmin\ to $4$, the algorithm to branch-and-bound
66and the output level for {\tt Ipopt} to $6$.\\
67
68When \Bonmin\ is run from within {\tt Ampl}, another way to set
69an option is through the
70internal {\tt Ampl} command {\tt options}.
71For example
72\begin{verbatim}
73options bonmin_options "bonmin.bb_log-level 4 \
74                  bonmin.algorithm B-BB print_level 6";
75\end{verbatim}
76has the same affect as the {\tt bonmin.opt} example above.
77Note that any \Bonmin\ option specified in the file {\tt bonmin.opt}
78overrides any setting of that option from within {\t Ampl}.\\
79
80A third way is to set options directly in the C/C++ code when
81running \Bonmin\ from inside a C/C++ program as is explained in the reference manual.
82
83A detailed description of all of the \Bonmin\ options is given in Appendix \ref{sec:optList}.
84In the following, we give some more details on options for the MILP subsolver and
85on the options specifically designed
86for nonconvex problems.\\
87
88\mylatexhtml{
89\begin{latexonly}
90%\begin{table}[htb]
91%\centering
92\begin{threeparttable}%[tb]
93\caption{\label{tab:options} %\parbox{\linewidth}{
94    List of options and compatibility with the different algorithms.
95    }
96\begin{tabular}{|l|r|r|r|r|r|r|}
97\hline
98Option & type &  default & {\tt B-BB} & {\tt B-OA} & {\tt B-QG} & {\tt B-Hyb} \\
99\hline
100\multicolumn{1}{|c}{} & \multicolumn{6}{l|}{output options}\\
101\hline
102bb\_log\_level & I & 1 & + & $-$  & + & +\\
103bb\_log\_interval & I & 100 & + & $-$ & + & +\\
104lp\_log\_level & I & 0 & $-$ & $-$ & + & +\\
105milp\_log\_level & I &  0 & $-$ &  + & $-$ & +\\
106oa\_log\_level & I & 1 & $-$ &  + & $-$ & +\\
107oa\_log\_frequency & I & 100 & $ - $ & $+$ & $-$ & $+$\\
108nlp\_log\_level & I & 1 & +&  + & + & +\\
109print\_user\_options & S & no & + & + & + & +\\
110\hline
111\multicolumn{1}{|c}{} & \multicolumn{6}{l|}{branch-and-bound options}\\
112\hline
113allowable\_gap  & F & 0 & + & + & + & +\\
114allowable\_fraction\_gap & F & 0& +& + & +& +\\
115cutoff & F& $10^{100}$ &  + & +& +& +\\
116cutoff\_decr & F & $10^{-5}$ & + & + & + & +\\
117integer\_tolerance & F & $10^{-6}$ &  + & + & + & +\\
118node\_limit & I & INT\_MAX &  + & +& + & + \\
119nodeselect\_stra$^*$ & S & best-bound & + & + & +& +\\
120number\_before\_trust$^*$ & I & 8 & $-$ & + & + & +\\
121number\_strong\_branch$^*$ & I & 20 & $-$ & + & + &+ \\
122time\_limit & F & $10^{10}$ & + & + & + & +\\
123\hline
124\multicolumn{1}{|c}{} & \multicolumn{6}{l|}{options for robustness}\\
125\hline
126max\_random\_point\_radius & F & $10^5$  &+ &+ &+ &+\\
127max\_consecutive\_failures & I & 10 & + & $-$ & $-$ & $-$\\
128nlp\_failure\_behavior & S & stop   & + & + & + & + \\
129num\_iterations\_suspect & I & $-$1 & + & + & + & + \\
130num\_retry\_unsolved\_random\_point & I & 0 & + & + & + & + \\
131\hline
132\multicolumn{1}{|c}{} & \multicolumn{6}{l|}{options for nonconvex problems}\\
133\hline
134max\_consecutive\_infeasible & I & 0 & + & $-$ & $-$ & $-$\\
135num\_resolve\_at\_node & I & 0 & + & +  & + & + \\
136num\_resolve\_at\_root & I & 0& + & + & + & +  \\
137\hline
138\multicolumn{1}{|c}{} & \multicolumn{6}{l|}{{\tt B-Hyb }specific options}\\
139\hline
140nlp\_solve\_frequency & I & 10 & $-$ & $-$ & $-$ & +\\
141oa\_dec\_time\_limit & F& 120 & $-$ & $-$ & $-$ & +\\
142tiny\_element & F & $10^{-8}$ & $-$ & + & + & + \\
143very\_tiny\_element & F & $10e^{-17}$ & $-$ & + & + & + \\
144\hline
145\multicolumn{1}{|c}{} & \multicolumn{6}{l|}{MILP options}\\
146\hline
147cover\_cuts$^*$  & I & $-$5 & $-$ & + & $-$ & +\\
148Gomory\_cuts$^*$ & I & $-$5 & $-$ &  + & $-$ & + \\
149milp\_subsolver &S & {\tt Cbc\_D} & $-$ & + & $-$ & + \\
150mir\_cuts$^*$  & I & $-$5 & $-$  & + & $-$ &+\\
151probing\_cuts$^1$$^*$  & I & -5 & $-$ & + & $-$ & +\\
152\hline
153\end{tabular}
154\begin{tablenotes}
155\item $\strut^*$ option is available
156         for MILP subsolver (it is only passed if the {\tt milp\_subsolver} option is set to {\tt Cbc\_Par},
157         see Subsection \ref{sec:milp_opt}).
158\item $\strut^1$ disabled for stability reasons.
159\end{tablenotes}
160\end{threeparttable}
161\end{latexonly}
162}{
163\begin{rawhtml}
164<table border="1">
165  <tr>
166    <td>Option </td>
167    <td> type </td>
168    <td> default </td>
169    <td> B-BB</td>
170    <td> B-OA</td>
171    <td> B-QG</td>
172    <td> B-Hyb</td>
173  </tr>
174  <tr>
175    <td>bb_log_level </td>
176    <td> I </td>
177    <td> 1 </td>
178    <td> + </td>
179    <td> - </td>
180    <td> + </td>
181    <td> +</td>
182  </tr>
183  <tr>
184    <td>bb_log_interval </td>
185    <td> I </td>
186    <td> 100</td>
187    <td> + </td>
188    <td> - </td>
189    <td> + </td>
190    <td> +</td>
191  </tr>
192  <tr>
193    <td>lp_log_level </td>
194    <td> I </td>
195    <td> 0 </td>
196    <td> - </td>
197    <td> - </td>
198    <td> + </td>
199    <td> +</td>
200  </tr>
201  <tr>
202    <td>milp_log_level </td>
203    <td> I </td>
204    <td> - </td>
205    <td> + </td>
206    <td> - </td>
207    <td> +</td>
208  </tr>
209  <tr>
210    <td>oa_log_level </td>
211    <td> I </td>
212    <td> 1 </td>
213    <td> - </td>
214    <td> + </td>
215    <td> - </td>
216    <td> +</td>
217  </tr>
218  <tr>
219    <td>nlp_log_level </td>
220    <td> I </td>
221    <td> 0 </td>
222    <td> +</td>
223    <td> + </td>
224    <td> + </td>
225    <td> +</td>
226  </tr>
227  <tr>
228    <td>allowable_gap </td>
229    <td> F </td>
230    <td> 0 </td>
231    <td> + </td>
232    <td> + </td>
233    <td> + </td>
234    <td> +</td>
235  </tr>
236  <tr>
237    <td>allowable_fraction_gap </td>
238    <td> F </td>
239    <td> 0</td>
240    <td> +</td>
241    <td> + </td>
242    <td> +</td>
243    <td> +</td>
244  </tr>
245  <tr>
246    <td>cutoff </td>
247    <td> F</td>
248    <td> 1e100 </td>
249    <td> + </td>
250    <td> +</td>
251    <td> +</td>
252    <td> +</td>
253  </tr>
254  <tr>
255    <td>cutoff_decr </td>
256    <td> F </td>
257    <td> 1e-05 </td>
258    <td> + </td>
259    <td> + </td>
260    <td> + </td>
261    <td> +</td>
262  </tr>
263  <tr>
264    <td>integer_tolerance </td>
265    <td> F </td>
266    <td> + </td>
267    <td> + </td>
268    <td> + </td>
269    <td> + </td>
270    <td> +</td>
271  </tr>
272  <tr>
273    <td>node_limit </td>
274    <td> I </td>
275    <td> INT_MAX </td>
276    <td> + </td>
277    <td> +</td>
278    <td> + </td>
279    <td> + </td>
280  </tr>
281  <tr>
282    <td>nodeselect_stra<a href="#MILP_options">(1)</a></td>
283    <td> S </td>
284    <td> best-bound </td>
285    <td> + </td>
286    <td> + </td>
287    <td> +</td>
288    <td> +</td>
289  </tr>
290  <tr>
291    <td>number_before_trust<a href="#MILP_options">(1)</a></td>
292    <td> I </td>
293    <td> 8 </td>
294    <td> - </td>
295    <td> + </td>
296    <td> + </td>
297    <td> +</td>
298  </tr>
299  <tr>
300    <td>number_strong_branch<a href="#MILP_options">(1)</a></td>
301    <td> I </td>
302    <td> 20 </td>
303    <td> - </td>
304    <td> + </td>
305    <td> + </td>
306    <td>+ </td>
307  </tr>
308  <tr>
309    <td>time_limit </td>
310    <td> F </td>
311    <td> 1e10 </td>
312    <td> + </td>
313    <td> + </td>
314    <td> + </td>
315    <td> +</td>
316  </tr>
317  <tr>
318    <td>ma+_random_point_radius </td>
319    <td> F </td>
320    <td>1e08</td>
321    <td>+ </td>
322    <td>+ </td>
323    <td>+ </td>
324    <td>+</td>
325  </tr>
326  <tr>
327    <td>ma+_consecutive_failures </td>
328    <td> I </td>
329    <td> 1</td>
330    <td> + </td>
331    <td> - </td>
332    <td> - </td>
333    <td> -</td>
334  </tr>
335  <tr>
336    <td>nlp_failure_behavior </td>
337    <td> S </td>
338    <td> stop </td>
339    <td> + </td>
340    <td> + </td>
341    <td> + </td>
342    <td> + </td>
343  </tr>
344  <tr>
345    <td>num_iterations_suspect </td>
346    <td> I </td>
347    <td> -1 </td>
348    <td> + </td>
349    <td> + </td>
350    <td> + </td>
351    <td> + </td>
352  </tr>
353  <tr>
354    <td>num_retry_unsolved_random_point </td>
355    <td> I </td>
356    <td> 0 </td>
357    <td> + </td>
358    <td> + </td>
359    <td> + </td>
360    <td> + </td>
361  </tr>
362  <tr>
363    <td>ma+_consecutive_infeasible </td>
364    <td> I </td>
365    <td> 0 </td>
366    <td> 0 </td>
367    <td> 0 </td>
368    <td> 0 </td>
369    <td> 0 </td>
370  </tr>
371  <tr>
372    <td>num_resolve_at_node </td>
373    <td> I </td>
374    <td> 0 </td>
375    <td> + </td>
376    <td> + </td>
377    <td> + </td>
378    <td> + </td>
379  </tr>
380  <tr>
381    <td>num_resolve_at_root </td>
382    <td> I </td>
383    <td> 0</td>
384    <td> + </td>
385    <td> + </td>
386    <td> + </td>
387    <td> + </td>
388  </tr>
389  <tr>
390    <td>nlp_solve_frequency </td>
391    <td> I </td>
392    <td> 10 </td>
393    <td> - </td>
394    <td> - </td>
395    <td> - </td>
396    <td> 10</td>
397  </tr>
398  <tr>
399    <td>oa_dec_time_limit </td>
400    <td> F</td>
401    <td> 120. </td>
402    <td> - </td>
403    <td> - </td>
404    <td> - </td>
405    <td> +</td>
406  </tr>
407  <tr>
408    <td>tiny_element </td>
409    <td> F</td>
410    <td> 1e-08 </td>
411    <td> - </td>
412    <td> + </td>
413    <td> + </td>
414    <td> + </td>
415  </tr>
416  <tr>
417    <td>very_tiny_element </td>
418    <td> F</td>
419    <td> 1e-17 </td>
420    <td> - </td>
421    <td> + </td>
422    <td> + </td>
423    <td> + </td>
424  </tr>
425    <tr>
426    <td>cover_cuts<a href="#MILP_options">(1)</a></td>
427    <td> I </td>
428    <td> -5 </td>
429    <td> - </td>
430    <td> + </td>
431    <td> - </td>
432    <td> +</td>
433  </tr>
434  <tr>
435    <td>Gomory_cuts<a href="#MILP_options">(1)</a></td>
436    <td> I </td>
437    <td> -5 </td>
438    <td> - </td>
439    <td> + </td>
440    <td> - </td>
441    <td> + </td>
442  </tr>
443  <tr>
444    <td>milp_subsolver </td>
445    <td>S </td>
446    <td> Cbc_D </td>
447    <td> - </td>
448    <td> + </td>
449    <td> - </td>
450    <td> + </td>
451  </tr>
452  <tr>
453    <td>mir_cuts<a href="#MILP_options">(1)</a></td>
454    <td> I </td>
455    <td> -5 </td>
456    <td> - </td>
457    <td> + </td>
458    <td> - </td>
459    <td>+</td>
460  </tr>
461  <tr>
462    <td>probing_cuts<a href="#MILP_options">(1)</a><a href="#disabled">(2)</a></td>
463    <td> I </td>
464    <td> 0 </td>
465    <td> - </td>
466    <td> + </td>
467    <td> - </td>
468    <td> +</td>
469  </tr>
470</table>
471\end{rawhtml}
472}
473
474
475\subsection{Passing options to the MILP subsolver}
476\label{sec:milp_opt}
477In the context of outer approximation decomposition, a standard MILP solver is used.
478Several option are available for configuring this MILP solver.
479\Bonmin\ allows a choice of different MILP solvers through the option
480{\tt bonmin.milp\_subsolver}. Values for this option are: {\tt Cbc\_D} which uses {\tt Cbc} with its
481default settings, {\tt Cplex} which uses {\tt Cplex} with its default settings, and
482{\tt Cbc\_Par} which uses a version of {\tt Cbc} that can be parameterized by the user.
483
484The options that can be set are the node-selection strategy, the number of strong-branching candidates,
485the number of branches before pseudo costs are to be trusted, and the frequency of the various cut generators
486(options marked with $^*$ in Table \ref{tab:options}). To pass those options to the MILP subsolver, you have
487to replace the prefix ``{\tt bonmin.}'' with ``{\tt milp\_sub.}''.
488
489
490\subsectionH{Getting good solutions to nonconvex problems}{sec:opt_nonconv}
491\label{sec:non_convex}
492A few options have been designed in \Bonmin\ specifically to treat
493problems that do not have a convex continuous relaxation.
494In such problems, the solutions obtained from {\tt Ipopt} are
495not necessarily globally optimal, but are only locally optimal. Also the outer-approximation
496constraints are not necessarily valid inequalities for the problem.
497
498No specific heuristic method for treating nonconvex problems is implemented
499yet within the OA framework.
500But for the pure branch-and-bound {\tt B-BB}, we implemented a few options having
501in mind that lower bounds provided by {\tt Ipopt} should not be trusted, and with the goal of
502trying to get good solutions. Such options are at a very experimental stage.
503
504First, in the context of nonconvex problems, {\tt Ipopt} may find different local optima when started
505from different starting points. The two options {\tt num\_re\-solve\_at\_root} and {\tt num\_resolve\_at\_node}
506allow for solving the root node or each node of the tree, respectively, with a user-specified
507number of different randomly-chosen
508starting points, saving the best solution found. Note that the function to generate a random starting point
509is very na\"{\i}ve: it chooses a random point (uniformly) between the bounds provided for the variable.
510In particular if there are some functions
511that can not be evaluated at some points of the domain, it may pick such points,
512 and so it is not robust in that respect.
513
514Secondly, since the solution given by {\tt Ipopt} does not truly give a lower bound, we allow for
515changing the fathoming rule
516to continue branching even if the solution value to the current node is worse
517than the best-known
518solution. This is achieved by setting {\tt allowable\_gap}
519and {\tt allowable\_fraction\_gap} and {\tt cutoff\_decr} to negative values.
520
521\subsectionH{Notes on \Ipopt\ options}{sec:opt_ipopt}
522\Ipopt\ has a very large number of options, to get a complete description of them, you
523should refer to the \Ipopt\ manual.
524Here we only mention and explain some of the options that have been more important to us, so far,
525in developing and using \Bonmin.
526\subsubsection{Default options changed by \Bonmin}
527\Ipopt\ has been tailored to be more efficient when used in the context of the
528solution of a MINLP problem. In particular, we have tried to
529improve \Ipopt's warm-starting capabilities and its ability to prove quickly that a subproblem
530is infeasible. For ordinary NLP problems, \Ipopt\ does not use these options
531by default, but \Bonmin\ automatically changes these options from their default values.
532
533Note that options set by the user in {\tt bonmin.opt} will override these
534settings.
535
536\paragraph{{\tt mu\_strategy} and {\tt mu\_oracle}} are set, respectively, to
537{\tt adaptive} and {\tt probing} by default (these are newly implemented strategies in \Ipopt\
538for updating the barrier parameter \cite{NocedalAdaptive} which we have found to be
539more efficient in the context of MINLP).
540\paragraph{{\tt gamma\_phi} and {\tt gamma\_theta}} are set to $10^{-8}$ and $10^{-4}$
541respectively. This has the effect of reducing the size of the filter in the line search performed by Ipopt.
542
543\paragraph{\tt required\_infeasibility\_reduction} is set to $0.1$.
544This increases the required infeasibility reduction when \Ipopt\ enters the
545restoration phase and should thus help
546detect infeasible problems faster.
547
548\paragraph{\tt expect\_infeasible\_problem} is set to {\tt yes} which enables some heuristics
549to detect infeasible problems faster.
550
551\paragraph{\tt warm\_start\_init\_point} is set to {\tt yes} when a full primal/dual starting
552point is available (generally all the optimizations after the continuous relaxation has been solved).
553
554\paragraph{\tt print\_level} is set to $0$ by default to turn off Ipopt output.
555\subsubsection{Some useful \Ipopt\ options}
556\paragraph{bound\_relax\_factor} is by default set to $10^{-8}$ in \Ipopt. All of the bounds
557of the problem are relaxed by this factor. This may cause some trouble
558when constraint functions can only be evaluated within their bounds.
559In such cases, this
560option should be set to 0.
Note: See TracBrowser for help on using the repository browser.