docs: add differentiability warning for Warp with mode='nearest'

[Kheil-Z]

Fixes #8540 .

Description

This PR updates the docstring of monai.networks.blocks.Warp to clarify that mode='nearest' results in zero gradients almost everywhere, effectively blocking gradient flow in registration training.

Changes:

Added a note to the Warp docstring about the gradient behavior of mode='nearest'.

Added a reference to the semi-supervised registration tutorial: https://github.com/Project-MONAI/tutorials/blob/main/3d_registration/learn2reg_oasis_unpaired_brain_mr.ipynb

Next Steps (future PR):

Extend VoxelMorph.forward to handle optional label and keypoint arguments for consistent warping behavior.

Types of changes

• [x] Non-breaking change (fix or new feature that would not break existing functionality).
• [ ] Breaking change (fix or new feature that would cause existing functionality to change).
• [ ] New tests added to cover the changes.
• [ ] Integration tests passed locally by running ./runtests.sh -f -u --net --coverage.
• [ ] Quick tests passed locally by running ./runtests.sh --quick --unittests --disttests.
• [x] In-line docstrings updated.
• [x] Documentation updated, tested make html command in the docs/ folder.

[coderabbitai[bot]]

Walkthrough

This PR adds an informational note to the Warp class constructor docstring in monai/networks/blocks/warp.py. The note states that using mode="nearest" yields non-differentiable warping (near-zero gradients), recommends bilinear/trilinear interpolation for learning-based registration, and includes a reference/example notebook link. No code logic or control flow is modified.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

• Pure docstring addition in one file; no behavioral changes.

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title directly matches the main change: adding a differentiability warning for Warp with mode='nearest' to documentation.
Description check	✅ Passed	Description covers all required template sections: fixes issue reference, clear description of changes, types marked appropriately, and inline docstrings/documentation updated.
Linked Issues check	✅ Passed	PR fulfills #8540 requirements: adds clear warning about non-differentiability of mode='nearest' in Warp docstring and provides learning resource reference.
Out of Scope Changes check	✅ Passed	Changes are confined to docstring updates in Warp.init; no code logic changes. Future VoxelMorph work noted as out of scope for this PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

📥 Commits

Reviewing files that changed from the base of the PR and between 7adf291ac21e6d9450c68bec8b1b40494a28fa0b and 5f5936ea74a80aec7d49d1bdc977ef7b28ac6c4f.

📒 Files selected for processing (1)

• monai/networks/blocks/warp.py (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• monai/networks/blocks/warp.py

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (19)

• GitHub Check: packaging
• GitHub Check: build-docs
• GitHub Check: quick-py3 (macOS-latest)
• GitHub Check: flake8-py3 (mypy)
• GitHub Check: quick-py3 (windows-latest)
• GitHub Check: quick-py3 (ubuntu-latest)
• GitHub Check: flake8-py3 (pytype)
• GitHub Check: flake8-py3 (codeformat)
• GitHub Check: min-dep-os (windows-latest)
• GitHub Check: min-dep-os (macOS-latest)
• GitHub Check: min-dep-py3 (3.12)
• GitHub Check: min-dep-os (ubuntu-latest)
• GitHub Check: min-dep-pytorch (2.8.0)
• GitHub Check: min-dep-pytorch (2.7.1)
• GitHub Check: min-dep-py3 (3.10)
• GitHub Check: min-dep-py3 (3.9)
• GitHub Check: min-dep-pytorch (2.6.0)
• GitHub Check: min-dep-py3 (3.11)
• GitHub Check: min-dep-pytorch (2.5.1)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[KumoLiu]

/build

[KumoLiu]

/build