refactor!: Make QuadprogProjector dependencies optional (#683)

* `quadprog`, `qpsolvers`, and `numpy` are moved from core to optional
dependencies
* New `quadprog_projector` extra groups them together, enabling `UPGrad`
and `DualProj` via `QuadprogProjector`
* `numpy` is also added to the `cagrad` and `nash_mtl` extras (and their
`_REQUIRED_DEPS` lists), and to the `plot` dev dependency group
* `_WithOptionalDeps` is moved from `torchjd.aggregation._mixins` to
`torchjd._mixins` so it can be reused by `QuadprogProjector` in
`torchjd._linalg`
* The standard install command in the README is updated to `pip install
"torchjd[quadprog_projector]"` so users following the README have
`UPGrad` and `DualProj` available out of the box
* Add changelog entry
* Update many tests to skip them / change aggregator depending on
aggregator availability

Author: ValerianRey

CHANGELOG.md

@@ -8,6 +8,14 @@ changelog does not include internal changes that do not affect the user.
 
 ## [Unreleased]
 
+### Changed
+
+- **BREAKING**: Removed `numpy`, `quadprog` and `qpsolvers` from the main dependencies of `torchjd`,
+  (which now only has `torch` as its main dependency). This makes the base version of `torchjd`
+  (installed with `pip install torchjd`) much lighter, but it means that users of `UPGrad` and
+  `DualProj` now have to install the new optional dependency group `quadprog_projector` explicitly
+  (with e.g. `pip install "torchjd[quadprog_projector]"`).
+
 ## [0.11.0] - 2026-05-18
 
 ### Changed

README.md

@@ -55,10 +55,11 @@ size). In addition to $\mathcal A_{\text{UPGrad}}$, TorchJD supports
 <!-- start installation -->
 TorchJD can be installed directly with pip:
 ```bash
-pip install torchjd
+pip install "torchjd[quadprog_projector]"
 ```
 <!-- end installation -->
