## Handoff Review (2026-05-27)

| Dimension | Score | Notes |
|-----------|-------|-------|
| Completeness | 5/5 | Goal, current state, completed/WIP/blocked items, files, verification, environment, branch and commit are all present. |
| Decision Quality | 5/5 | Decisions include rationale, alternatives, and key constraints such as CUDA-only full-model training. |
| Actionability | 4/5 | Next steps are ordered and concrete; exact full-training hyperparameters still need to be chosen before formal runs. |
| Accuracy | 5/5 | Branch, latest commit, and listed file paths were verified locally; tracked project files listed in the handoff exist. |
| Safety | 5/5 | No credentials, tokens, passwords, or private keys detected by text scan. |

**Blockers:** None for handoff. Operational blocker remains: full `XNet2d` with VMamba global branch should be run on CUDA, not CPU.
**Recommendations:** Before sharing outside this workspace, remember `docs/` is ignored by Git, so this handoff and the report may need to be copied, force-added, or moved into a tracked docs policy.
**Overall:** PASS_WITH_CAVEATS

# Handoff: 2026-05-27 19:09

## Summary

本轮工作围绕 X_SSL_Net 的阶段性整理和汇报材料展开。项目当前已经具备配置化训练入口、数据加载模块、基础实验脚本、最小烟测记录和汇报文档。当前没有新增正式完整实验结果，项目下一阶段重点是：一方面继续上一篇论文修改，另一方面启动 X_SSL_Net 作为第二篇项目的正式训练和消融实验。

## Current State

- **Complete:**
  - 训练入口已统一为 `tools/train.py`，支持 YAML 配置和 `--set` 覆盖。
  - 全监督分割训练主线已整理到 `lib/trainers/supervised.py`。
  - 通用训练能力集中在 `lib/trainers/base.py`，包括设备、日志、checkpoint、验证、early stopping 等。
  - `lib/data/` 数据加载模块已纳入项目代码，支持多个超声数据集。
  - 根目录已补充 `requirements.txt`。
  - 已添加 `tests/test_xnet_2d.py`，用于验证 `XNet2d` 输出 shape。
  - BUSI 数据划分可用：train 624，val 156。
  - CUDA 烟测已通过：BUSI、小模型、64x64、1 epoch、312 step，最终平均 loss 约 0.8459。
  - 汇报材料已写入 `docs/report/2026-05-27_x_ssl_net_status_report.md`。

- **In Progress:**
  - 正式完整训练尚未开展。
  - 消融实验尚未开展。
  - 当前项目汇报材料是阶段状态稿，可继续按实验结果补充。

- **Blocked:**
  - CPU 下完整 `XNet2d` 不能运行 VMamba global branch。即使设置 `ssm_backend=torch`，底层 `csm_triton.cross_scan_fn` 仍会调用 `torch.cuda.device(x.device)`，在 CPU 上报错。
  - 正式实验依赖 GPU 环境。

## Key Decisions

| Decision | Rationale | Alternative |
|----------|-----------|-------------|
| 将项目表述为“配置化训练重构已完成，烟测已完成，可进入正式实验” | 符合当前实际状态，避免把 smoke test 包装成正式实验结果 | 直接汇报“没有实验进展”，信息量不足 |
| 后续先跑全监督 baseline，再做消融 | 当前可运行主线是全监督分割训练，先拿稳定基线最实际 | 立即展开 SSL Trainer，不符合当前用户要求 |
| 通过 YAML 和 `--set` 管理实验 | 减少改代码次数，便于完整实验和消融实验复现 | 为每个实验手写单独训练脚本 |
| 正式训练使用 CUDA | 完整 VMamba global branch 当前 CPU 路径不可用 | 尝试 CPU 跑完整模型，会触发已知错误 |
| 交接文档放在 `docs/handoff/` | 文档按用途归档，避免根目录继续堆文件 | 放根目录 `HANDOFF.md`，不符合用户“都放到 docs 下”的要求 |

## Files Touched

| File | Purpose | Status |
|------|---------|--------|
| `.gitignore` | 调整忽略规则，使根目录 `/data/` 继续忽略，同时允许 `lib/data/` 作为代码模块纳入项目 | 已提交 |
| `requirements.txt` | 记录主训练依赖，包括 PyTorch、MONAI、ptwt、timm、Pillow、triton、swanlab、pytest 等 | 已提交 |
| `lib/data/` | 数据索引、加载、划分、augmentation、collate 等逻辑 | 已提交 |
| `lib/modules/xnet_2d.py` | 核心 `XNet2d` 模型，小波分支、频率精炼、VMamba global branch 等 | 已提交 |
| `lib/trainers/supervised.py` | 全监督分割训练逻辑，读取模型配置并启动训练 | 已提交 |
| `configs/segmentation/*.yaml` | 全监督训练和消融相关配置 | 已提交 |
| `tests/test_xnet_2d.py` | 模型 forward shape 测试；CPU 下跳过 global branch，CUDA 下覆盖完整路径 | 已提交 |
| `docs/report/2026-05-27_x_ssl_net_status_report.md` | 今日汇报稿，强调配置化训练、烟测完成、后续实验计划 | 本地 docs |
| `docs/handoff/2026-05-27_x_ssl_net_handoff.md` | 本交接文档 | 本地 docs |

