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.
Client programs should use the following URL and port number to access NEOS XML-RPC server:
https://neos-server.org:3333
| Function | Description |
|---|---|
| help() | |
| 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 |
| 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" |
| getCompletionCode(jobNumber, password) | Gets the completion code for "Done" jobs; result is undefined for jobs that are "Waiting" or "Running". Returns "Normal", "Out of memory", "Timed out", "Disk Space", "Server error", "Unknown Job", or "Bad Password" |
| getJobInfo(jobNumber, password) | Gets information on the job. Returns a tuple (category,
solver_name, input, status, completion_code) |
| 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) |
| emailJobResults(jobNumber, password) | Results for a finished job will be emailed to the email address specified in the job submission. If results are too large for email, they will not be emailed (though they can be accessed via the NEOS website |
| 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) |
| getOutputFile(jobNumber, password, fileName) |
Retrieve a named output file from NEOS where fileName is one of the
following: 'results.txt', 'ampl.sol', 'solver-output.zip', 'job.in',
'job.out', 'job.results'.
Note: the existence of a given file may depend on the solver or
options selected when the job is started. If the job is still
running, then this function will block until the job is finished.
This function will return a base-64 encoded object, which may be an error message if the requested file does not exist or if an illegal fileName argument is passed. Please read your XML-RPC client documentation for decoding a successful file return. |