MoleQueue JSON-RPC Specification: Difference between revisions

From wiki.openchemistry.org
Jump to navigation Jump to search
(Validate JSON, only result or error in responses)
Line 84: Line 84:
     "inputAsString": "PM6\n\nH 0.0 0.0 0.0\nH 1.0 0.0 0.0\n"
     "inputAsString": "PM6\n\nH 0.0 0.0 0.0\nH 1.0 0.0 0.0\n"
   },
   },
   "id": XXX
   "id": "XXX"
}
}
</source>
</source>
Line 98: Line 98:
     "inputAsPath": "/path/to/local/input/file/named/h2.mop"
     "inputAsPath": "/path/to/local/input/file/named/h2.mop"
   },
   },
   "id": XXX
   "id": "XXX"
}
}
</source>
</source>
Line 120: Line 120:
     "job id": 123456,
     "job id": 123456,
     "temporary working directory": "/tmp/MoleQueue/17/"
     "temporary working directory": "/tmp/MoleQueue/17/"
   }
   },
  "error": null,
   "id": "XXX"
   "id": XXX
}
}
</source>
</source>
Line 130: Line 129:
{
{
   "jsonrpc": "2.0",
   "jsonrpc": "2.0",
  "result": null,
   "error": "Cannot write to local directory \"/tmp/MoleQueue/17/\". Permission denied.",
   "error": "Cannot write to local directory \"/tmp/MoleQueue/17/\". Permission denied.",
   "id": XXX
   "id": "XXX"
}
}
</source>
</source>

Revision as of 20:40, 2 May 2012

JSON-RPC specification

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

The JSON-RPC 2.0 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:

{
  "jsonrpc": "2.0",
  "method": "listQueues",
  "id": "XXX"
}

Server response:

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

Request new job submission

Client request:

Two supported forms:

  • Input file provided as a single string
{
  "jsonrpc": "2.0",
  "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
{
  "jsonrpc": "2.0",
  "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:
{
  "jsonrpc": "2.0",
  "result": {
    "molequeue id": 17,
    "job id": 123456,
    "temporary working directory": "/tmp/MoleQueue/17/"
  },
  "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:
{
  "jsonrpc": "2.0",
  "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:

{
  "jsonrpc": "2.0",
  "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.