docs

docs/api.md

@@ -0,0 +1,62 @@
+# Package Overview
+
+High-level tour of the `alignn` package. For authoritative details, read the source —
+this page is a map, not an API reference.
+
+## Top-level modules
+
+| Module | Role |
+|---|---|
+| `alignn.train_alignn` | Training CLI entry point |
+| `alignn.train` | Training loop (called by the CLI) |
+| `alignn.config` | Pydantic config schema for training / models |
+| `alignn.data` | Dataset loaders — CSV/JSON index → torch datasets |
+| `alignn.dataset` | Low-level dataset classes |
+| `alignn.graphs` | Crystal graph + line graph construction |
+| `alignn.lmdb_dataset` | LMDB-backed dataset for large-scale training |
+| `alignn.pretrained` | Load and apply pretrained property predictors |
+| `alignn.run_alignn_ff` | ALIGNN-FF CLI entry point |
+| `alignn.cli` | Shared CLI argument parsing |
+| `alignn.utils` | Misc helpers (logging, config loading, …) |
+| `alignn.profiler` | Optional training profiler |
+
+## Models (`alignn.models`)
+
+| Module | Model |
+|---|---|
+| `alignn.models.alignn` | Original ALIGNN property predictor |
+| `alignn.models.alignn_atomwise` | ALIGNN with atomwise outputs (forces/charges/mag) |
+| `alignn.models.ealignn_atomwise` | Equivariant atomwise variant |
+| `alignn.models.utils` | Shared layers and helpers |
+
+## Force-field (`alignn.ff`)
+
+| Module | Role |
+|---|---|
+| `alignn.ff.ff` | `AlignnAtomwiseCalculator`, `default_path`, training utils |
+| `alignn.ff.calculators` | ASE calculator implementations |
+| `alignn.ff.all_models_alignn.json` | Registry of property-predictor checkpoints |
+| `alignn.ff.all_models_alignn_atomwise.json` | Registry of ALIGNN-FF checkpoints |
+
+Bundled pretrained checkpoints live in sub-directories of `alignn/ff/`, e.g.
+`v10.30.2024_dft_3d_307k/`, `v12.2.2024_dft_3d_307k/`,
+`v2024.12.12_dft_3d_multi_prop/`, `alignnff_wt01/`.
+
+## Examples & scripts
+
+- [`alignn/examples/`](https://github.com/atomgptlab/alignn/tree/main/alignn/examples) —
+  runnable sample datasets and configs (`sample_data`, `sample_data_ff`,
+  `sample_data_multi_prop`, …).
+- [`alignn/scripts/`](https://github.com/atomgptlab/alignn/tree/main/alignn/scripts) —
+  high-throughput training scripts that download public datasets and train one model
+  per target.
+
+## CLIs at a glance
+
+```bash
+train_alignn.py   -h   # training (regression, classification, atomwise, multi-output)
+pretrained.py     -h   # apply a pretrained property predictor
+run_alignn_ff.py  -h   # apply a pretrained ALIGNN-FF (optimize, EV curve, phonons, …)
+```
+
+All three are installed to your environment's `bin/` directory.

docs/contributing.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Contributions are welcome — bug fixes, new features, benchmarks, and docs.
+
+## How to contribute
+
+1. Fork [atomgptlab/alignn](https://github.com/atomgptlab/alignn) and create a topic
+   branch off `develop`.
+2. Install in development mode:
+   ```bash
+   git clone https://github.com/<you>/alignn
+   cd alignn
+   python -m pip install -e .
+   ```
+3. Make your change and add or update tests in `alignn/tests/`.
+4. Run the test suite:
+   ```bash
+   pytest alignn/tests
+   ```
+5. Open a pull request targeting `develop`.
+
+Detailed instructions mirror the general JARVIS guide:
+[Contribution.rst](https://github.com/atomgptlab/jarvis/blob/master/Contribution.rst).
+
+## Code of conduct
+
+See the JARVIS [Code of Conduct](https://github.com/atomgptlab/jarvis/blob/master/CODE_OF_CONDUCT.md).
+
+## Reporting issues
+
+Open a GitHub issue at <https://github.com/atomgptlab/alignn/issues>. Please include:
+
+- The ALIGNN version (`pip show alignn`)
+- PyTorch and DGL versions
+- Operating system and GPU (if applicable)
+- A minimal reproducer (config, a few structures, the command you ran)
+- The full error traceback

docs/index.md

@@ -0,0 +1,49 @@
+# ALIGNN & ALIGNN-FF
+
+[![PyPI](https://badge.fury.io/py/alignn.svg)](https://badge.fury.io/py/alignn)
+[![Build](https://github.com/atomgptlab/alignn/actions/workflows/main.yml/badge.svg)](https://github.com/atomgptlab/alignn/actions/workflows/main.yml)
+[![codecov](https://codecov.io/gh/atomgptlab/alignn/branch/main/graph/badge.svg?token=S5X4OYC80V)](https://codecov.io/gh/atomgptlab/alignn)
+[![Downloads](https://pepy.tech/badge/alignn)](https://pepy.tech/project/alignn)
+
+The **Atomistic Line Graph Neural Network (ALIGNN)** introduces a graph convolution layer
+that explicitly models both two- and three-body interactions in atomistic systems. It
+composes two edge-gated graph convolution layers: one applied to the atomistic line graph
+*L(g)* (triplet interactions) and one to the atomistic bond graph *g* (pair interactions).
+
+**ALIGNN-FF** is a universal force-field built on ALIGNN. It was trained on the JARVIS-DFT
+dataset (~75,000 materials and 4M+ energy/force entries) and supports any combination of
+89 elements. Pretrained models can be fine-tuned or trained from scratch on new data.
+
+![ALIGNN layer schematic](https://github.com/atomgptlab/alignn/blob/develop/alignn/tex/schematic_lg.jpg?raw=true)
+
+## Highlights
+
+- Property prediction (regression & binary classification)
+- Multi-output regression (e.g. energy + bandgap + DOS)
+- Universal force-field (ALIGNN-FF) with ASE calculator
+- Pretrained models on JARVIS, Materials Project, QM9, MOF datasets
+- Multi-GPU training via `torchrun` (`DistributedDataParallel`)
+- CLI entry points: `train_alignn.py`, `pretrained.py`, `run_alignn_ff.py`
+
+## Quick links
+
+- [Install ALIGNN](installation.md)
+- [Train your first model](training/single-output-regression.md)
+- [Use a pretrained model](pretrained/index.md)
+- [Run the ALIGNN-FF ASE calculator](usage/ase-calculator.md)
+- [Performance benchmarks](performance.md)
+
+## Citing
+
+If you use ALIGNN, please cite the relevant papers listed on the
+[References](references.md) page. The primary references are:
+
+1. Choudhary, K., DeCost, B. *Atomistic Line Graph Neural Network for improved
+   materials property predictions.* **npj Comput Mater** 7, 185 (2021).
+2. Choudhary, K., et al. *Unified graph neural network force-field for the periodic
+   table.* **Digital Discovery** (2023).
+
+## Correspondence
+
+Please open issues at <https://github.com/atomgptlab/alignn/issues> or email
+`drkamal@jhu.edu`.

docs/installation.md

@@ -0,0 +1,81 @@
+# Installation
+
+ALIGNN supports Linux, macOS, and Windows with Python 3.10.
+
+## Prerequisites
+
+Install Miniconda from <https://conda.io/miniconda.html>. Pick the installer matching
+your OS:
+
+```bash
+bash Miniconda3-latest-Linux-x86_64.sh      # Linux
+bash Miniconda3-latest-MacOSX-x86_64.sh     # macOS
+```
+
+On Windows, use the 64-bit Python 3.10 Miniconda installer.
+
+## Method 1 — conda (recommended)
+
+```bash
+conda create --name my_alignn python=3.10 -y
+conda activate my_alignn
+conda install dgl=2.1.0 pytorch torchvision torchaudio pytorch-cuda -c pytorch -c nvidia
+conda install alignn -y
+```
+
+## Method 2 — from GitHub (development install)
+
+```bash
+conda create --name my_alignn python=3.10 -y
+conda activate my_alignn
+conda install dgl=2.1.0 pytorch torchvision torchaudio pytorch-cuda -c pytorch -c nvidia
+git clone https://github.com/atomgptlab/alignn
+cd alignn
+python -m pip install -e .
+```
+
+## Method 3 — pip
+
+If you prefer pip, install DGL first from the wheel index that matches your CUDA/PyTorch
+version (see <https://www.dgl.ai/pages/start.html>).
+
+PyTorch 2.1 + CUDA 12.1 (Windows/Linux):
+
+```bash
+pip install -q dgl -f https://data.dgl.ai/wheels/torch-2.1/cu121/repo.html
+pip install alignn
+```
+
+CPU only:
+
+```bash
+pip install -q dgl -f https://data.dgl.ai/wheels/torch-2.1/repo.html
+pip install alignn
+```
+
+## Verifying your install
+
+```bash
+train_alignn.py -h
+pretrained.py -h
+run_alignn_ff.py -h
+```
+
+All three are Python executable scripts installed to your environment's `bin/` directory
+— you do not need to provide an absolute path.
+
+## Common issues
+
+!!! warning "DGL + CUDA mismatches"
+    The most common install problem is a DGL build that does not match your CUDA version.
+    If you see import errors about `libtorch_cuda.so` or similar, reinstall DGL from the
+    wheel index matching your CUDA driver.
+
+- Use `batch_size` of 32 or 64 for real trainings (the examples ship with `batch_size: 2`).
+- Complex `.cif` and `.pdb` files may require `cif2cell==2.0.0a3` and `pytraj`
+  respectively.
+- `pandas >= 1.2.3` is required.
+- From March 2024, `pytorch-ignite` is no longer required (removed for conda-forge
+  compatibility).
+
+See the [Notes & FAQ](notes.md) for more tips.

docs/notes.md

@@ -0,0 +1,43 @@
+# Notes & FAQ
+
+A grab-bag of tips collected from user issues and questions.
+
+## GPU / DGL
+
+- Install a DGL build that matches your CUDA runtime, e.g. `pip install dgl-cu111` for
+  CUDA 11.1. Mismatched builds are the most common install failure.
+- If you see errors involving `libcudart.so` or `libtorch_cuda.so`, reinstall DGL from
+  the wheel index that matches your PyTorch CUDA version (see
+  [Installation](installation.md)).
+
+## Structure file parsing
+
+- Simple `.cif` and `.pdb` files are handled by `jarvis-tools` directly.
+- For more complex CIFs, install `cif2cell==2.0.0a3`.
+- For complex PDBs, install `pytraj` via `conda install -c ambermd pytraj`.
+
+## Training hyperparameters
+
+- The example `config_example.json` ships with `batch_size: 2` so the test suite runs
+  fast. **Use `batch_size: 32` or `64` for real trainings** — otherwise training will
+  be very slow and under-performing.
+- `pandas >= 1.2.3` is required.
+- Starting March 2024, `pytorch-ignite` is no longer a dependency (removed for
+  conda-forge build compatibility).
+
+## CLIs are importable scripts
+
+`train_alignn.py`, `pretrained.py`, and `run_alignn_ff.py` are installed as executables
+in your environment's `bin/` directory. You do not need the absolute path — just run
+them.
+
+## Known dataset issues
+
+- **QM9** results: see
+  [issue #54](https://github.com/atomgptlab/alignn/issues/54) for details on a data-split
+  discrepancy that affects reproducibility.
+
+## Getting help
+
+- File a GitHub issue: <https://github.com/atomgptlab/alignn/issues>
+- Email: `drkamal@jhu.edu`

docs/performance.md

@@ -0,0 +1,92 @@
+# Performance
+
+ALIGNN has been benchmarked across many public materials datasets. For the most
+up-to-date numbers see [JARVIS-Leaderboard](https://pages.nist.gov/jarvis_leaderboard/).
+
+## JARVIS-DFT 2021 — classification
+
+| Classifier | Threshold | ALIGNN AUC |
+|---|---|---|
+| Metal / non-metal (OPT) | 0.01 eV | 0.92 |
+| Metal / non-metal (MBJ) | 0.01 eV | 0.92 |
+| Magnetic / non-magnetic | 0.05 µB | 0.91 |
+| High / low SLME | 10 % | 0.83 |
+| High / low spillage | 0.1 | 0.80 |
+| Stable / unstable (ehull) | 0.1 eV | 0.94 |
+| High / low n-Seebeck | -100 µV K⁻¹ | 0.88 |
+| High / low p-Seebeck | 100 µV K⁻¹ | 0.92 |
+| High / low n-PF | 1000 µW (mK²)⁻¹ | 0.74 |
+| High / low p-PF | 1000 µW (mK²)⁻¹ | 0.74 |
+
+## JARVIS-DFT 2021 — regression (MAE)
+
+| Property | Units | MAD | CFID | CGCNN | ALIGNN | MAD:MAE |
+|---|---|---|---|---|---|---|
+| Formation energy | eV/atom | 0.86 | 0.14 | 0.063 | **0.033** | 26.06 |
+| Bandgap (OPT) | eV | 0.99 | 0.30 | 0.20 | **0.14** | 7.07 |
+| Total energy | eV/atom | 1.78 | 0.24 | 0.078 | **0.037** | 48.11 |
+| Ehull | eV | 1.14 | 0.22 | 0.17 | **0.076** | 15.00 |
+| Bandgap (MBJ) | eV | 1.79 | 0.53 | 0.41 | **0.31** | 5.77 |
+| Bulk modulus K_v | GPa | 52.80 | 14.12 | 14.47 | **10.40** | 5.08 |
+| Shear modulus G_v | GPa | 27.16 | 11.98 | 11.75 | **9.48** | 2.86 |
+| Magnetic moment | µB | 1.27 | 0.45 | 0.37 | **0.26** | 4.88 |
+| SLME (%) | — | 10.93 | 6.22 | 5.66 | **4.52** | 2.42 |
+| Spillage | — | 0.52 | 0.39 | 0.40 | **0.35** | 1.49 |
+| ε (DFPT: elec + ionic) | — | 45.81 | 43.71 | 38.78 | **28.15** | 1.63 |
+| Max. piezo dij | C N⁻¹ | 24.57 | 36.41 | 34.71 | **20.57** | 1.19 |
+| Exfoliation energy | meV/atom | 62.63 | 63.31 | 50.0 | **51.42** | 1.22 |
+
+(Full table in the repository README — trimmed here for readability.)
+
+## Materials Project 2018
+
+| Property | Unit | MAD | CGCNN | MEGNet | SchNet | ALIGNN |
+|---|---|---|---|---|---|---|
+| Formation energy | eV/atom | 0.93 | 0.039 | 0.028 | 0.035 | **0.022** |
+| Bandgap | eV | 1.35 | 0.388 | 0.33 | — | **0.218** |
+
+## QM9 — MAE
+
+| Target | Units | SchNet | MEGNet | DimeNet++ | ALIGNN |
+|---|---|---|---|---|---|
+| HOMO | eV | 0.041 | 0.043 | 0.0246 | **0.0214** |
+| LUMO | eV | 0.034 | 0.044 | 0.0195 | **0.0195** |
+| Gap | eV | 0.063 | 0.066 | **0.0326** | 0.0381 |
+| µ | Debye | 0.033 | 0.050 | 0.0297 | **0.0146** |
+| ZPVE | eV | 0.0017 | 0.00143 | **0.00121** | 0.0031 |
+
+!!! info "QM9 caveat"
+    See [issue #54](https://github.com/atomgptlab/alignn/issues/54) for known
+    discrepancies related to the QM9 split.
+
+## hMOF — regression
+
+| Property | Unit | MAE | R² |
+|---|---|---|---|
+| Gravimetric surface area | m² g⁻¹ | 91.15 | 0.99 |
+| Volumetric surface area | m² cm⁻³ | 107.81 | 0.91 |
+| Void fraction | — | 0.017 | 0.98 |
+| LCD | Å | 0.75 | 0.83 |
+| PLD | Å | 0.92 | 0.78 |
+| CO₂ adsorption (all) | mol kg⁻¹ | 0.18 | 0.95 |
+
+## qMOF
+
+MAE on electronic bandgap: **0.20 eV**.
+
+## Open Catalyst — IS2RE 10k
+
+| Model | CGCNN | DimeNet | SchNet | DimeNet++ | ALIGNN |
+|---|---|---|---|---|---|
+| 10k | 0.988 | 1.0117 | 1.059 | 0.8837 | **0.61** |
+
+## Coming soon
+
+OMDB, HOPV, QETB.
+
+---
+
+Claims of *best* performance should be verified on the latest
+[JARVIS-Leaderboard](https://pages.nist.gov/jarvis_leaderboard/). Numbers from models
+other than ALIGNN are reported as-published by the original authors and are not
+necessarily reproduced in-house.