BlochTwin

A physics-faithful, open-source MRI scanner simulator (digital twin) for generating synthetic MRI training data with perfect ground truth and for learning how scan parameters shape the image, the scan time and the artifacts.

Status: alpha (v0.3). The core loop works end to end: tissue phantom → Bloch simulation → complex k-space → reconstructed image. Multi-coil acquisition, artifacts and gradient acoustic noise are on the roadmap below.

Why

MRI deep-learning work needs paired data that real scanners cannot provide. That means fully sampled complex k-space, noise-free references, voxel-wise tissue maps and exact sequence parameters. Physics simulators (JEMRIS, MRiLab, KomaMRI) produce faithful signals, but they are not built as ML data pipelines. ML toolkits (TorchIO, MONAI) are easy to use, but they fake k-space as the FFT of a magnitude image. BlochTwin aims at the gap between them: real acquisition physics, packaged as a headless Python/PyTorch library.

• Contrast comes from physics, not lookup tables. Each tissue's signal is computed by an operator-splitting Bloch engine. T1, T2 and T2* weighting follow from TR/TE/TI/flip and from the refocusing structure of the sequence.
• Every tissue parameter is cited. Tables for T1, T2, T2*, PD and χ at 1.5, 3 and 7 T carry their literature sources (blochtwin references). Less-standardized values, such as 7 T extrapolations, are flagged.
• Differentiable. The engine is written in PyTorch, so signals keep their autograd graph for diff-MRI experiments.
• Headless by design. The core never imports a GUI, so it runs on clusters. Viewers are optional.

Install

pip install blochtwin          # Python 3.10–3.13, CPU/CUDA, Apple MPS for convenience
pip install 'blochtwin[viz]'   # optional napari 3D inspector (add a Qt backend)

Quick start

import blochtwin as bt

phantom = bt.build_brain_phantom(voxel_mm=2.0)   # built-in procedural head (incl. air sinuses)

# T2-weighted spin echo: CSF bright
se = bt.simulate(phantom, bt.SpinEcho(matrix=(128, 128), tr_ms=3000, te_ms=100), field_t=3.0)
print(se.magnitude.shape, se.scan_time_s)          # (128, 128) 384.0

# T1-weighted spoiled gradient echo: same phantom, different physics, WM bright
gre = bt.simulate(phantom, bt.GradientEcho(tr_ms=15, te_ms=4, flip_deg=25), field_t=3.0)

# FLAIR: inversion recovery that nulls CSF (TI chosen from CSF T1 at 3 T)
flair = bt.simulate(phantom, bt.FLAIR(), field_t=3.0)

kspace, image = gre.kspace, gre.image              # complex k-space + reconstruction

The same from the command line:

blochtwin simulate --seq se --te 90        # image + k-space + scan time
blochtwin simulate --seq flair
blochtwin tables --field 7.0               # cited tissue parameters at 7 T
blochtwin info

Real anatomy can be loaded from sources you download yourself. Their data is never bundled because it is under third-party licenses:

bt.list_phantom_sources()                                 # sources + licenses
bt.load_phantom("brainweb", directory="brainweb/")        # BrainWeb fuzzy tissue maps
bt.load_phantom("nyhead", path="nyhead_seg.nii")          # New York Head (scalp/skull/air)

What works today (v0.3)

Validation

• Steady-state GRE and SE signals match closed-form solutions to machine precision. IR matches too, except right at the null point.
• Single-voxel cross-check against KomaMRI.jl 0.10.4 (SE, IR, flip sweeps over WM, GM and CSF): 0.0023 % mean absolute difference (worst 0.011 %). Reproduce with benchmarks/compare.py.

Roadmap

1. Artifacts, field strength and acoustics. Sampling patterns, motion, chemical shift, susceptibility, EPI ghosts, and gradient acoustic noise, which no open simulator models today.
2. Multi-coil. Coil sensitivities, SENSE and GRAPPA.
3. Compressed sensing.
4. Dataset generator. Paired, fastMRI-compatible tuples with domain randomization, plus an interactive teaching UI.
5. v1.0. Validation against real data (fastMRI) and a companion paper.

How to cite

If you use BlochTwin in academic work, please cite it (see CITATION.cff; a Zenodo DOI will be added with the first tagged release). Citation is a community norm we ask you to honor, not a license restriction.

License

Apache License 2.0. You are free to use, modify and distribute BlochTwin, including commercially. "BlochTwin" and its logo are trademarks of newmean.ai. Forks may use the code but not the name or logo (see NOTICE).

Questions and physics-fidelity reports are welcome on GitHub Issues or at dev@newmean.ai.