Calculation runs

vibe-sketch prepares supported inputs and can submit them through an installed, configured vibe-queue. The calculation program executes them; the sketcher stores submission references and can explicitly import supported results. For a worked example, follow the queue lifecycle tutorial.

Inputs, jobs, runs and results

Item	What it represents	Where it lives
Input file	Geometry and settings translated by a writer	Your export directory or the queue workspace
Document job	A species, program and program-neutral specification	The saved QVF/VSK document’s jobs list
Run record	One submission’s queue run ID, host and timestamp	A job’s runs list
Live run state	The queue’s report of execution	The configured queue’s state, queried when needed
Calculation result	Output, final geometry and other program-specific data	The calculation workspace and retrieved result files

Writing an input does not create a queue run. Submitting the same species, program and specification again appends a new run to its matching job; it does not reuse or deduplicate the earlier calculation. A different specification creates another job. Save after submission to retain the returned run records.

Editing away a species also removes its jobs and run records from the sketch. Save a copy first when retaining that history matters; external queue runs continue independently. See species identity.

A saved run record does not contain a copy of the queue’s workspace or its results. Reopening the document with a different queue configuration can leave those run IDs unresolved. Preserve the result files separately.

Readiness and submission

GET /api/queue returns installed, daemon, programs and message. Check all of them: an installed integration is not proof that its daemon is running, and an available ORCA executable does not make vibe-qc available. The current sketcher integration submits locally through vibe-queue with host localhost. It has no remote-host selector.

Program	How the sketcher selects the executable
orca	An absolute binary path registered as the queue program orca
vibeqc	The Python registered for vibeqc (also accepts vibe-qc), or the sketcher’s interpreter if it can import the complete vibe-qc package

Naming support alone does not establish a working vibe-qc calculation engine. Start the sketch server in the same queue environment used to register and inspect the programs. See integration setup.

CLI submit, REST /submit and MCP submit_jobs generate missing geometries before submission. The lower-level SDK vibesketch.queue.submit does not: embed first and inspect its report. The SDK returns a Submission; retain and save Submission.document to keep the job/run records and group metadata. Its submitted list identifies started runs, and refused maps species IDs to reasons.

A submission groups the selected species in the queue. Reaction and scheme selection deduplicate shared species. The response includes a group ID and per-species runs; some inputs can be refused while other species are submitted, so inspect both lists. For vibe-qc, submission prefers a pinned QVF job container and records fallbacks when it uses a script instead. container: false over REST or --script on the CLI selects scripts explicitly. See QVF job containers. Unlike the stored input-export route, REST submission can return HTTP 200 with no submitted runs and a nonempty refused mapping. The status code alone is insufficient. A timeout or broken connection does not establish that nothing was submitted; inspect the queue and document before retrying.

Resources

resources.nprocs becomes the queue CPU request, defaulting to one when no resources are specified. For ORCA, it also controls %pal. The vibe-qc writer emits num_threads when the requested count is greater than one; a value of one is not emitted as an explicit thread-limit argument.

For ORCA, maxcore_mb is memory per process, not a total budget. The queue memory request is rounded up from nprocs * maxcore_mb / 0.75, reserving headroom beyond the input’s %maxcore setting. For example, four processes at 3000 MB each request 16000 MB from the queue. Without a maxcore_mb value, this integration supplies no explicit memory request.

The vibe-qc writer refuses maxcore_mb because it cannot translate that per-core setting into the program’s memory interface. See input writers for supported task and resource combinations.

Status and cancellation

vibe-sketch runs DOCUMENT --json, REST /api/documents/{id}/runs and MCP show_runs query saved run records, newest submission first. Returned rows identify the job, species, program, task, method, run and submission time. When the queue has the run, they also expose its state, exit code, start and finish times, failure reason and working directory as available.

State or field	Interpretation
pending, running	The run has not reached a terminal state
completed	The queue reports execution complete; inspect the scientific output before accepting the result
failed, killed, interrupted, oom_killed, starved, time_exceeded, aborted_by_queue	Terminal states recognized by the integration; inspect the failure reason and output
unknown	The queue cannot find the saved run ID; this is not a successful result
finished	True for any recognized terminal state, including failure and cancellation

Cancel by the actual run ID, using the browser control, vibe-sketch cancel, REST /api/queue/runs/{run}/cancel or MCP cancel_run. A finished run returns 409 over REST; a missing run returns 404. Cancellation does not remove the saved job or run record. Quitting the sketcher does not cancel queued work.

Retrieve and keep results

Use vibe-queue’s result-retrieval workflow as shown in reopen, fetch and inspect. Check method, charge, multiplicity, convergence and final geometry in the actual output. Queue completion and a zero process exit code are not alone scientific acceptance criteria.

Open supported result files in vibe-view for detailed inspection. Importing a result QVF into vibe-sketch reads supported structures and sketch content; it does not retain every calculation payload. Save an edited sketch to a new file and keep the original archive.

For results imported onto recorded runs, reaction energies, provenance and exported energy tables, follow results. Reaction-path preparation is covered by NEB inputs, and staged recipes and campaign acceptance by staged calculations. These are explicit workflows, not consequences of submitting an ordinary single-species input. Consult the roadmap for release and qualification boundaries.