Skip to main content

polarobi

Build gurobipy models from polars frames. Columns go from Arrow memory into the Gurobi C API in one call per variable or constraint family, while the model stays fully usable through gurobipy.

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

orders = pl.DataFrame(
    {
        "order": ["o1", "o1", "o2", "o2", "o3"],
        "factory": ["f1", "f2", "f1", "f2", "f2"],
        "quantity": [40, 40, 25, 25, 60],
        "value": [120.0, 100.0, 100.0, 75.0, 120.0],
    }
)
capacity = pl.DataFrame({"factory": ["f1", "f2"], "capacity": [50, 80]})

model = gp.Model()
model.ModelSense = gp.GRB.MAXIMIZE

# One binary variable per order and factory, worth the order's value.
x = grb(orders).add_vars(model, by=["order", "factory"], vtype="B", obj="value", name="x")
# Each order is made at most once, and no factory exceeds its capacity.
grb(x).add_constrs(model, by="order", sense="<=", rhs=1.0, name="assign")
grb(x).add_constrs(
    model, capacity, by="factory", sense="<=", rhs="capacity", coef="quantity", name="cap"
)

model.optimize()
print(grb(x).get(model, "X").filter(pl.col("X") > 0.5))

grb(df) is the typed form of polars' df.grb namespace: both do the same, but type checkers only see the first. See Type Checking for why.

How it works

  • Model._cmodel holds the GRBmodel*. The native module binds to the Gurobi library that gurobipy already loaded (never a second copy) and checks that both report the same version.
  • Numeric columns are passed without copying (one concatenation if a column has several chunks). Names are copied, since C needs NUL-terminated strings.
  • New columns and rows are registered with gurobipy as gp.Var(cmodel, i) / gp.Constr(cmodel, i) handles in Model._internal_vars / Model._constrs. That is what keeps getVars, getVarByName, mixed expressions, remove, copy and friends working. The handles are created in Rust, at about half the cost of a Python loop over gurobipy's handle constructor.
  • Constraint and term order follow the input frames, so equal inputs build models with equal Fingerprints.

This relies on private gurobipy attributes (_cmodel, _internal_vars, _livevars, _constrs, _liveconstrs, _has_pending_deletions). Pin gurobipy to a minor version and keep tests/test_compat.py in CI.

Contributing

polarobi is a mixed Rust and Python project. The Rust extension in src/ is compiled by maturin into the module polarobi._native and packaged together with the Python sources in python/polarobi/. uv drives the whole thing: maturin is the project's build backend, so the usual uv commands compile the extension when needed.

Prerequisites

  • Rust, stable, installed with rustup, with the rustfmt and clippy components for the pre-commit hooks:
    rustup component add rustfmt clippy
    
    On Windows, rustup's default toolchain needs the MSVC build tools (Visual Studio Build Tools, "Desktop development with C++"). On macOS, the Xcode command line tools.
  • uv, which also provides Python. polarobi supports Python 3.12 and up; CI runs 3.14.
  • A Gurobi license that gurobipy finds. The size-limited license that ships with gurobipy is enough for the tests.

You do not need a Gurobi installation or SDK to compile: the extension does not link against Gurobi. At import it binds to the Gurobi library that gurobipy has already loaded into the process.

Setting up

uv sync --all-groups
uv run prek install

uv sync --all-groups creates .venv, installs the dev and benchmark dependencies and builds polarobi with maturin as an editable install: a .pth file points at python/, and the compiled extension is placed next to the Python sources as python/polarobi/_native.*.pyd (or .so). The type check covers the benchmarks too, so it needs the bench group. prek install sets up the pre-commit hooks below.

The build loop

  • Python changes take effect immediately, the package is installed in editable mode.
  • Rust changes are picked up by the next uv sync or uv run: [tool.uv] cache-keys in pyproject.toml lists Cargo.toml and src/**/*.rs, so uv rebuilds the extension when they change. This builds in release mode, which takes a while to compile.
  • For faster iterations on Rust code, build a debug extension in place and keep uv from rebuilding over it:
    uv run --no-sync maturin develop --uv
    uv run --no-sync pytest
    
    Debug builds compile quickly but run slowly, so use maturin develop --uv --release, or a plain uv sync, before benchmarking.
  • cargo check and cargo clippy work on src/ directly and are the quickest way to see compile errors.

