Module xqsm 

xQSM deep-learning dipole inversion (onnx feature).

xQSM is an octave-convolution U-Net (with a global residual) that maps a local tissue field (ppm) to susceptibility (ppm). It is orientation-agnostic and takes no dipole kernel — the field goes in, χ comes out. This mirrors the authors’ pure-Python inference (sunhongfu/xQSM): centered zero-pad each dimension to a multiple of 8, run the net, crop back, and multiply the output by the mask. No normalization.

Weights are not bundled; the caller passes the exported xqsm.onnx bytes (see crate::models).

Reference pipeline

• Training data: local fields simulated from 1 mm isotropic χ maps (xQSM_invivo: 90 LN-QSM subjects, 48³ patches) by the forward dipole model; no field strength or TE enters (Gao et al., NMR Biomed 2021, “Data Preparation”).
• Inputs fed in the paper’s in-vivo tests: best-path unwrapping, then RESHARP background removal (paper, in-vivo experiments paragraph); tested at 1 mm (3T) and 0.6 mm (7T) isotropic. The paper’s resolution study found all networks degrade on anisotropic voxels (NRMSE 22–47 %) and on voxels finer than the training data (“Generalization Evaluation”).
• Resampling: the authors’ MATLAB wrapper (sunhongfu/iQSM_Plus legacy/matlab/xQSM.m:104-127,170-176) interpolates anisotropic data to an isotropic grid at the finest voxel size (imresize3) before the net and back afterwards. Their Python sunhongfu/xQSM inference.py does not resample. This crate does not resample either; the caller must supply an isotropic grid to match the MATLAB wrapper.
• Orientation: axial (B0 along the third axis; matlab/eval/run_demo.m:8).

Agreement with the original

tests/models_onnx/dipole.rs runs it on a 36×32×28 box of in-vivo data (1 mm, 2.89 T, across the brain’s edge) against its original’s verified QSM-CI entry, xQSM 5d13b36 (xqsm) (QSMxT/QSM-CI#316; the fixture is regenerated in Actions by tests/data/dl_dipole_qsmci_small.py): NRMSE 1.5e-3 %, max |Δ| 1.0e-5 ppm (measured 2026-10-30): float32 rounding. On QSM-CI’s 128×160×96 case: 4.2e-4 %.

Pipeline rules

The facts above that a configuration can depart from are published as rules in crate::pipeline::rules::RULES (each with its strength, basis, reason and source): xqsm.bg-resharp.

Functions

xqsm

Run xQSM dipole inversion.

xqsm_tiled

Memory-bounded xQSM via overlap-tiling — the same fully-convolutional net run patch-by- patch so peak memory is bounded by one patch (for 32-bit WASM, where the whole-volume xqsm overflows the 4 GB heap on clinical-size data). Results approximate whole-volume xQSM up to tile-boundary error; see crate::inversion::tiled.