# `BONMIN` Users' Manual

Introduction | Download | Install | Use | Setting Options | Options List | Bibliography |

- Bonmin
- Wiki
- NEOS
- IBM-CMU OCR
- IBM MINLP
- COIN-OR Home
- Projects
- FAQs
- Download
- Mailing Lists
- Get Involved
- Related Resources
- COIN-OR Foundation
- Events
- Members

## Setting Options

Passing options to BONMIN / List of options / Getting good solutions to nonconvex problems / Notes on Ipopt options /

### Options

### Passing options to BONMIN

Options in BONMIN can be set in several different ways.

First, you can set options by putting them in a file called bonmin.opt in the directory where bonmin is executing. If you are familiar with the file ipopt.opt (formerly named PARAMS.DAT) in Ipopt, the syntax of the bonmin.opt is similar. For those not familiar with 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 Ipopt. If you want to set options for Ipopt (when used inside BONMIN) you have to set them in the file bonmin.opt (the standard Ipopt option file ipopt.opt is not read by BONMIN.) For a list and a description of all the Ipopt options, the reader may refer to the documentation of Ipopt.

Since bonmin.opt contains both Ipopt and BONMIN options, for clarity all BONMIN options should be preceded with the prefix “bonmin.” in 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 ??).

The most important option in BONMIN is the choice of the solution algorithm. This can be set by using the option named bonmin.algorithm which can be set to B-BB, B-OA, B-QG, or B-Hyb (it’s default value is B-BB). Depending on the value of this option, certain other options may be available or not. The list of options together with their types, default values and availability in each of the four algorithms can be found 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 B-BB, B-OA, B-QG, B-Hyb, B-Ecp, and B-iFP ‘√’ indicates that the option is available for that particular algorithm while ‘-’ indicates that it is not.

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

A small example is as follows:

bonmin.bb_log_level 4
bonmin.algorithm B-BB
print_level 6

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 Ipopt to 6.

When BONMIN is run from within Ampl, another way to set an option is through the internal Ampl command options. For example

options bonmin_options "bonmin.bb_log-level 4 \
bonmin.algorithm B-BB print_level 6";

has the same affect as the bonmin.opt example above. Note that any BONMIN option specified in the file bonmin.opt overrides any setting of that option from within mpl.

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 here. In the following, we give some more details on options for the MILP subsolver and on the options specifically designed for nonconvex problems.

### Passing options to local search based heuristics and oa generators

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 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 “bonmin.” prefix is replaced with a prefix that identifies the sub-algorithm used:

- to pass options to Outer Approximation Decomposition: oa_decomposition.,
- to pass options to Feasibility Pump for MINLP: pump_for_minlp.,
- to pass options to RINS: rins.,
- to pass options to RENS: rens.,
- to pass options to Local Branching: local_branch.

For example, we may want to run a maximum of 60 seconds of FP for MINLP until 6 solutions are found at the beginning of the hybrid algorithm. To do so we set the following option in bonmin.opt

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

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 BONMINfor solving an MINLP) and want to stop as soon as B-QG found 1 solution. We set the following options in bonmin.opt

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

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 bonmin.milp_subsolver. Values for this option are: Cbc_D which uses Cbc with its default settings, Cplex which uses Cplex with its default settings, and Cbc_Par which uses a version of Cbc that can be parameterized by the user. The options that can be set in 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 ??).

### Getting good solutions to nonconvex problems

To solve a problem with non-convex constraints, one should only use the branch-and-bound algorithm 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 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 B-BB, we implemented a few options having in mind that lower bounds provided by 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, Ipopt may find different local optima when started from different starting points. The two options num_resolve_at_root and 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ï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 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 allowable_gap and allowable_fraction_gap and cutoff_decr to negative values.

### Notes on Ipopt options

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.

##### 0.0.1 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 bonmin.opt will override these settings.

mu_strategy and mu_oracle are set, respectively, to adaptive and probing by default (these are newly implemented strategies in Ipopt for updating the barrier parameter [Nocedal2004] which we have found to be more efficient in the context of MINLP).

gamma_phi and 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.

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.

expect_infeasible_problem is set to yes, which enables some heuristics to detect infeasible problems faster.

warm_start_init_point is set to yes when a full primal/dual starting point is available (generally all the optimizations after the continuous relaxation has been solved).

print_level is set to 0 by default to turn off Ipopt output.

##### 0.0.2 Some useful Ipopt options

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.