Skip to main content

Build NeuS2 on HPC

· 3 min read
Rafoolin

Overview​

This tutorial explains how to build and configure NeuS2 on an Ubuntu-based system, specifically within the FAU HPC environment.

While the official NeuS2 repository provides general installation instructions, HPC systems typically require additional configuration steps due to module management, CUDA compatibility, and compilation constraints.

In this guide, we will:

  • Clone and prepare the NeuS2 repository
  • Set up a Conda environment
  • Configure CUDA and compiler modules on FAU HPC
  • Install PyTorch and PyTorch3D
  • Resolve common compilation issues
  • Build NeuS2 successfully
  • Run a sample dataset (DTU Scan24)

Build​

Official repository:

👉 https://github.com/19reborn/NeuS2

1. Clone the Repository​

If you encounter timeout issues on the HPC cluster, configure the proxy first:

export http_proxy=http://proxy:80
export https_proxy=http://proxy:80

Then clone recursively:

git clone --recursive https://github.com/19reborn/NeuS2
cd NeuS2

2. Allocate a GPU (Interactive Job)​

For compilation and testing, request a GPU node.

Documentation:

👉 https://doc.nhr.fau.de/clusters/tinygpu/#interactive-jobs

Example using tinyx with RTX 3080:

salloc.tinygpu --gres=gpu:rtx3080:1 --time=02:00:00

After allocation, proceed with environment setup.

Note: Use squeue to check on active shells and by scancel ID cancel the ones you don't want!

3. Create Conda Environment​

conda create -n neus2 python=3.9
conda activate neus2
pip install -r requirements.txt

Then based on NeuS2 guidance, we need to install pytorch and pytorch3d and if you meet problems of compiling, you may find solutions here.

But I continue it like the following:

4. Load Required HPC Modules​

Load system modules before installing PyTorch:

module load python/3.12-conda
module load cuda/12.6.2
module load gcc/11.5.0
module load cmake

These ensure compatibility with CUDA 12.6 and proper C++ compilation.

5. Install PyTorch (CUDA 12.6)​

Install PyTorch matching CUDA 12.6:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

Verify CUDA detection:

python -c "import torch; print(torch.cuda.is_available())"

6. Install PyTorch3D​

PyTorch3D requires build tools:

python -m pip install -U pip setuptools wheel ninja
python -m pip install -U iopath fvcore
python -m pip install --no-build-isolation "git+https://github.com/facebookresearch/pytorch3d.git"

If compilation errors occur, check troubleshooting compile errors.

7. Install Additional Dependencies​

Install required X11 and rendering libraries:

conda install -c conda-forge \
  xorg-libxrandr \
  xorg-libx11 \
  xorg-libxext \
  xorg-libxrender \
  xorg-libxinerama \
  xorg-libxcursor \
  xorg-libxi \
  xorg-xorgproto
python -m pip install lpips

Set environment variables:

export CMAKE_PREFIX_PATH=$CONDA_PREFIX:$CMAKE_PREFIX_PATH
export PKG_CONFIG_PATH=$CONDA_PREFIX/lib/pkgconfig:$PKG_CONFIG_PATH

8. Build NeuS2​

rm -rf build
cmake . -B build
cmake --build build -j

If the build completes successfully, NeuS2 is ready.

Run NeuS2​

Download the DTU Scan24 sample dataset and run the code similar to the following:

python scripts/run.py \
  --scene ../data/dtu_scan24/transform.json \
  --name dtu_sample \
  --network dtu.json \
  --n_steps 100

If everything is configured correctly, NeuS2 should begin training and produce sample outputs.

Happy coding! 👩‍💻