Skip to content

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.

quantui --help

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:

pip install 'quantui[app]'
quantui run app

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 1 when Voilà is not installed — install quantui[app] and ensure voila is on your PATH.
  • Exit code 1 in Apptainer + JupyterLab sessions (NCShare and similar HPC portals) — use quantui setup and launch from JupyterLab instead; see quantui 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:

  1. Writes ~/.quantui/app.ipynb (same as quantui run app uses)
  2. Writes ~/.local/bin/quantui-app (or $XDG_BIN_HOME/quantui-app)
quantui setup
quantui-app          # after ~/.local/bin is on PATH

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:

  1. Open ~/QuantUI.ipynb and click Render with Voilà (clean student view), or
  2. Run the one-liner in any notebook:
    from quantui.app import QuantUIApp
    QuantUIApp().display()
    

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 tail reflects 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')
GPU offload not available
  reason: QUANTUI_DISABLE_GPU is set in the environment
GPU offload not available
  reason: cupy reports 0 CUDA devices
GPU offload not available
  reason: cupy device probe failed: <error>

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 1 rather than raising, so the command is safe to use in if ...; then ... fi and && ... 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_s over 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

Wrote /home/youruser/.quantui/dashboard.html

With --open, the CLI picks the right opener for your environment:

  • WSL: tries wslview first (bundled with the wslu package), then falls back to explorer.exe. Both delegate to your Windows default browser via WSL interop — no Linux-side browser install needed. If neither is available, sudo apt install wslu fixes it in one step.
  • Linux native: stdlib webbrowser.open (which uses xdg-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.jsonl doesn't exist yet, the command prints (perf log is empty — run a calculation first) to stderr and exits 0. 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.

quantui results ~/.quantui/staging/H2O_freq_B3LYP_def2-SVP

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:

apptainer exec /path/to/quantui.sif quantui install-launcher /shared/bin
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

quantui gpu check && quantui run app

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)

pip install 'quantui[app]'
quantui run app
# optional one-time shell shortcut:
quantui setup

Quick "what happened in my last session?"

quantui log tail -n 100 | grep -E "calc_done|calc_error|startup"

After a benchmarking run, open the report

quantui analytics build --open

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).