gigablochs 0.2.4

A flexible Bloch simulation framework enabling large parameter space investigations, such as for Arterial Spin Labelling (ASL)

MRI Bloch Simulation

GigaBlochs is a flexible Bloch simulation framework enabling large parameter space investigations in Magnetic Resonance Imaging (MRI). The Bloch equations describe the time-evolution of magnetization in a magnetic field resulting from radiofrequency (RF) pulses, gradients waveforms, off-resonance effects, and motion of hydrogen nuclei (or "spins") through these fields, as in the case of pulsatile blood flow in arteries.

The capability to handle arbitrary, multi-dimensional spin properties which evolve at every timestep, combined with tools for flow modelling, allows for realistic simulations of complex sequences, such as Arterial Spin Labelling (ASL). ASL is a technique that uses the magnetization of blood as an endogenous contrast agent for quantification of perfusion.

Features

• Simulate the full time-evolution of the magnetization following an arbitrary pulse sequence
• Avoids the hard pulse approximation, constructing all B-field components from RF and gradient waveforms along with off-resonance effects
• Uses numpy-style broadcasting to effectively run up to millions of Bloch simulations in parallel
• Sophisticated blood flow modelling tools to incorportate friction and pulsatile flow effects when relevant
• GPU acceleration using CuPy, with CPU fallback, for seamless and fully device-agnostic simulation code
• Visualise the effect on magnetization of whole parameter grids using Bokeh
• Animations of the magnetization dynamics in 3D on the Bloch Sphere using Manim

ASL Features

• Simulate PASL sequences or background suppression using adiabatic pulses
• Simulate CASL with constant concurrent RF and gradients
• Simulate PCASL with a train of RF sinc pulses and gradients
• Use arbitrary flow trajectories to simulate the effect of pulsatile blood flow
• Use the rigid tube model to simulate viscosity and vessel wall friction across arteries

Example

Pulsed ASL (PASL) uses an adiabatic pulse to label a slab of blood in one go. Here's an animation on the Bloch sphere of an adiabatic inversion pulse in a reference frame rotating at the instantaneous frequency of the pulse (which only coincides with the Larmor frequency when passing through the transverse plane):

.. video:: _static/BlochScene_PASL.mp4 :width: 800 :loop:

.. code-block:: python

from gigablochs import animation
animation.bloch_sphere(downsampled_magnetization, downsampled_b_field, time_interval)

See examples/Adiabatic Inversion Animation.ipynb <https://github.com/nathanielatom/gigablochs/blob/main/examples/Adiabatic%20Inversion%20Animation.ipynb>__ for the full simulation code.

.. .. toctree:: :maxdepth: 2 :caption: Examples :hidden:

    adiabatic_pulse_demo

.. pcasl_demo flow_demo background_suppression_demo

Installation

To install GigaBlochs, simply run:

.. code-block:: bash

pip install git+https://github.com/nathanielatom/gigablochs

Advanced Installation

For GPU acceleration using cupy, ensure you have a compatible NVIDIA GPU and CUDA toolkit <https://docs.cupy.dev/en/stable/install.html#requirements>__, then install GigaBlochs with the gpu extra:

.. code-block:: bash

pip install git+https://github.com/nathanielatom/gigablochs[gpu]

For 3D animations on the Bloch sphere using manim, install dependencies <https://docs.manim.community/en/stable/installation.html>__ as shown below and include the animation extra:

.. tab-set::

.. tab-item:: Ubuntu / Debian / Windows Subsystem for Linux (WSL)

    .. code-block:: bash

        sudo apt update
        sudo apt install build-essential pkg-config libcairo2-dev libpango1.0-dev
        pip install git+https://github.com/nathanielatom/gigablochs[animation]

.. tab-item:: macOS

    .. code-block:: bash

        # install brew package manager if not already installed
        /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
        brew install cairo pkg-config
        pip install git+https://github.com/nathanielatom/gigablochs[animation]

Both extras can be installed at once with gigablochs[animation,gpu].

See dependencies in the pyproject.toml file for required and optional packages. To install the very latest commit from github run:

.. code-block:: bash

pip install git+https://github.com/nathanielatom/gigablochs