Crystal Graph Convolutional Neural Networks (CGCNN)

To use CGCNN for training or prediction, you must organize your crystal data into a root_dir containing the following files:

1. id_prop.csv: A CSV file with two columns. The first column is a unique ID for each crystal, and the second column is the target property value. (For prediction tasks, the second column can contain placeholder/random numbers).
2. atom_init.json: A JSON file storing the initialization vector for each element. You can use data/sample-regression/atom_init.json as a template.
3. [ID].cif: One CIF file per crystal, where the filename matches the ID provided in id_prop.csv.

Directory Structure:

root_dir
├── id_prop.csv
├── atom_init.json
├── id0.cif
├── id1.cif
└── ...

When using pre-trained CGCNN models, keep the following limitations in mind to ensure accurate predictions:

1. Data Distribution Alignment: Models only generalize to crystals from the same distribution as their training data. Always check the Data Ref. (e.g., Materials Project/ICSD) associated with the model. Using a model trained on experimentally synthesized structures (like ICSD) to predict properties of imaginary or thermodynamically unstable crystals may result in significant errors.
2. Accuracy Awareness: All CGCNN models have inherent prediction errors. Consult the Model Ref. provided in the model documentation to understand the expected accuracy and error margins before relying on results.

The CGCNN model relies on material structures and properties sourced from external open datasets. Because these datasets cannot be redistributed directly, you must download them manually and convert them into the formats required by CGCNN.

The primary sources are:

• Materials Project database: https://www.materialsproject.org
• Perovskite database: https://cmr.fysik.dtu.dk/cubic_perovskites/cubic_perovskites.html

To reproduce the exact results from the original paper, use the three CSV files provided in the repository which contain the specific material IDs used in the study. Note that since the Materials Project database is updated frequently, properties and structures for the same IDs may differ from those used in the original publication.

To contribute a pre-trained model to the repository, email txie@mit.edu. Note that only peer reviewed works are accepted.

Your submission must include:

1. A .pth.tar file containing the CGCNN model.
2. The model type and the target property.
3. Links to the data reference and the model reference.

To set up the CGCNN environment, use conda to create a new environment named cgcnn with the required dependencies: pytorch, scikit-learn, torchvision, and pymatgen.

Note: This package requires PyTorch v1.0.0+ and is incompatible with versions below v0.4.0.

conda upgrade conda
conda create -n cgcnn python=3 scikit-learn pytorch torchvision pymatgen -c pytorch -c conda-forge

# Activate the environment
source activate cgcnn

The following pre-trained model is available for categorical material property prediction.

| File                        | Positive | Negative      |
| --------------------------- | -------- | ------------- |
| `semi-metal-classification` | Metal    | Semiconductor |

The following pre-trained models are available for predicting continuous material properties. Use these files to perform regression tasks on new crystal structures.

Use predict.py to estimate properties for new crystals using a pre-trained model file (.pth.tar).

Usage: python predict.py <path_to_pretrained_model> <path_to_customized_dataset_dir>

Outputs:

• test_results.csv: Stores the ID, the placeholder target value from your id_prop.csv, and the predicted value.
  • For regression, this is the predicted property.
  • For classification, this is a probability between 0 and 1 representing the likelihood of the crystal belonging to class 1.

# Predict formation energies
python predict.py pre-trained/formation-energy-per-atom.pth.tar data/sample-regression

# Predict classification (e.g., metal vs semiconductor)
python predict.py pre-trained/semi-metal-classification.pth.tar data/sample-classification

The following arguments are available in the main.py CLI interface.

--task {regression,classification}
--disable-cuda
--workers N
--epochs N
--start-epoch N
--batch-size N
--lr LR
--lr-milestones N
--momentum M
--weight-decay W
--print-freq N
--resume PATH
--train-ratio N
--train-size N
--val-ratio N
--val-size N
--test-ratio N
--test-size N
--optim {SGD,Adam}
--atom-fea-len N
--h-fea-len N
--n-conv N
--n-h N