NEOS Server Home

NEOS API

NEOS runs an XML-RPC server to communicate with clients for submitting and retrieving jobs.  The server can communicate with clients written in Python, Perl, PHP, C, C++, Java, Ruby, and probably other languages as well.  More information on XML-RPC and writing clients can be found at http://www.xmlrpc.com or http://xmlrpc-c.sourceforge.net/xmlrpc-howto/xmlrpc-howto.html. Any NEOS job submitted using the XML-RPC API must be formulated in the XML format required by the desired solver. More information on this format can be found by following the 'XML-RPC' link on the solver's page.


The NEOS XML-RPC server is located at the URL http://neos.mcs.anl.gov:3332. It supports the following methods:

string help()
Returns a help message describing this interface.
string welcome()
Returns a welcome message.
string ping()
Returns "NEOS Server is alive\n".
string printQueue()
Returns a string of current NEOS jobs.
array listAllSolvers()
Returns an array of strings in format category:solver_name:input.
array listSolversInCategory(string cat)
Same as above, but limited to entries matching category cat.
struct listCategories()
Returns dictionary of "abbreviation: full_name" (or error:errormsg)
array submitJob(string jobxml [,user [,source]])
Submits a job to NEOS.  The jobxml string must be in the format described by the solver's XML-RPC help page.  It returns a two-item list of (int jobnumber, string password) if successful, otherwise returns (0,"").
string getJobStatus(int jobnumber, string passwd)
Returns "Done", "Running", "Waiting", "Unknown Job", or "Bad Password"
string killJob(int jobnumber, string passwd)
Terminates a job from the NEOS server if running, dequeues the job if it is still waiting. Returns a confirmation string or error message.
base64 getFinalResults(int jobnumber, string passwd)
Returns the base64 encoded results of a job.  This method will block until the job has finished running.
array getIntermediateResults(int jobnumber, string passwd, int offset)
This method captures the standard output of the job in real time, starting at offset.  Returns a two-item list of (base64 encoded output, int newoffset).    This method will block until the solver submits its output to NEOS or the job is completed.

A sample Python client is included in the NEOS download package as NeosClient.py:
#!/usr/bin/env python
import sys
import xmlrpclib
import time

from config import Variables

if len(sys.argv) < 2 or len(sys.argv) > 3:
  sys.stderr.write("Usage: NeosClient <xmlfilename | help | queue>\n")
  sys.exit(1)

neos=xmlrpclib.Server("http://%s:%d" % (Variables.NEOS_HOST, Variables.NEOS_PORT))

if sys.argv[1] == "help":
  sys.stdout.write("Help not yet available...\n")

elif sys.argv[1] == "queue":
  msg = neos.printQueue()
  sys.stdout.write(msg)

else:
  xmlfile = open(sys.argv[1],"r")
  xml=""
  buffer=1
  while buffer:
    buffer =  xmlfile.read()
    xml+= buffer
  xmlfile.close()

  (jobNumber,password) = neos.submitJob(xml)
  sys.stdout.write("jobNumber = %d\n" % jobNumber)

  offset=0
  status=""
  while status != "Done":
    (msg,offset) = neos.getIntermediateResults(jobNumber,password,offset)
    sys.stdout.write(msg.data)
    status = neos.getJobStatus(jobNumber, password)

  msg = neos.getFinalResults(jobNumber, password).data
  sys.stdout.write(msg)

@NEOS_WEB_DISCLAIMER@