Skip to content

specsolve

Optimisation as a data pipeline. Tables in, polars builds the model, tables out. Every solve can be kept as parquet, to query, share or solve again.

CI PyPI Python Docs License: MIT

Your first model Browse the examples Benchmarks

specsolve solves linear and mixed-integer models from tables. You pass a model file and your data as Arrow tables or parquet paths. specsolve builds the model on polars, hands it to HiGHS, Gurobi or Xpress, and returns tidy tables. The model file is written in mathspec, which states the math and checks it before any data exists.

What it is for

  • Tables in, tables out. Pass any Arrow table, such as polars, pandas or DuckDB, or a parquet path. Each variable, dual and expression comes back as a tidy table with one row per coordinate. Your data →
  • Every solve is an archive. archive= writes the model, its data and its answer as parquet, with the solver and versions that made it. scan_archive reads it where it lies and solves the same question again, and a directory of runs reads as one set of tables. Archiving a solve →
  • Fast from the first call. A script that builds one small model and hands it to the solver finishes in about half a second, about half of linopy's time (#2031). The solver stays loaded: update() puts new numbers on it, and the next solve carries on from where the last one ended. Benchmarks →
  • No slow way to write a model. In linopy or Pyomo, the model is Python code, and slow code builds slowly. A specsolve model is a YAML file with data attached, and specsolve makes sure it builds fast. Coming from linopy →
  • Sweeps and rolling horizons built in. One call runs scenario sweeps, rolling horizons and myopic pathways over the same model. specsolve checks each window against how the model couples before it runs. A horizon too large for one solve →
  • Validated against PyPSA. PyPSA's model is one file here, grown rung by rung through storage, unit commitment, multi-period and stochastic runs. All 58 rungs match PyPSA's objective, and 36 match its duals row for row. The PyPSA ladder →

Built on mathspec

specsolve and mathspec split one job, and both read the same model file.

  • mathspec states the model. A YAML file of dimensions, parameters, variables, constraints and an objective. mathspec checks the file with no data, and prints it as math for a paper. The language →
  • specsolve solves it. specsolve attaches your tables to the file, builds the model on polars, solves it, and keeps the answer as parquet. Your first model →

A model 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 file holds no data, so you can check and diff it before any data exists, and print it as math.

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.result.primal('p').group_by('generator').agg(pl.col('value').sum()))
  1. A source is any table: polars, pandas, pyarrow or DuckDB. It can also be a parquet path, such as 'load': 'load.parquet'.
  2. archive= writes the spec, the data and the answer to runs/base/ as parquet files.
  3. A tidy table, with one row per snapshot and generator.
  4. 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.

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.