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 larmorx Apache-2.0: crate larmorx-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
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.

python
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_cg calls 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.

Agreement, replica against the original: sdcflows 2.17.1’s field-map estimation (standard comparison, 37 cases of the record), by category and verdict
comparison scripts9
random testing28

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 fix and in reproduce;
  • 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.

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, compfmap and bs_filter
Fit
BSplineApprox as bs_filter calls 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 *_coeff000 file, every one, at 1 and 14 threads, in fix and in reproduce; 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.sdcflows at commit 61185255c67d; 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

Inputds005454-sub-16: phase mapthe scanner's phase difference as BIDS stores it (PhaseMap2rads' input)
Inputds005454-sub-16: unwrapped phase (rad)fMRIPrep's own PRELUDE output (FSL in its image), Phasediff2Fieldmap's input
Originalsdcflows 2.17.1numpy 2.5.4, SciPy 1.18.1, scikit-learn 1.9.1: LARMORX's reference
Replicareplicalarmorx, Apache-2.0 · 1 thread, reproduce · against sdcflows 2.17.1

Bit-identical878,080 of 878,080 voxels equal

the replica against the originalreplica − sdcflows 2.17.1

Bit-identical878,080 of 878,080 voxels equal

the replica against itself: 1 and 14 threadsreplica: 14 threads − 1 thread

Bit-identical878,080 of 878,080 voxels equal

the replica against itself: fix and reproducereplica: fix − reproduce

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 reasonOutputmax |Δ|Values that differRMS of Δmax |Δ| ÷ range1 − 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 recordevery outputidentical: 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 outputidentical: 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 outputidentical: 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 outputsidentical: 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 outputidentical: 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 outputidentical: 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 larmorx 61185255c67d; 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 its RUN_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.

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, compfmap and bs_filter
Fit
BSplineApprox as bs_filter calls 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 *_coeff000 file, every one, at 1 and 14 threads, in fix and in reproduce; 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.sdcflows at commit 61185255c67d; 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
Inputds002603-sub-01: phase mapthe scanner's phase difference as BIDS stores it (PhaseMap2rads' input)
Inputds002603-sub-01: unwrapped phase (rad)fMRIPrep's own PRELUDE output (FSL in its image), Phasediff2Fieldmap's input
Originalsdcflows 2.17.1numpy 2.5.4, SciPy 1.18.1, scikit-learn 1.9.1: LARMORX's reference
Replicareplicalarmorx, Apache-2.0 · 1 thread, reproduce · against sdcflows 2.17.1

Bit-identical2,097,152 of 2,097,152 voxels equal

the replica against the originalreplica − sdcflows 2.17.1

Bit-identical2,097,152 of 2,097,152 voxels equal

the replica against itself: 1 and 14 threadsreplica: 14 threads − 1 thread

Bit-identical2,097,152 of 2,097,152 voxels equal

the replica against itself: fix and reproducereplica: fix − reproduce

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 reasonOutputmax |Δ|Values that differRMS of Δmax |Δ| ÷ range1 − 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 recordevery outputidentical: 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 outputidentical: 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 outputidentical: 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 outputsidentical: 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 outputidentical: 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 outputidentical: 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 larmorx 61185255c67d; 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 its RUN_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.

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, compfmap and bs_filter
Fit
BSplineApprox as bs_filter calls 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 *_coeff000 file, every one, at 1 and 14 threads, in fix and in reproduce; 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.sdcflows at commit 61185255c67d; 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
Inputds002422-sub-02: phase mapthe scanner's phase difference as BIDS stores it (PhaseMap2rads' input)
Inputds002422-sub-02: unwrapped phase (rad)fMRIPrep's own PRELUDE output (FSL in its image), Phasediff2Fieldmap's input
Originalsdcflows 2.17.1numpy 2.5.4, SciPy 1.18.1, scikit-learn 1.9.1: LARMORX's reference
Replicareplicalarmorx, Apache-2.0 · 1 thread, reproduce · against sdcflows 2.17.1

Bit-identical98,304 of 98,304 voxels equal

the replica against the originalreplica − sdcflows 2.17.1

Bit-identical98,304 of 98,304 voxels equal

the replica against itself: 1 and 14 threadsreplica: 14 threads − 1 thread

Bit-identical98,304 of 98,304 voxels equal

