mrpro.operators.DictionaryMatchOp

class mrpro.operators.DictionaryMatchOp[source]

Bases: Operator[Tensor, tuple[Unpack[Tin]]]

Dictionary Matching Operator.

This operator can be used for dictionary matching, for example in magnetic ressonance fingerprinting.

It performs absolute normalized dot product matching between a dictionary of signals, i.e. find the entry \(d^*\) in the dictionary maximizing \(\left|\frac{d}{\|d\|} \cdot \frac{y}{\|y\|}\right|\) and returns the associated signal model parameters \(x\) generating the matching signal \(d^*=d(x)\).

At initialization, a signal model needs to be provided. Afterwards append with different x values should be called to add entries to the dictionary. This operator then calculates for each x value the signal returned by the model. To perform a match, use __call__ and supply some y values. The operator will then perform the dot product matching and return the associated x values.

__init__(generating_function: Callable[[Unpack[Tin]], tuple[Tensor]], index_of_scaling_parameter: int | None = None)[source]

Initialize DictionaryMatchOp.

Parameters:

generating_function (Callable[[Unpack[TypeVarTuple]], tuple[Tensor]]) – signal model that takes n inputs and returns a signal y.
index_of_scaling_parameter (int | None, default: None) –
Normalized dot product matching is insensitive to overall signal scaling. A scaling factor (e.g. the equilibrium magnetization m0 in InversionRecovery) is calculated after the dictionary matching if index_of_scaling_parameter is not None. index_of_scaling_parameter should set to the index of the scaling parameter in the signal model.

Example:
For ~mrpro.operators.models.InversionRecovery the parameters are [m0, t1] and therefore index_of_scaling_parameter should be set to 0. The operator will then return t1 estimated via dictionary matching and m0 via a post-processing step. If index_of_scaling_parameter is None, the value returned for m0 will be meaningless.

__call__(input_signal: Tensor) → tuple[Unpack[Tin]][source]

Perform dot-product matching.

Given an input signal (or batch of signals), this method finds the entry in the precomputed dictionary that has the highest absolute normalized dot product similarity. It then returns the set of parameters x that generated this dictionary entry.

If index_of_scaling_parameter was set during initialization, the corresponding scaling parameter is estimated and inserted into the returned tuple of parameters.

Parameters:: input_signal (Tensor) – Input signal(s) to match against the dictionary. Expected shape is (m, ...), where m is the signal dimension (e.g., number of time points) and (...) are batch dimensions.
Returns:: A tuple of tensors representing the parameters x from the dictionary that best matched the input signal(s). Each tensor in the tuple corresponds to a parameter, and their shapes will match the batch dimensions of input_signal.

forward(input_signal: Tensor) → tuple[Unpack[Tin]][source]: Apply forward of DictionaryMatchOp.

Note

Prefer calling the instance of the DictionaryMatchOp operator as operator(x) over directly calling this method. See this PyTorch discussion.

append(*x: Unpack[Tin]) → Self[source]

Append x values to the dictionary.

Parameters:: x (Unpack[TypeVarTuple]) – points where the signal model will be evaluated. For signal models with n inputs, n tensors should be provided. Broadcasting is supported.
Returns:: Self

__add__(other: Operator[Unpack[Tin], Tout]) → Operator[Unpack[Tin], Tout][source]

__add__(other: Tensor | complex) → Operator[Unpack[Tin], tuple[Unpack[Tin]]]

Operator addition.

Returns lambda x: self(x) + other(x) if other is a operator, lambda x: self(x) + other*x if other is a tensor

__matmul__(other: Operator[Unpack[Tin2], tuple[Unpack[Tin]]] | Operator[Unpack[Tin2], tuple[Tensor, ...]]) → Operator[Unpack[Tin2], Tout][source]

Operator composition.

Returns lambda x: self(other(x))

__mul__(other: Tensor | complex) → Operator[Unpack[Tin], Tout][source]

Operator multiplication with tensor.

Returns lambda x: self(x*other)

__radd__(other: Tensor | complex) → Operator[Unpack[Tin], tuple[Unpack[Tin]]][source]

Operator right addition.

Returns lambda x: other*x + self(x)

__rmul__(other: Tensor | complex) → Operator[Unpack[Tin], Tout][source]

Operator multiplication with tensor.

Returns lambda x: other*self(x)