source: trunk/Bonmin/doc/options.tex @ 1

Last change on this file since 1 was 1, checked in by andreasw, 13 years ago

imported initial code

File size: 13.5 KB
Line 
1
2%%% Local Variables:
3%%% mode: latex
4%%% TeX-master: "BONMIN_UsersManual"
5%%% End:
6
7\subsection{\Bonmin\  output options}
8\label{app:opt_loglevel}
9\paragraph{bb\_log\_level} specify branch-and-bound's log level.
10
11 Set the level of output of the branch-and-bound:
12 \begin{itemize}
13  \item {\tt 0} - none,
14  \item {\tt 1} - minimal,
15  \item {\tt 2} - normal low,
16  \item {\tt 3} - normal high,
17  \item {\tt 4} - verbose.
18  \end{itemize}
19 The valid range for this integer option is
20 $${\tt 0} \le \hbox{\tt bb\_log\_level } \le {\tt 5}$$
21and its default value is {\tt 3}.
22
23
24\paragraph{bb\_log\_interval} Interval at which node level output is printed.
25
26 Set the interval (in terms of number of nodes) at
27which a log on node resolutions (consisting of
28lower and upper bounds) is given. The valid range for this integer option is
29$${\tt 0} \le \hbox{\tt bb\_log\_interval } <  \infty$$
30and its default value is {\tt 100}.
31
32
33\paragraph{lp\_log\_level} specify LP log level.
34
35 Set the level of output of the linear programming
36subsolver in {\tt B-Hyb }or {\tt B-QG}:
37 \begin{itemize}
38  \item {\tt 0} - none,
39  \item {\tt 1} - minimal,
40  \item {\tt 2} - normal low,
41  \item {\tt 3} - normal high,
42  \item {\tt 4} - verbose.
43  \end{itemize}
44The valid range for this integer option is
45$${\tt 0} \le \hbox{\tt lp\_log\_level } \le {\tt 5}$$
46and its default value is {\tt 0}.
47
48
49\paragraph{milp\_log\_level} specify MILP subsolver log level.
50
51 Set the level of output of the MILP subsolver in
52OA :
53 \begin{itemize}
54  \item {\tt 0} - none,
55  \item {\tt 1} - minimal,
56  \item {\tt 2} - normal low,
57  \item {\tt 3} - normal high,
58  \item {\tt 4} - verbose.
59  \end{itemize}
60The valid range for this integer option is
61$${\tt 0} \le \hbox{\tt milp\_log\_level } \le {\tt 5}$$
62and its default value is {\tt 0}.
63
64
65\paragraph{oa\_log\_level} specify OA iterations log level.
66
67 Set the level of output of OA decomposition solver :
68 \begin{itemize}
69  \item {\tt 0} - none,
70  \item {\tt 1} - normal low,
71  \item {\tt 2} - normal high.
72  \end{itemize}
73  The valid range for this integer option is
74  $${\tt 0} \le \hbox{\tt oa\_log\_level } \le {\tt 2}$$
75  and its default value is {\tt 1}.
76
77\paragraph{oa\_log\_frequency} specify OA log frequency.
78  The valid range for this real option is
79  $$ 0 \le \hbox{\tt oa\_log\_frequency } \le \infty $$
80  and its default value is $100$.
81
82
83
84  \paragraph{nlp\_log\_level} specify NLP solver interface log level (independent from ipopt print\_level).
85
86  Set the level of output of the IpoptInterface :
87  \begin{itemize}
88  \item {\tt 0} - none,
89  \item {\tt 1} - low and readable with warnings,
90  \item {\tt 2} - verbose
91  \end{itemize}
92 The valid range for this integer option is
93$${\tt 0} \le {\tt nlp\_log\_level } \le {\tt 2}$$
94and its default value is {\tt 1}.
95
96\paragraph{print\_user\_options} Prints the list of options set by the user.
97The default value for this option is ``no".\\
98Possible values are:
99\begin{itemize}
100\item yes: print the list,
101\item no: don't.
102\end{itemize}
103
104\subsection{\Bonmin\ branch-and-bound options}
105
106\paragraph{algorithm} Choice of the algorithm.
107
108       This will preset default values for most options
109    of \Bonmin\ but depending on which algorithm some
110of these can be changed (refer to Table \ref{tab:options} to see which options
111           are valid with which algorithm).
112    The default value for this string option is ``{\tt B-Hyb}''.
113\\
114Possible values:
115\begin{itemize}
116   \item {\tt B-BB}: simple branch-and-bound algorithm,
117   \item {\tt B-OA}: OA Decomposition algorithm,
118   \item {\tt B-QG}: Quesada and Grossmann branch-and-cut algorithm,
119   \item {\tt B-Hyb}: hybrid outer approximation based branch-and-cut.
120\end{itemize}
121
122
123\paragraph{allowable\_gap}
124Specify the value of absolute gap under which the algorithm stops.
125
126 Stop the tree search when the gap between the
127objective value of the best known solution and
128the best lower bound on the objective of any solution
129is less than this. The valid range for this real option is
130$$-10^{20} \le \hbox{\tt allowable\_gap } \le 10^{20}$$
131and its default value is $0$.
132
133
134\paragraph{allowable\_fraction\_gap}
135Specify the value of relative gap under which the algorithm stops.
136
137 Stop the tree search when the gap between the
138objective value of the best known solution and
139the best bound on the objective of any solution
140is less than this fraction of the absolute value
141of the best known solution value. The valid range for this real option is
142$$-10^{20} \le \hbox{\tt allowable\_fraction\_gap } \le 10^{20}$$
143and its default value is $0$.
144
145\paragraph{cutoff}Specify a cutoff value
146
147cutoff should be the value of a feasible solution known by the user
148(if any). The algorithm will only look for solutions better (meaning with a lower objective value)
149than cutoff. The valid range for this real option is
150$$-10^{100} \le \hbox{\tt cutoff } \le 10^{100}$$
151and its default value is $10^{100}$.
152
153
154\paragraph{cutoff\_decr} Specify cutoff decrement.
155
156 Specify the amount by which cutoff is decremented
157below a new best upper-bound (usually a small
158positive value but in non-convex problems it may
159be a negative value). The valid range for this real option is
160$${\tt -10^{10}} \le \hbox{\tt cutoff\_decr } \le {\tt 10^{10}}$$
161and its default value is ${\tt 10^{-05}}$.
162
163
164\paragraph{nodeselect\_stra} Choose the node selection strategy.
165
166 Choose the strategy for selecting the next node
167to be processed.
168The default value for this string option is ``{\tt best-bound}''.
169\\
170Possible values:
171\begin{itemize}
172   \item {\tt best-bound}: choose node with the least bound,
173   \item {\tt depth-first}: Perform depth-first search,
174   \item {\tt breadth-first}: Perform breadth-first search,
175   \item {\tt dynamic}: {\tt Cbc} dynamic strategy (start with depth-first
176search and turn to best bound after 3 integer
177feasible solutions have been found).
178\end{itemize}
179
180
181\paragraph{number\_strong\_branch}
182Choose the maximum number of variables considered for strong branching.
183
184 Set the number of variables on which to do strong
185branching. The valid range for this integer option is
186$${\tt 0} \le \hbox{\tt number\_strong\_branch } <  \infty$$
187and its default value is ${\tt 0}$.
188
189
190\paragraph{number\_before\_trust}
191Set the number of branches on a variable before its pseudo costs are to
192be believed in dynamic strong branching.
193
194 A value of 0 disables dynamic strong branching. The valid range for this integer option is
195$${\tt 0} \le \hbox{\tt number\_before\_trust } <  \infty$$
196and its default value is ${\tt 0}$.
197
198
199\paragraph{time\_limit}
200Set the global maximum computation time (in seconds) for the algorithm.
201
202 The valid range for this real option is
203$${\tt 0} <  \hbox{\tt time\_limit } <  \infty$$
204and its default value is ${\tt 10^{+10}}$.
205
206
207\paragraph{node\_limit}
208Set the maximum number of nodes explored in the branch-and-bound search.
209
210The valid range for this integer option is
211$${\tt 0} \le \hbox{\tt node\_limit } <  \infty$$
212and its default value is {\tt INT\_MAX} (as defined in system {\tt limits.h}).
213
214
215\paragraph{integer\_tolerance}
216Set integer tolerance.
217
218 Any number within that value of an integer is
219considered integer.
220The valid range for this real option is
221$${\tt 0} <  \hbox{\tt integer\_tolerance } <  {\tt 0.5}$$
222and its default value is ${\tt 10^{-06}}$.
223
224
225
226\subsection{\Bonmin\ options for robustness}
227
228\paragraph{max\_random\_point\_radius}
229Set max value r for coordinate of a random point.
230
231 When picking a random point, each coordinate is selected uniformly
232in the interval $[\min(\max(l,-r),u-r),
233\max(\min(u,r),l+r)]$ where l is the lower bound
234for the variable and u is its upper bound.
235Beware that this is a very naive procedure. In particular,
236it may not be possible to evaluate some functions (such as log, 1/x)
237at such a randomly generated point (if \Bonmin\  finds that this is the case,
238it will give up random point generation).
239The valid range for this real option is
240$${\tt 0} <  \hbox{\tt max\_random\_point\_radius } <  \infty$$
241and its default value is ${\tt 10^{+08}}$.
242
243
244\paragraph{max\_consecutive\_failures}
245Number $n$ of consecutive unsolved problems before aborting
246a branch of the tree.
247
248 When $n > 0$, continue exploring a branch of the
249tree until $n$ consecutive problems in the branch
250are unsolved (i.e., for
251which {\tt Ipopt} can not guarantee optimality within
252the specified tolerances). The valid range for this integer option is
253$${\tt 0} \le \hbox{\tt max\_consecutive\_failures } <  \infty$$
254and its default value is ${\tt 10}$.
255
256
257\paragraph{num\_iterations\_suspect}
258(for debugging purposes only) number of iterations to consider a problem
259suspect.
260
261When the number of iterations taken by the continuous nonlinear solver
262(for the moment this is Ipopt) to solve a node is above this number,
263the subproblem is
264considered to be suspect and is outputed
265to a file. If set to {\tt -1} no subproblem is ever considered suspect.
266The valid range for this integer option is
267$${\tt -1} \le \hbox{\tt num\_iterations\_suspect } <  \infty$$
268and its default value is $-1$.
269
270
271\paragraph{nlp\_failure\_behavior}
272Set the behavior when an NLP or a series of NLP are unsolved by {\tt Ipopt}
273(an NLP is unsolved if {\tt Ipopt} is not able to guarantee optimality within the specified tolerances).
274
275 If set to ``{\tt fathom}'', the algorithm will fathom the
276node when an NLP is unsolved. The algorithm then becomes a
277heuristic. A warning that the solution might not
278be optimal is printed.
279The default value for this string option is ``{\tt stop}".
280\\
281Possible values:
282\begin{itemize}
283   \item {\tt stop}: Stop when failure happens.
284   \item {\tt fathom}: Continue when failure happens.
285\end{itemize}
286
287\paragraph{num\_retry\_unsolved\_random\_point}
288Number $k$ of times that the algorithm tries to resolve an unsolved NLP with a
289random starting point (unsolved NLP as defined above).
290 When an NLP is unsolved, if $k > 0$, the algorithm tries
291again to solve the failed NLP with $k$ new
292randomly chosen starting points  or until the
293problem is solved with success. The valid range for this integer option is
294$${\tt 0} \le \hbox{\tt num\_retry\_unsolved\_random\_point } <  \infty$$
295and its default value is {\tt 0}.
296
297
298
299\subsection{\Bonmin\ options for non-convex problems}
300
301\paragraph{max\_consecutive\_infeasible}
302Number $k$ of consecutive infeasible subproblems before aborting a branch.
303
304 Explores a branch of the tree
305      until $k$ consecutive
306problems are infeasible by the NLP subsolver. The valid range for
307this integer option is
308$${\tt 0} \le \hbox{\tt max\_consecutive\_infeasible } <  \infty$$
309and its default value is {\tt 0}.
310
311
312\paragraph{num\_resolve\_at\_root}
313Number $k$ of trials to solve the root node with different starting points.
314
315 The algorithm solves the root node with $k$
316random starting points and keeps the best
317local optimum found. The valid range for this integer option is
318$${\tt 0} \le \hbox{\tt num\_solve\_at\_root } <  \infty $$
319and its default value is {\tt 0}.
320
321
322\paragraph{num\_resolve\_at\_node}
323Number $k$ of tries to solve a node (other than the root) of the tree with different starting point.
324
325 The algorithm solves all the nodes with $k$
326different random starting points and keeps
327the best local optimum found. The valid range for this integer option is
328$${\tt 0} \le \hbox{\tt num\_solve\_at\_node } <  \infty$$
329and its default value is {\tt 0}.
330
331
332
333\subsection{\Bonmin\ options : {\tt B-Hyb} specific options}
334
335\paragraph{nlp\_solve\_frequency}
336Specify the frequency (in terms of nodes) at which NLP relaxations
337are solved in {\tt B-Hyb}.
338
339 A frequency of 0 amounts to never solve the
340NLP relaxation. The valid range for this integer option is
341$${\tt 0} \le \hbox{\tt nlp\_solve\_frequency } <  \infty$$
342and its default value is {\tt 10}.
343
344
345\paragraph{oa\_dec\_time\_limit}
346Specify the maximum number of seconds spent overall in OA decomposition iterations.
347
348 The valid range for this real option is
349$${\tt 0} \le \hbox{\tt oa\_dec\_time\_limit } <  \infty$$
350and its default value is {\tt 120}.
351
352\paragraph{tiny\_element}
353Value for tiny element in OA cut.
354We will remove cleanly (by relaxing cut) an element lower
355than this.
356
357The  valid range for this real option is
358$$0 \le \hbox{\tt tiny\_element } <  \infty$$
359and its default value is $10^{-8}$.
360
361\paragraph{very\_tiny\_element}
362Value for very tiny element in OA cut.
363Algorithm will take the risk of neglecting an element lower
364than this.
365
366The  valid range for this real option is
367$$0 \le \hbox{\tt very\_tiny\_element } <  \infty$$
368and its default value is $10^{-17}$.
369
370\paragraph{milp\_subsolver}
371Choose the subsolver to solve MILPs sub-problems in OA decompositions.
372
373  To use Cplex, a valid license is required and
374you should have compiled OsiCpx in COIN-OR  (see Osi documentation).
375The default value for this string option is ``{\tt Cbc\_D}''.
376\\
377Possible values:
378\begin{itemize}
379   \item {\tt Cbc\_D}: COIN-OR Branch and Cut with default options,
380   \item {\tt Cbc\_Par}: COIN-OR Branch and Cut with options passed by user,
381   \item {\tt Cplex}: Ilog Cplex.
382\end{itemize}
383
384
385\subsubsection{Cut generators frequency}
386For each one of the cut generators
387\paragraph{Gomory\_cuts}
388\paragraph{probing\_cuts}(by default probing cuts are currently disabled for numerical stability reason)
389\paragraph{cover\_cuts}
390\paragraph{mir\_cuts}
391Sets the frequency (in terms of nodes) for generating cuts of
392the given type in the branch-and-cut.
393\begin{itemize}
394\item $k > 0$, cuts are generated every k nodes,
395\item $-99 < k < 0$,  cuts are generated every -k nodes but
396{\tt Cbc} may decide to stop generating cuts, if not
397enough are generated at the root node,
398\item$k = -99$ cuts are generated only at the root node,
399\item $k = 0$ or $k = -100$ cuts are not generated.
400\end{itemize}
401 The valid range for this integer option is
402$${\tt -100} \le k <  \infty$$
403and its default value is ${\tt -5}$ (excepted for probing
404cuts for which default is 0).
Note: See TracBrowser for help on using the repository browser.