residopt 0.1.0

Residual compilation prototype for robust optimization models

residopt

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

Paper: Residual Compilation (Zenodo PDF)

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:

uv run python examples/robust_regression.py

Run tests:

uv run pytest

Run the ellipsoid support benchmark:

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:

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:

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

Larger optional random cases are available with:

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

To test tolerance coupling in the oracle layer:

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):

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:

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:

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:

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:

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:

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.