Installation

Quick Start (All Platforms)

Install Miniconda (if not already installed):
- Download from Anaconda
- Follow platform-specific installation instructions
Clone and Install KINTSUGI:

# Clone the repository
git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI

# Create conda environment (choose your platform)
# Linux:
conda env create -f envs/env-linux.yml

# Windows:
conda env create -f envs/env-windows.yml

# macOS:
conda env create -f envs/env-macos.yml

# Activate and verify
conda activate KINTSUGI
kintsugi check

Verify Installation:

kintsugi check

Windows Installation

Option A: Using Installation Script (Recommended)

# Open PowerShell as Administrator
cd C:\Users\[your username]
git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI

# Run installation script
.\scripts\install.ps1

Option B: Manual Installation

# Open Anaconda Prompt
conda update -n base conda
conda install -n base conda-libmamba-solver
conda config --set solver libmamba

# Clone repository
cd C:\Users\[your username]
git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI

# Create environment
conda env create -f envs/env-windows.yml
conda activate KINTSUGI

Download Windows Dependencies

Windows requires additional binary dependencies from Zenodo:

Download from: https://zenodo.org/records/14969214
Extract to the KINTSUGI folder:
- PyVips-dev-8.16 (required for image I/O)

Note: Java, Maven, and FIJI are no longer required. KINTSUGI now uses pure Python implementations (CuPy/NumPy) for all processing including EDF.

Linux Installation

Option A: Using Installation Script (Recommended)

git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI
chmod +x scripts/install.sh
./scripts/install.sh

Option B: Manual Installation

# Install system dependencies (Java/Maven no longer required)
sudo apt-get update
sudo apt-get install -y libvips-dev

# Clone and setup
git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI

conda env create -f envs/env-linux.yml
conda activate KINTSUGI

macOS Installation

# Install system dependencies (Java/Maven no longer required)
brew install vips

# Clone and setup
git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI

conda env create -f envs/env-macos.yml
conda activate KINTSUGI

GPU Acceleration (Optional)

KINTSUGI supports multi-GPU acceleration for significantly faster processing.

Basic GPU Support (CuPy + PyTorch)

For GPU-accelerated deconvolution, stitching, and denoising:

# Install via kintsugi CLI (recommended)
kintsugi install gpu

# Or manually for CUDA 12.x
pip install cupy-cuda12x torch torchvision

# Or for CUDA 11.x
pip install cupy-cuda11x torch torchvision

Multi-GPU Support

KINTSUGI automatically detects and uses all available non-integrated NVIDIA GPUs:

from kintsugi.gpu import get_gpu_manager

# Check available GPUs
gpu = get_gpu_manager()
print(gpu.summary())
# Output: Found 2 GPU(s):
#   [0] NVIDIA A100 (40.0 GB, CC 8.0)
#   [1] NVIDIA A100 (40.0 GB, CC 8.0)

# PyTorch models automatically use DataParallel
from kintsugi.denoise import CAREDenoiser
denoiser = CAREDenoiser()  # Uses all GPUs for inference

# Multi-GPU stitching
from notebooks.Kstitch._translation_computation import get_multi_gpu_accelerator
accelerator = get_multi_gpu_accelerator((1024, 1024))

GPU-Accelerated Image Processing

KINTSUGI uses CuPy for GPU-accelerated image processing operations:

Operation	GPU Acceleration
Illumination Correction	CuPy FFT-based BaSiC algorithm
Stitching	CuPy phase correlation
Deconvolution	CuPy Lucy-Richardson with FFT
Extended Depth of Focus	CuPy variance projection

# Check GPU availability
from kintsugi.gpu import get_gpu_manager
gpu = get_gpu_manager()
print(gpu.summary())

# GPU-accelerated illumination correction
from kintsugi.kcorrect_gpu import KCorrectGPU
corrector = KCorrectGPU(device_id=0)
flatfield, darkfield = corrector.estimate(images)

# Multi-GPU stitching
from notebooks.Kstitch._translation_computation import get_multi_gpu_accelerator
accelerator = get_multi_gpu_accelerator(tile_shape)

GPU-Accelerated Single-Cell Analysis

For GPU-accelerated single-cell analysis (clustering, UMAP, spatial analysis with RAPIDS), see the dedicated repository: rapids_singlecell

External Dependencies

Dependency	Purpose	Installation
libvips	High-performance image I/O	`conda install libvips` (Linux/macOS) or Zenodo (Windows)
VALIS	Image registration	Vendored as `Kreg` (no separate install needed)
CuPy	GPU image processing	`conda install cupy` or `pip install cupy-cuda12x`
PyTorch	Deep learning models (optional)	`pip install torch torchvision`

