feat(api): the feasible region of a model on two of its quantities is traced as a polygon

[FBumann]

Prompt: Is it possible to analyze the feasible region of an optimization problem? […] I want to analyze if I modeled sth correctly. Like in a complex multi component power plant. […] What would we need to visualize the feasible region or sth like it? […] Draft pr this […] Add the plotting […] How are binaries etc handled? We should handle all combinations, individual regions […] I want a way of having everything as a long form dff maybe? […] We need a nice extensive notebook showing this feature in the docs […] I think this feature could be a bit more self explanatory. Especially the data frames! Rethink the feature […] I think the plots could be nicer. Plotly? […] I can't see the plots in the docs

Note

The following content was generated by AI.

sps.project(spec, sources, x='heat', y='power', at={'t': 5}) traces the region two named quantities can reach. It returns a Region of tidy frames and a plotly plot(). binaries='each' traces every binary combination as its own piece. docs/region.md walks it on a CHP plant.

frame	columns
vertices	(piece, vertex, x, y)	every vertex of every piece, counter-clockwise; a free trace is piece 0
pieces	(piece, variable, dims…, value)	what each piece pinned, with the coordinate as typed columns; no rows when nothing was pinned
edges	(piece, edge, kind, name, dims…, side)	the variable bounds and constraint rows tight at both ends of an edge, at the coordinates at names
optimum	(piece, x, y)	where the model as written lands, and in which piece
hull	(vertex, x, y)	the region as one polygon; the hull of the pieces when they were traced apart

Every frame keeps its schema whether the binaries were free or traced apart. label(piece) spells a piece for a legend, such as running[chp]=1, running[boiler]=1, running[peaker]=0.

How it works

The probe. project adds ordinary declarations to the caller's spec: three scalar weights, two named expressions, and a one-hot selection parameter per axis where at fixes a coordinate. The objective becomes x_direction * x_axis + y_direction * y_axis + objective_weight * (the file's own), maximised. Four compass directions enclose the region. Then each hull edge is probed along its outward normal: a solve past the edge is a new vertex, a solve on it settles the edge. The trace ends when every edge is settled. All solves run on the fast path with keep='progress': one load, however many vertices. The optimum is one more solve with the directions at zero and the file's objective weighted ±1. A name the spec already declares is refused.

Edges. PolarsEngine.binding(result, tolerance) reads which bounds and rows a solve sits on, off the built model's handoff.cols and handoff.rows. An edge is bound by what is tight at both its ends. Rows at coordinates other than those at names are left out, and so are binaries.

Binaries. A binary makes the region a union of polygons, and a directional solve finds only the hull. binaries='each' adds two rows per binary, b >= b_at_least and b <= b_at_most, with both sides as data. A combination is then a right-hand side pushed onto the loaded solver, so loads stays at one. The pinned columns come from the first free solve's primal, so a column a where removed is not pinned. An infeasible combination is left out. Above 10 columns (1024 traces) it refuses and names at as the way to ask about fewer. integer variables are never pinned.

The picture. plot() needs the new [plot] extra (plotly). Each piece is a filled polygon in its own colour under its label. Hovering a vertex reads its coordinates. Hovering the middle of an edge reads the rows of edges, such as capacity[0, chp] at its upper. The optimum is a diamond naming its piece. plot(figure, name='hour 1') draws onto an existing figure with the next colours.

The page. docs/region.md runs at build time like the other tutorial pages. It traces a gas well feeding a CHP, a boiler and a peaker, each with a minimum load, over four hours. It reads every edge off edges, stacks every hour on one figure, traces the five feasible commitment states of eight, and breaks the model twice on purpose: no cap is named at the first direction, and a boiler that cannot idle names minimum_load. A small show(figure) helper prints figure.to_html(include_plotlyjs='cdn') into html="true" blocks. tests/test_tutorials.py runs the page and holds each claim.

Rebase onto main 68234d2, and gates

The branch was 88 commits behind, across the lpspec → specsolve rename. Its own changes are squashed into one commit and ported by hand:

