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://tldp.org/HOWTO/XML-RPC-HOWTO/index.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.
Please see this section for example XML-RPC client written in Python.


The NEOS XML-RPC server is located at the URL http://neos-1.neos-server.org:3332.

Routines for getting information from NEOS

help()
emailHelp()
Returns general help message for email users
welcome()
Returns a welcome message.
version()
Returns version number of the NEOS server (string).
ping()
Verifies that this NeosServer is running.
 
Returns message 'NeosServer is alive'
printQueue()
Returns a string containing the current NEOS jobs.
getSolverTemplate(category, solvername, inputMethod)
Returns a template for a given solver.
 
If the solver category:solvername:inputMethod exists on NEOS, then
an XML template is returned for using this solver via the XML-RPC
or email interfaces.
getXML(category, name, input)
Returns the XML description of the given solver.
 
This will be deprecated.  Use getSolverTemplate.
listAllSolvers()
Lists all solvers available on NEOS.
 
Returns a list of category:solver:inputMethod
listCategories()
Lists all categories available on NEOS
 
Returns a dictionary with entries {'abbreviated name':'full name',...}
If you want to provide a solver to NEOS in an unavailable category,
please email the NEOS administrators and we will add it for you.
listSolversInCategory(category)
List all NEOS solvers in this category
 
Returns a list of solver:input for every solver in the category
(category can be abbreviation or full_name)

Routines for submitting and retrieving jobs on NEOS

submitJob(xmlstring, user='', interface='', id=0)
Submit an optimization job to NEOS.
 
Use this method to submit your job to NEOS.
It will return a tuple containing (jobnumber,password).
You can the use this jobnumber and password to get the
results or status of your job using the methods getStatus,
getIntermediateResults, and getFinalResults.
 
In case of an error (NEOS Job queue is full), submitJob() will
return (0,errorMessage)
 
For more information on the format of the xmlstring, you can
use the getSolverTemplate function.
getJobStatus(jobNumber, password)
Get the current status of your job.
 
Returns "Done", "Running", "Waiting", "Unknown Job", or "Bad Password".
getJobInfo(jobNumber, password)
Gets information on the job.
returns a four-tuple (category, solver_name, input, status).
killJob(jobNumber, password, killmsg='')
Cancel a NEOS submission.
 
If you want to cancel a job submission running on NEOS (or
waiting to run on NEOS), then use this method.  We require
the job password to prevent abuse of this function.
getFinalResults(jobNumber, password)
Gets results of job from NEOS.
 
Retrieve results from NEOS.  If the job is still running, then
this function will hang until the job is finished.
 
This function will return a base-64 encoded object.
Please read your XML-RPC client documentation for decoding.  
 
(For Python's xmlrpclib library, you can use the object's 'data'
data member).
getIntermediateResults(jobNumber, password, offset)
Gets intermediate results of job from NEOS.
 
Retrieve intermediate results from NEOS, starting at the character
offset up to the last received data.  Intermediate results are usually
the standard output of the solver daemon.
 
If the job is still running, then this function will hang until
another packet of output is sent to NEOS or the job is finished.
The offset 
 
This function will return a tuple of thebase-64 encoded object and
the new offset (object, newoffset).  The offset refers to uncoded
characters.  Please read your XML-RPC client documentation for decoding.  
 
(For Python's xmlrpclib library, you can use the object's 'data'
data member).
getFinalResultsNonBlocking(jobNumber, password)
Gets results of job from NEOS (non-blocking).
 
Retrieve results from NEOS.  If the job is still running, then
this function will return an empty string (base-64 encoded).
 
This function will return a base-64 encoded object.
Please read your XML-RPC client documentation for decoding.  
 
(For Python's xmlrpclib library, you can use the object's 'data'
data member).
getIntermediateResultsNonBlocking(jobNumber, password, offset)
Gets intermediate results of job from NEOS.
 
Retrieve intermediate results from NEOS.  Intermediate results are
usually the standard output of the solver daemon.
 
This function will return a tuple of thebase-64 encoded object and
the new offset.  The offset refers to uncoded characters.
Please read your XML-RPC client documentation for decoding.  
 
(For Python's xmlrpclib library, you can use the object's 'data'
data member).

Routines for maintaining solvers on NEOS

pingHost(user, hostname)
Verifies a solver daemon.
 
If there is a solver daemon running on this host
under the user's account, then a confimation message
is returned ('OK').  Otherwise, an error message is returned.
validateSolverXML(xmlString)
Checks the syntax of the solver XML description.
 
Before submitting your solver description to NEOS, you can use
this method to check if your syntax is correct.  It will either
return 'OK' or an error message.
registerSolver(xmlString)
Register a new solver on NEOS
 
This will create a new solver on NEOS.  Anyone is permitted
to register their solver on NEOS.  If you would like to make
your solver available, please read the documentation at
@NEOS_WEB_SITE@/SolverHowTo.html
removeSolver(category, solvername, input, password)
Remove a solver from NEOS.
 
If you need to temporarily disable your solver, then you can use
the disableSolver method instead.
disableSolver(category, solvername, input, password)
Temporarily disable your solver.
 
If you wish to temporarily remove your solver from NEOS, then you
can use this method.  Your solver will be removed from the NEOS solvers
index, and any users who attempt to use your solver while
disabled will receive a message that it has been disabled.
Use 'enableSolver' to reenable.
enableSolver(category, solvername, input, password)
Reenables a solver that has been disabled.
 
To provide a new solver, use registerSolver.
registerExample(xmlstring, password)
Register an example on the NEOS web pages.
 
This function will upload an example onto the NEOS web page
for your solver.
removeExample(category, solvername, input, passwd, examplename)
Remove an example from NEOS
 
This will remove the example from your NEOS solver page.

Using Python to interact with NEOS via XML-RPC

Below is a simple Python script that accept NEOS Job XML file name as an input. It will submit a job to NEOS and print result to console.
To generate a job XML, please go to web submission interface of each solver, then upload input files as normal submission. Check "dry-run" box at the bottom and hit submit.
This will create a job XML that can be used with this program. Copy its content and write to a file. ( eg. job.xml )
In addition, using "queue" as argument to the program will print the current status of NEOS job queue.

Example
./NeosClient.py job.xml

A Python client is also included in the NEOS download package as NeosClient.py


#!/usr/bin/env python
#########################################
# NeosClient.py
#########################################
import sys
import xmlrpclib
import time

NEOS_HOST="neos-dev1.discovery.wisc.edu"
NEOS_PORT=3332

if len(sys.argv) != 2:
  sys.stderr.write("Usage: NeosClient <xmlfilename | queue> ")
  sys.exit(1)

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

if sys.argv[1] == "queue":
  #Print NEOS job queue
  msg = neos.printQueue()
  sys.stdout.write(msg)

else:
  #Read XML file
  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 " % jobNumber)

  offset=0
  status=""
  #Print out partial job output while job is running
  while status != "Done":
    (msg,offset) = neos.getIntermediateResults(jobNumber,password,offset)
    sys.stdout.write(msg.data)
    status = neos.getJobStatus(jobNumber, password)
 
  #Print out the final result
  msg = neos.getFinalResults(jobNumber, password).data
  sys.stdout.write(msg)



Submit comments and questions Terms of Use