the replica against itself: fix and reproducereplica: fix − reproduce

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 reasonOutputmax |Δ|Values that differRMS of Δmax |Δ| ÷ range1 − 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 recordevery outputidentical: 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 outputidentical: 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 outputidentical: 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 outputsidentical: 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 outputidentical: 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 outputidentical: 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 larmorx 61185255c67d; 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 its RUN_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

EstimatorPhase (rad)Field mapCoefficientsFitted fieldErrorfMRIPrep's filesWorkflowThreads, fix, releasesVerdict
ds005454-sub-16 wf_gre16a GRE phase difference at 7 T (Siemens), 112 × 112 × 70 voxels of 2 mmidenticalidenticalidenticalidenticalidenticalidenticalidenticalidenticalBit-identical
ds002603-sub-01 wf_auto_00000a Philips phase difference at 3 T (acq-Mm2), 128 × 128 × 128 voxels of 2 mmidenticalidenticalidenticalidenticalidenticalidenticalidenticalidenticalBit-identical
ds002422-sub-02 wf_auto_00000the first of two phase differences at 1.5 T (run-01); 64 × 64 × 24 voxelsidenticalidenticalidenticalidenticalidenticalidenticalidenticalidenticalBit-identical
ds002422-sub-02 wf_auto_00001the second phase difference at 1.5 T (run-02), on another grid; 64 × 64 × 36 voxelsidenticalidenticalidenticalidenticalidenticalidenticalidenticalidenticalBit-identical
ds001600-sub-1 wf_auto_00000two phase images (acq-v1, phase1 and phase2): sdcflows subtracts them; 64 × 64 × 44 voxelsidenticalidenticalidenticalidenticalidenticalidenticalidenticalidenticalBit-identical
ds001600-sub-1 wf_auto_00001two phase images of a second protocol (acq-v2); 64 × 64 × 44 voxelsidenticalidenticalidenticalidenticalidenticalidenticalidenticalidenticalBit-identical
ds001600-sub-1 wf_auto_00002a phase difference (acq-v4); 64 × 64 × 44 voxelsidenticalidenticalidenticalidenticalidenticalidenticalidenticalidenticalBit-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.

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

Originalsdcflows BSplineApprox 2.17.1numpy 2.5.4, SciPy 1.18.1, scikit-learn 1.9.1: LARMORX's reference
fMRIPrep's outputfMRIPrep's outputfMRIPrep 25.2.6's own coefficients: bs_filter's *_coeff000 file (sdcflows 2.15.1 in its image)
Replicareplicalarmorx, Apache-2.0 · 1 thread, reproduce · against sdcflows BSplineApprox 2.17.1

Bit-identical4,352 of 4,352 voxels equal

the replica against the originalreplica − sdcflows BSplineApprox 2.17.1

Bit-identical4,352 of 4,352 voxels equal

the replica against fMRIPrep's outputreplica − fMRIPrep's output

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 reasonmax |Δ|Values that differRMS of Δmax |Δ| ÷ range1 − 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 recordidentical: 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 larmorx 61185255c67d; 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 its RUN_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).

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’s bs_filter; fmap2data_xfm fMRIPrep’s fmapreg_wf/coregister transform
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_field at commit 61185255c67d
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

Inputds005454 sub-16 BOLD, task restas BIDS stores it (the first 10 volumes), distorted along the phase encoding
Originalsdcflows ApplyCoeffsField 2.17.1numpy 2.5.4, SciPy 1.18.1: LARMORX's reference
Replicareplicalarmorx, Apache-2.0 · 1 thread, reproduce · against sdcflows ApplyCoeffsField 2.17.1
Replicareplicalarmorx, Apache-2.0 · 14 threads, fix (the default)

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

the original against itself: two releases of numpy and SciPysdcflows ApplyCoeffsField 2.17.1: numpy 2.5.4 / SciPy 1.18.1 − numpy 2.3.5 / SciPy 1.15.3

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

