
\begin{PageSummary}
\PageName{Setting Options}
\PageSection{Passing options to \Bonmin }{sec:opt_opt}
\PageSection{List of options}{sec:options_list}
\PageSection{Getting good solutions to nonconvex problems}{sec:opt_nonconv}
\PageSection{Notes on \Ipopt\ options}{sec:opt_ipopt}
\end{PageSummary}


\PageTitle{Options}{sec:opt}
\subsectionH{Passing options to \Bonmin}{sec:opt_opt}
Options in \Bonmin\ can be set in several different ways.

First, you can set options by putting them in a file called {\tt
bonmin.opt} in the directory where {\tt bonmin} is executing. If you
are familiar with the file
\href{\IpoptDoc{34}}{\tt
ipopt.opt} (formerly named {\tt PARAMS.DAT}) in {\tt Ipopt}, the
syntax of the {\tt bonmin.opt} is similar. For those not familiar
with {\tt ipopt.opt}, the syntax is simply to put the name of the
option followed by its value, with no more than two options on a
single line. Anything on a line after a \# symbol is ignored (i.e.,
treated as a comment).

Note that \Bonmin\ sets options for {\tt
Ipopt}. If you want to set options for {\tt Ipopt} (when used inside \Bonmin) you have to set them
in the file {\tt bonmin.opt} (the standard {\tt Ipopt} option file {\tt ipopt.opt}
is not read by \Bonmin.)
For a list and a description of all the {\tt Ipopt} options, the
reader may refer to the
\footlink{\IpoptDoc{39}}{documentation
of {\tt
Ipopt}}.

Since {\tt bonmin.opt} contains both {\tt Ipopt} and \Bonmin\ options, for clarity
all \Bonmin\ options should be preceded with the prefix ``{\tt bonmin.}'' in {\tt bonmin.opt}~.
Note that some options can also be passed to the MILP subsolver used by \Bonmin\
in the outer approximation decomposition
and the hybrid (see Subsection \ref{sec:sub_solvers}).

