Quick Start
This Quick Start builds a small allocation model: each order can be produced by one of several factories, each factory has a capacity, and we pick the assignment with the highest total margin. It covers the three things you do with polarobi: add variables, add constraints and read results.
Prerequisites
The Quick Start assumes you have installed polarobi and that gurobipy finds a Gurobi license. The size-limited license that comes with gurobipy is enough for this example.
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],
"margin": [3.0, 2.5, 4.0, 3.0, 2.0],
}
)
capacity = pl.DataFrame({"factory": ["f1", "f2"], "capacity": [50, 80]})
model = gp.Model() grb(df) gives you polarobi's operations on a frame. It is the typed form of the df.grb namespace that importing polarobi registers on every DataFrame: both do the same, but type checkers only understand grb(df). See Type Checking for why.
Adding Variables
Each row of orders is a candidate assignment, so we add one binary variable per row. Its objective coefficient is the margin it earns, computed by a polars expression.
x = grb(orders).add_vars(
model, by=["order", "factory"], vtype="B", obj=pl.col("quantity") * pl.col("margin"), name="x"
) Output
add_vars returns the frame with a new idx column: the Gurobi column index of each row's variable. This column is how constraints refer to variables later on.
┌───────┬─────────┬──────────┬────────┬─────┐
│ order ┆ factory ┆ quantity ┆ margin ┆ idx │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ i64 ┆ f64 ┆ u32 │
╞═══════╪═════════╪══════════╪════════╪═════╡
│ o1 ┆ f1 ┆ 40 ┆ 3.0 ┆ 0 │
│ o1 ┆ f2 ┆ 40 ┆ 2.5 ┆ 1 │
│ o2 ┆ f1 ┆ 25 ┆ 4.0 ┆ 2 │
│ o2 ┆ f2 ┆ 25 ┆ 3.0 ┆ 3 │
│ o3 ┆ f2 ┆ 60 ┆ 2.0 ┆ 4 │
└───────┴─────────┴──────────┴────────┴─────┘ The variables are named from the key columns in by, exactly as gurobipy's Model.addVars would name them: x[o1,f1], x[o1,f2] and so on.
Adding Constraints
Constraints are built from a frame of terms: one row per variable in a constraint, with the keys that group terms into constraints, the variable's idx and a coefficient. x is already such a frame.
First, every order is assigned at most once. Grouping x by order gives one constraint per order, with a coefficient of 1 for each of its variables:
assign = grb(x).add_constrs(model, by="order", sense="<=", rhs=1.0, name="assign") Second, no factory exceeds its capacity. Here the right-hand side differs per constraint, so we pass capacity as the rows frame, one row per constraint, and take rhs from its column. The coefficient is each order's quantity:
cap = grb(x).add_constrs(
model, capacity, by="factory", sense="<=", rhs="capacity", coef="quantity", name="cap"
) Output
Both calls return their rows with the constraints' row index in idx.
┌───────┬─────┐ ┌─────────┬──────────┬─────┐
│ order ┆ idx │ │ factory ┆ capacity ┆ idx │
│ --- ┆ --- │ │ --- ┆ --- ┆ --- │
│ str ┆ u32 │ │ str ┆ i64 ┆ u32 │
╞═══════╪═════╡ ╞═════════╪══════════╪═════╡
│ o1 ┆ 0 │ │ f1 ┆ 50 ┆ 3 │
│ o2 ┆ 1 │ │ f2 ┆ 80 ┆ 4 │
│ o3 ┆ 2 │ └─────────┴──────────┴─────┘
└───────┴─────┘ The resulting model
Written by model.write("quickstart.lp"):
Maximize
120 x[o1,f1] + 100 x[o1,f2] + 100 x[o2,f1] + 75 x[o2,f2] + 120 x[o3,f2]
Subject To
assign[o1]: x[o1,f1] + x[o1,f2] <= 1
assign[o2]: x[o2,f1] + x[o2,f2] <= 1
assign[o3]: x[o3,f2] <= 1
cap[f1]: 40 x[o1,f1] + 25 x[o2,f1] <= 50
cap[f2]: 40 x[o1,f2] + 25 x[o2,f2] + 60 x[o3,f2] <= 80
Binaries
x[o1,f1] x[o1,f2] x[o2,f1] x[o2,f2] x[o3,f2]
End Solving and Reading Results
The model is a plain gurobipy model, so solving it is too:
model.ModelSense = gp.GRB.MAXIMIZE
model.optimize() get reads an attribute for every row of a frame and adds it as a column, so the solution comes back as a frame you can filter and join like any other:
chosen = grb(x).get(model, "X").filter(pl.col("X") > 0.5)
slack = grb(cap).get(model, "Slack") Output
┌───────┬─────────┬──────────┬────────┬─────┬─────┐
│ order ┆ factory ┆ quantity ┆ margin ┆ idx ┆ X │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ i64 ┆ f64 ┆ u32 ┆ f64 │
╞═══════╪═════════╪══════════╪════════╪═════╪═════╡
│ o1 ┆ f1 ┆ 40 ┆ 3.0 ┆ 0 ┆ 1.0 │
│ o3 ┆ f2 ┆ 60 ┆ 2.0 ┆ 4 ┆ 1.0 │
└───────┴─────────┴──────────┴────────┴─────┴─────┘
┌─────────┬──────────┬─────┬───────┐
│ factory ┆ capacity ┆ idx ┆ Slack │
│ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ u32 ┆ f64 │
╞═════════╪══════════╪═════╪═══════╡
│ f1 ┆ 50 ┆ 3 ┆ 10.0 │
│ f2 ┆ 80 ┆ 4 ┆ 20.0 │
└─────────┴──────────┴─────┴───────┘ Next Steps
The Guides cover each part in depth, starting with Variables and Constraints. If you already have a gurobipy model built with loops over iter_rows(), see Porting a gurobipy Model.