Building wheels

uv build

builds an sdist and a wheel for the current platform into dist/. For a manylinux wheel from another platform, maturin can cross-compile with zig:

uvx maturin build --release --zig --target x86_64-unknown-linux-gnu

Wheels use Python's stable ABI (pyo3's abi3-py312 feature), so one wheel per platform, tagged cp312-abi3, works on every Python from 3.12 on.

Checks

The pre-commit hooks in prek.toml run on every commit. Run them on everything with:

uv run prek run --all-files
Hook Checks
uv-lock uv.lock matches pyproject.toml
ruff-format, ruff-check Python formatting and lints, fixed in place
basedpyright strict type checking of the package and the tests
cargo fmt Rust formatting, fixed in place
cargo clippy Rust lints, with warnings as errors
cargo test Rust unit tests of the parts that need no Gurobi

A hook that fixes files in place fails the commit; add the fixed files and commit again.

Tests

uv run pytest
cargo test

cargo test covers what the native module does without Gurobi: reading Arrow columns and lists, the CSR checks and merging repeated variables. Some of its tests start an embedded Python to check error messages. Everything that calls Gurobi is tested through pytest against gurobipy.

Besides unit tests, tests/test_equivalence.py runs a Hypothesis state machine that checks every model polarobi builds against the same model built with plain gurobipy, down to the MPS file and Fingerprint. The default profile is quick; set HYPOTHESIS_PROFILE=ci for ten times the examples, or thorough for a long search after changes to the native code or the namespace semantics:

HYPOTHESIS_PROFILE=thorough uv run pytest tests/test_equivalence.py

tests/harness/__init__.py explains how to extend the harness for a new feature, and Equivalence with gurobipy what it guarantees.

Benchmarks

benchmarks/build_model.py builds the same allocation model with polarobi, in two plain gurobipy styles and with gurobipy-pandas at several sizes, checks that their fingerprints match, and writes the timings to benchmarks/results/<system>.json. benchmarks/plot.py draws the figures on the documentation's Benchmarks page from such a file and prints its table:

uv run --group bench python benchmarks/build_model.py --sizes 1000 10000 100000 1000000 10000000 --cpus 0,2,4,6,8,10
uv run --group bench python benchmarks/plot.py benchmarks/results/results.json

--cpus pins the run to one thread per performance core; on hybrid CPUs the operating system otherwise moves it between core types. 10M rows need well over 11 GB of free memory.

Changes to polarobi itself are measured by CodSpeed, on every pull request and on master: benches/stages.rs covers the pure Rust stages, and benchmarks/test_api.py has one benchmark per call of the Python API. The Benchmarks workflow runs both under CPU simulation, which reports instruction, cache and memory-access costs that don't depend on the runner's load, and under memory profiling, which reports peak memory, bytes allocated and allocations. CodSpeed comments the changes on the pull request. Locally, both run timed:

cargo bench --bench stages
uv run --group dev --group codspeed pytest benchmarks/ --codspeed

Documentation

The documentation is built with Zensical from docs/, with the API reference generated from the docstrings:

uv run zensical serve
uv run zensical build --clean --strict

serve rebuilds on changes and serves the site on http://localhost:8000.

Keep in Mind

  • gurobipy's private attributes. polarobi registers its handles through Model._cmodel, _internal_vars, _livevars, _constrs, _liveconstrs and _has_pending_deletions(), so gurobipy is pinned to one minor version. Raising the pin needs a thorough run of the equivalence harness.
  • No numpy at runtime. numpy is a dev dependency only, because polars' type annotations refer to it. tests/test_no_numpy.py fails if polarobi ever imports it.
  • The Gurobi library is never loaded twice. The native module only ever binds to the copy gurobipy loaded.

Layout

polarobi/
├── src/                      # Rust extension, built as polarobi._native
│   ├── lib.rs                # Module definition
│   ├── gurobi.rs             # Binding to gurobipy's Gurobi library, error handling
│   ├── columns.rs            # Zero-copy views of Arrow columns as C arrays
│   ├── model.rs              # Bulk adds, attribute reads and writes
│   └── handles.rs            # gurobipy handle creation
├── python/polarobi/          # Python package
│   ├── _namespace.py         # The df.grb namespace (GurobiFrame), the public API
│   ├── _api.py               # Its implementation: inputs, names, constraint layout
│   ├── _handles.py           # Registering handles with gurobipy
│   ├── _library.py           # Finding and binding the Gurobi library
│   └── _native.pyi           # Type stub of the extension
├── tests/
│   ├── harness/              # Equivalence harness: reference implementation, comparison
│   ├── test_equivalence.py   # State machine against plain gurobipy
│   └── test_*.py             # Compatibility, parity and edge cases
└── docs/                     # Documentation (Zensical)

