Porting a gurobipy Model
A common way to build gurobipy models from polars data is to iterate: iter_rows() into addVars, group_by().agg() into dicts of LinExpr, and a loop of addLConstr calls. polarobi replaces each of those steps with a frame operation. This guide shows the translation on a typical capacity constraint, then lists the patterns one by one.
Port one family at a time
polarobi and gurobipy work on the same model, so you can port a model family by family and compare the result after each step. Working with gurobipy covers mixing both.
An Example
Demand rows are assigned to vendors per week. Each vendor week has a minimum quantity, which may be breached at a penalty, and a maximum quantity. Vendor weeks without any demand get no constraints.
Setup
import gurobipy as gp
import polars as pl
from polarobi import GurobiFrame as grb
demand = pl.DataFrame(
{
"order": ["o1", "o2", "o3"],
"vendor_code": ["V1", "V1", "V2"],
"ex_go_date": ["20260101", "20260101", "20260101"],
"quantity": [30.0, 45.0, 20.0],
}
)
capacity = pl.DataFrame(
{
"vendor_code": ["V1", "V2", "V3"],
"ex_go_date": ["20260101", "20260101", "20260101"],
"min_qty": [50.0, 25.0, 10.0],
"max_qty": [100.0, 80.0, 60.0],
}
)
model = gp.Model() keys = ("vendor_code", "ex_go_date")
x = model.addVars(demand.select("order", *keys).iter_rows(), vtype=gp.GRB.BINARY, name="x")
breach = model.addVars(capacity.select(*keys).iter_rows(), name="breach")
exprs = {}
for v, w, orders, quantities in demand.group_by(keys).agg("order", "quantity").iter_rows():
exprs[v, w] = gp.LinExpr(quantities, [x[o, v, w] for o in orders])
for v, w, min_qty, max_qty in capacity.select(*keys, "min_qty", "max_qty").iter_rows():
if (expr := exprs.get((v, w))) is None:
continue
model.addLConstr(expr + breach[v, w] >= min_qty, name=f"min[{v},{w}]")
model.addLConstr(expr <= max_qty, name=f"max[{v},{w}]") from polarobi import add_constrs
keys = ("vendor_code", "ex_go_date")
x = grb(demand).add_vars(model, by=["order", *keys], vtype="B", name="x")
breach = grb(capacity).add_vars(model, by=keys, name="breach")
rows = capacity.join(x.select(keys), on=keys, how="semi")
add_constrs(model, [(x, "quantity"), breach], rows, by=keys, sense=">=", rhs="min_qty")
grb(x).add_constrs(model, rows, by=keys, sense="<=", rhs="max_qty", coef="quantity") What changed:
- Variables come from the frames directly.
bynames the key columns, and names are formatted from them asaddVarsformats its keys. - Lookups like
x[o, v, w]disappear.xalready carries each variable'sidxnext to its keys, so selecting columns is enough. Where variables and data live in different frames, a join on the keys does the lookup. - Expressions become terms frames. Adding the breach variable to the quantity expression is a second source in the list passed to
add_constrs. - Skipping groups with
continuebecomes filtering the rows frame. The maximum constraint does not even need that: rows without terms are dropped by default. The minimum constraint does, because the breach term would otherwise make every vendor week non-empty. - The loop of
addLConstrcalls becomes oneadd_constrscall per family.
The names differ slightly, as polarobi names constraints the way addConstrs does: min[V1,20260101]. If you depend on a particular name format, pass an expression, such as name=pl.concat_str(pl.lit("min_"), "vendor_code", pl.lit("_"), "ex_go_date").
Pattern by Pattern
| gurobipy | polarobi |
|---|---|
model.addVars(df.select(keys).iter_rows(), ...) | grb(df).add_vars(model, by=keys, ...) |
model.addVar(ub=b, obj=c, name="v") | add_var(model, ub=b, obj=c, name="v") |
ub=list(caps.values()) | ub="cap", a column of the same frame |
x[(a, b)] lookups | A join on a, b that brings idx along |
gp.LinExpr(coefs, [x[k] for k in keys]) | A terms frame with idx and a coefficient column, passed as coef= |
quicksum(x[k] for k in keys) | A terms frame with idx; coef defaults to 1 |
quicksum(e1 + e2) across families | add_constrs(model, [(df1, c1), (df2, c2)], ...) |
One model.addLConstr(quicksum(...) <= b) | grb(terms).add_constr(model, sense="<=", rhs=b) |
expr <= big_m * y | y's terms with coef=-big_m, rhs=0 |
if not exprs: continue | Default drop_empty=True, or a filtered rows frame |
for row in df.iter_rows(): model.addLConstr(...) | grb(terms).add_constrs(model, df, by=keys, ...) |
y.setAttr("ub", 0) for some groups | grb(y.filter(...)).set(model, "UB", 0.0) |
setAttr("BranchPriority", list(y.values()), ...) | grb(y).set(model, "BranchPriority", 10) |
[(k, v.X) for k, v in x.items() if v.X > 0] | grb(x).get(model, "X").filter(pl.col("X") > 0) |
Checking the Port
Two models built from the same data should be identical, not just equally good. Compare them before switching:
for m in (old_model, new_model):
m.update()
assert old_model.NumVars == new_model.NumVars
assert old_model.NumConstrs == new_model.NumConstrs
assert old_model.NumNZs == new_model.NumNZs
assert old_model.Fingerprint == new_model.Fingerprint Fingerprint depends on the order of variables and constraints. If the original model builds its constraints from group_by or unique without maintain_order=True, its order changes from run to run, and so does its fingerprint. Make the original deterministic first, then compare.