Note: Java, Maven, and FIJI/CLIJ2 are no longer required. KINTSUGI now uses pure Python implementations (CuPy/NumPy) for all processing including Extended Depth of Focus (EDF).

HPC Installation (SLURM Clusters)

For HPC environments like UF HiPerGator, KINTSUGI provides a dedicated environment file (envs/env-hpc.yml) that installs all dependencies upfront — including GPU/CUDA packages, spatial analysis tools, and workflow orchestration. This avoids the common “install base then install extras” pattern that causes silent failures on HPC.

Quick Start (Recommended)

module load conda
git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI
./scripts/install.sh --hpc

This single command:

Creates the KINTSUGI conda env from envs/env-hpc.yml
Installs PyTorch + CUDA 12.4 via conda (not pip — avoids version conflicts)
Installs CUDA runtime libraries (libcufft, libcublas) needed by CuPy
Deploys LD_LIBRARY_PATH activation scripts (fixes libstdc++ mismatch on old OS kernels)
Copies CUDA headers for CuPy JIT compilation
Applies the SLURM TRES patch for Snakemake
Runs kintsugi check and fails if required dependencies are broken

Manual HPC Installation

If you prefer step-by-step control:

module load conda

# Create environment with full GPU/CUDA/analysis stack
conda env create -f envs/env-hpc.yml
conda activate KINTSUGI

# Deploy LD_LIBRARY_PATH fix + CUDA headers
kintsugi fix-hpc

# CRITICAL: Re-activate to pick up the new LD_LIBRARY_PATH
conda deactivate && conda activate KINTSUGI

# Apply SLURM compatibility patch
kintsugi patch slurm

# Verify everything works
kintsugi check

Fixing a Broken HPC Environment

If kintsugi check shows [MISSING] for packages that ARE installed (scikit-learn, matplotlib, pyvips, stackview), this is the libstdc++ version mismatch — the system’s C++ library is too old and loading before conda’s. Fix without recreating the env:

conda activate KINTSUGI
kintsugi fix-hpc
conda deactivate && conda activate KINTSUGI
kintsugi check

For comprehensive troubleshooting, see HPC Troubleshooting.

env-hpc.yml vs env-linux.yml

Feature	`env-linux.yml` (Desktop)	`env-hpc.yml` (HPC)
PyTorch + CUDA	Not included (install via `kintsugi install gpu`)	Included via conda pytorch channel
CUDA runtime libs	Not included	`cuda-libraries`, `cuda-cudart-dev`
libstdcxx-ng	Not pinned	Pinned `>=12.0` (fixes GLIBCXX mismatch)
scanpy/analysis	Not included (install via `kintsugi install analysis`)	Included via conda-forge
Napari	Not included	Not included (no display on HPC)
Snakemake/SLURM	Included	Included
Target use	Workstations, laptops	SLURM clusters (HiPerGator, etc.)

HPC-Specific Notes

Login nodes vs compute nodes: Install on login nodes (no GPU). The env includes torch and CuPy, which are importable without GPU hardware. kintsugi check reporting “CUDA not available” on login nodes is expected.
Never install packages inside SLURM jobs. The conda env must be fully built before submitting.
Cache redirection: SLURM jobs automatically redirect pip/torch/numba caches to /blue/ storage via account-specific scripts.
SLURM TRES patch: SLURM >= 24.11 requires kintsugi patch slurm. This is auto-applied by install.sh --hpc and kintsugi install all.
Verification: Run ./scripts/verify_hpc_env.sh for a comprehensive environment check beyond kintsugi check.

Updating Existing Projects

When you update the KINTSUGI repository (git pull), project copies of notebooks, modules, and workflow scripts may become stale. See the Updating Existing Projects section in the README for full details.

Key commands:

# Sync notebooks and Python modules to all project folders
python scripts/sync_to_projects.py          # Auto-discovers KINTSUGI_Projects/*/notebooks
python scripts/sync_to_projects.py --dry-run  # Preview changes

# Refresh workflow scripts for a single project
kintsugi workflow config /path/to/project --force

# Bulk-refresh workflow scripts across all projects
for d in /path/to/KINTSUGI_Projects/*/workflow/scripts; do
  cp workflow/scripts/*.py "$d/"
done

Note: A git post-commit hook automatically runs sync_to_projects.py after each commit. Notebooks use %autoreload 2 — no kernel restart needed after module updates.

Verifying Installation

# Check all dependencies including GPU
kintsugi check

# Or via Python
python -c "
from kintsugi.gpu import get_gpu_manager
print(get_gpu_manager().summary())
"