## Verification

- Syntax check:

```bash
python -m py_compile tools/train.py lib/trainers/base.py lib/trainers/builder.py lib/trainers/supervised.py lib/modules/xnet_2d.py lib/tools/loss.py lib/tools/metrics.py lib/tools/optim.py lib/utils/config.py lib/data/*.py scripts/generate_project_split.py tests/test_xnet_2d.py
```

- XNet2d shape test:

```bash
/opt/miniforge3/envs/xnet_mamba/bin/python - <<'PY'
from tests.test_xnet_2d import test_xnet2d_forward_preserves_segmentation_shape
test_xnet2d_forward_preserves_segmentation_shape()
print('xnet forward shape test passed')
PY
```

- BUSI split check:

```bash
/opt/miniforge3/envs/xnet_mamba/bin/python scripts/generate_project_split.py --dataset BUSI --root data/BUSI --seed 42
```

Observed result: train 624, val 156.

- CUDA smoke training:

```bash
/opt/miniforge3/envs/xnet_mamba/bin/python tools/train.py \
  --config configs/segmentation/train_sup_us_template.yaml \
  --set train.device=cuda train.epochs=1 train.batch_size=2 train.val_batch_size=2 \
  train.num_workers=0 train.persistent_workers=false train.pin_memory=false \
  train.prefetch_factor=null train.amp=false train.grad_clip.enabled=false \
  train.deterministic=true dataset.dataset_name=BUSI dataset.root=data/BUSI \
  dataset.image_size='[64,64]' model.encoder_channels='[8,16,24,32]' \
  model.encoder_depths='[1,1,1,1]' model.decoder_channels='[24,16,8]' \
  model.stem_channels=8 model.bottleneck_depth=1 model.global_ratio=1.0 \
  model.use_global_branch_stage1=false model.use_frequency_refine=true \
  model.ssm_d_state=1 model.ssm_backend=auto model.out_channels=null \
  model.use_wavelet_branch=true validation.enabled=false \
  checkpoint.dir=outputs/smoke/supervised/BUSI checkpoint.save=false \
  logging.use_swanlab=false logging.print_training_setup=false logging.log_interval=9999
```

Observed result: 312/312 steps completed, final average total/seg loss about 0.8459.

## Environment

- Recommended environment: `/opt/miniforge3/envs/xnet_mamba`
- Python: 3.10.20 in `xnet_mamba`
- CUDA GPU observed: NVIDIA GeForce RTX 4070 Ti SUPER, 16 GB
- Core imports available in `xnet_mamba`: `torch`, `monai`, `ptwt`, `timm`, `triton`, `PIL`
- Missing in `xnet_mamba` during check: `pytest`, `swanlab`
- Note: smoke training disabled SwanLab with `logging.use_swanlab=false`.

## Next Steps (Priority Order)

1. 完成上一篇论文修改 — 当前汇报口径里这是近期主要工作之一。
2. 跑 X_SSL_Net 正式 baseline — 建议先选 BUSI 或 BUS-UCLM，使用默认 256x256 配置，在 CUDA 上完整训练并记录 Dice、IoU、loss 曲线、最优 epoch、耗时和显存。
3. 做第一组消融实验 — 优先比较 full model、no wavelet branch、no frequency refine、不同 low-frequency radius。
4. 整理实验结果表格 — 可使用 `tools/summarize_results.py` 汇总 `best.pth` 指标，必要时补充手动结果表。
5. 根据 baseline 和消融结果决定是否继续调整模型结构或训练策略。

## Open Questions

- 正式实验优先数据集是 BUSI、BUS-UCLM，还是需要同时覆盖更多超声数据集？
- 完整训练的 epoch、batch size、输入尺寸是否沿用当前模板，还是根据 GPU 显存重新设定？
- 是否需要把 `pytest` 和 `swanlab` 安装到 `xnet_mamba` 环境，或者保持 smoke/正式训练均通过配置关闭 SwanLab？
- CPU 路径是否需要后续修复，还是默认该模型只支持 GPU 正式训练？

## Known Pitfalls

- 不要在 CPU 上跑完整 VMamba global branch；当前会报 `Expected a cuda device, but got: cpu`。
- `logging.use_swanlab=true` 时，如果环境没有安装 `swanlab`，代码会提示缺失并继续；正式记录实验建议确认日志工具是否需要启用。
- `docs/` 当前被 `.gitignore` 忽略，本交接文档和汇报稿属于本地文档资料，不会自动出现在 `git status --short` 中。
- `/data/` 应继续忽略，不要把真实数据集提交进仓库。
- 若新增消融配置，注意同步 `checkpoint.dir` 和 `logging.experiment_name`，避免结果覆盖或命名混乱。

## Branch Info

- **Branch:** `feat_ssl_us_skeleton`
- **Latest Commit:** `5f33d6e8b468d03595fe8be884e557304bd501e1` — "feat(data): 添加数据处理模块和配置频率细化参数"
- **Commit Time:** `2026-05-27T18:47:16+08:00`
- **Base Branch:** not verified in this session