Repository navigation
Releases: energy-models/mathspec
Release list
0.2.1
A spec can now be written as several files. merge
composes fragments, each a spec that owns part of the math and reads what
another file declares under given:. override
lays patches over a base, each changing part of it. A named expression adds
itself as a term to a sum with adds_to:, and one fragment sets the objective.
Every fragment typesets on its own, in LaTeX, Typst and Markdown, and gets
advice before any merge: what it reads from another file prints in its legend,
so one component's math can be reviewed without the rest of the model.
PyPSA in 24 files
is the PyPSA spec composed this way, and merges back to the one file.
Nothing a 0.2.0 file or call does stops working. Two rules of the language
are now stated exactly. A consumer that attaches data refuses a null or NaN
parameter value: a coordinate with no value has no row, and inf and -inf
are values (#788). And
dual(c) is the rate at which the optimal objective rises with the right side
of c, for every comparator and under either sense, which is what engines
return (#751).
The pull requests in this release:
Composition
- feat(language): a spec is composed from files that each state part of it, and patched with files that each change part of it (#732)
- feat(language): a term names the sum it adds to with
adds_to:, agiven: expressions:entry of its own file, and a sum another file defines takes terms too (#763) - feat(language): merge refuses a second objective, and a composed objective reads a sum that each file adds its part to (#763)
- fix(language): merge and override take a list of files, and its order is the order of the terms and of the patches (#761)
- fix(language): a merged spec's descriptions do not depend on the order the fragments are passed in, and a reader's fills one its owner left out (#739)
- fix(language): a given declaration that leaves out its domain or dtype folds into an introducer that sets one (#768)
- fix(language): a file whose terms read each other's sums is refused at load (#780)
- fix(language): a where that reads a given expression names it as a given expression, not as a variable (#809)
- refactor(language): a term prints as the definition it is, and one rule folds every reading (#738)
- fix(typeset): a term a file adds to a sum keeps its definition line when the expressions are inlined (#766)
Language
- feat(language): two files that state the same spec write one text, and
canonical --checkfails a file that is not in it (#731) - feat(language): a named expression may declare the frame it is read over (#741)
- feat(language): a sum names several dimensions in one over= list (#778)
- feat(language): a divisor or a power over parameters may add, so a discount factor is written where it is used (#757)
- feat(language): a parameter value that is null or NaN is refused when the data is attached (#788)
- fix(language): dual(c) is the rate at which the optimal objective rises with the right side of c, so an equality has a sign too (#751)
- fix(language): a cases block with one case may compare expressions in its when: (#795)
- fix(language): a where string names several columns in at's over= and into=, as an expression does (#782)
- fix(language): a macro formal written inside a list takes the name the call binds to it (#779)
Typesetting and advice
- fix(typeset): a substituted term that opens with a minus prints as a subtraction (#759)
- fix(advice): an objective that reads a given expression or an empty sum gets advice rather than a KeyError (#767)
Documentation
- docs(pypsa): a single spec covers every pypsa model class and component (#620)
- docs(pypsa): the pypsa spec is also 24 topic files that merge back to it, each component adding its share of a sum by name (#736)
- docs(pypsa): an efficiency, a rate or a phase shift may change from snapshot to snapshot (#717)
- docs: the composition how-to builds a component library from terms each file adds to a sum (#762)
- docs: the composition how-to shows a sum that one file defines and other files add terms to (#800)
- docs: a file restates a shared dimension as its dtype alone, and
mergecarries the one description written for it (#743) - docs(language): a reported quotient is absent where its divisor is zero, whether a solve or the data gave that zero (#765)
- docs(notation): the notation page shows a named expression whose declared frame is wider than its body (#756)
- docs: code examples on the site are readable in light and dark mode, and a diagram shows what mathspec leaves to engines and other tools (#730)
- docs: the site follows the reader's light or dark setting, and a page shows where it sits in the navigation (#727)
0.2.0
A file now states a specification, or spec. A model is a spec with
data attached, which an engine builds and a solver takes. mathspec holds specs
only. The API, the messages and the docs use the two words in these senses
(glossary).
This release breaks three things:
- The first parameter of
to_spec,advice,typeset,typeset_declaration,
to_latex,to_typstandto_markdownisspec, notmodel. A call that
passesmodel=by keyword fails. A positional call works as before. - The module
mathspec.modelis nowmathspec.spec.from mathspec import Spec
works as before. - Error and advice messages say "spec" where they said "model". A test that
matches the old text fails.
The pull requests in this release:
- feat!: what a file states is called a spec, the functions that read one take it as spec, and model means a spec with data (#721)
- docs: the README and the docs home page say that spec is short for specification (#724)
- fix(docs): the Python API pages link every name a docstring cites, and show advice as the function it is (#720)
0.1.0
🎉 mathspec is officially on PyPI!
pip install mathspec0.1.0rc1
The release candidate for 0.1.0, the first release on PyPI:
pip install mathspec==0.1.0rc1. The package installs, imports and runs as
mathspec since 0.0.0-alpha.127
(#702). The
0.0.0-alpha.N releases below were tags and GitHub releases only.
- docs: a page says how the package version and the language version of a model file relate (#711)
- docs: the installation page and the PyPI project page say
pip install mathspec, and the README's links resolve on PyPI (#707) - docs: every link to the documentation points at mathspec.readthedocs.io (#706)
v0.0.0-alpha.127
v0.0.0-alpha.126
v0.0.0-alpha.125
0.0.0-alpha.125 (2026-09-25)
Bug Fixes
- language: an unknown operator's refusal points at the limits page instead of an escape key that does not exist (#676) (5e4ef2b)
- language: messages and docs say data is attached rather than bound, so a bound is only a variable's limit (#694) (cc8ba08)
Documentation
- a development section holds the PyPSA parity pages and the contributing guide (#678) (a399bdd)
- a first tutorial writes the dispatch model one block at a time, checks it and prints it (#680) (48b60e8)
- a glossary defines each word the docs use in a fixed sense (#675) (2561ad8)
- each page keeps only what its reader needs, and a fact stated twice keeps one home (#686) (ef8dcb9)
- engine authors get a program api page rendered from math_spec.program, and the per-module pages and the file-and-program page are gone (#697) (784867a)
- one Python API page documents every public name, including the typesetting functions (#679) (ee5ffdf)
- the nav keeps tutorials, how-to guides, reference and about for model writers, and puts the rest under development (#683) (341ad2a)
- the notation page heads each section with the construct it shows (#682) (66faa7b)
- the readme and home page lead with what a user gets, and name specsolve and linopy as engines (#698) (9fda1bc)
- the readme drops the internals diagram and the repeated formats, and is a third shorter (#699) (234245b)
- what spec.expand() returns is documented on the model writer's python api page, and reading.md keeps only which program an engine reads (#696) (a9caeae)
- what spec.expand() returns is stated once, as a different model that binds the same data (#677) (413550e)