vibe-sketcher and vibe-viewer with the queue

Audience: you prepare structures in vibe-sketcher, compute them with vibe-qc (or ORCA), and look at the results in vibe-view. vq is the part in the middle that runs the calculations and keeps track of them.

vibe-sketcher           vq                      vibe-qc / ORCA          vibe-viewer
draw, embed,   -->    submit, queue,   -->    compute on a     -->    fetch, open,
write inputs          track, fetch            daemon host or          watch live,
                                              cluster                 capture figures

Each product is installed on its own and works without the others. The queue integration is an optional extra in vibe-sketcher and vibe-view. Their own manuals are the reference: vibe-sketcher and vibe-viewer.

Install the integration

vq is not on a package index, so install it into the other product’s environment from a vq checkout first, then add the queue extra:

git clone https://github.com/vibyverse/vibe-scheduler.git ~/vibe-queue

# in the vibe-view checkout
.venv/bin/python -m pip install ~/vibe-queue
.venv/bin/python -m pip install -e '.[queue]'

# in the vibe-sketch checkout
.venv/bin/python -m pip install ~/vibe-queue
.venv/bin/python -m pip install -e '.[queue]'

Both talk to the vq daemon on the same machine, through vq’s Python API, so that machine needs a running daemon (vq daemon install; see installing vq) and a registered vibe-qc program, for example vibeqc-dev (adding programs). Register orca too if you want ORCA inputs to run. Check with:

vq daemon status
vq programs localhost

From vibe-sketcher: submit what you drew

vibe-sketcher writes the inputs and submits them as one group, recording each run in the document:

vibe-sketcher convert CCO --from smiles -o ethanol.vsk
vibe-sketcher submit ethanol.vsk --all --program vibeqc --task sp --method B3LYP --basis def2-SVP
vibe-sketcher runs ethanol.vsk              # each run's state and where its result is
vibe-sketcher cancel-group ethanol.vsk g1   # cancel a group that has not finished

A vibe-qc job goes to vq as a QVF job container, so the result is written into a file that still holds the sketch. Every submission carries the vibe-sketch tag, so you can also follow it with vq directly:

vq queue localhost --tag vibe-sketch
vq status localhost <jobid>

For staged work, such as an optimization followed by frequencies for every species of a reaction scheme, vibe-sketcher compiles a recipe into a vq campaign and prints the command that runs it:

vibe-sketcher campaign-compile scheme.vsk recipe1 --out campaign-dir --program vibeqc-dev
# ...prints the `vq campaign run ...` command for this campaign; run it as printed
vibe-sketcher campaign-status scheme.vsk recipe1 recipe1-c1

vq campaign run can be stopped and started again at any point; vibe-sketcher campaign-render then turns the verified stages into aligned QVF files and, with vibe-viewer installed, images.

In vibe-viewer: watch, open and submit

vibe-viewer open and vibe-viewer desktop have a vq Job Manager panel. It lists the local queue’s jobs by state, shows a job’s log tail, and opens a completed job’s QVF archives after fetching it. Watch live opens a running job’s checkpoint and reloads it as the calculation progresses.

From the viewer you can also submit the structure on screen: set the method, basis, charge and multiplicity, then Submit to vq cluster. With Submit as QVF container on, the payload is a pending QVF container that the queue runs in place. The viewer picks the vibe-qc program registered with vq. Set VIBEVIEW_VQ_PROGRAM to choose one when several are registered.

From the command line:

vibe-viewer from-vq <jobid>                  # fetch the job and open its .qvf files
vibe-viewer from-vq <jobid1> <jobid2> -o results/
vibe-viewer vq-features                      # which visualizations need what from vibe-qc

from-vq calls vq fetch, so it reaches whatever host your vq config points at.

vibe-viewer as a queue job: figures without a screen

vibe-viewer can render images headlessly, which makes it a program like any other. Register it on the host that renders, with a health check that proves capture works:

[programs.vibeview-dev]
kind = "venv"
python = "/home/USER/vibe-view/.venv/bin/python"
git_dir = "/home/USER/vibe-view"
branch = "main"
import_check = "vibeview"
healthcheck_command = "xvfb-run -a vibe-view capture-selftest"
description = "vibe-view headless capture"

Then submit a capture job next to the result it renders:

vq submit workstation --program vibeview-dev -d ./results/<jobid> -- \
    sh -c 'xvfb-run -a "$VQ_PROGRAM_BIN/vibe-view" capture water.qvf -o water.png'
vq fetch workstation <capture-jobid> --name water.png -o figures/

vq programs workstation should report vibeview-dev as OK first. In a campaign, the same command is a render node that runs only after the calculation’s results have been verified.