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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

polar_high-3.6.0.tar.gz (414.9 kB view details)

Uploaded Jul 9, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

polar_high-3.6.0-py3-none-any.whl (257.2 kB view details)

Uploaded Jul 9, 2026 Python 3

File details

Details for the file polar_high-3.6.0.tar.gz.

File metadata

Download URL: polar_high-3.6.0.tar.gz
Upload date: Jul 9, 2026
Size: 414.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for polar_high-3.6.0.tar.gz
Algorithm	Hash digest
SHA256	`fd0a41731e3a7dd3b50cc1bcf481d74ca97b83cdd5bf7596e0b10af9e98dd75c`
MD5	`071a58170a64a8fd8a7bf6827389e8b2`
BLAKE2b-256	`f92fe7caa787f0f9fb6aec7754ecc791d0237374ab8c26ac3b252c5507599a30`

See more details on using hashes here.

Provenance

The following attestation bundles were made for polar_high-3.6.0.tar.gz:

Publisher: release.yml on nodal-tools/polar-high

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: polar_high-3.6.0.tar.gz
- Subject digest: fd0a41731e3a7dd3b50cc1bcf481d74ca97b83cdd5bf7596e0b10af9e98dd75c
- Sigstore transparency entry: 2126820148
- Sigstore integration time: Jul 9, 2026
Source repository:
- Permalink: nodal-tools/polar-high@1465a27d2da0071d3c16e3e625e6e224ac407dc8
- Branch / Tag: refs/tags/v3.6.0
- Owner: https://github.com/nodal-tools
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1465a27d2da0071d3c16e3e625e6e224ac407dc8
- Trigger Event: push