{"id":30294497,"url":"https://github.com/linkedin/dualip","last_synced_at":"2026-02-25T21:06:34.113Z","repository":{"id":40291894,"uuid":"381516168","full_name":"linkedin/DuaLip","owner":"linkedin","description":"DuaLip: Dual Decomposition based Linear Program Solver","archived":false,"fork":false,"pushed_at":"2023-11-16T19:02:28.000Z","size":3993,"stargazers_count":56,"open_issues_count":1,"forks_count":10,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-04-13T23:22:24.552Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://linkedin.github.io/DuaLip/","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linkedin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing/index.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-06-29T22:52:42.000Z","updated_at":"2023-09-22T04:28:55.000Z","dependencies_parsed_at":"2023-10-14T19:50:08.932Z","dependency_job_id":null,"html_url":"https://github.com/linkedin/DuaLip","commit_stats":null,"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/linkedin/DuaLip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkedin%2FDuaLip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkedin%2FDuaLip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkedin%2FDuaLip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkedin%2FDuaLip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linkedin","download_url":"https://codeload.github.com/linkedin/DuaLip/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkedin%2FDuaLip/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270796216,"owners_count":24647319,"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","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-08-17T01:35:15.024Z","updated_at":"2026-02-25T21:06:34.107Z","avatar_url":"https://github.com/linkedin.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DuaLip: Dual Decomposition-based Linear Program Solver\n\n[![License](https://img.shields.io/badge/License-BSD_2--Clause-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n[![PyTorch 2.6+](https://img.shields.io/badge/PyTorch-2.6%2B-ee4c2c.svg)](https://pytorch.org/)\n[![Docs](https://img.shields.io/badge/docs-GitHub_Pages-green.svg)](https://linkedin.github.io/DuaLip)\n\nDuaLip is an **extreme-scale Linear Program (LP) solver** built on PyTorch. It solves structured LP problems of the form:\n\n```\nminimize    c^T x\nsubject to  Ax ≤ b\n            x_i ∈ C_i   for all i ∈ {1, 2, ..., I}\n```\n\nwhere `x = (x_1, ..., x_I)` is the full vector of optimization variables, `x_i` is the vector associated with entity `i` (e.g., a user), and `A, b, c, C_i` are problem-specific data.\n\nMany large-scale decision systems — allocation, assignment, marketplace shaping — reduce to solving very large LPs on a recurring cadence. General-purpose LP solvers treat the constraint matrix as an unstructured operator and have not scaled to these extreme problem sizes. Specialized matching solvers cannot accommodate the heterogeneous constraint families (budgets, pacing, fairness, frequency caps) that arise in production.\n\nDuaLip fills this gap with a **ridge-regularized dual ascent** approach that:\n- Exploits block-diagonal structure for massive parallelism\n- Requires no commercial solver license\n- Runs entirely on commodity GPUs with open-source PyTorch\n\n## Features\n\n- **Extreme scale** — structured LPs with hundreds of millions of entities and up to trillions of variables\n- **GPU-accelerated** — significant wall-clock speedups over the prior Spark-based solver through native CUDA execution\n- **Operator-centric API** — new LP formulations require only a new `ObjectiveFunction`; projections and the solve loop are reused\n- **Distributed multi-GPU** — scales horizontally via `torch.distributed` (NCCL); communication cost depends only on the dual dimension\n- **Nesterov-accelerated gradient ascent** — with Lipschitz-based step sizing, Jacobi preconditioning, and optional γ decay\n- **Polytope projections** — box, simplex, and cone constraints, extensible via a registry pattern\n- **Warm start** — initialize from a previous dual solution for faster convergence on recurring workloads\n- **MLflow integration** — track dual objective, step sizes, hyperparameters, and convergence diagnostics\n- **Python-native** — aligns with common numerical and ML stacks for easy instrumentation and debugging\n\n## Quick start\n\n### Requirements\n\n- Python \u003e= 3.10\n- PyTorch \u003e= 2.6.0\n\n### Installation\n\n```bash\npip install -e .\n```\n\n### Usage\n\n```python\nimport torch\nfrom dualip.objectives.matching import MatchingInputArgs\nfrom dualip.projections.base import create_projection_map\nfrom dualip.run_solver import run_solver\nfrom dualip.types import ComputeArgs, ObjectiveArgs, SolverArgs\n\n# Build your problem data (A and c in CSC format, budget vector b)\n# and a projection map defining per-column constraints\ninput_args = MatchingInputArgs(\n    A=A_csc,                            # sparse constraint matrix (CSC)\n    c=C_csc,                            # sparse cost matrix (CSC)\n    b_vec=b_vec,                        # budget / RHS vector\n    projection_map=create_projection_map(projection_entries),\n)\n\nsolver_args = SolverArgs(max_iter=5000, gamma=1e-3)\ncompute_args = ComputeArgs(host_device=\"cuda:0\")\nobjective_args = ObjectiveArgs(objective_type=\"matching\")\n\nresult = run_solver(input_args, solver_args, compute_args, objective_args)\n\nprint(f\"Dual objective: {result.dual_objective:.6f}\")\n```\n\nFor a complete end-to-end example, see [examples/movielens_matching/movies_lens_matching.py](examples/movielens_matching/movies_lens_matching.py) which solves a matching problem on the MovieLens dataset. An example using a MIPLIB 2017 problem is available under [examples/miplib_2017/](examples/miplib_2017/).\n\nFor reference on setting up your own problem, see [benchmark/run_matching_benchmark.py](benchmark/run_matching_benchmark.py) (single-GPU) and [benchmark/run_matching_benchmark_dist.py](benchmark/run_matching_benchmark_dist.py) (distributed multi-GPU).\n\n## PyTorch-based solver\n\nDuaLip was originally built on Scala/Spark. The PyTorch rewrite is a ground-up redesign that replaces the CPU-centric, schema-bound runtime with a GPU-native, composable architecture, delivering significant wall-clock speedups while making new problem formulations far easier to express.\n\nThe solver uses an **operator-centric programming model** built around three decoupled primitives — `ObjectiveFunction`, `ProjectionMap`, and `Maximizer` — so new LP formulations only require implementing a new `ObjectiveFunction` while reusing the solve loop, projections, and distributed primitives.\n\n**Key design choices for GPU performance:**\n- Sparse CSC storage aligned with block-diagonal structure\n- Batched projection kernels\n- Jacobi preconditioning with γ continuation schedule\n- Distributed multi-GPU via `torch.distributed` (NCCL)\n- Warm start support\n- Pure PyTorch — no custom C++/CUDA kernels\n\n## Documentation\n\nFull documentation is available at **[linkedin.github.io/DuaLip](https://linkedin.github.io/DuaLip)**.\n\n## Migrating from the Spark-based solver\n\nThis PyTorch-based solver is a ground-up rewrite of the original [Spark/Scala DuaLip solver](https://arxiv.org/abs/2103.05277). The core dual-decomposition algorithm is the same, but the implementation, data formats, and APIs are entirely new.\n\n**Version history:** Tags `v1.0.0` through `v4.0.5` correspond to the Spark/Scala solver. The PyTorch rewrite begins at `v5.0.1` on the `master` branch.\n\nSee the [Quick start](#quick-start) section and [examples/movielens_matching/movies_lens_matching.py](examples/movielens_matching/movies_lens_matching.py) for examples of the new API.\n\n## Development\n\n1. **Create and activate a virtual environment**\n\n   ```bash\n   python -m venv .venv \u0026\u0026 source .venv/bin/activate\n   ```\n\n2. **Install dev dependencies and pre-commit hooks**\n\n   ```bash\n   make install\n   ```\n\n3. **Run tests**\n\n   ```bash\n   make test\n   ```\n\n4. **Run checkstyle** (format + lint)\n\n   ```bash\n   make checkstyle\n   ```\n\n## Repository structure\n\n```\nsrc/dualip/          Core library\n  objectives/        Objective functions (matching, MIPLIB)\n  optimizers/        Accelerated gradient descent solver\n  projections/       Box, simplex, cone projections\n  preprocessing/     Input validation and Jacobi preconditioning\n  utils/             Sparse, distributed, and MLflow utilities\ntests/               Unit and distributed tests\nexamples/            Example problems (MovieLens matching, MIPLIB 2017)\nbenchmark/           Scaling and performance benchmarks\ndocs/                Sphinx documentation source\n```\n\n## Citing DuaLip\n\nIf you use DuaLip in your work, please cite:\n\n```bibtex\n@inproceedings{ramanath:21,\n  author  = {Ramanath, Rohan and Keerthi, Sathiya S. and Basu, Kinjal and Salomatin, Konstantin and Yao, Pan},\n  title   = {Efficient Algorithms for Global Inference in Internet Marketplaces},\n  journal = {arXiv preprint arXiv:2103.05277},\n  year    = {2021},\n  url     = {https://arxiv.org/abs/2103.05277}\n}\n\n@InProceedings{pmlr-v119-basu20a,\n  title     = {{ECLIPSE}: An Extreme-Scale Linear Program Solver for Web-Applications},\n  author    = {Basu, Kinjal and Ghoting, Amol and Mazumder, Rahul and Pan, Yao},\n  booktitle = {Proceedings of the 37th International Conference on Machine Learning},\n  pages     = {704--714},\n  year      = {2020},\n  volume    = {119},\n  series    = {Proceedings of Machine Learning Research},\n  publisher = {PMLR},\n  url       = {http://proceedings.mlr.press/v119/basu20a.html}\n}\n```\n\n## Contributing\n\nPlease report bugs and feature requests via the [GitHub issue tracker](https://github.com/linkedin/DuaLip/issues). To contribute code, see the [contributing guide](https://linkedin.github.io/DuaLip/contributing/index.html).\n\n## Acknowledgements\n\nDuaLip is built and maintained by the AI Algorithms team at LinkedIn:\n\n- [Gregory Dexter](https://www.linkedin.com/in/gregorydexter1/)\n- [Aida Rahmattalabi](https://www.linkedin.com/in/aida-rahmattalabi-23a4ab4a/)\n- [Sanjana Garg](https://www.linkedin.com/in/sanjana-garg/)\n- [Qingquan Song](https://www.linkedin.com/in/qingquan-song-b71167119/)\n- [Zhipeng Wang](https://www.linkedin.com/in/zhipeng-wang-phd-66806816/)\n\n## License\n\nBSD 2-Clause License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkedin%2Fdualip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinkedin%2Fdualip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkedin%2Fdualip/lists"}