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.
1 maintainer
Metadata
1 maintainer
Release files for polar-high 3.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| polar_high-3.8.0.tar.gz | 431.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| polar_high-3.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 696.0 kB
Release files / polar_high-3.8.0.tar.gz
| Download URL | polar_high-3.8.0.tar.gz |
|---|---|
| Size | 431.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7d9e4ca4fe40deb7b04f6fc6969c26ae64119b87c8c4dfc70947659793a0e4d5
|
|
BLAKE2b-256 checksum How to use checksums |
36e199e668a7a5780e4289c558dda79dcd547f4a78f6f4be485070fcb68846f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency logRelease files / polar_high-3.8.0-py3-none-any.whl
| Download URL | polar_high-3.8.0-py3-none-any.whl |
|---|---|
| Size | 264.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
79bf350d746c4c0974b2e0e575cffe9af80c6a14371113e329c730d885aea64b
|
|
BLAKE2b-256 checksum How to use checksums |
bfc306c5d3283c72ae4a36815fae348ab853150a3cabb598f5de831881d46cbc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency log
