Metadata-Version: 2.4
Name: residopt
Version: 0.1.0
Summary: Residual compilation prototype for robust optimization models
License-Expression: MIT
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cvxpy>=1.9.2
Requires-Dist: numpy>=2.0
Requires-Dist: scikit-learn>=1.9.0
Dynamic: license-file

residopt
========

First-cut research prototype for residual compilation of robust optimization
atoms into solver-facing CVXPY models.

Paper: [Residual Compilation (Zenodo PDF)](https://zenodo.org/records/21197063/files/ResidualCompilation.pdf?download=1)

What this is
------------

Robust optimization is about making decisions that still work when inputs are
uncertain. `residopt` is a prototype compiler for those models: it recognizes
common uncertainty constraints and turns them into solver-ready convex
constraints when that is worthwhile, or leaves them behind a checking oracle
when direct compilation would be too expensive.

The novelty is the decision layer. Existing tools often either reformulate a
known robust constraint or solve it with an oracle; `residopt` treats that
choice as something the compiler can reason about per constraint, with explicit
certificates and benchmark-derived cost signals. The underlying theory comes
from seeing these uncertainty rewrites as residual operations, but the practical
goal is simple: preserve correctness while choosing the faster strategy for the
instance at hand.

Implemented templates:

- Ellipsoidal linear support constraints as exact SOCP certificates.
- Budget-uncertainty support constraints as exact LP certificates.
- Single quadratic payloads over ellipsoids as exact S-lemma SDP certificates.
- Certificate labels and propagation: exact, upper envelope, relaxation, oracle.
- A simple compile-or-oracle cost rule for partial compilation.
- A screened hybrid compiler path that solves the nominal problem, compiles
  near-active atoms, and leaves the rest behind oracle certificates.

Run the Section 7-style robust conic regression example:

```bash
uv run python examples/robust_regression.py
```

Run tests:

```bash
uv run pytest
```

Run the ellipsoid support benchmark:

```bash
uv run python benchmarks/ellipsoid_support.py
```

The benchmark reports median timing over repeated runs, build/solve/oracle
timing splits, objective and solution gaps, final robust feasibility, and active
robust constraint counts. `comp_solve` and `cut_solve` are CVXPY wall-clock
solve calls; `comp_core` and `cut_core` are solver-reported core solve time.
`comp_model` and `cut_model` expose CVXPY canonicalization/setup overhead, and
`core_up` compares solver-core time plus oracle time rather than wall-clock
modeling overhead.

To generate the controlled uplift-vs-active-fraction sweep:

```bash
uv run python benchmarks/ellipsoid_support.py --suite activity --baseline eager --repeat 5
```

The activity suite uses curved disk constraints in a shared subspace so the
target active fraction is reflected in the final robust solution. The default
cut policy adds all violated cuts per round, which is the stronger cutting-plane
baseline. To force a one-cut-at-a-time diagnostic:

```bash
uv run python benchmarks/ellipsoid_support.py --suite activity --baseline eager --cut-policy most_violated --repeat 5
```

Larger optional random cases are available with:

```bash
uv run python benchmarks/ellipsoid_support.py --suite scale --case m200_d50 --repeat 3
```

To test tolerance coupling in the oracle layer:

```bash
uv run python benchmarks/ellipsoid_support.py --case large --baseline eager --tolerance-sweep
```

The `req_inner` column reports the largest swept inner tolerance that passed the
final robust feasibility check for that case and baseline. Rows with status
`inner_verified_final_infeasible` are deliberately retained: they are cases where
the oracle loop reported convergence at its inner tolerance but failed the final
pessimization pass at the requested robust tolerance.

To sweep requested robust tolerances with a refined ratio grid and verify the
empirical coupling `inner = O(outer)`:

```bash
uv run python benchmarks/ellipsoid_support.py --case large --baseline eager --refined-tolerance-sweep --repeat 2 --csv tmp/benchmarks/ellipsoid_tolerance_refined.csv
```

To test repeated-solve amortization for exact SOCP atoms:

```bash
uv run python benchmarks/ellipsoid_support.py --suite amortization --workload-size 50 --baseline lazy --csv tmp/benchmarks/ellipsoid_amortization.csv
```

Run the quadratic S-lemma SDP benchmark:

```bash
uv run python benchmarks/quadratic_ellipsoid.py
```

This compares exact SDP compilation for quadratic ellipsoidal payloads against a
cutting-plane baseline with a numerical trust-region pessimizer. The `oracle_it`
column reports trust-region secular iterations, so this suite is the first place
where inner-oracle work is not just a closed-form norm evaluation.

To generate the fixed-activity quadratic `m x d` crossover grid:

```bash
uv run python benchmarks/quadratic_ellipsoid.py --suite grid --repeat 5 --baseline eager --csv tmp/benchmarks/quadratic_grid.csv
```

To test repeated-solve amortization for quadratic S-lemma SDP atoms:

```bash
uv run python benchmarks/quadratic_ellipsoid.py --suite amortization --workload-size 50 --baseline lazy --csv tmp/benchmarks/quadratic_amortization.csv
```

To validate the empirical decision rule on generated summary CSVs:

```bash
uv run python benchmarks/decision_rule.py tmp/benchmarks/ellipsoid_smoke.csv tmp/benchmarks/ellipsoid_scale_m200.csv tmp/benchmarks/ellipsoid_activity.csv tmp/benchmarks/ellipsoid_amortization.csv tmp/benchmarks/quadratic_smoke.csv tmp/benchmarks/quadratic_scale.csv tmp/benchmarks/quadratic_activity_controlled.csv tmp/benchmarks/quadratic_grid.csv tmp/benchmarks/quadratic_amortization.csv --target core --out tmp/benchmarks/decision_rule_core_apriori_loso.csv
uv run python benchmarks/decision_rule.py tmp/benchmarks/ellipsoid_smoke.csv tmp/benchmarks/ellipsoid_scale_m200.csv tmp/benchmarks/ellipsoid_activity.csv tmp/benchmarks/ellipsoid_amortization.csv tmp/benchmarks/quadratic_smoke.csv tmp/benchmarks/quadratic_scale.csv tmp/benchmarks/quadratic_activity_controlled.csv tmp/benchmarks/quadratic_grid.csv tmp/benchmarks/quadratic_amortization.csv --target wall --feature-set wall --out tmp/benchmarks/decision_rule_wall_features_loso.csv
```

By default the validator uses deployable pre-baseline features and
leave-one-suite-out validation. Use `--feature-set wall` for deployable
modeling-overhead and cut-policy features; pass `--feature-set leaky` only for
diagnostics.

See `docs/BenchmarkAnalysis.md` for the current benchmark interpretation and
reproduction commands. The frozen CSV snapshot behind the paper's benchmark
table is in `docs/benchmark_artifacts/`. See `docs/PriorArtSweep.md` for the
working map of nearby robust-optimization modeling, compiler, and oracle-method
prior art.

The prototype is intentionally small. It exposes the core research loop from
the Residual Compilation paper: match robust atoms, emit deterministic conic
constraints with a certificate, and keep enough cost metadata to decide when an
atom should stay behind a pessimizing oracle instead of being compiled.

License
-------

Code and project support files are licensed under the MIT License. The
ResidualCompilation paper is licensed under Creative Commons Attribution 4.0
International (CC BY 4.0). See `LICENSE` for the artifact-specific terms.
