Skip to content

Commit 4ab2e61

Browse files
NCCU-Schultz-LabNCCU-Schultz-Lab
committed
Add CI, Dependabot, LICENSE, README, SECURITY
Initial repository scaffolding: add GitHub Actions CI (Linux/Windows test matrix, linting with ruff, mypy type checks, and Codecov upload), Dependabot configuration for pip and GitHub Actions with grouped updates and pyscf major-version ignore, an MIT LICENSE, a detailed README for installation/usage/tutorials, and a SECURITY.md describing vulnerability reporting and scope. These changes set up automated testing, dependency maintenance, project documentation, and security guidance for the codebase.
1 parent f5d2ee1 commit 4ab2e61

5 files changed

Lines changed: 400 additions & 0 deletions

File tree

‎.github/dependabot.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
version: 2
2+
3+
updates:
4+
# Python dependencies (pyproject.toml)
5+
- package-ecosystem: pip
6+
directory: /
7+
schedule:
8+
interval: weekly
9+
day: monday
10+
open-pull-requests-limit: 5
11+
groups:
12+
# Batch minor/patch bumps for core scientific deps into one PR
13+
scientific-core:
14+
patterns:
15+
- "numpy"
16+
- "matplotlib"
17+
- "plotly"
18+
# ASE + PySCF together since they interact
19+
qc-engines:
20+
patterns:
21+
- "ase"
22+
- "pyscf"
23+
# Jupyter ecosystem together
24+
jupyter:
25+
patterns:
26+
- "jupyter*"
27+
- "ipywidgets"
28+
- "notebook"
29+
- "voila"
30+
- "ipykernel"
31+
# Dev/test tools together
32+
dev-tools:
33+
patterns:
34+
- "pytest*"
35+
- "mypy"
36+
- "types-*"
37+
- "ruff"
38+
ignore:
39+
# PySCF major versions may break API — review manually
40+
- dependency-name: pyscf
41+
update-types: ["version-update:semver-major"]
42+
43+
# GitHub Actions pinned to SHA via Dependabot — keeps runners current
44+
- package-ecosystem: github-actions
45+
directory: /
46+
schedule:
47+
interval: weekly
48+
day: monday
49+
open-pull-requests-limit: 3

