ONet_Based_UDE

基于算子谱神经网络的超声损伤检测 - 从 3D 超声时空信号到 2D 缺陷图的跨模态映射

---

📋 项目简介

本项目实现了两种深度学习模型,用于从3D 时空超声信号映射到2D 缺陷图:

• OperatorMapper3D ⭐: 基于低秩算子分解的 3D 卷积网络（推荐）（待开发为使用超声检测相关算子如拉普拉斯算子、小波基等构造空间函数和算子）
• LSTMMapper3D: 基于双向 LSTM 的时序特征提取网络

核心技术:

• 3D 卷积 + 残差连接提取时空特征
• 低秩算子分解降低参数量
• 动态组合损失函数（Focal + Tversky + BCE）
• Cosine Annealing 学习率调度 + Dice 早停策略

---

🚀 快速开始

1. 安装依赖

# 使用uv（推荐,速度快10-100倍）
pip install uv
uv pip install -e .

2. 运行测试

# 测试3D模型基础功能（约30秒）
uv run python tests/test_models_3d.py

# 快速训练验证（约2分钟）
uv run python tests/test_models_3d.py --train-smoke --epochs 5

3. 训练模型

# 标准训练（推荐配置）
uv run python scripts/train_3d_models.py --model operator --epochs 100 --visualize

# 自定义训练
uv run python scripts/train_3d_models.py \
    --model operator \
    --epochs 150 \
    --batch-size 8 \
    --lr 5e-4 \
    --img-size 64 \
    --n-train 800 \
    --n-val 200

---

📊 核心参数调优指南

模型参数

参数	默认值	影响	调优建议
--rank	128	算子秩维度	↑ 提高表达力,↓ 降低过拟合
--latent-dim	2048	潜在空间维度	↑ 增强特征,↑ 内存占用
--img-size	64	输出图像尺寸	32/64/128（越大越精细）

训练参数

参数	默认值	影响	调优建议
--lr	5e-4	学习率	不收敛 ↑,震荡 ↓
--batch-size	8	批次大小	GPU 允许时 ↑,OOM 时 ↓
--epochs	100	训练轮数	Dice<0.7 时 ↑ 至 150-200

数据参数

参数	默认值	影响	调优建议
--nx,--ny	51	空间分辨率	↓ 加速训练,↑ 提高精度
--sig-len	1000	时间序列长度	↓ 减少内存,↑ 细节信息
--n-train	800	训练样本数	↑ 提升泛化,↑ 训练时间

性能对比（100 epochs）:

配置	Dice Score	训练时间（GPU）	内存占用
快速测试 (32×32, 400 样本)	0.38	15 分钟	4GB
标准配置 (64×64, 800 样本)	0.65	45 分钟	8GB
高精度 (128×128, 1600 样本)	0.72	2 小时	16GB

---

💡 模型架构

OperatorMapper3D（推荐）

3D Signal (ny×nx×sig_len)
    ↓
[3D Conv Blocks] → 提取时空特征
    (32→64→128→256 channels, 残差连接)
    ↓
[Low-Rank Operator] → 降维映射 (W = B@A)
    (rank=128, compression ratio~0.05)
    ↓
[Enhanced Decoder] → 渐进上采样
    (4×4 → 8×8 → 16×16 → ... → img_size)
    ↓
2D Defect Image (img_size×img_size)

参数量: ~2M
最佳 Dice: 0.65-0.75（100 epochs）

LSTMMapper3D

3D Signal → 2D Spatial Conv → LSTM → Decoder → 2D Image

参数量: ~1.5M
最佳 Dice: 0.55-0.68（100 epochs）

---

📂 项目结构

