Develop

README.md

@@ -1,31 +1,38 @@
 # SlakoNet
 
-Accurate and efficient prediction of electronic band structures is essential for designing materials with targeted properties. However, existing machine learning models often lack universality and struggle to predict detailed electronic structures, while traditional tight-binding models based on the Slater-Koster (SK) formalism suffer from (i) limited transferability, (ii) the need for manual parameterization, and (iii) training on low-fidelity electronic structure data. To address these challenges, I introduce SlaKoNet, a parameter optimization framework that learns SK-based Hamiltonian matrix elements across 65 elements of the periodic table using automatic differentiation. SlaKoNet is trained on density functional theory data from the JARVIS-DFT database using the Tran-Blaha modified Becke-Johnson (TBmBJ), encompassing over 20000 materials. The framework achieves a mean absolute error (MAE) of 0.74 eV for bandgap predictions against experimental data, representing a reasonable improvement over standard GGA functionals (MAE = 1.14 eV) while preserving the computational advantages and physical interpretability of tight-binding methods. SlaKoNet demonstrates promising scalability with up to 8.4× speedup on GPUs, enabling rapid electronic structure screening for materials discovery.
-
+SlaKoNet learns Slater-Koster tight-binding Hamiltonian matrix elements
+across 65 elements using automatic differentiation, trained on JARVIS-DFT
+data with the Tran-Blaha modified Becke-Johnson (TBmBJ) functional
+(>20,000 materials). It reaches 0.74 eV MAE for band gaps against
+experiment, versus 1.14 eV for standard GGA, while keeping the cost and
+interpretability of tight binding.
 
 ![SlakoNet schematic](https://github.com/atomgptlab/slakonet/blob/main/slakonet/examples/sk_schematic.png)
 
 ## Key Features
 
-- **Universal parameterization**: Works across 65 elements and their combinations
-- **Physics-informed**: Based on Slater-Koster tight-binding formalism
-- **High accuracy**: Mean absolute error of 0.74 eV for band gaps vs experimental values
-- **Scalable**: GPU-accelerated calculations for systems up to 2000 atoms
-- **Comprehensive properties**: Predicts band structures, DOS, band gaps, and orbital projections
+- **Universal parameterization**: 65 elements and their combinations
+- **Physics-informed**: Slater-Koster tight-binding formalism
+- **Accurate**: 0.74 eV MAE for band gaps vs experiment
+- **Scalable**: GPU-accelerated, >10,000 atoms with the sparse solver
+- **Comprehensive**: band structures, DOS, band gaps, orbital projections
+- **ASE-compatible**: energy, forces and stress through a standard calculator
 
 ## Installation
-Install via pip:
+
 ```bash
 pip install slakonet
 ```
 
-Or create a conda environment and install SlaKoNet in editable mode. To do so, first, install miniforge https://github.com/conda-forge/miniforge. For example: 
+Or create a conda environment and install SlaKoNet in editable mode. To
+do so, first install [miniforge](https://github.com/conda-forge/miniforge):
 
 ```
 wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
 ```
 
-Based on your system requirements, you'll get a file something like 'Miniforge3-XYZ'.
+Based on your system requirements, you'll get a file something like
+'Miniforge3-XYZ'.
 
 ```
 bash Miniforge3-$(uname)-$(uname -m).sh
@@ -48,7 +55,7 @@ pip install uv; uv pip install -e .
 
 ### Google Colab example
 
-[Open in Colab](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/slakonet_example.ipynb)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/slakonet_example.ipynb)
 
 ### Example of Training Models
 
@@ -64,6 +71,33 @@ python slakonet/predict_slakonet.py  --file_path slakonet/examples/POSCAR-JVASP-
 
 ![SlakoNet output](https://github.com/atomgptlab/slakonet/blob/main/slakonet/examples/slakonet_bands_dos.png)
 
+### Available Parameter Sets
+
+Parameter sets are downloaded from
+[Figshare](https://figshare.com/articles/dataset/SlakoNet_parameters/30122215)
+on first use and cached under `~/.cache/atomgptlab/slakonet/`.
+
+| Name | Description |
+| --- | --- |
+| `slakonet_v0` | Original universal parameter set (paper v1) |
+| `slakonet_v1` | Second-generation universal parameter set |
+| `slakonet_v1a` | Refined v1 parameter set |
+
+```python
+from slakonet.optim import default_model
+
+model = default_model(model_name="slakonet_v1a")
+```
+
+`default_model()` with no arguments uses `slakonet_v1a`; set the
+`SLAKONET_MODEL` environment variable to change the default globally, and
+`--model_path slakonet_v1a` selects a set from the command line:
+
+```bash
+SLAKONET_MODEL=slakonet_v1a python slakonet/predict_slakonet.py --jid JVASP-107
+python slakonet/predict_slakonet.py --model_path slakonet_v1a --jid JVASP-107
+```
+
 ### Using Pretrained Models in Python
 
 ```python
@@ -82,7 +116,7 @@ model = default_model()
 # Get structure (example with JARVIS ID)
 atoms, opt_gap, mbj_gap = get_atoms("JVASP-107")  
 geometry = Geometry.from_ase_atoms([atoms.ase_converter()])
-shell_dict = generate_shell_dict_upto_Z65()
+shell_dict = generate_shell_dict_upto_Z65(model=model)
 
 # Compute electronic properties
 with torch.no_grad():
@@ -93,9 +127,9 @@ with torch.no_grad():
         device="cuda"
     )
 
-# Access results
-print(f"Band gap: {properties['band_gap_eV']:.3f} eV")
-print(f"Fermi energy: {properties['fermi_energy_eV']:.3f} eV")
+# Access results (all tensors; .item() for scalars)
+print(f"Band gap: {properties['bandgap'].item():.3f} eV")
+print(f"Fermi energy: {properties['fermi_energy'].item():.3f} eV")
 
 # Plot band structure and DOS
 eigenvalues = properties["eigenvalues"]
@@ -133,20 +167,49 @@ bs = calc.band_structure(si, path="GXWKGL", npoints=20,
 e, dos = calc.dos(si)
 print(calc.get_bandgap(), calc.get_fermi_level())
 
+# Hamiltonian and overlap, (n_kpoints, n_orbitals, n_orbitals)
+H, S = calc.get_HS(si)
+
 # reuse on another structure with NO model reload
 ge = bulk("Ge", "diamond", a=5.66); ge.calc = calc
 ge.get_potential_energy()
 ```
 
+`get_bandstructure()` and `get_dos()` are aliases of `band_structure()`
+and `dos()`. The same three accessors exist on
+`slakonet.main.SlakoNetCalculator`.
+
+`get_HS` returns the k-resolved Hamiltonian and overlap. **H is in
+Hartree** and the basis is non-orthogonal, so band energies come from
+the generalized eigenproblem:
+
+```python
+import scipy.linalg as sla
+from ase.build import bulk
+from slakonet.optim import default_model
+from slakonet.ase_calc import SlaKoNetCalculator
+
+calc = SlaKoNetCalculator(default_model().float(), kpoints=(3, 3, 3))
+si = bulk("Si", "diamond", a=5.43)
+si.calc = calc
+si.get_potential_energy()                       # sets the Fermi level
+
+H, S = calc.get_HS(si)
+w = sla.eigh(H[0], S[0], eigvals_only=True)     # k-point 0
+eigenvalues_eV = w * 27.211 - calc.get_fermi_level()
+```
+
 Toggles (constructor keywords): `compute_forces`, `compute_stress`,
 `use_scc`, `include_dos`, `kpoints`, `cutoff`, `kT`, `alpha`, `beta`,
 `device`. Setting `compute_forces=False` gives a fast energy-only path
 for high-throughput screening.
 
-Notes: forces are scaled by `beta` (default `0.1`); pass `beta=1.0` for
-physically correct forces. Stress is converted to ASE units
-(eV/Ang^3, Voigt) but should be validated against a numerical-strain
-reference before use in cell relaxation. A full runnable demo is in
+Notes: `alpha` scales the band-structure energy and `beta` the forces;
+both default to `1.0`, which gives the standard DFTB total energy
+`E = E_band + E_rep` together with its exact gradient. Energy, forces
+and stress have been checked against finite differences (agreement
+better than 0.5% for bulk Si and SiC), so cell relaxation with
+`ExpCellFilter` is supported. A full runnable demo is in
 `slakonet/examples/slakonet_calculator_example.py`. See also the ASE docs
 page *Calculators -> SlaKoNet*.
 
@@ -158,32 +221,33 @@ page *Calculators -> SlaKoNet*.
 
 ## Performance Benchmarks
 
-- **Accuracy**: 0.76 eV MAE for band gaps (vs 0.38 eV for reference TB-mBJ DFT)
-- **Speed**: <10 seconds for 1000-atom systems on GPU
-- **Scalability**: Efficient with GPU acceleration
-- **Coverage**: Validated on 50 semiconductor/insulator compounds for experiments
+Accuracy: 0.76 eV MAE for band gaps (vs 0.38 eV for reference TB-mBJ
+DFT), validated on 50 semiconductor/insulator compounds.
 
-![SlakoNet timing](https://github.com/atomgptlab/slakonet/blob/main/slakonet/examples/timing.png)
-
-
-## Output Properties
+### Scaling
 
-SlakoNet predicts comprehensive electronic properties including:
+Time per diagonalization, with peak GPU memory in brackets (GB). The
+dense `eigh` path is limited to roughly 7,000 orbitals; beyond that the
+sparse solver is the only option.
 
-- Electronic band structures along high-symmetry k-paths
-- Total and projected density of states (DOS)
-- Band gaps (direct/indirect) and band edges
-- Fermi energy and electronic structure topology
-- Atom-projected and orbital-projected DOS (s/p/d contributions)
+| atoms | Norb | dense eigh (s) | sparse solve (s) |
+| ---: | ---: | ---: | ---: |
+| 128 | 1,152 | 0.15 [2.6] | 0.12 [2.6] |
+| 1,024 | 9,216 | – (Norb > 7k) | 3.71 [3.4] |
+| 3,456 | 31,104 | – | 56.9 [5.3] |
+| 8,192 | 73,728 | – | 403 [10.0] |
+| 11,664 | 104,976 | – | 956 [19.2] |
+| 16,000 | 144,000 | – | > 30 min (timeout) |
 
-## Applications
+![SlakoNet timing](https://github.com/atomgptlab/slakonet/blob/main/slakonet/examples/timing.png)
 
-- High-throughput materials screening
-- Electronic structure prediction without expensive DFT
-- Band structure and DOS calculations for device design
-- Semiconductor and quantum materials discovery
-- Educational tools for solid-state physics
+## Output Properties
 
+- Band structures along high-symmetry k-paths
+- Total, atom-projected and orbital-projected DOS (s/p/d)
+- Band gaps (direct/indirect) and band edges
+- Fermi energy
+- Hamiltonian and overlap matrices
 
 ## Dataset
 

setup.py

@@ -8,7 +8,7 @@
 
 setuptools.setup(
     name="slakonet",
-    version="5.20.2026",
+    version="2026.7.26",
     author="Kamal Choudhary",
     author_email="kchoudh2@jhu.edu",
     description="slakonet",

slakonet/__init__.py

@@ -1,3 +1,3 @@
 """Version number."""
 
-__version__ = "5.20.2026"
+__version__ = "2026.7.26"