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

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

Upload fixes to doc from Claudia

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