Building YRT-PET

Requirements

  • pybind11 if compiling the python bindings (ON by default)

  • CUDA toolkit if compiling using GPU (ON by default)

  • An internet connection to download the cxxopts, nlohmann/json, and catch2 libraries

  • zlib, to read NIfTI images in .nii.gz format, but this is pre-installed in most Unix distributions

Configuration and compilation

From the command-line interface:

git clone git@github.com:YaleBioImaging/yrt-pet.git
cd yrt-pet
mkdir build
cd build
cmake ../yrt-pet/ -DUSE_CUDA=[ON/OFF] -DBUILD_PYBIND11=[ON/OFF]
make

With [ON/OFF] being replaced by the desired configuration

  • The -DUSE_CUDA option enables or disables GPU accelerated code

    • This option is ON by default

  • The -DBUILD_PYBIND11 option enables or disables YRT-PET’s python bindings

    • This option is ON by default

Post-compilation steps

  • (optional) To run unit tests, run ctest -V from the build folder.

  • Install YRT-PET by running cmake --install . --prefix <installation path> from the build folder.

    • This will install YRT-PET’s header files, library, and binary executables in <installation path>

    • A file named install_manifest.txt will be created in the build folder

    • To uninstall, run xargs rm < ./install_manifest.txt

  • To check if GPU was successfully enabled for the project, run yrtpet_reconstruct --help. If the --gpu option appears, the program was compiled with GPU acceleration.

FAQ

  • I get a message that look like Could NOT find ZLIB (missing: ZLIB_LIBRARY ZLIB_INCLUDE_DIR)

    • This means that the zlib library was not found

    • Remedy for Linux:

      • if you use APT: sudo apt install zlib1g-dev

      • if you use YUM: sudo yum install zlib-devel

    • Remedy for macOS:

      • brew install zlib-devel

    • It is a widely used library and is widely available on many platforms. Make sure to check online if the above solutions do not work.

  • I get a message that looks like:

    Could not find a package configuration file provided by "pybind11" with any
of the following names:

  pybind11Config.cmake
  pybind11-config.cmake

Add the installation prefix of "pybind11" to CMAKE_PREFIX_PATH or set
"pybind11_DIR" to a directory containing one of the above files.  If
"pybind11" provides a separate development package or SDK, be sure it has
been installed.

    • This is because the pybind11 library was not found. YRT-PET requires the pybind11 sources and CMake files to compile with python bindings. Several fixes are possible:

      • Disable Python bindings altogether by adding -DBUILD_PYBIND11=OFF to the CMake command

      • If you are using Linux with APT: sudo apt install pybind11-dev

      • On macOS: brew install pybind11

      • Another fix is to install pybind11 using pip or conda. (See documentation for more
        information        )

  • If compiling with GPU acceleration enabled, note that by default, the architecture that the code will be compiled towards will be native. This means that YRT-PET will be compiled for the architecture of the host’s GPU. Note that YRT-PET requires CMake 3.28+ to build the project

    • One can bypass this behavior using one of the two following ways:

      • Set the CUDAARCHS environment variable.

      • Add -DCMAKE_CUDA_ARCHITECTURES=[CUDA architectures list].

    • Example: -DCMAKE_CUDA_ARCHITECTURES="61;75"

    • More information here

  • If compiling with GPU acceleration enabled, make sure the CUDACXX environment variable is set to the location of nvcc. Run echo $CUDACXX to verify this.

  • In order to compile with the python bindings, one needs to have a working python installation or activate a virtual environment.

    • The python bindings will only work for the host’s Python version and only for the CPython implementations.

      • Example: One cannot compile YRT-PET with python bindings using Python 3.10 and expect them to work within Python 3.11

    • To add the YRT-PET python bindings to the python environment, add the build folder to the PYTHONPATH environment variable.

    • To test the python bindings, run: python -c "import pyyrtpet as yrt; print(yrt.compiledWithCuda());"

      • If the PYTHONPATH environment variable is not set or misplaced, the error will look like:

        • ModuleNotFoundError: No module named 'pyyrtpet'

      • If there is a mismatch between the python version used to compile YRT-PET and the environment’s python version, the error will look like:

        • ImportError: No module named pyyrtpet_wrapper._pyyrtpet

      • If the PYTHONPATH environment is properly set and the python versions match, the command will either print True or False.

        • True if the project was compiled with -DUSE_CUDA=ON

        • False if the project was compiled with -DUSE_CUDA=OFF

  • YRT-PET uses std::thread for parallelization. By default, YRT-PET will use the maximum amount of available threads.

  • I get an error that looks like:

    CMake Error at /usr/share/cmake-3.29/Modules/CMakeDetermineCompilerId.cmake:814 (message):
Compiling the CUDA compiler identification source file
"CMakeCUDACompilerId.cu" failed.

...
143 | #error -- unsupported GNU version! gcc versions later than 12 are not supported! The nvcc flag '-allow-unsupported-compiler' can be used to override this version check; however, using an unsupported host compiler may cause compilation failure or incorrect run time execution. Use at your own risk.
|      ^~~~~

    • This is because nvcc tries to use a version of gcc that is not supported by the CUDA toolkit (yet).

    • If you have a different version of gcc installed, you can do: -DCMAKE_CUDA_HOST_COMPILER=g++-11