Skip to content

Notice: 开发者贡献指南(Draft) #258

Open
Open
Notice: 开发者贡献指南(Draft)#258
@leeleolay

Description

@leeleolay
leeleolay
opened on Mar 30, 2026

Contributing to PaddleMaterials

感谢你对 PaddleMaterials 的关注与贡献！

1. 开发原则

提交到 PaddleMaterials 的代码，不仅需要能跑，还需要满足以下项目要求：

  1. 符合仓库现有任务划分与目录结构
  2. 符合 repo 已有代码逻辑和调用风格
  3. 按照 README 可以完成主要流程
  4. 文档与代码实现保持一致
  5. 优先保证可维护、可复现、可扩展

对于复现类 PR，本项目更关注：

  • 是否接入到了正确的任务目录
  • 是否沿用了 PaddleMaterials 现有的数据流、配置流和入口脚本
  • 是否补齐了 README、配置、测试
  • 是否与现有模块风格一致

2. 仓库结构与放置规范

请严格按照仓库现有结构放置代码，不要随意新建平行体系。

当前主要任务目录包括：

  • interatomic_potentials/：任务-机器学习原子间势函数（MLIP）
  • electronic_structure/：任务-机器学习电子结构（MLES）
  • property_prediction/：任务-性质预测（PP）
  • structure_generation/：任务-结构生成（SG）
  • spectrum_elucidation/：任务-谱图解析（SE）
  • ppmat/：公共模型、数据集、模块、工具实现
  • test/：项目级测试
  • docs/：项目文档

2.1 新模型接入

新增模型时，一般应至少涉及以下位置中的一部分：

  • ppmat/models/：模型主体实现
  • 对应任务目录下的 configs/<model_name>/：模型配置与 README
  • 对应任务目录下的训练 / 测试 / 推理入口适配
  • 必要时补充 test/ 下测试

不要把完整模型逻辑直接堆在任务脚本里，也不要绕开 ppmat 现有抽象单独再造一套训练框架。
当前套件未实现统一predictor或sampler，每一个单独任务下暂时存放有单独的predictor或sampler实现，建议参考当前任务中已有的实现。
如当前推理器或采样器不满足拟定合入模型的功能实现，建议针对已有的进行功能改造和升级，并且要对相关的模型做测试。

Notes:未来会对 predictor / sampler 进行重构，届时将统一封装模型推理逻辑。

2.2 新数据集接入

新增数据集时，一般应放在：

  • ppmat/datasets/

要求尽量复用现有 dataset 风格，保持：

  • 初始化参数风格一致
  • 数据划分逻辑清晰
  • 字段命名清晰
  • 与现有 dataloader / collate / transform 兼容
  • 使用工厂函数的方式封装数据集加载逻辑

数据集适配类 PR 应优先参考仓库已有数据集实现，而不是直接照搬外部仓库写法。
如果已有工厂函数或工具类或数据处理逻辑可以复用，请优先使用现有封装。
如果不满足现有封装，请在 ppmat/datasets/ 下新建文件夹存放。

Notes:未来会对工厂函数进行重构，届时将统一封装数据集加载逻辑。

2.3 工具脚本与转换脚本

tests/ 或任务目录下的工具脚本，只应放置：

  • 用户需要明确调用的正式工具
  • 权重转换、评测、对齐等确有长期维护意义的脚本

不应提交：

  • 临时调试脚本
  • 只在作者本地环境下可用的脚本
  • 含硬编码路径的实验脚本
  • 一次性对齐脚本但没有说明文档的文件

3. PaddleMaterials 特定要求

3.1 必须沿用仓库已有入口与组织方式

新增内容应尽量接入现有流程，而不是另起炉灶。包括但不限于：

  • 训练入口
  • 推理入口
  • 配置组织方式
  • 数据集注册 / 调用方式
  • 模型调用接口

