source: html/use.html @ 1584

Last change on this file since 1584 was 1584, checked in by pbonami, 10 years ago

Documentation in new cleaner html form

File size: 15.2 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
2  "http://www.w3.org/TR/html4/loose.dtd"> 
3<html > 
4<head><title></title> 
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 
6<meta name="generator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)"> 
7<meta name="originator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)"> 
8<!-- html --> 
9<meta name="src" content="tmp.tex"> 
10<meta name="date" content="2010-01-23 16:34:00"> 
11<link rel="stylesheet" type="text/css" href="bonmin.css"> 
12</head><body 
13>
14<!--l. 2--><p class="noindent" ><div id="header">   <h1 id="siteName"><TT> <big> BONMIN </big> </tt> Users' Manual</h1>   <div id="globalNav">   <a href="Intro.html">Introduction</a> |   <a href="Obtain.html">Download</a> |  <a href="Install.html">Install</a> |   <a href="use.html">Use</a> |   <a href="options_set.html">Setting Options</a> |   <a href="options_list.html">Options List</a> |   <a href="bib.html">Bibliography</a> |  </div>   </div>  <div id="leftPanel"> <div id="side-bar">  <ul> <li class="main"><a href="/Bonmin/index.html">Bonmin</a></li>  <li><a href="https://projects.coin-or.org/Bonmin">Wiki</a></li>   <li><a href="http://neos.mcs.anl.gov/neos/solvers/minco:Bonmin/AMPL.html"> NEOS </a> </li>  <li><a href="http://egon.cheme.cmu.edu/ibm/page.htm">IBM-CMU OCR </a></li>  <li><a href="http://domino.research.ibm.com/comm/research_projects.nsf/pages/minlp.index.html">  IBM MINLP </a></li>  <br>  <br>  <li class="main"><a href="/index.html">COIN-OR Home</a></li>  <li><a href="/projects.html">Projects</a></li>  <li><a href="/faqs.html">FAQs</a></li>   <li><a href="/download.html">Download</a></li>  <li><a href="/mail.html">Mailing Lists</a></li>  <li><a href="/how-to-help.html">Get Involved</a></li>  <li><a href="/resources.html">Related Resources</a></li>  <li class="main"><a href="/foundation.html">  <br>  <br>  COIN-OR Foundation  </a></li>   <li><a href="/events.html">Events</a></li>  <li><a href="/members.html">Members</a></li>  </ul>  </div> </div> <!--end navBar div -->  <br>   <h2 id="pageName"> Running <span 
15class="cmtt-10">BONMIN </span> </h2> <a href="#sec:run&#x02D9;nl " > On an .nl file  </a> /
16<a href="#sec:run&#x02D9;ampl " > From Ampl  </a> / <a href="#sub&#x02D9;sec:prio " > priorities and SOS in Ampl  </a> /
17<a href="#sec:run&#x02D9;gams " > From GAMS  </a> / <a href="#sec:run&#x02D9;cpp " > From a C++ Programm  </a> /   </div> 
18<!--l. 11--><p class="noindent" > <div id="rightPanel"> <div id="headlines"> <h4>References </h4>     <div id="refer"> <p>  1 <a 
19href="../bib/index.html#Gay" >Writing <span 
20class="cmbx-10">.nl </span>files. D.M.&#x00A0;Gay.</a>  </p> </div>       <div id="refer"> <p>  2 <a 
21href="../bib/index.html#AMPL" >AMPL: A Modeling Language for
22Mathematical Programming, Second Edition, Duxbury Press Brooks Cole
23Publishing Co., 2003. R.&#x00A0;Fourer and D.M.&#x00A0;Gay and B.W.&#x00A0;Kernighan.</a>  </p> </div>     </div> </div> 
24<!--l. 18--><p class="noindent" > </div> <div id="content"> <div class="feature"> <h3> Running <span 
25class="cmtt-10">BONMIN </span></h3> <span 
26class="cmtt-10">BONMIN</span>&#x00A0;can be run
27     <ul class="itemize1">
28     <li class="itemize">from  a  command  line  on  a  <span 
29class="cmtt-10">.nl </span>file  (see    <a href=&#8221;../bib/index.html#Gay&#8221;
30     > [Gay2005]</a> ),
31     </li>
32     <li class="itemize">from  the  modeling  language  <a 
33href="http://www.ampl.com" ><span 
34class="cmtt-10">Ampl</span></a> (see    <a href=&#8221;../bib/index.html#AMPL&#8221;
35     > [Fourrer2003]</a> ),
36     </li>
37     <li class="itemize">from the <a 
38href="http://www.gams.com/" >Gams</a> modeling language,
39     </li>
40     <li class="itemize">by invoking it from a C/C++ program.
41     </li>
42     <li class="itemize">remotely through the <a 
43href="http://neos.mcs.anl.gov/neos" >NEOS</a> web interface.</li></ul>
44<!--l. 30--><p class="indent" >   In this page, we give some details about the various ways to run <span 
45class="cmtt-10">BONMIN</span>.
46<!--l. 33--><p class="indent" >    </div> <div class="story"> <h3><a name=  &#8221;sec:run&#x02D9;nl&#8221; ></a> On a <span 
47class="cmtt-10">.nl </span>file  </h3>   <span 
48class="cmtt-10">BONMIN</span>&#x00A0;can read a <span 
49class="cmtt-10">.nl </span>file which could be
50generated by <span 
51class="cmtt-10">Ampl </span>(for example <span 
52class="cmtt-10">mytoy.nl </span>in the <span 
53class="cmtt-10">Bonmin-dist/Bonmin/test</span>
54subdirectory). The command line takes just one argument which is the name of the
55<span 
56class="cmtt-10">.nl </span>file to be processed.
57<!--l. 40--><p class="indent" >   For example, if you want to solve <span 
58class="cmtt-10">mytoy.nl</span>, from the <span 
59class="cmtt-10">Bonmin-dist </span>directory,
60issue the command:
61<!--l. 43--><p class="indent" >   <div id="verbatim">
62
63   <table 
64class="verbatim"><tr class="verbatim"><td 
65class="verbatim"><div class="verbatim">
66&#x00A0;<br />bonmin&#x00A0;test/mytoy.nl
67&#x00A0;<br />
68</div>
69</td></tr></table>
70<!--l. 48--><p class="nopar" > </div> 
71<!--l. 51--><p class="indent" >    </div> <div class="story"> <h3><a name=  &#8221;sec:run&#x02D9;ampl&#8221; ></a> From <span 
72class="cmtt-10">Ampl </span> </h3>  To use <span 
73class="cmtt-10">BONMIN</span>&#x00A0;from <span 
74class="cmtt-10">Ampl </span>you just need to have
75the directory where the <span 
76class="cmtt-10">bonmin </span>executable is in your <span 
77class="cmtt-10">$PATH </span>and to issue the
78command
79<!--l. 56--><p class="indent" >   <div id="verbatim">
80
81   <table 
82class="verbatim"><tr class="verbatim"><td 
83class="verbatim"><div class="verbatim">
84&#x00A0;<br />option&#x00A0;solver&#x00A0;bonmin;
85&#x00A0;<br />
86</div>
87</td></tr></table>
88<!--l. 61--><p class="nopar" > </div> 
89<!--l. 64--><p class="indent" >   in the <span 
90class="cmtt-10">Ampl </span>environment. Then the next <span 
91class="cmtt-10">solve </span>will use <span 
92class="cmtt-10">BONMIN</span>&#x00A0;to solve the
93model loaded in <span 
94class="cmtt-10">Ampl</span>. After the optimization is finished, the values of the variables in
95the best-known or optimal solution can be accessed in <span 
96class="cmtt-10">Ampl</span>. If the optimization is
97interrupted with <span 
98class="cmtt-10">&#x003C;CTRL-C&#x003E; </span>the best known solution is accessible (this feature is not
99available in Cygwin).
100<br class="newline" />
101<!--l. 71--><p class="indent" >    </div> <div class="story"> <h3><a name=  &#8221;A&#8221; ></a> Example <span 
102class="cmtt-10">Ampl </span>model  </h3>   simple <span 
103class="cmtt-10">Ampl </span>example model follows:
104<!--l. 73--><p class="indent" >   <div id="verbatim">
105
106   <table 
107class="verbatim"><tr class="verbatim"><td 
108class="verbatim"><div class="verbatim">
109&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;#&#x00A0;An&#x00A0;Ampl&#x00A0;version&#x00A0;of&#x00A0;toy
110&#x00A0;<br />
111&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;reset;
112&#x00A0;<br />
113&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;var&#x00A0;x&#x00A0;binary;
114&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;var&#x00A0;z&#x00A0;integer&#x00A0;&#x003E;=&#x00A0;0&#x00A0;&#x003C;=&#x00A0;5;
115&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;var&#x00A0;y{1..2}&#x00A0;&#x003E;=0;
116&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;minimize&#x00A0;cost:
117&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;-&#x00A0;x&#x00A0;-&#x00A0;y[1]&#x00A0;-&#x00A0;y[2]&#x00A0;;
118&#x00A0;<br />
119&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;subject&#x00A0;to
120&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;c1:&#x00A0;(&#x00A0;y[1]&#x00A0;-&#x00A0;1/2&#x00A0;)^2&#x00A0;+&#x00A0;(y[2]&#x00A0;-&#x00A0;1/2)^2&#x00A0;&#x003C;=&#x00A0;1/4&#x00A0;;
121&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;c2:&#x00A0;x&#x00A0;-&#x00A0;y[1]&#x00A0;&#x003C;=&#x00A0;0&#x00A0;;
122&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;c3:&#x00A0;x&#x00A0;+&#x00A0;y[2]&#x00A0;+&#x00A0;z&#x00A0;&#x003C;=&#x00A0;2;
123&#x00A0;<br />
124&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;option&#x00A0;solver&#x00A0;bonmin;&#x00A0;#&#x00A0;Choose&#x00A0;BONMIN&#x00A0;as&#x00A0;the&#x00A0;solver&#x00A0;(assuming&#x00A0;that
125&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;#&#x00A0;bonmin&#x00A0;is&#x00A0;in&#x00A0;your&#x00A0;PATH
126&#x00A0;<br />
127&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;solve;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;#&#x00A0;Solve&#x00A0;the&#x00A0;model
128&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;display&#x00A0;x;
129&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;display&#x00A0;y;
130&#x00A0;<br />
131</div>
132</td></tr></table>
133<!--l. 98--><p class="nopar" > </div> 
134<!--l. 101--><p class="indent" >   (This example can be found in the subdirectory <span 
135class="cmtt-10">Bonmin/examples/amplExamples/</span>
136of the <span 
137class="cmtt-10">BONMIN</span>&#x00A0;package.)
138<!--l. 104--><p class="indent" >    </div> <div class="story"> <h3><a name=  &#8221;sub&#x02D9;sec:prio&#8221; ></a> Setting up branching priorities, directions and declaring SOS1
139constraints in ampl  </h3>   Branching priorities, branching directions and pseudo-costs can
140be passed using <span 
141class="cmtt-10">Ampl </span>suffixes. The suffix for branching priorities is <span 
142class="cmtt-10">"priority"</span>
143(variables with a higher priority will be chosen first for branching), for branching
144direction is <span 
145class="cmtt-10">"direction" </span>(if direction is 1 the <span 
146class="cmsy-10">&#x2265; </span>branch is explored first, if direction
147is <span 
148class="cmsy-10">-</span>1 the <span 
149class="cmsy-10">&#x2264; </span>branch is explored first), for up and down pseudo costs <span 
150class="cmtt-10">"upPseudoCost"</span>
151and <span 
152class="cmtt-10">"downPseudoCost" </span>respectively (note that if only one of the up and
153down pseudo-costs is set in the <span 
154class="cmtt-10">Ampl </span>model it will be used for both up and
155down).
156<br class="newline" />
157<!--l. 114--><p class="indent" >   For example, to give branching priorities of 10 to variables <span 
158class="cmtt-10">y </span>and 1 to variable <span 
159class="cmtt-10">x</span>
160and to set the branching directions to explore the upper branch first for
161all variables in the simple example given, we add before the call to solve:
162<div id="verbatim">
163
164   <table 
165class="verbatim"><tr class="verbatim"><td 
166class="verbatim"><div class="verbatim">
167&#x00A0;<br />suffix&#x00A0;priority&#x00A0;IN,&#x00A0;integer,&#x00A0;&#x003E;=0,&#x00A0;&#x003C;=&#x00A0;9999;
168&#x00A0;<br />y[1].priority&#x00A0;:=&#x00A0;10;
169&#x00A0;<br />y[2].priority&#x00A0;:=&#x00A0;10;
170&#x00A0;<br />x.priority&#x00A0;:=&#x00A0;1;
171&#x00A0;<br />
172&#x00A0;<br />suffix&#x00A0;direction&#x00A0;IN,&#x00A0;integer,&#x00A0;&#x003E;=-1,&#x00A0;&#x003C;=1;
173&#x00A0;<br />y[1].direction&#x00A0;:=&#x00A0;1;
174&#x00A0;<br />y[2].direction&#x00A0;:=&#x00A0;1;
175&#x00A0;<br />x.direction&#x00A0;:=&#x00A0;1;
176&#x00A0;<br />
177</div>
178</td></tr></table>
179<!--l. 130--><p class="nopar" > </div> 
180<!--l. 133--><p class="indent" >   SOS Type-1 branching is also available in <span 
181class="cmtt-10">BONMIN</span>&#x00A0;from <span 
182class="cmtt-10">Ampl</span>. We follow the
183conventional way of doing this with suffixes. Two type of suffixes should be
184declared:
185<!--l. 137--><p class="indent" >   <div id="verbatim">
186
187   <table 
188class="verbatim"><tr class="verbatim"><td 
189class="verbatim"><div class="verbatim">
190suffix&#x00A0;sosno&#x00A0;IN,&#x00A0;integer,&#x00A0;&#x003E;=1;&#x00A0;&#x00A0;#&#x00A0;Note&#x00A0;that&#x00A0;the&#x00A0;solver&#x00A0;assumes&#x00A0;that&#x00A0;these
191&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;#&#x00A0;&#x00A0;&#x00A0;values&#x00A0;are&#x00A0;positive&#x00A0;for&#x00A0;SOS&#x00A0;Type&#x00A0;1
192&#x00A0;<br />suffix&#x00A0;ref&#x00A0;IN;
193</div>
194</td></tr></table>
195<!--l. 142--><p class="nopar" > </div> 
196<!--l. 145--><p class="indent" >   Next, suppose that we wish to have variables
197<!--l. 147--><p class="indent" >   <div id="verbatim">
198
199   <table 
200class="verbatim"><tr class="verbatim"><td 
201class="verbatim"><div class="verbatim">
202var&#x00A0;X&#x00A0;{i&#x00A0;in&#x00A0;1..M,&#x00A0;j&#x00A0;in&#x00A0;1..N}&#x00A0;binary;
203</div>
204</td></tr></table>
205<!--l. 150--><p class="nopar" > </div> 
206and the &#8220;convexity&#8221; constraints:
207<!--l. 154--><p class="indent" >   <div id="verbatim">
208
209   <table 
210class="verbatim"><tr class="verbatim"><td 
211class="verbatim"><div class="verbatim">
212subject&#x00A0;to&#x00A0;Convexity&#x00A0;{i&#x00A0;in&#x00A0;1..M}:
213&#x00A0;<br />&#x00A0;&#x00A0;&#x00A0;sum&#x00A0;{j&#x00A0;in&#x00A0;1..N}&#x00A0;X[i,j]&#x00A0;=&#x00A0;1;
214</div>
215</td></tr></table>
216<!--l. 158--><p class="nopar" > </div> 
217<!--l. 161--><p class="indent" >   (note that we must explicitly include the convexity constraints in the <span 
218class="cmtt-10">Ampl</span>
219model).
220<!--l. 163--><p class="indent" >   Then after reading in the data, we set the suffix values: <div id="verbatim">
221
222   <table 
223class="verbatim"><tr class="verbatim"><td 
224class="verbatim"><div class="verbatim">
225&#x00A0;<br />#&#x00A0;The&#x00A0;numbers&#x00A0;&#8216;val[i,j]&#8217;&#x00A0;are&#x00A0;chosen&#x00A0;typically&#x00A0;as
226&#x00A0;<br />#&#x00A0;&#x00A0;&#x00A0;&#x00A0;&#x00A0;the&#x00A0;values&#x00A0;&#8216;represented&#8217;&#x00A0;by&#x00A0;the&#x00A0;discrete&#x00A0;choices.
227&#x00A0;<br />let&#x00A0;{i&#x00A0;in&#x00A0;1..M,&#x00A0;j&#x00A0;in&#x00A0;1..N}&#x00A0;X[i,j].ref&#x00A0;:=&#x00A0;val[i,j];
228&#x00A0;<br />
229&#x00A0;<br />#&#x00A0;These&#x00A0;identify&#x00A0;which&#x00A0;SOS&#x00A0;constraint&#x00A0;each&#x00A0;variable&#x00A0;belongs&#x00A0;to.
230&#x00A0;<br />let&#x00A0;{i&#x00A0;in&#x00A0;1..M,&#x00A0;j&#x00A0;in&#x00A0;1..N}&#x00A0;X[i,j].sosno&#x00A0;:=&#x00A0;i;
231</div>
232</td></tr></table>
233<!--l. 173--><p class="nopar" > </div> 
234<!--l. 176--><p class="indent" >    </div> <div class="story"> <h3><a name=  &#8221;sec:run&#x02D9;gams&#8221; ></a> From <span 
235class="cmtt-10">Gams </span> </h3>  Thanks to the <a 
236href="http://projects.coin-or.org/GAMSlinks" >GAMSlinks</a> project, Bonmin is
237available in <span 
238class="cmtt-10">Gams </span>since release 22.5 of the <a 
239href="http://www.gams.com/" ><span 
240class="cmtt-10">GAMS</span></a> modeling system. The system is
241available for <a 
242href="http://download.gams-software.com/" >download from GAMS</a>. Without buying a license it works as a demo
243with limited capabilities. Documentation for using <span 
244class="cmtt-10">BONMIN</span>&#x00A0;in <span 
245class="cmtt-10">GAMS </span>is available
246<a 
247href="http://www.gams.com/solvers/coin.pdf" >here</a>.
248<!--l. 187--><p class="indent" >    </div> <div class="story"> <h3><a name=  &#8221;sec:run&#x02D9;cpp&#8221; ></a> From a C/C++ program  </h3>   <span 
249class="cmtt-10">BONMIN</span>&#x00A0;can also be run from within a
250C/C++ program if the user codes the functions to compute first- and second-order
251derivatives. An example of such a program is available in the subdirectory
252<span 
253class="cmtt-10">CppExample </span>of the <span 
254class="cmtt-10">examples </span>directory. For further explanations, please refer to this
255example and to the reference manual.
256   
257</body></html> 
258
259
260
Note: See TracBrowser for help on using the repository browser.