Simplified Line-Input Crystal-Encoding System

This software implementes Simplified Line-Input Crystal-Encoding System (SLICES), the first invertible and invariant crystal representation.

It has several main functionalities:

• Encode crystal structures into SLICES strings
• Reconstruct original crystal structures from their SLICES strings (Text2Crystal)
• Generate crystals with desired properties using conditional RNN (Inverse Design)

Developed by Hang Xiao 2023.04 xiaohang07@live.cn

Nature Communications [Paper] [SLICES晶体语言视频介绍][SLICES101] [Data/Results][Source code]

We provide a huggingface space to allow one-click conversion of CIF to SLICES and SLICES to CIF online.

[Online SLICES/CIF Convertor]

MatterGPT

[Paper] [MatterGPT Online Demo] [视频简介][视频教程]

Table of Contents

• Installation
• Examples
  • Crystal to SLICES and SLICES to crystal
  • Augment SLICES and canonicalize SLICES
• SLICES视频教程
• MatterGPT视频教程
• Tutorials
  • Video Tutorials
  • Jupyter backend setup
  • Tutorial 1.0 Examples
  • Tutorial 2.1 MatterGPT for Single-Property (eform) Material Inverse Design
  • Tutorial 2.2 MatterGPT for Single-Property (bandgap) Material Inverse Design
  • Tutorial 2.3 MatterGPT for Multi-Property (bandgap&eform) Material Inverse Design
• Documentation
• Reproduction of benchmarks
• Citation
• Contact

Installation

# pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple (use this if you are in China)
conda env create --name slices --file=environments.yml
conda activate slices
pip install slices==2.0.2
#If you're in China, use this command instead: "pip install slices -i https://pypi.tuna.tsinghua.edu.cn/simple".

Please note that this installtion method is intended for Linux operating systems like Ubuntu and CentOS. Unfortunately, SLICES is not directly compatible with Windows or MacOS due to the modified XTB binary was compiled on Linux. To run SLICES on Windows or MacOS, one can run SLICES with docker, referring to Jupyter backend setup.

If "TypeError: bases must be types" occurs when you use SLICES library, then do this:

pip install protobuf==3.20.0

If errors still occur, then you can run SLICES with docker, referring to Jupyter backend setup.

Examples

Crystal to SLICES and SLICES to crystal