the replica against the originalreplica − sdcflows ApplyCoeffsField 2.17.1
the replica against itself: fix and reproducereplica: fix − reproducescale ±556

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 reasonmax |Δ|Values that differRMS of Δmax |Δ| ÷ range1 − 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 recordidentical: 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-0256922,092,940 of 24,576,000 (89.9 %)8.730.2360.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 larmorx 61185255c67d; 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 its RUN_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-Mb4Mm3Tr550 and registration; inside fMRIPrep’s BOLD brain mask, dilated by one voxel
Registration
fMRIPrep’s from-boldref_to-auto00000 transform (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’s exact_field
Grid
80 × 80 × 36 voxels of 3 × 3 × 3.3 mm; shown: 55 × 65 × 36 around the brain
Inputds002603 sub-01: BOLD reference (acq-Mb4Mm3Tr550)fMRIPrep's desc-hmc_boldref, an oblique grid
InputThe exact field where the transform puts the targetevery voxel's B-spline weights at its registered position (numpy, SciPy)
Originalsdcflows B0FieldTransform.fit 2.17.1approx=True: the grid built and sampled where the target lies unregistered
Replicareplicalarmorx, Apache-2.0 · fix (the default), SDC-10 corrected: the grid built and sampled where the transform puts the target
the original against the known answersdcflows B0FieldTransform.fit 2.17.1 − the exact fieldscale ±87.6
the replica against the known answerreplica, fix − the exact fieldscale ±87.6
the replica against itself: fix and reproduce (SDC-10)replica: fix − reproduce (SDC-10)scale ±87.6

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 reasonmax |Δ|Values that differRMS of Δmax |Δ| ÷ range1 − 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-10113230,400 of 230,400 (100 %)7.430.2320.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-10identical: 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-100.00108217,256 of 230,400 (94.3 %)2.68e−52.21e−61.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-01113230,400 of 230,400 (100 %)7.430.230.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 larmorx 61185255c67d; 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 its RUN_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, RMSlargestreplica, fix − exact, RMSlargestreplica, reproduce = sdcflowsNamedVerdict
ds002603 sub-01_task-wm_acq-Mb4Mm3Tr55054,383 voxels in the BOLD brain mask8.4882.95.19e−69.16e−5identicalSDC-01, SDC-10Deliberate correction
ds002603 sub-01_task-wm_acq-SeqMm3Tr200054,790 voxels in the BOLD brain mask7.6787.25.4e−69.16e−5identicalSDC-01, SDC-10Deliberate 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 mapsdcflows 2.17.1replica, reproducereplica, fixVerdict
ds005454-sub-16 sub-16_fmapid-gre16112 × 112 × 70 × 1 voxelsValueError: operands could not be broadcast together with shapes (3,3) (4,)the same errorthe 3D map’s fit, every value (stored in the input’s 4D shape); names SDC-06Deliberate correction
ds002603-sub-01 sub-01_acq-Mm2_fmapid-auto00000128 × 128 × 128 × 1 voxelsValueError: operands could not be broadcast together with shapes (3,3) (4,)the same errorthe 3D map’s fit, every value (stored in the input’s 4D shape); names SDC-06Deliberate correction
ds002422-sub-02 sub-02_run-01_fmapid-auto0000064 × 64 × 24 × 1 voxelsValueError: operands could not be broadcast together with shapes (3,3) (4,)the same errorthe 3D map’s fit, every value (stored in the input’s 4D shape); names SDC-06Deliberate correction
ds002422-sub-02 sub-02_run-02_fmapid-auto0000164 × 64 × 36 × 1 voxelsValueError: operands could not be broadcast together with shapes (3,3) (4,)the same errorthe 3D map’s fit, every value (stored in the input’s 4D shape); names SDC-06Deliberate 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)

EntryWhatRuleOn this pageThe record's case
SDC-01weights beyond the control gridD, measured: Anamed in the SDC-10 example (sampling positions beyond the grid)difftest/sdc01-weights-beyond-the-grid
SDC-02a rotated sampling gridD, measured: Athe unwarping example (fMRIPrep’s registration rotates ds005454’s grid)difftest/sdc02-rotated-sampling-grid
SDC-03CheckRegister’s signed translation testA, not switched yet––
SDC-04a constant phase mapB–difftest/sdc04-constant-phase-map
SDC-05an integer or float32 readout timeA–difftest/sdc05-integer-readout-time
SDC-06a 4D header of one volumeAthe SDC-06 table (fMRIPrep’s own field maps)difftest/sdc06-4d-field-map-of-one-volume
SDC-07TOPUPCoeffReorient’s negationD, measured: A–difftest/sdc07-bids-i-direction-kept
SDC-08a positive-axes series from a fileA–difftest/sdc08-positive-axes-series-from-a-file
SDC-09SubtractPhases without EchoTimeB–difftest/sdc09-missing-echo-time
SDC-10the approximation ignores the transformAthe SDC-10 example and table (ds002603’s BOLD references)difftest/sdc10-approximation-where-the-transform-puts-the-target
SDC-11a resize onto a single voxelA–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

