X_SSL_Net/docs/findings.md

Findings & Decisions

Requirements

• User asked to thoroughly read the project and introduce its current state to make future work easier.
• Follow-up request: implement recommended items 1-4 (.gitignore/data tracking, dependency manifest, smoke verification, XNet2d shape test) and skip item 5 (SSL Trainer).

Research Findings

• Repository root: /home/kekezack/workspace/X_SSL_Net.
• Git branch: feat_ssl_us_skeleton.
• Dirty files at start: configs/segmentation/train_sup_us_template.yaml, configs/segmentation/us_exp_sup_busi.yaml, configs/segmentation/us_exp_sup_busi_ablation.yaml, lib/modules/xnet_2d.py, lib/trainers/supervised.py, plus untracked lib/modules/xnet_2d_zh.py.
• Main top-level files/directories identified: README.md, configs/segmentation, tools, lib/modules, lib/trainers, lib/tools, vendored lib/SwinTransformer, vendored lib/sam2.
• No AGENTS.md, CLAUDE.md, or GEMINI.md found in parent tree during initial scan.
• lib/data/ exists locally and implements dataset indexing/loading/splitting, but git status --ignored lib/data reports it as ignored (!! lib/data/) and git ls-files lib/data returns nothing.
• Supported dataset builders in local lib/data: BUS-UCLM, TG3K, TN3K, OTU_2d, BUSI, BUS-BRA, BUS_UC, CCAUI, DDTI.
• BUSI and several datasets require generated project split files under <dataset_root>/splits/project/train.txt and val.txt; script is scripts/generate_project_split.py.
• Main training command path: tools/train.py --config configs/segmentation/optimized/*.yaml, or tools/run_optimized_supervised.sh which prepares splits then invokes training.
• Main trainer registry currently has one trainer: supervised_segmentation.
• Main model is XNet2d: encoder with local/wavelet/VMamba global branches, plain U-Net decoder skip fusion, FFT frequency refinement, and segmentation head returning seg_logits.
• Loss and metrics depend on MONAI. Model depends on PyTorch, ptwt, timm, and VMamba-related code; image loading depends on Pillow.
• Current environment import check: yaml available, but torch, monai, ptwt, timm, triton, PIL, and swanlab are missing.
• No project root dependency manifest found (requirements.txt/pyproject.toml absent); dependency references only exist in vendored/reference directories.
• Project tests are effectively absent; only ref/SAM2-UNet/test.py found under ignored reference code.
• python -m py_compile passed for key local files including trainer, model, loss/metrics, and data loader.
• .gitignore currently ignores ref/, tmp/, data/, outputs/logs, .codex, and also .gitignore; local diff adds docs/.
• .gitignore was updated so root /data/ remains ignored but lib/data/ is no longer ignored and appears as ?? lib/data/.
• Added root requirements.txt for the main training stack.
• Added tests/test_xnet_2d.py for XNet2d segmentation output shape.
• xnet_mamba conda environment has core training dependencies (torch, monai, ptwt, timm, triton, PIL) but lacks pytest and swanlab.
• BUSI project splits exist and load successfully: train 624, val 156.
• CPU full-model forward is currently blocked by VMamba/csm_triton CPU path: cross_scan_fn enters torch.cuda.device(x.device) even when ssm_backend="torch".
• CUDA smoke training passed on BUSI with 64x64 images, small model, 1 epoch, no validation/checkpoint/SwanLab: 312 train steps, final average total/seg loss about 0.84585.

Technical Decisions

Decision	Rationale
Do not modify project code during audit	User requested reading/status, not implementation

Issues Encountered

Issue	Resolution
Cannot run model/training in current environment	Missing core ML dependencies; limited verification to static reading and py_compile
Training depends on ignored lib/data/ package	Treat as repository state risk; mention in handoff
CPU full XNet2d/Trainer smoke fails due to VMamba global branch CUDA wrapper	Recorded as model backend limitation; verified full smoke on available CUDA GPU

Resources

• README.md
• tools/train.py
• lib/trainers/supervised.py
• lib/modules/xnet_2d.py
• configs/segmentation/*.yaml