Sovereign 8s.is mirror of standardgalactic/crystalgrw
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-05-22 14:39:23 +07:00
assets Initial commit 2025-01-15 22:47:33 -05:00
checkpoints update v1.1.1 2025-09-22 11:00:36 -04:00
conf fix a bug when embed noisy_atom_types 2026-05-22 14:39:23 +07:00
data control cpg condition with label_string, e.g. cpg_m-3m 2025-03-07 07:54:28 -05:00
scripts updated v1.1.0 2025-06-01 13:48:01 -04:00
src/crystalgrw fix a bug when embed noisy_atom_types 2026-05-22 14:39:23 +07:00
.gitignore Initial commit 2025-01-15 22:47:33 -05:00
CHANGELOG.md update v1.1.1 2025-09-22 11:00:36 -04:00
environment.yaml update compute_metrics for evaluating unique and novel 2025-03-06 21:32:51 -05:00
LICENSE Initial commit 2025-01-15 22:47:33 -05:00
pyproject.toml Initial commit 2025-01-15 22:47:33 -05:00
README.md update v1.1.1 2025-09-22 11:00:36 -04:00

CrystalGRW: Generative Modeling of Crystal Structures with Targeted Properties via Geodesic Random Walks

arXiv

Version

Current version: 1.1.1

See the CHANGELOG.md for details on updates.

Training scheme for CrystalGRW

Training scheme for CrystalGRW.

Manifolds depicted in the figure are `\mathbb{T}^2`, `\Delta^2`, and `\mathbb{R}^3`.

Sampling scheme for CrystalGRW

Sampling scheme for CrystalGRW.

Installation

git clone https://github.com/trachote/crystalgrw.git
cd crystalgrw
conda env create -f environment.yaml
conda activate crystalgrw

Usage

Training a Model

To train a model, run the following command:

python scripts/train.py --config_path conf/mp20_condition.yaml \
                        --output_path output_dir \
                        --ddp True

The Distributed Data Parallel (DDP) option is set to True for multi-GPU training. This option is available for EquiformerV2 only. GemNet-dT does not support DDP training in the current version.

Generating Crystal Structures

To generate structures, run the following command:

python scripts/evaluate.py --model_path output_dir \
                           --batch_size 8 \
                           --num_batches_to_samples 10 \
                           --adaptive_timestep 1 \
                           --save_xyz True 

Generating Crystal Structures with Guided Conditions

To generate structures guided by an input point group, run the following command:

python scripts/evaluate.py --model_path output_dir \
                           --batch_size 8 \
                           --num_batches_to_samples 10 \
                           --adaptive_timestep 1 \
                           --label_string cpg_m-3m \
                           --guidance_strength 0.5 \
                           --save_xyz True

Compute Metrics

To evaluate compositional and structural validity, uniqueness, and novelty of generated structures, run the following command:

python compute_metrics.py --root_path path/to/folder \
                          --dataset_path data/mp_20/train.csv \
                          --gen_file_name gen_file_name \
                          --n_samples 1000 \
                          --task gen

Example Runs with MP-20 Dataset

  1. Unzip data/mp_20.zip.
  2. Update paths in conf/*.yaml files by replacing path-to-folder/crystalgrw with pwd.
    • conf/mp20_example.yaml: Configuration for training the model.
    • conf/mp20_condition.yaml: Configuration for training with controlled conditions.
  3. Train the model using the Training a Model command.

Configurations

CrystalGRW can choose to corrupt either of three crystal properties:

  • fractional coordinates
  • atomic types
  • lattice matrices

Depending on the specific task, you may want to alter only some of these properties. Adjust the settings in the configuration file by modifying the corrupt_{property} tags in file conf/*.yaml accordingly.

Pretrained Models

To use pretrained models, download them using the following command

git lfs pull -I checkpoints/<model-name>

Generating structures from pretrained models

  1. Once downloaded, edit the PROJECT_ROOT path in hparams.yaml file to point to your local project directory.
  2. pretrained_alexmp20_2025-04-15 a model trained on ALEX-MP-20 dataset, use the Generating Crystal Structures command to generate structures.
  3. pretrained_alexmp20_pointgroups_2025-04-18 a model trained on ALEX-MP-20 dataset and conditioned on point groups, use the Generating Structures with Guided Conditions command to generate structures.

Models trained on the MP-20 dataset can be downloaded from the following link: https://zenodo.org/records/14948252.

Citations

If you use CrystalGRW in your research, please cite:

@misc{tangsongcharoen2025crystalgrw,
      title={CrystalGRW: Generative Modeling of Crystal Structures with Targeted Properties via Geodesic Random Walks}, 
      author={Krit Tangsongcharoen and Teerachote Pakornchote and Chayanon Atthapak and Natthaphon Choomphon-anomakhun and Annop Ektarawong and Björn Alling and Christopher Sutton and Thiti Bovornratanaraks and Thiparat Chotibut},
      year={2025},
      eprint={2501.08998},
      archivePrefix={arXiv},
      primaryClass={cond-mat.mtrl-sci},
      url={https://arxiv.org/abs/2501.08998}, 
}

GNN submodules

Two options for the denoiser (decoder)

  1. EquiformerV2
@inproceedings{
liao2024equiformerv,
title={EquiformerV2: Improved Equivariant Transformer for Scaling to Higher-Degree Representations},
author={Yi-Lun Liao and Brandon M Wood and Abhishek Das and Tess Smidt},
booktitle={The Twelfth International Conference on Learning Representations},
year={2024},
url={https://openreview.net/forum?id=mCOBKZmrzD}
}
  1. GemNet-dT
@inproceedings{
klicpera2021gemnet,
title={GemNet: Universal Directional Graph Neural Networks for Molecules},
author={Johannes Klicpera and Florian Becker and Stephan G{\"u}nnemann},
booktitle={Advances in Neural Information Processing Systems},
editor={A. Beygelzimer and Y. Dauphin and P. Liang and J. Wortman Vaughan},
year={2021},
url={https://openreview.net/forum?id=HS_sOaxS9K-}
}

One option for the encoder (if used)
3) DimeNet++

@misc{gasteiger2022fast,
      title={Fast and Uncertainty-Aware Directional Message Passing for Non-Equilibrium Molecules}, 
      author={Johannes Gasteiger and Shankari Giri and Johannes T. Margraf and Stephan Günnemann},
      year={2022},
      eprint={2011.14115},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}