LION.models.LIONmodel

Classes

LIONModelParameter(**kwargs)	A model's parameters (default_parameters()), with what every model has: model_input_type (ModelInputType) and initial_reconstruction ("default", or how the model's initial reconstruction is made; set_initial_reconstruction), plus normalisation once set (set_normalisation).
LIONmodel(model_parameters[, operator_params])	Base class for all models in the toolbox.
ModelInputType(value[, names, module, ...])	What a model takes as input: the measurements (SINOGRAM; e.g. LPD) or an image, a reconstruction of them (IMAGE; e.g. FBPConvNet, the denoisers).

Functions

as_model_parameter(params)	The LIONModelParameter for params, with model_input_type as a ModelInputType.
made_from_random_state(target, kwargs, state)	target(**kwargs) made with torch's random state state (so with the initial weights a model made from that state had), leaving the program's random numbers as they were.
noise_level_map(noise_level, x)	The noise level as one channel the size of the images x (B, C, ...): (B, 1, ...).

---

class LION.models.LIONmodel.LIONModelParameter(**kwargs)

Bases: LIONParameter

A model’s parameters (default_parameters()), with what every model has: model_input_type (ModelInputType) and initial_reconstruction (“default”, or how the model’s initial reconstruction is made; set_initial_reconstruction), plus normalisation once set (set_normalisation).

The parameters given as keywords, LIONParameter(n_iters=10). A dict value becomes a LIONParameter, unless it is a spec (a dict with "_target_", see LION.utils.spec), which describes an object and stays a dict.

class LION.models.LIONmodel.LIONmodel(model_parameters, operator_params=None)

Bases: Module, ABC

Base class for all models in the toolbox.

A model that uses an operator takes (operator_params, model_parameters=None); one that doesn’t takes only (model_parameters=None).

operator_params: the parameters of the operator the model uses (an OperatorParameters). For CT, it’s the geometry: LPD(geometry). The model makes its operator from them (self.op): its domain is the image, its range the measurements (the sinogram, in CT).

model_parameters: the model’s own parameters; None gives default_parameters().

Initialize internal Module state, shared by both nn.Module and ScriptModule.

abstract static default_parameters()

The model’s parameters, each with its default: every parameter the model has, so this is also their list. A model from a paper defaults to the paper’s.

get_parameters()

(model_parameters, operator_params), or model_parameters for a model without an operator.

get_input_type()

What the model takes: measurements or an image (ModelInputType).

takes_noise_level()

Whether the model is called with the noise level of its input, model(x, noise_level=...): its parameters’ use_noise_level (e.g. DRUNet’s). A model that decides otherwise (e.g. GSD, from its denoiser) says so by overriding this.

set_normalisation(normalisation_type='sample', dataset=None, data_range=None)

Normalise the model’s inputs (and map its outputs back), in training and whenever it is used: “sample” (each image’s own range), “dataset” (the targets’ range over dataset, computed now), “custom” (data_range) or “none”. It is one of the model’s parameters (model_parameters.normalisation: its type, and range for “dataset” and “custom”), so it is saved and made again with the model.

A model that takes measurements (sinograms) gets them mapped as the images are, by linearity (Normalisation.normalise_measurements), and its output is mapped back; its operator is unchanged. “sample” isn’t defined for such models.

set_initial_reconstruction(reconstruction)

How the model’s initial reconstruction is made from the measurements, reconstruction(y, operator): the input of a model that takes images (LION.optimizers.LIONsolver.model_forward), or where a model that takes measurements and starts from a reconstruction (e.g. LPD) starts, in training and whenever it is used. It is one of the model’s parameters (model_parameters.initial_reconstruction), so it is saved and made again with the model: a LION function or a functools.partial of one, e.g. functools.partial(sirt, num_iterations=50). "default" (or None) is the operator’s default reconstruction (Operator.default_reconstruction_fn, e.g. fdk for CT), replaced by that function once the model has its operator, so it is saved as the function that was used.

initial_reconstruction(y, op)

The model’s initial reconstruction of the measurements y (model_parameters.initial_reconstruction; “default”: op’s default reconstruction, e.g. FDK for CT).

normalise(x)

Normalise x as set by set_normalisation() (identity if unset).

unnormalise(x, reference=None)

Undo normalise() (identity if no normalisation is set). reference: the input that was normalised, whose own range a “sample” normalisation maps back to.

static cite(cite_format='bib')

Where the model comes from: its paper’s citation, BibTeX (“bib”) or “MLA” (LION.utils.citation); None if it has none. Models from a paper define it.

