README.md

---
library_name: pytorch
tags:
- diffusion
- drug-discovery
- structure-based-drug-design
- molecule-generation
- chemistry
---
<h1 align="center">NucleusDiff</h1>

<h3 align="center">
  Manifold-Constrained Nucleus-Level Denoising Diffusion Model<br />
  for Structure-Based Drug Design
</h3>

<p align="center">
  <strong>Official pretrained checkpoint and data artifacts for the PNAS 2025 paper.</strong>
</p>

<p align="center">
  <a href="https://www.caltech.edu/about/news/new-ai-model-for-drug-design-brings-more-physics-to-bear-in-predictions"><img src="https://img.shields.io/badge/Caltech-News-FF6C0C" alt="Caltech News" /></a>
  <a href="https://yanliang3612.github.io/NucleusDiff/"><img src="https://img.shields.io/badge/Project-Page-0A66C2?logo=githubpages&amp;logoColor=white" alt="Project Page" /></a>
  <a href="https://www.pnas.org/doi/10.1073/pnas.2415666122"><img src="https://img.shields.io/badge/Paper-PNAS-B31B1B" alt="PNAS Paper" /></a>
  <a href="https://arxiv.org/abs/2409.10584"><img src="https://img.shields.io/badge/arXiv-2409.10584-B31B1B?logo=arxiv&amp;logoColor=white" alt="arXiv" /></a>
  <a href="https://github.com/yanliang3612/NucleusDiff"><img src="https://img.shields.io/badge/GitHub-Source_Code-181717?logo=github&amp;logoColor=white" alt="Source code" /></a>
  <a href="https://doi.org/10.5281/zenodo.17093932"><img src="https://img.shields.io/badge/DOI-Zenodo-1682D4?logo=zenodo&amp;logoColor=white" alt="Zenodo DOI" /></a>
  <a href="https://join.slack.com/t/matdiscoverai/shared_invite/zt-32kktcuk0-XaaJT2P9qZTfNdaCzJUGAg"><img src="https://img.shields.io/badge/Slack-Join_SciGenAI-4A154B?logo=slack&amp;logoColor=white" alt="Join SciGenAI on Slack" /></a>
</p>

<p align="center">
  <a href="https://join.slack.com/t/matdiscoverai/shared_invite/zt-32kktcuk0-XaaJT2P9qZTfNdaCzJUGAg">
    <img src="https://readme-typing-svg.demolab.com?font=Inter&amp;weight=700&amp;size=18&amp;pause=1200&amp;color=0A66C2&amp;center=true&amp;vCenter=true&amp;width=900&amp;lines=Official+NucleusDiff+model+%26+data+artifacts;Physics-informed+diffusion+for+structure-based+drug+design;Join+SciGenAI+for+Q%26A%2C+collaboration+%26+code+contributions" alt="NucleusDiff model, data, and community" />
  </a>
</p>

<p align="center">
  Shengchao Liu<sup>*</sup>, Liang Yan<sup>*</sup>, Weitao Du, Weiyang Liu, Zhuoxinran Li, Hongyu Guo,<br />
  Christian Borgs, Jennifer Chayes, Anima Anandkumar
</p>

<p align="center">
  <strong>Proceedings of the National Academy of Sciences (PNAS), 2025</strong><br />
  <sup>*</sup>Equal contribution
</p>

---

## ✨ Overview

NucleusDiff is a physics-informed diffusion model for structure-based drug design. It constrains generated atomic nuclei with sampled points on electron-cloud manifolds, incorporating van der Waals spatial boundaries to reduce atomic collisions while preserving strong binding affinity.

This Hugging Face repository is the official mirror for the pretrained checkpoint and project data artifacts. For installation, training, inference, and evaluation, see the [NucleusDiff source repository](https://github.com/yanliang3612/NucleusDiff#readme).

## 📦 Repository Contents

| Resource | Location | Description |
|---|---|---|
| 🧠 Pretrained model | [`model/`](https://huggingface.co/LiangYan3612/NucleusDiff/tree/main/model) | Official NucleusDiff checkpoint |
| 🧬 Project data | [`data/`](https://huggingface.co/LiangYan3612/NucleusDiff/tree/main/data) | Training, evaluation, and therapeutic-target artifacts |
| 💻 Implementation | [GitHub](https://github.com/yanliang3612/NucleusDiff) | Source code, configuration, and usage instructions |

### Model

- `model/nucleusdiff_pretrained_model.pt` — pretrained NucleusDiff checkpoint.

### Data

- `data/crossdocked_v1.1_rmsd1.0_pocket10_processed_w_manifold_data_version.lmdb` — preprocessed CrossDocked manifold dataset.
- `data/crossdocked_pocket10_pose_w_manifold_data_split.pt` — train/validation/test split used by NucleusDiff.
- `data/crossdocked_v1.1_rmsd1.0.tar.gz` — filtered CrossDocked data.
- `data/split_by_name.pt` — reference CrossDocked split.
- `data/test_set.zip` — protein test set used for docking evaluation.
- `data/real_world.zip` — therapeutic-target evaluation data.
- `data/affinity_info.pkl` — affinity metadata.
- `data/test_vina_crossdock_dict.pkl` — CrossDocked Vina evaluation metadata.

## ⬇️ Download

Install or update the Hugging Face CLI:

```bash
pip install -U huggingface_hub
```

Download only the pretrained model:

```bash
hf download LiangYan3612/NucleusDiff \
  --include "model/*" \
  --local-dir ./NucleusDiff_artifacts
```

Download all data files:

```bash
hf download LiangYan3612/NucleusDiff \
  --include "data/*" \
  --local-dir ./NucleusDiff_artifacts
```

Download the complete model-and-data snapshot:

```bash
hf download LiangYan3612/NucleusDiff \
  --local-dir ./NucleusDiff_artifacts
```

## 💬 Community

Join the [SciGenAI Slack community](https://join.slack.com/t/matdiscoverai/shared_invite/zt-32kktcuk0-XaaJT2P9qZTfNdaCzJUGAg) for the dedicated NucleusDiff channel, real-time questions, code contributions, pull requests, and collaboration across generative AI for science.

## 📜 License and Data Provenance

The NucleusDiff source code is released under the [MIT License](https://github.com/yanliang3612/NucleusDiff/blob/main/LICENSE). Included data artifacts are mirrors of the files used by the project and may remain subject to the terms of their original data sources.

## 📖 Citation

```bibtex
@article{liu2025manifold,
  title={Manifold-constrained nucleus-level denoising diffusion model for structure-based drug design},
  author={Liu, Shengchao and Yan, Liang and Du, Weitao and Liu, Weiyang and Li, Zhuoxinran and Guo, Hongyu and Borgs, Christian and Chayes, Jennifer and Anandkumar, Anima},
  journal={Proceedings of the National Academy of Sciences},
  volume={122},
  number={41},
  pages={e2415666122},
  year={2025},
  publisher={National Academy of Sciences}
}
```