tomopt.optimisation.loss package

Submodules

tomopt.optimisation.loss.loss module

class tomopt.optimisation.loss.loss.AbsDetectorLoss(*, target_budget, budget_smoothing=10, cost_coef=None, steep_budget=True, debug=False)

Bases: Module

Abstract base class from which all loss functions should inherit.

The loss consists of:

• A component that quantifies the performance of the predictions made via the detectors

• An optional component that relates to the cost of the detector

The total loss is the sum of these, with the cost-component being rescaled by a coefficient characterising its relative importance.

The performance component (error) should ideally be as close to the final task that the detector will be performing, and will depend on the output of the inference algorithm used

The optional cost component is included as a budget weighting, which gradually increases with the current cost up to a predefined budget, after which it increases rapidly, but smoothly. Be default, the budget is based on a sigmoid centred at the budget, which linearly increases after the budget is exceeded. A less steep version is selectable, which flattens out slightly for high costs.

Inheriting classes will need to at least override the _get_inference_loss method.

Parameters:

• target_budget (Optional[float]) – If not None, will include a cost component in the loss configured for the specified budget. Should be specified in the same currency units as the detector cost.

• budget_smoothing (float) – controls how quickly the budget term rises with cost; lower values => slower rise

• cost_coef (Union[Tensor, float, None]) – Balancing coefficient used to multiply the budget term prior to its addition to the error component of the loss. If set to None, it will be set equal to the inference-error computed the first time the loss is computed

• steep_budget (bool) – If True, will use a linearly increasing budget term when the budget is exceeded, otherwise the budget term will flatten off for very high costs

• debug (bool) – If True, will print out information about the loss whenever it is evaluated

forward(pred, volume)

Computes the loss for the predictions of a single volume using the current state of the detector

Parameters:

• pred (Tensor) – the predictions from the inference

• volume (Volume) – Volume containing the passive volume that was being predicted and the detector being optimised

Return type:

Tensor

Returns:

The loss for the predictions and detector

class tomopt.optimisation.loss.loss.AbsMaterialClassLoss(*, x02id, target_budget, budget_smoothing=10, cost_coef=None, steep_budget=True, debug=False)

Bases: AbsDetectorLoss

Abstract base class for cases in which the task is to classify materials in the passive volumes, or some other aspect of the volumes. The targets returned by the volume are expected to be float X0s, and are converted to class IDs using an X0 to ID map.

The loss consists of:

• A component that quantifies the performance of the predictions made via the detectors

• An optional component that relates to the cost of the detector

The total loss is the sum of these, with the cost-component being rescaled by a coefficient characterising its relative importance.

The performance component (error) should ideally be as close to the final task that the detector will be performing, and will depend on the output of the inference algorithm used

The optional cost component is included as a budget weighting, which gradually increases with the current cost up to a predefined budget, after which it increases rapidly, but smoothly. Be default, the budget is based on a sigmoid centred at the budget, which linearly increases after the budget is exceeded. A less steep version is selectable, which flattens out slightly for high costs.

Inheriting classes will need to at least override the _get_inference_loss method.

Parameters:

• x02id (Dict[float, int]) – Dictionary mapping float X0 targets to integer class IDs

• target_budget (float) – If not None, will include a cost component in the loss configured for the specified budget. Should be specified in the same currency units as the detector cost.

• budget_smoothing (float) – controls how quickly the budget term rises with cost; lower values => slower rise

• cost_coef (Union[Tensor, float, None]) – Balancing coefficient used to multiply the budget term prior to its addition to the error component of the loss. If set to None, it will be set equal to the inference-error computed the first time the loss is computed

• steep_budget (bool) – If True, will use a linearly increasing budget term when the budget is exceeded, otherwise the budget term will flatten off for very high costs

• debug (bool) – If True, will print out information about the loss whenever it is evaluated

class tomopt.optimisation.loss.loss.VolumeClassLoss(*, x02id, target_budget, budget_smoothing=10, cost_coef=None, steep_budget=True, debug=False)

Bases: AbsMaterialClassLoss

Loss function designed for tasks where some overall target of the passive volume must be classified, and the target of the volume is encoded as a float X0. E.g. what is the material of a large block in the volume.

The Inference-error component of the loss depends on shape of predictions provided:

If the predictions are of shape (1,classes,voxels), they will be interpreted as multi-class log-probabilities and the negative log-likelihood computed If the predictions are of shape (1,1,voxels), they will be interpreted as binary class probabilities and the binary cross-entropy computed

The ordering of the “flattened” voxels should match that of volume.get_rad_cube().flatten()

The total loss consists of:

• The NLL or BCE

• An optional component that relates to the cost of the detector

The total loss is the sum of these, with the cost-component being rescaled by a coefficient characterising its relative importance.

The optional cost component is included as a budget weighting, which gradually increases with the current cost up to a predefined budget, after which it increases rapidly, but smoothly. Be default, the budget is based on a sigmoid centred at the budget, which linearly increases after the budget is exceeded. A less steep version is selectable, which flattens out slightly for high costs.

Parameters:

• x02id (Dict[float, int]) – Dictionary mapping float X0 targets to integer class IDs

• target_budget (float) – If not None, will include a cost component in the loss configured for the specified budget. Should be specified in the same currency units as the detector cost.

• budget_smoothing (float) – controls how quickly the budget term rises with cost; lower values => slower rise

• cost_coef (Union[Tensor, float, None]) – Balancing coefficient used to multiply the budget term prior to its addition to the error component of the loss. If set to None, it will be set equal to the inference-error computed the first time the loss is computed

• steep_budget (bool) – If True, will use a linearly increasing budget term when the budget is exceeded, otherwise the budget term will flatten off for very high costs

• debug (bool) – If True, will print out information about the loss whenever it is evaluated

class tomopt.optimisation.loss.loss.VolumeIntClassLoss(*, targ2int, pred_int_start, use_mse, target_budget, budget_smoothing=10, cost_coef=None, steep_budget=True, debug=False)

Bases: AbsDetectorLoss

Loss function designed for tasks where some overall integer target of the passive volume must be classified, and the values of this target are quantifiably comparable (i.e. the integers are treatable as numbers not just categorical codes). E.g. Predicting how many layers of the passive volume are filled with a given material.

The Inference-error component of the loss computed as the integer_class_loss(). Predictions should be provided as probabilities for every possible integer target The target from the volume can be converted to an integer (e.g. height to layer ID) using a targ2int function

The total loss consists of:

• The integer class loss (ICL)

• An optional component that relates to the cost of the detector

The total loss is the sum of these, with the cost-component being rescaled by a coefficient characterising its relative importance.

The optional cost component is included as a budget weighting, which gradually increases with the current cost up to a predefined budget, after which it increases rapidly, but smoothly. Be default, the budget is based on a sigmoid centred at the budget, which linearly increases after the budget is exceeded. A less steep version is selectable, which flattens out slightly for high costs.

Parameters:

• target_budget (float) – If not None, will include a cost component in the loss configured for the specified budget. Should be specified in the same currency units as the detector cost.

• budget_smoothing (float) – controls how quickly the budget term rises with cost; lower values => slower rise

• cost_coef (Union[Tensor, float, None]) – Balancing coefficient used to multiply the budget term prior to its addition to the error component of the loss. If set to None, it will be set equal to the inference-error computed the first time the loss is computed

• steep_budget (bool) – If True, will use a linearly increasing budget term when the budget is exceeded, otherwise the budget term will flatten off for very high costs

• debug (bool) – If True, will print out information about the loss whenever it is evaluated

class tomopt.optimisation.loss.loss.VolumeMSELoss(*, target_budget, budget_smoothing=10, cost_coef=None, steep_budget=True, debug=False)

Bases: AbsDetectorLoss

TODO: Add unit tests and docs

class tomopt.optimisation.loss.loss.VoxelClassLoss(*, x02id, target_budget, budget_smoothing=10, cost_coef=None, steep_budget=True, debug=False)

Bases: AbsMaterialClassLoss

Loss function designed for tasks where the voxelwise material class ID must be classified. Inference-error component of the loss is the negative log-likelihood on log class-probabilities, averaged over all voxels (NLL)

Predictions should be provided as log-softmaxed class probabilities per voxel, with shape (1,classes,voxels). The ordering of the “flattened” voxels should match that of volume.get_rad_cube().flatten()

The total loss consists of:

• The NLL

• An optional component that relates to the cost of the detector

