QuantUI CLI¶
QuantUI ships a small command-line toolkit for inspecting state and
generating reports from outside the notebook. After installing the
package (pip install -e . or pip install quantui), the quantui
command is on your PATH.
The CLI is meant to complement the Voilà app. Most commands are
read-only diagnostics against ~/.quantui/ (or whatever
QUANTUI_LOG_DIR points at). The exceptions are quantui run app
and quantui setup, which start (or prepare) the student-facing
Voilà interface; quantui view, which opens the History + Analysis
viewer on a results folder; quantui submit, which sends calculations
to a SLURM cluster; and quantui install-launcher, which writes the
quantui-batch launcher for doing that from a login node.
Reach for the CLI when you want to:
- launch the app without remembering Voilà flags or notebook paths
- check what the app has been doing without opening a notebook
- confirm GPU offload is wired correctly before starting a long run
- generate a usage / GPU-speedup report you can share or pin to a tab
- script log inspection or analytics into a shell pipeline / cron job
Command reference¶
| Command | What it does |
|---|---|
quantui run app |
Start the Voilà student app |
quantui setup |
Write ~/.quantui/app.ipynb and a quantui-app shell shortcut |
quantui view |
Open the History + Analysis viewer on a results folder |
quantui log tail |
Print recent events from event_log.jsonl |
quantui gpu check |
Probe GPU-offload availability and explain failures |
quantui analytics build |
Build an HTML usage dashboard from perf_log.jsonl |
quantui submit |
Submit .xyz or request-JSON files as SLURM batch jobs |
quantui results |
Summarize a batch job folder's newest finished result |
quantui jobs |
List your batch jobs and where each one is |
quantui install-launcher |
Write the quantui-batch launcher for submitting from a login node |
quantui run app¶
Start the student-facing Voilà interface. On first use (or after
quantui setup), the CLI writes a thin launcher notebook to
~/.quantui/app.ipynb — the same three-line pattern as the repo's
notebooks/molecule_computations.ipynb, without requiring a git clone.
Requires the [app] extra:
Flags¶
| Flag | Default | Description |
|---|---|---|
--port PORT |
8867 |
TCP port (matches the native launchers/ scripts) |
--open |
off | Open http://localhost:PORT in the default browser after startup |
--force |
off | Regenerate ~/.quantui/app.ipynb before starting |
Examples¶
# Default — prints the URL, runs until Ctrl-C
quantui run app
# Open the browser automatically (WSL-aware)
quantui run app --open
# Custom port
quantui run app --port 8888
Notes¶
- Exit code
1when Voilà is not installed — installquantui[app]and ensurevoilais on yourPATH. - Exit code
1in Apptainer + JupyterLab sessions (NCShare and similar HPC portals) — usequantui setupand launch from JupyterLab instead; seequantui setup. - Override the config directory with
QUANTUI_HOME(useful in tests).
quantui setup¶
One-time (or idempotent) provisioning for users who want a persistent shell shortcut:
- Writes
~/.quantui/app.ipynb(same asquantui run appuses) - Writes
~/.local/bin/quantui-app(or$XDG_BIN_HOME/quantui-app)
Pass --force to overwrite an existing notebook or script.
NCShare and HPC JupyterLab¶
On cluster portals that launch QuantUI inside Apptainer + JupyterLab (NCShare is the primary example), the browser proxies only the Jupyter connection. A standalone Voilà server on port 8867 is not reachable.
When the CLI detects that environment (Apptainer + Jupyter server env
vars), quantui setup also writes ~/QuantUI.ipynb — visible in the
JupyterLab file browser — and prints NCShare-specific launch instructions
instead of the usual quantui run app guidance.
Launch QuantUI from JupyterLab:
- Open
~/QuantUI.ipynband click Render with Voilà (clean student view), or - Run the one-liner in any notebook:
quantui run app exits with code 1 in this context and explains the
above — do not use it for browser access on NCShare.
quantui view¶
Open the read-only History + Analysis viewer (the same viewer the
desktop installers ship; see Viewer) on a QuantUI results
folder. Requires the [app] extra.
quantui view # folder: $QUANTUI_RESULTS_DIR, else the last one opened, else ~
quantui view ~/quantui_results # a specific folder
quantui view --no-browser # print the URL only
| Flag | Default | Description |
|---|---|---|
FOLDER |
see above | Results folder to open (exit 1 if it is not a folder) |
--port PORT |
a free port | TCP port for Voilà |
--no-browser |
off | Do not open the browser automatically |
The server binds to 127.0.0.1 and uses a per-run token, so other
machines and other local web pages cannot start kernels on it. The full
URL (with the token) is printed at startup.
quantui log tail¶
Print the last N entries from the QuantUI event log
(~/.quantui/logs/event_log.jsonl). Each event is rendered on one
line as timestamp event_type message k=v k=v ..., so the output
is grep-friendly.
Flags¶
| Flag | Default | Description |
|---|---|---|
-n N |
20 |
Number of most-recent events to print |
Examples¶
# Last 20 events
quantui log tail
# Last 50 events
quantui log tail -n 50
# Find every GPU-related event
quantui log tail -n 500 | grep -i gpu
# Watch the most recent error
quantui log tail -n 200 | grep -i error | tail -5
Sample output¶
2026-05-25T13:55:22.421910+00:00 viz_route_decision task=molecule_preview pref=auto chosen=py3dmol reason=auto -> task primary (py3dmol)
2026-05-25T13:55:22.470028+00:00 startup QuantUI 0.3.0 started (viz backend pref=auto)
2026-05-25T14:08:14.102544+00:00 calc_done B3LYP/STO-3G on H2O elapsed_s=1.2 converged=True gpu_used=True gpu_name=NVIDIA GeForce RTX 4050 Laptop GPU
Notes¶
- The event log is pruned of entries older than 7 days periodically
(every 20 writes), so
tailreflects roughly the active week. - Output goes to stdout; the
(event log is empty)and(no event log at PATH)notices go to stderr so they don't pollute pipelines. - Exit code: always
0(even when no events exist — the absence of events is not an error).
quantui gpu check¶
Probe whether QuantUI's GPU offload path is functional in the current
environment. This is the canonical one-liner for verifying that
gpu4pyscf + cupy are installed correctly and that
is_gpu_available() will return True when the PySCF app path runs. Use
--engine pyfock to probe PyFock's independent CuPy path.
Flags¶
| Flag | Default | Description |
|---|---|---|
--engine {pyscf,pyfock} |
pyscf |
Which GPU path to probe: pyscf (gpu4pyscf + cupy) or pyfock (PyFock's CuPy path) |
Examples¶
# Is GPU offload working right now?
quantui gpu check
# Check the separate PyFock/CuPy path
quantui gpu check --engine pyfock
# Use in a shell condition
if quantui gpu check; then
echo "GPU mode"
else
echo "Falling back to CPU"
fi
# Diagnose a CI machine
QUANTUI_DISABLE_GPU=1 quantui gpu check # confirms env-var path
Sample output¶
When GPU is available:
GPU offload available: NVIDIA GeForce RTX 4050 Laptop GPU
note: NVIDIA GeForce RTX 4050 Laptop GPU looks like a consumer/workstation GPU, ...
... offload here may be SLOWER than your CPU. Benchmark before relying on it; ...
(exit code 0). The note: (on stderr) appears for any card without
strong double-precision throughput — most consumer and workstation GPUs.
With --engine pyfock the first line reads PyFock GPU available: <name>.
When GPU is unavailable, the command prints a reason (to stderr) so you know where to look next:
GPU offload not available
reason: gpu4pyscf is not installed — install the extra matching your driver's CUDA version, e.g. pip install 'quantui[gpu-cuda13x]' (see README → 'Optional: GPU acceleration')
Other reasons you may see: GPU offload is switched off in QuantUI
settings (System Settings tab → GPU offload → Use GPU when available), gpu4pyscf is installed
but failed to import: <error> (usually missing CUDA libraries), and
gpu4pyscf import raised <ExceptionType>: <error>.
(all return exit code 1)
Notes¶
- Detection is cached for the lifetime of QuantUI's runtime (so the
Voilà app doesn't re-probe on every result-card render); the CLI
clears that cache before probing so each invocation reflects the
current state — useful right after a
pip install. - Returns exit
1rather than raising, so the command is safe to use inif ...; then ... fiand&& ...chains.
quantui analytics build¶
Build a self-contained HTML analytics dashboard from
~/.quantui/logs/perf_log.jsonl and write it to a file you can open
in any browser.
The dashboard contains:
- Overview cards — total runs, total compute time, GPU vs CPU run counts, unique molecules / methods / basis sets used.
- GPU vs CPU speedup table — for every
(method, basis, formula)tuple that has runs on both devices, the median CPU time, median GPU time, and the speedup factor. Sorted best-speedup first. - Prediction accuracy — how close the runtime estimator's predictions were to the measured times (median error, share within 25%, and a predicted-vs-actual scatter).
- Method usage — bar chart of run counts per method.
- Calc-type distribution — bar chart of run counts per calculation type.
- Recent timeline — scatter of
elapsed_sover time, coloured by compute device (CPU grey, GPU green, Unknown light grey for pre-2026-05-25 records that don't yet have device info).
Plotly's JavaScript is inlined into the HTML, so the file works offline and can be emailed, attached to a writeup, or pinned to a browser tab.
Flags¶
| Flag | Default | Description |
|---|---|---|
-o PATH, --output PATH |
~/.quantui/dashboard.html |
Output HTML path |
--open |
off | After writing, open the dashboard in the default browser (WSL-aware — uses wslview / explorer.exe on WSL) |
Examples¶
# Build the dashboard at the default location
quantui analytics build
# Build and immediately open it in the browser
quantui analytics build --open
# Write somewhere shareable
quantui analytics build -o ~/Desktop/quantui-report.html
# Build into a shared folder + open
quantui analytics build -o ~/projects/lab-share/quantui-report.html --open
Sample output¶
With --open, the CLI picks the right opener for your environment:
- WSL: tries
wslviewfirst (bundled with thewslupackage), then falls back toexplorer.exe. Both delegate to your Windows default browser via WSL interop — no Linux-side browser install needed. If neither is available,sudo apt install wslufixes it in one step. - Linux native: stdlib
webbrowser.open(which usesxdg-open). - macOS / Windows native: stdlib
webbrowser.open.
If no opener succeeds — e.g. a headless container with no display — you'll see:
Wrote /home/youruser/.quantui/dashboard.html
(could not auto-open browser — open /home/youruser/.quantui/dashboard.html manually)
The exit code stays 0 either way — the dashboard was written
successfully; only the auto-open is best-effort.
Notes¶
- Empty perf log: if
perf_log.jsonldoesn't exist yet, the command prints(perf log is empty — run a calculation first)to stderr and exits0. No file is written. - Old records with no GPU info: records written before session 55
(2026-05-25) don't have
gpu_used. The dashboard counts those in a separate "Unknown" device bucket rather than assuming CPU — that keeps the GPU-vs-CPU speedup table honest. - Speedup table empty? It only shows tuples that have runs on both devices. After enabling GPU, re-run any prior CPU calc on the GPU to populate at least one row.
quantui submit¶
Submit calculations to the SLURM batch backend without the app. Each input is
an .xyz file (with --calc) or a CalculationRequest JSON file; flags given
on the command line override a JSON file's values.
# A frequency job from an XYZ file
quantui submit water.xyz --calc frequency --method B3LYP --basis def2-SVP
# Check the resource estimate without submitting
quantui submit water.xyz --calc tddft --solvent Water --dry-run
# Start only after another job succeeds
quantui submit water.xyz --calc frequency --depends-on <request id>
# Write the job folder (request.json + submit.slurm) but do not call sbatch
quantui submit water.xyz --calc geometry_opt --prepare-only
Useful flags: --charge, --mult, --solvent, --preopt,
--option KEY=VALUE (repeatable), --cores, --memory-gb, --walltime,
--email, --mail-events, --job-name, --partition, --no-apptainer,
--apptainer-image. quantui submit --help lists them all.
A method QuantUI does not support (e.g. HF: use RHF or UHF), an unknown
solvent, or a solvent on a calc type the batch worker runs gas-phase only
(NMR, PES scan) is refused before anything is queued; for .xyz inputs, so is
an impossible charge/multiplicity.
A real submission needs sbatch on PATH and QUANTUI_ENABLE_SLURM set
(see Environment variables); otherwise the command
exits 1 with the reason. --dry-run and --prepare-only skip that check
and cannot be combined (exit 2).
A real submission counts toward the same limits as the app: at most
QUANTUI_MAX_CONCURRENT_JOBS (default 2) QuantUI jobs queued or running at
once, and QUANTUI_SLURM_SUBMIT_COOLDOWN_S (default 30) seconds between
submits. With several input files the command waits out the cooldown between
them, but an input that would exceed the job limit is rejected (exit 1) and
the rest still run. For a larger batch, raise QUANTUI_MAX_CONCURRENT_JOBS
for that command (e.g. QUANTUI_MAX_CONCURRENT_JOBS=30 quantui submit
lab2/*.xyz --calc frequency), or use --prepare-only and run sbatch on the
printed scripts yourself.
quantui results¶
Print a plain-text summary of a batch job folder's newest finished attempt:
convergence, energy, gap, dipole, imaginary modes and strongest IR bands,
excited states, or NMR shifts. It is the same summary as quantui-batch
results, for use inside the image.
The argument can also be one attempt folder. Exit code 1 means no attempt has
finished yet (or its result.json cannot be read); 2 means the argument is
not a folder.
quantui jobs¶
List your batch jobs, newest first, with where each one is: waiting, running (with the worker's progress), done or failed.
quantui jobs # the newest 10
quantui jobs -n 25 # the newest 25
quantui jobs --running # only jobs not finished yet
quantui jobs --all
With squeue on PATH (an allocation on the cluster) it first refreshes the job
records from the queue. Without it (an OnDemand terminal) the state is read
from each job folder; a running job whose progress has not changed for 30
minutes is flagged as possibly stopped.
quantui install-launcher¶
Write quantui-batch, a standard-library Python launcher for submitting
QuantUI jobs from a cluster login node over SSH. The launcher never starts the
image or imports QuantUI on the login node; the calculation runs in the image
on a compute node. Run this once per image, inside it, from an allocation:
| Argument / flag | Default | Description |
|---|---|---|
DIR |
~/bin |
Directory to write quantui-batch into |
--image PATH |
the image this command runs in | Apptainer image the launcher submits to |
--force |
off | Overwrite an existing quantui-batch (without it, exit 1) |
Students then use quantui-batch submit, status, results, log,
rerun --more-memory, cancel and more. Full guide (presets, --from
chaining, --queue-rest, check):
apptainer/slurm/README.md.
Environment variables¶
| Variable | Effect |
|---|---|
QUANTUI_HOME |
Override ~/.quantui/ for the generated launcher notebook (app.ipynb) and setup output. |
XDG_BIN_HOME |
Override ~/.local/bin as the destination for the quantui-app shell shortcut. |
QUANTUI_LOG_DIR |
Override the default ~/.quantui/logs/ location. The dashboard's default output (~/.quantui/dashboard.html) follows: it lives one level up from the active QUANTUI_LOG_DIR. |
QUANTUI_DISABLE_GPU |
Force CPU mode even when gpu4pyscf is installed. quantui gpu check reports this as the reason. Accepted truthy values: 1, true, True. |
QUANTUI_ENABLE_SLURM |
Opt in to SLURM batch (cluster) on the System Settings → Execution backend dropdown. Requires sbatch on PATH. Off by default so student deployments stay in-kernel until an operator enables cluster mode in the Apptainer image, JupyterHub spawner, or shell. Accepted truthy values: 1, true, yes, on. |
QUANTUI_MAX_CONCURRENT_JOBS |
Most QuantUI SLURM jobs queued or running at once (app and quantui submit; default 2). |
QUANTUI_SLURM_SUBMIT_COOLDOWN_S |
Minimum seconds between SLURM submits (default 30; 0 disables). quantui submit waits it out between input files. |
QUANTUI_FREQ_PARALLEL |
Opt in to parallel CPU workers for the IR/Raman finite-difference displacement loops in frequency calculations (6N displaced SCFs). Same effect as the Parallelize IR/Raman displacements (CPU) checkbox on the System Settings tab; when this env var is set it overrides the saved setting. Reference SCF and Hessian still use gpu4pyscf when available. Requires ≥4 cores and ≥2 atoms. Off by default. Accepted truthy values: 1, true, yes, on. |
Common workflows¶
Verify GPU is wired before a long run¶
If gpu check exits non-zero, the app launch is skipped and the
reason was printed to stderr.
Launch the app (pip install, no git clone)¶
Quick "what happened in my last session?"¶
After a benchmarking run, open the report¶
The dashboard opens; the speedup table summarises everything across runs without you needing to remember which calc ran where.
Plumbing into cron / CI¶
# Daily snapshot, no auto-open (headless)
quantui analytics build -o /var/reports/quantui-$(date +%F).html
Adding a new subcommand¶
Each verb is one _cmd_<verb>(args: argparse.Namespace) -> int in
quantui/cli.py plus a registration in
_build_parser. The pattern is short by design — gpu check,
log tail, and analytics build all fit in well under 50 lines of
production code apiece. See the module docstring for the contract.
Tests live in tests/test_cli.py — every
subcommand should cover its happy path, its empty/missing-data path,
and any flag-specific behavior (e.g. --open was tested against both
a successful webbrowser.open and a failed one).