---

name: cuda-extensions description: "Safely diagnose and plan use of this repository's legacy 2D/3D NMS and RoIAlign CUDA extensions without compiling or treating precompiled binaries as portable." metadata: disco-role: operating disable-model-invocation: true license: Apache 2.0

Legacy CUDA extensions

Use this sub-skill when a model import, proposal stage, RoIAlign call, or installation question reaches cuda_functions/. It is an operating guide for compatibility diagnosis and source-backed interface selection, not a build recipe to execute automatically.

Non-negotiable boundaries

• Do not run build.py from this skill. It invokes the removed torch.utils.ffi.create_extension API and can write native build output. scripts/check_legacy_cuda_compat.py is the read-only diagnostic entry point.
• Do not compile the checked-in CUDA sources as part of normal diagnosis. The host has no nvcc, and source modernization plus ABI validation is a separate engineering task.
• Treat exact execution of the historical detector path as optional/unverified. This includes MRCNN/U-FRCNN/RetinaNet/Retina U-Net runs that import the custom operators. A framework-level CUDA tensor smoke is evidence only for PyTorch and the driver; it is not evidence that these extensions work.
• There is no CPU substitute for claiming exact legacy detector execution. The source contains nms_cpu, and RoIAlign has a CPU branch, but using those branches does not verify the model's imported nms_gpu/legacy CUDA ABI path. Do not silently change a CUDA failure into a CPU result.
• Do not load or inspect the checked-in *.so, *.o, or swap files as runtime evidence. They are host- and ABI-specific artifacts; the source and wrappers are the portable evidence.

For a one-command, non-mutating report, run from the repository root:

python skills/disco/medical-detection-toolkit/sub-skills/cuda-extensions/scripts/check_legacy_cuda_compat.py \
  --repo-root .

Add --framework-cuda-smoke only when a tiny PyTorch allocation is safe on the selected GPU. Read compatibility before interpreting the result, then use troubleshooting for a stop/route decision.

Current verified classification

The prepared inspection stack reports a modern CUDA-capable PyTorch wheel, CUDA available, and an A100-class (sm_80) device. The host driver reports CUDA 13.0. nvcc is absent and torch.utils.ffi cannot be imported. The repository pins torch==0.4.1 and its README describes precompiled TitanX-era operators. Therefore the current host is useful for a safe PyTorch CUDA smoke and static inspection, but it is not a verified environment for the legacy operators or exact detector path. These facts are recorded with evidence in compatibility.md; do not weaken this classification because nvidia-smi reports a newer driver or because a .so file exists.

Routing procedure

1. Run the read-only checker. Record the Python interpreter, torch/driver facts, presence of torch.utils.ffi, nvcc, README architecture mappings, build inputs, and native artifacts. The checker never imports a custom extension and never calls build.py.
2. Separate framework CUDA from custom-op CUDA. If the optional framework smoke succeeds, report only that torch.cuda can allocate and execute a tiny tensor on the selected device. A failure due to device memory, device selection, or driver state is a host issue; it still does not justify trying the legacy extension.
3. Check dimensionality before reading signatures. cf.dim == 2 routes model proposal/detection NMS to 2D; a 3D configuration routes to 3D. The Mask/Faster R-CNN family additionally routes feature maps to the direct ra2D or ra3D function wrapper. See custom-ops.md.
4. Classify compatibility blockers. Missing torch.utils.ffi, missing nvcc, an unsupported architecture, or an unverified precompiled binary is a stop condition—not a prompt to patch imports, symlink libraries, or use CPU silently.
5. Route upward. For model selection, configuration, tensor shapes, and output contracts, continue with models-and-architectures. For prediction, postprocessing, 2D-to-3D merging, and saved-result behavior, continue with inference-and-evaluation. Return here only for custom-op import/build/ABI diagnosis.

Interfaces at a glance

NMS

