SWIN finetuning: domain-gap closing Tier 1/2 (balanced softmax, EMA, flip TTA) + SWIN-L 384 concrete run

[trgardos]

Summary

Implements the Tier 1 & Tier 2 "concrete next run" from SWIN_training_setup_summary.md (§10 recommendations / §11 step-by-step) on top of faridkar's SWIN finetuning framework, scoped to stay within SWIN-L 384 (no backbone swap). Goal: close the macro-F1 gap on the ~15.5k-class long tail.

The branch is 5 commits, structured so the framework sync is isolated from the new work:

1. 34045dd Sync framework from faridkar — brings this repo's finetuning/SWIN/ up to faridkar's current trainer (integrated ArcFace + non-backbone overlay, multi-task, mixup/cutmix, multi-crop TTA), plus configs_advanced/ (curriculum + seed ensemble), hyperparameter_configs/, launch_sweep.py, and reference docs. No tgardos edits in this commit — verbatim, so the rest of the PR is a clean diff.
2. c20acfa §10/§11 Tier 1–2 features + concrete config (see below).
3. 956f6b5 Environment — use the spring-2026-pyt conda env (not faridkar's personal herb_env); document pip install --user evaluate wandb.
4. e1f946c W&B setup docs — gardoslab/herbdl logging.
5. 6bd0636 Output-path auto-relocation + TrainingArguments fix.

New trainer features (all config-gated, default-off — existing configs unchanged)

Feature	Section	Config key
Balanced softmax / logit adjustment (species log-prior added to logits at train time only)	1.3-A	long_tail.logit_adjustment / tau
Weight EMA (shadow avg copied into model at train end → final eval/save use EMA)	2.6	ema.enabled / decay
Horizontal-flip TTA (avg over crops × {orig, flip})	2.7	multi_crop.flip
gradient_checkpointing_enable/disable passthrough on the multi-task/ArcFace wrappers	—	training.gradient_checkpointing

Balanced softmax is applied in MixupTrainer.compute_loss for single-task and multi-task, in both the mixup and non-mixup paths, and is off at inference (plain argmax) — the standard balanced-softmax recipe for lifting macro-F1 on rare classes.

The concrete run

• configs_advanced/swin_large_384_concrete.yml — SWIN-L @384 (ImageNet-22k), multi-task + balanced softmax + EMA, medium (cold-start-safe) augmentation, 100 epochs, TTA block ready for inference.
• submit_concrete.sh — A100-80G seed-ensemble launcher (distinct run_id/output_dir per seed via --set). Nothing is auto-submitted.
• CONCRETE_RUN_README.md — run/feature docs, one-time env setup (pip + W&B), smoke test, warm-start, OOM tuning, TTA inference.

Fixes surfaced along the way

• Output paths auto-relocate: configs hardcode .../workspaces/faridkar/herbdl/...; the trainer now rewrites any .../workspaces/<author>/herbdl prefix to the workspace it's actually run from (preserving the run name), so every config writes under the runner's own workspace with no YAML edits. HERBDL_NO_RELOCATE=1 opts out.
• TrainingArguments allow-list was silently dropping gradient_checkpointing and load_best_model_at_end — now forwarded, so the 384 config's gradient checkpointing actually takes effect (it would otherwise OOM).

Deferred (future ensemble members, intentionally out of scope)

Domain-pretrained backbone swap (Tier 1.1 timm/open_clip), warmed-up ArcFace rescue (Tier 2.4), class-balanced sampler / two-stage cRT (Tier 1.3-B), and +2021 data (Tier 2.8).

Validation

py_compile + full module import under spring-2026-pyt; all configs_advanced/*.yml parse; --set override flow and output-path relocation unit-tested (faridkar→tgardos rewrite, local/unrelated paths untouched, opt-out honored). No GPU training run yet — recommend the README smoke test before launching the 48h jobs.

🤖 Generated with Claude Code

[Farid-Karimli]

I like the updates -- curious to see what effect balanced softmax has.