Installation

Installation#

The prerequisites, the editable install, the pre-commit hooks and the documentation build.

Prerequisites#

Besides the environment and PyTorch build of the user guide, you need:

  • A C++17 compiler and CMake. The CPU kernels (src/blochsim/_epg_cpu.cpp, _perk_cpu.cpp) are compiled at install, and there is no Python fallback.

    sudo apt install build-essential      # Debian, Ubuntu
sudo dnf install gcc-c++ make         # Fedora, RHEL

    xcode-select --install

    The Visual Studio Build Tools with the “Desktop development with C++” workload; build from the Developer Command Prompt.

  • Git, and a fork of pulserver/blochsim to open a pull request from.

  • The CUDA toolkit, only to compile the GPU kernels for a card. CMake compiles them wherever it finds nvcc; on Linux they are also compiled for the host, so they can be tested without one (see Tests).

Development installation#

git clone https://github.com/pulserver/blochsim
cd blochsim
pip install -e ".[dev]"
pre-commit install

The dev extra is test, doc and examples plus ruff, mypy and pre-commit. Python edits take effect on the next import. A C++ edit needs the install again, and a failed compile leaves the previous extension importable, so check the exit status and which file is loaded:

pip install -e ".[dev]" ; echo "exit: $?"
python -c "import blochsim._epg_cpu as k; print(k.__file__)"

Source layout#

Path

Content

src/blochsim/sequence/

Events, operators and builders, and the dispatch to the kernels. _parameters.py is the parameter ABI the Python dispatch, the C++ extension and the GPU kernels share.

src/blochsim/_model/

The signal model: physics, the simulator that orders events, and the binding that resolves a protocol’s structure once.

src/blochsim/_epg_cpu.cpp, _perk_cpu.cpp

The CPU kernels. Every GPU path exists here too; the two agree to float32 round-off.

src/blochsim/_epg_kernels.hpp, _pools_kernels.hpp

The GPU kernels.

src/blochsim/_operator.py, _subspace.py

The model operator and the temporal basis a reconstruction composes with.

src/blochsim/simulators/, estimators/, optim/

Shipped sequences, and what is built on them.

tests/, examples/, docs/

Tests mirrored by subpackage, gallery scripts, Sphinx sources.

Read Kernels before changing any of the kernels.

Pre-commit hooks#

After pre-commit install, every commit checks the staged files. .pre-commit-config.yaml pins the ruff version, so your commit and CI are judged by the same build.

pre-commit run --all-files      # what CI runs
pre-commit run ruff-format      # one hook
pre-commit autoupdate           # move the pinned versions forward

A hook that rewrites a file fails the commit and leaves the fix in the working tree: review it, git add it and commit again.

Hook bypass#

SKIP=ruff-check git commit -m "..."     # one hook
git commit --no-verify -m "..."         # all hooks

CI runs every hook on every branch, so a bypass only defers the failure. A rule that does not fit this code belongs in ignore or per-file-ignores in pyproject.toml, with a comment.

Documentation build#

bash scripts/build_docs.sh              # incremental
bash scripts/build_docs.sh --clean      # re-execute every example
PYTHON_BIN=~/envs/blochsim/bin/python bash scripts/build_docs.sh
python -m http.server --directory docs/build/html 8000

The build executes every gallery example and re-renders the explanation figures from docs/explanation_figures.py with the BlochSim in your working tree. Adding a figure or an example is described in Documentation.