compute_svd_coefficients#

mrinufft.extras.compute_svd_coefficients(field_map: NDArray, readout_time: NDArray, mask: NDArray, L: int = -1, n_bins: int | tuple[int, int] = 1024, lazy: bool = False, partial_svd: bool = True)[source]#

Compute off-resonance correction coefficients using an SVD.

Solves \(\arg\min_{B,C} = \|E - BC \|_{F}^2\)

In practise it utilizes truncated SVD to extract L leading singular vectors from the weighted exponentiated phase matrix sampled at field map histogram centers.

Parameters:

  • field_map (NDArray) – The field map (off-resonance map) in rad/s, If complex-valued, the real part is interpreted as R2* mapping. If real-valued this is the field inhomogeneities in Hz. and will be multiplied by \(2j\pi\)

  • readout_time (NDArray) – The vector of time points (in seconds) at which to compute phase evolution.

  • mask (NDArray) – Binary mask indicating object region for field map/statistics. Only those voxels are used to build the histogram, so field-map values outside it are clamped to the range spanned by the object.

  • L (int, optional) – Number of virtual centers or basis functions retained (default is -1, automatically estimated from the time-bandwidth product of the readout). Too small an L leaves a large residual phase error, which appears as artefacts in the corrected image; a warning is logged when that happens.

  • n_bins (int, optional) – Number of histogram bins for off-resonance value clustering (default is 1024).

  • lazy (bool, default False) – If True, use a lazy evaluation scheme for the space interpolator C, saving memory.

  • partial_svd (bool, default True) – If True, only compute the L components required for the estimation, not the full SVD.

Returns:

  • B (NDArray) – [L, nbins] phase basis matrix in the time domain.

  • C (NDArray) – [L, nt] interpolation matrix to transform weighted basis to phase at the time points; nt = len(readout_time).

  • E (NDArray) – [nbins, nt] exponential off-resonance phase matrix at input histogram bins.

References

Sutton BP, Noll DC, Fessler JA. Fast, iterative image reconstruction for MRI in the presence of field inhomogeneities. IEEE Trans Med Imaging. 2003 Feb;22(2):178-88. doi: 10.1109/tmi.2002.808360. PMID: 12715994.

Note

This function uses numpy for all CPU arrays, and cupy for all on-gpu array. It will convert all its array argument to the respective array library. The outputs will be converted back to the original array module and device.

See also

This function is part of the orc_factorization registry, get_orc_factorization(). You can find other registered functions in this registry below:

Key

Function

"svd"

compute_svd_coefficients(field_map, readout_time, mask, L=-1, n_bins=1024, lazy=False, partial_svd=True)

"mti"

compute_mti_coefficients(field_map, readout_time, mask, L=-1, n_bins=1024, lazy=False)

"mfi"

compute_mfi_coefficients(field_map, readout_time, mask, L=9, n_bins=1024, lazy=True)