vibesketch.queue

Running calculations through vibe-queue (roadmap WP 2.5).

vibe-queue is optional (the queue extra, installed from a vibe-queue checkout). Its Python API is imported lazily, as vibe-view does: vq.submit.submit_local to submit, vq.status.show_status_json to follow a run, vq.kill.kill_job to cancel, vq.config.load_config for the programs registered with the queue, and vq.daemon_control.is_daemon_serving to tell whether anything will run.

What is submitted is what the input writers write:

  • ORCA: the input in a directory of its own, run as [<orca binary>, <input>] with the binary vibe-queue knows as the program orca (an absolute path; vibe-queue runs no shell), the input’s %pal processes as CPUs, and memory for %maxcore per process with ORCA’s recommended quarter of headroom.

  • vibe-qc: a QVF job container (vibesketch.document.qvf.job_container: the structure, the job.spec, the document and provenance.run_status: "pending"), submitted through vibe-queue’s single-QVF route, which runs vibeqc run from the venv program registered for vibe-qc and needs that program’s name and a pin of its runtime (vq.submit._program_runtime_pin_for_submit, the call vibe-view #86 settled). The runner updates the container in place, so the result keeps its sketch. When no container can be built or pinned (no qvf-writer, no registered vibe-qc program with a git identity, an older vibe-queue), the run script goes instead, run by the Python of the program vibe-queue knows as vibeqc or by this interpreter when vibe-qc imports here, and Submission.fallbacks says why.

Each submission is recorded on the document as a job with its runs (the queue’s working directory and, for a container, its file name), so a saved document knows its calculations and where their results are. The runs one call starts form a group (g1, g2, …): a reaction’s or a whole scheme’s species under one specification, each distinct species once, so the group is followed and cancelled as one (roadmap WP 4.1).

Module Attributes

PROGRAMS

Programs whose inputs vibe-queue can run, by writer name.

TERMINAL

States after which a run changes no more (vq.spec.TERMINAL_STATES).

TAG

The tag every vibe-sketch submission carries.

CONTAINER_TAG

The tag a QVF job container carries besides, as vibe-view's do.

Functions

cancel(run_id)

Cancel a run; raises ValueError for a finished one, KeyError for none.

cancel_group(document, group)

Cancel the runs of group that have not finished; the ids cancelled.

group_states(document)

The document's run groups with their progress, newest first.

queue_status()

Whether vibe-queue is installed and serving, and which programs it can run.

reaction_species(document[, reactions])

The distinct species of reactions (all of them when None), in document order.

run_states(document)

Every run of the document's jobs with its state in vibe-queue, newest first.

submit(document, *, program, spec[, ...])

Write each species' input and submit it to vibe-queue, as one group.

Classes

Submission(document[, submitted, refused, ...])

What submit() did.

Exceptions

QueueUnavailable

vibe-queue is not installed, or cannot run this program.
exception vibesketch.queue.QueueUnavailable[source]

Bases: RuntimeError

vibe-queue is not installed, or cannot run this program.

class vibesketch.queue.Submission(document, submitted=<factory>, refused=<factory>, fallbacks=<factory>, group=None)[source]

Bases: object

What submit() did.

Parameters:
document: Document
submitted: list[dict[str, str]]

{"job", "species", "run", "input"} per run started; input is container (a QVF job container), script or directory (ORCA).

refused: dict[str, list[str]]

Per species id, why it was not submitted.

fallbacks: dict[str, str]

Per species id, why a run script went to vibe-queue instead of a QVF job container.

group: str | None = None

The group the started runs form; None when nothing was submitted.

vibesketch.queue.TERMINAL = frozenset({'aborted_by_queue', 'completed', 'failed', 'interrupted', 'killed', 'oom_killed', 'starved', 'time_exceeded'})

States after which a run changes no more (vq.spec.TERMINAL_STATES).

vibesketch.queue.cancel(run_id)[source]

Cancel a run; raises ValueError for a finished one, KeyError for none.

Parameters:

run_id (str)

Return type:

str

vibesketch.queue.cancel_group(document, group)[source]

Cancel the runs of group that have not finished; the ids cancelled.

Finished runs are left alone. Raises KeyError when the document has no run in that group.

Parameters:
Return type:

list[str]

vibesketch.queue.group_states(document)[source]

The document’s run groups with their progress, newest first.

Each row names the group, its runs and species, the program, task and method they share, a tally of the runs’ states, and whether the group is finished.

Parameters:

document (Document)

Return type:

list[dict[str, Any]]

vibesketch.queue.queue_status()[source]

Whether vibe-queue is installed and serving, and which programs it can run.

Return type:

dict[str, Any]

vibesketch.queue.reaction_species(document, reactions=None)[source]

The distinct species of reactions (all of them when None), in document order.

Reactants, reagents and products all count: a scheme is computed when every species it draws is. A species in several steps appears once. Raises the writers’ UnknownReference for a reaction the document lacks.

Parameters:
Return type:

list[str]

vibesketch.queue.run_states(document)[source]

Every run of the document’s jobs with its state in vibe-queue, newest first.

Parameters:

document (Document)

Return type:

list[dict[str, Any]]

vibesketch.queue.submit(document, *, program, spec, species=None, reactions=None, container=True)[source]

Write each species’ input and submit it to vibe-queue, as one group.

species names species; reactions names reactions whose species (reactants, reagents and products, each once) join them; with neither, every species goes. The runs started form one group, named in Submission.group and on each run.

A vibe-qc job goes as a QVF job container, which keeps the sketch with its result; when none can be built or pinned, or with container false, the run script goes instead, and Submission.fallbacks says why. Species the writer refuses, or that have no 3D structure, are listed in Submission.refused. Raises QueueUnavailable when vibe-queue is missing or cannot run program either way, and the writers’ UnknownWriter/UnknownReference (a reaction, a species) as write_inputs() does.

Parameters:
Return type:

Submission