polar-high 1.1.0

Python library for building indexed linear and mixed-integer programs in polars; assembles into HiGHS, exportable as MPS.

polar-high

A Python library for building and solving large indexed linear and mixed-integer programs. Variables and parameters are polars DataFrames, expressions are joined and grouped lazily, and the matrix is assembled directly through HiGHS — or exported as MPS for any other LP solver. The kernel is intentionally domain-free: it has no opinions about energy systems, supply chains, or any specific application.

Install

pip install polar-high

Requires Python 3.11+. HiGHS ships in highspy, no separate install.

Quickstart

A tiny dispatch LP — wind + coal over three hours, minimise cost subject to capacity and per-hour demand.

import polars as pl
from polar_high import Problem, Param, Sum

p = Problem()

v_idx = pl.DataFrame({
    "unit": ["wind", "wind", "wind", "coal", "coal", "coal"],
    "hour": [1, 2, 3, 1, 2, 3],
})
v_production = p.add_var("v_production", dims=("unit", "hour"),
                         index=v_idx, lower=0.0)

cost = Param(("unit",),
             pl.DataFrame({"unit": ["wind", "coal"],
                           "value": [2.0, 8.0]}))

cap = Param(("unit", "hour"), pl.DataFrame({
    "unit":  ["wind", "wind", "wind", "coal", "coal", "coal"],
    "hour":  [1, 2, 3, 1, 2, 3],
    "value": [3.0, 1.0, 4.0, 10.0, 10.0, 10.0],
}))

demand = Param(("hour",),
               pl.DataFrame({"hour": [1, 2, 3], "value": [5.0, 6.0, 4.0]}))

p.set_objective(cost * v_production, sense="min")

p.add_cstr("capacity", over=v_idx, sense="<=",
           lhs_terms={"production": v_production},
           rhs_terms={"cap": cap})

p.add_cstr("demand_balance",
           over=v_idx.select("hour").unique().sort("hour"),
           sense="==",
           lhs_terms={"production": Sum(v_production, over=("unit",))},
           rhs_terms={"demand": demand})

sol = p.solve()
print(sol.obj, sol.value("v_production"))

Documentation

Full docs at https://nodal-tools.fi/polar-high/ — published with MkDocs + mike for per-version reads.

• Concepts — the indexed-frame mental model (Var, Param, Sum, Where, Lag, broadcasting/join semantics).
• Guide — warm-starting, Lagrangian decomposition, performance tuning, debugging.
• API reference — autogenerated from docstrings.
• Compare — how polar-high relates to Pyomo, JuMP, gurobipy, linopy, and GNU MathProg.

Build locally: pip install -e ".[docs]" && mkdocs serve.

Used by

polar-high is the build engine behind the FlexTool energy-system modelling toolkit (not in master branch yet). FlexTool's test fleet — comparing the new implementation against the earlier GNU MathProg one across many scenarios — has been used as validation for the kernel in addition to kernel's own testing.

License

Apache-2.0 — see LICENSE and NOTICE. Changelog: CHANGELOG.md.