
\begin{PageSummary}
\PageName{Running \Bonmin}
\PageSection{On an .nl file}{sec:run_nl}
\PageSection{From AMPL}{sec:run_ampl}
\PageSection{priorities and SOS in AMPL}{sub_sec:prio}
\PageSection{From GAMS}{sec:run_gams}
\PageSection{From a C++ Program}{sec:run_cpp}
\end{PageSummary}

\begin{quickref}
\quickcitation{Writing \texttt{\bf .nl} files. D.M.~Gay.}{\BibPage \#Gay}
\quickcitation{AMPL: A Modeling Language for Mathematical
Programming, Second Edition, Duxbury Press Brooks Cole Publishing Co., 2003. R.~Fourer and D.M.~Gay and B.W.~Kernighan.}{\BibPage \#AMPL}
\end{quickref}


\PageTitle{Running \Bonmin}{sec:run}
\Bonmin\ can be run
\begin{itemize}
\item [(i)] from a command line on a {\tt .nl} file
(see \mycite{Gay}{Gay2005}),
\item [(ii)] from the modeling language \footlink{http://www.ampl.com}{\tt AMPL} (see
\mycite{AMPL}{Fourer2003}),
\item[(iii)] from the \footlink{http://www.gams.com/}{GAMS} modeling language,
\item [(iv)] by invoking it from a C/C++ program,
\item[(v)] remotely through the \footlink{http://neos.mcs.anl.gov/neos}{NEOS} web interface,
\item[(vi)] via the \footlink{https://projects.coin-or.org/OS}{Optimization Services} project,
\item[(vii)] via the MATLAB \footlink{http://www.i2c2.aut.ac.nz/Wiki/OPTI}{OPTI Toolbox}.
\end{itemize}

In \latexhtml{the subsections that follow}{this page}, we give some details about the
various ways to run \Bonmin.

\subsectionH{On a {\tt .nl} file}{sec:run_nl}
\Bonmin\ can read a {\tt .nl} file which could be generated by {\tt
AMPL} (for example {\tt mytoy.nl} in the {\tt
Bonmin-dist/Bonmin/test} subdirectory). The command line takes just
one argument which is the name of the {\tt .nl} file to be
processed.

For example, if you want to solve {\tt mytoy.nl}, from the {\tt
Bonmin-dist} directory, issue the command:

\begin{colorverb}
\begin{verbatim}

bonmin test/mytoy.nl

\end{verbatim}
\end{colorverb}

\subsectionH{From {\tt AMPL}}{sec:run_ampl}
To use \Bonmin\ from {\tt AMPL} you just need to have the directory where the
{\tt bonmin} executable is in your {\tt \$PATH} and to issue the
command

\begin{colorverb}
\begin{verbatim}

option solver bonmin;

\end{verbatim}
\end{colorverb}

in the {\tt AMPL} environment. Then the next {\tt solve} will
use \Bonmin\ to solve the model loaded in {\tt AMPL}.
After the optimization is finished, the values of the variables in the best-known
or optimal solution can be accessed in {\tt AMPL}. If the optimization is interrupted
with {\tt <CTRL-C>} the best known solution is accessible (this feature is not available in Cygwin).

\subsubsectionH{Example {\tt AMPL} model}{}
A simple {\tt AMPL} example model follows:

\begin{colorverb}
\begin{verbatim}

   # An AMPL version of toy

   reset;

   var x binary;
   var z integer >= 0 <= 5;
   var y{1..2} >=0;
   minimize cost:
       - x - y[1] - y[2] ;

   subject to
       c1: ( y[1] - 1/2 )^2 + (y[2] - 1/2)^2 <= 1/4 ;
       c2: x - y[1] <= 0 ;
       c3: x + y[2] + z <= 2;

   option solver bonmin; # Choose BONMIN as the solver (assuming
                         # that bonmin is in your PATH)

   solve;                # Solve the model
   display x;
   display y;

\end{verbatim}
\end{colorverb}
(This example model can be found in the \Bonmin\ package in the subdirectory {\tt Bonmin/examples/amplExamples/}.)

\subsubsectionH{Setting up branching priorities, directions and declaring SOS1 constraints in AMPL}{sub_sec:prio}
Branching priorities, branching directions and pseudo-costs can be passed using {\tt AMPL} suffixes.
The suffix for branching priorities is {\tt "priority"} (variables with a higher priority
will be chosen first for branching),
for branching direction is {\tt "direction"} (if direction is $1$ the $\geq$ branch
is explored first, if direction is $-1$ the $\leq$ branch is explored first), for up
and down pseudo costs {\tt "upPseudoCost"} and {\tt "downPseudoCost"} respectively
(note that if only one of the up and down pseudo-costs is set in the {\tt AMPL} model it will
be used for both up and down).

For example, to give branching priorities of $10$ to variables {\tt y} and 1 to variable {\tt x}
and to set the branching directions to explore the upper branch first for all variables
in the simple example given, we add before the call to solve:
\begin{colorverb}
\begin{verbatim}

suffix priority IN, integer, >=0, <= 9999;
y[1].priority := 10;
y[2].priority := 10;
x.priority := 1;

suffix direction IN, integer, >=-1, <=1;
y[1].direction := 1;
y[2].direction := 1;
x.direction := 1;

\end{verbatim}
\end{colorverb}

SOS Type-1 branching is also available in \Bonmin\ from {\tt AMPL}. We
follow the conventional way of doing this with suffixes.
Two type of suffixes should be declared:

\begin{colorverb}
\begin{verbatim}
suffix sosno IN, integer, >=1;  # Note that the solver assumes
                                # that these values are positive
                                # for SOS Type 1
suffix ref IN;
\end{verbatim}
\end{colorverb}

Next, suppose that we wish to have variables

\begin{colorverb}
\begin{verbatim}
var X {i in 1..M, j in 1..N} binary;
\end{verbatim}
\end{colorverb}
and the ``convexity'' constraints:

\begin{colorverb}
\begin{verbatim}
subject to Convexity {i in 1..M}:
   sum {j in 1..N} X[i,j] = 1;
\end{verbatim}
\end{colorverb}

(note that we must explicitly include the convexity constraints in the {\tt AMPL} model).

Then after reading in the data, we set the suffix values:
\begin{colorverb}
\begin{verbatim}

# The numbers `val[i,j]' are chosen typically as
#     the values `represented' by the discrete choices.
let {i in 1..M, j in 1..N} X[i,j].ref := val[i,j];

# These identify which SOS constraint each variable belongs to.
let {i in 1..M, j in 1..N} X[i,j].sosno := i;
\end{verbatim}
\end{colorverb}

\subsectionH{From {\tt GAMS}}{sec:run_gams}
Thanks to the \footlink{http://projects.coin-or.org/GAMSlinks}{GAMSlinks} project, 
Bonmin is available in {\tt GAMS} since release 22.5 of the \footlink{http://www.gams.com/}{\tt GAMS} modeling system. 
The system is available for \footlink{http://download.gams.com/download}{download from GAMS}. Without buying a license it works as a demo with limited capabilities. Documentation for using \Bonmin\ in {\tt GAMS} is available
\latexhtml{ at
$$
         \mbox{\tt http://www.gams.com/solvers/coin.pdf}
$$
}{\href{http://www.gams.com/solvers/coin.pdf}{here}.}


\subsectionH{From a C/C++ program}{sec:run_cpp}
\Bonmin\ can also be run from within a C/C++ program if the user codes
the functions to compute first- and second-order derivatives.
An example of such a program is available in the subdirectory {\tt CppExample} of
the {\tt examples} directory. For further explanations, please refer to this example and to the reference manual.
