DictionaryMatcher

class torchsim.DictionaryMatcher(acquisition=None, *, dictionary=None, parameters=None, query_chunk_size=4096, dictionary_chunk_size=16384, top_k=1, groups=None, prune=5e-3)

Bases: Estimator

Match signals using normalized complex inner products.

Parameters:

• acquisition (Simulator, optional) – The sequence being inverted: a simulator that ships with TorchSim, one written by subclassing Simulator, or any other Simulator. Every tissue property that is neither unknown nor measured separately is fixed on it beforehand, with the constructor or bind(). Leave it out to fit from signals handed to fit() directly.

• dictionary (torch.Tensor, optional) – Simulated atoms shaped (n_atoms, n_contrasts). Leave it out and give an acquisition instead, and the atoms are simulated from it.

• parameters (torch.Tensor, optional) – Parameter values shaped (n_atoms, n_parameters). If provided, a call returns parameter estimates; otherwise it returns atom indices.

• query_chunk_size (int, optional) – Maximum measured signals compared at once.

• dictionary_chunk_size (int, optional) – Maximum dictionary atoms compared at once.

• top_k (int, optional) – Number of candidates retained by match(). The first is the conventional dictionary-matching estimate.

• groups (int, optional) – Cluster the dictionary into this many groups and match against their representative signals first, ruling out whole groups before any atom in them is scored. Read grouping afterwards: its condition says whether the representatives are still distinct enough to prune with, and its compression says how much shorter an inner product inside a group is.

• prune (float, optional) – How far below its best group score a voxel still considers a group, as a fraction of that score. Larger keeps more groups and costs more. The default is the value Cauley et al. [1] tuned on 280 groups of 700 atoms; on a smaller dictionary or a coarser parameter grid it can rule out the group actually holding the match, which shows up as a handful of voxels landing several grid steps away. Widening it is the fix.

Notes

Compression comes first and is global: one temporal basis for the whole dictionary, which the signals are in too. Grouping then clusters within that basis, so the two savings multiply – the basis shortens every inner product, the grouping cuts how many are taken. State a rank and the dictionary it matches against is compressed to (atoms, rank).

The expensive operation is a matrix product. Torch therefore dispatches directly to the installed CPU BLAS or cuBLAS implementation; a separate C++ or Triton matrix-multiplication kernel would duplicate a faster vendor implementation. Chunking bounds the temporary score matrix.

References

[1]

Cauley, S. F., Setsompop, K., Ma, D., et al., “Fast group matching for MR fingerprinting reconstruction”, Magnetic Resonance in Medicine 74.2 (2015), pp. 523-528. https://doi.org/10.1002/mrm.25439

Methods

fit	Fit the estimator over a sampling of the tissue it will meet.
from_coefficients	Map coefficients that are already in this estimator's basis.
map	Estimate the tissue a measurement came from.
match	Return the top matching atoms, scores, scales, and parameters.
training_set	Simulate a training set: signals, unknowns, and knowns.
uncertainty_of	The standard deviation the measurement noise leaves on each map.

property fitted

Whether the matcher holds a dictionary.

property grouping

How the dictionary was clustered, or None if it was not.

match(signals)

Return the top matching atoms, scores, scales, and parameters.