Installing SUSAN¶

SUSAN’s Python layer installs with pip; the pip build step compiles the C++/CUDA engine automatically via CMake. The only mandatory system requirement is an NVIDIA GPU with a supported CUDA toolkit (≥ 10, ≤ 13). All other requirements depend on the chosen installation path.

Method	Best for	Requires	Difficulty
Quick install	Fresh system, all tools	conda only	Easiest
pip into an existing environment	Existing Python env	System cmake/CUDA/gcc	Easy
conda environment with system build tools	New conda env, system tools	System cmake/CUDA/gcc	Easy
Self-contained conda environment (CUDA 12)	New conda env, self-contained	conda only	Moderate
HPC / SLURM clusters	SLURM clusters	Cluster modules	Moderate
Building from source (custom configurations and MATLAB)	Custom builds, MATLAB	System cmake/CUDA/gcc	Advanced

Quick install¶

The fastest path to a fully featured installation on a fresh system. No system compilers or CUDA installation required; everything is managed by conda.

conda env create --file envs/environment_full.yml
conda activate susan-full
conda env update --file envs/environment_susan_devel_cuda12.yml

This creates an environment with Jupyter, Spyder, PyTorch, and all analysis tools, then compiles and installs SUSAN using conda-managed cmake, g++, and the CUDA 12 toolkit.

Prerequisites¶

The following tools must be on PATH before installing (except for the self-contained conda paths, which manage them via conda):

CUDA toolkit ≥ 10 and ≤ 13 (provides nvcc and cuFFT).
CMake ≥ 3.14.
gcc / g++ compatible with the installed CUDA version.
git (for cloning or pip-from-git installs).
OpenMPI (optional): detected automatically by CMake; enables multi-node execution if present.
MATLAB (optional): detected automatically by CMake; enables the MATLAB interface if present.

Note

Eigen3 and LodePNG are fetched automatically by CMake during the build if not already present on the system; no manual installation is needed.

pip into an existing environment¶

If cmake, gcc, and the CUDA toolkit are already on PATH, SUSAN installs directly into any active Python environment.

Core install:

pip install "git+https://github.com/rsanchezloayza/SUSAN"

Optional extras:

PyTorch (required for the Noise2Noise denoiser):

pip install "SUSAN[ml] @ git+https://github.com/rsanchezloayza/SUSAN"

Analysis tools (scikit-image, scikit-learn, numba, bm4d):

pip install "SUSAN[analysis] @ git+https://github.com/rsanchezloayza/SUSAN"

Both:

pip install "SUSAN[full] @ git+https://github.com/rsanchezloayza/SUSAN"

conda environment with system build tools¶

Use this path when cmake, gcc, and the CUDA toolkit are already available system-wide (most Linux workstations with an NVIDIA driver installed).

Step 1 — create and activate the working environment:

Jupyter / VS Code

conda env create --file envs/environment_jupyter.yml
conda activate susan-jupyter

Spyder

conda env create --file envs/environment_spyder.yml
conda activate susan-spyder

Jupyter + Spyder

conda env create --file envs/environment_full.yml
conda activate susan-full

Step 2 — install SUSAN:

conda env update --file envs/environment_susan.yml

Note

The install overlay (environment_susan.yml) carries only NumPy, SciPy, and the pip install step. All other packages (PyTorch, scikit-image, etc.) are already provided by the context environment from Step 1.

Note

The conda environment files use nodefaults to avoid the Anaconda default channel, which has commercial licensing restrictions. Packages are resolved exclusively from pytorch and conda-forge.

Self-contained conda environment (CUDA 12)¶

Use this path when cmake, gcc, or the CUDA toolkit are not available system-wide (e.g., a fresh workstation without a system CUDA installation).

Step 1 — create and activate the working environment:

Jupyter / VS Code

conda env create --file envs/environment_jupyter.yml
conda activate susan-jupyter

Spyder

conda env create --file envs/environment_spyder.yml
conda activate susan-spyder

Jupyter + Spyder

conda env create --file envs/environment_full.yml
conda activate susan-full

Step 2 — install SUSAN with conda-managed build tools:

conda env update --file envs/environment_susan_devel_cuda12.yml

This installs cmake, make, g++, and the CUDA 12 toolkit from conda-forge before invoking the pip build step. No system compilers or CUDA installation are required.

HPC / SLURM clusters¶

On cluster systems, compilers and CUDA are provided by the module system.

Step 1 — create and activate the working environment:

conda env create --file envs/environment_hpc.yml
conda activate susan-hpc

Step 2 — load cluster modules and install SUSAN:

module load cuda cmake gcc        # exact names vary by cluster
module load openmpi               # optional, for multi-node support
pip install "git+https://github.com/rsanchezloayza/SUSAN"

Note

If the PyTorch bundled by the pytorch conda channel does not match the cluster’s CUDA version, install it separately after SUSAN:

pip install torch --index-url https://download.pytorch.org/whl/cu<VER>

Replace <VER> with the numeric CUDA version (e.g., cu121 for CUDA 12.1).

Building from source (custom configurations and MATLAB)¶

Manual compilation is needed when you require a custom CMake configuration, want to build without pip, or need the MATLAB interface.

Clone and compile:

git clone https://github.com/rsanchezloayza/SUSAN
cd SUSAN
mkdir bin && cd bin
cmake ../
make -j

Hint

If CMake cannot locate nvcc automatically, pass it explicitly:

cmake ../ -DCMAKE_CUDA_COMPILER=$(which nvcc)

CMake automatically detects OpenMPI and MATLAB and compiles their respective targets if found.

Install the Python package:

Standard

pip install .

Editable (development)

pip install -e .

MATLAB interface:

No extra steps are required. If MATLAB is found by CMake, the MEX files are compiled and placed in the +SUSAN/ directory automatically. Add the repository root to the MATLAB path:

addpath /path/to/SUSAN