User guide

The platforms BlochSim supports, its installation, and where to ask for help. A first simulation is lesson 1 of the Course.

Supported platforms

BlochSim supports Python 3.10 and later; CI tests 3.10 and 3.14 on Linux, macOS and Windows. One wheel per platform serves every supported interpreter, because the kernels are built against the CPython stable ABI.

Platform	Wheels	GPU kernels
Linux	x86-64 and aarch64, glibc and musl	x86-64, through the cu12 or cu13 extra
macOS	Apple silicon and Intel	none
Windows	x86-64	none

Elsewhere, pip builds the C++ kernels from source, which needs a C++17 compiler and CMake. There is no pure-Python fallback.

Installation

Virtual environment

Install into an environment of its own, so the PyTorch, NumPy and SciPy versions a simulation pins stay apart from the rest of the machine.

venv

python -m venv ~/envs/blochsim
source ~/envs/blochsim/bin/activate     # Windows: ~\envs\blochsim\Scripts\activate
python -m pip install --upgrade pip

conda

conda create -n blochsim python=3.12
conda activate blochsim

Install BlochSim with pip inside the environment; there is no conda package.

uv

uv venv --python 3.12 ~/envs/blochsim
source ~/envs/blochsim/bin/activate

Read uv pip install for pip install below.

PyTorch

Install PyTorch first. A CPU build and a CUDA build share a name and a version, and differ only in the index they come from, so pip cannot choose for you.

CPU only

pip install torch --index-url https://download.pytorch.org/whl/cpu

Everything in BlochSim runs on the CPU, on threaded C++ kernels.

NVIDIA GPU

Pick the CUDA tag your driver supports on pytorch.org; cu128 stands for it below:

pip install torch --index-url https://download.pytorch.org/whl/cu128

Apple silicon

pip install torch

There is no Metal path; the simulation runs on the CPU kernels.

Check the build before installing on top of it:

python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

A CUDA build prints a CUDA version and True; a CPU build prints None and False.

BlochSim

pip install blochsim            # CPU kernels
pip install "blochsim[cu12]"    # plus the GPU kernels, for a CUDA 12 PyTorch
pip install "blochsim[cu13]"    # plus the GPU kernels, for a CUDA 13 PyTorch

The GPU kernels are compiled ahead of time and need a driver, not the CUDA toolkit. Install the extra that matches PyTorch’s CUDA major version; BlochSim refuses a mismatched one and names the extra to install. The examples extra brings the packages the gallery imports.

Check the installation by simulating a fast spin echo for three tissues:

import torch
from blochsim.simulators import FSESimulator

acquisition = FSESimulator(
    ESP=5.0,                                   # ms
    TR=3000.0,                                 # ms
    T1=torch.tensor([830.0, 1330.0, 4000.0]),  # ms
    T2=torch.tensor([80.0, 110.0, 2000.0]),    # ms
)
signal = acquisition.simulate(flip=torch.full((48,), 60.0))
print(signal.shape)  # torch.Size([3, 48])

On a GPU, move the simulator and give it tensors on the same device:

acquisition = acquisition.to("cuda")
signal = acquisition.simulate(flip=torch.full((48,), 60.0, device="cuda"))

Getting help

Ask questions in Discussions: how to model a sequence, whether a signal is expected, which estimator suits a problem.

Report bugs in Issues. The form asks for:

• the shortest script that reproduces it;

• what you expected, and the reference you compare against: a closed form, a published figure or another simulator;

• the full traceback, if it raises;

• the environment, as the form’s command prints it;

• whether it happens on the CPU kernels, the GPU kernels, or both.

Request a sequence, a physical effect or an estimator through the same form, naming the paper the model comes from and the figure it should reproduce.

Report a vulnerability privately, as a draft advisory from the repository’s Security tab or by email to the address in the security policy. The kernels index raw pointers, so an out-of-bounds read or write reachable from ordinary arguments belongs there. Wrong physics is a bug report.