dicee.losses.custom_losses

Alternative loss functions selectable via the loss_fn config option.

BaseKGE.__init__ (dicee/models/base_model.py) instantiates one of these in place of the framework’s default loss based on args["loss_fn"]; see that dispatch for the exact string values and which additional config options (label_smoothing_rate, label_relaxation_alpha) feed each one’s constructor.

Several of these declare a current_epoch parameter on forward so they can vary their behavior over training; BaseKGE.loss_function detects this once per model (self._loss_needs_epoch, set by inspecting self.loss.forward’s parameters) and forwards the current epoch only to losses that declare it.

Classes

DefaultBCELoss	Plain BCEWithLogitsLoss, selectable via loss_fn="BCELoss".
WeightedBCELoss	BCE weighted by each prediction's own confidence.
LabelSmoothingLoss	Fixed-rate label-smoothing loss, selectable via loss_fn="LS"
AdaptiveLabelSmoothingLoss	KL-divergence label smoothing with a smoothing factor that self-adjusts
LabelRelaxationLoss	Label relaxation loss, selectable via loss_fn="LRLoss".
AdaptiveLabelRelaxationLoss	LabelRelaxationLoss with an alpha that self-adjusts from
ConfidenceBasedAdaptiveLabelRelaxationLoss	LabelRelaxationLoss where alpha shrinks as the model's
CombinedLSandLR	Switches from LabelSmoothingLoss to LabelRelaxationLoss
CombinedAdaptiveLSandAdaptiveLR	Switches from AdaptiveLabelSmoothingLoss to
AggregatedLSandLR	Fixed 0.4/0.6 weighted average of LabelSmoothingLoss and
ACLS	Adaptive and Conditional Label Smoothing-style calibration loss,

Module Contents

class dicee.losses.custom_losses.DefaultBCELoss

Bases: torch.nn.Module

Plain BCEWithLogitsLoss, selectable via loss_fn="BCELoss".

Equivalent to the framework’s own default entity/relation-prediction loss (see BaseKGE.__init__); provided as an explicit loss_fn option for parity with the other choices in this module.

forward(pred, target)

class dicee.losses.custom_losses.WeightedBCELoss

Bases: torch.nn.Module

BCE weighted by each prediction’s own confidence.

Down-weights low-confidence predictions (sigmoid(pred) near 0.5) and up-weights confident ones, clamped to [0.5, 1.0]. Weights are detached, so they don’t receive gradients themselves. current_epoch is accepted for interface consistency with the other loss_fn options but is currently unused.

forward(pred, target, current_epoch)

class dicee.losses.custom_losses.LabelSmoothingLoss(smoothness_ratio=0.0)

Bases: torch.nn.Module

Fixed-rate label-smoothing loss, selectable via loss_fn="LS" (smoothness_ratio comes from the label_smoothing_rate config option).

Converts pred (logits) to log-probabilities and compares against a smoothed target distribution (mass smoothness_ratio redistributed uniformly over the non-target classes) via KL(pred || smoothed_target) — the same fixed-rate variant of AdaptiveLabelSmoothingLoss’s per-call smoothing, without the batch-to-batch adaptation.

This is independent of the (separately, correctly implemented) dataset-level smoothing controlled by the same label_smoothing_rate option (dicee/dataset_classes/_label_based.py, _negative_sampling.py), which bakes smoothing into the training targets regardless of loss_fn.

Parameters:

smoothness_ratio (float) – Fraction of probability mass redistributed from the target class(es) to the non-target classes; 0 recovers a KL-divergence loss with no smoothing.

smoothness_ratio = 0.0

forward(pred, target)

class dicee.losses.custom_losses.AdaptiveLabelSmoothingLoss(min_smoothing_factor=0.01, max_smoothing_factor=0.2, smoothing_factor_step=0.01, initial_smoothing_factor=0.1)

Bases: torch.nn.Module

KL-divergence label smoothing with a smoothing factor that self-adjusts from batch to batch, selectable via loss_fn="AdaptiveLabelSmoothingLoss".

Converts logits to log-probabilities and compares against a smoothed target distribution (mass smoothing_factor redistributed uniformly over the non-target classes) via KL(pred || smoothed_target). After each call, smoothing_factor moves one smoothing_factor_step toward max_smoothing_factor if the loss increased since the previous call, or toward min_smoothing_factor if it decreased — i.e. it backs off smoothing while the model is improving and leans into it when training stalls. current_epoch is accepted for interface consistency with the other loss_fn options but is currently unused.

This module is stateful (prev_loss, smoothing_factor persist across calls), so a fresh instance should be used per training run.

Parameters:

• min_smoothing_factor (float) – Lower bound the adaptive smoothing factor can decay to.

• max_smoothing_factor (float) – Upper bound the adaptive smoothing factor can grow to.

• smoothing_factor_step (float) – Adjustment applied to the smoothing factor after each call.

• initial_smoothing_factor (float) – Starting value before any adjustment has occurred.

min_smoothing_factor = 0.01

max_smoothing_factor = 0.2

smoothing_factor_step = 0.01

smoothing_factor = 0.1

prev_loss = None

eps = 1e-14

forward(logits, target, current_epoch)

class dicee.losses.custom_losses.LabelRelaxationLoss(alpha=0.0)

Bases: torch.nn.Module

Label relaxation loss, selectable via loss_fn="LRLoss".

Based on “From Label Smoothing to Label Relaxation” (Lienen & Hullermeier, AAAI 2021): instead of smoothing toward one fixed soft target, it constructs a credal set of distributions that assign at least 1 - alpha probability to the target class(es) and measures the KL divergence to the closest point in that set, rather than to a single fixed distribution. Predictions that are already confident enough (probability mass on the target above 1 - alpha) incur zero loss.

Parameters:

alpha (float) – Relaxation strength in [0, 1); 0 recovers ordinary cross-entropy-style behavior (no slack), larger values tolerate more probability mass elsewhere before penalizing.

alpha = 0.0

gz_threshold = 0.1

eps = 1e-14

forward(pred, target)

class dicee.losses.custom_losses.AdaptiveLabelRelaxationLoss(min_alpha=0.01, max_alpha=0.2, alpha_step=0.01, initial_alpha=0.1)

Bases: torch.nn.Module

LabelRelaxationLoss with an alpha that self-adjusts from batch to batch, selectable via loss_fn="AdaptiveLabelRelaxationLoss".

Computes the label-relaxation loss once under torch.no_grad() with the current alpha to decide the adjustment (grow toward max_alpha if the loss increased since the previous call, shrink toward min_alpha if it decreased), then recomputes the loss with the updated alpha for the actual gradient-carrying return value. Like AdaptiveLabelSmoothingLoss, this module is stateful (prev_loss, alpha persist across calls) - use a fresh instance per training run.

Parameters:

• min_alpha (float) – Lower bound the adaptive alpha can decay to.

• max_alpha (float) – Upper bound the adaptive alpha can grow to.

• alpha_step (float) – Adjustment applied to alpha after each call.

• initial_alpha (float) – Starting value before any adjustment has occurred.

min_alpha = 0.01

max_alpha = 0.2

alpha_step = 0.01

alpha = 0.1

prev_loss = None

eps = 1e-14

gz_threshold = 0.1

forward(pred, target)

class dicee.losses.custom_losses.ConfidenceBasedAdaptiveLabelRelaxationLoss(alpha=0.1)

Bases: torch.nn.Module

LabelRelaxationLoss where alpha shrinks as the model’s own average prediction confidence grows, selectable via loss_fn="ConfidenceBasedAdaptiveLabelRelaxationLoss".

Each call rescales alpha by (1 - mean(pred)) before computing the loss. Unlike AdaptiveLabelRelaxationLoss, this adjustment is one-directional and unbounded below: alpha only ever decays toward 0 as confidence rises, with no mechanism to grow back if confidence later drops. current_epoch is accepted for interface consistency with the other loss_fn options but is currently unused. Stateful (alpha persists and mutates across calls) - use a fresh instance per training run.

Parameters:

alpha (float) – Initial relaxation strength before any confidence-based decay.

alpha = 0.1

gz_threshold = 0.1

eps = 1e-14

forward(pred, target, current_epoch)

class dicee.losses.custom_losses.CombinedLSandLR(smoothness_ratio=0.0, alpha=0.0)

Bases: torch.nn.Module

Switches from LabelSmoothingLoss to LabelRelaxationLoss after epoch 20, selectable via loss_fn="CombinedLSandLR".

Intended to smooth early training then relax the target distribution later on.

Parameters:

• smoothness_ratio (float) – Forwarded to LabelSmoothingLoss for the first 20 epochs.

• alpha (float) – Forwarded to LabelRelaxationLoss from epoch 20 onward.

smoothness_ratio = 0.0

alpha = 0.0

forward(pred, target, current_epoch)

class dicee.losses.custom_losses.CombinedAdaptiveLSandAdaptiveLR

Bases: torch.nn.Module

Switches from AdaptiveLabelSmoothingLoss to AdaptiveLabelRelaxationLoss after epoch 100, selectable via loss_fn="CombinedAdaptiveLSandAdaptiveLR".

Both inner losses use their default hyperparameters; there is currently no way to configure them through this wrapper.

adaptive_label_smoothing

adaptive_label_relaxation

criterion = ''

forward(pred, target, current_epoch)

class dicee.losses.custom_losses.AggregatedLSandLR(smoothness_ratio=0.1, alpha=0.1)

Bases: torch.nn.Module

Fixed 0.4/0.6 weighted average of LabelSmoothingLoss and LabelRelaxationLoss, selectable via loss_fn="AggregatedLSandLR".

Unlike CombinedLSandLR, both terms are computed every call and blended (0.4 * smoothing + 0.6 * relaxation) rather than switched between by epoch.

Parameters:

• smoothness_ratio (float) – Forwarded to the inner LabelSmoothingLoss.

• alpha (float) – Forwarded to the inner LabelRelaxationLoss.

smoothness_ratio = 0.1

alpha = 0.1

forward(pred, target, current_epoch)

class dicee.losses.custom_losses.ACLS(pos_lambda: float = 1.0, neg_lambda: float = 0.1, alpha: float = 0.1, margin: float = 10.0, num_classes: int = 200, ignore_index: int = -100)

Bases: torch.nn.Module

Adaptive and Conditional Label Smoothing-style calibration loss, selectable via loss_fn="ACLS".

Adds a margin-based confidence regularizer to cross-entropy: for the predicted (argmax) class, logits above margin are penalized quadratically (discourages over-confidence on the top class), and for every other class, logits within margin of the top logit are also penalized quadratically (discourages under-separation from the runner-up classes). The two penalties are weighted by pos_lambda/neg_lambda and added to CrossEntropyLoss scaled by alpha.

Warning

nn.CrossEntropyLoss expects targets as class indices (or a proper probability distribution per row); KGE’s KvsAll labels are multi-hot (possibly several true tails per row), which is not an equivalent input. num_classes and ignore_index are currently unused in forward/get_reg.

Parameters:

• pos_lambda (float) – Weight of the over-confidence penalty on the predicted class.

• neg_lambda (float) – Weight of the under-separation penalty on the other classes.

• alpha (float) – Weight of the regularization term relative to cross-entropy.

• margin (float) – Logit margin used by both penalty terms.

• num_classes (int) – Currently unused.

• ignore_index (int) – Currently unused.

pos_lambda = 1.0

neg_lambda = 0.1

alpha = 0.1

margin = 10.0

num_classes = 200

ignore_index = -100

cross_entropy

property names

get_reg(inputs, targets)

forward(inputs, targets)