specsolve¶

Solve an optimisation problem written in YAML. Attach your data as tables, and keep the solver loaded for quick updates and warm starts.

Run a model Browse the examples

specsolve solves mathspec specs. A spec states the math, and mathspec checks it before any data exists. specsolve attaches your tables to the spec, builds the resulting model on polars, and hands it to HiGHS, Gurobi or Xpress.

What it is for¶

Tables in, tables out. Pass any Arrow table, such as polars, pandas or DuckDB, or a parquet path. Results come back as tables, and an archive keeps the spec, its data and its results as parquet, ready for queries, plots or BI. Tables in, tables out →
Sweeps and rolling horizons built in. One call runs scenario sweeps, rolling horizons and myopic pathways over the same spec. Each window is checked against how the model couples before it runs. Sweep a model →
Fast, and hard to get wrong. Tables hold only the rows that exist, so a model's topology does not change its cost. The solver stays loaded: update() puts new numbers on it, and keep='progress' warm-starts from the last run. The API is a handful of verbs, with nothing to tune. Benchmarks →
Validated against PyPSA. PyPSA's model is one file here, grown rung by rung through storage, unit commitment, multi-period and stochastic runs. All 16 rungs match PyPSA's objective, and 12 match its duals row for row. The PyPSA ladder →

A spec is one file¶

# dispatch.yaml
dimensions:
  snapshot: {dtype: int}
  generator: {dtype: str}
parameters:
  p_max: {dims: [generator]}
  load:  {dims: [snapshot]}
  cost:  {dims: [generator]}
variables:
  p:
    dims: [snapshot, generator]
    where: "p_max > 0"
    bounds: {lower: 0, upper: p_max}
constraints:
  power_balance:
    dims: [snapshot]
    expression: sum(p, over=generator) == load
objective:
  sense: minimize
  expression: sum(p * cost)

The math it states¶

Printed from the file above, with no data and no solver. How shows the call.

The mathLaTeXHow

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

Sets¶

Symbol	Meaning
\(\mathcal{S}\)	index \(s\) — `snapshot` — dispatch periods
\(\mathcal{G}\)	index \(g\) — `generator` — generating units

Parameters¶

Symbol	Meaning
\(\bar p\)	`p_max` over \(\mathcal{G}\) — installed capacity
\(\ell\)	`load` over \(\mathcal{S}\) — demand to be met
\(c\)	`cost` over \(\mathcal{G}\) — marginal cost

Variables¶

Symbol	Meaning
\(p\)	`p` over \(\mathcal{S} \times \mathcal{G}\) — output of a generator in a snapshot

Objective¶

\[ \min \sum_{s \in \mathcal{S},\ g \in \mathcal{G}} p_{s,g} \cdot c_{g} \]

Subject to¶

power_balance

\[ \sum_{g \in \mathcal{G}} p_{s,g} = \ell_{s} \qquad \forall\, s \in \mathcal{S} \]

Variable domains¶

p

\[ 0 \le p_{s,g} \le \bar p_{g} \qquad \forall\, s \in \mathcal{S},\ g \in \mathcal{G} \,:\, \bar p_{g} > 0 \]

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

\paragraph{Sets}
\begin{description}
\item[{$\mathcal{S}$}] index $s$ --- \texttt{snapshot} --- dispatch periods
\item[{$\mathcal{G}$}] index $g$ --- \texttt{generator} --- generating units
\end{description}

\paragraph{Parameters}
\begin{description}
\item[{$\bar p$}] \texttt{p\_max} over $\mathcal{G}$ --- installed capacity
\item[{$\ell$}] \texttt{load} over $\mathcal{S}$ --- demand to be met
\item[{$c$}] \texttt{cost} over $\mathcal{G}$ --- marginal cost
\end{description}

\paragraph{Variables}
\begin{description}
\item[{$p$}] \texttt{p} over $\mathcal{S} \times \mathcal{G}$ --- output of a generator in a snapshot
\end{description}

\paragraph{Objective}
\begin{align}
 && \min & \sum_{s \in \mathcal{S},\ g \in \mathcal{G}} p_{s,g} \cdot c_{g}
\end{align}

\paragraph{Subject to}
\begin{align}
\text{power\_balance} && \sum_{g \in \mathcal{G}} p_{s,g} & = \ell_{s} && \forall\, s \in \mathcal{S}
\end{align}

\paragraph{Variable domains}
\begin{align}
\text{p} && 0 \le p_{s,g} & \le \bar p_{g} && \forall\, s \in \mathcal{S},\ g \in \mathcal{G} \,:\, \bar p_{g} > 0
\end{align}

import mathspec as ms

symbols = {
    'notation': 'latex',
    'dimensions': {
        'snapshot': {'index': 's', 'set': '\\mathcal{S}'},
        'generator': {'index': 'g', 'set': '\\mathcal{G}'},
    },
    'names': {
        'cost': 'c',
        'load': '\\ell',
        'p_max': '\\bar p',
    },
}

ms.to_latex('dispatch.yaml', symbols=symbols)  # amsmath align
ms.to_typst('dispatch.yaml')  # compiles without a TeX toolchain
ms.to_markdown('dispatch.yaml')  # renders as-is on GitHub

symbols is optional — drop it and the same model prints as \(\mathit{load}_t\), \(p^{\mathrm{max}}_g\). A dict, a YAML path or a SymbolTable; a key naming nothing in the model is an error, not a symbol that silently never applies. Every spelling is printed verbatim — notation says which language they are, and a render in the other one refuses.

Or from a shell, where the table is that same YAML on disk and --standalone emits a document that compiles rather than a fragment to \input:

python -m mathspec latex dispatch.yaml --symbols dispatch.symbols.yaml
python -m mathspec typst dispatch.yaml --standalone -o dispatch.typ

The renderer is mathspec's, and reads the same file this page solves.

Solve it¶

import specsolve as sps, polars as pl

generators = ['wind', 'solar', 'gas']
sources = {  # (1)!
    'p_max': pl.DataFrame({'generator': generators, 'value': [100.0, 60.0, 200.0]}),
    'cost': pl.DataFrame({'generator': generators, 'value': [1.0, 2.0, 50.0]}),
    'load': pl.DataFrame({'snapshot': range(6), 'value': [80.0, 120.0, 150.0, 180.0, 140.0, 100.0]}),
    'snapshot': range(6),
    'generator': generators,
}

result = sps.solve('dispatch.yaml', sources, archive='runs/base/')  # (2)!
print(result.objective)  # 1920.0
print(result.primal('p'))  # (3)!
print(result.dual('power_balance'))

base = sps.scan_archive('runs/base/')  # (4)!
print(base.answer.primal('p').group_by('generator').agg(pl.col('value').sum()))

A source is any table: polars, pandas, pyarrow or DuckDB. It can also be a parquet path, such as 'load': 'load.parquet'.
archive= writes the spec, the data and the answer to runs/base/ as parquet files.
A tidy table, with one row per snapshot and generator.
scan_archive reads the archive where it lies. base.sources are parquet paths, so sps.solve(base.spec, base.sources) asks the same question again.

Where to next¶

Run a model: a file and your tables to an answer, in five steps.
Your data: from the files an instance arrives in to one table per parameter, and what attaching refuses.
Python API: attach, build, solve and read back, and sweep one spec over scenarios.
The language: what a file may contain, on mathspec's site.
About: the architecture, the measured cost, and what will never be built.

Install it¶

pip install specsolve

Installation lists the extras.

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. A retired spelling fails at load and names its rewrite. Real models round-trip through solve and are tested against linopy. The accepted surface is not yet frozen.