如果现有任务目录已经存在同类模型或同类任务，请优先对齐该目录下已有实现。

例如：

  • 晶体/分子性质预测任务，优先参考 property_prediction/ 下已有模型与配置组织
  • 机器学习原子间势函数任务，优先参考 interatomic_potentials/ 下已有模型与 README 组织
  • 数据集适配，优先参考 ppmat/datasets/ 中已有实现

3.2 不接受仓库外风格强行迁入

来自其他框架或其他仓库的代码，不能简单复制后直接提交。
必须完成 PaddleMaterials 风格适配，包括：

  • 参数组织方式统一
  • 配置命名方式统一
  • 训练 / 推理 / 采样接口统一
  • 文档风格统一
  • PaddlePaddle 代码风格统一

3.3 使用 Paddle 官方正式版本

  • 必须使用 PaddlePaddle 官方正式发布版本
  • 不得依赖 develop 版本
  • 若对 Paddle 版本有最低要求，需在 README 中明确写明
  • 若依赖特定 CUDA、Python 版本，也应一并说明

对于 PR 验收，若代码只能在 develop 版本下运行，一般不视为满足合入条件。

3.4 README 与文档要求

PaddleMaterials 的贡献，尤其是模型复现类和数据集适配类 PR，必须保证 README 可用。
基本要求如下：

3.4.1 README 至少应包含

  1. 任务简介
  2. 模型 / 数据集简介
  3. 数据准备方式
  4. 环境依赖
  5. 训练命令
  6. 评测命令
  7. 推理命令（如适用）
  8. 关键配置说明
  9. 参考结果
  10. 参考论文或来源链接

3.4.2 README 必须满足

  • 按照 README 操作，可以完成主要流程
  • 文档与代码一致
  • 命令能直接复制运行，避免隐式前置条件
  • 不省略关键步骤
  • 不允许 README 写一套、代码实现另一套

3.4.3 复现结果说明

对于模型复现类 PR，建议在 README 中写清：

  • 复现目标
  • 所用数据集版本
  • 关键超参数
  • 训练轮数 / batch size / 学习率
  • 评测指标
  • 与原论文或参考实现的结果对比
  • 偏差范围与原因说明（如有）

若暂时无法完整对齐原论文结果，也应明确说明当前完成到什么程度，而不是模糊表述“支持该模型”。

3.5. 配置文件要求

配置文件应与 PaddleMaterials 现有风格保持一致。

3.5.1 配置内容应清晰完整

至少建议包含：

  • model
  • dataset
  • dataloader
  • optimizer
  • lr_scheduler
  • loss
  • metric
  • trainer / predictor / sampler 相关设置
  • save / log / eval 相关设置

3.5.2 配置默认应尽量可运行

提交的配置不要求都是大规模训练配置，但至少应保证：

  • 能正常解析
  • 能构建模型
  • 能构建数据集
  • 能启动最小流程

3.5.3 命名规范

建议配置命名体现：

  • 任务
  • 模型名
  • 数据集名
  • 训练目标

例如：

  • megnet_mp2018_e_form.yaml
  • chgnet_oc20_s2ef.yaml
  • schnet_qm9_gap.yaml

避免使用难以理解的命名，如：

  • final_new.yaml
  • test2.yaml
  • run_ok.yaml

3.6. 数据集适配要求

数据集适配类 PR 是 PaddleMaterials 的重点贡献类型之一。提交时请满足以下要求：

3.6.1 需要说明清楚数据来源

请在 README 中说明：

  • 数据集名称
  • 来源链接
  • 原始格式
  • 下载方式
  • 预处理方式
  • 划分方式
  • 标签含义

3.6.2 数据集实现应与现有 dataset 风格一致

要求：

  • 字段命名清楚
  • 返回值结构稳定
  • 与现有训练 / 评测流程兼容
  • 不在 dataset 内写过多任务特判逻辑
  • 不把预处理、训练逻辑和 dataset 强耦合

