Metadata-Version: 2.1
Name: ppmat
Version: 0.2.1
Summary: An AI-driven materials science toolkit based on PaddlePaddle.
Home-page: https://github.com/PaddlePaddle/PaddleMaterials
Author: PaddlePaddle
License: Apache-2.0
Project-URL: Documentation, https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/Install.md
Project-URL: Issues, https://github.com/PaddlePaddle/PaddleMaterials/issues
Project-URL: Source, https://github.com/PaddlePaddle/PaddleMaterials
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase==3.23.0
Requires-Dist: colorlog==6.8.2
Requires-Dist: hydra-core==1.3.2
Requires-Dist: einops==0.8.0
Requires-Dist: importlib-metadata==8.6.1
Requires-Dist: jarvis-tools==2025.5.30
Requires-Dist: lmdb==1.7.5
Requires-Dist: lz4==4.4.5
Requires-Dist: matminer==0.9.2
Requires-Dist: numpy==1.26.4
Requires-Dist: omegaconf==2.3.0
Requires-Dist: p-tqdm==1.4.0
Requires-Dist: packaging==25.0
Requires-Dist: pandas==2.3.0
Requires-Dist: pgl==2.2.6
Requires-Dist: Pillow==11.1.0
Requires-Dist: pyarrow==15.0.2
Requires-Dist: pymatgen==2024.10.29
Requires-Dist: pymatgen-analysis-defects==2025.1.18
Requires-Dist: pymatgen-analysis-diffusion==2024.7.15
Requires-Dist: pyparsing==3.2.3
Requires-Dist: rdkit==2024.9.1
Requires-Dist: Requests==2.32.4
Requires-Dist: scikit-learn==1.7.0
Requires-Dist: scipy==1.13.1
Requires-Dist: setuptools==68.2.2
Requires-Dist: SMACT==2.5.5
Requires-Dist: sympy==1.12.1
Requires-Dist: tensorboardX==2.6.2.2
Requires-Dist: tqdm==4.66.4
Requires-Dist: typing-extensions==4.14.0
Requires-Dist: visualdl==2.5.3
Requires-Dist: wandb==0.18.3

<!-- PyPI long description: keep repository links and image sources absolute. -->

# PaddleMaterials

<p align="center">
  <img src="https://raw.githubusercontent.com/PaddlePaddle/PaddleMaterials/develop/docs/ppmat_logo.png" alt="PaddleMaterials" width="400">
</p>

<p align="center">
  <a href="https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/Install.md">
    <img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&amp;logoColor=white">
  </a>
  <a href="https://pypi.org/project/ppmat/">
    <img alt="PyPI version" src="https://img.shields.io/pypi/v/ppmat?logo=pypi&amp;logoColor=white">
  </a>
  <a href="https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/LICENSE">
    <img alt="Apache 2.0 License" src="https://img.shields.io/github/license/PaddlePaddle/PaddleMaterials">
  </a>
  <a href="https://github.com/PaddlePaddle/PaddleMaterials/stargazers">
    <img alt="GitHub Stars" src="https://img.shields.io/github/stars/PaddlePaddle/PaddleMaterials?style=flat&amp;logo=github">
  </a>
</p>

## 🚀 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.

<p align="left">
 <img src="https://raw.githubusercontent.com/PaddlePaddle/PaddleMaterials/develop/docs/overview_en.png" align="middle" width = "1000"/>
<p align="left">

### 🧩 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](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/property_prediction/README.md) |
| **Structure Generation (SG)** | Generate new crystal structures with diffusion models | [README](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/structure_generation/README.md) |
| **Machine Learning Interatomic Potential (MLIP)** | DFT-accurate potentials for molecular dynamics | [README](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/interatomic_potentials/README.md) |
| **Electronic Structure (ES)** | Predict electronic structure properties | [README](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/electronic_structure/README.md) |
| **Spectrum Elucidation (SE)** | Reconstruct molecular structures from NMR spectra | [README](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/spectrum_elucidation/README.md) |
| **Spectrum Enhancement (SPEN)** | Enhance microscopy and spectral signals | [README](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/spectrum_enhancement/README.md) |

### 🤖 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](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/ppmat/models/__init__.py#L75)

---

## 🚀 Get Started

### 🔧 Installation

Please refer to the installation [document](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/Install.md) for your hardware environment. See [SupportedHardwareList](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/docs/multi_device.md) for more multi-hardware adaptation information.

---

### ⚡ Easy Inference

#### Property Prediction

Predict material formation energy using a pretrained MEGNet model:

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/electronic_structure/configs/infgcn/README.md#prediction) for dataset and checkpoint preparation.

#### Spectrum Elucidation

Run NMR spectrum elucidation using a pretrained DiffNMR checkpoint:

```bash
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:

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

---

### 🏋️ Start Training

For training and fine-tuning, refer to the [documentation](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/get_started.md).

---

## 🤝 Contributors & Cooperation & Community

[![Star History Chart](https://api.star-history.com/svg?repos=PaddlePaddle/PaddleMaterials&type=date&legend=top-left)](https://www.star-history.com/#PaddlePaddle/PaddleMaterials&type=date&legend=top-left)

Thanks to all contributors who have helped build PaddleMaterials！
<a href="https://github.com/PaddlePaddle/PaddleMaterials/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=PaddlePaddle/PaddleMaterials" />
</a>

Thanks for the following organiziton for cooprative support!
<p align="left">
 <img src="https://raw.githubusercontent.com/PaddlePaddle/PaddleMaterials/develop/docs/logo_SZNL_2.jpeg" align="middle" width = "180"/>
 <img src="https://raw.githubusercontent.com/PaddlePaddle/PaddleMaterials/develop/docs/logo_SinochemDI_2.jpeg" align="middle" width = "180"/>
 <img src="https://raw.githubusercontent.com/PaddlePaddle/PaddleMaterials/develop/docs/logo_MetaX.png" align="middle" width = "140"/>
<p align="left">

Join the PaddleMaterials WeChat group to discuss with us!
<p align="left">
 <img src="https://raw.githubusercontent.com/PaddlePaddle/PaddleMaterials/develop/docs/wechat_group.png" align="middle" width = "100"/>
<p align="left">

## 🛠️ Contribute to PaddleMaterials

For developer, please refer to [architecture](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/docs/ARCHITECTURE_ch.md).

---

## 📜 License

PaddleMaterials is licensed under the [Apache License 2.0](https://github.com/PaddlePaddle/PaddleMaterials/blob/develop/LICENSE).

---

## 🎓 Citation

```bibtex
@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](https://github.com/PaddlePaddle/PaddleScience) |
[Matgl](https://github.com/materialsvirtuallab/matgl) |
[CDVAE](https://github.com/txie-93/cdvae) |
[DiffCSP](https://github.com/jiaor17/DiffCSP) |
[MatterGen](https://github.com/microsoft/mattergen) |
[MatterSim](https://github.com/microsoft/mattersim) |
[CHGNet](https://github.com/CederGroupHub/chgnet) |
[AIRS](https://github.com/divelab/AIRS)
