Add warning to documentation that warp in nearest neighbor mode is non differentiable

[Tessel2000]

Is your feature request related to a problem? Please describe.
I spend several days figuring out why my spatial transformer network using a warp layer did not properly train. In the end, the reason is that when using the nearest neighbor mode for the warp layer, the result is non-differentiable.

Pytorch does not give any warnings of this and it is also not mentioned in the documentation of grid_sample.

Describe the solution you'd like
An addition to the documentation of the warp layer that warns users of the non-differentiability of the nearest neighbor mode.

Describe alternatives you've considered
I do not really see any other alternatives, as this modification is so small.

[Kheil-Z]

Nearest-neighbor warping is technically differentiable but produces zero gradients almost everywhere, so it blocks gradient flow during training.

In the semi-supervised registration setting, the correct approach would be to one-hot encode the mask, use bilinear or trilinear warping, and compute the loss on the resulting soft maps.

I do agree it would be useful to add a warning in the documentation when mode="nearest". Beyond that, it could be helpful to have more helper flags for semi-supervised DIR settings to handle these cases automatically (e.g a warp_mask=True in VoxelMorph.forward , and potentially a coordinate transform for keypoints).

Happy to open a PR if this aligns with the maintainers’ direction.