core

Module containing core utility functions and abstract classes for models.

class FilterOutputs(indexes: int | list[int])

Helper class for use in :class:~`torch.nn.Sequential` to filter previous layer’s outputs by index.

indexes

Index(es) of the inputs to pass forward.

Type:

int | list[int]

Parameters:

indexes (int | list[int]) – Index(es) of the inputs to pass forward.

forward(inputs: Tensor) → Tensor

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class MinervaBackbone(*args, **kwargs)

Abstract class to mark a model for use as a backbone.

backbone

Backbone of the the model.

Type:

Module

freeze_backbone(freeze: bool = True) → None

Freeze the backbone so that the weights do not change while the rest of the model trains.

Parameters:

freeze (bool) – Whether to ‘freeze’ the backbone (Set requires_grad_() to False). Defaults to True.

Added in version 0.28.

get_backbone() → Module

Gets the backbone network of the model.

Returns:

The backbone of the model.

Return type:

Module

class MinervaDataParallel(model: Module, paralleliser: Type[DataParallel] | Type[DistributedDataParallel], *args, **kwargs)

Wrapper for DataParallel or DistributedDataParallel that automatically fetches the attributes of the wrapped model.

model

torch model to be wrapped by DataParallel or DistributedDataParallel.

Type:

Module

paralleliser

The paralleliser to wrap the model in.

Type:

DataParallel | DistributedDataParallel

Parameters:

model (Module) – torch model to be wrapped by DataParallel or DistributedDataParallel.

forward(*inputs: tuple[Tensor, ...]) → tuple[Tensor, ...]

Ensures a forward call to the model goes to the actual wrapped model.

Parameters:

inputs (tuple[Tensor, ...]) – Input of tensors to be parsed to the model forward.

Returns:

Output of model.

Return type:

tuple[Tensor, …]

class MinervaModel(criterion: Module | None = None, input_size: tuple[int, ...] | None = None, n_classes: int | None = None, scaler: GradScaler | None = None)

Abstract class to act as a base for all Minerva Models.

Designed to provide inter-compatability with Trainer.

criterion

torch loss function model will use.

Type:

Module

input_shape

Optional; Defines the shape of the input data. Typically in order of number of channels, image width, image height but may vary dependant on model specs.

Type:

tuple[int, …]

n_classes

Number of classes in input data.

Type:

int

output_shape

The shape of the output of the network. Determined and set by determine_output_dim().

Type:

tuple[int, …]

optimiser

torch optimiser model will use, to be initialised with inherited model’s parameters.

Parameters:

• criterion (Module) – Optional; torch loss function model will use.

• input_shape (tuple[int, ...]) – Optional; Defines the shape of the input data. Typically in order of number of channels, image width, image height but may vary dependant on model specs.

• n_classes (int) – Optional; Number of classes in input data.

determine_output_dim(sample_pairs: bool = False, change_detection: bool = False) → None

Uses get_output_shape() to find the dimensions of the output of this model and sets to attribute.

set_criterion(criterion: Module) → None

Set the internal criterion.

Parameters:

criterion (Module) – Criterion (loss function) to set.

set_optimiser(optimiser: Optimizer) → None

Sets the optimiser used by the model.

Warning

MUST be called after initialising a model and supplied with a torch.optim.Optimizer using this model’s parameters.

Parameters:

optimiser (Optimizer) – torch.optim.Optimizer model will use, initialised with this model’s parameters.

step(x: Tensor, y: Tensor, train: bool = False) → tuple[Tensor, Tensor | tuple[Tensor, ...]]

step(x: Tensor, *, train: bool = False) → tuple[Tensor, Tensor | tuple[Tensor, ...]]

Generic step of model fitting using a batch of data.

Raises:

• NotImplementedError – If optimiser is None.

• NotImplementedError – If criterion is None.

Parameters:

• x (Tensor) – Batch of input data to network.

• y (Tensor) – Either a batch of ground truth labels or generated labels/ pairs.

• train (bool) – Sets whether this shall be a training step or not. True for training step which will then clear the optimiser, and perform a backward pass of the network then update the optimiser. If False for a validation or testing step, these actions are not taken.

Returns:

tuple of the loss computed by the loss function and the model outputs.

Return type:

tuple[Tensor, Tensor | tuple[Tensor, …]]

class MinervaOnnxModel(model: Module, *args, **kwargs)