3.6.3 数据集适配验收底线

数据集适配 PR 至少应满足：

  • 数据集类可实例化
  • 数据能够被正常读取
  • 样本字段与下游模型匹配
  • 按 README 能跑通基本流程
  • 文档与代码一致

3.6.4 数据集文件和预训练模型权重

数据集/模型的适配 PR 应附带数据集文件和预训练模型权重，以便验收。
数据集文件和预训练模型权重可以单独上传到网盘，提供链接可@reviewr上传到BCE上。
reviewr会将数据集文件和预训练模型权重上传到BCE上，并在PR中回复链接。
开发者需将数据集文件和预训练模型权重链接添加到代码对应的位置上

4. 测试与验收要求

4.1 必须满足的最低要求

PR 合入前，至少应满足以下内容中的核心项：

  • 代码可正常导入
  • 关键配置可解析
  • 模型能完成最小前向
  • 数据集能正常加载
  • 主要流程能跑通
  • 不明显破坏现有功能

4.2 建议补充的测试

建议为新增内容补充以下测试之一或多项，非必须：

  • dataset smoke test
  • model forward test
  • config load test
  • train/eval/predict smoke test
  • 关键模块单测

4.3 对模型复现类 PR 的特别要求

模型复现类 PR 不强求一次性达到完全工程化，但至少要做到：

  • 复现目标明确
  • 结果有基本支撑
  • README 可跑通
  • 配置与代码匹配
  • 主要指标可复现或可解释

若仅完成“代码移植”而没有基本跑通与说明，不建议直接合入。

4.4 代码风格与格式检查

本仓库使用 pre-commit 进行基础格式检查。提交前请自行检查代码风格。

4.4.1 提交前建议执行

pre-commit run --all-files

4.4.2 基本格式要求

  • Python 代码风格与现有仓库保持一致
  • YAML / JSON 格式合法
  • Markdown 不应包含 CRLF 和 tab
  • C/CUDA 代码需通过 clang-format
  • 不保留无关 debug 输出
  • 不提交冲突标记、私钥、无关临时文件

4.4.3 不建议合入的内容

以下内容通常不建议直接合入 PaddleMaterials 主仓库：

  • 与仓库主任务方向无关的代码
  • 无 README、无说明、无最小验证的模型移植
  • 含个人本地绝对路径的代码
  • 强依赖私有环境的脚本
  • 临时实验文件
  • 大量未说明来源的权重或数据
  • 文档与代码明显不一致的实现
  • 只能在 Paddle develop 版本运行的功能
  • 完全绕开现有项目结构、另写一套训练框架的实现

4.4.4 提交前检查清单

提交 PR 前，请至少确认以下内容：

  • 修改内容属于 PaddleMaterials 现有任务方向
  • 目录位置正确
  • 沿用了现有代码组织与调用方式
  • 使用 Paddle 官方正式发布版本
  • README 已补充且可用
  • 训练 / 评测 / 推理主要流程能说明白
  • 配置文件能正常解析
  • 数据集 / 模型最小流程已验证
  • 已执行格式检查
  • 未提交无关临时文件、大日志、缓存文件
  • 未提交无说明的大体积权重文件
  • PR 描述完整

5. Review 关注重点

Review 时，维护者通常会重点关注：

  • 是否符合 PaddleMaterials 当前任务方向
  • 是否符合 repo 已有结构与逻辑
  • README 是否可支撑完整使用
  • 文档与代码是否一致
  • 是否具备最小可复现性
  • 是否容易长期维护
  • 是否对现有功能造成副作用

请理解，review 的目标不是增加门槛，而是保证 PaddleMaterials 作为统一 AI4Materials 工具库的整体质量。

6. 致谢

感谢每一位贡献者对 PaddleMaterials 的支持，共同完善 PaddleMaterials 的模型、数据集、训练评测与推理能力。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions