Merge branch 'main' into chore/use-glm-5.2-in-opencode-action

Author: ValerianRey

CHANGELOG.md

@@ -8,12 +8,29 @@ changelog does not include internal changes that do not affect the user.
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-06-24
+
+### Added
+
+- Added `ExcessMTL` and `ExcessMTLWeighting` from [Robust Multi-Task Learning with Excess
+  Risks](https://proceedings.mlr.press/v235/he24n.html) (ICML 2024). `ExcessMTLWeighting` is a
+  stateful `Weighting` that maintains task weights across calls via an exponentiated gradient update
+  driven by per-task excess risk estimates. The excess risk is approximated using an AdaGrad-style
+  diagonal Hessian. An optional `n_warmup_steps` parameter controls how many forward calls collect
+  gradient statistics before weight updates begin.
+
+## [0.16.0] - 2026-06-22
+
 ### Added
 
 - Added `COSMOS` from [Scalable Pareto Front Approximation for Deep Multi-Objective
   Learning](https://arxiv.org/pdf/2103.13392) (ICDM 2021), a `Scalarizer` that combines a linear
   scalarization with a cosine-similarity penalty pulling the vector of values toward a preference
   direction.
+- Added `PBI` (Penalty-based Boundary Intersection) from [MOEA/D: A Multiobjective Evolutionary
+  Algorithm Based on Decomposition](https://ieeexplore.ieee.org/document/4358754) (IEEE TEVC 2007), a
+  `Scalarizer` that decomposes the values into a component along a preference direction and a
+  penalized perpendicular component.
 
 ## [0.15.0] - 2026-06-15
 

CONTRIBUTING.md

@@ -95,6 +95,13 @@ CC=gcc uv pip install --python-version=3.14 -e '.[full]' --group check --group d
 uv run pre-commit install
 ```
 
+## Working with agents
+
+We encourage contributors to use AI agents when contributing to TorchJD, but there are a few rules:
+- The initiative should come from a human. We do not want PRs from fully automated bots.
+- The changes should be reviewed by a human before a non-draft PR is open.
+- To avoid vendor lock-in, we do not provide any file that is specific to an agent vendor. To use a specific agent that does not follow open file naming conventions, you have to adapt a few things yourself (e.g. symlink files). For example, to work with claude, you have to symlink `CLAUDE.md` to `AGENTS.md`, and `.claude/skill/` to `skills/`.
+
 ## Checks
 
 ### Running tests
@@ -275,26 +282,3 @@ The three plot scripts produce PDFs saved to `tests/trajectories/results/<object
 > [!NOTE]
 > The plot scripts require a LaTeX installation for rendering:
 > `sudo apt-get install texlive-latex-extra texlive-fonts-recommended dvipng cm-super`
-
-
-## Release
-
-*This section is addressed to maintainers.*
-
-To release a new `torchjd` version, you have to:
-- If the release introduces changes to the interface, make sure that `README.md` reflects those
-  changes.
-- Make sure that all tests, including those on cuda, pass (for this, you need access to a machine
-  that has a cuda-enabled GPU).
-- Make sure that all important changes since the last release have been reported in the
-  `[Unreleased]` section at the top of the changelog.
-- Add a `[X.Y.Z] - yyyy-mm-dd` header in the changelog just below the `[Unreleased]` header.
-- Change the version in `pyproject.toml`.
-- Make a pull request with those changes and merge it.
-- Make a draft of the release on GitHub (click on `Releases`, then `Draft a new release`, then fill
-  the details).
-- Publish the release (click on  `Publish release`). This should trigger the deployment of the new
-  version on PyPI and the building and deployment of the documentation on github-pages.
-- Check that the new version is correctly deployed to PyPI, that it is installable and that it
-  works.
-- Check that the documentation has been correctly deployed.

NOTICES

@@ -143,6 +143,34 @@ SOFTWARE.
 
 -------------------------------------------------------------------------------
 
+Project: ExcessMTL
+Source: https://github.com/uiuctml/ExcessMTL/blob/main/LibMTL/LibMTL/weighting/ExcessMTL.py
+Used in: src/torchjd/aggregation/_excess_mtl.py
+
+MIT License
+
+Copyright (c) 2024 UIUC TML Lab
+
+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.
+
+-------------------------------------------------------------------------------
+
 Project: SDMGrad
 Source: https://github.com/OptMN-Lab/SDMGrad/blob/main/methods/weight_methods.py
 Used in: src/torchjd/aggregation/_sdmgrad.py

README.md

@@ -231,6 +231,7 @@ TorchJD provides many existing aggregators from the literature, listed in the fo
 | [Constant](https://torchjd.org/stable/docs/aggregation/constant#torchjd.aggregation.Constant)              | [ConstantWeighting](https://torchjd.org/stable/docs/aggregation/constant#torchjd.aggregation.ConstantWeighting)        | -                                                                                                                                                                    |
 | -                                                                                                           | [CRMOGMWeighting](https://torchjd.org/stable/docs/aggregation/cr_mogm/#torchjd.aggregation.CRMOGMWeighting)           | [On the Convergence of Stochastic Multi-Objective Gradient Manipulation and Beyond](https://proceedings.neurips.cc/paper_files/paper/2022/file/f91bd64a3620aad8e70a27ad9cb3ca57-Paper-Conference.pdf) |
 | [DualProj](https://torchjd.org/stable/docs/aggregation/dualproj#torchjd.aggregation.DualProj)              | [DualProjWeighting](https://torchjd.org/stable/docs/aggregation/dualproj#torchjd.aggregation.DualProjWeighting)        | [Gradient Episodic Memory for Continual Learning](https://arxiv.org/pdf/1706.08840)                                                                                  |
+| [ExcessMTL](https://torchjd.org/stable/docs/aggregation/excess_mtl#torchjd.aggregation.ExcessMTL)          | [ExcessMTLWeighting](https://torchjd.org/stable/docs/aggregation/excess_mtl#torchjd.aggregation.ExcessMTLWeighting)    | [Robust Multi-Task Learning with Excess Risks](https://proceedings.mlr.press/v235/he24n.html)                                                                        |
 | [FairGrad](https://torchjd.org/stable/docs/aggregation/fairgrad#torchjd.aggregation.FairGrad)              | [FairGradWeighting](https://torchjd.org/stable/docs/aggregation/fairgrad#torchjd.aggregation.FairGradWeighting)        | [Fair Resource Allocation in Multi-Task Learning](https://arxiv.org/pdf/2402.15638)                                                                                  |
 | [GradDrop](https://torchjd.org/stable/docs/aggregation/graddrop#torchjd.aggregation.GradDrop)              | -                                                                                                                      | [Just Pick a Sign: Optimizing Deep Multitask Models with Gradient Sign Dropout](https://arxiv.org/pdf/2010.06808)                                                    |
 | [GradVac](https://torchjd.org/stable/docs/aggregation/gradvac#torchjd.aggregation.GradVac)              | [GradVacWeighting](https://torchjd.org/stable/docs/aggregation/gradvac#torchjd.aggregation.GradVacWeighting)                                                                                                                      | [Gradient Vaccine: Investigating and Improving Multi-task Optimization in Massively Multilingual Models](https://arxiv.org/pdf/2010.05874)                                                    |

docs/source/docs/aggregation/excess_mtl.rst

@@ -0,0 +1,10 @@
+:hide-toc:
+
+ExcessMTL
+=========
+
+.. autoclass:: torchjd.aggregation.ExcessMTL
+    :members: __call__, reset
+
+.. autoclass:: torchjd.aggregation.ExcessMTLWeighting
+    :members: __call__, reset

docs/source/docs/aggregation/index.rst

@@ -30,6 +30,7 @@ Abstract base classes
     constant.rst
     cr_mogm.rst
     dualproj.rst
+    excess_mtl.rst
     fairgrad.rst
     graddrop.rst
     gradvac.rst

docs/source/docs/scalarization/index.rst

@@ -21,6 +21,7 @@ Abstract base class
     geometric_mean.rst
     imtl_l.rst
     mean.rst
+    pbi.rst
     random.rst
     stch.rst
     sum.rst

docs/source/docs/scalarization/pbi.rst

@@ -0,0 +1,7 @@
+:hide-toc:
+
+PBI
+===
+
+.. autoclass:: torchjd.scalarization.PBI
+    :members: __call__

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "torchjd"
-version = "0.15.0"
+version = "0.17.0"
 description = "Library for Jacobian Descent with PyTorch."
 readme = "README.md"
 authors = [

skills/check-release/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: check-release
+description: Verifies that a TorchJD release was published correctly by checking the docs site, installing from PyPI, and smoke-testing newly added classes. Use after a release has been merged and published.
+---
+
+# Check TorchJD Release
+
+This skill verifies that a release is live and correct after it has been published.
+
+**For agents:** invoke as `/check-release X.Y.Z` (e.g. `/check-release 0.16.0`).
+If no version is provided, read the current version from `pyproject.toml`.
+
+---
+
+## Instructions
+
+### Step 1: Determine the version
+
+Read `pyproject.toml` to find the `version` field under `[project]`. Use the version provided as
+an argument, or the one from `pyproject.toml` if none is given.
+
+### Step 2: Identify newly added classes
+
+Read `CHANGELOG.md` and find the `## [X.Y.Z]` section. Extract the names of any newly added
+public classes, functions, or methods listed under `### Added`. You will use these in later steps.
+
+### Step 3: Check the docs site
+
+Fetch `https://torchjd.org`.
+
+- Verify that the versions dropdown (or switcher) includes `vX.Y.Z` as an entry.
+- Verify that the `stable` entry is present.
+
+If the version entry is missing, report it and stop — the rest of the checks depend on the docs
+being live.
+
+### Step 4: Verify the new-version docs contain the newly added classes
+
+For each newly added class or function identified in Step 2, fetch its expected docs page under
+`https://torchjd.org/vX.Y.Z/`. Use the URL patterns from similar existing classes found in
+`README.md` or by browsing the stable docs (`https://torchjd.org/stable/`) to infer the correct
+path (e.g. `https://torchjd.org/vX.Y.Z/docs/aggregation`,
+`https://torchjd.org/vX.Y.Z/docs/scalarization`, etc.).
+
+Confirm that each new class/function name appears on the fetched page.
+
+### Step 5: Verify the stable docs also reflect the new version
+
+Fetch the same doc pages under `https://torchjd.org/stable/` and confirm the newly added
+classes/functions appear there too (i.e. `stable` points to the new release).
+
+### Step 6: Install torchjd from PyPI in a temp environment
+
+Run the following commands to create an isolated install:
+
+```bash
+cd /tmp && mkdir -p test_torchjd_install && cd test_torchjd_install
+uv venv && uv pip install torchjd
+```
+
+Verify the installed version matches X.Y.Z:
+
+```bash
+cd /tmp/test_torchjd_install && uv pip show torchjd
+```
+
+If the version is wrong, you may need to install with `--no-cache`.
+
+### Step 7: Smoke-test the newly added classes
+
+Write a minimal Python script `/tmp/test_torchjd_install/smoke_test.py` that:
+
+- Imports each newly added class or function by its fully-qualified name from `torchjd`.
+- Instantiates or calls each one with a minimal valid input (e.g. a small `torch.Tensor`, a dummy
+  preference vector, or no arguments if the class takes none).
+- Does NOT assert correctness of values — only that the code runs without raising an exception.
+
+Use the existing test suite under `tests/` or the docs pages fetched in Step 4 as a reference for
+correct import paths and minimal usage patterns.
+
+Run the script:
+
+```bash
+cd /tmp/test_torchjd_install && uv run python smoke_test.py
+```
+
+Report the result. If it crashes, show the traceback.
+
+### Step 8: Clean up
+
+```bash
+rm -rf /tmp/test_torchjd_install
+```
+
+### Step 9: Report
+
+Summarize what was verified:
+- Docs site: version dropdown ✓/✗, new-version page ✓/✗, stable page ✓/✗
+- PyPI install: version matches ✓/✗
+- Smoke test: each newly added class ✓/✗ (list them)
+
+If everything passes, the release is confirmed good. If anything failed, describe what needs
+attention.