Installation

MechanoChat requires Python ≥ 3.9 and an NVIDIA GPU.

Note

The simulation kernels are written with numba.cuda and have no CPU fallback, so a CUDA-capable GPU is required to run sem.sim_gpu(...). Importing the package itself works without a GPU.

We recommend Conda or Mamba for environment management. To install Mamba, see miniforge.

Step 1 — Create and activate an environment

mamba create -n mc_39 python=3.9
mamba activate mc_39

Step 2 — Install the CUDA toolkit

mamba install cudatoolkit -c conda-forge   # installs CUDA 11.8 by default

Step 3 — Install MechanoChat with the matching GPU bindings

Check your driver / CUDA version with nvidia-smi, then choose the extra according to your CUDA toolkit major version (step 2 installs 11.x):

pip install "mechanochat[cuda11]"     # for a CUDA 11.x toolkit (default)
# pip install "mechanochat[cuda12]"   # for a CUDA 12.x toolkit

Warning

Do not omit the extra. It pulls in NVIDIA’s official cuda-python bindings, which numba needs on recent NVIDIA drivers (CUDA 13 / driver 580+). Without them, numba 0.60’s built-in ctypes driver bindings cause a segfault when the CUDA context is initialized.

cuda-python ships as an extra rather than a regular dependency only because its major version has to match the CUDA version on your machine, which cannot be decided at packaging time.

Development version

git clone https://github.com/XiangyuKuang/mechanochat.git
cd mechanochat
pip install -e ".[cuda11]"

Before you run a simulation

Important

Make sure NUMBA_CUDA_USE_NVIDIA_BINDING=1 is set before sem.sim_gpu(...) runs. Without it, on CUDA 13 / driver 580+ the kernel crashes with a segfault and no Python traceback.

Set it in the very first cell, before any other import (including scanpy):

import os
os.environ["NUMBA_CUDA_USE_NVIDIA_BINDING"] = "1"
# — must run before importing scanpy / numba —
import mechanochat as mc
import scanpy as sc

Quick self-check:

import numba.cuda as c
assert c.cudadrv.driver.USE_NV_BINDING == 1, "env var not in effect — restart the kernel"

Optional — set it once at the environment level

Setting the variable at the environment level saves you from repeating the two os.environ lines at the top of every script and notebook. The effect is exactly the same; it is only a convenience.

# conda activation hook — applies on every `mamba activate mc_39`
mkdir -p "$CONDA_PREFIX/etc/conda/activate.d"
echo 'export NUMBA_CUDA_USE_NVIDIA_BINDING=1' \
    > "$CONDA_PREFIX/etc/conda/activate.d/numba_cuda_binding.sh"
mamba activate mc_39   # re-activate for it to take effect

For Jupyter / VSCode notebooks, also set it in the kernel, so it applies even when the kernel is launched without shell activation. Add an "env" block to the kernel’s kernel.json (locate it with jupyter kernelspec list):

{
  "argv": ["...python", "-m", "ipykernel_launcher", "-f", "{connection_file}"],
  "env": { "NUMBA_CUDA_USE_NVIDIA_BINDING": "1" }
}