Bloch Equation Simulator for Python

A high-performance Python implementation of the Bloch equation solver originally developed by Brian Hargreaves at Stanford University. This package provides a fast C-based core with Python bindings, parallel processing support, and an interactive GUI with classic waveform simulation and an event-based Sequence mode for Pulseq workflows.

Download:

pip install "blochsimulator[gui,pulseq]"

or already built on GitHub Releases

Demo

Sequence mode

Sequence Mode: Demonstration of different EPI sequence modes on a spherical object, including multi-repetition and multi-slice acquisitions with B0 inhomogeneities. Generated EPI, CSI, and bSSFP sequences can be exported as Pulseq .seq files.

Classic simulation

Free Mode: Demonstration of a spin-echo simulation.

Features

Simulation and sequence design

Fast C-based Bloch solver with parallel processing support. The GUI can be used in 2 modes:

Free Mode

Free mode lets you investigate the behaviour of spins over a range of frequencies and spatial positions. Good for education and learning MRI concepts such as off-resonances, relaxation, basic sequences, rf pulses etc.

Features:

• Endpoint and full time-resolved simulations
• Configurable tissue properties including T1, T2, proton density, and initial magnetization.
• Parameter sweeps with final-state or full time-resolved result collection.
• RF pulse design for rectangular, sinc, Gaussian, adiabatic half/full passage, and BIR-4 pulses
• Sequence support for FID, spin echo, gradient echo, inversion recovery, slice-selective excitation, EPI, and SSFP.
• Live magnetization, signal, spectrum, spatial-profile, heatmap, and 3D-vector views.

Sequence mode

A mode that lets you load, generate and simulate Pulseq .seq sequences. In addition, an interactive 3D phantom and B1 Tx/Rx designer is provided.

Features:

• Internal FID with configurable Block, Sinc, Gaussian, SLR, or imported RF Designer pulses, flip angle, RF duration, phase and carrier offset. Set the complex FID points per repetition, sampling bandwidth, ADC delay, receiver offset, repetition count and TR. TR is measured from RF start to RF start; Shortest possible fits the pulse, delay and complete FID. Magnetization evolves continuously between repetitions, without resetting, averaging or spoiling. The sequence ends after the final FID. Use Generate sequence or Live preview to refresh the timeline.
• RF + Slice Selection for full 3D excitation volumes immediately after a pulse and its slice gradient, with optional rephasing and direct $|M_{xy}|$, $M_z$, and phase inspection. See RF excitation volumes.
• Interactive generation of Pulseq bipolar or flyback EPI, centre-out 2D spiral, 2D EPSI/MGE, 2D CSI, spoiled 2D FLASH, Cartesian 3D bSSFP, alternating-frequency spectrally selective 3D bSSFP, and Cartesian or spiral-phyllotaxis radial 3D multi-echo bSSFP sequences, with export to .seq files and reproducing Jupyter notebooks.
• Spectral-spatial RF design with explicit spatial and frequency target ranges, coupled RF/slice-gradient waveforms, configurable two-dimensional Bloch validation, spatial and spectral profile cuts, and phantom-aware metabolite frequencies. A stable-ID pulse library and ordered cyclic schedule support separate metabolite pulses, per-entry flip-angle or RF amplitude scaling, repetition, reordering, and a coherent cumulative preview. FLASH applies one schedule step per complete image frame by default and preserves schedule definitions and ADC labels through Pulseq export and import. Pulses, schedule, and legacy-single-pulse migration are stored with project files. The native Python flyback method is based on the Larson/Kerr design approach; supported modes, validation scope, differences from the MATLAB reference, citations, and license provenance are documented in Spectral-spatial RF pulse design.
• Spin Probe mode enables the investigation of the behaviour of spectral/spatial spin distributions during sequences.
• Spectral and dynamic phantom design with spatial peak distributions, pyruvate-to-lactate kinetics, spatial B0 inhomogeneity maps, and optional time-dependent B0 offsets.
• B1 Transmit Receive design, letting you choose between uniform, 3D birdcage, 3D surface coil B1 fields.
• A dimension-aware Reconstruction Explorer for interactive 2D/3D k-space and image views, echo/repetition/slice selection, CSI voxel spectra, receive-coil combination, simulated pool comparison, and known-frequency linear IDEAL estimates.

Visualization and analysis and reproducibility

Project files that contain current parameter selection, selected sequence, phantom and B1 can be saved and loaded. The tool has different ways to visualize and export bloch simulations:

Free Mode

The time-resolved bevahiour of spins during and after RF Pulse can be visualized in a multitude of ways, including a 3D vector view, heatmaps, spectral and spatial profiles. Additionally, simulation results can be exported as

• figures/animations and xarray.Dataset conversion

• automatically generated Jupyter notebooks (analysis of spin-echo result data and reproduction) using the parameters selected in the GUI.

Sequence Mode

