# bce_with_logits

Python API: `luxonis_train.attached_modules.losses.bce_with_logits`

Binary cross entropy over raw logits.

## Classes

### BCEWithLogitsLoss

Binary cross entropy on logits, with the sigmoid inside the loss.

The loss combines the sigmoid and the binary cross entropy in one step. This is more numerically stable than a `Sigmoid` layer
followed by `BCELoss`, because the combined step uses the log-sum-exp trick.

 * `Inputs:`: * `predictions` (`Tensor`): `[B, C, ...]` logits
    * `target` (`Tensor`): same shape, float values in `[0, 1]`
 * `Outputs:`: * `Tensor`: scalar, or `[B, C, ...]` when `reduction` is `"none"`
 * `Formula:`: For a logit x, its target y, and the sigmoid σ, the loss of one element is ℓ = − w[p ylogσ(x) + (1 − y)log(1 −
   σ(x))] Here w comes from `weight` and p from `pos_weight`. Both are `1` when they are not set. `reduction` then takes the mean
   or the sum over all elements, or keeps the loss of each element.

> **References**
> * Source: Wraps [torch.nn.BCEWithLogitsLoss](https://docs.pytorch.org/docs/stable/generated/torch.nn.BCEWithLogitsLoss.html) (BSD-3-Clause).
 * License: Apache-2.0 (this project)

> **Notes**
> The class wraps `nn.BCEWithLogitsLoss`. [forward](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/bce_with_logits.md) compares the shapes of the two tensors first and raises `RuntimeError` when they differ.

> **Example**
> Attached to a `DDRNetSegmentationHead` in `model.nodes`:

```yaml
- name: DDRNetSegmentationHead
  inputs: [DDRNet]
  losses:
    - name: BCEWithLogitsLoss
```

 * `Compatible with:`: * Nodes: *
   [BiSeNetHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/bisenet_head.md)
       * [ClassificationHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/classification_head.md)
       * [DDRNetSegmentationHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ddrnet_segmentation_head.md)
       * [SegmentationHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/segmentation_head.md)
       * [TransformerClassificationHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_classification_head.md)
       * [TransformerSegmentationHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/transformer_segmentation_head.md)

#### Methods

##### init

```python
def __init__(weight: list[float] | None = None, reduction: Literal['none', 'mean', 'sum'] = 'mean', pos_weight: Tensor | None = None, **kwargs):
```

Initialize the loss and the wrapped `nn.BCEWithLogitsLoss`.

Parameters

 * `weight` (`list[float] | None`): Factors for the loss of the elements. The list becomes a tensor that broadcasts against the
   loss of shape `[B, C, ...]`, aligned at the last dimension. For a target of shape `[B, C]`, a list of `C` values gives one
   factor to each class. For a target of shape `[B, C, H, W]`, the list aligns with `W`, not with the classes. `None` gives every
   element the factor `1`.
 * `reduction` (`Literal['none', 'mean', 'sum']`): How to reduce the loss of the elements: * `"none"`: return the loss of each
   element.
    * `"mean"`: return the mean over all elements.
    * `"sum"`: return the sum over all elements.
 * `pos_weight` (`Tensor | None`): Factors for the positive term of the loss. The tensor broadcasts against the target, aligned at
   the last dimension. For a target of shape `[B, C, H, W]`, a tensor of shape `[C, 1, 1]` gives one factor to each class. `None`
   gives the factor `1`. A list raises `TypeError`.
 * `**kwargs`: Keyword arguments forwarded to
   [BaseLoss](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/base_loss.md),
   such as `final_loss_weight` and `node`.

##### forward

```python
def forward(predictions: Tensor, target: Tensor) -> Tensor:
```

Compute the binary cross entropy between logits and targets.

> **Examples**
> A confident correct logit gives a small loss, and a confident wrong logit gives a large loss:

```pycon
>>> import torch
>>> loss = BCEWithLogitsLoss(reduction="none")
>>> logits = torch.tensor([[2.0, -2.0]])
>>> target = torch.tensor([[1.0, 1.0]])
>>> values = loss(logits, target)[0].tolist()
>>> [round(value, 4) for value in values]
[0.1269, 2.1269]
```

The target must have the shape of the logits:

```pycon
>>> BCEWithLogitsLoss()(logits, torch.tensor([1.0, 1.0]))
Traceback (most recent call last):
    ...
RuntimeError: Target tensor dimension (torch.Size([2])) and preds tensor dimension (torch.Size([1, 2])) should be the same.
```

Parameters

 * `predictions` (`Tensor`): Logits of shape `[B, C, ...]`, the main output of the node.
 * `target` (`Tensor`): Float targets in `[0, 1]`, of the same shape as `predictions`. The `classification` label has the shape
   `[B, C]`, and the `segmentation` label has the shape `[B, C, H, W]`.

Returns

 * `Tensor`: A scalar for the `"mean"` and `"sum"` reductions. For `"none"`, the loss of each element, of shape `[B, C, ...]`.

Raises

 * `RuntimeError`: When `predictions` and `target` have different shapes.

#### Attributes

##### criterion

##### supported_tasks