CaseLines comparedChangedReason
every case3814–
difftest/nibabel-quaternion-apply11LAPACK-3.12.1
difftest/nibabel-quaternion-displacements11LAPACK-3.12.1
difftest/nibabel-quaternion-topup11LAPACK-3.12.1
difftest/sdc02-single-voxel-no-notice11LAPACK-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.
  • ApplyCoeffsField takes 1.7 times less time at 1 and at 14 threads.

The machine was shared with other work.

Speed, the replica against the original: sdcflows 2.17.1’s field-map estimation

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
  1. 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×
  2. 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×
  3. 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×
  4. 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×
  5. 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×
  6. 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×
  7. 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×
  8. 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×
0.1 s1 s10 s100 s

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)

Callsdcflowsreplica, reproducereplica, fixreplica ÷ sdcflows
BSplineApprox, ds002422’s first field map (64 × 64 × 24)36782810.223
BSplineApprox, ds005454’s field map (112 × 112 × 70)1,4744684680.317
ApplyCoeffsField, 20 volumes of ds005454’s BOLD (160 × 160 × 96)3,7418288290.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.1335,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, phase96,415 / 63,582 / 79,884 / 31,673 / 31,936 / 31,981
fits: one, two control grids83,573 / 12,842
targets: own grid, aligned, rotated31,711 / 63,697 / 48,058
transforms: none, identity, rigid71,711 / 21,675 / 50,080
recentring: median, mean, mode, none54,882 / 13,671 / 13,826 / 14,036
4D field maps of one volume (SDC-06)14,263
distinct options and settings drawn1,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

StatusWhat it wasRegister
registervalidation/difftest/cases/sdcflows-fieldmap/sdc11-resize-onto-a-single-voxel.json10 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.json2 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.json2 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.json1 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

CaseCategoryWhat it testsVerdictChecks
weightscomparison scriptsthe 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
coeffscomparison scriptsTOPUPCoeffReorient (SDC-07), TransformCoefficients, reorient_pedir; fMRIPrep's fix_coeff
command 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
phasecomparison scriptsthe phase-difference preparation; fMRIPrep's phmap2rads, calc_phdiff, compfmap files
command 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-writercomparison scriptslx.io.save_nibabel against nibabel
command 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
b0fieldcomparison scriptsdeoblique_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
applycomparison scriptsB0FieldTransform.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-corecomparison scriptsBSplineApprox's core: 16 synthetic cases and fMRIPrep's seven calls
command 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-approxcomparison scriptsbspline_approx complete and fMRIPrep's seven bs_filter calls with their files
command 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
ridgecomparison scriptsnumpy's dot, SciPy's cg, scikit-learn's Ridge; fMRIPrep's seven fits and coefficients
command 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-orderrandom testingBSplineApprox 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-signrandom testingBSplineApprox 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-writesrandom testingB0FieldTransform.fit's field written as nibabel writes it (the header's float32), also when the field is held as float64Bit-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-weightsrandom testingB0FieldTransform.fit on a target no knot reaches: scipy's kron of an empty axis is a float64 matrix, so sdcflows' field is float64 zerosBit-identical

Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case).

3/3
difftest/infinity-message-dtyperandom testingBSplineApprox of an unscaled little-endian float32 file holding an infinity: scikit-learn's message names dtype('<f4'), the raw array nibabel returnsBit-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-applyrandom testingB0FieldTransform.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 raisesBit-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-topuprandom testingTOPUPCoeffReorient on a reference whose rotation has two equal axis candidates: nibabel's io_orientation through numpy's SVD picks the axisBit-identical

Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case).

3/3
difftest/mode-zero-signrandom testingBSplineApprox 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-maskrandom testingBSplineApprox 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 NaNBit-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-coefficientsrandom testingBSplineApprox 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 matchBit-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-fitrandom testingB0FieldTransform.fit on a target with a qform only: nibabel's qform affine (extended precision), the field's affine bit for bitBit-identical

Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case).