Converting a crystal structure to its SLICES string and converting this SLICES string back to its original crystal structure. Suppose we wish to convert the crystal structure of NdSiRu (mp-5239,https://next-gen.materialsproject.org/materials/mp-5239?material_ids=mp-5239) to its SLICES string and converting this SLICES string back to its original crystal structure. The python code below accomplishes this:

from slices.core import SLICES
from pymatgen.core.structure import Structure
# obtaining the pymatgen Structure instance of NdSiRu
original_structure = Structure.from_file(filename='NdSiRu.cif')
# creating an instance of the InvCryRep Class (initialization)
backend=SLICES()
# converting a crystal structure to its SLICES string
slices_NdSiRu=backend.structure2SLICES(original_structure) 
# converting a SLICES string back to its original crystal structure and obtaining its M3GNet_IAP-predicted energy_per_atom
reconstructed_structure,final_energy_per_atom_IAP = backend.SLICES2structure(slices_NdSiRu)
print('SLICES string of NdSiRu is: ',slices_NdSiRu)
print('\nReconstructed_structure is: ',reconstructed_structure)
print('\nfinal_energy_per_atom_IAP is: ',final_energy_per_atom_IAP,' eV/atom')
# if final_energy_per_atom_IAP is 0, it means the M3GNet_IAP refinement failed, and the reconstructed_structure is the ZL*-optimized structure.

Augment SLICES and canonicalize SLICES

Converting a crystal structure to its SLICES string and perform data augmentation (50x), then reduce these 50 SLICES to 1 canonical SLICES with get_canonical_SLICES.

from slices.core import SLICES
from pymatgen.core.structure import Structure
from pymatgen.analysis.structure_matcher import StructureMatcher, ElementComparator
# obtaining the pymatgen Structure instance of Sr3Ru2O7
original_structure = Structure.from_file(filename='Sr3Ru2O7.cif')
# creating an instance of the InvCryRep Class (initialization)
backend=SLICES(graph_method='econnn')
# converting a crystal structure to its SLICES string and perform data augmentation (50x)
slices_list=backend.structure2SLICESAug_atom_order(structure=original_structure,num=50) 
slices_list_unique=list(set(slices_list))
cannon_slices_list=[]
for i in slices_list_unique:
    cannon_slices_list.append(backend.get_canonical_SLICES(i))
# test get_canonical_SLICES
print(len(slices_list),len(set(cannon_slices_list)))
# 50 SLICES generated by data augmentation has been reduced to 1 canonical SLICES

SLICES视频教程

MatterGPT视频教程

Tutorials

Video Tutorials

Jupyter backend setup

(1) Download this repo and unzipped it.

(2) Put Materials Project's new API key in "APIKEY.ini".

(3) Edit "CPUs" in "slurm.conf" to set up the number of CPU threads available for the docker container.

(4) Run following commands in terminal (Linux or WSL2 Ubuntu on Win11)

# Download SLICES_docker with pre-installed SLICES and other relevant packages. 
docker pull xiaohang07/slices:v9  
# you can build your own docker image using the Dockerfile in this repo. Many thanks to Prof. Haidi Wang (https://haidi-ustc.github.io/about/) for the Dockerfile.
# You can download the compressed docker image v9 at https://figshare.com/s/260701a1accd0192de20 if docker pull does not work. 
# Then you can load this docker image using the following command: 
xz -dc slices_v9.tar.xz | docker load
# Make entrypoint_set_cpus.sh executable 
sudo chmod +x entrypoint_set_cpus_jupyter.sh ./slices/xtb_noring_nooutput_nostdout_noCN
# Repalce "[]" with the absolute path of this repo's unzipped folder to setup share folder for the docker container.
# e.g. for windows cmd: -v C:\Users\admin\Desktop\SLICES-main:/crystal
# e.g. for windows wsl: -v /mnt/c/Users/admin/Desktop/SLICES-main:/crystal
# e.g. for linux: -v /home/admin/Desktop/SLICES-main:/crystal
docker run -it -p 8888:8888 -h workq  --shm-size=0.5gb --gpus all -v /[]:/crystal xiaohang07/slices:v9 /crystal/entrypoint_set_cpus_jupyter.sh

Please note: The best way to run this project is using Docker on Windows 11, as this allows you to utilize GPU for model training directly within Docker containers. In contrast, when running Docker on Ubuntu, accessing GPU from within Docker containers has proven problematic (verified across multiple machines). Therefore, on Ubuntu systems, a hybrid approach is required: install PyTorch directly on the host machine for training MatterGPT models and generating SLICES, while other steps can be run in Docker. 请注意：在所有操作系统中，运行此项目的最佳方式是使用 Windows 11 的 Docker 环境，因为它能够让你在 Docker 容器内直接调用 GPU 来训练模型。相比之下，在 Ubuntu 系统中运行 Docker 时会遇到 GPU 调用的问题（经过多台计算机测试验证），因此在 Ubuntu 上需要采用混合方案：在本机直接安装 PyTorch 来训练 MatterGPT 模型和生成 SLICES，而其他步骤则可以在 Docker 容器中完成。 *(5) Press CTRL (or Command on Mac) and click the link that starts with http://127.0.0.1 in your terminal (highlighted in yellow in the image below). This will open the Jupyter notebook in your web browser. Click on the Tutorial_.ipynb file to load the relevant tutorial notebook.**

Tutorial 1.0 Examples

Tutorial 2.1 MatterGPT for Single-Property (eform) Material Inverse Design

Tutorial 2.2 MatterGPT for Single-Property (bandgap) Material Inverse Design

Tutorial 2.3 MatterGPT for Multi-Property (bandgap&eform) Material Inverse Design

Documentation

The SLICES documentation is hosted at read-the-docs.

Reproduction of benchmarks

For detailed instructions on reproducing benchmarks, please refer to the benchmarks documentation.

Citation

Please consider citing the following paper if you find our code & data useful.

@article{xiao2023invertible,
  title={An invertible, invariant crystal representation for inverse design of solid-state materials using generative deep learning},
  author={Xiao, Hang and Li, Rong and Shi, Xiaoyang and Chen, Yan and Zhu, Liangliang and Chen, Xi and Wang, Lei},
  journal={Nature Communications},
  volume={14},
  number={1},
  pages={7027},
  year={2023},
  publisher={Nature Publishing Group UK London}
}

@misc{chen2024mattergptgenerativetransformermultiproperty,
      title={MatterGPT: A Generative Transformer for Multi-Property Inverse Design of Solid-State Materials}, 
      author={Yan Chen and Xueru Wang and Xiaobin Deng and Yilun Liu and Xi Chen and Yunwei Zhang and Lei Wang and Hang Xiao},
      year={2024},
      eprint={2408.07608},
      archivePrefix={arXiv},
      primaryClass={cond-mat.mtrl-sci},
      url={https://arxiv.org/abs/2408.07608}, 
}

Acknowledgement

During the development process, I referenced and drew inspiration from several excellent open source projects and related resources. I would like to express special thanks to the developers of these projects and the contributions of the open source community. The main projects we referenced are:

• tobascco
• xtb
• m3gnet
• chgnet
• molgpt

Contact and Support

Start a new discussion thread in [Discussion], or reach out to Hang Xiao (https://www.researchgate.net/profile/Hang-Xiao-8) xiaohang07@live.cn if you have any questions.