Background and history#
The specification of an optimisation model (a spec) takes its shape from development efforts in the Calliope energy system framework. The language of a spec has evolved considerably since porting to the framework-agnostic mathspec project. This evolution has moved the math further out of code and into a file that any piece of software (a tool) can read.
The problem#
In many open-source energy system modelling frameworks, the math lives in the source code as calls to a library such as Pyomo or linopy. A reader who wants the equations has to read that code or hand-written duplications of that math. A user cannot add a constraint without writing code and the documentation and the code can easily drift apart. A constraint can also only be validated by building a model with data.
Calliope set out to solve all four problems by moving the math into a human-readable YAML file. mathspec has continued that mission and has gone beyond what was achieved in Calliope, introducing even more features to make it easier to write and validate your math.
Note
Some modelling frameworks use algebraic modelling languages instead, which are programming languages built especially for writing out the math of an optimisation problem (e.g. AMPL or GAMS). While their syntax is close to the math, they don't offer the flexibility of more popular programming languages such as Python or Julia. Those which have widespread usage are also proprietary; few viable open-source alternatives exist.
Initial development record#
| When | What | Source |
|---|---|---|
| 2020-08 | Calliope maintainers begin discussions on YAML math formulations. | #100 |
| 2021-05 | @sjpfenninger sets the goal: every constraint in YAML, and the math documentation generated from it. | #360, #361 |
| 2023-02 | @brynpickering's parser lands, with foreach and the equation grammar. where is a string parsed with the parsing library pyparsing, and constraints are built from constraints.yaml on the labelled-array library xarray. |
PR #397, #408, #411 |
| 2023 | A user can replace the built-in math with their own file. The documentation of the math is generated from a built model. A schema validates the math files. | PR #414, #442, #454 |
| 2024-01 | The syntax is documented, and 0.7.0.dev2 is the first published release with all of its math in YAML. | PR #456, 0.7.0.dev2 |
| 2024 - 2026 | Calliope adds piecewise constraints, direct Gurobi and HiGHS solver engines, dispatch and MGA math, and post-solve expressions. | PR #551, #569, #716, #839 |
| 2026-03 | @FBumann creates lpspec (later specsolve): declarative linear and mixed-integer linear programs (LP and MILP) on a streaming relational query library. Its math language develops from a port of Calliope's. | specsolve, PR #336 |
| 2026-08 | The language and the typesetter are extracted from specsolve into a repository of their own. specsolve becomes one engine among many. | PR #17 |
| 2026-08 | The PyPSA math is written as a spec to prove its viability. | PR #134 to #143 |
| 2026-09 | Calliope 0.7.0 is released, its first stable release with YAML math; the Calliope math is rewritten as a spec to prove its viability. | 0.7.0, PR #770 |
| 2026-09 | The first post-alpha release of mathspec is published on the Python Package Index; specsolve depends on mathspec 0.1.0 and fluxopt math is written as a spec. |
0.1.0, specsolve #1754, fluxopt #358 |
People and organisations#
Calliope is developed in the calliope-project organisation by those listed in its AUTHORS file. specsolve is developed by @FBumann in the fluxopt organisation. mathspec is developed in the framework-agnostic energy-models organisation (contributors).
See also
- versions, for how the package version and the language version relate
- how mathspec works, for what mathspec does with a spec today