pytorch-fairloss 0.1.1__tar.gz

pytorch_fairloss-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/* --verbose

pytorch_fairloss-0.1.1/.gitignore

@@ -0,0 +1,12 @@
+data/
+*.pth
+__pycache__/
+*.py[cod]
+*$py.class
+.DS_Store
+.vscode/
+
+dist/
+build/
+*.egg-info/
+.eggs/

pytorch_fairloss-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aref
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytorch_fairloss-0.1.1/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: pytorch-fairloss
+Version: 0.1.1
+Summary: PyTorch classification loss with a SmoothMax-based calibration penalty
+Project-URL: Homepage, https://github.com/stormaref/FairLoss
+Project-URL: Repository, https://github.com/stormaref/FairLoss
+Project-URL: Issues, https://github.com/stormaref/FairLoss/issues
+Author-email: Aref <storm.aref@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calibration,classification,loss,pytorch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FairLoss
+
+PyTorch classification loss that combines cross-entropy with a smooth argmax penalty. Inspired by **Penalized Logarithmic Loss (PLL)** from Ahmadian et al. (2025).
+
+## The problem
+
+In multi-class classification, we often want losses to rank **correct** predictions above **incorrect** ones. Strictly proper scores such as cross-entropy encourage calibrated probabilities, but they do not always do that.
+
+Consider two logits with true class `0`:
+
+| Sample | Logits               | True class | Argmax correct? |
+| ------ | -------------------- | ---------- | --------------- |
+| 1      | `[0.34, 0.33, 0.33]` | 0          | Yes             |
+| 2      | `[0.49, 0.51, 0.00]` | 0          | No              |
+
+Sample 2 assigns a **higher logit to the true class** but picks the **wrong label**. Cross-entropy prefers sample 2; intuitively, sample 1 should win.
+
+Ahmadian et al. call this the **Superior** property: a scoring rule should always rank correct predictions above incorrect ones. PLL adds a hard argmax penalty while staying strictly proper. FairLoss applies the same idea with a differentiable penalty suitable for gradient-based training.
+
+Running [`examples/difference.py`](examples/difference.py) on these logits:
+
+```
+Cross-entropy:  tensor([1.0920, 0.9681])   # sample 2 wins
+FairLoss:       tensor([1.0920, 1.3014])   # sample 1 wins
+```
+
+Cross-entropy gives sample 2 the lower loss because it is more confident on the true class. FairLoss adds a penalty when the argmax is wrong, so sample 1 ends up with the lower loss. Sample 1 keeps the same loss under both criteria because its prediction is already correct.
+
+## How it works
+
+FairLoss keeps standard cross-entropy and adds a SmoothMax-based penalty:
+
+```
+total_loss = cross_entropy + penalty
+```
+
+The penalty is built from the gap between the true-class logit and a smooth approximation of the largest logit:
+
+1. **SmoothMax** approximates `max(logits)` — the predicted class.
+2. **`logit_true - smooth_max`** is near zero when the argmax is correct, negative when it is wrong.
+3. A **sigmoid transform** maps that gap into a smooth penalty: near zero for correct predictions, positive for incorrect ones.
+
+Full derivation: [`formulation.pdf`](formulation.pdf)
+
+## Install
+
+```bash
+pip install pytorch-fairloss
+```
+
+Import as `from fairloss import FairLoss` (the PyPI name differs from the import path).
+
+Or install from source:
+
+```bash
+pip install git+https://github.com/stormaref/FairLoss.git
+```
+
+## Quick start
+
+```python
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from fairloss import FairLoss
+
+model = nn.Linear(784, 10)
+criterion = FairLoss()
+optimizer = optim.Adam(model.parameters(), lr=1e-3)
+
+x = torch.randn(64, 784)
+y = torch.randint(0, 10, (64,))
+
+logits = model(x)
+loss = criterion(logits, y)
+
+optimizer.zero_grad()
+loss.backward()
+optimizer.step()
+```
+
+See [`examples/basic_usage.py`](examples/basic_usage.py) for a training loop and [`examples/difference.py`](examples/difference.py) for the cross-entropy comparison above.
+
+## API
+
+### `FairLoss(cross_entropy=None, smooth_max_beta=1000.0, scaling_factor=1000.0, reduction="mean")`
+
+Wraps a `nn.CrossEntropyLoss` and adds the FairLoss penalty on top.
+
+| Parameter         | Description                                                                 |
+| ----------------- | --------------------------------------------------------------------------- |
+| `cross_entropy`   | Optional `nn.CrossEntropyLoss` with `reduction="none"`. Defaults to `nn.CrossEntropyLoss(reduction="none")`. Pass a custom instance to set `weight`, `label_smoothing`, `ignore_index`, etc. |
+| `smooth_max_beta` | Temperature for the smooth maximum approximation over logits.               |
+| `scaling_factor`  | Scale applied before the sigmoid penalty transform.                         |
+| `reduction`       | Reduction applied to the combined loss: `"mean"`, `"sum"`, or `"none"`. Default: `"mean"`. |
+
+**Forward pass**
+
+- `output`: Logits tensor of shape `(N, C)` where `N` is batch size and `C` is number of classes.
+- `target`: Integer class labels of shape `(N,)`.
+- **Returns**: Scalar mean loss over the batch (or per-sample losses when `reduction="none"`).
+
+## Requirements
+
+- Python 3.9+
+- PyTorch 2.0+
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Reference
+
+Ahmadian, R., Ghatee, M., & Wahlström, J. (2025). Superior scoring rules for probabilistic evaluation of single-label multi-class classification tasks. _International Journal of Approximate Reasoning_, 182, 109421. [https://doi.org/10.1016/j.ijar.2025.109421](https://doi.org/10.1016/j.ijar.2025.109421)
+
+Preprint: [arXiv:2407.17697](https://arxiv.org/abs/2407.17697)
+
+GitHub: https://github.com/stormaref/FairLoss

pytorch_fairloss-0.1.1/README.md

@@ -0,0 +1,118 @@
+# FairLoss
+
+PyTorch classification loss that combines cross-entropy with a smooth argmax penalty. Inspired by **Penalized Logarithmic Loss (PLL)** from Ahmadian et al. (2025).
+
+## The problem
+
+In multi-class classification, we often want losses to rank **correct** predictions above **incorrect** ones. Strictly proper scores such as cross-entropy encourage calibrated probabilities, but they do not always do that.
+
+Consider two logits with true class `0`:
+
+| Sample | Logits               | True class | Argmax correct? |
+| ------ | -------------------- | ---------- | --------------- |
+| 1      | `[0.34, 0.33, 0.33]` | 0          | Yes             |
+| 2      | `[0.49, 0.51, 0.00]` | 0          | No              |
+
+Sample 2 assigns a **higher logit to the true class** but picks the **wrong label**. Cross-entropy prefers sample 2; intuitively, sample 1 should win.
+
+Ahmadian et al. call this the **Superior** property: a scoring rule should always rank correct predictions above incorrect ones. PLL adds a hard argmax penalty while staying strictly proper. FairLoss applies the same idea with a differentiable penalty suitable for gradient-based training.
+
+Running [`examples/difference.py`](examples/difference.py) on these logits:
+
+```
+Cross-entropy:  tensor([1.0920, 0.9681])   # sample 2 wins
+FairLoss:       tensor([1.0920, 1.3014])   # sample 1 wins
+```
+
+Cross-entropy gives sample 2 the lower loss because it is more confident on the true class. FairLoss adds a penalty when the argmax is wrong, so sample 1 ends up with the lower loss. Sample 1 keeps the same loss under both criteria because its prediction is already correct.
+
+## How it works
+
+FairLoss keeps standard cross-entropy and adds a SmoothMax-based penalty:
+
+```
+total_loss = cross_entropy + penalty
+```
+
+The penalty is built from the gap between the true-class logit and a smooth approximation of the largest logit:
+
+1. **SmoothMax** approximates `max(logits)` — the predicted class.
+2. **`logit_true - smooth_max`** is near zero when the argmax is correct, negative when it is wrong.
+3. A **sigmoid transform** maps that gap into a smooth penalty: near zero for correct predictions, positive for incorrect ones.
+
+Full derivation: [`formulation.pdf`](formulation.pdf)
+
+## Install
+
+```bash
+pip install pytorch-fairloss
+```
+
+Import as `from fairloss import FairLoss` (the PyPI name differs from the import path).
+
+Or install from source:
+
+```bash
+pip install git+https://github.com/stormaref/FairLoss.git
+```
+
+## Quick start
+
+```python
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from fairloss import FairLoss
+
+model = nn.Linear(784, 10)
+criterion = FairLoss()
+optimizer = optim.Adam(model.parameters(), lr=1e-3)
+
+x = torch.randn(64, 784)
+y = torch.randint(0, 10, (64,))
+
+logits = model(x)
+loss = criterion(logits, y)
+
+optimizer.zero_grad()
+loss.backward()
+optimizer.step()
+```
+
+See [`examples/basic_usage.py`](examples/basic_usage.py) for a training loop and [`examples/difference.py`](examples/difference.py) for the cross-entropy comparison above.
+
+## API
+
+### `FairLoss(cross_entropy=None, smooth_max_beta=1000.0, scaling_factor=1000.0, reduction="mean")`
+
+Wraps a `nn.CrossEntropyLoss` and adds the FairLoss penalty on top.
+
+| Parameter         | Description                                                                 |
+| ----------------- | --------------------------------------------------------------------------- |
+| `cross_entropy`   | Optional `nn.CrossEntropyLoss` with `reduction="none"`. Defaults to `nn.CrossEntropyLoss(reduction="none")`. Pass a custom instance to set `weight`, `label_smoothing`, `ignore_index`, etc. |
+| `smooth_max_beta` | Temperature for the smooth maximum approximation over logits.               |
+| `scaling_factor`  | Scale applied before the sigmoid penalty transform.                         |
+| `reduction`       | Reduction applied to the combined loss: `"mean"`, `"sum"`, or `"none"`. Default: `"mean"`. |
+
+**Forward pass**
+
+- `output`: Logits tensor of shape `(N, C)` where `N` is batch size and `C` is number of classes.
+- `target`: Integer class labels of shape `(N,)`.
+- **Returns**: Scalar mean loss over the batch (or per-sample losses when `reduction="none"`).
+
+## Requirements
+
+- Python 3.9+
+- PyTorch 2.0+
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Reference
+
+Ahmadian, R., Ghatee, M., & Wahlström, J. (2025). Superior scoring rules for probabilistic evaluation of single-label multi-class classification tasks. _International Journal of Approximate Reasoning_, 182, 109421. [https://doi.org/10.1016/j.ijar.2025.109421](https://doi.org/10.1016/j.ijar.2025.109421)
+
+Preprint: [arXiv:2407.17697](https://arxiv.org/abs/2407.17697)
+
+GitHub: https://github.com/stormaref/FairLoss

pytorch_fairloss-0.1.1/examples/basic_usage.py

@@ -0,0 +1,30 @@
+"""Minimal example: train a linear classifier with FairLoss."""
+
+import torch
+import torch.nn as nn
+import torch.optim as optim
+
+from fairloss import FairLoss
+
+
+def main():
+    model = nn.Linear(784, 10)
+    criterion = FairLoss()
+    optimizer = optim.Adam(model.parameters(), lr=1e-3)
+
+    for step in range(3):
+        x = torch.randn(64, 784)
+        y = torch.randint(0, 10, (64,))
+
+        logits = model(x)
+        loss = criterion(logits, y)
+
+        optimizer.zero_grad()
+        loss.backward()
+        optimizer.step()
+
+        print(f"step={step + 1} loss={loss.item():.4f}")
+
+
+if __name__ == "__main__":
+    main()

pytorch_fairloss-0.1.1/examples/difference.py

@@ -0,0 +1,16 @@
+import torch
+import torch.nn as nn
+from fairloss import FairLoss
+
+output = torch.tensor(
+    [[0.34, 0.33, 0.33], [0.49, 0.51, 0.0]], dtype=torch.float32)
+target = torch.tensor([0, 0], dtype=torch.long)
+
+cross_entropy_fn = nn.CrossEntropyLoss(reduction="none")
+fair_loss_fn = FairLoss(reduction="none")
+
+cross_entropy = cross_entropy_fn(output, target)
+fair_loss = fair_loss_fn(output, target)
+
+print(f"Cross-entropy:  {cross_entropy}")
+print(f"FairLoss:       {fair_loss}")

pytorch_fairloss-0.1.1/fairloss/__init__.py

@@ -0,0 +1,4 @@
+from fairloss.loss import FairLoss
+
+__all__ = ["FairLoss"]
+__version__ = "0.1.1"

pytorch_fairloss-0.1.1/fairloss/loss.py

@@ -0,0 +1,83 @@
+from typing import Literal, Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class FairLoss(nn.Module):
+    """Classification loss combining cross-entropy with a SmoothMax-based penalty.
+
+    Args:
+        cross_entropy: Cross-entropy loss with ``reduction="none"``. Defaults to
+            ``nn.CrossEntropyLoss(reduction="none")``.
+        smooth_max_beta: Temperature for the smooth maximum approximation.
+        scaling_factor: Scale applied before the sigmoid penalty transform.
+        reduction: Reduction applied to the combined loss.
+
+    Forward:
+        output: Logits of shape (N, C).
+        target: Integer class labels of shape (N,).
+        Returns: Scalar mean loss over the batch.
+    """
+
+    def __init__(
+        self,
+        cross_entropy: Optional[nn.CrossEntropyLoss] = None,
+        smooth_max_beta: float = 1000.0,
+        scaling_factor: float = 1000.0,
+        reduction: Literal["mean", "none", "sum"] = "mean",
+    ):
+        super().__init__()
+        if cross_entropy is None:
+            cross_entropy = nn.CrossEntropyLoss(reduction="none")
+
+        if not isinstance(cross_entropy, nn.CrossEntropyLoss):
+            raise TypeError(
+                "cross_entropy must be an instance of nn.CrossEntropyLoss, "
+                f"got {type(cross_entropy).__name__}."
+            )
+        if cross_entropy.reduction != "none":
+            raise ValueError(
+                'cross_entropy must use reduction="none" so FairLoss can add the '
+                f"penalty per sample before applying its own reduction, got "
+                f'reduction="{cross_entropy.reduction}".'
+            )
+
+        self.cross_entropy = cross_entropy
+        self.smooth_max_beta = smooth_max_beta
+        self.scaling_factor = scaling_factor
+        self.reduction = reduction
+
+    def one_hot_encode(self, target: torch.Tensor, num_classes: int) -> torch.Tensor:
+        target = target.long()
+        return F.one_hot(target, num_classes=num_classes).float()
+
+    def forward(self, output: torch.Tensor, target: torch.Tensor) -> torch.Tensor:
+        num_classes = output.shape[1]
+        base_loss = self.cross_entropy(output, target)
+
+        target = self.one_hot_encode(target, num_classes)
+        smooth_max = (1.0 / self.smooth_max_beta) * torch.logsumexp(
+            self.smooth_max_beta * output, dim=1, keepdim=False
+        )
+
+        result = output - smooth_max.unsqueeze(1)
+        element_wise_mult = result * target
+
+        ones_vector = torch.ones(num_classes, 1, device=output.device)
+        final_scalar = torch.matmul(element_wise_mult, ones_vector)
+
+        sigmoid_output = torch.sigmoid(self.scaling_factor * -1 * final_scalar)
+        final_output = (sigmoid_output - 0.5) * 2
+        final_output = final_output.squeeze(1)
+
+        penalty = final_output / num_classes
+        total_loss = base_loss + penalty
+
+        if self.reduction == "mean":
+            return total_loss.mean()
+        if self.reduction == "sum":
+            return total_loss.sum()
+
+        return total_loss

pytorch_fairloss-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pytorch-fairloss"
+version = "0.1.1"
+description = "PyTorch classification loss with a SmoothMax-based calibration penalty"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["classification", "loss", "pytorch", "calibration"]
+authors = [
+    { name = "Aref", email = "storm.aref@gmail.com" },
+]
+dependencies = [
+    "torch>=2.0",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/stormaref/FairLoss"
+Repository = "https://github.com/stormaref/FairLoss"
+Issues = "https://github.com/stormaref/FairLoss/issues"
+
+[project.optional-dependencies]
+dev = ["build", "twine", "pytest"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["fairloss"]