Skip to content

Commit be1a22e

Browse files
knc6knc6
committed
New README
1 parent b5363a7 commit be1a22e

1 file changed

Lines changed: 169 additions & 0 deletions

File tree

‎alignn/README2.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
![Build Status](https://github.com/usnistgov/alignn/actions/workflows/main.yml/badge.svg)
2+
[![codecov](https://codecov.io/gh/usnistgov/alignn/branch/main/graph/badge.svg?token=S5X4OYC80V)](https://codecov.io/gh/usnistgov/alignn)
3+
[![PyPI version](https://badge.fury.io/py/alignn.svg)](https://badge.fury.io/py/alignn)
4+
![Latest GitHub Tag](https://img.shields.io/github/v/tag/usnistgov/alignn)
5+
![Code Size](https://img.shields.io/github/languages/code-size/usnistgov/alignn)
6+
![Commit Activity](https://img.shields.io/github/commit-activity/y/usnistgov/alignn)
7+
[![Downloads](https://pepy.tech/badge/alignn)](https://pepy.tech/project/alignn)
8+
9+
# ALIGNN & ALIGNN-FF
10+
11+
## Overview
12+
13+
The Atomistic Line Graph Neural Network (ALIGNN) introduces a novel graph convolution layer that captures both two-body and three-body interactions in atomistic systems, enhancing materials property prediction. ALIGNN uses a composition of two edge-gated graph convolutions: one on the atomistic line graph (triplet interactions), and one on the bond graph (pairwise interactions).
14+
15+
ALIGNN-FF is an extension tailored to force field modeling, trained on the JARVIS-DFT dataset (~75,000 materials and 4 million entries), supporting 89 elements for structural and chemical diversity. Users can fine-tune existing models or train from scratch on custom datasets.
16+
17+
![ALIGNN Layer Diagram](https://github.com/usnistgov/alignn/blob/develop/alignn/tex/schematic_lg.jpg)
18+
19+
## Table of Contents
20+
- [Installation](#installation)
21+
- [Examples](#examples)
22+
- [Pre-trained Models](#pretrained-models)
23+
- [Web Applications](#web-applications)
24+
- [ALIGNN-FF & ASE Calculator](#alignn-ff--ase-calculator)
25+
- [Performance Benchmarks](#performance-benchmarks)
26+
- [Notes & Tips](#notes--tips)
27+
- [References](#references)
28+
- [Contribution Guide](#contribution-guide)
29+
- [Contact](#contact)
30+
- [Funding](#funding)
31+
32+
---
33+
34+
## Installation
35+
36+
You can install ALIGNN using GitHub (development), PyPI with `uv`, or via Conda/Miniforge.
37+
38+
### Step 1: Install Miniforge (Recommended Python Environment)
39+
Download Miniforge installer from: https://github.com/conda-forge/miniforge
40+
Choose the installer matching your OS (e.g., `Miniforge3-MacOSX-arm64.sh` or `Miniforge3-Linux-x86_64.sh`).
41+
42+
```bash
43+
bash Miniforge3-MacOSX-arm64.sh # or your platform-specific file
44+
```
45+
46+
### Method 1: GitHub (Development Version)
47+
```bash
48+
git clone https://github.com/usnistgov/alignn
49+
cd alignn
50+
pip install -e .
51+
```
52+
53+
### Method 2: PyPI Installation using `uv` (Recommended)
54+
55+
```bash
56+
!pip install uv
57+
!uv venv .venv --python 3.10
58+
!source .venv/bin/activate
59+
!pip install -q alignn
60+
```
61+
62+
Ensure that you install the correct `dgl` version beforehand, compatible with your CUDA version. For example:
63+
64+
```bash
65+
pip install dgl -f https://data.dgl.ai/wheels/torch-2.1/cu121/repo.html # For CUDA 12.1
66+
```
67+
68+
For CPU-only systems:
69+
```bash
70+
pip install dgl -f https://data.dgl.ai/wheels/torch-2.1/repo.html
71+
```
72+
73+
---
74+
75+
## Examples
76+
77+
ALIGNN provides a suite of Google Colab notebooks showcasing various use cases:
78+
79+
| Task | Link | Description |
80+
|------|------|-------------|
81+
| Regression | [Notebook](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/alignn_jarvis_leaderboard.ipynb) | Single-output regression (e.g., exfoliation energy). |
82+
| ML Force Field | [Notebook](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/Train_ALIGNNFF_Mlearn.ipynb) | Train MLFF from scratch for Si. |
83+
| Relaxation + Phonons | [Notebook](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/ALIGNN_Structure_Relaxation_Phonons_Interface.ipynb) | Use pre-trained ALIGNN-FF. |
84+
| Scaling | [Notebook](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/Timing_uMLFF.ipynb) | Timing analysis. |
85+
| Amorphous Structures | [Notebook](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/Fast_Melt_Quench.ipynb) | Melt-quench MD simulation. |
86+
| Misc Tasks | [Notebook](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/Training_ALIGNN_model_example.ipynb) | Training multiple regression/classification models. |
87+
88+
---
89+
90+
## Pretrained Models
91+
92+
Pre-trained ALIGNN and ALIGNN-FF models are hosted on [Figshare](https://figshare.com/projects/ALIGNN_models/126478). You can use them for fast inference with the provided scripts:
93+
94+
```bash
95+
pretrained.py --model_name jv_formation_energy_peratom_alignn --file_format poscar --file_path POSCAR.vasp
96+
```
97+
98+
For ALIGNN-FF:
99+
```bash
100+
run_alignn_ff.py --file_path POSCAR.vasp --task="optimize"
101+
```
102+
103+
---
104+
105+
## Web Applications
106+
107+
1. [JARVIS-ALIGNN Web App](https://jarvis.nist.gov/jalignn/): Predict formation energy, total energy, bandgap.
108+
2. [JARVIS-ALIGNN-FF App](https://jarvis.nist.gov/jalignnff/): Perform structure relaxations online.
109+
110+
---
111+
112+
## ALIGNN-FF & ASE Calculator
113+
114+
ALIGNN-FF integrates with ASE for tasks like structure optimization, energy-volume curves, and phonon calculations. A full script example is included in the documentation above.
115+
116+
---
117+
118+
## Performance Benchmarks
119+
120+
ALIGNN achieves state-of-the-art performance on JARVIS-DFT, Materials Project, QM9, and other datasets. See:
121+
- [JARVIS-Leaderboard](https://pages.nist.gov/jarvis_leaderboard/)
122+
- Specific tables in documentation for detailed metrics (classification/regression).
123+
124+
---
125+
126+
## Notes & Tips
127+
128+
- Install correct DGL-CUDA version for GPU support.
129+
- Use batch size >32 for large datasets.
130+
- `train_alignn.py` and `pretrained.py` are CLI tools.
131+
- Pandas >1.2.3 required.
132+
- Multi-GPU supported with `torchrun`.
133+
- PyTorch Ignite dependency removed (as of March 2024).
134+
135+
---
136+
137+
## References
138+
139+
1. https://www.nature.com/articles/s41524-021-00650-1
140+
2. https://pubs.rsc.org/en/content/articlehtml/2023/dd/d2dd00096b
141+
3. Full publication list: https://jarvis-tools.readthedocs.io/en/master/publications.html
142+
143+
---
144+
145+
## Contribution Guide
146+
147+
Please see: [How to Contribute](https://github.com/usnistgov/jarvis/blob/master/Contribution.rst)
148+
149+
---
150+
151+
## Contact
152+
153+
- Report issues: [GitHub Issues](https://github.com/usnistgov/alignn/issues)
154+
- Email: kamal.choudhary@nist.gov
155+
156+
---
157+
158+
## Funding
159+
160+
- [NIST-MGI](https://www.nist.gov/mgi)
161+
- [NIST-CHIPS](https://www.nist.gov/chips)
162+
163+
---
164+
165+
## Code of Conduct
166+
167+
Please review: [Code of Conduct](https://github.com/usnistgov/jarvis/blob/master/CODE_OF_CONDUCT.md)
168+
169+

0 commit comments

Comments
 (0)
⚡