Installation¶
pip / uv¶
Install the latest released btorch from PyPI:
or
Optional extras¶
The core install is lightweight. Heavy libraries are optional extras and are
imported lazily; calling a feature whose library is missing raises an
ImportError with the exact pip install "btorch[...]" command.
| Extra | Installs | Enables |
|---|---|---|
| (core) | torch, numpy, pandas, scipy, jaxtyping, matplotlib | models, connectome tools, static plots |
btorch[io] |
xarray, zarr, numcodecs, h5py, hdf5plugin | btorch.io.serialization (xarray/Zarr save and load), btorch.utils.hdf5_utils |
btorch[config] |
omegaconf, pyyaml | btorch.utils.conf (OmegaConf helpers), btorch.utils.yaml_utils |
btorch[fast] |
numba, polars | optional accelerators (hex grid ops, use_polars aggregation); results are identical without them |
btorch[gpu] |
triton | GPU event timing in btorch.utils.bench.do_bench |
btorch[analysis] |
powerlaw, nolds, fastdtw | avalanche/DFA criticality, Lyapunov and entropy estimates, DTW trace clustering |
btorch[viz] |
networkx, plotly | interactive hex plots (btorch.visualisation.hex.interactive), graph plots |
btorch[sparse] |
torch_scatter, torch_sparse | optional, selectable sparse kernel backend (see below; needs PyG wheels) |
btorch[examples] |
torchvision, seaborn, tqdm | scripts in examples/ |
btorch[all] |
every extra above | everything |
CUDA support¶
btorch depends on PyTorch 2.3 or newer (torch.compiler.is_compiling). PyPI ships CPU-only torch by default. For CUDA,
install PyTorch with the right compute platform first, then add btorch:
Or with uv:
See the PyTorch Get Started page for other CUDA / ROCm variants.
conda / mamba¶
environment.yml bundles PyTorch with CUDA, pytorch_sparse, and all heavy
dependencies via conda-forge and PyG channels:
conda env create -n btorch -f https://github.com/Criticality-Cognitive-Computation-Lab/btorch/raw/refs/heads/main/environment.yml
conda activate btorch
Or with mamba:
mamba env create -n btorch -f https://github.com/Criticality-Cognitive-Computation-Lab/btorch/raw/refs/heads/main/environment.yml
mamba activate btorch
Install from source control¶
Btorch is fast evolving. For the latest unreleased changes, install directly from the repository:
Gitee mirror alternative:
Editable install (development)¶
Clone the repo and install in editable mode:
git clone https://github.com/Criticality-Cognitive-Computation-Lab/btorch.git
cd btorch
pip install -e . --config-settings editable_mode=strict
If you use uv, clone and sync the lockfile:
git clone https://github.com/Criticality-Cognitive-Computation-Lab/btorch.git
cd btorch
uv sync --group dev --all-extras
source .venv/bin/activate
pip install -e . --config-settings editable_mode=strict
For CUDA with uv, install torch with the right backend first:
uv venv .venv-cuda
uv pip install torch --torch-backend auto --python .venv-cuda/bin/python
uv pip install -e . --python .venv-cuda/bin/python
Optional: torch_sparse backend¶
Sparse connections (btorch.models.connection.SparseConnection) need only
PyTorch. They train, run on CPU and GPU, and compile with
torch.compile(..., fullgraph=True) without torch_sparse.
If torch_sparse is installed, btorch registers it as an additional kernel
backend. It is never selected automatically; choose it explicitly with
btorch.sparse.runtime.use_backend("torch_sparse") (see the
sparse connectivity guide).
Use prebuilt wheels from the PyG repository
matching your PyTorch and CUDA version:
# Example for PyTorch 2.7 with CUDA 12.6
pip install torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.7.0+cu126.html
If torch_sparse is absent, nothing changes: the default backend is used.