open-standards/wai/wai-quantum-service/docs/scheduler.md

The job service as a scheduler's resource

An on-premises batch scheduler, or a resource-management interface in front of one, can hand the job service to its batch jobs as a resource, the way it hands out processors or accelerators. The command line's wai-quantum task is the adapter. It follows the shape these interfaces share, described here by function:

function	wai-quantum task …	what it does
describe the resource	target	the service's methods, limits, store, metering and receipt keys, as JSON
check it is accessible, and acquire it	acquire	checks the service is healthy and takes this client now, and opens a lease (exit 69 if not)
start a task	start JOB.json	submits a job or a set under the lease, prints its id
a task's state	status ID	queued, running, done, failed, cancelled or interrupted (exit 0 done, 1 ended otherwise, 2 still active)
wait for a task	wait ID	follows it to its end, each state on standard error
a task's result	result ID	its request and result as JSON, the receipt checked first (exit 1 if it does not verify)
stop a task	stop ID	cancels it
release the resource	release	stops every task of the lease still queued or running, and closes it

The exit statuses follow the sysexits convention batch scripts test for: 65 a job file that does not read, 69 the resource unavailable or refusing, 75 a refusal to retry later (the client's limits, a full queue).

The lease

The lease is a file: --lease, or WAI_QUANTUM_LEASE, by default wai-quantum-lease.json in the working directory. It names the service, the moment it was acquired, the service's receipt key and limits then, and every task started under it. The service itself holds no reservation: the lease is the adapter's record of what one allocation started, so that releasing it stops exactly those tasks.

Wiring it to a scheduler

A scheduler runs a prologue before a batch job starts and an epilogue after it ends, however it ends. Point both at the adapter, and give the job the service's address (and, for a private deployment, its key) in its environment:

# prologue, before the batch job: the resource must be there, and take this client
export WAI_QUANTUM_SERVICE=https://quantum.example.org/quantum-jobs
export WAI_QUANTUM_LEASE="$JOB_DIR/wai-quantum-lease.json"
wai-quantum task acquire || exit 69

# the batch job
id=$(wai-quantum task start sweep.json)
wai-quantum task wait "$id"
wai-quantum task result "$id" > result.json      # checked against its receipt first
wai-quantum verify result.json                   # and again, by anyone, later

# epilogue, after the batch job, however it ended: no task outlives the allocation
wai-quantum task release

sweep.json is any job the service takes. A set or a sweep runs as one task, one result per item and one receipt binding them, so a parameter scan is a single task, not one per point:

{ "qasm": "OPENQASM 3.0;\ninput float theta;\nqubit[2] q;\nrx(theta) q[0];\ncx q[0], q[1];\n",
  "sweep": { "theta": [0.0, 0.25, 0.5, 0.75, 1.0] },
  "observables": ["Z0 Z1"] }

Before committing an allocation to it, a job can be planned without running: wai-quantum submit prog.qasm --dry-run gives the method, the memory, the estimated time and energy with their basis, the bounds that apply, and whether the service would take it now.

Limits and keys

The public service counts a client by its address. A batch system submits from a few login or compute nodes on behalf of many people, so on a shared deployment give the scheduler its own API key (WAI_QUANTUM_API_KEY, see self-host.md). Its limits are then counted by the key's name, and WAI_QSVC_CLIENT_ACTIVE, WAI_QSVC_CLIENT_GB, WAI_QSVC_CLIENT_BURST, WAI_QSVC_CLIENT_READS and WAI_QSVC_CLIENT_CHECKS (how many of its submissions and checks are read at once; more wait behind them) size them. Every answer carries the client's submission window in RateLimit-Policy and RateLimit, and a refusal past it carries Retry-After. The adapter exits 75 on such a refusal, which a scheduler can treat as "requeue".