Skip to content

Installation

Experimental

polarobi is unstable and experimental. Its API may change without notice, and it builds on private internals of gurobipy. Use it for production models only if you can verify the result, for example by comparing the model's Fingerprint with a model built another way, or if you have other strong guarantees that the model is correct.

polarobi requires Python 3.12 or higher.

pip install polarobi
uv add polarobi
poetry add polarobi

Dependencies

polarobi has just two dependencies:

  • gurobipy: The Gurobi Python API, and with it the Gurobi library itself.
  • polars: DataFrames.

It does not need numpy. polars exchanges data with the native module through the Arrow PyCapsule interface.

gurobipy is pinned to a minor version

polarobi registers its variables and constraints with gurobipy through some of gurobipy's private attributes, so each polarobi release supports a single gurobipy minor version, currently 14.0. See How it Works for the details.

Gurobi License

polarobi uses whatever license gurobipy finds. The size-limited license that comes with the gurobipy package is enough to try it on small models; anything larger needs a full Gurobi license.

Building from Source

The native module is written in Rust and built with maturin. You need a Rust toolchain and uv:

git clone <repository> && cd polarobi
uv sync

uv sync compiles the extension and installs polarobi into the project's environment, rebuilding it whenever the Rust sources change. uv build produces a wheel for your platform.

Type Checking

polars registers namespaces at runtime, so type checkers do not know about df.grb and treat its calls as untyped. Python's type system has no way to declare an attribute on another package's class, so there is no annotation that fixes that.

df.grb is an instance of polarobi.GurobiFrame, constructed with the frame. Constructing it yourself gives you the same namespace, fully typed. A short alias keeps the calls readable:

import gurobipy as gp
import polars as pl
from polarobi import GurobiFrame as grb

orders = pl.DataFrame({"order": ["o1", "o2"], "value": [3.0, 5.0]})
model = gp.Model()

x = grb(orders).add_vars(model, by=["order"], vtype="B", obj="value")
assign = grb(x).add_constr(model, sense="<=", rhs=1.0)
constraints = grb(assign).handles(model, kind="constr")  # list[gp.Constr]

Type checkers then check every argument and know every return type: add_vars returns a pl.DataFrame, handles(kind="constr") a list[gp.Constr], and a misspelled keyword is an error.

In a chain of polars calls, pipe does the same:

x = orders.filter(pl.col("value") > 4).pipe(grb).add_vars(model, vtype="B", obj="value")

grb(df) and df.grb are the same class doing the same work, so both forms can be mixed freely. polarobi itself is fully typed, and its own sources check cleanly under strict basedpyright.