iivs-cardio

A monorepo for deep-learning and bio-imaging research on cardiomyocytes

Requires Python 3.13 or newer and an NVIDIA GPU with a CUDA 13.0-capable driver.

git clone https://github.com/iivs-lab/cardiomyocytes.git
cd cardiomyocytes
uv sync --group dev
uv run python scripts/env/generate_dotenv.py

The first uv sync pulls the CUDA build of torch (~1.8 GB). On Windows, OpenCV additionally needs the one-time cuDNN step below.

generate_dotenv.py writes the .env that every script under scripts/ loads before reading its configuration:

PROJECT_ROOT=/absolute/path/to/cardiomyocytes
CONFIGS_ROOT=${PROJECT_ROOT}/configs

CONFIGS_ROOT is what points hydra at configs/, so a run started from any working directory composes the same configuration. Skip this step and those scripts stop at KeyError: 'CONFIGS_ROOT' before doing any work.

The paths are absolute and machine-specific, so .env is generated per clone rather than committed. It is written once and left alone; re-run with --force after moving the checkout.

The whole stack is pinned to CUDA 13.0 on NVIDIA GPUs and installed by uv sync:

• Python 3.13 or newer
• PyTorch 2.12.1 / torchvision 0.27.1 — from the dedicated PyTorch index (.../whl/cu130) set in pyproject.toml
• OpenCV opencv-contrib-python 4.13.0.90 — a CUDA build (cudawarped wheels) linking the system CUDA 13.0 runtime and cuDNN

On Windows the OpenCV CUDA wheel can't find cuDNN (the cuDNN v9 installer keeps it in its own folder, and Python 3.8+ no longer searches PATH). Run once, in an Administrator PowerShell, to symlink cuDNN where the wheel looks:

./scripts/env/setup-opencv-cuda.ps1

A bare import cv2 then loads the CUDA build in any environment (venv, uv, conda, …). Notes:

• cuDNN from a zip — unpacked into bin\x64: the script no-ops; unpacked elsewhere: pass -CUDNN_PATH <folder>.
• After a cuDNN/CUDA upgrade — re-run to repoint the links.
• Linux — not needed; ld.so finds cuDNN via RPATH / LD_LIBRARY_PATH / ldconfig.

See TODO.md for tracked open items.

See CHANGELOG.md for the version history.

This project is distributed under the terms of the MIT license.