mathspec

Write the specification (spec) of an optimisation model as a YAML file. Check it and print it as math, with no data and no solver.

A mathspec file states a specification, or spec. A spec declares four things: the axes it runs over, such as snapshot and generator; the data it expects, such as load and cost; the decisions the solver makes, such as dispatch; and the rules those decisions obey, such as sum(dispatch, over=generator) == load. The file below is a complete spec.

mathspec builds nothing and solves nothing itself. specsolve and linopy build a model from a spec and its data, and solve it. Support in both is work in progress.

• Check specs in CI, with no data. A wrong name or dimension fails when the file loads, and the error names the fix. Errors →
• Publish the math you solve. The equations in the paper print from the file the solver reads. Typeset →
• One spec, many tools. Engines, renderers and analysers read the spec through one public API, so no two of them can read the file differently. Program API →
• Write full-size specs. The spec of PyPSA's n.optimize() model is one file, with stochastic, multi-period and quadratic variants. PyPSA in one file →

Example

description: Least-cost dispatch of a generator fleet against an hourly load.

dimensions:
  snapshot: { dtype: int, description: dispatch periods }
  generator: { description: generating units }

parameters:
  capacity: { dims: [generator], description: installed capacity }
  load: { dims: [snapshot], description: demand to be met }
  cost: { dims: [generator], description: marginal cost }

variables:
  dispatch:
    description: output of a generator in a snapshot
    dims: [snapshot, generator]
    where: "capacity > 0"
    bounds: { lower: 0, upper: capacity }

constraints:
  power_balance:
    dims: [snapshot]
    expression: sum(dispatch, over=generator) == load

objective:
  sense: minimize
  expression: sum(dispatch * cost)

The math it prints

The typesetter prints the file above as math, with no data and no solver. Markdown is one of three formats, and GitHub renders it here.

Least-cost dispatch of a generator fleet against an hourly load.

Objective

\min \sum_{t \in \mathcal{T},\ g \in \mathcal{G}} \mathit{dispatch}_{t,g} \cdot \mathrm{cost}_{g}

Subject to

power_balance

\sum_{g \in \mathcal{G}} \mathit{dispatch}_{t,g} = \mathrm{load}_{t} \qquad \forall\, t \in \mathcal{T}

Variable domains

dispatch

0 \le \mathit{dispatch}_{t,g} \le \mathrm{capacity}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \,:\, \mathrm{capacity}_{g} > 0

Each format is one call:

import mathspec as ms

spec = ms.to_spec('dispatch.yaml')

ms.to_markdown(spec)
ms.to_latex(spec)
ms.to_typst(spec)

A symbol table gives the names their conventional spelling, as in the folded block. Print a spec as math does the same from a shell.

Documentation

The documentation is at https://mathspec.readthedocs.io.

Installation

See installation. To work on mathspec, see contributing.

Prior art

Every file under src/ was written in specsolve and extracted here. The keys themselves, which are YAML math, a block per component, dims: and a where: string, come from Calliope. linopy supplies the vocabulary that sum(over=) and the dimension rules are named against.

Status

Alpha, pre-1.0.

Breaking changes land without a deprecation cycle. Pin an exact version if you depend on this, and read the changelog before upgrading. Every construct round-trips through the schema, the parsers and all three typeset formats, and the LaTeX is compiled. The accepted YAML is not yet frozen.

Licence

The code is MIT, and the prose is CC-BY-4.0.