Quickstart

Prerequisites

Python 3.9 or higher

CUDA 12 runtime libraries (for GPU-enabled installation)

Installation

GBRL provides pre-compiled binaries for easy installation. Choose one of the following options:

CPU-only installation (default):

pip install gbrl

GPU-enabled installation (requires CUDA 12 runtime libraries):

pip install gbrl-gpu

Verify installation:

import gbrl
print(gbrl.cuda_available())  # Should return True if GPU installation succeeded

Source Compilation

Prerequisites

• Python 3.9 or higher

• LLVM/OpenMP (macOS)

• CUDA Toolkit 11 or 12 (optional, for GPU acceleration; requires NVCC)

• Graphviz (Optional)

Platform-specific Dependencies

macOS

GBRL requires LLVM and OpenMP. These can be installed using Homebrew:

brew install libomp llvm

CUDA

GBRL compiles CUDA and requires NVCC (source compilation supports CUDA 11 and above).

Ensure that CUDA_PATH is set. Verify that NVCC exists by running the command

nvcc --version

And set CUDACXX to the location of NVCC.

Note

CUDA installation via Anaconda may not install the full CUDAToolkit.

Make sure that Anaconda is up-to-date and run conda install cuda -c nvidia to install the full CUDAToolkit.

Anaconda might still cause issues with CUDA. In such case, set CUDACXX and CUDA_PATH to the non-conda location. For example on Linux, the non-conda location of NVCC can be found by running which nvcc while Anaconda is deactivated.

Note

For integration with Microsoft Visual Studio, copy the following files:

CUDA <cuda_version>.props
CUDA <cuda_version>.targets
CUDA <cuda_version>.xml
Nvda.Build.CudaTasks.v<cuda_version>.dll
cudart.lib

into <visual studio path>\BuildTools\MSBuild\Microsoft\VC\<visual studio version>\BuildCustomizations for Visual Studio 2019 or into <visual studio path>\2022\Community\MSBuild\Microsoft\VC\v170\BuildCustomizations for Visual Studio 2022. <visual studio path> is often found at C:\Program Files\Microsoft Visual Studio. The CUDA files are often found in <cuda_path>\extras\visual_studio_integration\MSBuildExtensions, where <cuda_path> is often found at C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\<cuda version>.

Installation

Advanced users who wish to compile GBRL from source should follow these instructions.

Clone the GBRL repository and install:

git clone <gbrl-repo-url>
cd gbrl
pip install .

Environment Variables

After installation, you may need to set environment variables to ensure that your system correctly locates all necessary files. Here are examples of setting these variables for different operating systems.

### Windows PowerShell using Visual Studio 16 2019 and CUDA 12.4

# PowerShell script to set environment variables
$env:CMAKE_GENERATOR = "Visual Studio 16 2019" # Adjust version as necessary
$env:VS160COMNTOOLS = "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\Common7\Tools"  # Adjust path as necessary
$env:CUDA_PATH = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4"
$env:CUDA_PATH_V12_4 = $env:CUDA_PATH  # Adjust CUDA version as necessary
$env:PATH = "$env:CUDA_PATH\bin;$env:PATH"
$env:INCLUDE = "$env:CUDA_PATH\include;$env:INCLUDE"
$env:LIB = "$env:CUDA_PATH\lib\x64;$env:LIB"
$env:CUDACXX = "$env:CUDA_PATH\bin\nvcc.exe"

### macOS

export PATH="$(brew --prefix llvm)/bin:$PATH"
export LDFLAGS="-L$(brew --prefix libomp)/lib -L$(brew --prefix llvm)/lib -L$(brew --prefix llvm)/lib/c++ -Wl,-rpath,$(brew --prefix llvm)/lib/c++"
export CPPFLAGS="-I$(brew --prefix libomp)/include -I$(brew --prefix llvm)/include"
export CC="$(brew --prefix llvm)/bin/clang"
export CXX="$(brew --prefix llvm)/bin/clang++"
export DYLD_LIBRARY_PATH="$(brew --prefix llvm)/lib:$(brew --prefix libomp)/lib"

### Linux

export CUDA_HOME=/usr/local/cuda
export PATH=$PATH:$CUDA_HOME/bin:/usr/local/bin
export CUDACXX=$CUDA_HOME/bin/nvcc
export CC=/usr/bin/gcc
export CXX=/usr/bin/g++

Explanation: - CMAKE_GENERATOR and CMAKE_GENERATOR_PLATFORM are used by CMake to specify the build system. - CUDA_PATH (or CUDA_HOME for consistency with CUDA-related tools) specifies the location of the CUDA Toolkit. - PATH is updated to include the CUDA binaries. - INCLUDE and LIB are updated to include CUDA headers and libraries. - CUDACXX specifies the location of, NVCC, the CUDA compiler.

Graphviz (Optional)

To enable tree visualization, ensure Graphviz and its development headers are installed and in path before compiling.