Installation

PyTorch first

Use the PyTorch installation selector to install the CPU or CUDA build you want in your active Python environment. Then install bartorch into that same environment:

python -m pip install bartorch

The metadata requires Python 3.10+, PyTorch 2.1+, NumPy 1.24+ and SciPy 1.10+. A wheel includes the embedded BART library; wheel users need neither a separate BART executable nor a C compiler.

Note

This checkout is pre-alpha. The command above is the intended release install path, not a claim that wheels for every platform are published. If pip cannot find a suitable distribution, use the Toolchain source installation. A source archive needs the developer toolchain too.

Checking the installation

import torch
import bartorch
import bartorch.tools as bt

print(torch.__version__)
print(bartorch.__version__)
print(bartorch.bart_version())
print(bartorch.build_info())
image = bt.phantom([32, 32])
print(image.shape, image.dtype, image.device)

Devices and non-Cartesian transforms

CUDA needs both a CUDA-capable PyTorch and a bartorch library built with CUDA; torch.cuda.is_available() and bartorch.cuda_available() check each. Move input tensors with tensor.to("cuda"). Some commands stage work through host memory, so tensor placement alone does not guarantee every step runs on the card. CPU and CUDA are the device paths; Apple MPS is not supported.

FINUFFT computes every non-Cartesian transform. It is a dependency rather than an extra, so pip install bartorch brings it. cuFINUFFT serves a transform on a card and is an extra:

python -m pip install 'bartorch[cufinufft]'

Wheels are published for Linux x86_64 and macOS on Apple silicon, the platforms FINUFFT ships wheels for too. Elsewhere – Linux on aarch64, an Intel Mac – pip install bartorch builds from the source distribution and builds FINUFFT alongside it, which needs CMake, ninja and a C++ compiler.

The substitution installs itself on first use. A transform it cannot serve raises an error naming the reason rather than falling back to BART’s own gridder. The mkl extra is optional; the Cartesian examples do not need it.

Platforms

Linux is the platform bartorch is developed and measured on, and the one the CUDA path is written for.

macOS works, without FINUFFT. torch and the FINUFFT wheel each carry an OpenMP runtime, and LLVM’s runtime ends the process rather than run beside a second copy of itself (OMP: Error #15). On macOS the substitution checks for that pair before the first call into FINUFFT, declines when it finds it, and says so once at warning level; BART’s own gridder then computes the non-Cartesian transforms. The same collision is open upstream in mri-nufft with no fix. KMP_DUPLICATE_LIB_OK=TRUE makes it run and is documented by the runtime’s authors as unsafe – a crash later, or a wrong answer quietly – so bartorch neither sets nor suggests it. A conda environment where one OpenMP runtime serves both packages is the way to FINUFFT on macOS; it is untested here.

Windows is not a target. BART does not build on it; WSL2 is a Linux install like any other.

Next: Conventions and <no title>.