【Hackathon 10th Spring No.7】wD-MPNN模型复现 RFC

rfcs/PaddleMaterials/wD-MPNN/20260420_wD-MPNN.md

@@ -0,0 +1,140 @@
+# wD-MPNN 设计文档
+
+| API名称      | 新增API名称       |
+| ------------ | ----------------- |
+| 提交作者     | 柳顺(megemini)    |
+| 提交时间     | 2026-04-20        |
+| 版本号       | V1.0.0            |
+| 依赖飞桨版本 | develop           |
+| 文件名       | 20260420_wD-MPNN.md |
+
+# 一、概述
+
+## 1、相关背景
+
+wD-MPNN (weighted directed Message Passing Neural Network) 是一种基于加权有向消息传递的图神经网络模型，用于聚合物性质预测。该模型由 Aldeghi 和 Coley 提出（论文："A graph representation of molecular ensembles for polymer property prediction", Chem. Sci. 2022, 13, 10486-10498），通过将聚合物的平均重复单元表示为分子系综图，并在边上引入有向权重，实现了对共聚物和无规共聚物等复杂聚合物结构的性质预测。
+
+## 2、功能目标
+
+本项目旨在将 wD-MPNN 模型集成至 PaddleMaterials 框架，提供模型训练、评估和推理的完整 pipeline，实现与原始 PyTorch 版本的精度对齐。
+
+## 3、意义
+
+填补飞桨生态在聚合物性质预测领域的空白
+
+# 二、飞桨现状
+
+PaddleMaterials 目前不支持 wD-MPNN 模型。
+
+# 三、业内方案调研
+
+[polymer-chemprop](https://github.com/coleygroup/polymer-chemprop) 此 REPO 提供了 PyTorch 实现，包括模型：
+
+- chemprop/models/model.py，实现了 MoleculeModel 模型（MPN 编码器 + FFN 读出网络）
+- chemprop/models/mpn.py，实现了 MPNEncoder 和 MPN 模型（加权有向消息传递网络）
+
+# 四、对比分析
+
+**PyTorch原版**：
+
+基于 PyTorch 的实现，使用 RDKit 进行分子操作。
+
+**飞桨实现**：
+
+基于 PaddlePaddle 的实现，使用 RDKit 进行分子操作。
+
+# 五、设计思路与实现方案
+
+```shell
+ppmat/
+├── datasets/
+│   ├── __init__.py
+│   ├── polymer_chemprop_dataset.py # 聚合物数据集处理类
+│   └── collate_fn.py # 数据集处理函数
+├── models/
+│   ├── polymer_chemprop/
+│   │    ├── __init__.py
+│   │    ├── featurization.py # 分子图特征化，对应 polymer-chemprop 的 chemprop/features/featurization.py
+│   │    ├── model.py # MoleculeModel 模型，对应 polymer-chemprop 的 chemprop/models/model.py
+│   │    ├── mpn.py # MPNEncoder/MPN 消息传递网络，对应 polymer-chemprop 的 chemprop/models/mpn.py
+│   │    └── nn_utils.py # 神经网络工具方法，对应 polymer-chemprop 的 chemprop/nn_utils.py
+│   └── __init__.py
+├── property_prediction/
+│   └── configs/
+│       └── polymer_chemprop/
+│           └── polymer_chemprop_delaney.yaml # 模型训练配置
+└── .pre-commit-config.yaml
+```
+
+其中：
+
+- `datasets/polymer_chemprop_dataset.py` 与 `datasets/collate_fn.py`
+
+polymer-chemprop 中的数据集处理类为 `chemprop/data/data.py`，其中定义了 `MoleculeDatapoint`、`MoleculeDataset`、`MoleculeDataLoader` 等类。本项目主要参考该文件进行适配，将数据集处理类迁移至 `datasets/polymer_chemprop_dataset.py`。
+
+`MoleculeDataLoader` 中使用 `construct_molecule_batch` 作为 collate 函数，该函数会预计算 `BatchMolGraph`。本项目将此逻辑迁移至 `datasets/collate_fn.py` 中，以适配 PaddleMaterials 的数据处理方式。
+
+- `models/polymer_chemprop/featurization.py`
+
+对应 polymer-chemprop 的 `chemprop/features/featurization.py`。
+
+- `models/polymer_chemprop/model.py`
+
+对应 polymer-chemprop 的 `chemprop/models/model.py`，迁移 `MoleculeModel` 类。
+
+- `models/polymer_chemprop/mpn.py`
+
+对应 polymer-chemprop 的 `chemprop/models/mpn.py`，迁移 `MPNEncoder` 和 `MPN` 类。
+
+- `models/polymer_chemprop/nn_utils.py`
+
+对应 polymer-chemprop 的 `chemprop/nn_utils.py`
+
+- `property_prediction/configs/polymer_chemprop/polymer_chemprop_delaney.yaml`
+
+配置模型训练参数。
+
+整体而言，转写 Paddle 的过程中没有遇到不能直接转写的情况，基本都是依赖 RDKit 进行。
+
+另外，polymer-chemprop 原项目使用 `TrainArgs` 类进行参数管理，本项目在转换到 PaddleMaterials 没有采用此种方式，以 PaddleMaterials 的普通参数方式进行参数传递。
+
+# 六、测试和验收的考量
+
+- **单元测试**：本地对模型、类、方法做必要的单元测试
+- **精度对齐**：与PyTorch原版在相同数据集上进行精度对齐
+- **集成测试**：验证与PaddleMaterials训练pipeline的兼容性
+
+**验收标准**：
+
+- 模型训练精度与PyTorch原版精度对齐
+- 模型推理精度与PyTorch原版精度对齐
+- 模型训练pipeline与PaddleMaterials训练pipeline兼容
+
+# 七、可行性分析和排期规划
+
+## 可行性分析
+
+- **技术可行性**：
+
+  使用 PaddlePaddle 代替 PyTorch 进行开发，RDKit 分子操作部分无需替换，经验证可行。
+
+- **数据可行性**：
+
+  使用 polymer-chemprop 中提供的数据进行测试，精度与 PyTorch 原版精度对齐。
+
+## 排期规划
+
+- 代码迁移，1 周
+- 集成测试，1 周
+- 精度测试，1 周
+- 其他事项，1 周
+
+# 八、影响面
+
+本项目将 wD-MPNN 集成到 PaddleMaterials 中，未引入除 RDKit 外的其他依赖。
+
+# 附件及参考资料
+
+- https://github.com/PaddlePaddle/community/blob/master/hackathon/hackathon_10th/%E3%80%90Hackathon_10th%E3%80%91%E5%BC%80%E6%BA%90%E8%B4%A1%E7%8C%AE%E4%B8%AA%E4%BA%BA%E6%8C%91%E6%88%98%E8%B5%9B%E6%98%A5%E8%8A%82%E7%89%B9%E5%88%AB%E5%AD%A3%E2%80%94%E4%BB%BB%E5%8A%A1%E5%90%88%E9%9B%86.md#no6---no19-paddlemateirals%E6%A8%A1%E5%9E%8B%E5%A4%8D%E7%8E%B0
+- https://github.com/PaddlePaddle/PaddleMaterials/issues/194
+- https://github.com/coleygroup/polymer-chemprop