HelloNEOS example solver

This page will walk you through the process of hooking a solver up to the the NEOS Server. Our example will be a very simple solver that either adds or multiplies two user-given values.

Naming Your Solver

The first step (after downloading and installing) is to create the XML file describing the solver (see Registering Your Solver for for information). We will call our solver 'HelloNEOS'. Because this is an example and there really isn't a name for the input format, we will use the input type 'basic'. The category 'test' is special to NEOS, because anything using this category will be put onto a separate solver testing page. Normally, the category would describe the type of problem you are solving -- 'lp' for Linear Programming, 'bco' for Bound Constrained Optimization, etc. Please contact us if you are having questions about what category your solver might fall under.

So the first few lines of the XML file will look like:

<neos:SolverDescription xmlns:neos="http://www.mcs.anl.gov/neos">
<neos:category>test</neos:category>
<neos:solver>HelloNEOS</neos:solver>
<neos:inputMethod>basic</neos:inputMethod>
<neos:password>hello</neos:password>
<neos:contact>fakeperson@mcs.anl.gov</neos:contact>

You may need to change the name of your solver in case somebody else is also trying out the HelloNEOS solver. And of course, you should use your own email address. This will allow NEOS to send you mail if there are problems with your solver.


Describing the input

The next section describes the input that the solver needs from the user. We will use textfields to get the two numbers that we will multiply or add, and we also want to get the operation itself using radio buttons. The neos:token tag is used to select the input when using the email or XML-RPC interfaces to NEOS, the neos:filename tag indicates the name of the file that will be created on your workstation containing the data, and neos:prompt will give Web users a prompt for what data is expected.
<neos:input TYPE="textfield">
  <neos:token>num1</neos:token>
  <neos:filename>num1</neos:filename>
  <neos:prompt>First Number</neos:prompt>
</neos:input>

<neos:input TYPE="textfield">
  <neos:token>num2</neos:token>
  <neos:filename>num2</neos:filename>
  <neos:prompt>Second Number</neos:prompt>
</neos:input>

<neos:input TYPE="radio">
  <neos:token>operation</neos:token>
  <neos:filename>operation</neos:filename>
  <neos:prompt>Which Operation</neos:prompt>
  <neos:option value="Multiplication" default="true">Multiplication</neos:option>
  <neos:option value="Addition">Addition</neos:option>
</neos:input>

More information on the various input types and tags can be found here.


Designating Workstations

The final bit of the XML file is to tell NEOS what machines your solver will be running on and what user account will be running it. We suggest creating a user account 'neos' to run your solver:
<neos:machine>
  <neos:hostname>lully.mcs.anl.gov</neos:hostname>
  <neos:user>neos</neos:user>
</neos:machine>

If you want to run on more than one workstation, then you will need to add another neos:machine entry. NEOS will then select one of the machines at random whenever it receives a job request for your solver. More information on designating machines and setting time, file, and memory limits can be found here.

Finally, you need to close up your XML file with

</neos:SolverDescription>
The entire HelloNEOS XML file can be found here.

Registering with NEOS

Now you need to send this XML file to NEOS. This can be done with the SolverTools/register.py Python script:
register.py HelloNEOS.txt

This should give you a confirmation message like 'Entering into database'. If there is an error in your XML file, you should get a message explaining why NEOS couldn't parse the file. If you get a message about a wrong password, then somebody else is using the HelloNEOS solver name and you will need to choose another name to use.

Now your solver should be present on NEOS. Look here. Clicking on your solver will show you a web form with two text fields for the numbers and a radio button section for the operation. We're not quite done yet, so submitting your problem won't work yet. You can go ahead and give a try though, you should get some error about not finding a station to run the solver on.


Writing the Driver

The driver is the actual program that will execute on your workstation. You need to be able to read the inputs that the user sent and print out any information you want to return to the user. This driver can be any executable file you create, such as a compiled C program or Python script. Our example script hello.py for the HelloNEOS solver looks like:
#!/usr/bin/env python
import os
print ("Hello NEOS!");

f = open('num1','r')
num1 = float(f.read())
f.close()

f = open('num2','r')
num2 = float(f.read())
f.close()

f = open('operation','r')
operation=f.read()
f.close()

if operation=="Multiplication":
  print "%.5f * %.5f = %.5f" % (num1, num2, num1*num2)
else:
  print "%.5f + %.5f = %.5f" % (num1, num2, num1+num2)

Starting your server

The last step for setting up your solver is to start a server that NEOS will contact when it needs to send your workstation a job. To do this, you need to create a file listing all of the solvers that will be running on your host and where the drivers are located. Since you only have the HelloNEOS solver so far, your file -- let's call it /home/neos/driverlist.txt will look like this:
test:HelloNEOS:basic /path/to/hello.py

Before starting the server, you need to edit the SolverTools/config.py file to give the location of this driverlist.txt file and some directories for running jobs in:

class Variables:
  NEOS_HOST="neos.mcs.anl.gov"
  NEOS_PORT=3332
  JOBSDIR="/home/neos/HelloNEOS/jobs"
  LOGDIR="/home/neos/HelloNEOS/logs"
  TESTDIR="/home/neos/HelloNEOS/test"

  DRIVER_FILE="/home/neos/driverlist.txt"

Now you are ready to go. Just execute

SolverTools/SolverDaemon.py
If you are behind a firewall, then you will need to open up a port. You can choose which port to listen on by giving the port as a command line argument:
SolverDaemon.py 4000

Congratulations, you have created a solver for NEOS. You should be able to access your solver here.


Removing Your Solver

If you wish to remove a solver from NEOS (such as this HelloNEOS example when you are done with it), use the SolverTools/remove.py script:
remove.py test:HelloNEOS:basic password
where 'password' is the password that you selected in the XML file. @NEOS_WEB_DISCLAIMER@