Package: alignn
Table of ContentsIntroductionInstallationExamplesPre-trained modelsQuick start using colabJARVIS-ALIGNN webappALIGNN-FF & ASE CalculatorPeformances on a few datasetsUseful notesReferencesHow to contributeCorrespondenceFunding supportALIGNN (Introduction)The Atomistic Line Graph Neural Network (https://www.nature.com/articles/s41524-021-00650-1)  introduces a new graph convolution layer that explicitly models both two and three body interactions in atomistic systems.This is achieved by composing two edge-gated graph convolution layers, the first applied to the atomistic line graphL(g)(representing triplet interactions) and the second applied to the atomistic bond graphg(representing pair interactions).The atomistic graphgconsists of a node for each atomi(with atom/node representationshi), and one edge for each atom pair within a cutoff radius (with bond/pair representationseij).The atomistic line graphL(g)represents relationships between atom triplets: it has nodes corresponding to bonds (sharing representationseijwith those ing) and edges corresponding to bond angles (with angle/triplet representationstijk).The line graph convolution updates the triplet representations and the pair representations; the direct graph convolution further updates the pair representations and the atom representations.InstallationFirst create a conda environment:
Install miniconda environment fromhttps://conda.io/miniconda.htmlBased on your system requirements, you'll get a file something like 'Miniconda3-latest-XYZ'.Now,bash Miniconda3-latest-Linux-x86_64.sh (for linux)
bash Miniconda3-latest-MacOSX-x86_64.sh (for Mac)Download 32/64 bit python 3.10 miniconda exe and install (for windows)
Now, let's make a conda environment, say "version", choose other name as you like::conda create --name version python=3.10
source activate versionoptional GPU dependenciesIf you need CUDA support, it's best to install PyTorch and DGL before installing alignn to ensure that you get a CUDA-enabled version of DGL.To [install the stable release of PyTorch] on linux with cudatoolkit 11.8 runconda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidiaTheninstall the matching DGL versionconda install -c dglteam/label/cu118 dglSome of our models may not be stable with the latest DGL release (v1.1.0) so you may wish to install v1.0.2 instead:conda install -c dglteam/label/cu118 dgl==1.0.2.cu118Method 1 (editable in-place install)You can install a development version of alignn by cloning the repository and installing in place with pip:git clone https://github.com/usnistgov/alignn
cd alignn
python -m pip install -e .Method 2 (using pypi):As an alternate method, ALIGNN can also be installed usingpipcommand as follows:pip install alignn
pip install dgl==1.0.1+cu117 -f https://data.dgl.ai/wheels/cu117/repo.htmlExamplesDatasetThe main script to train model istrain_folder.py. A user needs at least the following info to train a model: 1)id_prop.csvwith name of the file and corresponding value, 2)config_example.jsona config file with training and hyperparameters.Users can keep their structure files inPOSCAR,.cif,.xyzor.pdbfiles in a directory. In the examples below we will use POSCAR format files. In the same directory, there should be anid_prop.csvfile.In this directory,id_prop.csv, the filenames, and correponding target values are kept incomma separated values (csv) format.Here is an example of training OptB88vdw bandgaps of 50 materials from JARVIS-DFT database. The example is created using thegenerate_sample_data_reg.pyscript. Users can modify the script for more than 50 data, or make their own dataset in this format. For list of available datasets seeDatabases.The dataset in split in 80:10:10 as training-validation-test set (controlled bytrain_ratio, val_ratio, test_ratio) . To change the split proportion and other parameters, change theconfig_example.jsonfile. If, users want to train on certain sets and val/test on another dataset, setn_train,n_val,n_testmanually in theconfig_example.jsonand also setkeep_data_orderas True there so that random shuffle is disabled.A brief help guide (-h) can be obtained as follows.train_folder.py -hRegression exampleNow, the model is trained as follows. Please increase thebatch_sizeparameter to something like 32 or 64 inconfig_example.jsonfor general trainings.train_folder.py --root_dir "alignn/examples/sample_data" --config "alignn/examples/sample_data/config_example.json" --output_dir=tempClassification exampleWhile the above example is for regression, the follwoing example shows a classification task for metal/non-metal based on the above bandgap values. We transform the dataset
into 1 or 0 based on a threshold of 0.01 eV (controlled by the parameter,classification_threshold) and train a similar classification model. Currently, the script allows binary classification tasks only.train_folder.py --root_dir "alignn/examples/sample_data" --classification_threshold 0.01 --config "alignn/examples/sample_data/config_example.json" --output_dir=tempMulti-output model exampleWhile the above example regression was for single-output values, we can train multi-output regression models as well.
An example is given below for training formation energy per atom, bandgap and total energy per atom simulataneously. The script to generate the example data is provided in the script folder of the sample_data_multi_prop. Another example of training electron and phonon density of states is provided also.train_folder.py --root_dir "alignn/examples/sample_data_multi_prop" --config "alignn/examples/sample_data/config_example.json" --output_dir=tempAutomated model trainingUsers can try training using multiple example scripts to run multiple dataset (such as JARVIS-DFT, Materials project, QM9_JCTC etc.). Look into thealignn/scripts/train_*.pyfolder. This is done primarily to make the trainings more automated rather than making folder/ csv files etc.
These scripts automatically download datasets fromDatabases in jarvis-toolsand train several models. Make sure you specify your specific queuing system details in the scripts.Using pre-trained modelsAll the trained models are distributed on [Figshare](https://figshare.com/projects/ALIGNN_models/126478.Thepretrained.py scriptcan be applied to use them. These models can be used to directly make predictions.A brief help section (-h) is shown using:pretrained.py -hAn example of prediction formation energy per atom using JARVIS-DFT dataset trained model is shown below:pretrained.py --model_name jv_formation_energy_peratom_alignn --file_format poscar --file_path alignn/examples/sample_data/POSCAR-JVASP-10.vaspQuick start using GoogleColab notebook exampleThe followingnotebookprovides an example of 1) installing ALIGNN model, 2) training the example data and 3) using the pretrained models. For this example, you don't need to install alignn package on your local computer/cluster, it requires a gmail account to login. Learn more about Google colabhere.The followingnotebookprovides an example of ALIGNN-FF model.Web-appA basic web-app is for direct-prediction available atJARVIS-ALIGNN app. Given atomistic structure in POSCAR format it predict formation energy, total energy per atom and bandgap using data trained on JARVIS-DFT dataset.ALIGNN-FFASE calculatorprovides interface to various codes. An example for ALIGNN-FF is give below. Note that there are multiple pretrained ALIGNN-FF models available, here we use the deafult_path model. As more accurate models are developed, they will be made available as well:from alignn.ff.ff import AlignnAtomwiseCalculator,default_path
model_path = default_path()
calc = AlignnAtomwiseCalculator(path=model_path)

from ase import Atom, Atoms
import numpy as np
import matplotlib.pyplot as plt

lattice_params = np.linspace(3.5, 3.8)
fcc_energies = []
ready = True
for a in lattice_params:
    atoms = Atoms([Atom('Cu', (0, 0, 0))],
                  cell=0.5 * a * np.array([[1.0, 1.0, 0.0],
                                           [0.0, 1.0, 1.0],
                                           [1.0, 0.0, 1.0]]),
                 pbc=True)

    atoms.set_tags(np.ones(len(atoms)))
    atoms.calc = calc
    e = atoms.get_potential_energy()
    fcc_energies.append(e)

import matplotlib.pyplot as plt
%matplotlib inline
plt.plot(lattice_params, fcc_energies)
plt.title('1x1x1')
plt.xlabel('Lattice constant ($\AA$)')
plt.ylabel('Total energy (eV)')
plt.show()To train ALIGNN-FF usetrain_folder_ff.pyscript which usesatomwise_alignnmodel:AtomWise prediction example which looks for similar setup as before but unstead ofid_prop.csv, it requiresid_prop.jsonfile (see example in the sample_data_ff directory). Note ALIGNN-FF requires energy stored as energy per atom:train_folder_ff.py --root_dir "alignn/examples/sample_data_ff" --config "alignn/examples/sample_data_ff/config_example_atomwise.json" --output_dir=tempA pretrained ALIGNN-FF (under active development right now) can be used for predicting several properties, such as:run_alignn_ff.py --file_path alignn/examples/sample_data/POSCAR-JVASP-10.vasp --task="unrelaxed_energy"
run_alignn_ff.py --file_path alignn/examples/sample_data/POSCAR-JVASP-10.vasp --task="optimize"
run_alignn_ff.py --file_path alignn/examples/sample_data/POSCAR-JVASP-10.vasp --task="ev_curve"To know about other tasks, type.run_alignn_ff.py -hPerformancesPlease refer toJARVIS-Leaderboardto check the performance of ALIGNN models on several databases.1) On JARVIS-DFT 2021 dataset (classification)ModelThresholdALIGNNMetal/non-metal classifier (OPT)0.01 eV0.92Metal/non-metal classifier (MBJ)0.01 eV0.92Magnetic/non-Magnetic classifier0.05 µB0.91High/low SLME10 %0.83High/low spillage0.10.80Stable/unstable (ehull)0.1 eV0.94High/low-n-Seebeck-100 µVK-10.88High/low-p-Seebeck100 µVK-10.92High/low-n-powerfactor1000 µW(mK2)-10.74High/low-p-powerfactor1000µW(mK2)-10.742) On JARVIS-DFT 2021 dataset (regression)PropertyUnitsMADCFIDCGCNNALIGNNMAD: MAEFormation   energyeV(atom)-10.860.140.0630.03326.06Bandgap (OPT)eV0.990.300.200.147.07Total   energyeV(atom)-11.780.240.0780.03748.11EhulleV1.140.220.170.07615.00Bandgap   (MBJ)eV1.790.530.410.315.77KvGPa52.8014.1214.4710.405.08GvGPa27.1611.9811.759.482.86Mag. momµB1.270.450.370.264.88SLME   (%)No   unit10.936.225.664.522.42SpillageNo unit0.520.390.400.351.49Kpoint-lengthÅ17.889.6810.609.511.88Plane-wave cutoffeV260.4139.4151.0133.81.95єx   (OPT)No   unit57.4024.8327.1720.402.81єy (OPT)No unit57.5425.0326.6219.992.88єz   (OPT)No   unit56.0324.7725.6919.572.86єx (MBJ)No unit64.4330.9629.8224.052.68єy   (MBJ)No   unit64.5529.8930.1123.652.73єz (MBJ)No unit60.8829.1830.5323.732.57є   (DFPT:elec+ionic)No   unit45.8143.7138.7828.151.63Max. piezoelectric strain coeff (dij)CN-124.5736.4134.7120.571.19Max.   piezo. stress coeff (eij)Cm-20.260.230.190.1471.77Exfoliation energymeV(atom)-162.6363.3150.051.421.22Max. EFG1021Vm-243.9024.5424.719.122.30avg. meelectron mass unit0.220.140.120.0852.59avg. mhelectron mass unit0.410.200.170.1243.31n-SeebeckµVK-1113.056.3849.3240.922.76n-PFµW(mK2)-1697.80521.54552.6442.301.58p-SeebeckµVK-1166.3362.7452.6842.423.92p-PFµW(mK2)-1691.67505.45560.8440.261.573) On Materials project 2018 datasetThe results from models other than ALIGNN are reported as given in corresponding papers, not necessarily reproduced by us.PropUnitMADCFIDCGCNNMEGNetSchNetALIGNNMAD:MAEEfeV(atom)-10.930.1040.0390.0280.0350.02242.27EgeV1.350.4340.3880.33-0.2186.194) On QM9 datasetNote theissuerelated to QM9 dataset. The results from models other than ALIGNN are reported as given in corresponding papers, not necessarily reproduced by us. These models were trained with same parameters as solid-state databases but for 1000 epochs.TargetUnitsSchNetMEGNetDimeNet++ALIGNNHOMOeV0.0410.0430.02460.0214LUMOeV0.0340.0440.01950.0195GapeV0.0630.0660.03260.0381ZPVEeV0.00170.001430.001210.0031µDebye0.0330.050.02970.0146αBohr30.2350.0810.04350.0561R2Bohr20.0730.3020.3310.5432U0eV0.0140.0120.006320.0153UeV0.0190.0130.006280.0144HeV0.0140.0120.006530.0147GeV0.0140.0120.007560.01445) On hMOF datasetPropertyUnitMADMAEMAD:MAER2RMSEGrav. surface aream2g-11430.8291.1515.700.99180.89Vol. surface aream2cm-3561.44107.815.210.91229.24Void fractionNo unit0.160.0179.410.980.03LCDÅ3.440.754.560.831.83PLDÅ3.550.923.860.782.12All adspmol kg-11.700.189.440.950.49Adsp at 0.01barmol kg-10.120.043.000.770.11Adsp at 2.5barmol kg-12.160.484.500.900.976) On qMOF datasetMAE on electronic bandgap 0.20 eV7) On OMDB datasetcoming soon!8) On HOPV datasetcoming soon!9) On QETB datasetcoming soon!10) On OpenCatalyst datasetOn 10k dataset:DataSplitCGCNNDimeNetSchNetDimeNet++ALIGNNMAD: MAE10k0.9881.01171.0590.88370.61-Useful notes (based on some of the queries we received)If you are using GPUs, make sure you have a compatible dgl-cuda version installed, for example: dgl-cu101 or dgl-cu111, so e.g.pip install dgl-cu111.While comnventional '.cif' and '.pdb' files can be read using jarvis-tools, for complex files you might have to installcif2cellandpytrajrespectively i.e.pip install cif2cell==2.0.0a3andconda install -c ambermd pytraj.Make sure you usebatch_sizeas 32 or 64 for large datasets, and not 2 as given in the example config file, else it will take much longer to train, and performnce might drop a lot.Note thattrain_folder.pyandpretrained.pyin alignn folder are actually python executable scripts. So, even if you don't provide absolute path of these scripts, they should work.Learn about the issue with QM9 results here:https://github.com/usnistgov/alignn/issues/54Make sure you havepandasversion as 1.2.3.ReferencesAtomistic Line Graph Neural Network for improved materials property predictionsPrediction of the Electron Density of States for Crystalline Compounds with Atomistic Line Graph Neural Networks (ALIGNN)Recent advances and applications of deep learning methods in materials scienceDesigning High-Tc Superconductors with BCS-inspired Screening, Density Functional Theory and Deep-learningA Deep-learning Model for Fast Prediction of Vacancy Formation in Diverse MaterialsGraph neural network predictions of metal organic framework CO2 adsorption propertiesRapid Prediction of Phonon Structure and Properties using an Atomistic Line Graph Neural Network (ALIGNN)Unified graph neural network force-field for the periodic tableLarge Scale Benchmark of Materials Design MethodsPlease see detailed publications listhere.How to contributeFor detailed instructions, please seeContribution instructionsCorrespondencePlease report bugs as Github issues (https://github.com/usnistgov/alignn/issues) or email tokamal.choudhary@nist.gov.Funding supportNIST-MGI (https://www.nist.gov/mgi).Code of conductPlease seeCode of conduct