Add NVIDIA cuOpt as a GPU-accelerated solver

[mal84emma]

Closes #515
Bringing Nvidia speed to linopy.

Why?

• cuOpt is fast
• It's free and open-source (Apache 2.0)
• Did I mention it's fast?

Changes proposed in this Pull Request

First-class support for NVIDIA cuOpt as a linopy solver: LP, MILP and convex QP on the GPU through cuOpt's direct (in-memory) API, with duals for LP/QP, MIP gap and dual bound for MILP, semi-continuous variables, and a Model.to_cuopt() bridge. Installable with pip install "linopy[gpu]" (Linux, CUDA 12 driver ≥ 525.60.13, compute capability ≥ 7.0).

Note

The following content was generated by AI (a supervised multi-agent run; every commit on this branch is marked with its authoring model).

Design points a reviewer will care about

• Direct API only. File io_apis transparently fall back to the direct build with one warning. The rationale (unverified solution-file parsing, an inverted Q convention between .lp and .mps) is documented at the code site.
• method=3 (Barrier) is linopy's default, not cuOpt's own concurrent default, which segfaults on repeated solves of models ≳1300 variables (reproduced and documented). An escape hatch to PDLP (method=1) is documented for very large sparse LPs.
• All cuOpt solves run on one persistent worker thread. cuOpt's bundled LLVM OpenMP runtime leaks per-thread state — the fresh-thread-per-solve pattern aborts the process after a handful of solves. Reported upstream as NVIDIA/cuopt#1768; the worker also owns native object disposal so garbage collection on foreign threads (e.g. dask workers) cannot trigger native teardown off-thread.
• Maximisation is handled by sign-flipping the objective/Q into an equivalent minimisation and negating the objective, duals and dual bound back — verified against HiGHS on all six sense×constraint combinations plus the presolve path.
• QP uses 0.5 · M.Q (cuOpt symmetrises internally); a committed deliberate-failure test proves the wrong convention changes the answer by 50% relative, so the guard cannot rot silently.
• Honest refusals: MIQP raises NotImplementedError up front (cuOpt silently mis-solves it), warm start is refused (usable PDLP warm start needs three simultaneous non-default settings), reduced costs are not populated (upstream sign defect for maximised models with <= rows), SOS/indicator constraints are absent upstream. Each refusal carries a 1–3-line rationale at its enforcement site.
• GPU probe runs in a subprocess so available_solvers on a GPU-less machine simply omits cuOpt, and the probe cannot poison later os.fork() children.

Performance

Indicative benchmark: LOPF of the PyPSA scigrid-de example network (585 buses, 1423 generators, 852 lines), its 24-hour day tiled to scale the LP; wall time of m.solve(), solvers run sequentially on an otherwise idle Azure VM (8-core EPYC 7V12, Tesla T4 16 GB). HiGHS was given threads=8, parallel=on (measured: no gain over its defaults); cuOpt ran at this branch's defaults (direct API, barrier). Objectives agree to ≤8·10⁻⁴ relative at both solvers' default tolerances.

LP size	HiGHS	cuOpt (T4)	Speedup
60 k vars	4.1 s	2.2 s	~2×
417 k vars	116 s	5.8 s	~20×
1.67 M vars	1526 s	14.7 s	~104×
2.50 M vars	3359 s	20.9 s	~161×

cuOpt times are first-solve-in-process (cold): they include one-off CUDA context initialisation, which repeat solves in the same process avoid, running ~2 s faster. The gap widens with size (HiGHS scales ~n^1.9 here, cuOpt near-linearly). A T4 is the smallest supported datacenter GPU; newer hardware should do better.

Note

To be fair this is a bit of a trust-me-bro benchmark. HiGHS can solve much faster than its default config and even faster with better hardware (test was on a GPU optimized VM, though with not a very good GPU).
Regardless, cuOpt is fast and has been winning competitions.
Particularly now that cards with serious VRAM are available I think it could make solving large ESOMs more accessible without a commercial solver license.

