MoleQueue JSON-RPC Specification

JSON-RPC specification

This is the proposed communication protocol, it is neither final nor implemented!

The JSON-RPC specification is here. In a nutshell, the protocol consists of three message types: requests, responses, and notifications. Every request must be met with a reply, and a notification is simply a request with a null id.

Requests are JSON objects with three name/value pairs:

• method (String): The method requested.
• params (Array): An array of parameters for the requested method.
• id (Value): A unique identifier.

Each request is met with a reply of the following format:

• result (Object): The result of the request. Must be null if an error occurred.
• error (Object): A description of the error. Must be null if no error occurred.
• id (Value): Must be the same as the identifier used in the request.

As mentioned above, notifications follow the same format as requests, but use a null identifier.

Supported Messages

The following sections detail the requests, responses, and notifications that MoleQueue recognizes:

List of available Queues/Programs

To obtain a list of the available Queues and the programs supported by them, submit a request for the method "listQueues" with no parameters. MoleQueue will reply with an object containing a dictionary with user-set names identifying each queue, along with an array of the programs supported by each queue.

Client request:

{
  "method": "listQueues",
  "params": null,
  "id": XXX
}

Server response:

{
  "result": {
    "Big cluster SGE" : {
      "programs" : [ "GAMESS",
                     "MOPAC",
                     "Gaussian",
                     "NWChem",
                     ...
                   ]
    },
    "Remote cluster PBS" : {
      "programs" : [ "GAMESS",
                     "MOPAC",
                     "Gaussian",
                     "NWChem",
                     ...
                   ]
    },
    "Local" : {
      "programs" : [ "GAMESS",
                     "MOPAC",
                     "Gaussian",
                     "NWChem",
                     ...
                   ]
    },
  },
  "error": null,
  "id": XXX
}

Request new job submission

Client request:

Two supported forms:

• Input file provided as a single string

{
  "method": "submitJob",
  "params": {
    "queue": "Remote cluster PBS",
    "program": "MOPAC",
    "description": "PM6 H2 optimization",
    "inputAsString": "PM6\n\nH 0.0 0.0 0.0\nH 1.0 0.0 0.0\n"
  },
  "id": XXX
}

• Input file provided as a path

{
  "method": "submitJob",
  "params": {
    "queue": "Remote cluster PBS",
    "program": "MOPAC",
    "description": "PM6 H2 optimization",
    "inputAsPath": "/path/to/local/input/file/named/h2.mop"
  },
  "id": XXX
}

Additional (optional) parameters may be used to tweak job behavior further. Default values are provided in parenthesis:

• cleanRemoteFiles: (false) If true, any remote working directories are deleted.
• retrieveOutput: (true) If true, output files are copied back into the local working directory.
• outputDirectory: (null) If not null, this must be a string specifying a path to place completed output files, instead of the local working directory.
• cleanLocalWorkingDirectory: (false) If true, the local temporary working directory will be removed on successful job completion.
• hideFromQueue: (false) If true, the job will not be displayed in the MoleQueue GUI by default (useful for automated batch jobs).
• popupOnStateChange: (true) If true, a notification popup will be displayed system tray when the job's state changes.

Server response:

• If successful, some identifiers are returned:

{
  "result": {
    "molequeue id": 17,
    "job id": 123456,
    "temporary working directory": "/tmp/MoleQueue/17/"
  }  
  "error": null,
  "id": XXX
}

molequeue id is a identifier that is unique to this instance of MoleQueue, while job id is unique to the queue (Either a DRMS job id or a local process id).

• If unsuccessful, a descriptive error string is returned:

{
  "result": null,
  "error": "Cannot write to local directory \"/tmp/MoleQueue/17/\". Permission denied.",
  "id": XXX
}

Notification of job state change

When a job changes state, MoleQueue will send a notification to all active connections of the following form:

{
  "method": "jobStateChanged",
  "params": {
    "molequeue id": 17,
    "old state": "RemoteQueued",
    "new state": "Running"
  },
  "id": null
}

Valid states are:

• None: Initial state of job, should never be entered.
• Accepted: Job has been received and is being prepared (Writing input files, etc).
• LocalQueued: Job is being queued locally, either waiting for local execution or remote submission.
• Submitted: Job has been submitted to a remote queuing system.
• RemoteQueued: Job is pending execution on a remote queuing system.
• Running: Job is running, either remotely or locally.
• Finished: Job has completed.