• projection.py moved to src/specsolve/. lps is now sps, math_spec is now mathspec, and the name-clash check reads the spec's relations section.
• binding and expression_dims follow main's internals: model.handoff, program.expressions, PolarsCompiler(Scope(...)), SpecsolveError.
• src/ admits no Any (refactor: only the linopy lane and the solver sinks say Any #1699), so 19 annotations in projection.py use main's Buildable, Source, Label and Mapping[str, object]. A _section() helper narrows the spec dict. _shape imports plotly itself.
• One test writes the multi-link balance as sum(gen, by=gen_bus, over=generator, into=bus), because mathspec refuses the short form.
• Main replaced notebooks with pages that run at build time (docs: the site is built by zensical, and the two tutorials run as pages rather than notebooks #1693). docs/region.ipynb is now docs/region.md. Its tests moved from test_notebook.py into tests/test_tutorials.py with their assertions unchanged.
• The API page is built from docstrings, so the prose section is now a "Look at a model" subsection with ::: specsolve.project and ::: specsolve.Region. The list of names the probe adds moved into project's docstring.
• uv.lock was regenerated with uv lock. It adds plotly and narwhals only. The dev and docs pixi features take the plot extra.
• The changelog line is added.

Gates, in a uv venv with .[plot] and the dev and docs groups (pixi is unavailable in the sandbox):

• ruff check . and ruff format --check .: clean. pyrefly check: 0 errors.
• pytest -n 8: 3929 passed, 334 skipped, 1 xfailed, 10 failed. The 10 are gurobi and xpress cases that fail with ModuleNotFoundError in the sandbox; they fail the same way on main.
• test_projection.py: 44 passed. test_tutorials.py: 15 passed. zensical build --strict: clean; the region page holds 4 plotly figures.
• CI on d99c36a: every check green.

Not checked: the figures in a browser, whether their inline scripts run under Zensical's navigation.instant, and that plotly.js loads from the CDN once per figure (four times on the page).

Departures and what was not done

• projection.py reads model._program and model._engine: to learn a named expression's dims after the build, and what binds at a solve. The language exports no dims_of, and a walker over lowered nodes would be a second home for the dim algebra.
• Not done: per-axis coordinates (at is shared by both axes), rays for an unbounded region (it raises and names the direction), pinning integer variables, a matplotlib figure, committed figures.
• The mutation table was taken at 8b5ebdc against base 227ccdd, before the rethink and the rebase, and was not re-taken. Every mutation was caught: a lowered Program, the same quantity on both axes, an unknown quantity, at naming no declared dimension, a probe name the spec declares, at on a scalar quantity, at naming a dim the quantity does not carry, an infeasible model, an unbounded direction, the solve cap.

🤖 Generated with Claude Code

https://claude.ai/code/session_011BopadYhLNiGHaa37K5pC1

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 82 skipped benchmarks¹

---

_{Comparing claude/feasible-region-analysis-26xcox (d99c36a) with main (8c783ca)²}

Footnotes

1. 82 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. ↩

2. No successful run was found on main (68234d2) during the generation of this report, so 8c783ca was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[read-the-docs-community]

Documentation build overview

📚 lpspec | 🛠️ Build #34578978 | 📁 Comparing 5e07749 against latest (227ccdd)

  🔍 Preview build  

87 files changed · + 6 added · ± 80 modified · - 1 deleted

+ Added

• region/index.html
• howto/archiving/index.html
• howto/data/index.html
• howto/debug/index.html
• howto/parallel/index.html
• howto/warehouse/index.html

± Modified

• index.html
• about/benchmarks-scaling.html
• about/index.html
• examples/index.html
• guide/index.html
• interactive/index.html
• lifecycle/index.html
• about/architecture/index.html
• about/benchmarks/index.html
• about/changelog/index.html
• and 70 more...

- Deleted

• examples/data/index.html

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #34763738 | 📁 Comparing d99c36a against latest (68234d2)

  🔍 Preview build  

4 files changed

+ region/index.html
± about/architecture/index.html
± about/changelog/index.html
± reference/api/index.html