Bloch Equation Simulator for Python

A fast Bloch equation simulator with a C core, Python API and interactive GUI, based on the solver by Brian Hargreaves (Stanford). Use it to explore spin physics in Free Mode, or to simulate complete Pulseq acquisitions on 3D phantoms in Sequence Mode.

Installation

Python package (GUI, Pulseq support and Python API):

pip install blochsimulator
blochsimulator-gui

In a Jupyter notebook, use %pip install blochsimulator so the package lands in the notebook's own environment.

Desktop application for macOS and Windows (no Python needed): download from GitHub Releases. Builds target 64-bit systems; mainly tested on macOS 26.

The app is not signed with an Apple Developer ID, so macOS quarantines it. Move BlochSimulator.app to Applications and launch it. If it is blocked:

1. Dismiss the warning.
2. Open System Settings > Privacy & Security and scroll to Security.
3. Click Open Anyway next to the BlochSimulator.app message.
4. Launch BlochSimulator again.

Alternatively, if you trust the download, remove the quarantine flag:

xattr -cr /Applications/BlochSimulator.app

Demo

Sequence Mode

Sequence Mode: Demo of a typical workflow: Free phantom design, optional $B_0$ - inhomogeneites, defining transmit (birdcage in this case) and receive $B_1$ (surface coil). Followed by running the simulations and inspecting them in the Reconstruction viewer. Showcasing Point Spread Function (PSF) and k-space trajectory simulations. Exporting simulations results, as well as a jupyter notebook for analysis of sequence simuation results.

Free Mode

Free Mode: A 1D spin-echo simulation, and a 2D RF + Gradient Tour.

Modern UI

Now with Dark mode!

Features

Free Mode — understand spin behaviour over frequency and position:

• Endpoint or time-resolved simulation of configurable tissues (T1, T2, PD)
• RF pulses: rectangular, sinc, Gaussian, adiabatic half/full passage, BIR-4, or loaded from file
• FID, spin echo, gradient echo, inversion recovery, slice selection, EPI, SSFP
• Magnetization, signal, spectrum, spatial-profile, heatmap and 3D-vector views, GIF/MP4 export
• Parameter sweeps with final-state or full time-resolved result collection

Sequence Mode — simulate what the scanner would measure:

• Pulseq sequences, loaded or generated: EPI (bipolar/flyback), spiral, EPSI/MGE, CSI, FLASH, inversion recovery with T1 fit, PRESS, slice-selective FID, Cartesian 3D bSSFP, spectrally selective 3D bSSFP and Cartesian or radial multi-echo 3D bSSFP
• RF design including spectral-spatial pulses with per-metabolite pulse schedules
• Phantoms: 3D spectral phantoms with B0 maps, hyperpolarized pyruvate→lactate kinetics with inflow, and a mouse perfusion phantom for hyperpolarized ¹³C and for ¹H (tissue water, gadolinium DCE)
• B1 Tx/Rx fields: uniform, birdcage, surface coil
• Receiver noise calibrated from a measured phantom FID, to predict SNR of e.g. hyperpolarized in-vivo experiments
• Reconstruction Explorer for 2D/3D images, k-space and CSI spectra, with the phantom shown on the image grid
• PSF and spoiling analysis of the current sequence
• Export to .seq, NetCDF/HDF5, Bruker raw data (experimental) and auto-generated Jupyter notebooks; complete projects as .blochproj (see Bloch project vs. exported results)

See the User Guide for how to use these and what to watch out for.

Bloch project vs. exported results

The GUI writes two kinds of files. Choose by what you want to do with them:

	Bloch project (.blochproj)	Exported results (.nc, .h5, .npz, Bruker, DICOM, NIfTI)
Written by	File → Save Project, Export selected… in the Simulations list, parameter loops with Results: Save to folder	Export Results
Purpose	Continue working: re-open the complete session in the GUI	Analyse the numbers of one result in other tools
Contains	Sequence, phantom, B1 fields, all GUI controls, the last Free Mode result and the last Sequence/Spin Probe result	Signal, k-space, images, magnetization, B1 maps and the parameters as JSON metadata of the current result
Re-open in the GUI	Yes (File → Open Project)	No (a .nc file can be viewed with Open result… in the Reconstruction Explorer)
Read without Bloch Simulator	No, needs blochsimulator.project_io.load_project	Yes (xarray, h5py, NumPy, MATLAB, scanner viewers)

Both keep the simulation parameters (flip angle, matrix, FOV, TR/TE, nucleus, B0). Only a project also keeps the phantom and B1 field objects themselves. Two example notebooks show how to load each kind, including these parameters:

• load_bloch_project.ipynb: parameters, phantom, B1 and every simulation inside a project.
• load_exported_results.ipynb: NetCDF, HDF5 and NPZ exports with their metadata. Free Mode HDF5 exports: read_hdf5_examples.py.

Several simulations in one project. A project can hold one Free Mode and one Sequence (or Spin Probe) result at the same time. Each result again contains many spins, voxels, pools or coils that can be selected by index:

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