Installation#

PyTorch installation#

Install the PyTorch build for the target device first, with the command the PyTorch installation selector gives for the CPU or for a CUDA version. bartorch requires PyTorch 2.2 or later (2.3 on macOS, 2.7.1 on Linux); installing bartorch into an environment without PyTorch installs the default build from PyPI.

bartorch installation#

python -m pip install bartorch

This installs the wheel for the platform where one exists (see Prerequisites and supported platforms) together with NumPy, SciPy, TorchSim and MRI-NUFFT. A wheel contains the compiled library with BART and FINUFFT embedded; no BART or FINUFFT installation and no compiler are needed. Optional components are installed as extras:

python -m pip install 'bartorch[mkl]'        # Linux x86-64: MKL for BLAS, LAPACK and FFT
python -m pip install 'bartorch[deepinv]'    # bartorch.interop.to_deepinv
python -m pip install 'bartorch[learning]'   # Lightning and TorchIO, for bartorch.learning.Reconstruction and RandomGain
python -m pip install 'bartorch[correct]'    # SimpleITK, for bias field and gradient nonlinearity correction
python -m pip install 'bartorch[motion]'     # SimpleITK, for navigator registration
python -m pip install 'bartorch[pyhysco]'    # PyHySCO (GPL-3.0-only), for susceptibility correction

The installation is checked by building a phantom:

import bartorch
import bartorch.tools as bt

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

bartorch.build_info() reports the compiler, the OpenMP and CUDA configuration of the library and the FINUFFT version compiled into it, and bartorch.backend_sources() the library serving each BLAS and LAPACK routine and the FFT: MKL when the mkl extra is installed, otherwise the routines PyTorch links, and SciPy’s for the rest.

Source builds#

Where no wheel exists, pip builds the source distribution, which needs:

Tool	Requirement
C and C++ compiler	clang, or GCC 14 or later; BART’s nested functions are compiled as clang Blocks or as GCC heap trampolines, and older GCC is rejected at configuration. On Windows, clang from MSYS2’s CLANG64 environment, as Development prerequisites describes
CMake	3.25 or later
Git and network access	FINUFFT’s build fetches the versions of xsimd, POET and DUCC0 it pins, and CCCL for a CUDA build; `CPM_SOURCE_CACHE` names a directory that keeps them for later builds
OpenMP	Linux: the compiler’s OpenMP runtime, for example `libomp-dev` with clang on Debian and Ubuntu. macOS: the header from Homebrew’s `libomp`. Windows: MSYS2’s `llvm-openmp`, for the header. On macOS and Windows the library links against PyTorch’s runtime. Without OpenMP the build fails unless `-C cmake.define.BARTORCH_OPENMP=OFF` asks for a single-threaded library

The compiler is selected with CC and CXX:

CC=clang CXX=clang++ python -m pip install bartorch --no-binary bartorch

FINUFFT computes the FFT inside its CPU transform with DUCC0, which every wheel has compiled into the library. On x86-64 Linux, a source build with oneMKL installed (pip install mkl mkl-devel) can use oneMKL’s FFT through its FFTW3 interface instead:

python -m pip install "bartorch[mkl]" --no-binary bartorch \
    -C cmake.define.BARTORCH_FINUFFT_FFT=MKL

The library then links the libmkl_rt found at build time, and the mkl extra makes the same library serve BART’s BLAS, LAPACK and FFT. finufft_fft= in bartorch.build_info() names the FFT the library was built with.

On x86-64 Linux and Windows the library carries FINUFFT’s CPU transform compiled for any x86-64 processor, and in modules beside it for the x86-64-v2 (SSE4.2), x86-64-v3 (AVX2 and FMA) and x86-64-v4 (AVX-512) levels; the newest level the processor supports is used. The environment variable BARTORCH_FINUFFT_SIMD names another level, x86-64 for the baseline, and finufft_simd= in bartorch.build_info() lists the levels the library was built for. A source build selects them with -C cmake.define.BARTORCH_FINUFFT_SIMD="x86-64-v3", or builds the baseline alone with an empty value.

On x86-64 Linux each of those levels is also built on oneMKL’s FFT, and is used in place of DUCC0 when oneMKL is installed:

python -m pip install "bartorch[mkl]"

bartorch.backend_sources()["finufft_fft"] names the FFT in use. A source build carries these modules when oneMKL’s headers (mkl-include) are present, which the build requires on that platform; -C cmake.define.BARTORCH_FINUFFT_MKL_MODULES=OFF leaves them out.

A checkout of the repository is built as described in the developer guide.

CUDA#

CUDA support requires a CUDA build of both PyTorch and bartorch; torch.cuda.is_available() and bartorch.cuda_available() report each. The PyPI wheels are CPU builds, and there is no CUDA build on macOS or Windows. The CUDA build of each version, a Linux x86-64 wheel with the same file name, is attached to the GitHub release of that version:

python -m pip install https://github.com/pulserver/bartorch/releases/download/<tag>/<wheel>

It contains cuFINUFFT and device code for compute capabilities 7.5, 8.0, 8.6, 8.9 and 9.0, and links the CUDA 12 runtime, cuFFT and cuBLAS dynamically, which a CUDA 12 build of PyTorch provides. A source build with CUDA passes -C cmake.define.BARTORCH_CUDA=ON to pip and needs the CUDA toolkit with nvcc, version 12.1 or later for compute capability 9.0; -C cmake.define.BARTORCH_CUDA_ARCHITECTURES="80;86" selects the compute capabilities for BART’s kernels and cuFINUFFT alike.

Command-line interface#

Installation provides the bartorch command, which accepts the command lines of BART’s bart executable and operates on CFL files:

bartorch pics -l1 -r0.01 -i30 kspace sensitivities image
bartorch --list

A script written for bart runs with the command name replaced, or with a bart symbolic link to bartorch earlier on the PATH. Which commands run as bartorch.apps pipelines is stated in Command line.

Installation

Contents