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

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

imported initial code

File size: 5.7 KB
Line 
1\PageHead{Running \Bonmin}
2\StartPageSummary
3\PageSection{On an .nl file}{sec:run_nl}
4\PageSection{From Ampl}{sec:run_ampl}
5\PageSection{From a C++ Programm}{sec:run_cpp}
6\EndPageSummary
7\NavigationPanel
8
9
10
11\PageTitle{Running \Bonmin}{sec:run}
12\Bonmin\ can be run
13\begin{itemize}
14\item [(i)] from a command line on a {\tt .nl} file
15(see \cite{Gay}),
16\item [(ii)] from the modeling language \footlink{http://www.ampl.com}{\tt Ampl} (see
17\cite{AMPL}) or from \footlink{http://www.gams.com/}{Gams} provided
18that you have a valid {\tt Ampl} license, and
19\item [(iii)] by invoking it from a C/C++ program.
20\end{itemize}
21Eventually, we expect that a fourth option will be remotely, via the
22\footlink{http://neos.mcs.anl.gov/neos}{NEOS} Server for Optimization.
23In the subsections that follow, we give some details about the
24various ways to run \Bonmin.
25
26\subsectionH{On a {\tt .nl} file}{sec:run_nl}
27\Bonmin\ can read a {\tt .nl} file which could be generated by {\tt
28Ampl} (for example {\tt mytoy.nl} in the {\tt
29Bonmin-dist/Bonmin/test} subdirectory). The command line takes just
30one argument which is the name of the {\tt .nl} file to be
31processed.
32
33For example, if you want to solve {\tt mytoy.nl}, from the {\tt
34Bonmin-dist} directory, issue the command:
35
36\begin{verbatim}
37bonmin test/mytoy.nl
38\end{verbatim}
39
40\subsectionH{From {\tt Ampl}}{sec:run_ampl}
41To use \Bonmin\ from {\tt Ampl} you just need to have the directory where the
42{\tt bonmin} executable is in your {\tt \$PATH} and to issue the
43command
44
45\begin{verbatim}
46
47option solver bonmin;
48
49\end{verbatim}
50in the {\tt Ampl} environment. Then the next {\tt solve} will
51use \Bonmin\ to solve the model loaded in {\tt Ampl}.
52After the optimization is finished, the values of the variables in the best-known
53or optimal solution can be accessed in {\tt Ampl}. If the optimization is interrupted
54with {\tt <CTRL-C>} the best known solution is accessible (this feature is not available in Cygwin).\\
55
56A simple {\tt Ampl} example model follows:
57
58\begin{verbatim}
59
60   # An Ampl version of toy
61
62   reset;
63
64   var x binary;
65   var z integer >= 0 <= 5;
66   var y{1..2} >=0;
67   minimize cost:
68       - x - y[1] - y[2] ;
69
70   subject to
71       c1: ( y[1] - 1/2 )^2 + (y[2] - 1/2)^2 <= 1/4 ;
72       c2: x - y[1] <= 0 ;
73       c3: x + y[2] + z <= 2;
74
75   option solver bonmin; # Choose BONMIN as the solver (assuming that
76                         # bonmin is in your PATH
77
78   solve;                # Solve the model
79   display x;
80   display y;
81
82\end{verbatim}
83(This example can be found in the subdirectory {\tt Bonmin/examples/amplExamples/} of
84the \Bonmin\ package.)
85
86Branching priorities, branching directions and pseudo-costs can be passed using {\tt Ampl} suffixes.
87The suffix for branching priorities is {\tt "priority"} (variables with a higher priority
88will be chosen first for branching),
89for branching direction is {\tt "direction"} (if direction is $1$ the $\geq$ branch
90is explored first, if direction is $-1$ the $\leq$ branch is explored first), for up
91and down pseudo costs {\tt "upPseudoCost"} and {\tt "downPseudoCost"} respectively
92(note that if only one of the up and down pseudo-costs is set in the {\tt Ampl} model it will
93be used for both up and down).\\
94
95For example, to give branching priorities of $10$ to variables {\tt y} and 1 to variable {\tt x}
96and to set the branching directions to explore the upper branch first for all variables
97in the simple example given, we add before the call to solve:
98\begin{verbatim}
99
100suffix priority IN, integer, >=0, <= 9999;
101y[1].priority := 10;
102y[2].priority := 10;
103x.priority := 1;
104
105suffix direction IN, integer, >=-1, <=1;
106y[1].direction := 1;
107y[2].direction := 1;
108x.direction := 1;
109
110\end{verbatim}
111
112SOS Type-1 branching is also available in \Bonmin\ from {\tt Ampl}. We
113follow the conventional way of doing this with suffixes.
114Two type of suffixes should be declared:
115
116\begin{verbatim}
117suffix sosno IN, integer, >=1;  # Note that the solver assumes that these
118                                #   values are positive for SOS Type 1
119suffix ref IN;
120\end{verbatim}
121
122Next, suppose that we wish to have variables
123\begin{verbatim}
124var X {i in 1..M, j in 1..N} binary;
125\end{verbatim}
126and the ``convexity'' constraints:
127
128\begin{verbatim}
129subject to Convexity {i in 1..M}:
130   sum {j in 1..N} X[i,j] = 1;
131\end{verbatim}
132(note that we must explicitly include the convexity constraints in the {\tt Ampl} model).
133
134Then after reading in the data, we set the suffix values:
135\begin{verbatim}
136
137# The numbers `val[i,j]' are chosen typically as
138#     the values `represented' by the discrete choices.
139let {i in 1..M, j in 1..N} X[i,j].ref := val[i,j];
140
141# These identify which SOS constraint each variable belongs to.
142let {i in 1..M, j in 1..N} X[i,j].sosno := i;
143\end{verbatim}
144
145\subsubsection{From {\tt Gams} using {\tt Ampl}}
146The modeling system {\tt Gams} offers the possibility to solve {\tt Gams} models using any
147{\tt Ampl} capable solver. The {\tt Gams}/{\tt Ampl} link comes free with the {\tt Gams}
148system, but users must have a licensed {\tt Ampl} on their machine.
149
150To be able to use \Bonmin\ with {\tt Gams}, you must compile the COIN-OR libraries as static.
151This can be done by passing the option {\tt --enable-static} to the configure file.
152
153Detailed instruction for using {\tt Gams}/{\tt Ampl} can be found
154on \footlink{http://www.gams.com/solvers/gamsampl.pdf}{{\tt Gams} website}.\\
155
156Note that user set branching priorities and SOS Type-1 branching is not
157available from this interface.
158
159\subsectionH{From a C/C++ program}{sec:run_cpp}
160\Bonmin\ can also be run from within a C/C++ program if the user codes
161the functions to compute first- and second-order derivatives.
162An example of such a program is available in the subdirectory {\tt CppExample} of
163the {\tt examples} directory. For further explanations, please refer to the reference manual.
Note: See TracBrowser for help on using the repository browser.