Documentation is not entirely clear about CUDA/cupy installation requirements

[joshuacwnewton]

Is your feature request related to a problem? Please describe.

In one of our processing scripts, we currently perform inference using a MONAI model, and set torch.device to 'cuda' to perform inference on GPU. We use device when loading the models weights, as well as for the sw_device argument of the sliding_window_inference function.

Initially, GPU usage was working OK, I think? But later, it seems we forgot to install the necessary optional dependencies, because we ran into the following error:

  File "python3.9/site-packages/monai/transforms/spatial/array.py", line 2091, in __call__
    img_np = (convert_to_cupy if is_cuda else convert_to_numpy)(img_t, wrap_sequence=True)
  File "python3.9/site-packages/monai/utils/type_conversion.py", line 246, in convert_to_cupy
    data = cp.asarray(data, dtype)
  File "python3.9/site-packages/monai/utils/module.py", line 441, in __getattr__
    raise self._exception
  File "python3.9/site-packages/monai/utils/module.py", line 399, in optional_import
    pkg = __import__(module)  # top level module
monai.utils.module.OptionalImportError: import cupy (No module named 'cupy').

For details about installing the optional dependencies, please visit:
    https://docs.monai.io/en/latest/installation.html#installing-the-recommended-dependencies

Naturally, the thought is to pip install cupy, but this fails, because the actual package is called cupy-cuda12x.

Looking at the list of potential "extras" options, it's not entirely clear how to pick the correct extra to solve this issue. We started with monai[all] just to troubleshoot, and this does fix the problem, but it seems like overkill, installing dependencies we do not actually need. With some guesswork, we learned that monai[cucim] will install cupy. But, even then, it is not 100% clear from the documentation alone if this will install all of the necessary dependencies to perform inference without error.

Describe the solution you'd like

I think it would make sense if the installation section had an "installing MONAI for GPU usage" section that explains that, when is_cuda is true, MONAI will try to use CuPY, and thus [insert blank] dependencies are necessary (monai[cucim])?

It might also help to have an extra specifically called monai[cuda] to make it more discoverable/intuitive. But, if this turns out to just be an alias for monai[cucim], then maybe it's not necessary.

Thank you!

[joshuacwnewton]

Ah, I see now that there is a small section about CUDA that reads:

The installation commands below usually end up installing CPU variant of PyTorch. To install GPU-enabled PyTorch:

• Install the latest NVIDIA driver.
• Check PyTorch Official Guide for the recommended CUDA versions. For Pip package, the user needs to download the CUDA manually, install it on the system, and ensure CUDA_PATH is set properly.
• Continue to follow the guide and install PyTorch.
• Install MONAI using one the ways described below.

In that case I would suggest to give this checklist its own header, and potentially mention cupy here if necessary.

[joshuacwnewton]

Looking into related issues, I see:

• Necessary precautions for CuCIM updates #7452 (comment)

And also add cucim-cu12 as a dependency here: https://github.com/Project-MONAI/MONAI/blob/dev/requirements-dev.txt#L29

cucim-cu12; platform_system == "Linux" and python_version >= "3.9" and python_version <= "3.10"

It turns out that we are using Python 3.9 on Linux, so maybe this is only a corner case for our specific purposes, and that Python 3.11 and above do not require this?