{"id":27206346,"url":"https://github.com/torchjd/torchjd","last_synced_at":"2025-05-16T08:02:49.945Z","repository":{"id":245585078,"uuid":"809057064","full_name":"TorchJD/torchjd","owner":"TorchJD","description":"Library for Jacobian descent with PyTorch. It enables optimization of neural networks with multiple losses (e.g. multi-task learning).","archived":false,"fork":false,"pushed_at":"2025-05-14T12:15:31.000Z","size":775,"stargazers_count":234,"open_issues_count":3,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-16T08:01:36.731Z","etag":null,"topics":["deep-learning","jacobian-descent","multi-objective-optimization","multi-task-learning","multiobjective-optimization","multitask-learning","optimization","python","pytorch","torch"],"latest_commit_sha":null,"homepage":"https://torchjd.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TorchJD.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-01T15:07:10.000Z","updated_at":"2025-05-14T11:49:43.000Z","dependencies_parsed_at":"2024-12-08T21:25:03.524Z","dependency_job_id":"d7ef21dc-f501-4ef1-b202-50a86d501e96","html_url":"https://github.com/TorchJD/torchjd","commit_stats":null,"previous_names":["torchjd/torchjd"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TorchJD%2Ftorchjd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TorchJD%2Ftorchjd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TorchJD%2Ftorchjd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TorchJD%2Ftorchjd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TorchJD","download_url":"https://codeload.github.com/TorchJD/torchjd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493381,"owners_count":22080126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","jacobian-descent","multi-objective-optimization","multi-task-learning","multiobjective-optimization","multitask-learning","optimization","python","pytorch","torch"],"created_at":"2025-04-09T23:29:50.736Z","updated_at":"2025-05-16T08:02:49.939Z","avatar_url":"https://github.com/TorchJD.png","language":"Python","readme":"# ![image](docs/source/icons/favicon-32x32.png) TorchJD\n\n[![Doc](https://img.shields.io/badge/Doc-torchjd.org-blue?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8%2BCjwhLS0gQ3JlYXRlZCB1c2luZyBLcml0YTogaHR0cDovL2tyaXRhLm9yZyAtLT4KCjxzdmcKICAgd2lkdGg9IjIwNDcuNzJwdCIKICAgaGVpZ2h0PSIyMDQ3LjcycHQiCiAgIHZpZXdCb3g9IjAgMCAyMDQ3LjcyIDIwNDcuNzIiCiAgIHZlcnNpb249IjEuMSIKICAgaWQ9InN2ZzEiCiAgIHNvZGlwb2RpOmRvY25hbWU9IlRvcmNoSkRfbG9nb19jaXJjdWxhci5zdmciCiAgIGlua3NjYXBlOnZlcnNpb249IjEuMy4yICgwOTFlMjBlZjBmLCAyMDIzLTExLTI1KSIKICAgeG1sbnM6aW5rc2NhcGU9Imh0dHA6Ly93d3cuaW5rc2NhcGUub3JnL25hbWVzcGFjZXMvaW5rc2NhcGUiCiAgIHhtbG5zOnNvZGlwb2RpPSJodHRwOi8vc29kaXBvZGkuc291cmNlZm9yZ2UubmV0L0RURC9zb2RpcG9kaS0wLmR0ZCIKICAgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIgogICB4bWxuczpzdmc9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8c29kaXBvZGk6bmFtZWR2aWV3CiAgICAgaWQ9Im5hbWVkdmlldzEiCiAgICAgcGFnZWNvbG9yPSIjZmZmZmZmIgogICAgIGJvcmRlcmNvbG9yPSIjNjY2NjY2IgogICAgIGJvcmRlcm9wYWNpdHk9IjEuMCIKICAgICBpbmtzY2FwZTpzaG93cGFnZXNoYWRvdz0iMiIKICAgICBpbmtzY2FwZTpwYWdlb3BhY2l0eT0iMC4wIgogICAgIGlua3NjYXBlOnBhZ2VjaGVja2VyYm9hcmQ9IjAiCiAgICAgaW5rc2NhcGU6ZGVza2NvbG9yPSIjZDFkMWQxIgogICAgIGlua3NjYXBlOmRvY3VtZW50LXVuaXRzPSJwdCIKICAgICBpbmtzY2FwZTp6b29tPSIwLjE2Mjk4NjE1IgogICAgIGlua3NjYXBlOmN4PSIxMzk1LjgyNDEiCiAgICAgaW5rc2NhcGU6Y3k9Ijg3NC4zMDczOSIKICAgICBpbmtzY2FwZTp3aW5kb3ctd2lkdGg9IjI1NjAiCiAgICAgaW5rc2NhcGU6d2luZG93LWhlaWdodD0iMTM3MSIKICAgICBpbmtzY2FwZTp3aW5kb3cteD0iMCIKICAgICBpbmtzY2FwZTp3aW5kb3cteT0iMCIKICAgICBpbmtzY2FwZTp3aW5kb3ctbWF4aW1pemVkPSIxIgogICAgIGlua3NjYXBlOmN1cnJlbnQtbGF5ZXI9InN2ZzEiIC8%2BCiAgPGRlZnMKICAgICBpZD0iZGVmczEiIC8%2BCiAgPHBhdGgKICAgICBpZD0ic2hhcGUxIgogICAgIGZpbGw9IiMwMDAwMDAiCiAgICAgZmlsbC1ydWxlPSJldmVub2RkIgogICAgIGQ9Ik0yNTUuMjE1IDg5OS44NzVMMjU1Ljk2NCAyNTUuOTY0TDc2Ny44OTMgMjU1Ljk2NEw3NjcuODkzIDBMMCAwTDAuMDMxMjUzMyA4OTguODQ0QzAuMDMxNzMwNSA4OTguODE0IDg0LjU3MjYgODk5Ljg3NSAyNTUuMjE1IDg5OS44NzVaIgogICAgIHN0eWxlPSJmaWxsOiMxYTgxZWI7ZmlsbC1vcGFjaXR5OjEiCiAgICAgdHJhbnNmb3JtPSJtYXRyaXgoMS4wMDAwMDAwMTQzMDcwNyAwIDAgMS4wMDAwMDAwMTQzMDcwNyAxMjcuOTgyMjI2NTIyMDU2IDEyNy45ODIyMjY1MjIwNTYpIiAvPgogIDxwYXRoCiAgICAgaWQ9InNoYXBlMDEiCiAgICAgdHJhbnNmb3JtPSJtYXRyaXgoLTEuMDAwMDAwMDA5MjIxODUgMCAwIC0xLjAwMDAwMDAwOTIyMTg1IDE5MTkuOTEzNjE3Mzk4NzEgMTkxMC4zMzcxOTY5MzEyNSkiCiAgICAgZmlsbD0iIzAwMDAwMCIKICAgICBmaWxsLXJ1bGU9ImV2ZW5vZGQiCiAgICAgZD0iTTc2OC4wNzQgMTc3Mi42MUMtMjgyLjAwNCAxNTk4LjY1IC0yMjkuNzEyIDE1MS44MjEgNzY4LjA3NCAwQzc2Ny4wODMgMjkuOTMzNyA3NjguMDk2IDE0Mi43NiA3NjguMDc0IDI2MC44ODZDNDEuNDc0NiA0NTYuOTAzIDEzNy40MjMgMTM4MC4wNiA3NjguMDc0IDE1MTMuNjQiCiAgICAgc3R5bGU9ImZpbGw6IzFhODFlYjtmaWxsLW9wYWNpdHk6MSIgLz4KICA8cGF0aAogICAgIGlkPSJzaGFwZTAyIgogICAgIGZpbGw9IiMwMDAwMDAiCiAgICAgZmlsbC1ydWxlPSJldmVub2RkIgogICAgIGQ9Ik03NjcuOTA5IDg4Ny4zMzhDMjYzLjQwMiA4MDMuOTI2IDAuMDc1OTQyMSAzODcuOTY0IDAgMC4wODU2NDk3QzE0LjY4NjggLTAuMDI4NTQ5OSA5OS4wNTUxIC0wLjAyODU0OTkgMjU1LjAxMSAwLjA4NTY0OTdDMjU1LjMxMSAyODEuMTE0IDQ0OC43ODYgNTYyLjE2MyA3NjcuOTA5IDYyNi40OTkiCiAgICAgc3R5bGU9ImZpbGw6IzFhODFlYjtmaWxsLW9wYWNpdHk6MSIKICAgICB0cmFuc2Zvcm09Im1hdHJpeCgwLjk5OTk5OTk2MDczODQ0IDAgMCAwLjk5OTk5OTk2MDczODQ0IDEyNy45NjY1OTE0OTQzMjggMTAyMy43NzIxNDc4MzE0KSIgLz4KICA8ZWxsaXBzZQogICAgIHN0eWxlPSJmaWxsOiMxYTgxZWI7c3Ryb2tlLXdpZHRoOjEuMDY3OTtmaWxsLW9wYWNpdHk6MSIKICAgICBpZD0icGF0aDEiCiAgICAgY3g9IjEwMjYuMzYxIgogICAgIGN5PSIxMDE0LjIyMTEiCiAgICAgcng9IjE4My4yNTU0MyIKICAgICByeT0iMTgzLjUxNTU4IiAvPgo8L3N2Zz4K)](https://torchjd.org)\n[![Tests](https://github.com/TorchJD/torchjd/actions/workflows/tests.yml/badge.svg)](https://github.com/TorchJD/torchjd/actions/workflows/tests.yml)\n[![codecov](https://codecov.io/gh/TorchJD/torchjd/graph/badge.svg?token=8AUCZE76QH)](https://codecov.io/gh/TorchJD/torchjd)\n[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/TorchJD/torchjd/main.svg)](https://results.pre-commit.ci/latest/github/TorchJD/torchjd/main)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/torchjd)](https://pypistats.org/packages/torchjd)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/torchjd)](https://pypi.org/project/torchjd/)\n[![Static Badge](https://img.shields.io/badge/Discord%20-%20community%20-%20%235865F2?logo=discord\u0026logoColor=%23FFFFFF\u0026label=Discord)](https://discord.gg/76KkRnb3nk)\n\nTorchJD is a library extending autograd to enable\n[Jacobian descent](https://arxiv.org/pdf/2406.16232) with PyTorch. It can be used to train neural\nnetworks with multiple objectives. In particular, it supports multi-task learning, with a wide\nvariety of aggregators from the literature. It also enables the instance-wise risk minimization\nparadigm. The full documentation is available at [torchjd.org](https://torchjd.org), with several\nusage examples.\n\n## Jacobian descent (JD)\nJacobian descent is an extension of gradient descent supporting the optimization of vector-valued\nfunctions. This algorithm can be used to train neural networks with multiple loss functions. In this\ncontext, JD iteratively updates the parameters of the model using the Jacobian matrix of the vector\nof losses (the matrix stacking each individual loss' gradient). For more details, please refer to\nSection 2.1 of the [paper](https://arxiv.org/pdf/2406.16232).\n\n### How does this compare to averaging the different losses and using gradient descent?\n\nAveraging the losses and computing the gradient of the mean is mathematically equivalent to\ncomputing the Jacobian and averaging its rows. However, this approach has limitations. If two\ngradients are conflicting (they have a negative inner product), simply averaging them can result in\nan update vector that is conflicting with one of the two gradients. Averaging the losses and making\na step of gradient descent can thus lead to an increase of one of the losses.\n\nThis is illustrated in the following picture, in which the two objectives' gradients $g_1$ and $g_2$\nare conflicting, and averaging them gives an update direction that is detrimental to the first\nobjective. Note that in this picture, the dual cone, represented in green, is the set of vectors\nthat have a non-negative inner product with both $g_1$ and $g_2$.\n\n![image](docs/source/_static/direction_upgrad_mean.svg)\n\nWith Jacobian descent, $g_1$ and $g_2$ are computed individually and carefully aggregated using an\naggregator $\\mathcal A$. In this example, the aggregator is the Unconflicting Projection of\nGradients $\\mathcal A_{\\text{UPGrad}}$: it\nprojects each gradient onto the dual cone, and averages the projections. This ensures that the\nupdate will always be beneficial to each individual objective (given a sufficiently small step\nsize). In addition to $\\mathcal A_{\\text{UPGrad}}$, TorchJD supports\n[more than 10 aggregators from the literature](https://torchjd.org/stable/docs/aggregation).\n\n## Installation\n\u003c!-- start installation --\u003e\nTorchJD can be installed directly with pip:\n```bash\npip install torchjd\n```\n\u003c!-- end installation --\u003e\nSome aggregators may have additional dependencies. Please refer to the\n[installation documentation](https://torchjd.org/stable/installation) for them.\n\n## Usage\nThe main way to use TorchJD is to replace the usual call to `loss.backward()` by a call to\n`torchjd.backward` or `torchjd.mtl_backward`, depending on the use-case.\n\nThe following example shows how to use TorchJD to train a multi-task model with Jacobian descent,\nusing [UPGrad](https://torchjd.org/stable/docs/aggregation/upgrad/).\n\n```diff\n import torch\n from torch.nn import Linear, MSELoss, ReLU, Sequential\n from torch.optim import SGD\n\n+ from torchjd import mtl_backward\n+ from torchjd.aggregation import UPGrad\n\n shared_module = Sequential(Linear(10, 5), ReLU(), Linear(5, 3), ReLU())\n task1_module = Linear(3, 1)\n task2_module = Linear(3, 1)\n params = [\n *shared_module.parameters(),\n *task1_module.parameters(),\n *task2_module.parameters(),\n ]\n\n loss_fn = MSELoss()\n optimizer = SGD(params, lr=0.1)\n+ aggregator = UPGrad()\n\n inputs = torch.randn(8, 16, 10) # 8 batches of 16 random input vectors of length 10\n task1_targets = torch.randn(8, 16, 1) # 8 batches of 16 targets for the first task\n task2_targets = torch.randn(8, 16, 1) # 8 batches of 16 targets for the second task\n\n for input, target1, target2 in zip(inputs, task1_targets, task2_targets):\n features = shared_module(input)\n output1 = task1_module(features)\n output2 = task2_module(features)\n loss1 = loss_fn(output1, target1)\n loss2 = loss_fn(output2, target2)\n\n optimizer.zero_grad()\n- loss = loss1 + loss2\n- loss.backward()\n+ mtl_backward(losses=[loss1, loss2], features=features, aggregator=aggregator)\n optimizer.step()\n```\n\n\u003e [!NOTE]\n\u003e In this example, the Jacobian is only with respect to the shared parameters. The task-specific\n\u003e parameters are simply updated via the gradient of their task’s loss with respect to them.\n\nMore usage examples can be found [here](https://torchjd.org/stable/examples/).\n\n## Supported Aggregators\nTorchJD provides many existing aggregators from the literature, listed in the following table.\n\n\u003c!-- recommended aggregators first, then alphabetical order --\u003e\n| Aggregator | Publication |\n|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| [UPGrad](https://torchjd.org/stable/docs/aggregation/upgrad/) (recommended) | [Jacobian Descent For Multi-Objective Optimization](https://arxiv.org/pdf/2406.16232) |\n| [AlignedMTL](https://torchjd.org/stable/docs/aggregation/aligned_mtl/) | [Independent Component Alignment for Multi-Task Learning](https://arxiv.org/pdf/2305.19000) |\n| [CAGrad](https://torchjd.org/stable/docs/aggregation/cagrad/) | [Conflict-Averse Gradient Descent for Multi-task Learning](https://arxiv.org/pdf/2110.14048) |\n| [ConFIG](https://torchjd.org/stable/docs/aggregation/config/) | [ConFIG: Towards Conflict-free Training of Physics Informed Neural Networks](https://arxiv.org/pdf/2408.11104) |\n| [Constant](https://torchjd.org/stable/docs/aggregation/constant/) | - |\n| [DualProj](https://torchjd.org/stable/docs/aggregation/dualproj/) | [Gradient Episodic Memory for Continual Learning](https://arxiv.org/pdf/1706.08840) |\n| [GradDrop](https://torchjd.org/stable/docs/aggregation/graddrop/) | [Just Pick a Sign: Optimizing Deep Multitask Models with Gradient Sign Dropout](https://arxiv.org/pdf/2010.06808) |\n| [IMTL-G](https://torchjd.org/stable/docs/aggregation/imtl_g/) | [Towards Impartial Multi-task Learning](https://discovery.ucl.ac.uk/id/eprint/10120667/) |\n| [Krum](https://torchjd.org/stable/docs/aggregation/krum/) | [Machine Learning with Adversaries: Byzantine Tolerant Gradient Descent](https://proceedings.neurips.cc/paper/2017/file/f4b9ec30ad9f68f89b29639786cb62ef-Paper.pdf) |\n| [Mean](https://torchjd.org/stable/docs/aggregation/mean/) | - |\n| [MGDA](https://torchjd.org/stable/docs/aggregation/mgda/) | [Multiple-gradient descent algorithm (MGDA) for multiobjective optimization](https://www.sciencedirect.com/science/article/pii/S1631073X12000738) |\n| [Nash-MTL](https://torchjd.org/stable/docs/aggregation/nash_mtl/) | [Multi-Task Learning as a Bargaining Game](https://arxiv.org/pdf/2202.01017) |\n| [PCGrad](https://torchjd.org/stable/docs/aggregation/pcgrad/) | [Gradient Surgery for Multi-Task Learning](https://arxiv.org/pdf/2001.06782) |\n| [Random](https://torchjd.org/stable/docs/aggregation/random/) | [Reasonable Effectiveness of Random Weighting: A Litmus Test for Multi-Task Learning](https://arxiv.org/pdf/2111.10603) |\n| [Sum](https://torchjd.org/stable/docs/aggregation/sum/) | - |\n| [Trimmed Mean](https://torchjd.org/stable/docs/aggregation/trimmed_mean/) | [Byzantine-Robust Distributed Learning: Towards Optimal Statistical Rates](https://proceedings.mlr.press/v80/yin18a/yin18a.pdf) |\n\nThe following example shows how to instantiate\n[UPGrad](https://torchjd.org/stable/docs/aggregation/upgrad/) and aggregate a simple matrix `J` with\nit.\n```python\nfrom torch import tensor\nfrom torchjd.aggregation import UPGrad\n\nA = UPGrad()\nJ = tensor([[-4., 1., 1.], [6., 1., 1.]])\n\nA(J)\n# Output: tensor([0.2929, 1.9004, 1.9004])\n```\n\n\u003e [!TIP]\n\u003e When using TorchJD, you generally don't have to use aggregators directly. You simply instantiate\n\u003e one and pass it to the backward function (`torchjd.backward` or `torchjd.mtl_backward`), which\n\u003e will in turn apply it to the Jacobian matrix that it will compute.\n\n## Contribution\nPlease read the [Contribution page](CONTRIBUTING.md).\n\n## Citation\nIf you use TorchJD for your research, please cite:\n```\n@article{jacobian_descent,\n title={Jacobian Descent For Multi-Objective Optimization},\n author={Quinton, Pierre and Rey, Valérian},\n journal={arXiv preprint arXiv:2406.16232},\n year={2024}\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftorchjd%2Ftorchjd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftorchjd%2Ftorchjd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftorchjd%2Ftorchjd/lists"}