• Mouse Phantom Designer polarization inputs use absolute percent with the thermal multiple alongside them, based on nucleus, B0 and temperature. Mouse injections use mM × µl and show the resulting µmol dose and fully polarized equivalent. New injections start at 80 mM × 250 µl (20 µmol) and 10000 × thermal, 5.8 % at 7 T and 37 °C; older files retain their original dose and relative-polarization values. The spectral Phantom Designer keeps × thermal and shows the thermal polarization at its sample temperature.
• Receiver / Noise adds reproducible complex noise from a relative SNR (single-scan SNR of the ideal 90° FID of the whole object, including any delivered bolus) or a calibration from a measured phantom FID: amplitude, noise std, averages, bandwidth, flip angle, concentration (mM), volume (ml), enrichment and temperature. Noise follows each ADC event's bandwidth, so a thermal phantom scan predicts e.g. hyperpolarized in-vivo SNR. An optional reference scan model corrects the calibration for T1 saturation, T2* decay and the B1 workspace coil at the phantom position. Load FID… and Load noise scan… read the ParaVision raw data or complex arrays of the phantom FID and 0° noise scan directly. Its dedicated tab between Phantom + B1 and Simulations shows an SNR budget from the receiver setting through the whole-object FID and each readout bandwidth to the image voxels of the current object and last run. Clean ADC data and noise settings are preserved in projects and result exports. Settings → Interface → Signal units switches the current Sequence plots between physical amounts (mol with automatic SI prefixes, calibrated runs) and SNR units (noise σ = 1 per complex quadrature), without rerunning the simulation. Cartesian/CSI FFTs preserve that noise normalization; spiral images use a labelled estimate from their noise realization. Runs without the required calibration or noise metadata show simulation units. See receiver calibration.

Loaded and generated sequences can be inspected in a sequence viewer. A 3D phantom design viewer in addition to a 3D B1 design viewer are provided.

• Experimental export of simulated acquisitions as Bruker raw datasets, including fid and/or rawdata.job0 plus the associated parameter files.
• Automatically generated Jupyter notebooks using the parameters selected in the GUI.

Get started

Documentation

For detailed instructions on installation, GUI features, and Python API usage, see the User Guide.

Desktop application

Download the standalone application for Windows or macOS from GitHub Releases. This is the recommended option for interactive simulation and requires no Python installation. Windows downloads and Python wheels target 64-bit systems. Was mainly tested on macOS 26.5.2.

As I did not pay for the Apple Developer Program, the app is unlicensed and will be put in quarantine after unzipping and installation upon the first run. How to run it anyways:

xattr -cr /Applications/BlochSimulator.app

Python package

Install the full blochsimulator from PyPI including GUI and pulseq skills (recommended):

pip install "blochsimulator[gui,pulseq]"

or

pip install blochsimulator

The package exposes the full simulation API for Python scripts, Jupyter notebooks, and custom analysis pipelines, but no graphical user interface or pulseq skulls

Usage

GUI application

Once installed, launch the GUI from the applications folder or a terminal:

blochsimulator-gui

Jupyter Notebook/ Python API

The bloch simulator can be used in both jupyter notebooks or via python api

Jupyter Notebook

You can launch the interactive GUI directly from a cell in your local Jupyter Notebook. You can also export the selected GUI simulation as a notebook. See the spin-echo reproduction and spin-echo analysis examples.

# Install from PyPI once, if needed
!pip install blochsimulator[gui,pulseq]"

# Launch the GUI
!blochsimulator-gui

This requires Jupyter to run on your local machine; it does not work on a headless remote server or Google Colab.

Basic simulation

import numpy as np
from blochsimulator import BlochSimulator, TissueParameters

# Create simulator
sim = BlochSimulator(use_parallel=True, num_threads=4)

# Define tissue parameters
tissue = TissueParameters(
    name="Gray Matter",
    t1=1.33,  # seconds
    t2=0.083  # seconds
)

# Create a simple 90-degree pulse
ntime = 100
dt = 1e-5  # 10 microseconds
time = np.arange(ntime) * dt

b1 = np.zeros(ntime, dtype=complex)
b1[0] = 0.0235  # 90-degree hard pulse

gradients = np.zeros((ntime, 3))  # No gradients

# Run simulation
result = sim.simulate(
    sequence=(b1, gradients, time),
    tissue=tissue,
    mode=2  # Time-resolved output
)

# Plot results
sim.plot_magnetization()

from blochsimulator.project_io import load_project

project = load_project("simulation.blochproj")
phantom = project["phantom"]
result = project["sequence_result"]

from blochsimulator import BlochSimulator, SpinEcho, TissueParameters

sim = BlochSimulator()

# Create spin echo sequence
sequence = SpinEcho(te=20e-3, tr=500e-3)  # 20ms TE, 500ms TR

# Simulate white matter
tissue = TissueParameters.white_matter(3.0)

# Run simulation with multiple frequencies (T2* effects)
frequencies = np.linspace(-50, 50, 11)  # Hz
result = sim.simulate(sequence, tissue, frequencies=frequencies)

