A differentiable MRI simulator in PyTorch, checked against real scanners.
Everyone's invited, as long as they precess.
Phantom + coils + sequence → raw k-space. Bloch Party simulates every spin through every RF pulse, gradient and
ADC sample of a sequence, and every number along the way (flip angles, timings, gradient waveforms, T1/T2/PD and
field maps, coil sensitivities, the scanner's own imperfections) can be a tensor with requires_grad=True.
The simulated head above is 9.7 million spins, with the real sequences' sinc pulses, ramps, spoiling and slice
profiles, imaged through an 8-channel coil array on a laptop GPU.
| Differentiable, end to end | Autograd through the PyTorch reference, and a hand-written adjoint on the GPU: gradients reach the sequence, the tissue, the coils and the hardware model. Optimize a sequence, fit a scanner, train through the physics. |
| Fast | One GPU driver for Apple Metal and NVIDIA CUDA (same device code). A 3D 64³ GRE runs in 0.5 s on an RTX 4090; full 3D 128³ in ~3 min on an M4 laptop. |
| Realistic physics, opt-in | Sub-voxel isochromats, T2′, B0 from tissue susceptibility, B1⁺, 6-peak fat, magnetization transfer (rate model and generalized Bloch), CEST pools, diffusion (free and restricted), flow and motion, J-coupling. |
| Realistic hardware | Concomitant (Maxwell) fields, gradient nonlinearity, GIRF and eddy currents, B0 drift and respiration, full-wave coil fields, correlated receive noise. All differentiable in the hardware parameters. |
| Real sequences in, real data out | Lossless Pulseq read and write (.seq files a scanner can play), sampled BrainWeb heads with cited tissue tables, ISMRMRD HDF5 output with full provenance. |
| Checked, every feature | Against closed forms, a SciPy ODE solver, EPG, the signal equation, MRzero, and raw data from real scanners. Defaults stay bit-identical; ~1000 tests. |
git clone https://github.com/jonatanferm/blochparty && cd blochparty
uv sync # or: pip install -e .
uv run python examples/gre_demo.py # 8-coil GRE of Shepp-Logan -> outputs/gre_demo.pngimport blochparty as bp
phantom = bp.shepp_logan(64)
coils = bp.birdcage_sensitivities(phantom.pos, n_coils=8)
seq = bp.gre_2d(64, flip_deg=15.0, tr=10e-3, n_dummy=200)
kspace = bp.simulate(phantom, seq, coils).signal # (coils, n_adc) complex
image = bp.rss(bp.ifft2c(bp.kspace_grid(kspace, seq)))3D works the same way: bp.shepp_logan(32, ndim=3), bp.gre_3d(32), bp.reconstruct(...). Add
engine="gpu" to any simulate call to run it on Metal or CUDA.
More commands: tests, examples, benchmarks
uv sync --extra pulseq --extra mrzero --extra io --extra anatomy # everything optional
uv run pytest # the full suite, ~4 min on an M4 (GPU tests skip without a GPU)
uv run pytest -m "not slow" # the quick subset, under a minute
uv run python examples/optimize_contrast.py # gradient descent through the simulator (--gpu: the GPU adjoint)
uv run python examples/gre3d_128.py # full 3D 128^3 on the GPU, ~3 min on an M4
uv run python benchmarks/bench.py # timed 2D/3D workloads (--record to log)
uv run python benchmarks/bench.py --grad --backend gpu # forward + backward through the GPU adjoint
uv run python tools/readme_figures.py # this README's figuresA spin echo, as Bloch Party sees it: 36 isochromats spread over 60 Hz fan out after a 90°ₓ pulse, a 180°ᵧ pulse at 30 ms mirrors them, and they refocus at TE = 60 ms. The arrows are the simulator's magnetization at each frame; the dots are its ADC samples, on top of the closed form (agreement to 2e-3, set by the 50 µs hard pulses). A case with a known answer, so you can see the simulator is right; the real sequences below have none, and that is where it earns its keep.
L-BFGS on gradients through the Bloch simulation and the reconstruction finds the flip angle that maximizes
white/grey-matter contrast in a simulated spoiled GRE: 16.11° in 18 simulations, against 16.09° from the
closed-form steady state (examples/optimize_contrast.py).
blochparty.design builds on this: hardware and safety constraints (gradient, slew, B1, SAR,
PNS) with smooth penalties, CNR / SNR / PSF metrics, Cramér–Rao bounds, and a constrained optimizer.
Simulators are usually validated against closed forms and each other. Bloch Party also runs the scanner's own
.seq files on a digital model of the scanned object, with properties from independent references and
nothing fitted, and compares with the raw data the scanner measured
(validation/real/, docs/REALISM.md).
The ISMRM/NIST phantom on a 3 T Siemens Prisma, inversion-recovery spin echo, 14 spheres: simulating the actual sequence (sinc pulses and their slice profiles, crushers, spoilers, real timing) matches the measured curves to 1.3 %, where the analytic inversion-recovery formula misses by ~20 % (results). Other benchmarks cover multi-echo TSE, radial IR-bSSFP, CEST z-spectra, MT in BSA and a spiral TSE.
bp.sample_head(seed) returns a new head for every seed: a BrainWeb subject, smoothly deformed, with its own
tissue draws from a cited table (relaxation, MT, diffusion, susceptibility) and its own texture, ready to be
scanned and written out as ISMRMRD raw data with full provenance. With full-wave coil fields, the transmit field
and receive array come from Maxwell's equations too:
Every feature is checked against an independent reference (the record: docs/ROADMAP_ARCHIVE.md; the plan: ROADMAP.md). What other simulators do and the realism plan: docs/REALISM.md; which engine runs what: docs/ENGINES.md; hard-won lessons: docs/LESSONS.md; the project journal: docs/JOURNAL.md.
Anything numeric in a sequence or phantom can be a tensor with requires_grad=True
(flip angles, TR, gradient amplitudes, T1/T2/PD/B0/B1⁺/T2′/fat maps, coil maps).
One entry point, bp.simulate(phantom, seq, coils, ..., engine=), with the same arguments and result for
every engine, and one physics. Which features each engine runs, with forward and gradients, is the matrix in
docs/ENGINES.md, checked cell by cell by tests/engines/test_engines.py;
bp.engines.available(engine) says what runs on this machine.
engine="core"(the default): the reference. Plain PyTorch on any device, float32 or float64, differentiable by autograd. Every new effect lands here first.engine="metal"(blochparty.metal.simulate_metal): the engine for imaging-scale work, on the Apple GPU. Float32. Runs everything the core runs, free exchanging pools (CEST, up to five) included, except free pools together with the generalized Bloch bound pool. For CEST / MT saturation that combination is not needed: the rate model withBoundPool(cutoff=None)(the generalized model's own lineshape, no near-resonance cut) equals the generalized model to 5e-5 on 50 ms pulses and runs on the GPU (ROADMAP M1c). Differentiable through a hand-written adjoint on the GPU (sequence, phantom, coils,m_init, rate-model bound pool, scanner field model; not moving spins or free pools).engine="cuda"(blochparty.cuda.simulate_cuda): the Metal engine on an NVIDIA GPU, with the same arguments, results, adjoint and limits (the same device code and driver; kernels compiled at run time by NVRTC). An RTX 4090 runs the 3D 64^3 GRE benchmark in 0.5 s, against 2.4 s for Metal on an M4.engine="gpu": CUDA where an NVIDIA GPU is, else Metal. Scripts use this, so they run on either machine.engine="chunked"(bp.simulate_chunked): the core with a backward pass that holds one chunk of spins at a time, for gradients on large phantoms (no exchange, diffusion, motion, scanner model,FieldMapsorm_init).
The fused C++ CPU kernel (simulate_fused, float32 / float64 with a hand-written adjoint) was
retired on 2026-10-09 once the Metal adjoint passed its checks; it is in the git history.
kspace = bp.simulate(phantom, seq, coils, engine="gpu").signal # (coils, n_adc) complex64, back on the CPUphantom_from_maps turns 2D/3D maps into spins; the options below are off by default (one
spin per voxel centre, results unchanged bit for bit):
from blochparty.coils import birdcage_b1
from blochparty.phantom import b0_shim, b0_sphere
maps = bp.shepp_logan_maps(64)
grid = bp.grid_positions(64, 0.22).reshape(-1, 3)
air = b0_sphere(grid, (0.0, 0.07, 0.0), 0.01, 9.4e-6) # 1 cm air pocket in tissue, Hz
b0 = (b0_shim(grid, z2=300.0) + air).reshape(64, 64)
phantom = bp.phantom_from_maps(
maps["pd"], maps["t1"], maps["t2"], fov=0.22, db0=b0,
spins_per_voxel=4, jitter="stratified", seed=0, # 2x2 isochromats per voxel, PD / 4 each
t2prime=torch.full((64, 64), 0.05), # Lorentzian intra-voxel offsets: T2*
fat_fraction=(maps["label"] == 1).double(), # 6-peak fat spins in the "fat" ellipse
field_strength=3.0,
b1=birdcage_b1(grid, centre_brightening=0.3).reshape(64, 64)) # transmit scale- Sub-voxel isochromats (
spins_per_voxel=Kor per-side counts like(1, 8); regular sub-grid orjitter="stratified"; in-plane for 2D maps). Spins per voxel side must exceed the cycles of dephasing across a voxel that still carry signal (spoilers, stimulated echoes), else those configurations alias back as spurious echoes (validation/mrzero/RESULTS.md). Costs K× the spins; usesimulate_metal(its adjoint) orsimulate_chunkedfor gradients. - T2′ (
t2primemap): each voxel's spins get static offsets from a Lorentzian of half-width 1/(2πT2′) (Cauchy quantiles shuffled over the voxel, ort2prime_sampling="random"), so the FID decays with 1/T2* = 1/T2 + 1/T2′ and a spin echo refocuses it. K spins reproduce exp(−t/T2′) to ~0.5/√K of the initial signal over the first few T2′ (needs hundreds of spins per voxel for percent accuracy). - B0 maps:
b0_shim(offset, linear and second-order solid harmonics),b0_sphereandb0_cylinder(closed-form susceptibility fields, Lorentz corrected, B0 along z) return Hz at any positions; evaluate them atphantom.posto sample the field at every spin. - B1⁺:
Phantom.b1(None= 1) scales every RF pulse per spin (flip b1·α) insimulate,simulate_chunked,simulate_metal(forward and adjoint:b1gets gradients) andreference.signal_equation.coils.birdcage_b1(pos, centre_brightening, radius)is a CP birdcage field, uniform or with J0(kρ) centre brightening. - Fat (
fat_fractionmap): water keeps PD·(1 − f); one fat spin per peak ofFAT_PEAKS(−3.80 … +0.60 ppm, amplitudes normalised to 1) with PD·f·a_p, fat T1/T2 (fat_t1,fat_t2) and offset ppm·γ̄·B0 (field_strength, T): fat sits below water (−434 Hz for the main peak at 3 T). Fat spins share their water spin's position, T2′ offset and B1⁺.bp.shepp_logan(n, chemical_shift=True)turns its fat ellipse into fat.
sample_head(seed, root=...) returns a new head for every seed: a BrainWeb subject, smoothly
deformed, with its own tissue draws from the cited table (relaxation, MT, diffusion) and its own
texture; head.meta records every draw. io.write_dataset stores the result as ISMRMRD HDF5,
readable by Gadgetron or ismrmrd-python, with a /provenance group (sequence arrays and JSON,
the .seq file, the head's draws, seeds, engine, git commit, versions); io.read_dataset reads
it back. Both need the io extra (uv sync --extra io). examples/sampled_heads.py images ten heads
in three contrasts (figure).
from blochparty.io import write_dataset
head = bp.sample_head(7, root="validation/anatomy/data", voxel=(1e-3,) * 3)
k = round(-head.anatomy.origin[2] / head.anatomy.voxel[0]) # the z = 0 plane, where the slice is
ph = head.to_phantom(fov_region=(slice(k - 4, k + 5), slice(None), slice(None))) # B0 from the whole head
seq = bp.gre_2d(64, ramps=True, spoiling="rf", slice_thickness=5e-3)
coils = bp.birdcage_sensitivities(ph.pos, 8)
write_dataset("head7.h5", bp.simulate(ph, seq, coils, engine="gpu"), seq, phantom=head, seed=7, engine="gpu",
coils={"model": "birdcage", "n": 8})The default builders are idealised (hard pulse, instantaneous gradients, ideal spoiling) and
stay bit-identical. Opt in to the real versions, built within a System's hardware limits
(default: 40 mT/m, 170 T/m/s, 10 µs gradient / 1 µs RF / 0.1 µs ADC rasters, 100 µs RF dead
time, 30 µs ringdown; gradients in Hz/m):
from blochparty.builders import se_2d, tse_2d, bssfp_2d, epi_2d, cartesian_recon
seq = bp.gre_2d(64, spoiling="rf", ramps=True, slice_thickness=5e-3) # or spoiling="gradient"
seq = tse_2d(64, etl=8, refocus_flip_deg=[150, 120, 120, ...], ordering="centric")
seq = bssfp_2d(64, flip_deg=50.0) # alpha/2 prep, 180 deg phase cycling, TE = TR/2
seq = epi_2d(64) # single shot, blips on the readout ramps
image = bp.rss(cartesian_recon(bp.simulate(phantom, seq, coils).signal, seq))spoiling="gradient": a spoiler lobe brings the net readout-axis moment per TR tospoiler_cycles(default 4) cycles across a voxel, phase encodes are rewound;"rf"adds quadratic RF spoiling (117°, receiver phase follows). Spoiling acts on intra-voxel dephasing, so it needs several isochromats per voxel: with one spin at each voxel centre the spoiler is a whole number of turns and RF spoiling only modulates the signal line by line (ghosts).slice_thickness: windowed-sinc pulse (time_bw_product,apodization, default 2 ms) with slice-select gradient,slice_offsetvia a frequency offset, rephasing lobe including the ramps.ramps=True: trapezoids (minimum time, as pypulseq designs them).se_2d,bssfp_2d(and GRE) setmeta["kspace_shape"], sobp.reconstructworks.tse_2d(line ordering) andepi_2d(alternating readouts) setmeta["matrix"]andmeta["kspace_index"]instead;cartesian_kspace/cartesian_reconwork for all of them.- Building blocks for your own sequences (
blochparty.sequence):trapezoid(...)(by area, flat area or amplitude; any axis or direction),gradient_waveform(samples, raster),block_pulse,sinc_pulse,ADC, andSequenceBuilder.block(*gradients, rf=..., adc=...), which plays them together like a Pulseq block. Ramps are cut on the gradient raster and each segment carries its exact average gradient, so k-space is exact at every ADC sample. Limits are checked (per axis) and violations raise.
read_pulseq turns a .seq file (or a pypulseq.Sequence) into a Sequence, and
write_pulseq writes one back (both need the pulseq extra: pip install 'blochparty[pulseq]';
uv sync installs it for development):
from blochparty.pulseq import read_pulseq
seq = read_pulseq("gre.seq", kspace_shape=(64, 64)) # extra keywords go to seq.meta
kspace = bp.simulate(phantom, seq, coils).signal
seq.meta["adc_per_readout"], seq.meta["kspace_trajectory"] # samples per ADC; k from pypulseq
from blochparty.pulseq import write_pulseq
write_pulseq(bp.gre_2d(64, ramps=True, spoiling="rf", slice_thickness=5e-3), "gre.seq") # for the scanner- Blocks are split at every event boundary, so each ADC sample ends a segment; gradients use
the exact average over each segment, so k-space matches pypulseq's
calculate_kspaceto ~1e-10. Shaped RF, trapezoids, arbitrary and extended gradients, delays, frequency and phase offsets (including ppm), ADC phase modulation. Labels and triggers are ignored; other extensions (rotations, RF shims) raise. - Phases: Pulseq phase φ gives Mxy = i·e^{−iφ}·sin α (a real pulse still tips +z to +y), so
that a frequency offset f excites the slice at f/G as Pulseq defines it. MRzero reads the
phases as written:
read_pulseq(..., convention="mrzero")does the same (the mirror image). - Pulseq cannot express ideal spoiling; set
seq.spoil[i] = Trueafter import if wanted. - Files are read with every number as written (pypulseq's default merges events after rounding
amplitudes to six digits and timings to 1 µs; the scanner files in
validation/realread identically either way). write_pulseqis lossless: written and read back, GRE (ramps, slice selection, RF spoiling), TSE, bSSFP and EPI simulate identically to 1e-9, pypulseq'scheck_timingpasses and k-space equals itscalculate_kspace(tests/sequences/test_pulseq_write.py). It writes Pulseq 1.5 itself at full precision (pypulseq's writer keeps six digits), one Pulseq block perSequenceBuilder.blockcall (the builder records them inseq.meta["blocks"]; an EPI train's block is cut between its ADCs). It raises for what a scanner cannot play: ideal spoilers (spoil="drop"writes without them), the idealrf/readoutcalls and instantaneous gradients (useramps=Truebuilders), timings off the rasters, and sequences changed after building (e.g. byapply_girf: write the nominal sequence). Imported files are written back from their own events.- Cross-validation against MRzero:
uv sync --extra mrzero, thenuv run python validation/mrzero/compare_mrzero.py(writes validation/mrzero/RESULTS.md) oruv run pytest -m crosscheck.
Real gradients are not ideal. All of this is opt-in (scanner=None, no b0_offset: results
unchanged bit for bit), runs in simulate and simulate_metal (forward and adjoint), and is
differentiable in the hardware parameters, so a scanner's imperfections can be fitted:
from blochparty.fields import GradientNonlinearity, Scanner
from blochparty.girf import GIRF, EddyCurrents, apply_girf
from blochparty.drift import linear_drift, respiration
scanner = Scanner(field_strength=0.55, # concomitant fields (leading order)
nonlinearity=GradientNonlinearity.from_file("coil.grad")) # gradunwarp-style
played = apply_girf(seq, [GIRF.identity(delay=[2e-6, 2e-6, 3e-6]), # per-axis delays
EddyCurrents.per_axis([[0.01], [0.01], [0.02]], [[0.5e-3]] * 3,
b0_amplitude=[[1e-5]] * 3, b0_time_constant=[[1e-3]] * 3)])
played = respiration(linear_drift(played, rate=0.01), amplitude=3.0, period=4.0, gradient=(0.0, 20.0, 5.0))
kspace = bp.simulate(phantom, played, coils, scanner=scanner).signal- Concomitant (Maxwell) fields (
Scanner(field_strength=B0)): the transverse field components a cylindrical coil must have (div B = curl B = 0) shift the precession frequency by f_c = [(gx² + gy²) z² + gz² (x² + y²)/4 − gx gz xz − gy gz yz] / (2 f0) (Bernstein;z_asymmetryfor asymmetric z coils). It is a per-spin quadratic form in g, so free runs stay closed form (cumulative ∫gᵢgⱼ dt).concomitant="exact"uses |B| of the full vector field instead (very low field, checks). Ramps on the raster are staircases: their ∫g² is low by (step)²·dt/12 per segment. - Gradient nonlinearity (
GradientNonlinearity(alpha, beta, r0)or.from_file): per-axis solid-harmonic deviation of each coil (gradunwarp's Siemens convention,.gradA( n, m)lines oralpha_x n mlines); spins are encoded at f(r) = r + d(r). Gradients reach the coefficients. - GIRF and eddy currents (
apply_girf(seq, model), a sequence transform):GIRFimpulse responses (taps on the gradient raster, orfrom_transfer_function, with delays and cross terms, row 4 = B0),EddyCurrentsmulti-exponential terms (amplitudes and time constants differentiable, B0 terms included). Each segment gets the exact average of the response to the nominal staircase, so k-space is exact at every segment end. - Uniform field per segment:
Sequence.b0_offset(S,) [Hz] (None = zeros) adds to every spin's off-resonance, also during RF; B0 eddy currents and drift land there. - Drift and physiology (
blochparty.drift):linear_drift,exponential_drift,respiration(uniform + linear terms with a period) add exact segment averages tob0_offsetand (for linear fields) to the gradients.
Backprop through simulate keeps every spin's state at every segment, so memory grows as
spins × segments. When that no longer fits, swap in simulate_chunked: same arguments
and result, but the backward pass recomputes the simulation one spin chunk at a time, so
the graph it holds covers only spin_chunk spins.
from blochparty.chunked import simulate_chunked
kspace = simulate_chunked(phantom, seq, coils, spin_chunk=4096).signal
loss(kspace).backward() # same gradients as with simulate (to ~1e-12 in float64)- Use it for gradients on large phantoms (3D, sub-voxel spins); plain forward runs gain
nothing from it. It costs about one extra forward pass (~1.5×
simulateforward+backward) plus a fixed per-segment Python cost per chunk, so keep chunks in the thousands of spins. checkpoint_everybounds the other direction (segments) and combines with it.- Autograd also keeps a few tens of kB of bookkeeping per segment regardless of spin count, so for long sequences that floor, not the chunk, sets the minimum memory.
- First-order gradients only (no double backward).
The GPU engines (engine="gpu", "metal", "cuda") are differentiable through a hand-written adjoint
on the GPU instead of autograd (float32):
kspace = bp.simulate(phantom, seq, coils, engine="gpu").signal # compiles the kernels on first use
loss(kspace).backward() # the core's gradients to ~1e-6 .. 1e-4 (float32)- Gradients reach the sequence (
dt,rf,grad,adc_phase,b0_offset,rf_freq), the phantom (pos,pd,t1,t2,db0,b1), the coils,m_init, the rate-model bound pool, the scanner field model and staticFieldMaps; moving spins, free pools and the generalized bound pool raise (the core differentiates those). - The forward stores every spin's state each
checkpoint_everysegments (a multiple of 64, default ≈ √segments); the backward replays one interval at a time and sweeps it in reverse. Results are bit-identical for anycheckpoint_everyand from run to run (no atomics). - Forward + backward costs ~5-7 forward passes (3D GRE, 8 coils), with no autograd graph.
- First-order only (no double backward): a Cramér–Rao bound through it takes its Jacobian by
finite differences (
design.crb(..., method="fd4")).
blochparty.design adds what an optimizer (or an agent) needs around the simulator. Everything
is a differentiable function of the sequence's tensors or of simulated images:
from blochparty import design
hw = design.Hardware(max_grad=40, max_slew=150, max_b1=20) # mT/m, T/m/s, µT
loss = -design.cnr(image, wm, gm, sigma) + sum(design.penalties(seq, hw).values())
var = design.crb(signal_fn, theta) # Cramér–Rao bounds from the simulated Jacobian
report = design.design_report(seq, phantom, masks=masks, contrast_pairs=[("wm", "gm")], kspace_sigma=0.05)
report["violations"] # ["slew x exceeded at 128 boundaries (128 ranges); worst at boundary 402 (t = 2002.685 ms) by 699 % ...", ...]- Constraints, in scanner units: gradient amplitude [mT/m] and slew [T/m/s] per axis, peak
B1 [µT] (Hz → T via γ̄), RF energy Σ|B1|²·dt and a SAR proxy (mean |B1|², optionally scaled
and windowed), an approximate PNS estimate (chronaxie-filtered dG/dt; reproduces the IEC
hyperbolic strength–duration law, but is not a coil-specific model), scan time. Each has a
smooth penalty (
penalties) and violation reports naming segment ranges, times and excess. - A gradient step is taken to ramp over at most one gradient raster time (10 µs): ramps sampled
on the raster (as
read_pulseqdoes) give their true slew, while the builders' instantaneous gradients show up as violations instead of being hidden by long segments. - Metrics: tissue contrast, CNR, SNR and SNR efficiency (noise σ given, or propagated from the
coil noise model through any reconstruction by pseudo-replicas), PSF and its FWHM / sidelobes
from a simulated point spin, and the Cramér–Rao bound with the Jacobian w.r.t. tissue
parameters taken by autograd (
method="autograd", differentiable again throughsimulate) or central differences (method="fd", or"fd4"for float32 engines; differentiable throughsimulate_metal). minimize: augmented Lagrangian around L-BFGS, so active constraints hold exactly at the end.design_report: JSON-serialisable timing, constraints with margins, PSF and image metrics.
Optimizations with independently known answers (each is also a test; they run through the core
in float64, DESPOT1 also through the GPU adjoint with --gpu):
uv run python examples/design_despot1.py # VFA T1 mapping: CRB-optimal flips give 70.71 % of Ernst (Deoni 2003)
uv run python examples/design_contrast_tr.py # WM/GM contrast, flip and TR free under a scan-time budget
uv run python examples/design_tse_flips.py # low-SAR TSE refocusing train, echoes >= target (vs EPG + SLSQP)
uv run python examples/design_report.py # the report for an 8-coil GRE -> outputs/design_report.json| module | contents |
|---|---|
anatomy/ |
Anatomies on a physical grid (BrainWeb, QSM, AHEAD and IXI heads with cited tissue properties), the head sampler and its edits, and sub-voxel spins from them. Modules: ahead, brainweb, deformation, edits, grid, ixi, phantom, qsm, sampler, tables, tissuedb. |
coils.py |
Receive coil sensitivities and thermal noise. |
constants.py |
Physical constants shared across modules. |
design/ |
Sequence design: hardware / safety constraints, image-quality metrics and losses, and a machine-readable design report. Modules: estimation, hardware, metrics, optimize, parameters, problems, report. |
em.py |
Full-wave coil fields into blochparty: B1+ maps, receive sensitivities and noise covariance. |
engines/ |
How a simulation is run: simulate(..., engine=) (blochparty.simulate) on the PyTorch core, the chunked core or a GPU engine (Metal, CUDA). Modules: capabilities, chunked, core, gpu, prepare. |
epg.py |
Extended Phase Graph (EPG) reference model. |
exchange.py |
Magnetization transfer: a bound (semi-solid) pool exchanging with the free water. |
fields.py |
Scanner field model: what the spins see beyond the ideal B0 + G.r (REALISM.md, R1). |
generalized_bloch.py |
Generalized Bloch model of the semi-solid (bound) pool (Asslander et al., arXiv 2107.11000). |
generate/ |
Training data (ROADMAP M7): a spec and a seed -> simulated samples with their truth, written with provenance. Modules: heads, protocols, sample, spec. |
io/ |
Raw data in and out: simulated acquisitions as ISMRMRD HDF5 with full provenance (ismrmrd: write_dataset, read_dataset) and a minimal reader for Siemens twix files (twix). Modules: ismrmrd, twix. |
jcoupling.py |
J-coupled protons under spin-echo trains: density matrices for small coupled spin fragments (ROADMAP M6.1). |
loops.py |
Physically based coils: arrays of circular loops in the quasi-static limit. |
maps.py |
Scanner-frame field maps, sampled where each spin is. |
montecarlo.py |
Monte Carlo estimators for simulations repeated over independent random seeds (spin positions, walks): the debiased power and magnitude of K complex-image estimates, the leave-one-seed-out jackknife of any statistic, and scrambled Sobol points for quasi-Monte-Carlo spin placement. |
motion.py |
Moving spins: flow, periodic deformation and rigid motion. |
phantom.py |
Phantoms: collections of isochromats (spins) with tissue properties. |
receive.py |
The receive chain after the coils: what a scanner's electronics do to the signal. |
recon.py |
Reconstruction for Cartesian data: k-space gridding, centred FFTs, RSS and coil combination; and for undersampled data, line masks (uniform, variable-density, random) and CG-SENSE with given coil maps. |
reference.py |
Reference models used to validate the Bloch simulator. |
restriction.py |
Restricted diffusion: every spin walks inside its own impermeable compartment. |
result.py |
What a simulation returns, whichever engine ran it. |
rng.py |
Counter-based random numbers shared by every engine: Philox4x32-10 (Salmon et al., SC 2011). |
sequence.py |
Sequence representation: a flat list of piecewise-constant segments. |
sequences/ |
Building sequences: the builder and its events (builder), ready-made sequences (library), the Sequence.meta keys (meta), Pulseq import and export (pulseq), and the hardware's effects on a sequence: gradient impulse responses and eddy currents (girf), B0 drift and respiration (drift), the RF amplifier (transmit). Modules: builder, drift, girf, library, meta, pulseq, transmit. |
susceptibility.py |
Scalar susceptibility -> Lorentz-corrected spin frequency, and low-order shimming. |
Tests live in tests/<area>/: engines, physics, sequences, phantoms, signal, validation, design and
docs; uv run pytest tests/engines runs one area. Cases shared between files are in tests/cases.py, the
comparison helpers in tests/helpers.py, and the gpu fixture (every GPU engine on this machine) in
tests/conftest.py.
- Units (Pulseq-style): RF in Hz (γ̄·B1), gradients in Hz/m (γ̄·G), off-resonance in Hz, time in s, position in m. Gradient area = k-space position in cycles/m.
- Rotation: dM/dt = γ M × B with γ > 0. A pulse along +x tips +z to +y; RF phase φ puts the magnetization at Mxy = i·e^{iφ}·sin α.
- Signal: Mxy = Mx + iMy evolves as e^{−i2πft} at offset f; s(k) = Σ ρ(r)·C(r)·e^{−i2πk·r}; ADC phase ψ demodulates by e^{−iψ}.
- Grid: index i ↔ position (i − n/2)·FOV/n and k = (i − n/2)/FOV; arrays are ordered (z, y, x), so the last axis is x. 3D GRE lines run with ky fastest, then kz.
- ADC timing: sample i of a readout sits at (i + ½)·dwell after the ADC start (Pulseq).
- Pulseq: RF field = conj(Pulseq RF waveform), receiver phase = −(Pulseq ADC phase); see
blochparty/sequences/pulseq/for why and for the MRzero mapping.
Zero-Clause BSD: use, copy, modify and distribute it for any purpose, with or without fee, no
attribution required. The datasets the validation scripts download (BrainWeb, the NIST phantom scans, the
CEST and MT sets, the IT'IS tissue values cited in anatomy/tissuedb/sources.csv) keep their own terms, recorded
with each source.





