polar-high

A Python library for building and solving large linear and mixed-integer optimisation programs, i.e. domain specific language (DSL) for algebraic modelling. 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/MIP 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 Param, Problem, Sum

p = Problem()

# Index sets — declared once, reused below
unit_index = pl.DataFrame({"unit": ["wind", "coal"]})
time_index = pl.DataFrame({"hour": [1, 2, 3]})
composite_index = unit_index.join(time_index, how="cross")

# Decision variable v_production[unit, hour] >= 0
v_production = p.add_var(
    "v_production",
    dims=("unit", "hour"),
    index=composite_index,
    lower=0.0,
)

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

# Available capacity per unit per hour — built per-unit, then concatenated
cap_wind = time_index.with_columns(
    pl.lit("wind").alias("unit"),
    pl.Series("value", [3.0, 1.0, 4.0]),
)
cap_coal = time_index.with_columns(
    pl.lit("coal").alias("unit"),
    pl.Series("value", [10.0, 10.0, 10.0]),
)
cap = Param(
    ("unit", "hour"),
    pl.concat([cap_wind, cap_coal]).select("unit", "hour", "value"),
)

# Demand per hour
demand = Param(
    ("hour",),
    time_index.with_columns(pl.Series("value", [5.0, 6.0, 4.0])),
)

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

# v_production[unit, hour] <= cap[unit, hour]
p.add_cstr(
    "capacity",
    over=composite_index,
    lhs_terms={"production": v_production},
    sense="<=",
    rhs_terms={"cap": cap},
)

# Σ_unit v_production[unit, hour] == demand[hour]
p.add_cstr(
    "demand_balance",
    over=time_index,
    lhs_terms={"production": Sum(v_production, over=("unit",))},
    sense="==",
    rhs_terms={"demand": demand},
)

sol = p.solve()
print(f"objective: {sol.obj}")  # 72.0
print(sol.value("v_production"))

The same code lives at tests/fixtures/quickstart_example.py and is executed in the test suite, so README and docs stay in sync.

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, decomposition building blocks, 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 (still in dev branch only, 7.5.2026 situation). FlexTool's fleet of system tests (from earlier GNU MathProg to HiGHS implementation) has been used to test polar-high in real modelling use cases. In addition polar-high kernel has its own set of unit and system tests.

Created by

polar-high was created by Juha Kiviluoma of Nodal-Tools using Claude Opus.

License

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