torchcell.losses.dcell.DCellLoss

class DCellLoss(alpha: float = 0.3, use_auxiliary_losses: bool = True, *, aux_reduction: Literal['sum', 'mean'])[source]

Bases: Module

Loss function for the DCell model (Ma et al. 2018).

The paper’s objective (mirror torchcell-library/maUsingDeepLearning2018/paper.md line 196, sha256 ac837bc358ea4969a72789e66e31380bfdcbd7b8aea98dec47b108ee21d2070c) is (1/N) sum_i (Loss(Linear(O_i^(r)), y_i) + alpha * sum_{t != r} Loss(Linear(O_i^(t)), y_i)) + lambda ||W||_2, and line 199 states: “Loss is the squared error loss function, and $r$ is the root of the hierarchy” and “the parameter $alpha$ $_ { ( = 0 . 3 ) }$ balances these two contributions”. This class computes the first two terms; the lambda ||W||_2 term is the optimizer’s weight decay (weight_decay in the 005/006 configs, 1e-6), and the mirror text gives no value for lambda (“determined by four-fold cross-validation”).

aux_reduction="sum" is the paper’s sum over every non-root subsystem. aux_reduction="mean" divides that sum by the number of counted subsystems, an effective alpha of 0.3 / (T - 1). There is no default: real runs exist under both regimes. Neither value reproduces the loss of the 005/006 runs made before 2026-09-30 through torchcell.trainers.int_dcell: those passed [B, 1] predictions and targets against [B] heads, so each auxiliary MSE broadcast over a [B, B] grid and the root head (GO:<root index>) was counted as an auxiliary term as well (issue #578 records the affected runs).

The root is recognized by its DECLARED key, never by value or object identity: outputs["root_key"] (DCell and DCellOpt set it to GO:<root index>) and the alias "GO:ROOT". A non-root head whose values equal the root is counted. Shapes must match the target exactly; nothing is broadcast.

Parameters:

  • alpha – Weight for auxiliary losses (default: 0.3, the paper’s value).

  • use_auxiliary_losses – Whether to use losses from non-root subsystems (default: True).

  • aux_reduction – "sum" (the paper) or "mean" over the non-root subsystem MSEs; required, keyword-only.

forward(predictions: Tensor, outputs: dict[str, Any], target: Tensor) → tuple[Tensor, dict[str, Tensor]][source]

Compute the loss for DCell outputs.

Parameters:

  • predictions – Primary predictions tensor from the model (root output)

  • outputs – Model outputs; linear_outputs maps term keys to head outputs and root_key names the root’s own key

  • target – Target values to predict, the same shape as predictions

Returns:

Tuple of (total_loss, loss_components) where loss_components is a dictionary containing the primary_loss, auxiliary_loss, and weighted_auxiliary_loss.

Raises:

ValueError – If a prediction or counted head differs in shape from the target, or linear_outputs is given without root_key.