====== GAMS/KESTREL - Remote Solver Execution on NEOS Servers ======


===== Background =====
The Kestrel client/server is a way of sending your GAMS solve job to be solved via the NEOS Server from within your usual GAMS modeling environment and receiving results that can be processed as with any local solver. The solve statement using the GAMS/KESTREL solver invokes a "client" program that sends your problem to a solver running on one of the NEOS Server's remote computers. The results from the NEOS Server are eventually returned through Kestrel to GAMS, where you can view and manipulate them locally in the usual way. The introduction below covers everything you need to know to start using GAMS/KESTREL. Further information about more advanced features and other uses of Kestrel can be found at the  [[http://neos.mcs.anl.gov/neos/kestrel.html|Kestrel page on the NEOS Server]].

===== Installation =====

To get started using this feature, you must obtain the free Kestrel program. Currently GAMS/KESTREL is available for downloading for Windows and Unix.
All of these are obtained by entering your e-mail address where requested on the [[http://www-neos.mcs.anl.gov/neos/kestrel.html|Kestrel homepage]] and clicking on Proceed to Download. On the page that then appears, click on "kestrel client for GAMS" (Windows or Unix)  to download a single file constituting a GAMS/KESTREL installation file. Place the downloaded file in your GAMS system directory and follow the instructions for an [[http://support.gams-software.com/doku.php?id=installation:how_to_install_an_update_in_gams|incremental update]]. 


===== Using GAMS/KESTREL =====
After successful installation of the GAMS/KESTREL package, the kestrel solver can be used to solve a GAMS model remotely. For example, consider the trnsport model from [[http://www.gams.com/modlib/modlib.htm|GAMS Model Library]]. It can be solved locally in GAMS through the following statements,
<code>
model transport /all/; 
solve transport using lp minimizing z;
</code>
which specify the trnsport model and solve it with the default linear programming solver. We can add an option statement to the code to explicitly specify the solver. For example, if we change the linear programming solver to GAMS/MINOS, the code becomes
<code>
model transport /all/; 
option lp=minos;
solve transport using lp minimizing z;
</code>
To solve the same problem remotely through the NEOS Server, we simply change the linear programming solver to kestrel.
<code>
transport.optfile=1;
option lp=kestrel;
solve transport using lp minimizing z;
$echo kestrel_solver minos > kestrel.opt

</code>
The statement ''transport.optfile=1'' specifies that an options file, called kestrel.opt, will be used. The options file contains the remote solver name as well as any options for the remote solver. We instruct the Kestrel solver to use GAMS/MINOS as the remote solver by writing the foloowing kestrel.opt file: ''kestrel_solver minos''.

If you do not know what solvers are available via GAMS/KESTREL, submitting a job with a nonexistent solver set will return a list of enabled solvers.

A subsequent run of the code through the GAMS interpreter results in the transport model being solved through the NEOS Server with the GAMS/MINOS solver. Once the job is submitted to the NEOS Server, a job number, password, and Web address are displayed to the screen, which provide information on accessing the job and viewing the intermediate output, for example,
<code>
--- Executing KESTREL
Job has been submitted to Kestrel
Kestrel/NEOS Job number    : 93478
Kestrel/NEOS Job password  : utiwtxTK
Check the following URL for progress report : 
     http://www-neos.mcs.anl.gov/neos/neos-cgi/check-status.cgi?job=93478&pass=utiwtxTK
     In case of problems, e-mail: neos-comments@mcs.anl.gov
</code>
To look at the solver's output while it is running, point your browser at the URL given in the Kestrel output as shown above, and click on "View Intermediate Results" in the web page that appears. This will take you to another page that shows all of the output produced by the solver for your problem so far. To track the solver's progress, simply update this page periodically.

If the NEOS Server or the network becomes unavailable after the submission, a particular job can be retrieved by setting both the kestrel job and kestrel password in the options file.
<code>
     kestrel_solver minos
     kestrel_job 93478
     kestrel_password utiwtxTK
</code>
Re-issuing the command gams trnsport with this options file will retrieve the results for the specified job number.


===== Advanced GAMS/KESTREL Usage =====
To submit multiple optimization runs and then retrieve them in the order that they were submitted, use the GAMS solvers //kestrelsub// and //kestrelret//. **This feature should be used with care, so as not to overload the Server resources.**

To cancel an optimization run before the solver has completed execution, use a kestrel option file kestrel.opt to specify the appropriate job number and password, and then use the GAMS solver kestrelkil. For example:
<code>
transport.optfile=1;
option lp=kestrelkil;
solve transport using lp minimizing z;
</code>
with option file kestrel.opt
<code>
kestrel_job 93478
kestrel_password utiwtxTK
</code>