Skip to content

MediSwarm v1.3.0

Choose a tag to compare

View all tags
@Ultimate-Storm Ultimate-Storm released this 05 Apr 14:11
· 766 commits to main since this release
v1.3.0
d1ccf85

MediSwarm v1.3.0

Released: 2026-04-05

Major release adding the STAMP histopathology classification pipeline, FedProx aggregation strategy, comprehensive CI/CD infrastructure, Duke benchmark pipeline, and expanded documentation with architecture diagrams.

🔬 STAMP Classification Pipeline

Full support for KatherLab STAMP 2.4.0 histopathology classification in federated learning:

  • Separate Dockerfile_STAMP — Python 3.11, PyTorch 2.7.1, CUDA 12.6 (independent from ODELIA's Python 3.10/PyTorch 2.2.2 image)
  • Build flag — buildDockerImageAndStartupKits.sh now accepts -d / --dockerfile to select between Dockerfile_ODELIA and Dockerfile_STAMP
  • Synthetic dataset generator — Creates 2 sites × 15 patients with H5 feature files for integration testing
  • Integration tests — Preflight check, local training, and NVFlare simulation mode (3 rounds, 2 clients)
  • Per-round metrics CSV — STAMPMetricsCallback writes ground-truth/prediction probabilities and summary metrics per epoch

Two Docker Images

After v1.3.0, MediSwarm maintains two Docker images:

Image Python PyTorch Use Case
jefftud/odelia:<ver> 3.10 2.2.2 3D breast MRI classification
jefftud/stamp:<ver> 3.11 2.7.1 STAMP histopathology classification

🔄 FedProx Aggregation Strategy

Alternative to FedAvg for improved convergence with non-IID medical data:

  • FedProxCallback — Lightning callback adds proximal term (μ/2) × ‖w_local − w_global‖² to gradient updates
  • Cross-pipeline — Compatible with both ODELIA (pytorch_lightning) and STAMP (lightning)
  • Configurable — Set FEDPROX_MU environment variable (default: 0 = disabled, recommended: 0.001–0.01)
  • Documentation — docs/AGGREGATION_STRATEGIES.md compares FedAvg, FedProx, Scaffold, and FedOpt with decision matrix

🧪 CI/CD for STAMP

Expanded test infrastructure covering both pipelines:

  • Unit tests — test_stamp_training.py (465 lines), test_stamp_model_wrapper.py (257 lines), test_fedprox_callback.py (286 lines)
  • Integration tests — STAMP Docker build + preflight + local training + simulation in pr-test.yaml
  • Unified packages — unit-tests.yaml switched from pytorch-lightning to unified lightning package
  • Timeout — PR test timeout increased from 45 to 60 minutes
  • Cleanup — CI cleanup step now kills stamp and nvflare containers alongside odelia

📊 Duke Benchmark Pipeline

Automated end-to-end benchmarking on the Duke Breast MRI dataset:

  • run_duke_benchmark.sh — Orchestrates build → deploy → swarm training → result collection → local model comparison
  • Configurable deploy — deploy_and_test.sh reads SITES and SERVER_NAME from deploy_sites.conf (backward-compatible defaults)
  • deploy_sites.conf.example — Template with dl0/dl2/dl3 configuration for TUD compute cluster
  • Results template — docs/DUKE_BENCHMARK_RESULTS.md for recording benchmark outcomes

📐 Architecture Documentation

Expanded README from 46 lines to 214 lines:

  • System Architecture — Mermaid diagram showing site-to-server topology with NVFlare aggregation
  • Training Pipeline — Mermaid sequence diagram showing federated learning round lifecycle
  • Supported Pipelines — Comparison table (ODELIA 3D CNN vs STAMP Classification)
  • Key Features — Privacy, Docker reproducibility, multi-pipeline support
  • Project Structure — Annotated directory tree

🔐 Differential Privacy Assessment

Gap analysis and roadmap (documentation only — implementation deferred to v1.4.0):

  • docs/DIFFERENTIAL_PRIVACY.md — Current PercentilePrivacy is gradient clipping, NOT formal (ε,δ)-DP. Detailed analysis of Opacus/DP-SGD integration path, compatibility issues, and privacy budget accounting
  • docs/DIFFERENTIAL_PRIVACY_DECISION.md — Architecture decision record

Changed

  • deploy_and_test.sh container matching broadened to include stamp and nvflare alongside odelia
  • CI pr-test.yaml timeout increased from 45 to 60 minutes
  • CI cleanup step now kills stamp and nvflare containers

Stats

  • 31 files changed, 3,465 insertions, 162 deletions
  • 16 new files created
  • 9 pull requests (#252–#260)

Upgrade Notes

  • No breaking changes from v1.2.0
  • ODELIA pipeline users: no action required — Dockerfile_ODELIA is unchanged
  • STAMP pipeline users: build with ./buildDockerImageAndStartupKits.sh -d docker_config/Dockerfile_STAMP -p <project>
  • FedProx: opt-in via FEDPROX_MU env var — set to 0 or leave unset for standard FedAvg behavior

Full Changelog: v1.2.0...v1.3.0

Assets 2
Loading