.. _gpu-setup: ========= GPU Setup ========= NeurEco can leverage NVIDIA GPUs for accelerated training. This page explains how to install the required GPU drivers. .. contents:: On this page :local: :depth: 2 Requirements ============ To use GPU acceleration with NeurEco, you need: - An NVIDIA GPU with **compute capability 7.5 or higher** - An NVIDIA GPU driver at least as recent as the minimum version in `NVIDIA Driver Version`_; we recommend the version given there or a later one - For the Python library, a GPU edition of NeurEco and the CUDA build of PyTorch (see below) .. note:: To check your GPU's compute capability, visit the `NVIDIA CUDA GPUs page `_. No CUDA toolkit is needed: the desktop app and the ``neureco`` command include the CUDA libraries they use, and the Python library uses the CUDA libraries that come with PyTorch. The CPU-only edition of the ``neureco`` package does not use the GPU. A GPU edition comes from the Adagos package index for your PyTorch version, and pip takes the CUDA build of PyTorch from the PyTorch package index (on Windows, PyTorch from PyPI is CPU-only). For PyTorch 2.9, on Windows and Linux: .. code-block:: shell pip install "neureco~=5.0" --extra-index-url https://download.pytorch.org/whl/cu128 --extra-index-url https://adagos.com/downloads/neureco5/whl/torch2.9/ If you installed the CPU-only edition before, run ``pip uninstall neureco torch`` first. The version of a GPU edition ends with its PyTorch and CUDA build, for example ``5.0.1974+torch2.9.cu128`` on Windows; on Linux, the PyTorch 2.9 and 2.8 editions end in ``cu129`` and run with the CUDA 12.8 build of PyTorch. For PyTorch 2.8 or 2.7, see :ref:`installation`. NVIDIA Driver Version --------------------- NeurEco 5.0 uses CUDA 12: the desktop app and the ``neureco`` command include CUDA 12.9, and the GPU editions of the Python library use the CUDA 12 libraries of the PyTorch build installed with them. .. list-table:: :header-rows: 1 :widths: 40 30 30 * - Driver version - Linux - Windows * - Minimum - 525.60.13 - 527.41 * - Recommended - 575.51.03 or newer - 576.02 or newer The minimum versions run CUDA 12 through NVIDIA's CUDA minor version compatibility. The recommended versions are the drivers of CUDA 12.9, the version included with NeurEco. Use them in particular with GeForce RTX 50 series GPUs and other GPUs of compute capability 9.0 or higher. To see the installed driver version, run ``nvidia-smi``: it prints the version in its first lines. Windows Installation ==================== Step 1: Download the Driver --------------------------- Download the latest NVIDIA driver for your GPU from the `NVIDIA Driver Downloads page `__. Step 2: Install --------------- 1. Launch the downloaded installer 2. Follow the on-screen instructions 3. Restart your computer when prompted Step 3: Verify -------------- Open a command prompt and run: .. code-block:: shell nvidia-smi You should see information about your GPU and driver version. Linux Installation (Debian/Ubuntu) ================================== Steps 1 to 3 are for Ubuntu. On Debian, enable the ``contrib``, ``non-free`` and ``non-free-firmware`` components in your APT sources (``/etc/apt/sources.list`` or ``/etc/apt/sources.list.d/debian.sources``), run ``sudo apt update`` and ``sudo apt install linux-headers-amd64 nvidia-driver`` (see the `Debian wiki `__), then continue with Step 4. Step 1: Add the Repository -------------------------- Open a terminal and add the NVIDIA driver repository: .. code-block:: shell sudo add-apt-repository ppa:graphics-drivers/ppa sudo apt update Step 2: Find Available Drivers ------------------------------ List available driver versions: .. code-block:: shell ubuntu-drivers list Or check the `NVIDIA Unix Drivers page `_ for the latest version. Step 3: Install the Driver -------------------------- Install the latest driver (replace ``VERSION_NUMBER`` with the highest version from the list): .. code-block:: shell sudo apt install nvidia-driver-VERSION_NUMBER For example: .. code-block:: shell sudo apt install nvidia-driver-580 Step 4: Reboot -------------- Restart your computer to load the new driver: .. code-block:: shell sudo reboot Step 5: Verify -------------- After rebooting, verify the installation: .. code-block:: shell nvidia-smi Linux Installation (Red Hat) ============================ These steps are for Red Hat Enterprise Linux 9 and compatible distributions. For other releases, see the `NVIDIA Driver Installation Guide `__. Step 1: Enable EPEL Repository ------------------------------ .. code-block:: shell sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm Step 2: Install the Driver -------------------------- Add the NVIDIA repository and install the driver: .. code-block:: shell sudo dnf config-manager --add-repo https://developer.download.nvidia.com/compute/cuda/repos/rhel9/x86_64/cuda-rhel9.repo sudo dnf module enable nvidia-driver:open-dkms sudo dnf install nvidia-open Or download directly from the `NVIDIA Driver Downloads page `_. Step 3: Reboot and Verify ------------------------- .. code-block:: shell sudo reboot nvidia-smi Verifying GPU Usage in NeurEco ============================== In Python, check that PyTorch can see your GPU (the NeurEco Python library uses the PyTorch installed in your environment): .. code-block:: python import torch # Check if CUDA is available print(f"CUDA available: {torch.cuda.is_available()}") # Check GPU name if torch.cuda.is_available(): print(f"GPU: {torch.cuda.get_device_name(0)}") During training, you can monitor GPU usage with ``nvidia-smi``: .. code-block:: shell # Run in a separate terminal during training nvidia-smi -l 1 Troubleshooting =============== **"CUDA not available" in Python** - Ensure the NVIDIA driver is installed (``nvidia-smi`` should work) - Reinstall NeurEco with the CUDA build of PyTorch (on Windows, PyTorch from PyPI is CPU-only). For PyTorch 2.9: .. code-block:: shell pip uninstall neureco torch pip install "neureco~=5.0" --extra-index-url https://download.pytorch.org/whl/cu128 --extra-index-url https://adagos.com/downloads/neureco5/whl/torch2.9/ For PyTorch 2.8 or 2.7, use the package indexes of your edition, given in :ref:`installation`. **"CUDA driver version is insufficient for CUDA runtime version"** or **"the provided PTX was compiled with an unsupported toolchain"** - The NVIDIA driver is older than NeurEco needs: install at least the recommended version in `NVIDIA Driver Version`_, then restart the computer **"Driver/library version mismatch"** - Reboot your computer - If the issue persists, reinstall the NVIDIA driver **"Compute capability too low"** - Your GPU is too old for NeurEco. GPUs with compute capability below 7.5 are not supported. - Consider upgrading your GPU or using CPU-only mode **GPU not detected** - Ensure the GPU is properly seated in the PCIe slot - Check that your power supply provides adequate power - On laptops, ensure you're using the discrete GPU (not integrated graphics)