Metadata-Version: 2.4
Name: nexus-opt
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Dist: numpy>=1.20
Requires-Dist: highspy>=1.5
License-File: LICENSE
Summary: Rust-core optimisation library for Python: LP, MILP, QP, conic, nonlinear, black-box, multi-objective and stochastic behind one API
Keywords: optimisation,optimization,linear-programming,milp,conic,socp,solver,rust
Author: Vishal Ram Sanmuga Magesh
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/VishalRam24/nexus-opt/blob/main/WIKI.md
Project-URL: Homepage, https://github.com/VishalRam24/nexus-opt
Project-URL: Repository, https://github.com/VishalRam24/nexus-opt

<div align="center">

# nexus-opt

**One modelling API. Rust core. Every problem class.**

Linear, mixed-integer, quadratic, conic (SOCP/SDP), nonlinear, black-box,
multi-objective and stochastic programming — behind a single interface, so
changing problem class doesn't mean changing library.

[![License: MIT](https://img.shields.io/badge/License-MIT-14b8a6.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9%2B-4a5573.svg)](pyproject.toml)
[![Rust](https://img.shields.io/badge/core-Rust%20%2B%20PyO3-1c2337.svg)](Cargo.toml)

[Website](https://vishalram24.github.io/nexus/) ·
[User guide](WIKI.md) ·
[Energy layer](https://github.com/VishalRam24/nexus-energy)

</div>

---

## Install

```bash
pip install nexus-opt
```

Prebuilt wheels for Linux (glibc and musl; x86_64 / aarch64 / i686), macOS
(arm64 and x86_64) and Windows (x64 and x86). The crate builds as an **abi3**
extension, so one wheel per platform serves every CPython from 3.9 up — and no
Rust toolchain is needed to install.

> **Not yet on PyPI.** The wheel matrix is built and verified but publication is
> pending. Until then, see [Building from source](#building-from-source).

## Sixty seconds

```python
import nexus_opt as nx

m = nx.Model()
x = m.variable("x", lower=0)
y = m.variable("y", lower=0)

m.add(x + y >= 10)
m.add(x <= 6)
m.minimize(2 * x + 3 * y)

r = m.solve()
print(r.status, r.objective, r.value(x), r.value(y))
# optimal 24.0 6.0 4.0
```

Variables are continuous, integer or binary. Constraints are written with
ordinary `<=`, `>=`, `==` and compile straight to Rust structures; `nx.sum()`
reduces expressions in parallel.

## What's in it

**Quadratic and conic.** Quadratic objectives compile to native quadratic terms.
Second-order cones via `add_soc([head, x1, ..., xk])` (imposing `t >= ||x||₂`),
PSD cones over the lower-triangular entries of a symmetric matrix, and
`quad_form(model, xs, P)` which builds `xᵀPx` and validates that `P` is PSD.

**Nonlinear.** `sin`, `cos`, `sqrt` and division are first-class expression
operators, not wrappers. Nonlinear constraints live in a parallel container, so
the LP/QP presolve path stays untouched and bit-identical.

**Black-box and metaheuristics.** Differential evolution, particle swarm,
simulated annealing and CMA-ES:

```python
r = nx.solve_de(lambda x: x[0]**2 + x[1]**2, [(-5, 5), (-5, 5)])
```

`nx.solve_portfolio(...)` races several algorithms against the same objective
and returns the best.

**Multi-objective and stochastic.** `pareto_frontier(...)`, `stochastic_solve(...)`.

**Scale.** `solve_parallel_de`, `solve_admm`, and `PersistentHighs` for
warm-started re-solves across a sequence of related problems.

See [`WIKI.md`](WIKI.md) for the full API reference.

## Who uses it

[`nexus-energy`](https://github.com/VishalRam24/nexus-energy) is built directly
on this core — capacity expansion, unit commitment and OPF at exact parity with
PyPSA and GenX, several times faster. If you want the energy-system layer rather
than the solver, start there.

## Benchmarks

[`benchmarks/`](benchmarks) holds the comparison harness and stored results
(`benchmarks/_results/*.jsonl`) against scipy, cvxpy, PuLP, Pyomo, Optuna and
Nevergrad.

Third-party solvers appear there only as comparison rows — they are never
wrapped inside the library.

## Building from source

```bash
git clone https://github.com/VishalRam24/nexus-opt
cd nexus-opt
maturin build --release
pip install target/wheels/*.whl
```

Needs a Rust toolchain. Run the tests with `uv run pytest`.

## Licence

MIT — see [LICENSE](LICENSE).

