fix(impact-reg): show IMPACT's messages, explain an unseen GPU

[vboussot]

Summary

Three things an elastix + IMPACT run left the user to guess, all in apps/impact_reg.

IMPACT's messages were swallowed. The engine shows elastix's output on a failure only. When the device runs out of memory, IMPACT goes on with smaller feature patches and says so, the run is slower for it, and nothing told why. Its IMPACT: lines are now written as they come, once each.

A GPU the install cannot see failed mid-registration, with "CUDA is not available" and nothing to act on. A CPU build answers -h, so it passes for a valid install. The error now names the install, the environment's torch and what to do: point KONFAI_ELASTIX_DIR at a build made against that torch, or run on the CPU.

The installer fetched the CUDA asset on any suitable driver. That asset links the CUDA 12 runtime from where torch keeps its own, so under a torch built for CUDA 13 it could not load, and the install failed where the CPU asset would have run. The CUDA asset is now fetched for a CUDA 12 torch only. Otherwise the CPU asset is, with a line saying why, and a forced CUDA install refuses.

Measured

MR_CT_HeadNeck on a 192 x 160 x 192 pair, with the allocator of the elastix subprocess capped to a few MB of the GPU. The registration completes, and the run now prints what it did:

IMPACT: the model ran out of device memory on the whole image; retrying with a patch of (96 160 192).
IMPACT: the model ran out of device memory on the whole image; retrying with a patch of (96 160 96).

Before, the same run printed nothing, and took 98 s instead of 42 s.

Not changed: no asset exists for a CUDA 13 torch, so the GPU still needs a local build there.

Test plan

• new unit tests, each failing on main: the IMPACT: lines shown once, the hint on "CUDA is not available" and only there, the asset chosen from the torch's CUDA, a forced CUDA install refused
• apps/impact_reg/tests: 79 passed, with and without itk installed
• ruff, format

Summary by CodeRabbit

• Bug Fixes

  • Improved automatic GPU setup by matching the installed CUDA version and falling back to CPU when necessary.
  • Forced CUDA installation now reports incompatibility instead of attempting to use an unsupported package.
  • Registration errors now include actionable guidance when CUDA is unavailable.
  • Repeated device-memory fallback messages are shown only once during progress reporting.

• Tests

  • Added coverage for CUDA asset selection, CPU fallback, compatibility errors, and registration failure guidance.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 2c234707-6947-44ab-971f-be92f047b902

📥 Commits

Reviewing files that changed from the base of the PR and between 516eec5 and 1fe547c.

📒 Files selected for processing (3)

• apps/impact_reg/impact_reg_konfai/models/elastix_engine.py
• apps/impact_reg/tests/unit/test_elastix_install.py
• apps/impact_reg/tests/unit/test_engine_contracts.py

Included review availability: 7 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

---

📝 Walkthrough

Walkthrough

The installer now matches elastix CUDA assets to the installed PyTorch CUDA version. Registration deduplicates IMPACT: messages and adds CUDA setup guidance when elastix reports unavailable CUDA. Unit and contract tests cover these behaviors.

Changes

CUDA Compatibility and Elastix Diagnostics

Layer / File(s)	Summary
CUDA asset compatibility apps/impact_reg/impact_reg_konfai/models/elastix_install.py, apps/impact_reg/tests/unit/test_elastix_install.py	torch_cuda_flavor() selects cu128 only for Torch CUDA 12.x builds. Automatic selection falls back to CPU when no compatible CUDA asset exists. Forced CUDA installation raises an error when Torch cannot load the asset. Tests cover CUDA 12.8, CUDA 13, and CPU-only environments.
Elastix diagnostics and failure guidance apps/impact_reg/impact_reg_konfai/models/elastix_engine.py, apps/impact_reg/tests/unit/test_engine_contracts.py	Registration displays each distinct IMPACT: status line once. CUDA-unavailable failures include KONFAI_ELASTIX_DIR guidance. Tests cover repeated fallback messages and unrelated subprocess errors.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 1fe54

The installer now selects compatible elastix assets and registration provides deduplicated diagnostics with conditional CUDA guidance. No actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the two main changes: showing IMPACT messages and explaining GPU compatibility failures. It follows the required Conventional Commits format.
Description check	✅ Passed	The description clearly explains the behavior changes, user impact, measured result, and test coverage. It does not reproduce all template headings or checklist items, but it provides the required cor…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{A rabbit checks the CUDA trail,
Torch and elastix now set sail.
Repeated warnings hop once by,
Clear hints appear when CUDA cries.
Tests guard each path with care,
And guide the hare through setup there.}

_{Comment @coderabbitai help to get the list of available commands.}