Merge pull request #11 from The-Schultz-Lab/expansion

Expansion

Author: NCCU-Schultz-Lab

.github/copilot-instructions.md

@@ -1,3 +1,6 @@
+# Dev launcher stamp (written by launch-native.bat to skip redundant pip install)
+.dev_install_stamp
+
 # Python
 __pycache__/
 *.py[cod]
@@ -54,3 +57,6 @@ Thumbs.db
 *.swo
 
 planning/
+nul
+/.claude/
+/temp - untracked/

.gitignore

@@ -1,7 +1,7 @@
-# QuantUI-local
+# QuantUI
 
-[![CI](https://github.com/The-Schultz-Lab/QuantUI-local/actions/workflows/ci.yml/badge.svg)](https://github.com/The-Schultz-Lab/QuantUI-local/actions/workflows/ci.yml)
-[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://the-schultz-lab.github.io/QuantUI-local/)
+[![CI](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml/badge.svg)](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://the-schultz-lab.github.io/QuantUI/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11-blue)](https://www.python.org)
 
@@ -17,18 +17,30 @@ Built for classroom teaching at the
 
 ## What it does
 
-- **Molecule input** — paste XYZ coordinates, draw from a preset library, or
-  search PubChem by name or SMILES
-- **3D visualization** — interactive py3Dmol viewer, directly in the notebook
-- **In-session calculations** — RHF and UHF via PySCF, running in your Python
-  kernel (no batch submission)
-- **Results** — total energy, HOMO-LUMO gap, convergence status, and a
-  side-by-side comparison table for multiple calculations
+- **Molecule input** — paste XYZ coordinates, draw from a 20+ preset library,
+  or search PubChem by name or SMILES
+- **3D visualization** — interactive py3Dmol or PlotlyMol viewer with a live
+  backend toggle when both are installed; post-calculation structure rendered
+  automatically in the results panel
+- **In-session calculations** — RHF, UHF, 9 DFT functionals, MP2, and NMR
+  shielding via PySCF, running in your Python kernel (no batch submission)
+- **Implicit solvent** — PCM solvation (Water, Ethanol, THF, DMSO,
+  Acetonitrile) via a single checkbox
+- **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
+- **Geometry optimization** — BFGS optimizer with step-by-step trajectory
+  animation; vibrational frequency analysis with animated normal modes
 - **Results persistence** — every calculation is saved automatically to a
   timestamped directory; a built-in browser lets students reload past results
-  after a kernel restart
-- **Script export** — download a standalone `.py` file to run or study outside
-  the notebook
+  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
+- **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 code
   visible) for classroom demos, with dark mode toggle and dedicated output log
 
@@ -45,7 +57,7 @@ Built for classroom teaching at the
 ### Windows users: Apptainer container
 
 PySCF does not install on Windows natively. The
-[`apptainer/quantui-local.def`](apptainer/quantui-local.def) container bundles
+[`apptainer/quantui.def`](apptainer/quantui.def) container bundles
 the complete environment and runs anywhere Apptainer/Singularity is available.
 See [`apptainer/README.md`](apptainer/README.md) for build and run instructions.
 
@@ -57,8 +69,8 @@ See [`apptainer/README.md`](apptainer/README.md) for build and run instructions.
 
 ```bash
 # Create a dedicated environment
-conda create -n quantui-local python=3.11
-conda activate quantui-local
+conda create -n quantui python=3.11
+conda activate quantui
 
 # Install with PySCF and ASE
 pip install -e ".[pyscf,ase,app]"
@@ -67,7 +79,7 @@ pip install -e ".[pyscf,ase,app]"
 ### Option B — pip only
 
 ```bash
-python -m pip install quantui-local[pyscf,ase,app]
+python -m pip install quantui[pyscf,ase,app]
 ```
 
 ### Option C — Apptainer container (Windows / reproducible deployment)
@@ -80,7 +92,7 @@ See [apptainer/README.md](apptainer/README.md).
 
 ```bash
 # Activate your environment
-conda activate quantui-local
+conda activate quantui
 
 # JupyterLab (full IDE — shows code)
 jupyter lab notebooks/molecule_computations.ipynb
@@ -110,13 +122,37 @@ Five step-by-step notebooks in [`notebooks/tutorials/`](notebooks/tutorials/):
 
 ## Supported calculations
 
-| Method | When to use |
+### Methods
+
+| Method | Type | Best for |
+| --- | --- | --- |
+| RHF | Hartree-Fock | Closed-shell molecules; baseline reference |
+| UHF | Hartree-Fock | Radicals and open-shell systems |
+| B3LYP | DFT hybrid | General organic chemistry (default DFT choice) |
+| PBE | DFT GGA | Large molecules; metals; when speed matters |
+| PBE0 | DFT hybrid | Charge-transfer, band gaps |
+| M06-2X | DFT meta-hybrid | Thermochemistry, barrier heights |
+| wB97X-D | DFT range-sep. + D3 | Non-covalent interactions, excited states |
+| CAM-B3LYP | DFT range-sep. | Charge-transfer UV-Vis, Rydberg states |
+| M06-L | DFT local meta-GGA | Large molecules; transition metals |
+| HSE06 | DFT screened hybrid | Band gaps, large molecules |
+| PBE-D3 | DFT GGA + dispersion | Van der Waals complexes, stacking |
+| MP2 | Post-HF | Accurate energetics for small molecules (O(N⁵)) |
+
+### Calculation types
+
+| Type | Output |
 | --- | --- |
-| RHF | Closed-shell molecules — all electrons paired |
-| UHF | Open-shell molecules — radicals or unpaired electrons |
+| 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) |
+| 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 |
+
+### Basis sets
 
-**Basis sets:** STO-3G (fast, good for learning) → 6-31G (common research
-choice) → cc-pVTZ (high accuracy)
+STO-3G (fast, good for learning) → 3-21G → 6-31G / 6-31G\* / 6-31G\*\* →
+cc-pVDZ / cc-pVTZ → def2-SVP / def2-TZVP
 
 ---
 
@@ -141,18 +177,27 @@ pytest -m "not network" \
 
 ```text
 quantui/                  Main package
+  app.py                  QuantUIApp widget class (all tabs, UI logic)
   molecule.py             Molecule input and validation
-  session_calc.py         In-session PySCF runner
-  visualization_py3dmol.py  3D viewer
+  session_calc.py         In-session PySCF runner (RHF/UHF/DFT/MP2/PCM)
+  freq_calc.py            Vibrational frequency + thermochemistry analysis
+  ir_plot.py              IR spectrum chart (stick and Lorentzian broadened)
+  tddft_calc.py           TD-DFT UV-Vis excited-state calculations
+  nmr_calc.py             NMR shielding + ¹H/¹³C chemical shift prediction
+  optimizer.py            QM geometry optimization with trajectory
+  visualization_py3dmol.py  3D viewer (py3Dmol + PlotlyMol backends)
   pubchem.py              PubChem molecule search
   comparison.py           Side-by-side result tables
+  results_storage.py      Timestamped result persistence
+  calc_log.py             Performance logging and time estimation
+  benchmarks.py           Timing calibration benchmark suite
+  config.py               Methods, basis sets, solvent/NMR options, presets
   ase_bridge.py           ASE structure I/O
-  optimizer.py            QM geometry optimization
-  ...
+  preopt.py               LJ force-field pre-optimization
 notebooks/
   molecule_computations.ipynb   Main student-facing interface
-  tutorials/                    Step-by-step guided notebooks
-tests/                    pytest test suite (439 tests)
+  tutorials/                    Step-by-step guided notebooks (01–05)
+tests/                    pytest test suite (575+ tests)
 apptainer/                Container definition for reproducible deployment
 local-setup/              Conda environment definition
 pyproject.toml            Package metadata and tool config
@@ -162,10 +207,10 @@ pyproject.toml            Package metadata and tool config
 
 ## Relationship to the cluster version
 
-QuantUI-local is a downstream port of the cluster-based
-[QuantUI](https://github.com/The-Schultz-Lab/QuantUI) repository. All SLURM
+QuantUI (this repo) is a downstream port of the cluster-based
+[QuantUI-cluster](https://github.com/The-Schultz-Lab/QuantUI) repository. All SLURM
 infrastructure (job manager, job storage, batch templates) has been removed.
-Bug fixes flow `QuantUI → QuantUI-local`, not the other way around.
+Bug fixes flow from the cluster repo into this one, not the other way around.
 
 ---
 

README.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-QuantUI-local is an educational teaching tool designed for classroom and local
+QuantUI is an educational teaching tool designed for classroom and local
 research use. It runs calculations inside your own Python session — there is
 no server, no user accounts, and no data stored outside your local machine.
 
@@ -19,7 +19,7 @@ GitHub issue**.
 Instead, report it privately via one of these channels:
 
 - **GitHub private vulnerability reporting** — use the
-  [Security tab](https://github.com/The-Schultz-Lab/QuantUI-local/security/advisories/new)
+  [Security tab](https://github.com/The-Schultz-Lab/QuantUI/security/advisories/new)
   on this repository (preferred).
 - **Email** — contact the lab maintainer through the GitHub profile
   [@The-Schultz-Lab](https://github.com/The-Schultz-Lab).
@@ -28,7 +28,7 @@ Please include:
 
 1. A short description of the issue and its potential impact
 2. Steps to reproduce (or a minimal proof-of-concept)
-3. The version of QuantUI-local affected
+3. The version of QuantUI affected
 4. Your suggested fix, if you have one
 
 We aim to acknowledge reports within **5 business days** and to release a fix
@@ -55,7 +55,7 @@ Issues that are explicitly **out of scope**:
 
 ## Dependencies
 
-QuantUI-local relies on PySCF, ASE, NumPy, Matplotlib, ipywidgets, and
+QuantUI relies on PySCF, ASE, NumPy, Matplotlib, ipywidgets, and
 py3Dmol. Security advisories for these packages are tracked automatically
 via Dependabot. If you become aware of a critical CVE in one of these
 dependencies before Dependabot picks it up, please report it using the