The total loss is the sum of these, with the cost-component being rescaled by a coefficient characterising its relative importance.

The optional cost component is included as a budget weighting, which gradually increases with the current cost up to a predefined budget, after which it increases rapidly, but smoothly. Be default, the budget is based on a sigmoid centred at the budget, which linearly increases after the budget is exceeded. A less steep version is selectable, which flattens out slightly for high costs.

Parameters:

• x02id (Dict[float, int]) – Dictionary mapping float X0 targets to integer class IDs

• target_budget (float) – If not None, will include a cost component in the loss configured for the specified budget. Should be specified in the same currency units as the detector cost.

• budget_smoothing (float) – controls how quickly the budget term rises with cost; lower values => slower rise

• cost_coef (Union[Tensor, float, None]) – Balancing coefficient used to multiply the budget term prior to its addition to the error component of the loss. If set to None, it will be set equal to the inference-error computed the first time the loss is computed

• steep_budget (bool) – If True, will use a linearly increasing budget term when the budget is exceeded, otherwise the budget term will flatten off for very high costs

• debug (bool) – If True, will print out information about the loss whenever it is evaluated

class tomopt.optimisation.loss.loss.VoxelX0Loss(*, target_budget, budget_smoothing=10, cost_coef=None, steep_budget=True, debug=False)

Bases: AbsDetectorLoss

Loss function designed for tasks where the voxelwise X0 value must be predicted as floats. Inference-error component of the loss is the squared-error on X0 predictions, averaged over all voxels (MSE)

The total loss consists of:

• The MSE

• An optional component that relates to the cost of the detector

The total loss is the sum of these, with the cost-component being rescaled by a coefficient characterising its relative importance.

The optional cost component is included as a budget weighting, which gradually increases with the current cost up to a predefined budget, after which it increases rapidly, but smoothly. Be default, the budget is based on a sigmoid centred at the budget, which linearly increases after the budget is exceeded. A less steep version is selectable, which flattens out slightly for high costs.

Parameters:

• target_budget (Optional[float]) – If not None, will include a cost component in the loss configured for the specified budget. Should be specified in the same currency units as the detector cost.

• budget_smoothing (float) – controls how quickly the budget term rises with cost; lower values => slower rise

• cost_coef (Union[Tensor, float, None]) – Balancing coefficient used to multiply the budget term prior to its addition to the error component of the loss. If set to None, it will be set equal to the inference-error computed the first time the loss is computed

• steep_budget (bool) – If True, will use a linearly increasing budget term when the budget is exceeded, otherwise the budget term will flatten off for very high costs

• debug (bool) – If True, will print out information about the loss whenever it is evaluated

tomopt.optimisation.loss.sub_losses module

tomopt.optimisation.loss.sub_losses.integer_class_loss(int_probs, target_int, pred_start_int, use_mse, weight=None, reduction='mean')

Loss for classifying integers, when regression is not applicable. It assumed that the the integers really are quantifiably comparable, and not categorical codes of classes.

Like multiclass-classification, predictions are a probabilities for each possible integer, but the ICL aims to penalise close predictions less than far-off ones: For a target of 3 and a close prediction of softmax([1,3,10,5,5,3,1]) and a far-off prediction of softmax([10,3,1,5,5,3,1]), the categorical cross-entropy produces the same loss for both predictions (5.0154) despite the close prediction having a higher probability near the target.

ICL instead computes the absolute error, or squared error, between each of the possible integers and the true target. These errors are then normalised, weighted by the predicted probabilities, and summed. I.e. integers close to the target have a lower error, and these are given greater weight in the sum if they have a higher probability.

For the example, the ICL produces a loss of 1.0007 for the close prediction, and 8.8773 for the far-off one.

Parameters:

• int_probs (Tensor) – (*,integers) tensor of predicted probabilities

• target_int (Tensor) – (*) tensor of target integers

• pred_start_int (int) – the integer that the zeroth probability in predictions corresponds to

• use_mse (bool) – whether to compute errors as absolute or squared

• weight (Optional[Tensor]) – Optional (*) tensor of multiplicative weights for the unreduced ICLs

• reduction (str) – ‘mean’ return the average ICL, ‘sum’ sum the ICLs, ‘none’, return the individual ICLs

Return type:

Tensor