Metadata

Release files for polarobi 0.1.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for polarobi 0.1.7
File Size Uploaded Provenance Actions
polarobi-0.1.7.tar.gz 499.4 kB With provenance Details for polarobi-0.1.7.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for polarobi 0.1.7
File Actions
polarobi-0.1.7-cp312-abi3-win_amd64.whl CPython 3.12 abi3 Windows x86-64 Details for polarobi-0.1.7-cp312-abi3-win_amd64.whl
polarobi-0.1.7-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.12 abi3 Linux glibc 2.17+ x86-64 Details for polarobi-0.1.7-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
polarobi-0.1.7-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.12 abi3 Linux glibc 2.17+ ARM64 Details for polarobi-0.1.7-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
polarobi-0.1.7-cp312-abi3-macosx_10_12_universal2.macosx_10_12_x86_64.macosx_11_0_arm64.whl CPython 3.12 abi3 macOS 10.12+ universal2 (ARM64, x86-64), macOS 10.12+ x86-64, macOS 11.0+ ARM64 Details for polarobi-0.1.7-cp312-abi3-macosx_10_12_universal2.macosx_10_12_x86_64.macosx_11_0_arm64.whl

Total release size: 12.9 MB

Release files / polarobi-0.1.7.tar.gz

Download URL polarobi-0.1.7.tar.gz
Size 499.4 kB
Tags Source
SHA-256 checksum
How to use checksums
14061ea8ddc469688d85f1906d3018a430d9e62d743166c4174dcfddb0c50989
BLAKE2b-256 checksum
How to use checksums
0328492a2af0436e9a071af57296970faa0b437a6b56029c5684d21a65a91e2b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 17, 2026.

Transparency log

Release files / polarobi-0.1.7-cp312-abi3-win_amd64.whl

Download URL polarobi-0.1.7-cp312-abi3-win_amd64.whl
Size 2.6 MB
Tags CPython 3.12 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
04317de885f7dee8224cf3dc6dd5950cab0af1de7794a2f0c49e6ecdf3ce9119
BLAKE2b-256 checksum
How to use checksums
d520e25dc4bed01e02605bffab106a63595432e4407c8d949a1d3f76efb9dfcc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 17, 2026.

Transparency log

Release files / polarobi-0.1.7-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL polarobi-0.1.7-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 2.6 MB
Tags CPython 3.12 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
cb00d2f88134bf75030765b016cc86b8012a09027c50b049d1334889ef9b0733
BLAKE2b-256 checksum
How to use checksums
01c846241a2e18d54bc6e23051b753549d3aa2ed2420163637e767890b5b80de
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 17, 2026.

Transparency log

Release files / polarobi-0.1.7-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL polarobi-0.1.7-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 2.5 MB
Tags CPython 3.12 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
73b1760bd12c05148b58ed4d2e67728d12390c550f317a1ace79d40d5732b544
BLAKE2b-256 checksum
How to use checksums
f5026612bdd8d92c69774d116c15a20bec947901b3c9bfbe11152bbeb29c04e9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 17, 2026.

Transparency log

Release files / polarobi-0.1.7-cp312-abi3-macosx_10_12_universal2.macosx_10_12_x86_64.macosx_11_0_arm64.whl

Download URL polarobi-0.1.7-cp312-abi3-macosx_10_12_universal2.macosx_10_12_x86_64.macosx_11_0_arm64.whl
Size 4.7 MB
Tags CPython 3.12 abi3 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
82c3109994b387228fef88f9ab0a3c498ef204fc492c877f162293432844df99
BLAKE2b-256 checksum
How to use checksums
328be3af06ad6cf49b961b439e5e44d9e5613762ebac2b7ed1c600219307a082
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 17, 2026.

Transparency log

Security for polarobi 0.1.7

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.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for polarobi-0.1.7.tar.gz

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 Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page