ppmat 0.2.1

An AI-driven materials science toolkit based on PaddlePaddle.

PaddleMaterials

🚀 Introduction

PaddleMaterials is an end-to-end AI4Materials toolkit built on the PaddlePaddle deep learning framework. Designed as a data-mechanism dual-driven platform for developing and deploying foundation models in materials science, PPMat enables researchers to efficiently build AI models and accelerate material discovery using pretrained models.

🧩 Core Capabilities

Task	Description	Typical Applications
Property Prediction (PP)	Predict material properties from structure	Forward design or predict formation energy, band gap, elastic moduli etc.
Structure Generation (SG)	Generate novel crystal structures	Inverse design or structure generation
Machine Learning Interatomic Potential (MLIP)	Surrogate Model for DFT as ML potentials	Molecular dynamics simulations
Electronic Structure (ES)	Surrogate Model for DFT to predict physical field	Predict electronic density
Spectrum Elucidation (SE)	Reconstruct structures from spectra	NMR structure elucidation
Spectrum Enhancement (SPEN)	Enhance microscopy and spectrum signals	STEM image enhancement, denoising

🧱 Supported Materials

• Inorganic Crystals - Well-supported with multiple datasets and pretrained models
• Organic Molecules - Support for multiple datasets and pretrained models including small molecules and partial polymers

✨ Why PaddleMaterials?

• ✅ Rich Pretrained Models & AI-ready Datasets - 50+ pretrained models ready for inference and Multiple curated datasets for training
• ✅ Multi-Task Integration - Unified framework across tasks of PP, SG, MLIP, ES, SE, SPEN etc.
• ✅ Multi-Hardware Support - Full support for NVIDIA GPUs and MetaX GPUs and Intel CPUs
• ✅ Production-Ready - Easy to use with standandlize design & distributed training, mixed precision, checkpoint recovery

📑 Support Tasks

Task	Description	Link
Property Prediction (PP)	Predict formation energy, band gap, elastic properties	README
Structure Generation (SG)	Generate new crystal structures with diffusion models	README
Machine Learning Interatomic Potential (MLIP)	DFT-accurate potentials for molecular dynamics	README
Electronic Structure (ES)	Predict electronic structure properties	README
Spectrum Elucidation (SE)	Reconstruct molecular structures from NMR spectra	README
Spectrum Enhancement (SPEN)	Enhance microscopy and spectral signals	README

🤖 Available Pretrained Models

Task	Models	Dataset
Property Prediction	MEGNet, iComformer, DimeNet++, SphereNet	MP2018, MP2024, JARVIS, QM9, etc.
Structure Generation	MatterGen, DiffCSP	MP20, ALEX, etc.
Machine Learning Interatomic Potential	CHGNet, MatterSim, SphereNet	MPTRJ, MD17, etc.
Electronic Structure	InfGCN	QM9_ES, MP_ES, OMol25_MC_ES, etc.
Spectrum Elucidation	DiffNMR	MSD_NMR, etc.
Spectrum Enhancement	SFIN	SFIN-HAADF/BF, etc.

Full model list: See MODEL_REGISTRY

---

🚀 Get Started

🔧 Installation

Please refer to the installation document for your hardware environment. See SupportedHardwareList for more multi-hardware adaptation information.

---

⚡ Easy Inference

Property Prediction

Predict material formation energy using a pretrained MEGNet model:

python property_prediction/predict.py \
    --model_name='megnet_mp2018_train_60k_e_form' \
    --weights_name='best.pdparams' \
    --cif_file_path='./property_prediction/example_data/cifs/' \
    --save_path='result.csv'

Structure Generation

Generate novel crystal structures using a pretrained MatterGen model:

python structure_generation/sample.py \
    --model_name='mattergen_mp20' \
    --weights_name='latest.pdparams' \
    --save_path='result_mattergen_mp20/' \
    --mode='by_num_atoms' \
    --num_atoms=4

Interatomic Potentials

Predict energy and forces using a pretrained MatterSim model:

python interatomic_potentials/predict.py \
    --model_name='mattersim_1M' \
    --weights_name='mattersim-v1.0.0-1M_model.pdparams' \
    --cif_file_path='./interatomic_potentials/example_data/cifs/' \
    --save_path='result.csv'

Electronic Structure

Predict electron density using a pretrained InfGCN checkpoint:

python electronic_structure/predict.py \
    --config='electronic_structure/configs/infgcn/infgcn_qm9.yaml' \
    --checkpoint='path/to/infgcn_qm9.pdparams' \
    --split='validation' \
    --index=0 \
    --output_dir='output/infgcn_qm9/validation_0' \
    --save_pred_cube

See the InfGCN prediction guide for dataset and checkpoint preparation.

Spectrum Elucidation

Run NMR spectrum elucidation using a pretrained DiffNMR checkpoint:

python spectrum_elucidation/sample.py \
    --config_path='spectrum_elucidation/configs/diffnmr/DiffNMR.yaml' \
    --checkpoint_path='path/to/DiffNMR_nless15_best.pdparams' \
    --save_path='result_diffnmr_nless15/'

Spectrum Enhancement

Enhance STEM images using a pretrained SFIN model:

python spectrum_enhancement/predict.py \
    --model_name='sfin_haadf_enhance' \
    --split='val'

---

🏋️ Start Training

For training and fine-tuning, refer to the documentation.

---

🤝 Contributors & Cooperation & Community

Thanks to all contributors who have helped build PaddleMaterials！

Thanks for the following organiziton for cooprative support!

Join the PaddleMaterials WeChat group to discuss with us!

🛠️ Contribute to PaddleMaterials

For developer, please refer to architecture.

---

📜 License

PaddleMaterials is licensed under the Apache License 2.0.

---

🎓 Citation

@misc{paddlematerials2025,
  title={PaddleMaterials, a deep learning toolkit based on PaddlePaddle for material science.},
  author={PaddleMaterials Contributors},
  howpublished = {\url{https://github.com/PaddlePaddle/PaddleMaterials}},
  year={2025}
}

---

🙏 Acknowledgements

This repository references code from the following projects:

PaddleScience | Matgl | CDVAE | DiffCSP | MatterGen | MatterSim | CHGNet | AIRS