fittable

fittable

FittableModel protocol and BaseBoundModel base class.

This module defines the interface between signal models and the shared fitting infrastructure. A FittableModel is a model with all independent variables bound (time, AIF, b-values, PLDs, etc.) so that only free parameters remain.

Each modality provides a wrapper class that creates a FittableModel from its domain-specific signal model:

• DCE: BoundDCEModel(model, t, aif)
• IVIM: BoundIVIMModel(model, b_values)
• ASL: BoundASLModel(plds, m0, params)
• DSC: BoundGammaVariateModel(time)

The BaseBoundModel base class handles fixed-parameter logic shared across all wrappers.

FittableModel

Bases: Protocol

Protocol for fitting-ready models.

All independent variables are bound; only free parameters remain. The fitter interacts exclusively through this interface and never needs to know about modality-specific context (time, AIF, b-values).

Shapes

• observed_batch: (n_observations, n_voxels)
• params_batch: (n_free_params, n_voxels)
• predict_array_batch returns: (n_observations, n_voxels)
• compute_jacobian_batch returns: (n_free_params, n_observations, n_voxels) or None

name property

name

Model display name.

parameters property

parameters

List of free parameter names.

parameter_units property

parameter_units

Mapping of parameter names to their unit strings.

reference property

reference

Literature reference for the model.

get_bounds

get_bounds()

Return lower and upper bounds for each free parameter.

get_initial_guess_batch

get_initial_guess_batch(observed_batch, xp)

Compute initial parameter guesses from observed data.

PARAMETER	DESCRIPTION
observed_batch	Observed signal, shape (n_observations, n_voxels). TYPE: NDArray
xp	Array module (numpy or cupy). TYPE: module

RETURNS	DESCRIPTION
NDArray	Initial guesses, shape (n_free_params, n_voxels).

predict_array_batch

predict_array_batch(params_batch, xp)

Predict signal from parameter values.

PARAMETER	DESCRIPTION
params_batch	Parameter values, shape (n_free_params, n_voxels). TYPE: NDArray
xp	Array module (numpy or cupy). TYPE: module

RETURNS	DESCRIPTION
NDArray	Predicted signal, shape (n_observations, n_voxels).

compute_jacobian_batch

compute_jacobian_batch(params_batch, predicted, xp)

Return analytical Jacobian or None for numerical fallback.

PARAMETER	DESCRIPTION
params_batch	Parameter values, shape (n_free_params, n_voxels). TYPE: NDArray
predicted	Predicted signal, shape (n_observations, n_voxels). TYPE: NDArray
xp	Array module (numpy or cupy). TYPE: module

RETURNS	DESCRIPTION
NDArray | None	Jacobian of shape (n_free_params, n_observations, n_voxels), or None to use numerical finite differences.

BaseBoundModel

BaseBoundModel(model, fixed=None)

Shared base for all modality binding wrappers.

Handles fixed-parameter logic: filtering parameters, bounds, and initial guesses to exclude fixed values, and injecting them back into the full parameter array for model evaluation.

PARAMETER	DESCRIPTION
model	The underlying signal model. TYPE: BaseSignalModel
fixed	Parameters to fix at constant values during fitting. These are removed from the free parameter list and injected back into the full array inside predict_array_batch. TYPE: dict[str, float] | None DEFAULT: None

name property

name

Model display name, delegated to the wrapped signal model.

parameters property

parameters

Free parameters only (excludes fixed).

parameter_units property

parameter_units

Unit strings for free parameters only.

reference property

reference

Literature reference, delegated to the wrapped signal model.

get_bounds

get_bounds()

Return bounds for free parameters only.

ensure_device

ensure_device(xp)

Transfer stored arrays to the device associated with xp.

Call this once before the fitting loop so that every internal array lives on the same device as the observed data. The method is idempotent — repeated calls with the same xp are safe and essentially free.

The base implementation converts any array items in _fixed_values. Subclasses should call super() and then convert their own arrays (time, AIF, b-values, PLDs, etc.) via xp.asarray().

PARAMETER	DESCRIPTION
xp	Array module (numpy or cupy). TYPE: module

compute_jacobian_batch

compute_jacobian_batch(params_batch, predicted, xp)

Return analytical Jacobian or None for numerical fallback.

Default returns None (numerical finite differences). Subclasses with analytical Jacobians should override.