-Some aggregators may have additional dependencies. Please refer to the
+This includes the dependencies required by UPGrad and DualProj. Some other aggregators may have
+additional dependencies. Please refer to the
 [installation documentation](https://torchjd.org/stable/installation) for them.
 
 ## Usage

docs/source/installation.md

@@ -7,14 +7,14 @@
 
 Note that `torchjd` requires Python 3.10, 3.11, 3.12, 3.13 or 3.14 and `torch>=2.0`.
 
-Some aggregators (CAGrad and Nash-MTL) have additional dependencies that are not included by default
-when installing `torchjd`. To install them, you can use:
-```
-pip install "torchjd[cagrad]"
-```
-```
-pip install "torchjd[nash_mtl]"
-```
+Some aggregators have additional dependencies that are not included by default when installing
+`torchjd`. The following table lists the optional dependency groups and the aggregators they enable:
+
+Group | Classes | Dependencies | Install command |
+|-----|---------|--------------|-----------------|
+| `quadprog_projector` | {class}`~torchjd.linalg.QuadprogProjector` (used in {class}`~torchjd.aggregation.UPGrad` and {class}`~torchjd.aggregation.DualProj`) | [numpy](https://github.com/numpy/numpy), [quadprog](https://github.com/quadprog/quadprog), [qpsolvers](https://github.com/qpsolvers/qpsolvers) | `pip install "torchjd[quadprog_projector]"` |
+| `cagrad` | {class}`~torchjd.aggregation.CAGrad` | [numpy](https://github.com/numpy/numpy), [cvxpy](https://github.com/cvxpy/cvxpy/) | `pip install "torchjd[cagrad]"` |
+| `nash_mtl` | {class}`~torchjd.aggregation.NashMTL` | [numpy](https://github.com/numpy/numpy), [cvxpy](https://github.com/cvxpy/cvxpy/), [ecos](https://github.com/embotech/ecos) | `pip install "torchjd[nash_mtl]"` |
 
 To install `torchjd` with all of its optional dependencies, you can also use:
 ```

pyproject.toml

@@ -15,9 +15,6 @@ authors = [
 requires-python = ">=3.10"
 dependencies = [
     "torch>=2.3.0",  # Problems before 2.4.0, especially with autogram.
-    "quadprog>=0.1.9, != 0.1.10",  # Doesn't work before 0.1.9, 0.1.10 is yanked
-    "numpy>=1.21.2",  # Does not work before 1.21. No python 3.10 wheel before 1.21.2.
-    "qpsolvers>=1.0.1",  # Does not work before 1.0.1
 ]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -93,11 +90,13 @@ test = [
 ]
 
 plot = [
+    "numpy>=1.21.2",  # Does not work before 1.21. No python 3.10 wheel before 1.21.2.
     "plotly[kaleido]>=5.19.0",  # Recent version to avoid problems, could be relaxed
     "dash>=2.16.0",  # Recent version to avoid problems, could be relaxed
     "matplotlib>=3.10.0",  # Recent version to avoid problems, could be relaxed
 ]
-# Dependency group allowing to easily resolve version of the core dependencies to the lower bound.
+# Dependency group allowing to easily resolve version of the recommended dependencies to the lower
+# bound.
 lower_bounds = [
     "torch==2.3.0",
     "numpy==1.21.2",
@@ -106,14 +105,24 @@ lower_bounds = [
 ]
 
 [project.optional-dependencies]
+quadprog_projector = [
+    "numpy>=1.21.2",  # Does not work before 1.21. No python 3.10 wheel before 1.21.2.
+    "quadprog>=0.1.9, != 0.1.10",  # Doesn't work before 0.1.9, 0.1.10 is yanked
+    "qpsolvers>=1.0.1",  # Does not work before 1.0.1
+]
 nash_mtl = [
+    "numpy>=1.21.2",  # Does not work before 1.21. No python 3.10 wheel before 1.21.2.
     "cvxpy>=1.3.0",  # Could be relaxed
     "ecos>=2.0.14",  # Does not work before 2.0.14
 ]
 cagrad = [
+    "numpy>=1.21.2",  # Does not work before 1.21. No python 3.10 wheel before 1.21.2.
     "cvxpy>=1.3.0",  # No Clarabel solver before 1.3.0
 ]
 full = [
+    "numpy>=1.21.2",  # Does not work before 1.21. No python 3.10 wheel before 1.21.2.
+    "quadprog>=0.1.9, != 0.1.10",  # Doesn't work before 0.1.9, 0.1.10 is yanked
+    "qpsolvers>=1.0.1",  # Does not work before 1.0.1
     "cvxpy>=1.3.0",  # No Clarabel solver before 1.3.0
     "ecos>=2.0.14",  # Does not work before 2.0.14
 ]

src/torchjd/_linalg/_dual_cone.py

@@ -1,10 +1,15 @@
+import contextlib
 from abc import ABC, abstractmethod
 
-import numpy as np
 import torch
-from qpsolvers import solve_qp
 from torch import Tensor
 
+from torchjd._mixins import _WithOptionalDeps
+
+with contextlib.suppress(ImportError):
+    import numpy as np
+    from qpsolvers import solve_qp
+
 from ._gramian import normalize, regularize
 from ._matrix import PSDMatrix
 
@@ -49,7 +54,7 @@ def projector_or_default(projector: DualConeProjector | None) -> DualConeProject
     return projector
 
 
-class QuadprogProjector(DualConeProjector):
+class QuadprogProjector(_WithOptionalDeps, DualConeProjector):
     r"""
     Solves the quadratic program defined in :meth:`DualConeProjector.__call__` using the
     `quadprog <https://github.com/quadprog/quadprog>`_ QP solver.
@@ -61,12 +66,16 @@ class QuadprogProjector(DualConeProjector):
         ensures that it is positive definite.
     """
 
+    _REQUIRED_DEPS = ["numpy", "qpsolvers", "quadprog"]
+    _INSTALL_HINT = 'Install them with: pip install "torchjd[quadprog_projector]"'
+
     def __init__(
         self,
         *,
         norm_eps: float = 0.0001,
         reg_eps: float = 0.0001,
     ) -> None:
+        super().__init__()
         self._norm_eps = norm_eps
         self._reg_eps = reg_eps
 

src/torchjd/_mixins.py

@@ -0,0 +1,28 @@
+from importlib.util import find_spec
+from typing import Any
+
+
+class _WithOptionalDeps:
+    """
+    Mixin that raises :class:`ImportError` at instantiation time if required optional dependencies
+    are not installed.
+
+    Subclasses must define :attr:`_REQUIRED_DEPS` (list of package names to check via
+    :func:`importlib.util.find_spec`) and :attr:`_INSTALL_HINT` (appended to the error message).
+
+    .. warning::
+        This mixin must appear **first** in the inheritance list so that its :meth:`__init__`
+        runs before any base class that uses the optional dependencies.
+    """
+
+    _REQUIRED_DEPS: list[str]
+    _INSTALL_HINT: str
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        missing = [name for name in self._REQUIRED_DEPS if find_spec(name) is None]
+        if len(missing) != 0:
+            raise ImportError(
+                f"{self.__class__.__name__} requires {missing} to be installed. "
+                f"{self._INSTALL_HINT}"
+            )
+        super().__init__(*args, **kwargs)

src/torchjd/aggregation/_cagrad.py

@@ -1,24 +1,25 @@
 import contextlib
 from typing import cast
 
-import numpy as np
 import torch
 from torch import Tensor
 
 from torchjd._linalg import normalize
+from torchjd._mixins import _WithOptionalDeps
 from torchjd.linalg import PSDMatrix
 
 from ._aggregator_bases import GramianWeightedAggregator
-from ._mixins import _NonDifferentiable, _WithOptionalDeps
+from ._mixins import _NonDifferentiable
 from ._weighting_bases import _GramianWeighting
 
 with contextlib.suppress(ImportError):
     import cvxpy as cp
+    import numpy as np
 
 
 # Non-differentiable: the cvxpy solver operates on numpy arrays, breaking the autograd graph.
 class CAGradWeighting(_WithOptionalDeps, _NonDifferentiable, _GramianWeighting):
-    _REQUIRED_DEPS = ["cvxpy", "clarabel"]
+    _REQUIRED_DEPS = ["numpy", "cvxpy", "clarabel"]
     _INSTALL_HINT = 'Install them with: pip install "torchjd[cagrad]"'
     """
     :class:`~torchjd.aggregation.Weighting` [:class:`~torchjd.linalg.PSDMatrix`]

src/torchjd/aggregation/_mixins.py

@@ -1,37 +1,10 @@
 from abc import ABC, abstractmethod
-from importlib.util import find_spec
 from typing import Any
 
 import torch
 from torch import nn
 
 
-class _WithOptionalDeps:
-    """
-    Mixin that raises :class:`ImportError` at instantiation time if required optional dependencies
-    are not installed.
-
-    Subclasses must define :attr:`_REQUIRED_DEPS` (list of package names to check via
-    :func:`importlib.util.find_spec`) and :attr:`_INSTALL_HINT` (appended to the error message).
-
-    .. warning::
-        This mixin must appear **first** in the inheritance list so that its :meth:`__init__`
-        runs before any base class that uses the optional dependencies.
-    """
-
-    _REQUIRED_DEPS: list[str]
-    _INSTALL_HINT: str
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        missing = [name for name in self._REQUIRED_DEPS if find_spec(name) is None]
-        if len(missing) != 0:
-            raise ImportError(
-                f"{self.__class__.__name__} requires {missing} to be installed. "
-                f"{self._INSTALL_HINT}"
-            )
-        super().__init__(*args, **kwargs)
-
-
 class Stateful(ABC):
     """Mixin adding a reset method."""
 

src/torchjd/aggregation/_nash_mtl.py

@@ -5,23 +5,24 @@
 
 import contextlib
 
-import numpy as np
 import torch
 from torch import Tensor
 
-from torchjd.aggregation._mixins import Stateful, _NonDifferentiable, _WithOptionalDeps
+from torchjd._mixins import _WithOptionalDeps
+from torchjd.aggregation._mixins import Stateful, _NonDifferentiable
 
 from ._aggregator_bases import WeightedAggregator
 from ._weighting_bases import _MatrixWeighting
 
 with contextlib.suppress(ImportError):
     import cvxpy as cp
+    import numpy as np
     from cvxpy import Expression, SolverError
 
 
 # Non-differentiable: the cvxpy solver operates on numpy arrays, breaking the autograd graph.
 class _NashMTLWeighting(_WithOptionalDeps, _NonDifferentiable, Stateful, _MatrixWeighting):
-    _REQUIRED_DEPS = ["cvxpy", "ecos"]
+    _REQUIRED_DEPS = ["numpy", "cvxpy", "ecos"]
     _INSTALL_HINT = 'Install them with: pip install "torchjd[nash_mtl]"'
     """
     :class:`~torchjd.aggregation._mixins.Stateful`

tests/unit/aggregation/test_cagrad.py

@@ -1,7 +1,8 @@
-import pytest
+from utils.optional_deps import skip_if_deps_not_installed
 
-pytest.importorskip("cvxpy")
-pytest.importorskip("clarabel")
+from torchjd.aggregation import CAGradWeighting
+
+skip_if_deps_not_installed(CAGradWeighting)
 
 from contextlib import nullcontext as does_not_raise
 
@@ -11,7 +12,6 @@
 from utils.tensors import ones_
 
 from torchjd.aggregation import CAGrad
-from torchjd.aggregation._cagrad import CAGradWeighting
 
 from ._asserts import assert_expected_structure, assert_non_conflicting, assert_non_differentiable
 from ._inputs import scaled_matrices, typical_matrices