MoleQueue Protocol

avogadro-queue.md

MoleQueue JSON-RPC Protocol Summary

The MoleQueue client used by Avogadro's input generators lives in avogadrolibs/avogadro/molequeue/client/. This document summarizes the JSON-RPC protocol so it can be adapted to other queue systems.

Transport

• Wire: Qt QLocalSocket (Unix domain socket / Windows named pipe), default name MoleQueue. See jsonrpcclient.cpp:35-58.
• Framing: QDataStream (Qt 4.8 version) writes the JSON document as a length-prefixed QByteArray — first 4 bytes are big-endian byte count, then the UTF-8 JSON bytes. A non-Qt client must replicate this framing. See jsonrpcclient.cpp:83-93 and jsonrpcclient.cpp:126-136.
• Envelope: plain JSON-RPC 2.0. Every request is {"jsonrpc":"2.0","id":<int>,"method":"<name>","params":{...}}; replies carry result or error. The id is a per-client counter. See jsonrpcclient.cpp:75-81.

Methods

All dispatched by client.cpp.

Method	Params	Result
listQueues	none	{ "<queueName>": ["program1", ...] }
submitJob	the JobObject (see below)	{ "moleQueueId": <uint> }
lookupJob	{ "moleQueueId": <uint> }	full job JSON
cancelJob	{ "moleQueueId": <uint> }	{ "moleQueueId": <uint> }
registerOpenWith	file-handler registration	—
listOpenWithNames	none	array of handler names
unregisterOpenWith	{ "name": "<handlerName>" }	—

Server-pushed notification: jobStateChanged with params = { moleQueueId, oldState, newState }.

Terminal job states (from molequeuewidget.h:71-81): Finished, Error, Canceled.

submitJob Params (the JobObject)

Built up in jobobject.cpp and finalized in molequeuewidget.cpp:134-165. All fields are optional unless the server requires them; missing values get server defaults.

{
  "queue":       "<queueName from listQueues>",
  "program":     "<programName from listQueues>",
  "description": "free-text job title",
  "numberOfCores":      0,
  "cleanRemoteFiles":   false,
  "hideFromGui":        false,
  "popupOnStateChange": false,

  "inputFile": {
    "filename": "job.inp",
    "contents": "...full text of input file..."
  },
  "additionalInputFiles": [
    { "filename": "extra.dat", "contents": "..." },
    { "path": "/absolute/path/to/file" }
  ]
}

A file spec is either {filename, contents} (inline payload) or {path} (server-side absolute path) — see jobobject.cpp:111-125. The "main" input is named by the input generator's mainFileName(); everything else goes into additionalInputFiles (inputgeneratorwidget.cpp:318-330).

Typical Client Flow

1. Connect to the local socket.
2. listQueues → populate UI; user picks a queue/program pair.
3. submitJob with the JobObject → capture returned moleQueueId.
4. Listen for jobStateChanged notifications (or poll lookupJob) until terminal state.
5. On Finished, fetch outputs. The input generator emits openJobOutput(job) and the app reads files from the job's working directory via the lookup result.

Adapting to Another Queue System

An adapter would need to provide:

• A socket (or HTTP) endpoint speaking JSON-RPC 2.0 with the seven method names above — at minimum listQueues, submitJob, lookupJob, cancelJob, plus the jobStateChanged notification.
• Translation of the JobObject's queue / program / numberOfCores / inputFile / additionalInputFiles into whatever the target scheduler expects (Slurm/PBS submit script, REST payload, etc.).
• Either keep the Qt length-prefixed framing (so JsonRpcClient works unchanged), or add a new transport at the JsonRpcClient layer — Client itself is transport-agnostic above that.
• A mapping from scheduler-native states back to MoleQueue's vocabulary (Finished / Error / Canceled are the ones the UI checks).

Key Source Files

• avogadrolibs/avogadro/molequeue/client/jsonrpcclient.{h,cpp} — transport + framing.
• avogadrolibs/avogadro/molequeue/client/client.{h,cpp} — method dispatch and signal/slot API.
• avogadrolibs/avogadro/molequeue/client/jobobject.{h,cpp} — job payload builder.
• avogadrolibs/avogadro/molequeue/molequeuewidget.cpp — UI that produces the final JobObject.
• avogadrolibs/avogadro/molequeue/inputgeneratorwidget.cpp — input-generator → submission flow.