NEOS Server Home

NEOS Server: XML-RPC API


Users can submit jobs to and retrieve results from NEOS via NEOS's XML-RPC application programming interface. NEOS runs an XML-RPC server that can communicate with clients written in a variety of languages including C, C++, Java, Perl, PHP, Python, and Ruby. Descriptions of the functions in the NEOS XML-RPC API can be found below.

Any jobs submitted to NEOS using XML-RPC must be in the XML format required by the selected solver. Each solver's format is specified on the solver's interface page. From the list of available solvers, select an appropriate interface page and follow the "XML-RPC" link in the box on the top right corner of the page. Another option is to utilize the Dry Run option when submitting a job via the web interface. Selecting this option will return the XML code for the submitted job.

NEOS currently provides clients in Java and Python.

NEOS XML-RPC Server Information

Client programs should use the following URL and port number to access NEOS XML-RPC server:

https://neos-server.org:3333

Retrieving information from NEOS

Function Description
help()
emailHelp() Returns general help message for users using NEOS via email
welcome() Returns a welcome mesage
version() Returns the version number of the NEOS server as a string
ping() Verifies that the NEOS server is running. Returns the message 'NEOS server is alive'
printQueue() Returns a string with a list of the current jobs on NEOS
getSolverTemplate(category, solvername, inputMethod) Returns a template for the requested solver for the particular category and inputMethod provided. If the particular combination of solver:category:solvername:inputMethod exists on NEOS, then this function returns an XML template to use when submitting jobs via XML-RPC or email
listAllSolvers() Returns a list of all solvers available on NEOS, formated as category:solver:inputMethod
listCategories() Lists all solver categories available onf NEOS, formated as a dictionary with entries {'abbreviated name':'full name', ...}
listSolversInCategory(category) List all NEOS solvers in the specified category, formatted as solver:input. The category can be the full name or the abbreviation

Submitting Jobs and Retrieving Results from NEOS

Function Description
submitJob(xmlstring) or authenticatedSubmitJob(xmlstring, user, password) Submits an optimization job to NEOS. These methods will return a tuple (jobnumber, password). The returned job number and password can be used to get the status of the job or the results of the job. If there is any error (e.g., the NEOS job queue is full), the method will return the tuple (0, errorMessage). Information on the xmlstring format can be retrieved via the getSolverTemplate() function
getJobStatus(jobNumber, password) Gets the current status of the job. Returns "Done", "Running", "Waiting", "Unknown Job", or "Bad Password"
getJobInfo(jobNumber, password) Gets information on the job. Returns a tuple (category, solver_name, input, status)
killJob(jobNumber, password, killmsg="") Cancel a submitted job that is running or waiting to run on NEOS. The job password is required to prevent abuse of this function
getFinalResults(jobNumber, password) Retrieve results from a submitted job on NEOS. If the job is still running, then this function will hang until the job is finished. The function returns a base-64 encoded object. Please read the XML-RPC client documentation on how to decode this. (For Python's xmlrpclib library, you can use the object's 'data' data member)
getIntermediateResults(jobNumber, password, offset) Gets intermediate results of a job submitted to NEOS, starting at the specified character offset up to the last received data. Intermediate results are usually the standard output of the solver daemon. Note that because output does not stream for jobs with "long" priority (default value), getIntermediateResults() will not return any results for long priority jobs. Output does stream for jobs with "short" priority (maximum time of 5 minutes).

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. This function will return a tuple of the base-64 encoded object and the new offset (object, newoffset). The offset refers to uncoded characters. Please read your XML-RPC client documentation for information on how to decode. (For Python's xmlrpclib library, you can use the object's 'data' data member)
getFinalResultsNonBlocking(jobNumber, password) Gets results of a job submitted to NEOS (non-blocking), returned as a base-64 encoded object. If the job is still running, then this function will return an empty string (base-64 encoded). Please read your XML-RPC client documentation for information on how to decode. (For Python's xmlrpclib library, you can use the object's 'data' data member)
getIntermediateResultsNonBlocking(jobNumber, password, offset) Gets intermediate results of a job submitted to NEOS, returned as a base-64 encoded object and the new offset. The offset refers to the uncoded characters. Intermediate results are usually the standard output of the solver daemon. Note that because output does not stream for jobs with "long" priority (default value), getIntermediateResults() will not return any results for long priority jobs. Output does stream for jobs with "short" priority (maximum time of 5 minutes).

Please read your XML-RPC client documentation for information on how to decode. (For Python's xmlrpclib library, you can use the object's 'data' data member)