Special model class for enabling onnx models to be used within minerva.

model

onnx model imported into torch.

Type:

Module

Parameters:

model (Module) – onnx model imported into torch.

forward(*inputs: Any) → Any

Performs a forward pass of the model within.

Parameters:

inputs (Any) – Input to be parsed to the .forward method of model.

Returns:

Output of model.

Return type:

Any

class MinervaWrapper(model: Module | Callable[[...], Module], criterion: Module | None = None, input_size: tuple[int, ...] | None = None, n_classes: int | None = None, scaler: GradScaler | None = None, *args, **kwargs)

Wraps a torch model class in MinervaModel so it can be used in minerva.

model

The wrapped torch model that is now compatible with minerva.

Type:

Module

Parameters:

• model (Module | Callable[..., Module]) – The torch model object or constructor to, initialise and then wrap in model.

• criterion (Module) – Optional; torch loss function model will use.

• input_shape (tuple[int, ...]) – Optional; Defines the shape of the input data. Typically in order of number of channels, image width, image height but may vary dependant on model specs.

• n_classes (int) – Optional; Number of classes in input data.

forward(*inputs) → Any

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

bilinear_init(in_channels: int, out_channels: int, kernel_size: int) → Tensor

Constructs the weights for the bi-linear interpolation kernel for use in transpose convolutional layers.

Source: https://github.com/haoran1062/FCN-pytorch/blob/master/FCN.py

Parameters:

• in_channels (int) – Number of input channels to the layer.

• out_channels (int) – Number of output channels from the layer.

• kernel_size (int) – Size of the (square) kernel.

Returns:

Tensor of the initialised bi-linear interpolated weights for the transpose convolutional layer’s kernels.

Return type:

Tensor

extract_wrapped_model(model: MinervaModel | MinervaDataParallel | OptimizedModule) → MinervaModel

Extracts the actual model object from within MinervaDataParallel or :class:~`torch._dynamo.eval_frame.OptimizedModule` and returns.

Parameters:

model (MinervaModel | MinervaDataParallel | OptimizedModule) – Model that may or may not be wrapped.

Returns:

Extracted model.

Return type:

MinervaModel

Added in version 0.27.

get_model(model_name: str) → Callable[[...], MinervaModel]

Returns the constructor of the model_name in models.

Parameters:

model_name (str) – Name of the model to get.

Returns:

Constructor of the model requested.

Return type:

Callable[…, MinervaModel]

get_output_shape(model: Module, image_dim: Sequence[int] | int, sample_pairs: bool = False, change_detection: bool = False) → tuple[int, ...]

Gets the output shape of a model.

Parameters:

• model (Module) – Model for which the shape of the output needs to be found.

• image_dim (Sequence[int] | int]) – Expected shape of the input data to the model.

• sample_pairs (bool) – Optional; Flag for if paired sampling is active. Will send a paired sample through the model.

Returns:

The shape of the output data from the model.

Return type:

tuple[int, …]

get_torch_weights(weights_name: str) → WeightsEnum | None

Loads pre-trained model weights from torchvision via Torch Hub API.

Parameters:

weights_name (str) – Name of model weights. See https://pytorch.org/vision/stable/models.html#table-of-all-available-classification-weights for a list of possible pre-trained weights.

Returns:

API query for the specified weights. None if query cannot be found. See note on use:

Return type:

torchvision.models._api.WeightsEnum | None

Note

This function only returns a query for the API of the weights. To actually use them, you need to call get_state_dict() to download the weights (if not already in cache).

is_minerva_model(model: Module) → bool

Checks if model is a MinervaModel while accounting for models that are :class:~`torch._dynamo.eval_frame.OptimizedModule` from torch.compile() usage.

Parameters:

model (Module) – Torch model to be evaluated.

Returns:

True if model (or model wrapped in a compiled model) is a MinervaModel or MinervaDataParallel, else False.

Return type:

bool

Added in version 0.27.

is_minerva_subtype(model: Module, subtype: type) → bool

Checks if model is a specific type while accounting for models that are :class:~`torch._dynamo.eval_frame.OptimizedModule` from torch.compile() usage.

Parameters:

• model (Module) – Torch model to be evaluated.

• subtype (type) – Type to check model against.

Returns:

True if model (or model wrapped in a compiled model) is subtype else False.

Return type:

bool

Added in version 0.27.