Known upstream issue reviewers should weigh

cuOpt 26.08.00 can destabilise a long-lived host process after any in-process solve: its bundled OpenMP runtime intermittently corrupts glibc malloc metadata, crashing the process later in unrelated code. This was diagnosed to root cause (gdb backtrace into _int_malloc, linopy exonerated by a source audit and by mitigation experiments) and reported with full evidence on NVIDIA/cuopt#1768. Every completed full test-suite run on this branch has a failure set byte-identical to master's baseline — correctness is unaffected — but roughly two thirds of full --run-gpu suite runs abort mid-run from this corruption. The feature is opt-in (install extra + explicit solver choice); whether to ship ahead of an upstream fix is a maintainer decision this PR intentionally surfaces rather than hides.

Verification summary

• Expected values in the test suite were confirmed by differential testing against live in-process HiGHS 1.15.1 during development, then baked in: LP objective/primal/duals on all six sense×constraint-sense cells (duals agreed to ≤2.5e-9), MILP objective/gap/bound, QP objective to 2e-14 on the pinned 3-variable model, min and max.
• Status-map verification with forcing recipes for every reachable cuOpt termination status (both LP and MILP enums), including an empty-Solution time-limit path.
• 20 sequential n=2000 LP solves in one process (regression guard for the upstream thread-state leak; threshold chosen 1.54× above the measured abort boundary).
• All cuOpt GPU tests pass (pytest test/test_cuopt.py test/test_semi_continuous.py --run-gpu: 102 passed); CPU-only machines skip all of them; full CPU suite and every completed full GPU suite run are failure-set-identical to master's baseline (74 pre-existing failures/errors, all in test/remote and unrelated areas).
• Interrupt contract (Ctrl-C returns promptly, GPU work completes, worker reusable) covered by CPU-only tests.
• Docs build warning-identical to master's baseline in a venv without cuOpt installed (the ReadTheDocs condition).
• mypy: zero new errors (28 pre-existing Xpress errors on master unchanged); ruff clean.

Implementation Approach

This PR was a bit of an experiment at getting a Claude agent system to one-shot new features. If you're interested in the approach I took you can read the agent docs and my thoughts on how it went here.

Checklist

• Read by a human (Claude wrote the code, but I've read and checked it, all mistakes are mine).
• AI-generated content is marked (see AGENTS.md).
• Code changes are sufficiently documented; i.e. new functions contain docstrings and further explanations may be given in doc.
• Unit tests for new features were added (if applicable).
• A note for the release notes doc/release_notes.rst of the upcoming release is included.
• I consent to the release of this PR's code under the MIT license.

[codspeed-hq]

Merging this PR will degrade performance by 18.24%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
❌ 5 regressed benchmarks
✅ 169 untouched benchmarks
⏩ 175 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Memory	test_to_lp[knapsack-n=10000]	1.6 MB	2.7 MB	-40.25%
❌	Memory	test_to_lp[masked-n=100]	2.1 MB	2.6 MB	-20.71%
❌	Memory	test_to_lp[storage-n=250]	28.5 MB	35.8 MB	-20.49%
❌	Memory	test_to_lp[storage-n=10]	2.3 MB	2.9 MB	-20.33%
❌	Memory	test_to_lp[merge_balance-severity=0]	2.6 MB	3.2 MB	-17.89%
⚡	Memory	test_to_lp[rolling-severity=50]	429.7 MB	354.6 MB	+21.19%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing mal84emma:feat/cuopt-solver (bb0581b) with master (a64b657)}

Footnotes

1. 175 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[FabianHofmann]

great work @mal84emma ; I refactored the code a little and move cuopt helpers to the Cuopt solver class. I was confused about the minimization/maximization logic. but it turns out to be stable.

[mal84emma]

Awesome, thank you @FabianHofmann
The max/min is a bit of a hack to make sure the dual value signs are correct, basically by always converting to a minimize problem because cuOpt doesn't handle dual value signs properly - have updated the comment to make this more clear