Examples¶

This page lists every model in the repository, which constructs each exercises and whether an outside optimum checks its answer, so you can decide whether the language can say yours.

Three questions: can it say my model? · is it readable? · does it get the right answer? The first and the third are the two tables on this page. The second is each model page, where the file sits beside the same model written on another stack.

Every page starts from data in the shape preparing the data produces.

Every model¶

Teaching examples¶

PyPSA examples¶

Published optima¶

The three blocks on this page are generated. The catalogue comes from the site nav and each page's opening line. The constructs matrix comes from each model's resolved plan rather than its YAML text. The reference table comes from examples/ports/references.json, the file the tests assert against. pixi run python -m tools.constructs regenerates all three, and a test fails if any is stale.

Every page also carries the model as math, typeset from the file the engine builds by pixi run python -m tools.gallery_math and gated the same way. A model with a symbol table in examples/symbols/ is typeset in the notation of its own prose.

Can it say my model?¶

A model here is one spec with its data attached.

Every construct has a verified model behind it, one whose optimum came from somebody else. The witness for roll / shift is ramp limits, for integrality unit commitment, and for piecewise economies of scale.

A tick is a floor, not a ceiling. One verified model exercises the construct. It does not cover every shape of the construct, or the construct in combination with others.

Does it get the right answer?¶

✔ means the optimum did not come from specsolve. It came from a figure published with the model or from a reference implementation hand-written on another stack. The provenance column says which. Every model on this page runs in the test suite, so a test alone distinguishes nothing. The badge marks the one check that catches a shared misreading, the differential suite's blind spot: both lanes agreeing on a meaning the modeller did not intend. This table is the evidence behind the limits of the language.

A duals tick means the shadow prices are checked too, against the reference's own. For the PyPSA models that is buses_t.marginal_price, the nodal price. A dual vector is where two implementations most often disagree quietly: which side of a constraint the price belongs to, and what sign an inequality carries. Dantzig transport is checked because both of its constraints are inequalities pointing opposite ways. A MILP has no dual solution, and specsolve does not invent one; those are the · rows.

Adding a port is four files and five rules: CONTRIBUTING.md.

PyPSA, one feature at a time¶

The PyPSA ladder is the conformance instrument. It holds sixteen networks, each carrying what the one below it did not. Each is solved through PyPSA and through specsolve and compared four ways: the objective, the constraint and variable names, the size of the model handed to the solver, and every constraint's dual. A difference needs a recorded reason or the run is red. The numbers are there.

The PyPSA pages above are the gallery. Each shows one idiom, held by a test to an optimum that did not come from specsolve. A page shows how something is said; the ladder shows that it is said exactly. What could not be said is a row in the ledger.

The first pages grow one network a feature at a time: a transport model, then ramp limits on a widened instance, storage, a cyclic horizon that deletes a clause rather than adding one, KVL (Kirchhoff's voltage law) with the cycle basis as a parameter, and AC-DC with two load-bearing coordinates on one dimension. Each page says what it shows.

Ledger — what a port could not say¶

Each row feeds the roadmap with the verdict AGENTS.md asks for: macro, primitive, formulation, or refused.

Minimum up and down times says min_up_time as sum_back(start_up, along=snapshot, window=min_up_time), each generator's own width read off the column.

Two rows from 33 ports is the current rate.

Shapes still without a witness¶

The language can say each of these; no outside model in the corpus has yet been found to need it. Each row is a standing request, not a gap:

A model that needs one of these is worth more to the corpus than one that exercises a shape already covered.

The TSP row is narrower than it reads. The DFJ (Dantzig–Fulkerson–Johnson) subtour rows written out in full are sayable, and the TSP page draws the line between that and lazy generation.