feat: add adaptive sampling, motion registration, MEDL, and e2e ADS configs

[georgeyiasemis]

Description

This PR brings end-to-end adaptive dynamic sampling (ADS) and optional motion registration into DIRECT, together with the paper experiment layouts for the MIDL 2026 e2e ADS works.

It wires learned sampling policies and registration models through the MRI training/inference stack, ships validated train + inference YAML pairs under projects/e2e_ads_recon and projects/e2e_ads_recon_reg, and hardens config/checkpoint loading so those projects (and Hub-style inference YAMLs) run cleanly on current main (including ruff 0.16).

What's new

• Adaptive k-space sampling (direct/nn/adaptive/): policies for 1D/2D and static/dynamic masks, rejection-sampling as a typed training path (RejectionSamplingError), and budgeting that works with static ACS on dynamic volumes.
• Motion registration (direct/registration/, direct/nn/registration/): VoxelMorph-style learned registration plus classical utilities (demons, optical flow, elastic deformation); joint or decoupled recon↔registration training.
• MEDL reconstruction model and related engine support.
• 3D VarNet model/config/engine paths used by the ADS setups.
• Key-based losses (source_key / target_key) and displacement-field visualization for registration runs.
• Paper projects:
  • projects/e2e_ads_recon — adaptive sampling + reconstruction (vSHARP / MEDL variants, frame/init2 configs).
  • projects/e2e_ads_recon_reg — same family with registration (vSHARP / VarNet / LOUPE / fixed-mask variants, phase/frame and disjoint options).
• Sibling inference YAMLs (*_inference.yaml): one inference file per model with active val-4× masking and commented 6×/8× alternatives (no per-rate file explosion).

What's changed

• MRI engines (vSHARP, RIM, CIRIM, shared MRIModelEngine) call into adaptive sampling / registration when configured; writers can persist registration volumes and displacement fields.
• Config system: training / validation are optional so inference-only YAMLs are valid; logging.log_interval controls TensorBoard/scalar flush cadence.
• DYNAMIC masking correctly receives a time dimension; float adaptive masks are handled in DC fill / masking; Calgary-Campinas mask downloads cast acceleration to int filenames.
• Checkpoint loading raises a clear RuntimeError on missing keys; ModConv conv_out_bias / AdaIN kwargs wiring aligned so paper weights load under current UNet construction.
• filter_arguments_by_signature keeps **kwargs-based model builders working when configs carry extra image_* fields.
• Docs/READMEs for adaptive, registration, MEDL, and both e2e ADS projects; Python 3.12 / elasticdeform notes where needed.
• Merged with latest main ruff cleanup without dropping the above behavior.

User impact

• You can train and run the e2e ADS (and ADS+registration) paper configs from this repo with the published naming and sibling inference YAMLs.
• Inference configs can omit training / validation blocks; use *_inference.yaml (or the minimizer) instead of maintaining many rate-specific files.
• Registration models need a reference image in the batch (or registration_simulate_reference in transforms); without that, predict fails with a missing reference_image key.
• Adaptive / DYNAMIC sampling may skip batches on rejection-sampling failure during training (logged retries) instead of always aborting immediately.

[codecov]

Codecov Report

❌ Patch coverage is 79.22461% with 493 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.81%. Comparing base (65b3a9e) to head (7d25ab2).

Files with missing lines	Patch %	Lines
direct/nn/mri_models.py	66.28%	117 Missing ⚠️
direct/data/mri_transforms.py	57.47%	91 Missing ⚠️
direct/nn/adaptive/parameterized.py	72.50%	55 Missing ⚠️
direct/nn/adaptive/policy.py	77.11%	54 Missing ⚠️
direct/engine.py	42.69%	51 Missing ⚠️
direct/nn/medl/medl_engine.py	69.90%	31 Missing ⚠️
direct/nn/vsharp/vsharp_engine.py	35.55%	29 Missing ⚠️
direct/nn/adaptive/utils.py	84.94%	14 Missing ⚠️
direct/nn/registration/registration.py	91.57%	8 Missing ⚠️
direct/nn/adaptive/sampler.py	92.92%	7 Missing ⚠️
... and 13 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #316      +/-   ##
==========================================
- Coverage   84.71%   83.81%   -0.91%     
==========================================
  Files         110      129      +19     
  Lines       10122    12350    +2228     
==========================================
+ Hits         8575    10351    +1776     
- Misses       1547     1999     +452     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.