• cuda_functions/nms_2D/pth_nms.py:nms_gpu(dets, thresh) accepts a contiguous tensor with columns (y1, x1, y2, x2, score), sorts by column 4, calls the legacy _ext.nms.gpu_nms, and returns selected indices on CUDA. Its explicit nms_cpu uses the same five-column convention but is not a CUDA execution substitute.
• cuda_functions/nms_3D/pth_nms.py:nms_gpu(dets, thresh) accepts (y1, x1, y2, x2, z1, z2, score), sorts by the final column, calls the same legacy symbol, and returns selected CUDA indices. Its nms_cpu uses the seven-column convention.
• Both native implementations use inclusive +1 extents in IoU and suppress when overlap is >= thresh on CPU. The CUDA kernels use a 64-bit suppression mask with 64 threads per block and perform the final keep scan on CPU.
• models/mrcnn.py, models/ufrcnn.py, models/retina_net.py, and models/retina_unet.py import nms_gpu directly for RPN and/or final detection suppression. These imports make exact legacy detector execution depend on the custom extension even when ordinary PyTorch CUDA is healthy.

RoIAlign / crop-and-resize

• The 2D direct wrapper is cuda_functions/roi_align_2D/roi_align/crop_and_resize.py:CropAndResizeFunction. Construct it as (crop_height, crop_width, extrapolation_value=0) and call it with (image, boxes, box_ind). The image is N,C,H,W; boxes are M,4 normalized (y1,x1,y2,x2); box_ind is length M; output is M,C,crop_height,crop_width.
• The 3D direct wrapper is cuda_functions/roi_align_3D/roi_align/crop_and_resize.py:CropAndResizeFunction. Construct it as (crop_height, crop_width, crop_zdepth, extrapolation_value=0). Its intended image is N,C,H,W,Z, boxes are M,6 normalized (y1,x1,y2,x2,z1,z2), and output is M,C,crop_height,crop_width,crop_zdepth.
• models/mrcnn.py and models/ufrcnn.py call the direct wrappers as ra2D or ra3D in pyramid_roi_align; model ROIs are normalized and include a batch-index column before the wrapper separates boxes and batch_ixs.
• The optional RoIAlign classes in roi_align.py accept pixel-coordinate boxes in an (x1,y1,x2,y2) docstring and normalize them when transform_fpcoor=True. The 2D class is coherent with the 2D constructor. The checked-in 3D RoIAlign class is not a reliable 3D interface: it has a 2D docstring/coordinate split and calls CropAndResizeFunction without the required crop_zdepth. Use the direct 3D wrapper facts above and treat this class as source evidence of drift, not as verified API.

For exact argument and dispatch details, follow the linked custom-ops reference. For model-level shape and configuration contracts, follow models-and-architectures.

Build prerequisites (read-only planning only)

The README's historical sequence manually compiles an architecture-specific CUDA object with nvcc, then invokes the per-op build.py:

cuda_functions/nms_xD/src/cuda/
nvcc -c -o nms_kernel.cu.o nms_kernel.cu -x cu -Xcompiler -fPIC -arch=[arch]
python build.py

cuda_functions/roi_align_xD/roi_align/src/cuda/
nvcc -c -o crop_and_resize_kernel.cu.o crop_and_resize_kernel.cu -x cu -Xcompiler -fPIC -arch=[arch]
python build.py

The README examples map TitanX to sm_52, GTX 960M to sm_50, and GTX 1070/1080(Ti) to sm_61; they do not document A100 sm_80. Each build.py uses torch.utils.ffi.create_extension, old TH/THC tensor APIs, C/CUDA sources, and a precompiled .cu.o in extra_objects. This means all of the following are prerequisites for a real legacy build: a matching historical PyTorch/FFI ABI (the package pins 0.4.1), C/CUDA compiler headers and runtime, nvcc, a target architecture flag, and compatible source/build tooling. A CUDA-capable driver alone is insufficient. Never turn this planning section into an unreviewed build command; use the checker and stop on the blockers in troubleshooting.

Review checklist

Before handing a CUDA issue to another skill or user, record:

• the exact cf.dim, model family, and whether the failure is at NMS, RoIAlign, import, or build planning;
• the input shape/column convention and whether tensors are contiguous and on CUDA;
• checker output for torch, torch.utils.ffi, nvcc, device capability, and README arch mapping;
• whether a checked-in binary was merely present or actually verified (the default is not verified);
• a clear optional/unverified label for exact detector execution, with no CPU substitution; and
• the next route: models/configuration, inference/result handling, or a separate source-modernization project.

All bundled material is cross-linked here: custom-ops.md, compatibility.md, troubleshooting.md, and check_legacy_cuda_compat.py.