Wider k-nearest-neighbour graph (cutoff: 8.0, max_neighbors: 12) — the more accurate choice for property prediction.

cd alignn/examples/recipes/knn
python make_toy_dataset.py                    # -> id_prop.json (40 toy entries)
train_alignn.py --root_dir . --config_name config_example.json \
    --output_dir toy_out --target_key target --id_key jid

Key knobs: cutoff: 8.0, model.output_features: 1, graphwise_weight: 1.0, calculate_gradient: false. More: recipes/knn/README.md.

Same scalar task, but the fixed-radius graph (cutoff: 5.0) that is continuous under displacement — use it when you need MD-consistency.

cd alignn/examples/recipes/radius
python make_toy_dataset.py
train_alignn.py --root_dir . --config_name config_example.json \
    --output_dir toy_out --target_key target --id_key jid

Key knobs: cutoff: 5.0 (vs 8.0 for kNN). More: recipes/radius/README.md.

Predict a fixed-length response tensor per structure. Target is a length-D list.

cd alignn/examples/recipes/tensor
python make_toy_dataset.py
train_alignn.py --root_dir . --config_name config_example.json \
    --output_dir toy_out --target_key target --id_key jid

Key knobs: set model.output_features to your tensor dimension (9/18/36) and match D in make_toy_dataset.py. More: recipes/tensor/README.md.

Predict a full curve on a fixed grid. Target is a length-D list (one per bin).

cd alignn/examples/recipes/spectra
python make_toy_dataset.py
train_alignn.py --root_dir . --config_name config_example.json \
    --output_dir toy_out --target_key target --id_key jid

Key knobs: model.output_features = number of bins (200/300); match D in the toy script. More: recipes/spectra/README.md.

Train an interatomic potential with energy-conserving (gradient) forces and stress — usable for relaxation, MD, and LAMMPS (pair_alignn).

cd alignn/examples/recipes/forcefield
python make_toy_dataset.py
train_alignn.py --root_dir . --config_name config_example.json \
    --output_dir toy_out --target_key energy_per_atom --force_key forces --id_key jid

Key knobs: model.calculate_gradient: true, and the loss mixture graphwise_weight (energy) / gradwise_weight (forces) / stresswise_weight (stress). Energy must be per atom. More: recipes/forcefield/README.md.

Predict one value per atom. Target is a length-Natoms list under a per-atom key.

cd alignn/examples/recipes/atomwise
python make_toy_dataset.py
train_alignn.py --root_dir . --config_name config_example.json \
    --output_dir toy_out --target_key target --id_key jid --atomwise_key charges

Key knobs: model.atomwise_output_features: 1, atomwise_weight: 1.0, graphwise_weight: 0.0; pass --atomwise_key charges. More: recipes/atomwise/README.md.

(a) Single-property prediction — test MAE

(b) Multi-property — spectra / per-atom / tensor; held-out MAE (col. "radius")

(c) Interatomic force fields — mlearn per-element energy/force; large sets energy / force

Pure-PyTorch path (no DGL)

• ALIGNN 2.0 runs fully in native PyTorch — set the model name to a *_pure variant (e.g. alignn_atomwise_pure) and neighbor_strategy: "pure_torch". DGL is optional.
• If you do use the legacy DGL path, install a DGL build matching your CUDA runtime; mismatched builds are the most common install failure.

Structure file parsing

• Simple .cif/.pdb are handled by jarvis-tools directly.
• For complex CIFs: pip install cif2cell==2.0.0a3. For complex PDBs: conda install -c ambermd pytraj.

Training hyperparameters

• Example configs ship with a small batch_size/epochs so tests run fast. Use batch_size: 32–64 and epochs: 100–300 for real trainings — otherwise training is slow and under-performing.
• pandas >= 1.2.3 required. Since March 2024, pytorch-ignite is no longer a dependency.

CLIs are importable scripts

• train_alignn.py, pretrained.py, and run_alignn_ff.py install as executables in your environment's bin/ — just run them by name, no absolute path needed.

Known dataset issues

• QM9: see issue #54 for a data-split discrepancy affecting reproducibility.

Getting help

• GitHub issues: https://github.com/atomgptlab/alignn/issues · Email: drkamal@jhu.edu

Core

1. Choudhary, K. & DeCost, B. Atomistic Line Graph Neural Network for improved materials property predictions. npj Computational Materials 7, 185 (2021). Link
2. Choudhary, K., DeCost, B., Major, L., Butler, K., Thiyagalingam, J., Tavazza, F. Unified graph neural network force-field for the periodic table. Digital Discovery (2023). Link

Applications

3. Prediction of the Electron Density of States for Crystalline Compounds with ALIGNN. Link
4. Recent advances and applications of deep learning methods in materials science. Link
5. Designing High-Tc Superconductors with BCS-inspired Screening, DFT, and Deep-learning. Link
6. A Deep-learning Model for Fast Prediction of Vacancy Formation in Diverse Materials. Link
7. Graph neural network predictions of MOF CO₂ adsorption properties. Link
8. Rapid Prediction of Phonon Structure and Properties using ALIGNN. Link
9. Large Scale Benchmark of Materials Design Methods. Link
10. Prediction of Magnetic Properties in van der Waals Magnets using GNNs. Link
11. CHIPS-FF: Benchmarking universal force-fields. Link

A complete list is maintained at jarvis-tools publications.