Installation¶

Requirements¶

CardamomOT requires Python ≥ 3.8. Core dependencies (NumPy, SciPy, PyTorch, AnnData, POT, …) are installed automatically.

Step 1 — Create a virtual environment¶

With conda (recommended)¶

conda create -n cardamom_env python=3.12 -y
conda activate cardamom_env

Important

macOS Apple Silicon (arm64) — install Numba and its threading runtimes from conda-forge before pip-installing CardamomOT, to avoid the No threading layer error:

conda install -c conda-forge numba llvmlite llvm-openmp tbb tbb-devel -y

With venv¶

python -m venv cardamom_env
source cardamom_env/bin/activate      # Linux / macOS
# cardamom_env\Scripts\activate       # Windows

Step 2 — Install CardamomOT¶

Clone the repository and install in editable mode:

git clone https://github.com/eliasventre/CardamomOT.git
cd CardamomOT
pip install -e .

The cardamomot command and all dependencies (including visualization tools) are installed by default. Optional extras:

Extra	Command	Adds
`dev`	`pip install -e ".[dev]"`	pytest, black, flake8
`notebooks`	`pip install -e ".[notebooks]"`	Jupyter, scVelo

Step 3 — Verify¶

cardamomot --help

You should see the three sub-commands: run, pipeline, and step.

Troubleshooting¶

command not found: cardamomot

The cardamomot script is installed into your environment’s bin/ directory. Make sure the environment is activated before running it.

# With conda — always activate first:
conda activate cardamom_env
cardamomot --help

# Verify where the script was installed:
python -c "import sys; print(sys.prefix + '/bin/cardamomot')"

# Fallback that always works regardless of PATH:
python -m CardamomOT.cli --help

On HPC clusters, if ~/.local/bin is not in your PATH, add it:

export PATH="$HOME/.local/bin:$PATH"

No threading layer could be loaded (Numba)

Install Numba from conda-forge as described in the Apple Silicon note above.

ModuleNotFoundError: No module named 'scanpy'

Run pip install -e . again — scanpy is a core dependency and should be installed automatically. If the error persists, install it explicitly: pip install scanpy.