Release 0.10.0: version bump, README and docs

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-03
+
 ### Added
 
 - **Upload structure files** — new **Upload File** tab (Calculate → Molecule
@@ -104,6 +106,9 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
   (`git describe`) in the image's `QuantUICommit` label and
   `/opt/build-info/quantui-commit.txt`; its `--version` flag is gone — check
   out a release tag to build that release.
+- **Finished batch attempts reach History when the app starts**, even where
+  SLURM is unavailable (e.g. an OnDemand session), so jobs submitted from a
+  terminal show up without opening the Cluster Jobs tab.
 
 ### Fixed
 
@@ -161,12 +166,6 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
   Ni, Mo and most other metals, so a metal counted as 0 electrons and the
   memory estimate came out low. It now uses the full table.
 
-### Changed
-
-- **Finished batch attempts reach History when the app starts**, even where
-  SLURM is unavailable (e.g. an OnDemand session), so jobs submitted from a
-  terminal show up without opening the Cluster Jobs tab.
-
 ## [0.9.0] - 2026-09-26
 
 ### Added
@@ -1094,7 +1093,8 @@ Initial public scaffolding of the QuantUI package: `quantui` package with
 `calculator.py`, basic notebook launcher, Apptainer container definition,
 MIT license, and project metadata.
 
-[Unreleased]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.8.2...v0.9.0
 [0.8.2]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.8.0...v0.8.1

README.md

@@ -61,7 +61,11 @@ Real output from QuantUI, straight from the app:
   ready-to-run coordination complexes**, searchable by name/formula), or run a
   structure search by name, SMILES, InChI, PubChem CID, InChIKey, or CAS number
   (PubChem → NCI CACTUS → offline bundled-library fallback; SMILES/InChI resolve
-  locally with no network)
+  locally with no network), or upload a structure file (XYZ, MOL/SDF, MOL2,
+  PDB, CIF, Gaussian input or output)
+- **Structure editing** — set a bond length, angle or dihedral to a value,
+  delete atoms, add a hydrogen, change an element, undo; pick atoms by
+  clicking the viewer. Freeze atoms for a constrained geometry optimization
 - **Offline-first** — runs with no internet: the bundled molecule library and
   the 3D viewer's JavaScript (3Dmol.js) are vendored, so structure lookup and
   every 3D view work in an air-gapped classroom. (Network is used only for the
@@ -71,7 +75,9 @@ Real output from QuantUI, straight from the app:
   router picks the right renderer per task, and a Status-tab toggle persists
   your default-backend preference between sessions
 - **In-session calculations** — RHF, UHF, 9 DFT functionals, MP2, CCSD,
-  CCSD(T), NMR shielding, TD-DFT UV-Vis, and 1D PES scans via PySCF, running
+  CCSD(T), NMR shielding, TD-DFT UV-Vis, 1D PES scans, Marcus reorganization
+  energies and **transition-state searches** (Sella, with an automatic
+  frequency check that says whether it found a TS) via PySCF, running
   in your Python kernel. Optional PyFock 0.1.x adds native-Windows PBE
   single points and geometry optimizations for neutral, closed-shell molecules
   with def2-SVP/def2-TZVP, including orbital and population analysis;
@@ -81,13 +87,18 @@ Real output from QuantUI, straight from the app:
   optimizations, frequencies (PCM Hessian + IR; Raman stays gas-phase) and
   TD-DFT (non-equilibrium excitations). NMR and PES scans are gas-phase only
 - **Rich results** — total energy, HOMO-LUMO gap, Mulliken charges, dipole
-  moment, thermochemistry (H, S, G at 298 K), IR spectrum chart (stick and
-  Lorentzian-broadened), ¹H/¹³C NMR chemical shifts, orbital energy-level
-  diagram, HOMO/LUMO isosurface (cube-file rendering with toggle for HOMO-1,
-  HOMO, LUMO, LUMO+1), and a side-by-side comparison table for multiple
-  calculations
+  moment, point group, ⟨S²⟩ with a spin-contamination flag for open-shell
+  results, thermochemistry (U, H, S, G, Cv, Cp at any temperature and
+  pressure), IR spectrum chart (stick and Lorentzian-broadened), ¹H/¹³C NMR
+  chemical shifts, an orbital energy-level diagram with symmetry labels
+  (1a₁, 1b₂ …), and a side-by-side comparison table for multiple calculations
+- **Surfaces** — any molecular orbital (α and β for unrestricted results), an
+  **orbital gallery** of the orbitals around the HOMO–LUMO gap in small linked
+  viewers, the electron density, the spin density, and the electrostatic
+  potential mapped on the density surface
 - **Geometry optimization** — BFGS optimizer with step-by-step trajectory
   animation; vibrational frequency analysis with animated normal modes,
+  displacement arrows, an amplitude slider and a table of every mode,
   user-tunable playback FPS, and a per-result-directory disk cache so mode
   switches on repeat visits and history replay are instant
 - **Inorganic / coordination complexes** — first-class support for
@@ -106,7 +117,9 @@ Real output from QuantUI, straight from the app:
   timestamped directory; a built-in browser lets you reload past results
   after a kernel restart; the full `pyscf.log` is shown inline
 - **Structure exports** — download XYZ, MOL/SDF, or PDB files alongside the
-  saved results; script export for a standalone `.py` file
+  saved results; script export for a standalone `.py` file. Every export also
+  downloads straight to your computer, including from a remote
+  Voilà/OnDemand session
 - **Plot export** — save IR, UV-Vis, PES, and orbital diagrams as standalone
   HTML
 - **Optional GPU acceleration** — when [gpu4pyscf](https://github.com/pyscf/gpu4pyscf)
@@ -117,6 +130,11 @@ Real output from QuantUI, straight from the app:
   Geometry-optimization SCF and gradient steps offload the same way. For a
   frequency calculation, the displaced IR SCFs offload, but the reference SCF
   and the analytical Hessian still run on the CPU.
+- **Cluster batch jobs** — `quantui-batch` submits QuantUI calculations to
+  SLURM from a login node over SSH, without starting the image there (presets,
+  chaining from another job's optimized geometry, reruns with more memory or
+  time, results summaries); `quantui submit` does the same wherever QuantUI is
+  installed. See [apptainer/slurm/README.md](https://github.com/The-Schultz-Lab/QuantUI/blob/main/apptainer/slurm/README.md)
 - **Timing calibration** — one-click benchmark suite populates the time
   estimator with real machine data so predictions are accurate from the first run
 - **Voilà app mode** — serve the notebook as a polished widget-only UI (no
@@ -266,6 +284,19 @@ reports the reason. GPU single points use PyFock's GPU SCF/integral/XC path;
 GPU geometry optimizations use numerical finite-difference forces because the
 installed PyFock release's analytical gradient implementation is CPU-only.
 
+### Optional: transition-state searches (Sella)
+
+The **Transition State** calc type uses [Sella](https://github.com/zadorlab/sella),
+installed as an optional extra:
+
+```bash
+pip install "quantui[ts]"
+```
+
+Sella pulls in jax/jaxlib (about 380 MB) and is LGPL-3.0, used as a
+separately installed library. Without it the calc type stays in the menu and
+says how to install it. Local runs only for now (not SLURM batch jobs).
+
 ### Optional: GFN-FF metal pre-optimization (xtb)
 
 The classical (MMFF/UFF) pre-optimizer relies on RDKit's organic valence
@@ -414,8 +445,13 @@ dashboard. After installation:
 quantui log tail -n 50        # last 50 events from event_log.jsonl
 quantui gpu check             # is GPU offload available right now?
 quantui analytics build --open  # build dashboard.html + open in browser
+quantui submit water.xyz --calc frequency --method B3LYP --basis def2-SVP  # SLURM batch job
 ```
 
+On a cluster, `apptainer exec IMAGE quantui install-launcher DIR` writes the
+`quantui-batch` launcher for submitting from a login node — see
+[apptainer/slurm/README.md](https://github.com/The-Schultz-Lab/QuantUI/blob/main/apptainer/slurm/README.md).
+
 Full reference with all flags and examples: [docs/CLI.md](https://github.com/The-Schultz-Lab/QuantUI/blob/main/docs/CLI.md).
 
 ---
@@ -478,11 +514,13 @@ Five step-by-step notebooks in [`notebooks/tutorials/`](https://github.com/The-S
 | Type | Output |
 | --- | --- |
 | Single Point | Energy, HOMO-LUMO gap, Mulliken charges, dipole moment |
-| Geometry Opt | Optimised structure, trajectory animation |
-| Frequency | Vibrational frequencies, ZPVE, IR intensities, thermochemistry (H/S/G at 298 K), animated normal modes, IR spectrum chart (stick / Lorentzian broadened) |
+| Geometry Opt | Optimised structure, trajectory animation; optional frozen atoms |
+| Transition State | Saddle point near the input geometry (Sella, optional `[ts]` extra), then a frequency check: transition state, minimum, or higher-order saddle point; animated imaginary mode |
+| Frequency | Vibrational frequencies, ZPVE, IR intensities, thermochemistry at any temperature and pressure, animated normal modes, IR spectrum chart (stick / Lorentzian broadened) |
 | UV-Vis (TD-DFT) | Excitation energies, oscillator strengths, UV-Vis spectrum plot |
 | NMR Shielding | ¹H and ¹³C chemical shifts relative to TMS via GIAO; tabulated by element |
 | PES Scan | 1D potential energy surface along a bond, angle, or dihedral; energy profile chart; geometry animation at each scan point |
+| Reorganization Energy | Marcus four-point internal reorganization energy λ = λ₁ + λ₂ for hole (cation) and/or electron (anion) transfer |
 
 ### Basis sets
 
@@ -531,6 +569,8 @@ quantui/                  Main package
   freq_calc.py            Vibrational frequency + thermochemistry
   ir_plot.py              IR spectrum chart (stick / Lorentzian broadened)
   tddft_calc.py           TD-DFT UV-Vis excited-state calculations
+  ts_search.py            Transition-state search (Sella) + frequency check
+  reorganization_energy.py  Marcus four-point reorganization energy
   nmr_calc.py             NMR shielding + ¹H/¹³C chemical shifts
   pes_scan.py             1D potential energy surface scan
   optimizer.py            QM geometry optimization with trajectory
@@ -551,12 +591,14 @@ quantui/                  Main package
   benchmarks.py           Timing calibration benchmark suite
   config.py               Methods, basis sets, solvent/NMR options, presets
   ase_bridge.py           ASE structure I/O
+  batch_launcher.py       Renders the quantui-batch login-node launcher
+  backends/               SLURM batch backend, worker and job registry
   preopt.py               RDKit MMFF94/UFF force-field pre-optimization
   data/                   Bundled library (SQLite + manifests) + vendored 3Dmol.js
 notebooks/
   molecule_computations.ipynb   Main user-facing interface (3-cell launcher)
   tutorials/                    Step-by-step guided notebooks (01–05)
-tests/                    pytest test suite (~1500 tests; run in parallel via pytest-xdist)
+tests/                    pytest test suite (~3,700 tests; run in parallel via pytest-xdist)
 apptainer/                Container definition for reproducible deployment
 local-setup/              Conda environment definition
 pyproject.toml            Package metadata and tool config

docs/CLI.md

@@ -11,9 +11,10 @@ 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 exception is **`quantui run app`**
+`QUANTUI_LOG_DIR` points at). The exceptions are **`quantui run app`**
 and **`quantui setup`**, which start (or prepare) the student-facing
-Voilà interface.
+Voilà interface, and **`quantui submit`** / **`quantui install-launcher`**,
+which send calculations to a SLURM cluster.
 
 Reach for the CLI when you want to:
 
@@ -34,6 +35,8 @@ Reach for the CLI when you want to:
 | [`quantui log tail`](#quantui-log-tail) | Print recent events from `event_log.jsonl` |
 | [`quantui gpu check`](#quantui-gpu-check) | Probe GPU-offload availability and explain failures |
 | [`quantui analytics build`](#quantui-analytics-build) | Build an HTML usage dashboard from `perf_log.jsonl` |
+| [`quantui submit`](#quantui-submit) | Submit `.xyz` or request-JSON files as SLURM batch jobs |
+| [`quantui install-launcher`](#quantui-install-launcher) | Write the `quantui-batch` launcher for submitting from a login node |
 
 ---
 
@@ -340,6 +343,53 @@ successfully; only the auto-open is best-effort.
 
 ---
 
+## `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.
+
+```bash
+# 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`, `--job-name`, `--partition`. `quantui submit --help` lists them all.
+An impossible charge/multiplicity, 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.
+
+---
+
+## `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:
+
+```bash
+apptainer exec /path/to/quantui.sif quantui install-launcher /shared/bin
+```
+
+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](https://github.com/The-Schultz-Lab/QuantUI/blob/main/apptainer/slurm/README.md#submitting-from-a-terminal-quantui-batch).
+
+---
+
 ## Environment variables
 
 | Variable | Effect |

docs/features.md

@@ -16,6 +16,9 @@ local Python kernel.
     a structure search by name, SMILES, InChI, CID, or CAS —
     PubChem &rarr; NCI CACTUS &rarr; an <strong>offline</strong>
     bundled-library fallback, so the search still works with no network.
+    Or upload a file (XYZ, MOL/SDF, MOL2, PDB, CIF, Gaussian input/output)
+    and <strong>edit the structure</strong>: set bond lengths, angles and
+    dihedrals, delete atoms, add hydrogens, change elements, freeze atoms.
   </p>
 </div>
 
@@ -37,10 +40,12 @@ local Python kernel.
   <div class="feature-card__title">Calculations</div>
   <p class="feature-card__body">
     RHF, UHF, nine DFT functionals, MP2, CCSD, and CCSD(T) &mdash;
-    with six calculation types: single point, geometry optimization,
-    frequencies/thermochemistry, TD-DFT UV-Vis, NMR shielding,
-    and 1D PES scans. PCM implicit solvation for single points,
-    optimizations, frequencies and TD-DFT.
+    with eight calculation types: single point, geometry optimization,
+    <strong>transition-state search</strong> (Sella, with an automatic
+    frequency check), frequencies/thermochemistry, TD-DFT UV-Vis, NMR
+    shielding, 1D PES scans and Marcus reorganization energies. PCM
+    implicit solvation for single points, optimizations, frequencies
+    and TD-DFT.
   </p>
 </div>
 
@@ -49,9 +54,12 @@ local Python kernel.
   <div class="feature-card__title">Spectra &amp; Analysis</div>
   <p class="feature-card__body">
     IR spectrum (stick + Lorentzian-broadened), UV-Vis plot,
-    orbital energy-level diagram with HOMO/LUMO isosurfaces,
-    and <sup>1</sup>H/<sup>13</sup>C NMR chemical shifts vs TMS.
-    Side-by-side comparison table for multiple calculations.
+    <sup>1</sup>H/<sup>13</sup>C NMR shifts vs TMS, point groups and an
+    orbital diagram with symmetry labels. Any orbital (&alpha;/&beta;), an
+    <strong>orbital gallery</strong> in linked viewers, density, spin
+    density and ESP-mapped surfaces. Vibration viewer with displacement
+    arrows; thermochemistry at any T and P; &lang;S&sup2;&rang; for
+    open-shell results; side-by-side comparison tables.
   </p>
 </div>
 
@@ -64,7 +72,9 @@ local Python kernel.
     orbital data (Molden), trajectories (multi-frame XYZ, ASE
     <code class="inline-code">.traj</code>), cube files, spectra
     as HTML, full result bundles as <code class="inline-code">.zip</code>,
-    or any run as a standalone <code class="inline-code">.py</code> script.
+    or any run as a standalone <code class="inline-code">.py</code> script
+    &mdash; each one also downloads to your computer, even from a remote
+    Voil&agrave;/OnDemand session.
   </p>
 </div>
 
@@ -107,6 +117,19 @@ local Python kernel.
   </p>
 </div>
 
+<div class="card">
+  <div class="feature-card__icon">🗂️</div>
+  <div class="feature-card__title">Cluster Batch Jobs</div>
+  <p class="feature-card__body">
+    <code class="inline-code">quantui-batch</code> submits QuantUI
+    calculations to SLURM from a cluster login node over SSH, without
+    starting the image there: presets, chaining from another job's
+    optimized geometry, reruns with more memory or time, and result
+    summaries. <code class="inline-code">quantui submit</code> does the
+    same wherever QuantUI is installed.
+  </p>
+</div>
+
 <div class="card">
   <div class="feature-card__icon">🖥️</div>
   <div class="feature-card__title">Voil&agrave; App Mode</div>

docs/index.md

@@ -22,8 +22,9 @@ hide:
           QuantUI puts <a class="hero__link" href="https://pyscf.org" target="_blank" rel="noopener">PySCF</a>
           and a guarded native-Windows <a class="hero__link" href="https://github.com/manassharma07/PyFock" target="_blank" rel="noopener">PyFock</a> subset
           behind an interactive Jupyter/Voil&agrave; UI. Run DFT, MP2, CCSD,
-          CCSD(T), TD-DFT, NMR, geometry optimization, frequencies, and
-          PES scans &mdash; visualize structures, orbitals, IR and UV-Vis
+          CCSD(T), TD-DFT, NMR, geometry optimization, transition-state
+          searches, frequencies, and PES scans &mdash; visualize structures,
+          orbitals, densities, IR and UV-Vis
           spectra, all on your laptop with optional NVIDIA GPU offload via
           <a class="hero__link" href="https://github.com/pyscf/gpu4pyscf" target="_blank" rel="noopener">gpu4pyscf</a>.
         </p>
@@ -34,7 +35,7 @@ hide:
         <div class="hero__meta">
           <span class="hero__stat">Python 3.9&ndash;3.11</span>
           <span class="hero__sep">&middot;</span>
-          <span class="hero__stat">1500+ tests</span>
+          <span class="hero__stat">3700+ tests</span>
           <span class="hero__sep">&middot;</span>
           <span class="hero__stat">MIT License</span>
           <span class="hero__sep">&middot;</span>

docs/installation.md

@@ -50,6 +50,7 @@ other methods and workflows, use WSL or the Apptainer container described in
 | `ase` | ASE bridge for trajectory export and structure I/O |
 | `app` | Voilà, JupyterLab, and notebook launcher dependencies |
 | `xtb` | GFN-FF metal pre-optimization via xtb |
+| `ts` | Transition-state searches via [Sella](https://github.com/zadorlab/sella) (pulls in jax, about 380 MB) |
 
 ## Next steps