Metadata-Version: 2.4
Name: polar-high
Version: 1.1.2
Summary: Python library for building indexed linear and mixed-integer programs in polars; assembles into HiGHS, exportable as MPS.
Author-email: Juha Kiviluoma <juha.kiviluoma@nodal-tools.fi>
Maintainer-email: Juha Kiviluoma <juha.kiviluoma@nodal-tools.fi>
License: Apache-2.0
Project-URL: Homepage, https://github.com/nodal-tools/polar-high
Project-URL: Documentation, https://nodal-tools.github.io/polar-high/
Project-URL: Issues, https://github.com/nodal-tools/polar-high/issues
Project-URL: Changelog, https://github.com/nodal-tools/polar-high/blob/main/CHANGELOG.md
Keywords: optimization,linear-programming,lp,mip,highs,polars,edsl
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: highspy
Requires-Dist: polars
Requires-Dist: numpy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff>=0.6; extra == "lint"
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: mike; extra == "docs"
Requires-Dist: mkdocs-include-markdown-plugin; extra == "docs"
Dynamic: license-file

# polar-high

[![PyPI](https://img.shields.io/pypi/v/polar-high.svg?v=1)](https://pypi.org/project/polar-high/)
[![Python versions](https://img.shields.io/pypi/pyversions/polar-high.svg?v=1)](https://pypi.org/project/polar-high/)
[![License](https://img.shields.io/pypi/l/polar-high.svg?v=1)](https://github.com/nodal-tools/polar-high/blob/main/LICENSE)
[![tests](https://img.shields.io/github/actions/workflow/status/nodal-tools/polar-high/test.yml?branch=main&label=tests)](https://github.com/nodal-tools/polar-high/actions/workflows/test.yml)
[![docs](https://img.shields.io/github/actions/workflow/status/nodal-tools/polar-high/docs.yml?branch=main&label=docs)](https://nodal-tools.fi/polar-high/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

A Python library for building and solving large linear and
mixed-integer programs. Variables and parameters are
[polars](https://pola.rs/) DataFrames, expressions are joined and
grouped lazily, and the matrix is assembled directly through
[HiGHS](https://highs.dev/) — 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

```bash
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.

```python
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](https://github.com/jimporter/mike) for per-version
reads.

- **[Concepts](https://nodal-tools.fi/polar-high/latest/concepts/)** —
  the indexed-frame mental model (`Var`, `Param`, `Sum`, `Where`,
  `Lag`, broadcasting/join semantics).
- **[Guide](https://nodal-tools.fi/polar-high/latest/guide/warm-starting/)** —
  warm-starting, Lagrangian decomposition, performance tuning,
  debugging.
- **[API reference](https://nodal-tools.fi/polar-high/latest/reference/api/)** —
  autogenerated from docstrings.
- **[Compare](https://nodal-tools.fi/polar-high/latest/compare/alternatives/)** —
  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](https://github.com/irena-flextool/flextool) energy-system
modelling toolkit.
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](LICENSE) and [NOTICE](NOTICE).
Changelog: [CHANGELOG.md](CHANGELOG.md).
