Evidence · sdcflows
sdcflows’ field-map estimation
sdcflows turns a gradient-echo field map into the smooth field that corrects susceptibility distortion: the phase difference to radians and, after PRELUDE, to Hz; the field map’s cubic B-spline fit (scikit-learn’s ridge regression); the field evaluated on other grids and a series unwarped with it. fMRIPrep runs these steps for every phase-difference field map. LARMORX’s port is a replica of sdcflows 2.17.1 with the arithmetic of scikit-learn, SciPy, numpy and nibabel. In reproduce it gives sdcflows’ outputs bit for bit in all 37 cases of its record. On fMRIPrep’s seven phase-difference estimators it gives them in fix too, and fMRIPrep’s own files, at any thread count. Its default, fix, corrects sdcflows’ defects or refuses them with a clear error, each with sdcflows’ result on request. The fit takes 6.5 to 7.8 times less time at 14 threads, and 22 to 32 % of sdcflows’ peak memory at one.
- Ports
- replica
larmorxApache-2.0: cratelarmorx-sdcflows,lx.sdcflows, translated from sdcflows 2.17.1's Python (Apache-2.0):BSplineApprox,B0FieldTransform,ApplyCoeffsField,TOPUPCoeffReorient, the phase-difference workflow and its steps, with scikit-learn 1.9.1's ridge regression and the arithmetic of SciPy 1.18.1, numpy 2.5.4 (OpenBLAS 0.3.34) and nibabel 5.4.2
- replica
- Status
- replica validated (marked before the statuses' definition)
- Records
- standard comparison (sdcflows 2.17.1) · benchmark sdcflows-fieldmap · findings sdcflows-fieldmap
- Reference
- API page sdcflows-fieldmap
What is compared
Echo-planar images are distorted wherever the main field B₀ is not uniform: a voxel’s signal is displaced along the phase-encoding axis by the local off-resonance frequency (in Hz) times the readout time. A field map measures that frequency. A gradient-echo field map stores it as a phase: the phase difference between two echoes is 2π times the frequency times the echo-time difference, known only up to whole cycles of 2π. sdcflows (the NiPreps developers, Apache-2.0) is the library fMRIPrep uses to estimate the field and correct the distortion.
For a phase-difference field map fMRIPrep 25.2.6 runs sdcflows’ init_phdiff_wf:
- the scanner’s phase map is rescaled to radians from its minimum and maximum (
au2rads; two phase images are each rescaled and subtracted,subtract_phases); - FSL’s PRELUDE unwraps it inside the magnitude’s brain mask;
- it is divided by 2π and the echo-time difference (
phdiff2fmap): the field map in Hz.
sdcflows’ BSplineApprox (fMRIPrep’s node bs_filter) then approximates the field map by a smooth field. Its cubic B-splines sit on a control grid 16 × 16 × 10 mm apart, their coefficients fitted inside the brain mask by scikit-learn’s ridge regression (Ridge, α = 10⁻⁴, its sparse conjugate-gradient solver). The field map’s median inside the mask is subtracted before the fit, so the fitted field is centred on zero. The fitted field is evaluated everywhere (extrapolated beyond the mask), and the fitting error kept. fMRIPrep stores the coefficients and evaluates them on every grid it resamples a series onto (B0FieldTransform): it unwarps inside its one-shot resampler (its page), while sdcflows’ own ApplyCoeffsField evaluates the field on the series’ grid and unwarps it there.
The replica runs beside sdcflows 2.17.1, run in-process with the newest releases of the libraries under it (LARMORX’s reference) and with the releases the other comparisons share. fMRIPrep’s own files are the ones it wrote in its runs, with sdcflows 2.15.1 in fMRIPrep 25.2.6’s image.
import larmorx as lx
# fMRIPrep's phase-difference estimator: radians, PRELUDE, Hz
prep = lx.sdcflows.phdiff_workflow(
"sub-01_magnitude1_brain.nii.gz", ["sub-01_phasediff.nii.gz"],
[{"EchoTime1": 0.00492, "EchoTime2": 0.00738}], "sub-01_magnitude1_brain_mask.nii.gz",
out_dir="work",
)
# the B-spline fit (fMRIPrep's bs_filter): coefficients, field, error, extrapolated field
fit = lx.sdcflows.bspline_approx(prep.fieldmap.image, "sub-01_brain_mask.nii.gz",
out_dir="work", n_threads=8)
# the field on a BOLD reference, and a series unwarped with it
xf = lx.sdcflows.B0FieldTransform(coeffs=list(fit.coefficients))
xf.fit("sub-01_boldref.nii.gz")
corrected = xf.apply("sub-01_bold.nii.gz", pe_dir="j-", ro_time=0.0425, n_threads=8)The API page describes every function and option. How to read what follows: how to read the evidence.
Its port
sdcflows comes under the Apache-2.0 licence, as LARMORX does, so the replica is in larmorx itself, translated bit for bit as ANTs and fMRIPrep’s resampler are. sdcflows’ Python is the specification, with the arithmetic of the libraries it calls:
- the B-spline weights stored as SciPy’s sparse products store them, explicit zeros included;
- the ridge regression as scikit-learn’s
sparse_cgcalls SciPy’s conjugate gradients, every float32 dot product summed in the order of the OpenBLAS kernel numpy calls; - files read and written with nibabel’s arithmetic: the scale factors nibabel computes in x87’s extended precision (computed exactly in LARMORX, so every platform writes Linux’s bits) and the quaternions it derives with numpy’s SVD and eigenvalue routines (replicated).
The heavy parts run in Rust (larmorx-sdcflows) on the call’s threads, every sum kept in sdcflows’ order, so n_threads never changes a bit. At one thread the fit stores its collocation matrix once (8 bytes per weight, where sdcflows and scikit-learn hold it at least three times) and reads it at every product. At more threads it evaluates the weights at every product, which is faster there and holds no matrix. The sums are the same, in the same order, either way.
PRELUDE runs through lx.fsl.prelude (its page). A clean room of sdcflows’ steps is planned after FreeSurfer (roadmap).
The verdicts at a glance
The replica is a translation of sdcflows’ source, so the question is whether it gives sdcflows’ bytes.
Select a segment to list its cases below.
The record runs sdcflows 2.17.1 in-process as the reference, with the newest releases of the libraries under it (numpy 2.5.4 with OpenBLAS 0.3.34, SciPy 1.18.1, scikit-learn 1.9.1, nibabel 5.4.2). It compares the replica with it in reproduce (upstream_defects="reproduce"): every array, file (decompressed), header, warning and message, bit for bit. Its 37 cases pass, with 821 checks:
- 9 scripts cover every function of the port. They run on generated inputs (odd and oblique grids, qform-only and NIfTI-2 headers, NaN values, single slices, 4D images, every option and failure) and on fMRIPrep’s real calls (its phase-difference steps, its seven fits and its coefficients’ reorientation), where fMRIPrep’s own files of its runs are compared too.
- 28 permanent cases come from random testing.
In 33 of the 37 the replica’s default, fix, gives the same bytes. In the other 4 it corrects one of sdcflows’ defects (SDC-01, SDC-02, SDC-07, SDC-10: deliberate correction, below), and the record holds it to sdcflows’ own construction with the correction made in its pieces.
In fMRIPrep: seven phase-difference estimators
fMRIPrep 25.2.6 estimated seven phase-difference field maps on four of its runs: ds005454-sub-16 (7 T), ds002603-sub-01, ds002422-sub-02 (two, at 1.5 T) and ds001600-sub-1 (three protocols). Each estimator’s nodes were run again here on the inputs fMRIPrep gave them:
- sdcflows 2.17.1 with the newest releases and with the releases the other comparisons share;
- the replica at 1 and 14 threads, in
fixand inreproduce; - the replica’s whole workflow with PRELUDE’s clean room (
lx.fsl.prelude).
fMRIPrep’s own files stand beside them. Every comparison gives the same values, every one.
In each example below the input panels are the scanner’s phase map, the magnitude, sdcflows’ brain mask over it and fMRIPrep’s unwrapped phase (PRELUDE’s output, which the next step turns into Hz). The outputs, chosen above the viewer, are the phase difference in radians, the field map in Hz, the fitted field extrapolated over the field of view, and the fitting error inside the mask. The viewer opens on the field map.
ds005454: a GRE phase difference at 7 T
Worked example
fMRIPrep's field map from ds005454-sub-16's phase difference, and its B-spline fit
What this shows: In reproduce the replica gives every value of sdcflows 2.17.1’s four outputs (the phase difference in radians, the field map in Hz, the fitted field and the fitting error), at 1 and 14 threads alike, and fMRIPrep’s own files of this estimator hold the same values. Its whole workflow, with PRELUDE’s clean room, gives fMRIPrep’s field map in every voxel. No correction by default changes this call, and sdcflows gives the same values with both releases of the libraries.
- Replica against sdcflows 2.17.1Bit-identical
fMRIPrep 25.2.6’s phase-difference estimator of ds005454-sub-16 (a GRE phase difference at 7 T (Siemens), 112 × 112 × 70 voxels of 2 mm; sdcflows’ wf_gre16), step by step on the inputs its nodes were given: the scanner’s phase map rescaled to radians (the phase difference PRELUDE unwraps), fMRIPrep’s own unwrapped phase turned into Hz (the field map), and that field map approximated by cubic B-splines inside the brain mask (bs_filter): the smooth fitted field, extrapolated beyond the mask, and the fitting error. sdcflows 2.17.1 and the replica compute every output; fMRIPrep’s own files and the replica’s whole workflow (with PRELUDE) are compared with them value by value.
- Data
- OpenNeuro ds005454, sub-16 (CC-BY-4.0): the field map’s phase and magnitude as fMRIPrep’s nodes were given them; shown inside sdcflows’ brain mask of the magnitude, dilated by 2 voxels, so no face shows
- Nodes
- fMRIPrep 25.2.6,
work/fmriprep_25_2_wf/sub_16_wf/fmap_preproc_wf/wf_gre16:phdiff_wf/phmap2rads,calc_phdiff,compfmapandbs_filter - Fit
- BSplineApprox as
bs_filtercalls it: spacing [[16.0, 16.0, 10.0]] mm, ridge alpha 0.0001, recentred by the median, extrapolated, zooms_min 1; Δ TE from the echo times 3.06 and 4.08 ms - Coefficients
- the 16 × 16 × 17 B-spline coefficients (4,352 values, 16 × 16 × 10 mm spacing): the replica’s equal sdcflows’ and fMRIPrep’s own
*_coeff000file, every one, at 1 and 14 threads, infixand inreproduce; 187,289 voxels inside the mask, 354 conjugate-gradient iterations - Programs
- sdcflows 2.17.1 in both kept environments (in process, its nipype interfaces); the replica’s
lx.sdcflowsat commit61185255c67d; numpy’s OpenBLAS on its Haswell kernels, one thread, as fMRIPrep’s nodes - Grid
- 112 × 112 × 70 voxels of 2 × 2 × 2.1 mm; shown: 75 × 93 × 70 around the brain
Data shown
- fMRIPrep boot camp 7T training dataset (OpenNeuro ds005454, version 1.0.0, doi:10.18112/openneuro.ds005454.v1.0.0), Creative Commons Attribution 4.0 (CC BY 4.0). Attribution: Sleight EC, Esteban O, Grouiller F. fMRIPrep boot camp -- 7T training dataset. OpenNeuro ds005454, version 1.0.0. doi:10.18112/openneuro.ds005454.v1.0.0 The images shown are adapted from it: reoriented to RAS, cropped to the region shown, masked outside it, and shown as the outputs of the programs compared.




Bit-identical878,080 of 878,080 voxels equal
Bit-identical878,080 of 878,080 voxels equal
Bit-identical878,080 of 878,080 voxels equal
Axial slice 30 of 70; the crosshair where the field is strongest in the slice; choose the output (the phase difference, the field map, the fitted field, its error) above the images. The interactive viewer needs JavaScript; the metrics below are complete without it.
Every comparison, computed in float64 over every voxel of the outputs
| Comparison (A − B), verdict and reason | Output | max |Δ| | Values that differ | RMS of Δ | max |Δ| ÷ range | 1 − NCC |
|---|---|---|---|---|---|---|
| The original against itself: the yardstick | ||||||
| sdcflows: numpy 2.5.4 / SciPy 1.18.1 − numpy 2.3.5 / SciPy 1.15.3referenceFor reference, the originals’ own step between two releases of the libraries: with numpy 2.5.4 (OpenBLAS 0.3.34) and SciPy 1.18.1 sdcflows gives the same values as with numpy 2.3.5 (OpenBLAS 0.3.30) and SciPy 1.15.3, every one: sdcflows 2.15.1 to 2.17.1 and the libraries’ releases change nothing on these paths. the record | every output | identical: 0 of 878,080 values differ | ||||
| The replica against the original | ||||||
| replica − sdcflows 2.17.1Bit-identicalEvery value of the four outputs is sdcflows’: the phase in radians (numpy’s float64 rescaling rounded to float32), the field map in Hz, the ridge regression’s coefficients (scikit-learn’s sparse_cg, SciPy’s conjugate gradients with OpenBLAS’s float32 dot products, in their order) and the field they give inside and outside the mask, the fitting error. | every output | identical: 0 of 878,080 values differ | ||||
| The replica against fMRIPrep's output | ||||||
replica − fMRIPrep's outputBit-identicalfMRIPrep 25.2.6’s own files of this estimator (sdcflows 2.15.1 in its image) hold the same values: the phase difference PRELUDE was given, the field map, the extrapolated field (*_extra) the run used. | every output | identical: 0 of 878,080 values differ | ||||
replica, whole workflow with PRELUDE's clean room − fMRIPrep's outputBit-identicalThe replica’s whole phase-difference workflow, with PRELUDE’s clean room (lx.fsl.prelude, written from its specification), gives fMRIPrep’s field map in every voxel. | both outputs | identical: 0 of 878,080 values differ | ||||
| The replica against itself: thread counts, fix and reproduce | ||||||
| replica: 14 threads − 1 threadBit-identicalThe same bytes at 1 and 14 threads (at one thread the fit stores the collocation matrix, at more it evaluates the weights at every product: the same sums in the same order). | every output | identical: 0 of 878,080 values differ | ||||
replica: fix − reproduceBit-identicalNo correction by default applies to fMRIPrep’s call: fix and reproduce give the same values. | every output | identical: 0 of 878,080 values differ | ||||
Δ is A − B over all 878,080 voxels of each output file, not only those shown; fMRIPrep’s own files and the replica’s workflow are compared over their files (fMRIPrep keeps no fitting error, the workflow ends at the field map). The record’s threshold: in reproduce, every array, file (decompressed), header, warning and message bit-identical to sdcflows 2.17.1’s.
Provenance of this example
- Data: OpenNeuro ds005454, sub-16, CC-BY-4.0
- Inputs: phase map 0 (sha256 ef84f4949b28f3fb…); unwrapped (sha256 4800254623c56c01…); fmap (sha256 aa27ea0e32694d98…); mask (sha256 d748a07583ecf543…); magnitude (sha256 da6b994811a1e00b…); prelude_mask (sha256 d748a07583ecf543…); fMRIPrep’s own rads (sha256 c41556eee49fa98d…); fMRIPrep’s own fmap (sha256 aa27ea0e32694d98…); fMRIPrep’s own extrapolated (sha256 9dd937b4332cc7ea…); fMRIPrep’s own coeff (sha256 cc0b161dd80d5ebf…)
- Runs: figures cache entry
sdcflows-fieldmap/estimator-ds005454, computed 2026-11-08T09:32:54+00:00 with larmorx61185255c67d; sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.5.4 (OpenBLAS 0.3.34), SciPy 1.18.1 (oracles/python-newest: larmorx’s reference); sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.3.5 (OpenBLAS 0.3.30), SciPy 1.15.3 (the shared .venv); every command, its environment, threads and exit status are in itsRUN_INFO.json
Every number above is in sdcflows-fieldmap.json, exported by python -m larmorx_validation evidence sdcflows-fieldmap.
ds002603: a Philips phase difference at 2 mm
Worked example
fMRIPrep's field map from ds002603-sub-01's phase difference, and its B-spline fit
What this shows: In reproduce the replica gives every value of sdcflows 2.17.1’s four outputs (the phase difference in radians, the field map in Hz, the fitted field and the fitting error), at 1 and 14 threads alike, and fMRIPrep’s own files of this estimator hold the same values. Its whole workflow, with PRELUDE’s clean room, gives fMRIPrep’s field map in every voxel. No correction by default changes this call, and sdcflows gives the same values with both releases of the libraries.
- Replica against sdcflows 2.17.1Bit-identical
fMRIPrep 25.2.6’s phase-difference estimator of ds002603-sub-01 (a Philips phase difference at 3 T (acq-Mm2), 128 × 128 × 128 voxels of 2 mm; sdcflows’ wf_auto_00000), step by step on the inputs its nodes were given: the scanner’s phase map rescaled to radians (the phase difference PRELUDE unwraps), fMRIPrep’s own unwrapped phase turned into Hz (the field map), and that field map approximated by cubic B-splines inside the brain mask (bs_filter): the smooth fitted field, extrapolated beyond the mask, and the fitting error. sdcflows 2.17.1 and the replica compute every output; fMRIPrep’s own files and the replica’s whole workflow (with PRELUDE) are compared with them value by value.
- Data
- OpenNeuro ds002603, sub-01 (CC0-1.0): the field map’s phase and magnitude as fMRIPrep’s nodes were given them; shown inside sdcflows’ brain mask of the magnitude, dilated by 2 voxels, so no face shows
- Nodes
- fMRIPrep 25.2.6,
work/fmriprep_25_2_wf/sub_01_wf/fmap_preproc_wf/wf_auto_00000:phdiff_wf/phmap2rads,calc_phdiff,compfmapandbs_filter - Fit
- BSplineApprox as
bs_filtercalls it: spacing [[16.0, 16.0, 10.0]] mm, ridge alpha 0.0001, recentred by the median, extrapolated, zooms_min 1; Δ TE from the echo times 3 and 8 ms - Coefficients
- the 18 × 18 × 28 B-spline coefficients (9,072 values, 16 × 16 × 10 mm spacing): the replica’s equal sdcflows’ and fMRIPrep’s own
*_coeff000file, every one, at 1 and 14 threads, infixand inreproduce; 265,356 voxels inside the mask, 232 conjugate-gradient iterations - Programs
- sdcflows 2.17.1 in both kept environments (in process, its nipype interfaces); the replica’s
lx.sdcflowsat commit61185255c67d; numpy’s OpenBLAS on its Haswell kernels, one thread, as fMRIPrep’s nodes - Grid
- 128 × 128 × 128 voxels of 2 × 2 × 2 mm; shown: 82 × 100 × 84 around the brain
Data shown
- MB-EPI-comparison (OpenNeuro ds002603, version 1.0.0, doi:10.18112/openneuro.ds002603.v1.0.0), CC0 1.0 public-domain dedication.




Bit-identical2,097,152 of 2,097,152 voxels equal
Bit-identical2,097,152 of 2,097,152 voxels equal
Bit-identical2,097,152 of 2,097,152 voxels equal
Axial slice 43 of 84; the crosshair where the field is strongest in the slice; choose the output (the phase difference, the field map, the fitted field, its error) above the images. The interactive viewer needs JavaScript; the metrics below are complete without it.
Every comparison, computed in float64 over every voxel of the outputs
| Comparison (A − B), verdict and reason | Output | max |Δ| | Values that differ | RMS of Δ | max |Δ| ÷ range | 1 − NCC |
|---|---|---|---|---|---|---|
| The original against itself: the yardstick | ||||||
| sdcflows: numpy 2.5.4 / SciPy 1.18.1 − numpy 2.3.5 / SciPy 1.15.3referenceFor reference, the originals’ own step between two releases of the libraries: with numpy 2.5.4 (OpenBLAS 0.3.34) and SciPy 1.18.1 sdcflows gives the same values as with numpy 2.3.5 (OpenBLAS 0.3.30) and SciPy 1.15.3, every one: sdcflows 2.15.1 to 2.17.1 and the libraries’ releases change nothing on these paths. the record | every output | identical: 0 of 2,097,152 values differ | ||||
| The replica against the original | ||||||
| replica − sdcflows 2.17.1Bit-identicalEvery value of the four outputs is sdcflows’: the phase in radians (numpy’s float64 rescaling rounded to float32), the field map in Hz, the ridge regression’s coefficients (scikit-learn’s sparse_cg, SciPy’s conjugate gradients with OpenBLAS’s float32 dot products, in their order) and the field they give inside and outside the mask, the fitting error. | every output | identical: 0 of 2,097,152 values differ | ||||
| The replica against fMRIPrep's output | ||||||
replica − fMRIPrep's outputBit-identicalfMRIPrep 25.2.6’s own files of this estimator (sdcflows 2.15.1 in its image) hold the same values: the phase difference PRELUDE was given, the field map, the extrapolated field (*_extra) the run used. | every output | identical: 0 of 2,097,152 values differ | ||||
replica, whole workflow with PRELUDE's clean room − fMRIPrep's outputBit-identicalThe replica’s whole phase-difference workflow, with PRELUDE’s clean room (lx.fsl.prelude, written from its specification), gives fMRIPrep’s field map in every voxel. | both outputs | identical: 0 of 2,097,152 values differ | ||||
| The replica against itself: thread counts, fix and reproduce | ||||||
| replica: 14 threads − 1 threadBit-identicalThe same bytes at 1 and 14 threads (at one thread the fit stores the collocation matrix, at more it evaluates the weights at every product: the same sums in the same order). | every output | identical: 0 of 2,097,152 values differ | ||||
replica: fix − reproduceBit-identicalNo correction by default applies to fMRIPrep’s call: fix and reproduce give the same values. | every output | identical: 0 of 2,097,152 values differ | ||||
Δ is A − B over all 2,097,152 voxels of each output file, not only those shown; fMRIPrep’s own files and the replica’s workflow are compared over their files (fMRIPrep keeps no fitting error, the workflow ends at the field map). The record’s threshold: in reproduce, every array, file (decompressed), header, warning and message bit-identical to sdcflows 2.17.1’s.
Provenance of this example
- Data: OpenNeuro ds002603, sub-01, CC0-1.0
- Inputs: phase map 0 (sha256 aff5eb8991a293dd…); unwrapped (sha256 d2fc8fdbb58bc6ac…); fmap (sha256 028996d965224716…); mask (sha256 e45979f6a46d1728…); magnitude (sha256 f57cf6848227f2f2…); prelude_mask (sha256 e45979f6a46d1728…); fMRIPrep’s own rads (sha256 0fb2a30f7a193ab1…); fMRIPrep’s own fmap (sha256 028996d965224716…); fMRIPrep’s own extrapolated (sha256 f218b3aa7566473b…); fMRIPrep’s own coeff (sha256 74b19295496da1d5…)
- Runs: figures cache entry
sdcflows-fieldmap/estimator-ds002603, computed 2026-11-08T09:34:27+00:00 with larmorx61185255c67d; sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.5.4 (OpenBLAS 0.3.34), SciPy 1.18.1 (oracles/python-newest: larmorx’s reference); sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.3.5 (OpenBLAS 0.3.30), SciPy 1.15.3 (the shared .venv); every command, its environment, threads and exit status are in itsRUN_INFO.json
Every number above is in sdcflows-fieldmap.json, exported by python -m larmorx_validation evidence sdcflows-fieldmap.
ds002422: a phase difference at 1.5 T
The data panel’s 1.5 T subject has two phase-difference maps on different grids; the first is shown, both are in the table below.
Worked example
fMRIPrep's field map from ds002422-sub-02's phase difference, and its B-spline fit
What this shows: In reproduce the replica gives every value of sdcflows 2.17.1’s four outputs (the phase difference in radians, the field map in Hz, the fitted field and the fitting error), at 1 and 14 threads alike, and fMRIPrep’s own files of this estimator hold the same values. Its whole workflow, with PRELUDE’s clean room, gives fMRIPrep’s field map in every voxel. No correction by default changes this call, and sdcflows gives the same values with both releases of the libraries.
- Replica against sdcflows 2.17.1Bit-identical
fMRIPrep 25.2.6’s phase-difference estimator of ds002422-sub-02 (the first of two phase differences at 1.5 T (run-01); sdcflows’ wf_auto_00000), step by step on the inputs its nodes were given: the scanner’s phase map rescaled to radians (the phase difference PRELUDE unwraps), fMRIPrep’s own unwrapped phase turned into Hz (the field map), and that field map approximated by cubic B-splines inside the brain mask (bs_filter): the smooth fitted field, extrapolated beyond the mask, and the fitting error. sdcflows 2.17.1 and the replica compute every output; fMRIPrep’s own files and the replica’s whole workflow (with PRELUDE) are compared with them value by value.
- Data
- OpenNeuro ds002422, sub-02 (CC0-1.0): the field map’s phase and magnitude as fMRIPrep’s nodes were given them; shown inside sdcflows’ brain mask of the magnitude, dilated by 2 voxels, so no face shows
- Nodes
- fMRIPrep 25.2.6,
work/fmriprep_25_2_wf/sub_02_wf/fmap_preproc_wf/wf_auto_00000:phdiff_wf/phmap2rads,calc_phdiff,compfmapandbs_filter - Fit
- BSplineApprox as
bs_filtercalls it: spacing [[16.0, 16.0, 10.0]] mm, ridge alpha 0.0001, recentred by the median, extrapolated, zooms_min 1; Δ TE from the echo times 4.76 and 9.52 ms - Coefficients
- the 14 × 14 × 10 B-spline coefficients (1,960 values, 16 × 16 × 10 mm spacing): the replica’s equal sdcflows’ and fMRIPrep’s own
*_coeff000file, every one, at 1 and 14 threads, infixand inreproduce; 32,742 voxels inside the mask, 365 conjugate-gradient iterations - Programs
- sdcflows 2.17.1 in both kept environments (in process, its nipype interfaces); the replica’s
lx.sdcflowsat commit61185255c67d; numpy’s OpenBLAS on its Haswell kernels, one thread, as fMRIPrep’s nodes - Grid
- 64 × 64 × 24 voxels of 3 × 3 × 3.3 mm; shown: 54 × 62 × 24 around the brain
Data shown
- fMRI: resting state and arithmetic task (OpenNeuro ds002422, version 1.1.0, doi:10.18112/openneuro.ds002422.v1.1.0), CC0 1.0 public-domain dedication.




Bit-identical98,304 of 98,304 voxels equal
Bit-identical98,304 of 98,304 voxels equal
Bit-identical98,304 of 98,304 voxels equal
Axial slice 6 of 24; the crosshair where the field is strongest in the slice; choose the output (the phase difference, the field map, the fitted field, its error) above the images. The interactive viewer needs JavaScript; the metrics below are complete without it.
Every comparison, computed in float64 over every voxel of the outputs
| Comparison (A − B), verdict and reason | Output | max |Δ| | Values that differ | RMS of Δ | max |Δ| ÷ range | 1 − NCC |
|---|---|---|---|---|---|---|
| The original against itself: the yardstick | ||||||
| sdcflows: numpy 2.5.4 / SciPy 1.18.1 − numpy 2.3.5 / SciPy 1.15.3referenceFor reference, the originals’ own step between two releases of the libraries: with numpy 2.5.4 (OpenBLAS 0.3.34) and SciPy 1.18.1 sdcflows gives the same values as with numpy 2.3.5 (OpenBLAS 0.3.30) and SciPy 1.15.3, every one: sdcflows 2.15.1 to 2.17.1 and the libraries’ releases change nothing on these paths. the record | every output | identical: 0 of 98,304 values differ | ||||
| The replica against the original | ||||||
| replica − sdcflows 2.17.1Bit-identicalEvery value of the four outputs is sdcflows’: the phase in radians (numpy’s float64 rescaling rounded to float32), the field map in Hz, the ridge regression’s coefficients (scikit-learn’s sparse_cg, SciPy’s conjugate gradients with OpenBLAS’s float32 dot products, in their order) and the field they give inside and outside the mask, the fitting error. | every output | identical: 0 of 98,304 values differ | ||||
| The replica against fMRIPrep's output | ||||||
replica − fMRIPrep's outputBit-identicalfMRIPrep 25.2.6’s own files of this estimator (sdcflows 2.15.1 in its image) hold the same values: the phase difference PRELUDE was given, the field map, the extrapolated field (*_extra) the run used. | every output | identical: 0 of 98,304 values differ | ||||
replica, whole workflow with PRELUDE's clean room − fMRIPrep's outputBit-identicalThe replica’s whole phase-difference workflow, with PRELUDE’s clean room (lx.fsl.prelude, written from its specification), gives fMRIPrep’s field map in every voxel. | both outputs | identical: 0 of 98,304 values differ | ||||
| The replica against itself: thread counts, fix and reproduce | ||||||
| replica: 14 threads − 1 threadBit-identicalThe same bytes at 1 and 14 threads (at one thread the fit stores the collocation matrix, at more it evaluates the weights at every product: the same sums in the same order). | every output | identical: 0 of 98,304 values differ | ||||
replica: fix − reproduceBit-identicalNo correction by default applies to fMRIPrep’s call: fix and reproduce give the same values. | every output | identical: 0 of 98,304 values differ | ||||
Δ is A − B over all 98,304 voxels of each output file, not only those shown; fMRIPrep’s own files and the replica’s workflow are compared over their files (fMRIPrep keeps no fitting error, the workflow ends at the field map). The record’s threshold: in reproduce, every array, file (decompressed), header, warning and message bit-identical to sdcflows 2.17.1’s.
Provenance of this example
- Data: OpenNeuro ds002422, sub-02, CC0-1.0
- Inputs: phase map 0 (sha256 e0c3d483c72cc617…); unwrapped (sha256 a617f3841596502a…); fmap (sha256 f195d42f9f1243f0…); mask (sha256 2e6e4b01b18c1c8f…); magnitude (sha256 d3f31c76670abbd6…); prelude_mask (sha256 2e6e4b01b18c1c8f…); fMRIPrep’s own rads (sha256 ec076a87e64931d1…); fMRIPrep’s own fmap (sha256 f195d42f9f1243f0…); fMRIPrep’s own extrapolated (sha256 85e4c9aa5b2fd0fa…); fMRIPrep’s own coeff (sha256 bc24cb4ac7c4f435…)
- Runs: figures cache entry
sdcflows-fieldmap/estimator-ds002422-run01, computed 2026-11-08T09:34:37+00:00 with larmorx61185255c67d; sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.5.4 (OpenBLAS 0.3.34), SciPy 1.18.1 (oracles/python-newest: larmorx’s reference); sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.3.5 (OpenBLAS 0.3.30), SciPy 1.15.3 (the shared .venv); every command, its environment, threads and exit status are in itsRUN_INFO.json
Every number above is in sdcflows-fieldmap.json, exported by python -m larmorx_validation evidence sdcflows-fieldmap.
Every estimator
fMRIPrep’s seven phase-difference estimators, the replica against the original and fMRIPrep’s output: sdcflows 2.17.1
| Estimator | Phase (rad) | Field map | Coefficients | Fitted field | Error | fMRIPrep's files | Workflow | Threads, fix, releases | Verdict |
|---|---|---|---|---|---|---|---|---|---|
ds005454-sub-16 wf_gre16a GRE phase difference at 7 T (Siemens), 112 × 112 × 70 voxels of 2 mm | identical | identical | identical | identical | identical | identical | identical | identical | Bit-identical |
ds002603-sub-01 wf_auto_00000a Philips phase difference at 3 T (acq-Mm2), 128 × 128 × 128 voxels of 2 mm | identical | identical | identical | identical | identical | identical | identical | identical | Bit-identical |
ds002422-sub-02 wf_auto_00000the first of two phase differences at 1.5 T (run-01); 64 × 64 × 24 voxels | identical | identical | identical | identical | identical | identical | identical | identical | Bit-identical |
ds002422-sub-02 wf_auto_00001the second phase difference at 1.5 T (run-02), on another grid; 64 × 64 × 36 voxels | identical | identical | identical | identical | identical | identical | identical | identical | Bit-identical |
ds001600-sub-1 wf_auto_00000two phase images (acq-v1, phase1 and phase2): sdcflows subtracts them; 64 × 64 × 44 voxels | identical | identical | identical | identical | identical | identical | identical | identical | Bit-identical |
ds001600-sub-1 wf_auto_00001two phase images of a second protocol (acq-v2); 64 × 64 × 44 voxels | identical | identical | identical | identical | identical | identical | identical | identical | Bit-identical |
ds001600-sub-1 wf_auto_00002a phase difference (acq-v4); 64 × 64 × 44 voxels | identical | identical | identical | identical | identical | identical | identical | identical | Bit-identical |
Each phase-difference estimator of the four fMRIPrep runs that have one (ds001600 has three, ds002422 two), step by step on the inputs fMRIPrep’s nodes were given (the examples above show three): the replica (1 thread, reproduce) against sdcflows 2.17.1 (newest releases) output by output; against fMRIPrep 25.2.6’s own files (the phase difference, the field map, the extrapolated field and the coefficients); the replica’s whole workflow with PRELUDE’s clean room (lx.fsl.prelude) against fMRIPrep’s phase difference and field map; in one column, the replica at 14 threads and in fix, its default, against itself and sdcflows with the shared environment’s releases against the newest (the originals’ own step). Values counted as stored (NaN alike).
The coefficients
What fMRIPrep keeps of the fit is one coefficient per control point (4,352 on ds005454’s grid). The replica’s coefficients are sdcflows’ and fMRIPrep’s own file, every one: scikit-learn’s conjugate gradients (354 iterations here), each float32 sum taken in OpenBLAS’s order.
Worked example
The B-spline coefficients of ds005454-sub-16's field map
What this shows: In reproduce the replica gives every one of sdcflows 2.17.1’s 4,352 coefficients, at 1 and 14 threads alike, and fMRIPrep’s own coefficient file holds the same values. No correction by default changes this call.
- Replica against sdcflows BSplineApprox 2.17.1Bit-identical
What the fit computes: one coefficient per control point of a grid 16 mm apart in x and y and 10 mm in z, spread over the field map’s field of view; the field anywhere is the sum of the cubic B-splines of the nearest 4 × 4 × 4 control points, weighted by these coefficients. fMRIPrep keeps them (desc-coeff_fieldmap) and evaluates them on every grid it resamples the BOLD series onto.
- Data
- OpenNeuro ds005454, sub-16 (CC-BY-4.0): the coefficients of the field map above (no image of the head: a smooth field on a coarse grid)
- Grid
- 16 × 16 × 17 control points of 16 × 16 × 10 mm, every one shown
- Programs
- fMRIPrep 25.2.6’s own file; sdcflows 2.17.1 in both kept environments; the replica at commit
61185255c67d
Data shown
- fMRIPrep boot camp 7T training dataset (OpenNeuro ds005454, version 1.0.0, doi:10.18112/openneuro.ds005454.v1.0.0), Creative Commons Attribution 4.0 (CC BY 4.0). Attribution: Sleight EC, Esteban O, Grouiller F. fMRIPrep boot camp -- 7T training dataset. OpenNeuro ds005454, version 1.0.0. doi:10.18112/openneuro.ds005454.v1.0.0 The images shown are adapted from it: reoriented to RAS, cropped to the region shown, masked outside it, and shown as the outputs of the programs compared.



Bit-identical4,352 of 4,352 voxels equal
Bit-identical4,352 of 4,352 voxels equal
Axial slice 9 of 17; every coefficient of the control grid. The interactive viewer needs JavaScript; the metrics below are complete without it.
Every comparison, computed in float64 over every voxel of the outputs
| Comparison (A − B), verdict and reason | max |Δ| | Values that differ | RMS of Δ | max |Δ| ÷ range | 1 − NCC |
|---|---|---|---|---|---|
| The original against itself: the yardstick | |||||
| sdcflows BSplineApprox 2.17.1: numpy 2.5.4 / SciPy 1.18.1 − numpy 2.3.5 / SciPy 1.15.3referenceFor reference, the originals’ own step between two releases of the libraries: with numpy 2.5.4 (OpenBLAS 0.3.34) and SciPy 1.18.1 sdcflows gives the same values as with numpy 2.3.5 (OpenBLAS 0.3.30) and SciPy 1.15.3, every one: sdcflows 2.15.1 to 2.17.1 and the libraries’ releases change nothing on these paths. the record | identical: 0 of 4,352 values differ | ||||
| The replica against the original | |||||
| replica − sdcflows BSplineApprox 2.17.1Bit-identicalEvery coefficient is sdcflows’: scikit-learn’s ridge regression (sparse_cg, SciPy’s conjugate gradients) on the field map inside the mask, its float32 dot products as OpenBLAS’s Haswell kernel sums them. | identical: 0 of 4,352 values differ | ||||
| The replica against fMRIPrep's output | |||||
| replica − fMRIPrep's outputBit-identicalfMRIPrep 25.2.6’s own coefficient file holds the same values. | identical: 0 of 4,352 values differ | ||||
| The replica against itself: thread counts, fix and reproduce | |||||
| replica: 14 threads − 1 threadBit-identicalThe same bytes at 1 and 14 threads (at one thread the fit stores the collocation matrix, at more it evaluates the weights at every product: the same sums in the same order). | identical: 0 of 4,352 values differ | ||||
replica: fix − reproduceBit-identicalNo correction by default applies to fMRIPrep’s call: fix and reproduce give the same values. | identical: 0 of 4,352 values differ | ||||
Δ is A − B over all 4,352 coefficients. The record’s threshold: in reproduce, every array, file (decompressed), header, warning and message bit-identical to sdcflows 2.17.1’s.
Provenance of this example
- Data: OpenNeuro ds005454, sub-16, CC-BY-4.0
- Inputs: phase map 0 (sha256 ef84f4949b28f3fb…); unwrapped (sha256 4800254623c56c01…); fmap (sha256 aa27ea0e32694d98…); mask (sha256 d748a07583ecf543…); magnitude (sha256 da6b994811a1e00b…); prelude_mask (sha256 d748a07583ecf543…); fMRIPrep’s own rads (sha256 c41556eee49fa98d…); fMRIPrep’s own fmap (sha256 aa27ea0e32694d98…); fMRIPrep’s own extrapolated (sha256 9dd937b4332cc7ea…); fMRIPrep’s own coeff (sha256 cc0b161dd80d5ebf…)
- Runs: figures cache entry
sdcflows-fieldmap/estimator-ds005454, computed 2026-11-08T09:32:54+00:00 with larmorx61185255c67d; sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.5.4 (OpenBLAS 0.3.34), SciPy 1.18.1 (oracles/python-newest: larmorx’s reference); sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.3.5 (OpenBLAS 0.3.30), SciPy 1.15.3 (the shared .venv); every command, its environment, threads and exit status are in itsRUN_INFO.json
Every number above is in sdcflows-fieldmap.json, exported by python -m larmorx_validation evidence sdcflows-fieldmap.
The unwarping of a real series, and SDC-02
sdcflows’ ApplyCoeffsField ran on the first 10 volumes of ds005454’s resting-state series, with fMRIPrep’s coefficients and fMRIPrep’s registration of the BOLD reference to the field map. The replica’s unwarped series is sdcflows’, every value, at 1 and 14 threads.
The registration rotates the series’ grid against the coefficients’ grid, and there sdcflows’ weights are wrong. It multiplies, per axis, weights each taken from one index of the voxel, a product that is exact only for aligned grids (SDC-02). The replica’s default, fix, evaluates the B-splines at each voxel’s position and names SDC-02; in reproduce it gives sdcflows’ series. On this call the field changes by 3.65 Hz RMS inside the brain (31.3 Hz at most), and the series by 8.73 RMS over all its values, in the image’s units (its range is 2,417): compare fix − reproduce.
Worked example
The unwarping of a real BOLD series with fMRIPrep's field map
What this shows: In reproduce the replica gives every value of sdcflows 2.17.1’s 10 unwarped volumes, at 1 and 14 threads alike. In fix, its default, it corrects SDC-02: fMRIPrep’s registration rotates the series’ grid against the coefficients’ grid, where sdcflows’ weights are exact only for aligned grids. The field on the series’ grid changes by 3.65 Hz RMS inside the brain mask (31.3 Hz at most), and the series by 8.73 RMS over all its values (569.3 at most, in a range of 2,417).
- Replica against sdcflows ApplyCoeffsField 2.17.1Bit-identical
sdcflows’ ApplyCoeffsField (its own unwarping, the interface sdcflows’ workflows use; fMRIPrep 25.2.6 itself unwarps inside its one-shot resampler) on the first 10 volumes of OpenNeuro ds005454 sub-16’s resting-state series (7 T, multiband): fMRIPrep’s B-spline coefficients evaluated on the series’ grid through fMRIPrep’s registration of the BOLD reference to the field map, each voxel moved back along the phase-encoding axis by the field times the readout time, and its intensity corrected by the Jacobian. 4 of the 10 volumes are shown; the metrics cover every volume.
- Data
- OpenNeuro ds005454, sub-16, task rest (CC-BY-4.0); shown inside fMRIPrep’s BOLD brain mask, dilated by one voxel
- Inputs
- PE
j-, readout 0.0429303 s (the values of fMRIPrep’s ResampleSeries node); the coefficients of fMRIPrep’sbs_filter;fmap2data_xfmfMRIPrep’sfmapreg_wf/coregistertransform - Field
- the field on the series’ grid (
out_field): the replica’s equals sdcflows’ in every voxel - Programs
- sdcflows 2.17.1 (num_threads 8) in both kept environments; the replica’s
lx.sdcflows.apply_coeffs_fieldat commit61185255c67d - Volumes
- shown: file volumes 0, 3, 6, 9
- Grid
- 160 × 160 × 96 × 10 voxels of 1.4 × 1.4 × 1.4 mm; shown: 98 × 124 × 95 around the brain
Data shown
- fMRIPrep boot camp 7T training dataset (OpenNeuro ds005454, version 1.0.0, doi:10.18112/openneuro.ds005454.v1.0.0), Creative Commons Attribution 4.0 (CC BY 4.0). Attribution: Sleight EC, Esteban O, Grouiller F. fMRIPrep boot camp -- 7T training dataset. OpenNeuro ds005454, version 1.0.0. doi:10.18112/openneuro.ds005454.v1.0.0 The images shown are adapted from it: reoriented to RAS, cropped to the region shown, masked outside it, and shown as the outputs of the programs compared.




Bit-identical24,576,000 of 24,576,000 voxels equal
Bit-identical24,576,000 of 24,576,000 voxels equal

Axial slice 46 of 95, volume 1 of 4; file volume 0; compare the distorted series (before) with the unwarped one (after) with Swipe or Blink. The interactive viewer needs JavaScript; the metrics below are complete without it.
Every comparison, computed in float64 over every voxel of the outputs
| Comparison (A − B), verdict and reason | max |Δ| | Values that differ | RMS of Δ | max |Δ| ÷ range | 1 − NCC |
|---|---|---|---|---|---|
| The original against itself: the yardstick | |||||
| sdcflows ApplyCoeffsField 2.17.1: numpy 2.5.4 / SciPy 1.18.1 − numpy 2.3.5 / SciPy 1.15.3referenceFor reference, the originals’ own step between two releases of the libraries: with numpy 2.5.4 (OpenBLAS 0.3.34) and SciPy 1.18.1 sdcflows gives the same values as with numpy 2.3.5 (OpenBLAS 0.3.30) and SciPy 1.15.3, every one: sdcflows 2.15.1 to 2.17.1 and the libraries’ releases change nothing on these paths. the record | identical: 0 of 24,576,000 values differ | ||||
| The replica against the original | |||||
| replica − sdcflows ApplyCoeffsField 2.17.1Bit-identicalEvery value of the 10 unwarped volumes is sdcflows’: the field evaluated on the series’ grid through the registration’s inverse, the voxel shifts along the phase encoding, SciPy’s cubic B-spline interpolation and the Jacobian, written back into the series’ int16 type as nibabel scales it. | identical: 0 of 24,576,000 values differ | ||||
| The replica against itself: thread counts, fix and reproduce | |||||
| replica: 14 threads − 1 threadBit-identicalThe same bytes at 1 and 14 threads (at one thread the fit stores the collocation matrix, at more it evaluates the weights at every product: the same sums in the same order). | identical: 0 of 24,576,000 values differ | ||||
replica: fix − reproduceDeliberate correctionSDC-02, corrected by default with a notice (rule A): fMRIPrep’s registration of the BOLD reference to the field map rotates the series’ grid against the coefficients’ grid, where sdcflows multiplies per-axis weights each taken from one index of the voxel (a product exact only for aligned grids, with its warning “Image’s and B-Spline’s grids are not aligned”); the replica evaluates the B-spline at each voxel’s own position. The field on the series’ grid changes by 3.65 Hz RMS (largest 31.3 Hz) inside the brain mask; the unwarped series by 8.73 RMS over all its values (largest 569.3; the series’ range 2417). upstream_defects='reproduce' gives sdcflows’ series. SDC-02 | 569 | 22,092,940 of 24,576,000 (89.9 %) | 8.73 | 0.236 | 0.00151 |
Δ is A − B over all 24,576,000 values of the 160 × 160 × 96 × 10 series (every volume), in the image’s units (stored integers × scale factor). The record’s threshold: in reproduce, every array, file (decompressed), header, warning and message bit-identical to sdcflows 2.17.1’s.
Provenance of this example
- Data: OpenNeuro ds005454, sub-16, CC-BY-4.0
- Inputs: BOLD series (sha256 ce8957bdd40178f1…); fMRIPrep’s coefficients (sha256 cc0b161dd80d5ebf…); fMRIPrep’s registration (sha256 ac33fa91a0e3749e…)
- Runs: figures cache entry
sdcflows-fieldmap/apply-ds005454, computed 2026-11-08T09:35:49+00:00 with larmorx61185255c67d; sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.5.4 (OpenBLAS 0.3.34), SciPy 1.18.1 (oracles/python-newest: larmorx’s reference); sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.3.5 (OpenBLAS 0.3.30), SciPy 1.15.3 (the shared .venv); every command, its environment, threads and exit status are in itsRUN_INFO.json
Every number above is in sdcflows-fieldmap.json, exported by python -m larmorx_validation evidence sdcflows-fieldmap.
SDC-10: the field on an oblique BOLD reference
When the target of B0FieldTransform.fit is not aligned with the coefficients’ grid, sdcflows evaluates the field on a fine aligned grid around the target and interpolates it onto the target with cubic B-splines. It builds that grid around the target as given and samples it at the target’s own coordinates, so the registration to the field map (xfm_data2fmap) is ignored: the field is taken where the target lies before it is registered (SDC-10). fMRIPrep’s own reconstruction never takes this path (it refuses grids that are not aligned); sdcflows’ unwarping does.
On ds002603’s two oblique BOLD references, with fMRIPrep’s registration, sdcflows’ field departs from the known answer, the exact field, by 8.48 and 7.67 Hz RMS inside the brain (up to 87 Hz). The replica’s default, fix, builds and samples the grid where the transform puts the target and gives the exact field within 10⁻⁴ Hz (its float32 sums of the B-splines in another order). In reproduce it gives sdcflows’ field.
Worked example
SDC-10: the field on an oblique BOLD reference, sdcflows' and the corrected one
What this shows: In reproduce the replica gives sdcflows 2.17.1’s field, every value. That field departs from the known answer, the exact field, by 8.48 Hz RMS in the 54,383 voxels of the BOLD brain mask (82.9 Hz at most): it is the field where the target lies before its registration. In fix, its default, the replica corrects SDC-10 and gives the exact field within 9.2 × 10⁻⁵ Hz (5.2 × 10⁻⁶ Hz RMS), its float32 sums of the B-splines taken in another order.
- Replica against sdcflows B0FieldTransform.fit 2.17.1Bit-identical
sdcflows evaluates a field map on an EPI target with B0FieldTransform.fit (the first step of ApplyCoeffsField and of its unwarping workflow). When the target is not aligned with the coefficients’ grid it takes an approximation: a fine aligned grid around the target, then cubic B-splines onto the target. sdcflows builds that grid around the target as given and samples it there, ignoring the registration (xfm_data2fmap); the field is taken where the target lies before it is registered. fMRIPrep’s own reconstruction never takes this path (it refuses grids that are not aligned); sdcflows’ unwarping does. ds002603’s oblique BOLD reference with fMRIPrep’s registration to the field map, against the exact field.
- Data
- OpenNeuro ds002603, sub-01 (CC0-1.0): fMRIPrep’s coefficients, BOLD reference
sub-01_task-wm_acq-Mb4Mm3Tr550and registration; inside fMRIPrep’s BOLD brain mask, dilated by one voxel - Registration
- fMRIPrep’s
from-boldref_to-auto00000transform (inverted, as sdcflows takes it): a rotation of 1.06° and a shift of 5.29 mm - Defect
- SDC-10: the approximation ignores the transform (rule A)
- Programs
- sdcflows 2.17.1 in both kept environments; the replica at commit
61185255c67d, 14 threads; the exact field by validation/investigations/sdcflows-fieldmap/measure_sdc01_02.py’sexact_field - Grid
- 80 × 80 × 36 voxels of 3 × 3 × 3.3 mm; shown: 55 × 65 × 36 around the brain
Data shown
- MB-EPI-comparison (OpenNeuro ds002603, version 1.0.0, doi:10.18112/openneuro.ds002603.v1.0.0), CC0 1.0 public-domain dedication.







Axial slice 17 of 36; the crosshair where the correction changes the field most in the slice; the differences on one symmetric scale. The interactive viewer needs JavaScript; the metrics below are complete without it.
Every comparison, computed in float64 over every voxel of the outputs
| Comparison (A − B), verdict and reason | max |Δ| | Values that differ | RMS of Δ | max |Δ| ÷ range | 1 − NCC |
|---|---|---|---|---|---|
| The original against the known answer | |||||
| sdcflows B0FieldTransform.fit 2.17.1 − the exact fieldreferencesdcflows’ field departs from the exact one by 8.48 Hz RMS (median 2.82, largest 82.9 Hz) in the 54,383 voxels of the BOLD brain mask: it is the field where the target lies before the registration, not where the transform puts it. SDC-10 | 113 | 230,400 of 230,400 (100 %) | 7.43 | 0.232 | 0.0854 |
| The original against itself: the yardstick | |||||
| sdcflows B0FieldTransform.fit 2.17.1: numpy 2.5.4 / SciPy 1.18.1 − numpy 2.3.5 / SciPy 1.15.3referenceFor reference, the originals’ own step between two releases of the libraries: the same values with both releases. | identical: 0 of 230,400 values differ | ||||
| The replica against the original | |||||
replica, reproduce − sdcflows B0FieldTransform.fit 2.17.1Bit-identicalIn reproduce the replica gives sdcflows’ field, every value. SDC-10 | identical: 0 of 230,400 values differ | ||||
| The replica against the known answer | |||||
replica, fix − the exact fieldreferenceThe replica’s default, fix, gives the exact field: 5.2e-06 Hz RMS, largest 9.2e-05 Hz, in the brain mask (the float32 sums of the B-splines taken in another order). SDC-10 | 0.00108 | 217,256 of 230,400 (94.3 %) | 2.68e−5 | 2.21e−6 | 1.1e−12 |
| The replica against itself: fix and reproduce | |||||
replica: fix − reproduce (SDC-10)Deliberate correctionSDC-10, corrected by default with a notice (rule A): sdcflows’ approximation builds its fine aligned grid around the target as given and samples it at the target’s own coordinates, so xfm_data2fmap changes nothing but the choice of the path; the replica builds and samples it where the transform puts the target. fix names SDC-01 and SDC-10; upstream_defects='reproduce' gives sdcflows’ field. SDC-10 SDC-01 | 113 | 230,400 of 230,400 (100 %) | 7.43 | 0.23 | 0.0854 |
Δ is A − B over all 230,400 voxels of the BOLD reference’s grid; the RMS, median and largest differences in the reasons are those inside the brain mask (54,383 voxels). The record’s threshold: in reproduce, every array, file (decompressed), header, warning and message bit-identical to sdcflows 2.17.1’s.
Provenance of this example
- Data: OpenNeuro ds002603, sub-01, CC0-1.0
- Inputs: sub-01_task-wm_acq-Mb4Mm3Tr550: BOLD reference (sha256 66781e6ae283ccfe…); sub-01_task-wm_acq-Mb4Mm3Tr550: fMRIPrep’s registration (sha256 94155e5610dddcb3…); sub-01_task-wm_acq-Mb4Mm3Tr550: brain mask (sha256 262ad52581333627…); sub-01_task-wm_acq-SeqMm3Tr2000: BOLD reference (sha256 1125a630e5472d11…); sub-01_task-wm_acq-SeqMm3Tr2000: fMRIPrep’s registration (sha256 24d659e1611f82a0…); sub-01_task-wm_acq-SeqMm3Tr2000: brain mask (sha256 5b9b7aef78efcf76…)
- Runs: figures cache entry
sdcflows-fieldmap/sdc10-ds002603, computed 2026-11-08T09:35:56+00:00 with larmorx61185255c67d; sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.5.4 (OpenBLAS 0.3.34), SciPy 1.18.1 (oracles/python-newest: larmorx’s reference); sdcflows 2.17.1, scikit-learn 1.9.1, nibabel 5.4.2, numpy 2.3.5 (OpenBLAS 0.3.30), SciPy 1.15.3 (the shared .venv); every command, its environment, threads and exit status are in itsRUN_INFO.json
Every number above is in sdcflows-fieldmap.json, exported by python -m larmorx_validation evidence sdcflows-fieldmap.
SDC-10 on ds002603’s two oblique BOLD references, the original and the replica against the known answer: sdcflows B0FieldTransform.fit 2.17.1 (Hz, inside the brain mask)
| sdcflows − exact, RMS | largest | replica, fix − exact, RMS | largest | replica, reproduce = sdcflows | Named | Verdict | |
|---|---|---|---|---|---|---|---|
ds002603 sub-01_task-wm_acq-Mb4Mm3Tr55054,383 voxels in the BOLD brain mask | 8.48 | 82.9 | 5.19e−6 | 9.16e−5 | identical | SDC-01, SDC-10 | Deliberate correction |
ds002603 sub-01_task-wm_acq-SeqMm3Tr200054,790 voxels in the BOLD brain mask | 7.67 | 87.2 | 5.4e−6 | 9.16e−5 | identical | SDC-01, SDC-10 | Deliberate correction |
B0FieldTransform.fit(approx=True) with fMRIPrep’s coefficients and its registration of each BOLD reference to the field map, against the exact field where the transform puts the target. SDC-10.
SDC-06: fMRIPrep’s own field maps fitted again
fMRIPrep writes its field maps as 4D images of one volume. Given one of them, sdcflows’ BSplineApprox stops with a ValueError (the header’s four voxel sizes broadcast against three). The replica’s default, fix, fits the map as the 3D image it is (SDC-06); in reproduce it raises sdcflows’ error.
SDC-06 on fMRIPrep’s own field maps (4D, one volume), the replica against the original: sdcflows BSplineApprox 2.17.1
| Field map | sdcflows 2.17.1 | replica, reproduce | replica, fix | Verdict |
|---|---|---|---|---|
ds005454-sub-16 sub-16_fmapid-gre16112 × 112 × 70 × 1 voxels | ValueError: operands could not be broadcast together with shapes (3,3) (4,) | the same error | the 3D map’s fit, every value (stored in the input’s 4D shape); names SDC-06 | Deliberate correction |
ds002603-sub-01 sub-01_acq-Mm2_fmapid-auto00000128 × 128 × 128 × 1 voxels | ValueError: operands could not be broadcast together with shapes (3,3) (4,) | the same error | the 3D map’s fit, every value (stored in the input’s 4D shape); names SDC-06 | Deliberate correction |
ds002422-sub-02 sub-02_run-01_fmapid-auto0000064 × 64 × 24 × 1 voxels | ValueError: operands could not be broadcast together with shapes (3,3) (4,) | the same error | the 3D map’s fit, every value (stored in the input’s 4D shape); names SDC-06 | Deliberate correction |
ds002422-sub-02 sub-02_run-02_fmapid-auto0000164 × 64 × 36 × 1 voxels | ValueError: operands could not be broadcast together with shapes (3,3) (4,) | the same error | the 3D map’s fit, every value (stored in the input’s 4D shape); names SDC-06 | Deliberate correction |
fMRIPrep writes its field maps (desc-preproc_fieldmap) as 4D images of one volume; fitting one again with sdcflows’ BSplineApprox (fMRIPrep’s parameters, the map’s own brain mask) fails in bspline_grid, which broadcasts the header’s four zooms against three. SDC-06 (rule A): the replica’s default, fix, takes the first three zooms and gives the fit of the same map stored as a 3D image (sdcflows’ own result there), the coefficients and the extrapolated field; reproduce raises sdcflows’ error. SDC-06.
Corrections by default
Every defect the replica found in sdcflows was decided by the register’s rules (A: corrected by default; B: refused with a clear error; C: kept and documented; D: measured first). upstream_defects="reproduce" (on the command line --upstream-defects reproduce from the next release, LARMORX_UPSTREAM_DEFECTS=reproduce in 0.1.0rc1) gives sdcflows’ behaviour, its errors and warnings included (findings, register). Eight are corrected by default and two refused with a reason. SDC-03, in CheckRegister’s branch for two magnitude images, needs FreeSurfer’s mri_robust_register and comes with FreeSurfer’s port. fMRIPrep’s calls meet none of them; sdcflows’ own interfaces and workflows do (SDC-02 and SDC-10 above, on real data).
Corrections by default, the replica: sdcflows 2.17.1’s defects (SDC-01 to SDC-11)
| Entry | What | Rule | On this page | The record's case |
|---|---|---|---|---|
| SDC-01 | weights beyond the control grid | D, measured: A | named in the SDC-10 example (sampling positions beyond the grid) | difftest/sdc01-weights-beyond-the-grid |
| SDC-02 | a rotated sampling grid | D, measured: A | the unwarping example (fMRIPrep’s registration rotates ds005454’s grid) | difftest/sdc02-rotated-sampling-grid |
| SDC-03 | CheckRegister’s signed translation test | A, not switched yet | – | – |
| SDC-04 | a constant phase map | B | – | difftest/sdc04-constant-phase-map |
| SDC-05 | an integer or float32 readout time | A | – | difftest/sdc05-integer-readout-time |
| SDC-06 | a 4D header of one volume | A | the SDC-06 table (fMRIPrep’s own field maps) | difftest/sdc06-4d-field-map-of-one-volume |
| SDC-07 | TOPUPCoeffReorient’s negation | D, measured: A | – | difftest/sdc07-bids-i-direction-kept |
| SDC-08 | a positive-axes series from a file | A | – | difftest/sdc08-positive-axes-series-from-a-file |
| SDC-09 | SubtractPhases without EchoTime | B | – | difftest/sdc09-missing-echo-time |
| SDC-10 | the approximation ignores the transform | A | the SDC-10 example and table (ds002603’s BOLD references) | difftest/sdc10-approximation-where-the-transform-puts-the-target |
| SDC-11 | a resize onto a single voxel | A | – | difftest/sdc11-resize-onto-a-single-voxel |
Each decided by rules A to D (A: corrected by default; B: a clear error; C: kept and documented; D: measured first), each with upstream_defects='reproduce' giving sdcflows’ behaviour; the findings: docs/findings/sdcflows-fieldmap.md. fMRIPrep’s calls meet none of them (its reconstruction refuses grids that are not aligned; it passes FSL’s letters to TOPUPCoeffReorient); sdcflows’ own interfaces and workflows do. SDC-03 waits for FreeSurfer’s mri_robust_register (CheckRegister’s two-magnitude branch).
The originals’ own step: two library releases
Each case also runs sdcflows with the releases the other comparisons share (numpy 2.3.5 with OpenBLAS 0.3.30, SciPy 1.15.3) and says what changed from them to the newest, line by line. sdcflows’ code on these paths is the same in 2.15.1 (fMRIPrep 25.2.6’s) and 2.17.1, scikit-learn’s solver is the same from 1.6.1 to 1.9.1, and SciPy’s routines on these paths do the same arithmetic from 1.15 to 1.18.
Of 381 compared lines 4 change, all for one reason: numpy’s OpenBLAS 0.3.31 and later bundle LAPACK 3.12.1, which moves the last bits of numpy’s SVD and eigenvalue routines. So nibabel writes other NIfTI quaternions for some oblique affines, and decides a rotation with two equal candidate axes otherwise. The replica follows LAPACK 3.12.1 and reproduces 3.12.0 for the comparison in the shared environment.
Changes, the original against itself: sdcflows 2.17.1 with numpy 2.3.5 / SciPy 1.15.3 and with numpy 2.5.4 / SciPy 1.18.1
| Case | Lines compared | Changed | Reason |
|---|---|---|---|
| every case | 381 | 4 | – |
difftest/nibabel-quaternion-apply | 1 | 1 | LAPACK-3.12.1 |
difftest/nibabel-quaternion-displacements | 1 | 1 | LAPACK-3.12.1 |
difftest/nibabel-quaternion-topup | 1 | 1 | LAPACK-3.12.1 |
difftest/sdc02-single-voxel-no-notice | 1 | 1 | LAPACK-3.12.1 |
The record’s step (python_versions): every line of every case whose script passed the originals’ outputs to stepdigest.oracle, compared between the shared releases (two runs) and the newest. The changes have one reason, LAPACK-3.12.1: numpy’s OpenBLAS 0.3.31 and later bundle LAPACK 3.12.1, which moves the last bits of numpy’s svd and eigh, so nibabel writes other NIfTI quaternions for some oblique affines and its io_orientation decides a tied rotation otherwise (the replica follows 3.12.1, the newest, and reproduces 3.12.0 for the shared environment’s comparison).
Speed
The benchmark (report) runs sdcflows’ interfaces in-process and the replica on fMRIPrep’s seven bs_filter calls and on ApplyCoeffsField with 60 volumes of ds005454. It times the whole interface (reading, the fit or the unwarping, writing every file) and checks every output byte for byte. sdcflows’ fit has no thread option: scikit-learn’s conjugate gradients run on one thread.
- The replica at 14 threads takes 6.5 to 7.8 times less time (ds002603’s 128³ field map with 9,072 coefficients: 4.0 s against 27.5 s).
- At one thread, in a fresh process, it takes 1.09 to 1.14 times less.
ApplyCoeffsFieldtakes 1.7 times less time at 1 and at 14 threads.
The machine was shared with other work.
Seconds per call (the median of three runs) on a log scale; the factor is sdcflows’ time divided by the replica’s, both on one thread.
- sdcflows 2.17.1, 1 thread
- sdcflows 2.17.1, 14 threads (ApplyCoeffsField)
- replica, 1 thread
- replica, 14 threads
- bs_filter: ds005454-sub-16/wf_gre16 (112 × 112 × 70)sdcflows 2.17.1, 1 thread 16.7 sreplica, 1 thread 15.3 sreplica, 14 threads 2.15 s1.1×
- bs_filter: ds002422-sub-02/wf_auto_00000 (64 × 64 × 24)sdcflows 2.17.1, 1 thread 1.96 sreplica, 1 thread 1.73 sreplica, 14 threads 0.302 s1.1×
- bs_filter: ds002422-sub-02/wf_auto_00001 (64 × 64 × 36)sdcflows 2.17.1, 1 thread 3.44 sreplica, 1 thread 3.17 sreplica, 14 threads 0.499 s1.1×
- bs_filter: ds001600-sub-1/wf_auto_00000 (64 × 64 × 44)sdcflows 2.17.1, 1 thread 2.83 sreplica, 1 thread 3.29 sreplica, 14 threads 0.386 s0.86×
- bs_filter: ds001600-sub-1/wf_auto_00001 (64 × 64 × 44)sdcflows 2.17.1, 1 thread 2.97 sreplica, 1 thread 3.43 sreplica, 14 threads 0.449 s0.87×
- bs_filter: ds001600-sub-1/wf_auto_00002 (64 × 64 × 44)sdcflows 2.17.1, 1 thread 2.88 sreplica, 1 thread 3.36 sreplica, 14 threads 0.398 s0.86×
- bs_filter: ds002603-sub-01/wf_auto_00000 (128 × 128 × 128)sdcflows 2.17.1, 1 thread 27.5 sreplica, 1 thread 24.9 sreplica, 14 threads 4.04 s1.1×
- ApplyCoeffsField: ds005454-sub-16, 60 volumes (160 × 160 × 96 × 60)sdcflows 2.17.1, 1 thread 31.8 ssdcflows 2.17.1, 14 threads (ApplyCoeffsField) 11.3 sreplica, 1 thread 18.7 sreplica, 14 threads 6.56 s1.7×
From the benchmark report docs/benchmarks/sdcflows-fieldmap.json (commit 2ed5b887, 32 logical CPUs, the newest environment, OPENBLAS_NUM_THREADS=1 as fMRIPrep’s nodes; every output byte-identical). BSplineApprox has no thread option: sdcflows’ fit runs on one thread; the replica’s at one thread stores the collocation matrix, at 14 evaluates the weights at every product (the same bits). ds001600’s three one-thread fits ran after the benchmark’s first calls in the same process and took longer than in a fresh process (the report’s footnote 1: the stored matrix’s speed depends on what the process ran before, an open follow-up).
Memory
The memory rule allows LARMORX at most 10 % above the original’s peak plus 8 MiB for the same call; here the replica needs 22 to 32 % of sdcflows’ peak.
Peak memory, the replica against the original: sdcflows 2.17.1 (MiB, the memory rule’s calls, one thread)
| Call | sdcflows | replica, reproduce | replica, fix | replica ÷ sdcflows |
|---|---|---|---|---|
| BSplineApprox, ds002422’s first field map (64 × 64 × 24) | 367 | 82 | 81 | 0.223 |
| BSplineApprox, ds005454’s field map (112 × 112 × 70) | 1,474 | 468 | 468 | 0.317 |
| ApplyCoeffsField, 20 volumes of ds005454’s BOLD (160 × 160 × 96) | 3,741 | 828 | 829 | 0.221 |
Each call in a process of its own (validation/investigations/sdcflows-fieldmap/memory_call.py, the calls of tests/parity/test_memory_peak.py), its peak resident memory from /usr/bin/time -v, in the newest environment at one thread. The rule: at most 10 % above the original’s peak plus 8 MiB. sdcflows holds the collocation matrix at least three times (its matrix, scikit-learn’s copy, the adjoint’s transpose); the replica stores it once at one thread (and evaluates the weights at every product with more threads), and unwarps the series volume by volume.
Random testing
Random testing runs random valid inputs and option combinations through sdcflows and the replica and compares every output (how random testing works). A difference is shrunk to the smallest input and fewest options that still show it, then fixed and kept as a permanent case, registered as a defect of sdcflows, or reported. The replica’s random-testing run of 2026-11-08 lasted half an hour:
Random testing, the replica against the original: sdcflows 2.17.1’s field-map estimation (the run of 2026-11-08)
| Cases | |
|---|---|
| Random cases, each compared with sdcflows 2.17.1 | 335,471 |
| bit-identical (every output, the messages, the default’s notices) | 335,456 |
| differing (triaged below: fixed in the replica, or SDC-11 registered) | 14 |
| a notice without a visible change (SCI-02; triaged below) | 1 |
| calls: bspline_approx, fit, apply, displacements, topup, phase | 96,415 / 63,582 / 79,884 / 31,673 / 31,936 / 31,981 |
| fits: one, two control grids | 83,573 / 12,842 |
| targets: own grid, aligned, rotated | 31,711 / 63,697 / 48,058 |
| transforms: none, identity, rigid | 71,711 / 21,675 / 50,080 |
| recentring: median, mean, mode, none | 54,882 / 13,671 / 13,826 / 14,036 |
| 4D field maps of one volume (SDC-06) | 14,263 |
| distinct options and settings drawn | 1,499 |
| length (minutes; 12 jobs at one thread each) | 30.1 |
The replica’s random-testing run (seed sdc-trial, larmorx d47952d1c894): random field maps, masks, grids and orientations (oblique, permuted, qform-only headers, NIfTI-2), float32, float64 and scaled int16 images; BSplineApprox’s options, B0FieldTransform’s fit and apply on own, aligned and rotated targets with and without transforms, ApplyCoeffsField’s options, the displacement fields, TOPUPCoeffReorient with FSL and BIDS letters, the phase steps; sdcflows in-process, the replica in reproduce compared output by output, its default, fix, checked by the rule of the corrections by default. Every case in a memory box of 3 GiB (peaks below 0.49 GiB).
The replica’s differences from the original in the run of 2026-11-08, triaged
| Status | What it was | Register |
|---|---|---|
| registervalidation/difftest/cases/sdcflows-fieldmap/sdc11-resize-onto-a-single-voxel.json | 10 of the 14 cases (smallest sdc-trial 59267: a 4 x 4 x 4 field map at 1 mm, zooms_min 4): BSplineApprox’s resize gives a grid of one voxel, and nitransforms’ Affine.apply fails there with a bare AssertionError (assert targets.ndim == 2 after numpy’s squeeze of the one target point); the replica raised an AssertionError with its own message. Registered as SDC-11 (rule A): the voxel resampled and the fit made by default,… | SDC-11 |
| fixedvalidation/difftest/cases/sdcflows-fieldmap/error-cal-max-memory-order.json | 2 of the 14 cases (sdc-trial 236468, 325222): the error map’s cal_max is numpy’s max of sdcflows’ error array, which is Fortran-ordered (nibabel’s arrays); numpy’s SIMD max returns a new NaN or a zero’s sign by memory order, and the replica’s array was C-ordered: the replica keeps the error in Fortran order | – |
| fixedvalidation/difftest/cases/sdcflows-fieldmap/mode-zero-sign.json | 2 of the 14 cases (sdc-trial 200937, 320850): recentring by the mode where the mode is 0 and the zeros have both signs (one -0 among 1,609 and 2,934 +0): scipy’s mode is the first zero of np.unique’s sort (+0 here; numpy’s unstable SIMD quicksort leaves which zero is first undefined), the replica took -0 (the total order’s first); the replica now takes the zeros’ more frequent sign (+0 on a tie); only zero signs of the erro… | – |
| harnessvalidation/difftest/cases/sdcflows-fieldmap/sci02-padding-condition-notice.json | 1 case (sdc-trial 294008: apply of a uint8 series, order 2, grid-constant, cval -5): lx.ndimage names SCI-02 when the spline prefilter pads an integer input with a cval its type cannot hold, whether or not a sample point reaches the padding (a condition whose effect the comparison may not see); the suite’s fix pass of apply accepts SCI-02 without a change (silent_ok), as it does no other defect | – |
validation/difftest/triage.toml (block sdcflows-fieldmap, 2026-11-08); each difference has a permanent case (validation/difftest/cases/sdcflows-fieldmap/), run by the record. Two short random-testing runs before this run (the same day) found the replica’s mistakes in nibabel’s header arithmetic, SciPy’s float64 stacks and numpy’s NaN, all fixed, each with a permanent case.
Every case
Each case of the record, with what it tests, its command line, its verdict and the reason. Search, filter by category or verdict (or select a segment of the chart above), sort by a column; #case=<name> links to one.
37 cases
| Case | Category | What it tests | Verdict | Checks |
|---|---|---|---|---|
weights | comparison scripts | the control grid and the B-spline weights (SDC-01, SDC-02, SDC-06 both ways)command linepython -P validation/investigations/sdcflows-fieldmap/check_weights.py | Bit-identical Every one of its 45 checks: the outputs bit-identical to sdcflows’ (or fMRIPrep’s own files), the messages too, and the originals’ step per line. | 45/45 |
coeffs | comparison scripts | TOPUPCoeffReorient (SDC-07), TransformCoefficients, reorient_pedir; fMRIPrep's fix_coeffcommand linepython -P validation/investigations/sdcflows-fieldmap/check_coeffs.py | Bit-identical Every one of its 103 checks: the outputs bit-identical to sdcflows’ (or fMRIPrep’s own files), the messages too, and the originals’ step per line. | 103/103 |
phase | comparison scripts | the phase-difference preparation; fMRIPrep's phmap2rads, calc_phdiff, compfmap filescommand linepython -P validation/investigations/sdcflows-fieldmap/check_phase.py | Bit-identical Every one of its 106 checks: the outputs bit-identical to sdcflows’ (or fMRIPrep’s own files), the messages too, and the originals’ step per line. | 106/106 |
nibabel-writer | comparison scripts | lx.io.save_nibabel against nibabelcommand linepython -P validation/investigations/sdcflows-fieldmap/check_nibabel_write.py | Bit-identical Every one of its 13 checks: the outputs bit-identical to sdcflows’ (or fMRIPrep’s own files), the messages too, and the originals’ step per line. | 13/13 |
b0field | comparison scripts | deoblique_and_zooms, B0FieldTransform.fit reproduced and corrected (SDC-01, -02, -10)command linepython -P validation/investigations/sdcflows-fieldmap/check_b0field.py | Bit-identical Every one of its 69 checks: the outputs bit-identical to sdcflows’ (or fMRIPrep’s own files), the messages too, and the originals’ step per line. | 69/69 |
apply | comparison scripts | B0FieldTransform.apply, ApplyCoeffsField, the displacement fields (SDC-05, SDC-08)command linepython -P validation/investigations/sdcflows-fieldmap/check_apply.py | Bit-identical Every one of its 153 checks: the outputs bit-identical to sdcflows’ (or fMRIPrep’s own files), the messages too, and the originals’ step per line. | 153/153 |
approx-core | comparison scripts | BSplineApprox's core: 16 synthetic cases and fMRIPrep's seven callscommand linepython -P validation/investigations/sdcflows-fieldmap/check_approx.py | Bit-identical Every one of its 47 checks: the outputs bit-identical to sdcflows’ (or fMRIPrep’s own files), the messages too, and the originals’ step per line. | 47/47 |
bspline-approx | comparison scripts | bspline_approx complete and fMRIPrep's seven bs_filter calls with their filescommand linepython -P validation/investigations/sdcflows-fieldmap/check_bspline_approx.py | Bit-identical Every one of its 111 checks: the outputs bit-identical to sdcflows’ (or fMRIPrep’s own files), the messages too, and the originals’ step per line. | 111/111 |
ridge | comparison scripts | numpy's dot, SciPy's cg, scikit-learn's Ridge; fMRIPrep's seven fits and coefficientscommand linepython -P validation/investigations/sdcflows-fieldmap/check_ridge.py | Bit-identical Every one of its 89 checks: the outputs bit-identical to sdcflows’ (or fMRIPrep’s own files), the messages too, and the originals’ step per line. | 89/89 |
difftest/error-cal-max-memory-order | random testing | BSplineApprox after a resize with an infinity outside the mask: the error map's cal_max is numpy's max of sdcflows' Fortran-ordered array (a new NaN from the SIMD reduction, not the input's), so the replica keeps the error in Fortran order (the random-testing run of 2026-11-08) | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/error-cal-max-zero-sign | random testing | BSplineApprox of an int16 field map: the error map's cal_max is -0.0 where numpy's max over sdcflows' Fortran-ordered array meets a -0 first (the random-testing run of 2026-11-08) | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/fit-field-file-as-nibabel-writes | random testing | B0FieldTransform.fit's field written as nibabel writes it (the header's float32), also when the field is held as float64 | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/float64-field-without-weights | random testing | B0FieldTransform.fit on a target no knot reaches: scipy's kron of an empty axis is a float64 matrix, so sdcflows' field is float64 zeros | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/infinity-message-dtype | random testing | BSplineApprox of an unscaled little-endian float32 file holding an infinity: scikit-learn's message names dtype('<f4'), the raw array nibabel returns | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/io-orientation-tie-apply | random testing | B0FieldTransform.apply of a series whose rotation has equal axis candidates: the axis nibabel picks decides whether the series is reoriented, and so which error sdcflows raises | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/io-orientation-tie-topup | random testing | TOPUPCoeffReorient on a reference whose rotation has two equal axis candidates: nibabel's io_orientation through numpy's SVD picks the axis | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/mode-zero-sign | random testing | BSplineApprox recentred by the mode where the mode is 0 and the zeros have both signs (one -0 among 1,609 +0): scipy's mode is the first zero of np.unique's sort, +0 here; the replica takes the zeros' more frequent sign (numpy's unstable sort leaves the first one undefined), only zero signs of the error map depend on it (the random-testing run of 2026-11-08) | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/nan-sign-of-an-empty-mask | random testing | BSplineApprox with an empty mask after a resize: numpy's median of no values is x86's default NaN (sign bit set), so the error map is that NaN | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/nibabel-qform-only-coefficients | random testing | BSplineApprox of a field map with a qform only (sform code 0): its affine as nibabel reads it (get_qform in x87 extended precision, lx.io.load_nibabel), so the coefficients' sform rows and zero signs match | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/nibabel-qform-only-fit | random testing | B0FieldTransform.fit on a target with a qform only: nibabel's qform affine (extended precision), the field's affine bit for bit | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/nibabel-quaternion-apply | random testing | B0FieldTransform.apply on a rotated series: the corrected series' header carries nibabel's quaternion (numpy's linear algebra), not the replica's own | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/nibabel-quaternion-coefficients | random testing | BSplineApprox's coefficient grid of a rotated field map: nibabel's quaternion and zero signs in the coefficients' file | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/nibabel-quaternion-displacements | random testing | fmap_to_disp and disp_to_fmap of an oblique scaled int16 field map: nibabel's quaternions in both outputs | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 2/2 |
difftest/nibabel-quaternion-topup | random testing | TOPUPCoeffReorient's coefficients on a rotated reference: the qform quaternion nibabel writes (numpy's SVD and eigh through LAPACK and OpenBLAS's Haswell kernels; the replica's own Shepperd formula, used at first, gave other last bits and zero signs) | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/sci02-padding-condition-notice | random testing | B0FieldTransform.apply of a uint8 series with a negative cval, order 2 and grid-constant: lx.ndimage names SCI-02 when the prefilter pads with a cval the type cannot hold, whether or not a sample reaches the padding; the suite's fix pass of apply accepts that notice without a change (the random-testing run of 2026-11-08) | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/sdc01-weights-beyond-the-grid | random testing | B0FieldTransform.apply on a target reaching beyond the control grid: the replica gives the cubic B-spline's weights there (sdcflows continues the end polynomial of SciPy's extrapolation; reproduce gives it), SDC-01 named | Deliberate correction SDC-01, corrected by default (rule A): in | 3/3 |
difftest/sdc02-rotated-sampling-grid | random testing | B0FieldTransform.fit on a target rotated relative to the coefficients: the replica evaluates the B-spline at every voxel's own position (sdcflows multiplies per-axis weights taken from one index each; reproduce gives it), SDC-02 named | Deliberate correction SDC-02, corrected by default (rule A): in | 3/3 |
difftest/sdc02-single-voxel-no-notice | random testing | B0FieldTransform.apply of a single-voxel series on rotated coefficients: the separable product is the exact one there, so SDC-02 is not named | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/sdc04-constant-phase-map | random testing | PhaseMap2rads of a constant phase map: the replica raises a clear ValueError (sdcflows rescales 0/0 to NaN everywhere; reproduce gives it), SDC-04 named | Bit-identical Bit-identical to sdcflows in | 3/3 |
difftest/sdc05-integer-readout-time | random testing | B0FieldTransform.apply with an integer readout time: the replica unwarps (sdcflows raises a TypeError from zip over an int; reproduce gives it), SDC-05 named | Bit-identical Bit-identical to sdcflows in | 3/3 |
difftest/sdc06-4d-field-map-of-one-volume | random testing | BSplineApprox of a 4D field map of one volume with a 3D brain mask: the replica fits it with its first three zooms (sdcflows fails with numpy's broadcasting ValueError; reproduce gives it), SDC-06 named | Bit-identical Bit-identical to sdcflows in | 3/3 |
difftest/sdc07-bids-i-direction-kept | random testing | TOPUPCoeffReorient with a BIDS 'i' phase encoding: the replica keeps TOPUP's sign (sdcflows negates the field; reproduce gives it), SDC-07 named | Deliberate correction SDC-07, corrected by default (rule A): in | 3/3 |
difftest/sdc07-not-named-for-a-wrong-shape | random testing | TOPUPCoeffReorient with a BIDS 'i' direction and coefficients whose shape is not TOPUP's: both modes raise sdcflows' ValueError and SDC-07 is not named | Bit-identical Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case). | 3/3 |
difftest/sdc08-positive-axes-series-from-a-file | random testing | B0FieldTransform.apply of a 4D series read from a file with positive axes: the replica unwarps (sdcflows hands nibabel's ArrayProxy to rollaxis: AttributeError; reproduce gives it), SDC-08 named | Bit-identical Bit-identical to sdcflows in | 3/3 |
difftest/sdc09-missing-echo-time | random testing | SubtractPhases without EchoTime: the replica raises a clear ValueError (sdcflows a TypeError of comparing None; reproduce gives it), SDC-09 named | Bit-identical Bit-identical to sdcflows in | 5/5 |
difftest/sdc10-approximation-where-the-transform-puts-the-target | random testing | B0FieldTransform.fit with approx and a rigid xfm_data2fmap: the replica builds and samples the approximation's grid where the transform puts the target (sdcflows uses the target's own coordinates), SDC-10 named (with SDC-01 beyond the grid) | Deliberate correction SDC-10, corrected by default (rule A): in | 3/3 |
difftest/sdc11-resize-onto-a-single-voxel | random testing | BSplineApprox of a field map whose whole extent is below zooms_min: the resize gives a grid of one voxel, which the replica resamples and fits (sdcflows fails with nitransforms' bare AssertionError; reproduce gives it), SDC-11 named (the random-testing run of 2026-11-08) | Bit-identical Bit-identical to sdcflows in | 3/3 |
Known limits
- This page covers the field-map model and the phase-difference preparation. PEPOLAR’s and SyN’s steps, sdcflows’ masks, niworkflows’ helpers, fMRIPrep’s own field-map steps and sdcflows’ command line are on their own page.
CheckRegister’s branch for two magnitude images waits for FreeSurfer’smri_robust_register(SDC-03).- At one thread the stored collocation matrix’s speed depends on what the process ran before. In the benchmark, ds001600’s one-thread fits took 0.86 times sdcflows’ time after its first calls in the same process, and 1.1 times less in a fresh one (the report, footnote 1). To be measured before larmorprepx runs fits in a long-lived process.
- The record’s standard comparison holds fMRIPrep’s calls on its runs; the full comparisons and long random testing run in the final validation phase.
- The other five platforms are held to LARMORX’s own Linux output by the cross-platform checks.
History
- 2026-11-08: the replica, translated from sdcflows 2.17.1 with scikit-learn’s, SciPy’s, numpy’s and nibabel’s arithmetic; sdcflows’ defects SDC-01 to SDC-11 found, each corrected by default, refused with a clear error or waiting for FreeSurfer’s port; its record and its random-testing run (the roadmap).
- 2026-11-10: PEPOLAR, direct and fieldmap-less estimation, sdcflows’ masks and BIDS app, on their own page.
Data credits
The data this page shows or names: each dataset with its version, DOI and licence, from LARMORX's test-data catalog. Public-domain dedications (CC0, PDDL) ask nothing; the datasets are cited all the same.
- Example fieldmaps (OpenNeuro ds001600, version 1.0.0), Creative Commons Attribution-ShareAlike (CC BY-SA; the dataset gives no version). Attribution: Cieslak M., Elliott M., Satterthwaite T. Example Fieldmaps. OpenNeuro ds001600, version 1.0.0 (Siemens Prisma, University of Pennsylvania). The images shown are adapted from it: reoriented to RAS, cropped to the region shown, masked outside it, and shown as the outputs of the programs compared. Share-alike: the images adapted from this dataset are shared under the same licence, CC BY-SA.
- fMRI: resting state and arithmetic task (OpenNeuro ds002422, version 1.1.0, doi:10.18112/openneuro.ds002422.v1.1.0), CC0 1.0 public-domain dedication.
- MB-EPI-comparison (OpenNeuro ds002603, version 1.0.0, doi:10.18112/openneuro.ds002603.v1.0.0), CC0 1.0 public-domain dedication.
- fMRIPrep boot camp 7T training dataset (OpenNeuro ds005454, version 1.0.0, doi:10.18112/openneuro.ds005454.v1.0.0), Creative Commons Attribution 4.0 (CC BY 4.0). Attribution: Sleight EC, Esteban O, Grouiller F. fMRIPrep boot camp -- 7T training dataset. OpenNeuro ds005454, version 1.0.0. doi:10.18112/openneuro.ds005454.v1.0.0 The images shown are adapted from it: reoriented to RAS, cropped to the region shown, masked outside it, and shown as the outputs of the programs compared.