Calculation runs

vibe-sketcher prepares supported inputs and can submit them through an installed, configured vibe-queue. The self-contained desktop apps do not include vibe-scheduler (what they leave out). 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-scheduler 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-sketcher 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-sketcher 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-scheduler’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-viewer for detailed inspection. Importing a result QVF into vibe-sketcher 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.

Explicit external chain reports

A direct-API calculation need not be a Sketch campaign. The SDK function vibesketch.document.external_results.external_chain_report(document, data, expected_sha256, "real_restricted_cc") verifies a trusted evidence ZIP and returns a separate electronic reaction report. It does not create Queue runs, change the drawing or rewrite campaign reviews. The CLI is vibe-sketcher external-chain-report drawing.vsk chain.zip --sha256 DIGEST --reference-contract real_restricted_cc; --format also accepts csv, markdown and latex. REST uses POST /api/documents/{id}/external-chain-report with base64 data, sha256, reference_contract and optional format. MCP exposes external_chain_report with file, sha256 and the same explicit contract. In Recipes, select Real restricted CC, choose the evidence ZIP and its expected SHA256 under External chain evidence, then Review external chain.

The supported evidence schema is vibe-sketch.external-chain/1. A ZIP contains external-chain.json with schema, a files map from every other member name to its SHA256, and species. Each species ID maps to species_sha256 (the SDK’s species_digest), journal, preparation, and four stages: mace, pbe-opt, pbe-hessian, dlpno. Each stage maps directory and the original job_id. The directories retain unmodified producer acceptance.json, its hashed output files, input.xyz, _vq/terminal-diagnosis.json and _vq/exit-code. The DLPNO stage also retains dlpno.scf.jsonl and requested-cc-options.json. The original journal records completed, accepted jobs; preparation and acceptance reports bind each parent report and input geometry by digest. Optional prior_evidence entries retain a path and role of original-rejection, original-campaign or independent-reference. Their bytes are covered by files; their inclusion does not declare a retry relationship or overturn an original rejection.

The adapter checks complete MACE/PBE/Hessian/correlated chains, original job and terminal identities, atom order and geometry, output checksums, force bounds, stencil agreement (5 cm⁻¹), and the explicit reference contract. The supported surface is PBE/def2-SVP without density fitting, COSX or dispersion, followed by TightPNO DLPNO-CCSD(T)/cc-pVDZ with the recorded T1 implementation. The raw RHF QVF remains reference evidence; the converged correlated sidecar supplies the correlated total. These roles are never relabelled. Balanced reaction reports require matching protocols and software versions, retain generic instability, and provide electronic endpoint energies only. Complex stability, thermal corrections and correlated accuracy are not certified.

Archives are limited to 64 MiB compressed and expanded. Select a trusted archive and verify its expected digest independently: hashes establish integrity and cross-record consistency, not the identity or honesty of an arbitrary producer. This import route neither launches nor qualifies a new integrated campaign.