3/3
difftest/nibabel-quaternion-applyrandom testingB0FieldTransform.apply on a rotated series: the corrected series' header carries nibabel's quaternion (numpy's linear algebra), not the replica's ownBit-identical

Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case).

3/3
difftest/nibabel-quaternion-coefficientsrandom testingBSplineApprox's coefficient grid of a rotated field map: nibabel's quaternion and zero signs in the coefficients' fileBit-identical

Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case).

3/3
difftest/nibabel-quaternion-displacementsrandom testingfmap_to_disp and disp_to_fmap of an oblique scaled int16 field map: nibabel's quaternions in both outputsBit-identical

Bit-identical to sdcflows (a mistake of the replica’s found by random testing, fixed; its permanent case).

2/2
difftest/nibabel-quaternion-topuprandom testingTOPUPCoeffReorient'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-noticerandom testingB0FieldTransform.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-gridrandom testingB0FieldTransform.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 namedDeliberate correction

SDC-01, corrected by default (rule A): in reproduce the replica gives sdcflows’ outputs bit for bit; the default changes 9,160 values and names SDC-01.

3/3
difftest/sdc02-rotated-sampling-gridrandom testingB0FieldTransform.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 namedDeliberate correction

SDC-02, corrected by default (rule A): in reproduce the replica gives sdcflows’ outputs bit for bit; the default changes 1,583 values and names SDC-02.

3/3
difftest/sdc02-single-voxel-no-noticerandom testingB0FieldTransform.apply of a single-voxel series on rotated coefficients: the separable product is the exact one there, so SDC-02 is not namedBit-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-maprandom testingPhaseMap2rads of a constant phase map: the replica raises a clear ValueError (sdcflows rescales 0/0 to NaN everywhere; reproduce gives it), SDC-04 namedBit-identical

Bit-identical to sdcflows in reproduce; SDC-04’s case: the result of fix checked by the rule of the corrections by default.

3/3
difftest/sdc05-integer-readout-timerandom testingB0FieldTransform.apply with an integer readout time: the replica unwarps (sdcflows raises a TypeError from zip over an int; reproduce gives it), SDC-05 namedBit-identical

Bit-identical to sdcflows in reproduce; SDC-05’s case: the result of fix checked by the rule of the corrections by default.

3/3
difftest/sdc06-4d-field-map-of-one-volumerandom testingBSplineApprox 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 namedBit-identical

Bit-identical to sdcflows in reproduce; SDC-06’s case: the result of fix checked by the rule of the corrections by default.

3/3
difftest/sdc07-bids-i-direction-keptrandom testingTOPUPCoeffReorient with a BIDS 'i' phase encoding: the replica keeps TOPUP's sign (sdcflows negates the field; reproduce gives it), SDC-07 namedDeliberate correction

SDC-07, corrected by default (rule A): in reproduce the replica gives sdcflows’ outputs bit for bit; the default changes 818 values and names SDC-07.

3/3
difftest/sdc07-not-named-for-a-wrong-shaperandom testingTOPUPCoeffReorient with a BIDS 'i' direction and coefficients whose shape is not TOPUP's: both modes raise sdcflows' ValueError and SDC-07 is not namedBit-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-filerandom testingB0FieldTransform.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 namedBit-identical

Bit-identical to sdcflows in reproduce; SDC-08’s case: the result of fix checked by the rule of the corrections by default.

3/3
difftest/sdc09-missing-echo-timerandom testingSubtractPhases without EchoTime: the replica raises a clear ValueError (sdcflows a TypeError of comparing None; reproduce gives it), SDC-09 namedBit-identical

Bit-identical to sdcflows in reproduce; SDC-09’s case: the result of fix checked by the rule of the corrections by default.

5/5
difftest/sdc10-approximation-where-the-transform-puts-the-targetrandom testingB0FieldTransform.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 reproduce the replica gives sdcflows’ outputs bit for bit; the default changes 1,288 values and names SDC-10.

3/3
difftest/sdc11-resize-onto-a-single-voxelrandom testingBSplineApprox 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 reproduce; SDC-11’s case: the result of fix checked by the rule of the corrections by default.

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’s mri_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.