The most important option in \Bonmin\ is the choice of the solution
algorithm. This can be set by using the option named {\tt
bonmin.algorithm} which can be set to {\tt B-BB}, {\tt B-OA}, {\tt
B-QG}, or {\tt B-Hyb} (it's default value is {\tt B-BB}). Depending
on the value of this option, certain other options may be available
or not. \latexhtml{Table \ref{tab:options} gives t}{T}he list of options together
with their types, default values and availability in each of the
four algorithms\latexhtml{}{ can be found \href{\OptListPage \#sec:options_list}{here}}. The column labeled `type' indicates the type of the
parameter (`F' stands for float, `I' for integer, and `S' for
string). The column labeled `default' indicates the global default
value. Then for each of the algorithms {\tt B-BB}, {\tt B-OA},
{\tt B-QG}, {\tt B-Hyb}, {\tt B-Ecp}, and {\tt B-iFP} `$\surd$' indicates that the option is
available for that particular algorithm
while `$-$' indicates that it is not.

An example of a {\tt bonmin.opt} file including all the options
with their default values is located in the {\tt Test}
sub-directory.

A small example is as follows:
\begin{verbatim}
   bonmin.bb_log_level 4
   bonmin.algorithm B-BB
   print_level 6
\end{verbatim}
This sets the level of output of the branch-and-bound in \Bonmin\ to $4$, the algorithm to branch-and-bound
and the output level for {\tt Ipopt} to $6$.

When \Bonmin\ is run from within {\tt AMPL}, another way to set
an option is via the
internal {\tt AMPL} command {\tt options}.
For example
\begin{verbatim}
options bonmin_options "bonmin.bb_log-level 4 \
                  bonmin.algorithm B-BB print_level 6";
\end{verbatim}
has the same affect as the {\tt bonmin.opt} example above.
Note that any \Bonmin\ option specified in the file {\tt bonmin.opt}
overrides any setting of that option from within {\tt AMPL}.

A third way is to set options directly in the C/C++ code when
running \Bonmin\ from inside a C/C++ program as is explained in the reference manual.

A detailed description of all of the \Bonmin\ options is given \latexhtml{in Appendix \ref{sec:optList}}{\href{\OptListPage \#sec:options_list}{here}}.
In the following, we give some more details on options for the MILP subsolver and
on the options specifically designed
for nonconvex problems.

\latexhtml{
\include{options_table}
}{
}

\subsectionH{Passing options to local search based heuristics and oa generators}{sec:sub_solvers}
%\label{sec:sub_solvers}
Several parts of the algorithms in \Bonmin\ are based on solving a simplified version of the problem with another instance of \Bonmin:
Outer Approximation Decomposition (called in {\tt B-Hyb} at the root node)
and Feasibility Pump for MINLP (called in B-Hyb or B-BB at the root node), RINS, RENS, Local Branching.

In all these cases, one can pass options to the sub-algorithm used through the bonmin.opt file. The basic principle is
that the {\tt bonmin.} prefix  is replaced with a prefix that identifies the sub-algorithm used:
\begin{itemize}
\item {\tt oa\_decomposition.} to pass options to Outer Approximation Decomposition,
\item {\tt pump\_for\_minlp.} to pass options to Feasibility Pump for MINLP
\item {\tt rins.} to pass options to RINS,
\item {\tt rens.} to pass options to RENS,
\item {\tt local\_branch.} to pass options to Local Branching.
\end{itemize}


For example, we may want to run a maximum of 60 seconds of the feasibility pump for MINLP until 6 solutions are found at the beginning of the hybrid algorithm. To do so 
we set the following option in {\tt bonmin.opt}
\begin{verbatim}
bonmin.algorithm B-Hyb

bonmin.pump_for_minlp yes       # tells to run fp for MINLP
pump_for_minlp.time_limit 60    # set a time limit for the pump
pump_for_minlp.solution_limit 6 # set a solution limit
\end{verbatim}

Note that the actual solution and time limit will be the minimum of the global limits set for \Bonmin.

A slightly more complicated set of options may be used when using RINS. Say for example that we want to run RINS inside B-BB. Each time RINS is called we want
to solve the small-size MINLP generated using B-QG (we may run any algorithm available in \Bonmin for solving an MINLP) and want to stop as soon as B-QG found 1 solution.
We set the following options in bonmin.opt

\begin{verbatim}
bonmin.algorithm B-BB

bonmin.rins yes
rins.algorithm B-QG
rins.solution_limit 1

\end{verbatim}
This example shows that it is possible to set any option used in the sub-algorithm to be different than the one used for the main algorithm.


In the context of OA and FP for MINLP, a standard MILP solver is used.
Several option are available for configuring this MILP solver.
\Bonmin\ allows a choice of different MILP solvers through the option
{\tt bonmin.milp\_subsolver}. Values for this option are: {\tt Cbc\_D} which uses {\tt Cbc} with its
default settings, {\tt Cplex} which uses {\tt Cplex} with its default settings, and
{\tt Cbc\_Par} which uses a version of {\tt Cbc} that can be parametrized by the user.
The options that can be set in {\tt Cbc\_Par} are the number of strong-branching candidates,
the number of branches before pseudo costs are to be trusted, and the frequency of the various cut generators
(these options are signaled in Table \ref{tab:options}).

\subsectionH{Getting good solutions to nonconvex problems}{sec:opt_nonconv}
\label{sec:non_convex}
To solve a problem with non-convex constraints, one should only use the branch-and-bound algorithm {\tt B-BB}.


A few options have been designed in \Bonmin\ specifically to treat
problems that do not have a convex continuous relaxation.
In such problems, the solutions obtained from {\tt Ipopt} are
not necessarily globally optimal, but are only locally optimal. Also the outer-approximation
constraints are not necessarily valid inequalities for the problem.

No specific heuristic method for treating nonconvex problems is implemented
yet within the OA framework.
But for the pure branch-and-bound {\tt B-BB}, we implemented a few options having
in mind that lower bounds provided by {\tt Ipopt} should not be trusted, and with the goal of
trying to get good solutions. Such options are at a very experimental stage.

First, in the context of nonconvex problems, {\tt Ipopt} may find different local optima when started
from different starting points. The two options {\tt num\_re\-solve\_at\_root} and {\tt num\_resolve\_at\_node}
allow for solving the root node or each node of the tree, respectively, with a user-specified
number of different randomly-chosen
starting points, saving the best solution found. Note that the function to generate a random starting point
is very na\"{\i}ve: it chooses a random point (uniformly) between the bounds provided for the variable.
In particular if there are some functions
that can not be evaluated at some points of the domain, it may pick such points,
 and so it is not robust in that respect.

Secondly, since the solution given by {\tt Ipopt} does not truly give a lower bound, we allow for
changing the fathoming rule
to continue branching even if the solution value to the current node is worse
than the best-known
solution. This is achieved by setting {\tt allowable\_gap}
and {\tt allowable\_fraction\_gap} and {\tt cutoff\_decr} to negative values.

\subsectionH{Notes on {\tt Ipopt} options}{sec:opt_ipopt}
%\label{sec:opt_ipopt}
\Ipopt\ has a very large number of options, to get a complete description of them, you
should refer to the \Ipopt\ manual.
Here we only mention and explain some of the options that have been more important to us, so far,
in developing and using \Bonmin.
\subsubsection{Default options changed by \Bonmin}
\Ipopt\ has been tailored to be more efficient when used in the context of the
solution of a MINLP problem. In particular, we have tried to
improve \Ipopt's warm-starting capabilities and its ability to prove quickly that a subproblem
is infeasible. For ordinary NLP problems, \Ipopt\ does not use these options
by default, but \Bonmin\ automatically changes these options from their default values.

Note that options set by the user in {\tt bonmin.opt} will override these
settings.

\paragraph{{\tt mu\_strategy} and {\tt mu\_oracle}} are set, respectively, to
{\tt adaptive} and {\tt probing} by default (these are newly implemented strategies in \Ipopt\
for updating the barrier parameter \mycite{NocedalAdaptive}{Nocedal2004} which we have found to be
more efficient in the context of MINLP).
\paragraph{{\tt gamma\_phi} and {\tt gamma\_theta}} are set to $10^{-8}$ and $10^{-4}$
respectively. This has the effect of reducing the size of the filter in the line search performed by \Ipopt.

\paragraph{\tt required\_infeasibility\_reduction} is set to $0.1$.
This increases the required infeasibility reduction when \Ipopt\ enters the
restoration phase and should thus help to
detect infeasible problems faster.

\paragraph{\tt expect\_infeasible\_problem} is set to {\tt yes}, which enables some heuristics
to detect infeasible problems faster.

\paragraph{\tt warm\_start\_init\_point} is set to {\tt yes} when a full primal/dual starting
point is available (generally all the optimizations after the continuous relaxation has been solved).

\paragraph{\tt print\_level} is set to $0$ by default to turn off \Ipopt\ output.
\subsubsection{Some useful \Ipopt\ options}
\paragraph{bound\_relax\_factor} is by default set to $10^{-8}$ in \Ipopt. All of the bounds
of the problem are relaxed by this factor. This may cause some trouble
when constraint functions can only be evaluated within their bounds.
In such cases, this
option should be set to 0.
