Install#

Larmor needs Python 3.14 or newer. It is built and tested on Linux, macOS and Windows, and its wheels need no compiler:

Platform

Wheel

Linux, x86-64 and aarch64

manylinux (glibc-based distributions)

macOS 14 or newer, Apple silicon and Intel

arm64 and x86-64

Windows, x86-64

x86-64

Elsewhere, for example on a musl-based Linux such as Alpine, pip builds Larmor from its source distribution, which needs a C++20 compiler.

With pip or uv#

The library and the lar command line:

pip install larmor-dmri

With the viewer, BrainViewer, which adds Qt (PySide6), the pygfx renderer and the package that serves agents (MCP):

pip install "larmor-dmri[viewer]"

With uv, use uv pip install in the same way inside an environment, or uv add larmor-dmri in a uv project. uv also installs Python 3.14 when the computer does not have it: uv python install 3.14.

The viewer on its own#

To use the viewer as a desktop application, without setting up a Python environment, install the lar command as a tool with uv, then add the viewer to the desktop:

uv tool install "larmor-dmri[viewer]"
lar bv --install-launcher

The launcher is an entry in the application menu on Linux, an app in ~/Applications on macOS and a shortcut in the Start menu on Windows. It opens the viewer of this install. lar bv --uninstall-launcher removes it.

From source#

Installing from source compiles Larmor’s C++ module, so it needs a C++20 compiler:

  • Linux: GCC or Clang (sudo apt install g++ on Debian and Ubuntu).

  • macOS: the Command Line Tools (xcode-select --install).

  • Windows: Visual Studio 2022 or its Build Tools, with the “Desktop development with C++” workload.

The other build tools (CMake, Ninja, nanobind) are installed by the build. The C++ libraries Larmor uses, Eigen and pocketfft (both header-only), come with the source distribution on PyPI; from a git clone, CMake downloads them the first time it configures the build, so that step needs a network connection. On macOS the module uses the system’s Accelerate framework for matrix products; on Linux and Windows it uses Eigen’s own. Nothing more has to be installed.

git clone https://github.com/larmor-dmri/larmor.git
cd larmor
uv sync

uv sync installs Python 3.14 if needed, Larmor in editable mode, the viewer’s dependencies and the development tools; commands then run through uv, for example uv run lar --help and uv run lar bv. After a change to the C++ code, the next uv sync or uv run compiles the changed files again. With pip instead, in an environment with Python 3.14, pip install ".[viewer]" builds and installs it.

Remote use over SSH#

The viewer can run on a remote Linux server and show its window on your screen. Connect with X forwarding, ssh -X (MobaXterm on Windows does this by default), and start lar bv on the server. The server’s GPU draws the views, and only the finished images travel to your screen. If dragging feels slow, turn on Lower resolution while moving in the Settings panel.

Qt needs some X libraries that servers often lack. When one is missing, lar bv names it and the package that provides it; Getting started shows how to install them, with or without administrator rights.

GPU and software rendering#

The viewer draws through wgpu, which uses Metal on macOS, Vulkan on Linux, and DirectX 12 or Vulkan on Windows. To see which GPUs it finds, run this with the Python of the environment Larmor is installed in (for the viewer installed on its own: uv tool run --from "larmor-dmri[viewer]" python):

python -c "import wgpu; [print(a.summary) for a in wgpu.gpu.enumerate_adapters_sync()]"

  • No GPU is listed. Install or update the GPU’s driver; on Linux, the driver must include Vulkan support.

  • No GPU at all, as on many servers. The viewer then draws with a software renderer, which works but is slow: keep the views small, and turn on Lower resolution while moving. On Linux, the software renderer is Mesa’s Vulkan driver, lavapipe (the mesa-vulkan-drivers package on Debian and Ubuntu).

  • Several GPUs. GPU in the Settings panel chooses the one the viewer draws with; it applies when the viewer starts again.

Screenshots from Python (Viewer.screenshot) need no window and no display, but they need a GPU or a software renderer in the same way.