ONet_Based_UDE/
├── src/cross_modal/
│   ├── dataset/           # 3D数据集
│   ├── models/ 
|   |   |— base_model.py          # 模型抽象基类
│   │   ├── operator_mapper_3d.py  # 算子映射器
│   │   ├── lstm_mapper_3d.py      # LSTM映射器
│   │   └── losses.py              # 动态损失函数
│   └── trainers/          # 训练器
│       ├── config_3d.py           # 训练配置
│       └── trainer_3d.py          # 训练逻辑
├── scripts/
│   └── train_3d_models.py # 训练脚本
├── tests/
│   ├── test_models_3d.py  # 模型测试
│   └── test_dataset.py    # 数据集测试
├── docs/                  # 详细文档
└── legacy/                # 1D模型（已弃用）

---

🧪 测试指南

完整测试套件

# 运行所有测试（A-G: 基础功能）
uv run python tests/test_models_3d.py

# 包含训练冒烟测试（A-H）
uv run python tests/test_models_3d.py --train-smoke --epochs 10

测试覆盖

• ✅ A. 模型初始化和前向传播
• ✅ B. 动态输出尺寸适配（32/64/128）
• ✅ C. 批处理功能（1/4/8）
• ✅ D. 模型保存/加载
• ✅ E. 与 3D 数据集集成
• ✅ F. 损失函数计算
• ✅ G. GPU/CPU 兼容性
• ✅ H. 训练冒烟测试（可选）

详见 docs/testing_guide.md

---

📈 最佳实践

训练建议

1. 首次使用: 从小规模开始验证

   uv run python tests/test_models_3d.py --train-smoke --epochs 5 --n-train 64

2. 标准训练: 使用默认配置

   uv run python scripts/train_3d_models.py --model operator --epochs 100

3. 冲击高精度: 增加轮数和样本

   uv run python scripts/train_3d_models.py --epochs 200 --n-train 1600 --img-size 128

优化技巧

• Dice 不提升: 检查 results/training_curves.png,调整学习率或增加数据
• 训练过慢: 减小 --nx,--ny,--sig-len
• GPU 内存不足: 降低 --batch-size 或 --img-size
• 过拟合严重: 增加训练样本或降低模型复杂度

---

📚 文档

文档	说明
TESTING_GUIDE.md	测试脚本使用指南
3D_MODELS_GUIDE.md	3D 模型详细说明
UV_GUIDE.md	uv 依赖管理工具

---

🔧 常见问题

Q: CUDA Out of Memory?
A: --batch-size 4 或 --img-size 32

Q: Dice Score 过低（<0.5）?
A: 增加 --epochs 200 或检查数据质量

Q: 如何切换到 LSTM 模型?
A: --model lstm（参数量更小,精度略低）

Q: 训练后模型在哪?
A: checkpoints/best_model_3d_dice.pth（最佳 Dice）或 checkpoints/best_model_3d.pth（最佳 Loss）或在results目录下查看训练曲线和可视化结果

---

📖 参考文献

核心理论基础

[1] Kiruluta, A., Lemos, A., & Burity, P. (2025). Operator-Based Machine Intelligence: A Hilbert Space Framework for Spectral Learning and Symbolic Reasoning (1st ed.). arXiv. https://doi.org/10.48550/ARXIV.2507.21189

本项目中 OperatorMapper3D 的理论基础来源于该论文提出的基于希尔伯特空间的算子谱学习框架,通过低秩算子分解实现高效的跨模态映射。

引用本项目

如果您在研究中使用了本项目,请按以下格式引用:

@software{onet_based_ude_2025,
  title = {ONet\_Based\_UDE: Operator-Based Neural Network for Ultrasonic Damage Evaluation},
  author = {2p1c},
  year = {2025},
  url = {https://github.com/2p1c/ONet_Based_UDE},
  note = {基于算子谱神经网络的超声损伤检测 - 从3D超声时空信号到2D缺陷图的跨模态映射}
}

---

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

---

🙏 致谢

• PyTorch 团队提供的深度学习框架
• 3D 卷积网络和算子理论的相关研究

---

最后更新: 2024 年
项目状态: 积极维护中 🚀
当前最佳: OperatorMapper3D (Dice ~0.70, 100 epochs)