.. _egpu_installation:

Using an External GPU to Run Met.3D
===================================

.. note:: 
    The following description is current as of March 2025.

This guide provides instructions for setting up an external GPU (eGPU) to work with Met.3D on an Ubuntu system. The setup has been tested with specific hardware configurations, but different GPUs, eGPU enclosures, and operating system versions may require adjustments.

Prerequisites
-------------

We used for our testing the following setup:

- **eGPU Enclosure:** SoNNeT eGFX Breakaway Box 750ex
- **Laptop:** Dell Latitude 7430
- **Operating System:** Ubuntu 22.04 LTS
- **Tested GPUs:**
  
  - NVIDIA Quadro P5000
  - AMD RX 7800 XT

- A **Thunderbolt 3** connection on the laptop is required for proper bandwidth and functionality.
- Secure Boot must be disabled in BIOS (see below for instructions).

Setup Instructions
------------------

Insert and Connect the GPU
~~~~~~~~~~~~~~~~~~~~~~~~~~
   
- Insert the GPU into the eGPU enclosure.
- Connect the enclosure to the laptop via Thunderbolt 3.
- Restart the laptop to ensure hardware detection.

Install Graphics Drivers
~~~~~~~~~~~~~~~~~~~~~~~~

NVIDIA
   - Follow the guide at the `Ubuntu webpage <https://ubuntu.com/server/docs/nvidia-drivers-installation>`_ to find a suitable driver version.
   - In our tests, the latest driver (version 550) did not work with the Quadro P5000, 
     but version 535 was compatible. While we recommend the latest drivers, if you 
     encounter issues, consider downgrading.

AMD
   - Download the appropriate `.deb` driver package from 
     `AMD's support page <https://www.amd.com/en/support/download/linux-drivers.html>`_.
   - Install the package and run the following command to install the drivers::

         amdgpu-install --usecase=graphics

   - For troubleshooting, refer to the `amdgpu documentation <https://amdgpu-install.readthedocs.io/en/latest/>`_.


Enable Unsupported NVIDIA GPUs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some NVIDIA cards require additional configuration by editing the GRUB bootloader configuration, as outlined
in `this NVIDIA forum post <https://forums.developer.nvidia.com/t/nvidia-smi-no-devices-were-found/236462>`_ and
`this reddit post <https://www.reddit.com/r/eGPU/comments/14oocco/any_guides_for_setting_up_an_egpu_on_ubuntu_2204/?show=original>`_.

Edit the file::

   sudo nano /etc/default/grub

Modify the following line::

   GRUB_CMDLINE_LINUX_DEFAULT="quiet splash nvidia.NVreg_OpenRmEnableUnsupportedGpus=1"

Update GRUB and reboot::

   sudo update-grub
   sudo reboot


Install eGPU Switcher
~~~~~~~~~~~~~~~~~~~~~

- Install the `eGPU Switcher <https://github.com/hertg/egpu-switcher>`_, a tool to configure X.Org to 
  prefer the external GPU when detected at startup.
- Follow the setup instructions in the README in the linked git repository.
- If prompted for a specific driver name, leave the input blank.

Disable Secure Boot
~~~~~~~~~~~~~~~~~~~
- Reboot into BIOS and disable Secure Boot.
- Save changes and restart.

Verify GPU Detection
~~~~~~~~~~~~~~~~~~~~
After rebooting, check if the GPU is recognized using::

    glxinfo | grep "OpenGL renderer"

If successful, this should display the name of your external GPU, indicating that Met.3D 
can now utilize it for rendering.

Known issues
------------

This is a list of known issues and their fixes when using an eGPU.

Kernel module loading failed.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the eGPU is connected during boot, the system may encounter errors that prevent proper initialization.
In our testing setup, we observed that an AMD GPU triggered the following error in the kernel module::

   [amdgpu] trn=2 ack should not assert

Through testing, we found that this issue occurs because the Thunderbolt port is disabled early in 
the boot process, preventing the GPU from being detected correctly. To resolve this, ensure that 
Thunderbolt support is enabled in the BIOS and set to "Enabled" or "No Security" so that it remains 
active during boot.