DDPM for SAW Co-Design

面向声表面波（SAW）器件的正向性能预测与条件生成式逆设计项目。仓库将 多任务代理模型、Tandem、cVAE、条件 DDPM、优化基线和主动学习整理为一套 可阅读、可测试的研究工程代码。

当前状态：DDPM 的模型、训练、采样和合成数据测试已公开，但没有发布 DDPM 预训练权重或性能结果。仓库内的历史指标来自既有模型，不能视为 DDPM 成绩。

English summary

This portfolio repository explores surrogate-assisted inverse design for surface acoustic wave devices. It provides a conditional DDPM implementation for generating (N1, N2) designs from target (Q, IL_dB, bw_3dB) specifications, together with forward surrogates, tandem and cVAE inverse models, transparent baselines, and selected pretrained checkpoints. The COMSOL-derived training dataset is private. No pretrained DDPM checkpoint or DDPM performance claim is included.

项目亮点

• 正向代理：物理启发的 16 维特征、多任务残差 MLP、五种子集成。
• 多种逆设计路线：确定性 Tandem、生成式 cVAE、条件 DDPM。
• 可信基线：lookup、SVR、GPR、随机森林以及优化算法接口。
• 工程可复现性：统一配置、模型卡、权重哈希、CPU 合成烟雾测试和 CI。
• 结论边界清晰：二维设计域接近枚举，lookup 是必须保留的强基线。

项目中的自有代码、实验设计和公开版工程整理由作者独立完成；PyTorch、 scikit-learn 等第三方项目不包含在该声明中。

系统方法

flowchart LR
    A["Private COMSOL simulations<br/>N1, N2 → Q, IL, bandwidth"]
    B["Forward surrogate ensemble"]
    C["Target specifications"]
    D["Tandem inverse"]
    E["Conditional VAE"]
    F["Conditional DDPM"]
    G["Discrete candidate projection"]
    H["Surrogate ranking / lookup baseline"]
    I["Candidate designs for future COMSOL verification"]
    A --> B
    C --> D
    C --> E
    C --> F
    D --> G
    E --> G
    F --> G
    G --> H
    B --> H
    H --> I

Loading

DDPM 在标准化的二维设计变量上执行扩散，条件为三项目标性能。采样后保留 连续原始结果，再执行边界裁剪、整数化和允许设计对吸附，避免将不可制造的 连续值直接当作最终方案。

模型与权重

模型	公开代码	预训练权重	作用
多任务正向 MLP 集成	是	5 个种子	N1,N2 → Q,IL_dB,bw_3dB
Tandem inverse	是	1 个	确定性逆设计起点
Conditional VAE	是	1 个	一对多候选生成
Conditional DDPM	是	否	扩散式一对多候选生成
SVR/GPR/随机森林/lookup	是	不适用	透明比较基线
主动学习选择器	是	不适用	后续仿真补点

权重位于 artifacts/pretrained，按 模型族/版本/model_seed_<seed>.pt 保存。每个版本包含 manifest.json 和 MODEL_CARD.md，记录 SHA-256、训练数据边界和限制。

快速开始

git clone https://github.com/Ghyoung0095/DDPM-FOR-SAW-CODESIGN.git
cd DDPM-FOR-SAW-CODESIGN
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
pytest

上述测试只使用程序生成或仓库内的合成数据，不需要私有训练集。

使用已有正向权重

import numpy as np
from saw_codesign.pretrained import load_forward_surrogate

model = load_forward_surrogate(
    "artifacts/pretrained/forward_multitask_ensemble/v1/model_seed_42.pt"
)
prediction = model.predict(np.array([[80.0, 200.0]]))
print(prediction)  # columns: Q, IL_dB, bw_3dB

使用私有数据训练 DDPM

训练 CSV 必须含 N1,N2,Q,IL_dB,bw_3dB：

python -m saw_codesign.train_ddpm `
  --data D:\path\to\private_training.csv `
  --config configs\ddpm\default.yaml `
  --output artifacts\generated\ddpm\model.pt

生成候选：

python -m saw_codesign.generate `
  --model ddpm `
  --checkpoint artifacts\generated\ddpm\model.pt `
  --targets examples\targets.csv `
  --output outputs\ddpm_candidates.csv `
  --num-samples 50

已有结果

以下是原开发流程中已记录的历史结果，不是本仓库重新训练得到的 DDPM 指标：

方法	历史结果
正向多任务模型	Q R² 0.8818；IL_dB R² 0.8611；bw_3dB R² 0.9317
Tandem + 局部搜索	代理模型约束满足率 0.97
cVAE	约束满足率 0.91；每 50 个样本平均 45.2 个唯一候选
NSGA-II	约束满足率 0.97；平均 1235.15 次评估
Lookup	在近枚举二维空间中约束满足率 0.97

逆设计满足率由既有正向代理评估，并非新增 COMSOL 回验。模型卡中保留了 更具体的适用条件。

目录

src/saw_codesign/
├── common/                 # 数据契约、归一化和设计域
├── models/forward/         # 正向多任务代理
├── models/inverse/         # Tandem、cVAE、DDPM
├── baselines/              # 经典回归与 lookup
├── active_learning/        # 不确定性/多样性选点
├── train_ddpm.py           # DDPM 训练入口
└── generate.py             # DDPM 候选生成入口

artifacts/pretrained/       # 精选主线权重、模型卡和哈希
configs/                    # 各模型配置
docs/                       # 数据契约、架构与复现说明
tests/                      # 单元测试和合成烟雾测试

数据与研究边界

• 原始 2,085 行及清理后的 1,911 行 COMSOL 派生数据均不公开。
• 仓库不包含专利材料、原始仿真工程、内部备忘或个人路径。
• 二维 (N1,N2) 网格历史覆盖率约 93%，深度生成模型在该空间中不天然 优于 lookup；其价值主要是一对多生成接口和未来扩展到更高维设计变量。
• 已生成的逆设计候选尚未形成完整 COMSOL 回验闭环。
• 本仓库是研究原型与工程作品集，不用于临床诊断或生产器件验收。

详见 数据格式、架构说明 和 复现说明。

License

自有代码和仓库内发布的项目权重采用 MIT License。第三方依赖 仍受各自许可证约束，见 THIRD_PARTY_NOTICES.md。