# Access magnetization components
mx, my, mz = result['mx'], result['my'], result['mz']
signal = result['signal']

from blochsimulator import design_rf_pulse

# Design a sinc pulse
b1, time = design_rf_pulse(
    pulse_type='sinc',
    duration=2e-3,      # 2 ms
    flip_angle=180,     # degrees
    time_bw_product=4,  # Time-bandwidth product
    npoints=200
)

# Apply phase
phase = np.pi/4  # 45 degrees
b1_phased = b1 * np.exp(1j * phase)

# Simulate multiple positions and frequencies in parallel
positions = np.random.randn(100, 3) * 0.01  # Position scale: 10 mm
frequencies = np.linspace(-200, 200, 41)     # 41 frequencies

result = sim.simulate(
    sequence=sequence,
    tissue=tissue,
    positions=positions,
    frequencies=frequencies,
    mode=0  # Endpoint only (faster)
)

# Result shape: (100 positions, 41 frequencies)
print(f"Signal shape: {result['signal'].shape}")

# Convert last result to xarray
ds = sim.get_results_as_xarray()

# Access data with named dimensions
# Dimensions: (time, position, frequency)
print(ds.mx.dims)

# Powerful selection and plotting
ds.signal.sel(frequency=0, method='nearest').plot()

# Metadata is preserved in attributes
print(ds.attrs['t1'], ds.attrs['te'])

from blochsimulator import SpinEcho, GradientEcho

# Spin Echo
se = SpinEcho(te=30e-3, tr=1.0)

# Gradient Echo
gre = GradientEcho(te=5e-3, tr=10e-3, flip_angle=30)

# Compile to waveforms
b1, gradients, time = se.compile(dt=1e-6)

from blochsimulator import TissueParameters

# 3T parameters
gm = TissueParameters.gray_matter(3.0)
wm = TissueParameters.white_matter(3.0)
csf = TissueParameters.csf(3.0)

# 7T parameters
gm_7t = TissueParameters.gray_matter(7.0)

# Custom tissue
liver = TissueParameters(
    name="Liver",
    t1=0.812,
    t2=0.042,
    t2_star=0.028,
    density=0.9
)

Development

For detailed packaging, release workflows, and CI/CD information, see the Developer Guide.

git clone https://github.com/LucaNagel/bloch_sim_gui.git
cd bloch_sim_gui
pip install -e .

./scripts/run_gui.sh

from blochsimulator import BlochSimulator, TissueParameters

sim = BlochSimulator()
tissue = TissueParameters.gray_matter(3.0)
print(f"T1: {tissue.t1:.3f}s, T2: {tissue.t2:.3f}s")

conda create -n bloch-simulator python=3.12 pip
conda activate bloch-simulator
python -m pip install "ipykernel==7.4.0" ".[gui,pulseq]"

./scripts/build_pyinstaller.sh

.venv-packaging/bin/python setup.py build_ext --inplace
.venv-packaging/bin/python -m PyInstaller bloch_gui.spec --noconfirm

blochsimulator/
├── src/
│   └── blochsimulator/
│       ├── __init__.py
│       ├── simulator.py            # Core Python API
│       ├── gui.py                  # PyQt5 GUI
│       ├── bloch_core_modified.c   # C implementation
│       ├── bloch_core.h            # C header
│       ├── bloch_wrapper.pyx       # Cython wrapper
│       └── ...
├── tests/                          # Unit tests
├── docs/                           # Sphinx documentation
├── pyproject.toml                  # Modern build config
├── setup.py                        # C-extension build config
├── MANIFEST.in                     # Source dist manifest
└── README.md

Troubleshooting build issues

1. Missing compiler: Install gcc (Linux), Xcode (macOS), or Visual Studio (Windows).
2. OpenMP not found: The code will still work, but without parallelization.
3. Import error: Ensure that the .so or .pyd file is in the expected package directory.

Contributing

Contributions are welcome. Please:

1. Fork the repository.
2. Create a feature branch.
3. Add tests for new features.
4. Submit a pull request.

Citation

If you use this simulator in your research, please cite:

@software{blochsimulator_python,
  title={Python Bloch Equation Simulator GUI and API},
  author={Luca Nagel},
  year={2026},
  url={https://github.com/LucaNagel/bloch_sim_gui}
}

Acknowledgments

This project is based on code originally developed by Brian Hargreaves at Stanford University. As of July 2026, the original source is unfortunately unavailable. A Python adaptation of the code is available here.

• Original Bloch simulator by Brian Hargreaves, Stanford University
• NumPy and SciPy communities
• xarray team
• PyQt/PySide developers
• OpenMP project
• Built partially with Codex, Claude Code, and Gemini CLI

License

This project is licensed under the GNU General Public License v3.0. You may copy, distribute, and modify the software under the terms of GPLv3. Modified versions distributed to others must also be licensed under GPLv3 and include the corresponding source code.

Contact

Luca Nagel