MRI Bloch Simulation

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):

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

See examples/Adiabatic Inversion Animation.ipynb for the full simulation code.

Installation#

To install GigaBlochs, simply run:

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, then install GigaBlochs with the gpu extra:

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

For 3D animations on the Bloch sphere using manim, install dependencies as shown below and include the animation extra:

Ubuntu / Debian / Windows Subsystem for Linux (WSL)

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

macOS

# 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:

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

Animation#

`gigablochs.animation.bloch_sphere`(magnetization)	Animate magnetization and B-field vectors on a Bloch sphere.
`gigablochs.backends.manim_cairo.BlochScene`([...])

Bloch Simulation#

`gigablochs.bloch.construct_B_field`(rf_am[, ...])	Construct the magnetic field vector from the RF and gradient waveforms.
`gigablochs.bloch.unit_field_and_angle`(...[, ...])	Compute the unit field vector and rotation angle for a given field vector and time step.
`gigablochs.bloch.precess`(magnetization, ...)	Simulate the precession of the magnetization vector under the influence of the magnetic field.
`gigablochs.bloch.relax`(magnetization, T1, ...)	Apply relaxation to the magnetization vector.
`gigablochs.bloch.inverted_magnetization`(...)	Calculate labelling efficiency from final longitudinal magnetization at the end of the simulation by correcting for the T1 decay experienced by the spin isochromat since crossing the labelling plane Dai et al. [DGdBA08].
`gigablochs.bloch.labelling_efficiency`(...[, ...])	Compute the labeling efficiency from inverted and control longitudinal magnetizations.

RF Pulses#

`gigablochs.rf.sinc_pulse`(flip_angle, ...[, ...])	Generate a sinc pulse with a given flip angle and duration.
`gigablochs.rf.adiabatic_pulse`(flip_angle, ...)	Generate an adiabatic pulse with a given flip angle and duration.
`gigablochs.rf.adiabaticity`(pulse_am, ...)	Compute the adiabaticity of an RF pulse.
`gigablochs.rf.extend`(pulse, duration, dt[, axis])	Extend the pulse waveform to a given duration.

Flow Modelling#

`gigablochs.flow.integrate_trajectory`(...[, ...])	Integrate a velocity waveform to obtain a position waveform, or sample bolus trajectory.
`gigablochs.flow.constant`([start, stop, num, ...])	Generate a constant velocity flow profile.
`gigablochs.flow.half_sin`([start, stop, num, ...])	Generate a blood flow velocity waveform using a half sine wave, where negative values are set to zero, then shifted with the diastolic velocity offset.
`gigablochs.flow.exp_decay_train`([start, ...])	Generate a blood flow velocity waveform using an exponential decay train.
`gigablochs.flow.holdsworth_cca`([start, ...])	Generate a blood flow velocity waveform for the common carotid artery (CCA) based on the model by Holdsworth et al. (1999) Holdsworth et al. [HNF+99].

Utilities#

`gigablochs.utils.expand_dims_to`(arr1, arr2)	Expand dimensions of arr1 to be broadcastable with arr2.
`gigablochs.utils.dot`(a, b, *[, keepdims, axis])	Compute the dot product of two arrays.
`gigablochs.utils.rodrigues_rotation`(v, k, ...)	Apply Rodrigues rotation formula to rotate a vector `v` around an axis `k` by an angle `theta`.

References#

[DGdBA08] (1,2)

Weiying Dai, Dairon Garcia, Cedric de Bazelaire, and David C. Alsop. Continuous flow-driven inversion for arterial spin labeling using pulsed radio frequency and gradient fields. Magnetic Resonance in Medicine, 60(6):1488–1497, November 2008. URL: https://doi.org/10.1002/mrm.21790, doi:10.1002/mrm.21790.

[HNF+99] (1,2,3,4)

D W Holdsworth, C J D Norley, R Frayne, D A Steinman, and B K Rutt. Characterization of common carotid artery blood-flow waveforms in normal human subjects. Physiological Measurement, 20(3):219–240, January 1999. URL: http://dx.doi.org/10.1088/0967-3334/20/3/301, doi:10.1088/0967-3334/20/3/301.

[ZVS+16]

Li Zhao, Marta Vidorreta, Salil Soman, John A. Detre, and David C. Alsop. Improving the robustness of pseudo-continuous arterial spin labeling to off-resonance and pulsatile flow velocity. Magnetic Resonance in Medicine, 78(4):1342–1351, October 2016. URL: http://dx.doi.org/10.1002/mrm.26513, doi:10.1002/mrm.26513.