save(fname, **kwargs)

Saves the model to fname (fname.json, its parameters and records, and fname.pt, its weights), with what kwargs give:

• dataset: the record of the data (LION.data_loaders.data_record, e.g. experiment.data_record("train")), or a LIONParameter describing it;

• training: the record of the training (LION.optimizers.training_record, written by the solvers), or a LIONParameter describing it;

• operator_params (optional): the parameters of the data’s operator (e.g. the CT geometry), for a model without them;

• loss, epoch, and for resuming optimizer, scheduler (their state_dict()) and random_state: saved in the .pt. Other keywords are a ValueError.

Solvers save their models this way. To save a model to train it further, with the optimizer’s state, use save_checkpoint().

save_checkpoint(fname, epoch, loss, optimizer, training_param, **kwargs)

This is like save, but saves a checkpoint of the model. Its essentailly a wrapper of save() with mandatory values

classmethod instantiate(source, *, allow=(), initial_weights=False, **arguments)

The model a saved file describes, with its saved parameters and new (untrained) weights. load() is this plus the saved weights.

source: a model’s file ("model", "model.json" or "model.pt": the .json is read), the dict read from it, or the model’s spec. Called on a model class it makes that class; called on LIONmodel, the class the file names (allow as in load).

arguments replace recorded ones, e.g. model_parameters from parameters_from_file, changed, or operator_params.

initial_weights=True (source a file a solver saved): the weights its training started from, as its training record says: made again from the random state saved with the model, or read from the initial weights the solver saved; checked against the recorded hash. Not with arguments: a changed model is trained from new weights.

classmethod parameters_from_file(source, *, allow=())

What default_parameters() gives, as source (as in instantiate) recorded it: the model’s parameters, to change and make a model with, e.g.

parameters = LPD.parameters_from_file(“model”) parameters.n_iters = 5 model = LPD.instantiate(“model”, model_parameters=parameters)

instantiate makes the class the file records, with its other arguments (e.g. the operator’s parameters); LPD(operator_params, parameters) works too. Called on a model class, a file of another class gives a warning.

classmethod load(fname, *, weights_only=True, supress_warnings=False, allow=())

Function that loads a model from memory: built from its .json, with the weights of its .pt.

Called on a model class (FBPConvNet.load(f)) it builds that class; called on LIONmodel (LIONmodel.load(f)) it builds the class the file names. allow: module prefixes of your own model classes (see LION.utils.spec.build). weights_only=False reads a .pt that holds other objects, which can run code: only for files you trust. Returns (model, options, data); the model keeps its file as model.source_file (without suffix).

classmethod load_checkpoint(fname, *, weights_only=True, allow=())

Loads a checkpoint file (LIONsolver.set_checkpointing) as load loads a model file. Returns (model, options, data): the model, made again from the file (allow: modules outside LION it may name) with its weights; its options; the file’s other contents (the optimizer’s state, the epoch, the losses, …).

classmethod load_checkpoint_if_exists(fname, model, optimiser, total_loss, verbose=False)

Load the latest checkpoint matching fname (a glob pattern) into model and optimiser, in place.

The weights are loaded into the given model (rather than into a new instance) so that optimiser keeps optimising the parameters of the model that is returned. Returns (model, optimiser, start_epoch, total_loss, data), data["file"] being the checkpoint read; if no checkpoint exists the inputs are returned unchanged with start_epoch=0 and data=None.

class LION.models.LIONmodel.ModelInputType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: int, Enum

What a model takes as input: the measurements (SINOGRAM; e.g. LPD) or an image, a reconstruction of them (IMAGE; e.g. FBPConvNet, the denoisers). Its model_parameters.model_input_type.

SINOGRAM = 0

IMAGE = 1

LION.models.LIONmodel.as_model_parameter(params)

The LIONModelParameter for params, with model_input_type as a ModelInputType.

JSON files have no classes: a saved parameter loads back as a plain LIONParameter, nested ones included (e.g. the backbone parameters of GSD), and model_input_type as an int. Models call this on their parameters, so they accept them however they were made.

LION.models.LIONmodel.made_from_random_state(target, kwargs, state)

target(**kwargs) made with torch’s random state state (so with the initial weights a model made from that state had), leaving the program’s random numbers as they were.

LION.models.LIONmodel.noise_level_map(noise_level, x)

The noise level as one channel the size of the images x (B, C, …): (B, 1, …). noise_level: one number, or one per image (B values), as a model that takes the noise level is given it (model(x, noise_level=...); GaussianDenoiserSolver gives one per image, a PnP reconstruction one number).