‎.github/workflows/ci.yml‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
# ── Linux: full suite including PySCF-dependent tests ─────────────────────
11+
test-linux:
12+
name: Tests (ubuntu-latest, Python ${{ matrix.python-version }})
13+
runs-on: ubuntu-latest
14+
strategy:
15+
fail-fast: false
16+
matrix:
17+
python-version: ["3.10", "3.11"]
18+
19+
steps:
20+
- uses: actions/checkout@v4
21+
22+
- name: Set up Python ${{ matrix.python-version }}
23+
uses: actions/setup-python@v5
24+
with:
25+
python-version: ${{ matrix.python-version }}
26+
cache: pip
27+
28+
- name: Install package and dev dependencies
29+
run: |
30+
python -m pip install --upgrade pip
31+
pip install -e ".[pyscf,ase,dev]"
32+
33+
- name: Run tests (skip network tests)
34+
run: |
35+
pytest -m "not network" \
36+
--cov=quantui \
37+
--cov-report=term-missing \
38+
--cov-report=xml \
39+
--no-header -q
40+
41+
- name: Upload coverage to Codecov
42+
if: matrix.python-version == '3.11'
43+
uses: codecov/codecov-action@v4
44+
with:
45+
files: coverage.xml
46+
fail_ci_if_error: false
47+
48+
# ── Windows: non-PySCF tests only (PySCF requires Linux/WSL) ──────────────
49+
test-windows:
50+
name: Tests (windows-latest, Python 3.11)
51+
runs-on: windows-latest
52+
53+
steps:
54+
- uses: actions/checkout@v4
55+
56+
- name: Set up Python 3.11
57+
uses: actions/setup-python@v5
58+
with:
59+
python-version: "3.11"
60+
cache: pip
61+
62+
- name: Install package and dev dependencies
63+
run: |
64+
python -m pip install --upgrade pip
65+
pip install -e ".[ase,dev]"
66+
67+
- name: Run non-PySCF tests
68+
# PySCF tests are skipped automatically via skipif guards when pyscf
69+
# is not installed. network tests also skipped.
70+
run: |
71+
pytest -m "not network" \
72+
--ignore=tests/test_session_calc.py \
73+
--ignore=tests/test_optimizer.py \
74+
--ignore=tests/test_preopt.py \
75+
--no-cov \
76+
--no-header -q
77+
78+
# ── Lint / type-check ─────────────────────────────────────────────────────
79+
lint:
80+
name: Lint & type check
81+
runs-on: ubuntu-latest
82+
83+
steps:
84+
- uses: actions/checkout@v4
85+
86+
- name: Set up Python 3.11
87+
uses: actions/setup-python@v5
88+
with:
89+
python-version: "3.11"
90+
cache: pip
91+
92+
- name: Install lint dependencies
93+
run: |
94+
python -m pip install --upgrade pip
95+
pip install -e ".[dev]"
96+
pip install ruff
97+
98+
- name: Lint with ruff
99+
run: ruff check quantui/ tests/
100+
101+
- name: Type check with mypy
102+
run: mypy quantui/ --ignore-missing-imports

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 The Schultz Lab, North Carolina Central University
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# QuantUI-local
2+
3+
An interactive Jupyter interface for running quantum chemistry calculations
4+
locally — no cluster account, no SLURM, no queueing. Students design
5+
molecules, launch PySCF calculations in their own Python session, and
6+
visualize results in minutes.
7+
8+
Built for classroom teaching at the
9+
[Schultz Lab, North Carolina Central University](https://github.com/The-Schultz-Lab).
10+
11+
---
12+
13+
## What it does
14+
15+
- **Molecule input** — paste XYZ coordinates, draw from a preset library, or
16+
search PubChem by name or SMILES
17+
- **3D visualization** — interactive py3Dmol viewer, directly in the notebook
18+
- **In-session calculations** — RHF and UHF via PySCF, running in your Python
19+
kernel (no batch submission)
20+
- **Results** — total energy, HOMO-LUMO gap, convergence status, and a
21+
side-by-side comparison table for multiple calculations
22+
- **Script export** — download a standalone `.py` file to run or study outside
23+
the notebook
24+
- **Voilà app mode** — serve the notebook as a clean widget-only UI (no code
25+
visible) for classroom demos
26+
27+
---
28+
29+
## Platform requirements
30+
31+
| Platform | Works? | Notes |
32+
|----------|--------|-------|
33+
| Linux / macOS | Full | PySCF installs natively |
34+
| WSL (Windows) | Full | Use an Ubuntu WSL environment |
35+
| Windows (native) | Partial | All UI and visualization features work; PySCF calculations require the Apptainer container |
36+
37+
### Windows users: Apptainer container
38+
39+
PySCF does not install on Windows natively. The
40+
[`apptainer/quantui-local.def`](apptainer/quantui-local.def) container bundles
41+
the complete environment and runs anywhere Apptainer/Singularity is available.
42+
See [`apptainer/BUILD.md`](apptainer/BUILD.md) for build and run instructions.
43+
44+
---
45+
46+
## Installation
47+
48+
### Option A — conda (recommended for Linux/macOS/WSL)
49+
50+
```bash
51+
# Create a dedicated environment
52+
conda create -n quantui-local python=3.11
53+
conda activate quantui-local
54+
55+
# Install with PySCF and ASE
56+
pip install -e ".[pyscf,ase,app]"
57+
```
58+
59+
### Option B — pip only
60+
61+
```bash
62+
python -m pip install quantui-local[pyscf,ase,app]
63+
```
64+
65+
### Option C — Apptainer container (Windows / reproducible deployment)
66+
67+
See [apptainer/BUILD.md](apptainer/BUILD.md).
68+
69+
---
70+
71+
## Quick start
72+
73+
```bash
74+
# Activate your environment
75+
conda activate quantui-local
76+
77+
# JupyterLab (full IDE — shows code)
78+
jupyter lab notebooks/molecule_computations.ipynb
79+
80+
# Voilà app mode (widget-only — for classroom demos)
81+
voila notebooks/molecule_computations.ipynb
82+
```
83+
84+
Open the notebook, pick a molecule, choose a method and basis set, and click
85+
**Run Calculation**. Results appear directly in the notebook.
86+
87+
---
88+
89+
## Tutorials
90+
91+
Five step-by-step notebooks in [`notebooks/tutorials/`](notebooks/tutorials/):
92+
93+
| Notebook | Topic |
94+
|----------|-------|
95+
| [01_first_calculation.ipynb](notebooks/tutorials/01_first_calculation.ipynb) | Your first RHF calculation |
96+
| [02_basis_set_study.ipynb](notebooks/tutorials/02_basis_set_study.ipynb) | Comparing STO-3G, 6-31G, cc-pVDZ |
97+
| [03_multiplicity_radicals.ipynb](notebooks/tutorials/03_multiplicity_radicals.ipynb) | Open-shell molecules and UHF |
98+
| [04_charged_species.ipynb](notebooks/tutorials/04_charged_species.ipynb) | Ions and charged systems |
99+
| [05_comparing_results.ipynb](notebooks/tutorials/05_comparing_results.ipynb) | Side-by-side result analysis |
100+
101+
---
102+
103+
## Supported calculations
104+
105+
| Method | When to use |
106+
|--------|------------|
107+
| RHF | Closed-shell molecules — all electrons paired |
108+
| UHF | Open-shell molecules — radicals or unpaired electrons |
109+
110+
**Basis sets:** STO-3G (fast, good for learning) → 6-31G (common research
111+
choice) → cc-pVTZ (high accuracy)
112+
113+
---
114+
115+
## Running tests
116+
117+
```bash
118+
pip install -e ".[dev]"
119+
120+
# All tests (Linux/macOS — PySCF available)
121+
pytest -m "not network"
122+
123+
# Skip PySCF-dependent tests (Windows without container)
124+
pytest -m "not network" \
125+
--ignore=tests/test_session_calc.py \
126+
--ignore=tests/test_optimizer.py \
127+
--ignore=tests/test_preopt.py
128+
```
129+
130+
---
131+
132+
## Project structure
133+
134+
```
135+
quantui/ Main package
136+
molecule.py Molecule input and validation
137+
session_calc.py In-session PySCF runner
138+
visualization_py3dmol.py 3D viewer
139+
pubchem.py PubChem molecule search
140+
comparison.py Side-by-side result tables
141+
ase_bridge.py ASE structure I/O
142+
optimizer.py QM geometry optimization
143+
...
144+
notebooks/
145+
molecule_computations.ipynb Main student-facing interface
146+
tutorials/ Step-by-step guided notebooks
147+
tests/ pytest test suite (439 tests)
148+
apptainer/ Container definition for reproducible deployment
149+
local-setup/ Conda environment definition
150+
pyproject.toml Package metadata and tool config
151+
```
152+
153+
---
154+
155+
## Relationship to the cluster version
156+
157+
QuantUI-local is a downstream port of the cluster-based
158+
[QuantUI](https://github.com/The-Schultz-Lab/QuantUI) repository. All SLURM
159+
infrastructure (job manager, job storage, batch templates) has been removed.
160+
Bug fixes flow `QuantUI → QuantUI-local`, not the other way around.
161+
162+
---
163+
164+
## License
165+
166+
[MIT](LICENSE) — Copyright 2026 The Schultz Lab, North Carolina Central University

0 commit comments

Comments
 (0)