Installation — NVIDIA nvmath-python (original) (raw)

Install nvmath-python#

nvmath-python, like most modern Python packages, provides pre-built binaries (wheels and conda packages) to the end users. The full source code is hosted in theNVIDIA/nvmath-python repository.

In terms of CUDA Toolkit (CTK) choices, nvmath-python is designed and implemented to allow building and running against 1. pip-wheel, 2. conda, or 3. system installation of CTK. Having a full CTK installation at either build- or run-time is not necessary; only a small subset, as explained below, is enough.

Host & device APIs (see Overview) have different run-time dependencies and requirements. Even among host APIs the needed underlying libraries are different (for example, fft() on GPUs only needs cuFFT and not cuBLAS). Libraries are loaded when only needed. Therefore, nvmath-python is designed to have most of its dependencies optional, but provides convenient installation commands for users to quickly spin up a working Python environment.

The cheatsheet below captures nvmath-python’s required and optional build-time and run-time dependencies. Using the installation commands from the sections below should support most of your needs.

Install from PyPI#

The pre-built wheels can be pip-installed from the public PyPI. There are several optional dependencies expressible in the standard “extras” bracket notation. The following assumes that CTK components are also installed via pip (so no extra step from users is needed; the dependencies are pulled via extras).

The options below are for adventurous users who want to manage most of the dependencies themselves. The following assumes that system CTK is installed.

For system admins or expert users, pip install nvmath-python would be a bare minimal installation (very lightweight). This allows fully explicit control of all dependencies.

Install from conda#

Conda packages can be installed from the conda-forge channel.

Notes:

• For expert users, conda install -c conda-forge nvmath-python=*=core* would be a bare minimal installation (very lightweight). This allows fully explicit control of all dependencies.
• If you installed conda from miniforge, most likely the conda-forge channel is already set as the default, then the -c conda-forge part in the above instruction can be omitted.

Build from source#

Once you clone the repository and go into the root directory, you can build the project from source. There are several ways to build it since we need some CUDA headers at build time.

Notes:

• If you add the “extras” notation after the dot . (for example .[cu11],.[cu12,dx], …), it has the same meaning as explained in the previous section.
• If you don’t want the run-time dependencies to be automatically handled, add --no-depsafter the pip install command above; in this case, however, it’s your responsibility to make sure that all the run-time requirements are met.
• By replacing install by wheel, a wheel can be built targeting the current OS and CPython version.
• If you want inplace/editable install, add the -e flag to the command above (before the dot .). This is suitable for local development with a system-installed CTK. However, our wheels rely on non-editable builds so that the RPATH hack can kick in. DO NOT pass the -e flag when building wheels!
• All optional run-time dependencies as listed below need to be manually installed.

Cheatsheet#

Below we provide a summary of requirements to support all nvmath-python functionalities. A dependency is required unless stated otherwise.

Test Configuration#

nvmath-python is tested in the following environments:

Run nvmath-python#

As mentioned earlier, nvmath-python can be run with all methods of CUDA installation, including wheels, conda packages, and system CTK. As a result, there is detection logic to discover shared libraries (for host APIs) and headers (for device APIs to do JIT compilation).

Shared libraries#

• pip wheels: Will be auto-discovered if installed
• conda packages: Will be auto-discovered if installed, after wheel
• system CTK: On Linux, the users needs to ensure the shared libraries are discoverable by the dynamic linker, say by setting LD_LIBRARY_PATH or updating system search paths to include the DSO locations.

Host APIs#

This terminology is explained in the Host APIs.

Examples#

See the examples directory in the repo. Currently we have:

• examples/fft
• examples/linalg

Tests#

The requirements/pip/tests.txt file lists dependencies required for pip-controlled environments to run tests. These requirements are installed via the mainrequirements/pip-dev-<name>.txt files.

Running functionality tests#

pytest tests/example_tests tests/nvmath_tests/fft tests/nvmath_tests/linalg

Running performance tests#

This will currently run two tests for fft and one test for linalg:

pytest -v -s -k 'perf' tests/nvmath_tests/fft/ pytest -v -s -k 'perf' tests/nvmath_tests/linalg/

Device APIs#

This terminlogy is explained in the Device APIs.

Examples#

See the examples/device directory in the repo.

Tests#

Running functionality tests#

pytest tests/nvmath_tests/device examples/device

Running performance tests#

pytest -v -s -k 'perf' tests/nvmath_tests/device/

Troubleshooting#

For pip-users, there are known limitations (many of which are nicely captured in thepypackaging community project) in Python packaging tools. For a complex library such as nvmath-python that interacts with many native libraries, there are user-visible caveats.

1. Be sure that there are no packages with both -cu11 (for CUDA 11) and -cu12 (for CUDA 12) suffices coexisting in your Python environment. For example, this is a corrupted environment:
   $ pip list
   Package Version

nvidia-cublas-cu11 11.11.3.6
nvidia-cublas-cu12 12.5.2.13
pip 24.0
setuptools 70.0.0
wheel 0.43.0
Sometimes such conflicts could come from a dependency of the libraries that you use, so pay extra attention to what’s installed. 2. pip does not attempt to check if the installed packages can actually be run against the installed GPU driver (CUDA GPU driver cannot be installed by pip), so make sure your GPU driver is new enough to support the installed -cuXX packages [2]. The driver version can be checked by executing nvidia-smi and inspecting the Driver Version field on the output table. 3. CuPy installed from pip currently (as of v13.3.0) only supports conda and system CTK, and not pip-installed CUDA wheels. nvmath-python can help CuPy use the CUDA libraries installed to site-packages (where wheels are installed to) if nvmath is imported. From beta 2 (v0.2.0) onwards the libraries are “soft-loaded” (no error is raised if a library is not installed) when import nvmath happens. This behavior may change in a future release. 4. Numba installed from pip currently (as of v0.60.0) only supports conda and system CTK, and not pip-installed CUDA wheels. nvmath-python can also help Numba use the CUDA compilers installed to site-packages if nvmath is imported. Same as above, this behavior may change in a future release.

In general, mixing-and-matching CTK packages from pip, conda, and the system is possible but can be very fragile, so it’s important to understand what you’re doing. The nvmath-python internals are designed to work with everything installed either via pip,conda, or local system (system CTK, including tarball extractions, are the fallback solution in the detection logic), but mix-n-match makes the detection logic impossible to get right.

To help you perform an integrity check, the rule of thumb is that every single package should only come from one place (either pip, or conda, or local system). For example, if both nvidia-cufft-cu11 (which is from pip) and libcufft (fromconda) appear in the output of conda list, something is almost certainly wrong. Below is the package name mapping between pip and conda, with XX={11,12}denoting CUDA’s major version:

Note that system packages (by design) do not show up in the output of conda list orpip list. Linux users should check the installation list from your distro package manager (apt, yum, dnf, …). See also the Linux Package Manager Installation Guide for additional information.

For more information with regard to the new CUDA 12+ package layout on conda-forge, see theCUDA recipe README.

Footnotes