API Reference

gurobipy_pandas.api.add_vars(model, pandas_obj, *, name=None, lb=0.0, ub=1e+100, obj=0.0, vtype='C', index_formatter='default')

Add a variable to the given model for each entry in the given pandas Index, Series, or DataFrame.

Parameters:

modelModel

A Gurobi model to which new variables will be added

pandas_objIndex, Series, or DataFrame

A pandas Index, Series, or DataFrame

namestr, optional

If provided, used as base name for new Gurobi variables and the name of the returned series

lbfloat, str, or Series, optional

Lower bound for created variables. Can be a single numeric value. If pandas_obj is an Index or Series, can be a Series aligned with pandas_obj. If pandas_obj is a dataframe, can be a string referring to a column of pandas_obj. Defaults to 0.0.

ubfloat, str, or Series, optional

Upper bound for created variables. Can be a single numeric value. If pandas_obj is an Index or Series, can be a Series aligned with pandas_obj. If pandas_obj is a dataframe, can be a string referring to a column of pandas_obj. Defaults to 0.0.

objfloat, str, or Series, optional

Linear objective function coefficient for created variables. Can be a single numeric value. If pandas_obj is an Index or Series, can be a Series aligned with pandas_obj. If pandas_obj is a dataframe, can be a string referring to a column of pandas_obj. Defaults to 0.0.

vtypestr or Series, optional

Types of created variables. Can be a single string specifying the type (e.g. GRB.BINARY). If pandas_obj is an Index or Series, can be a Series aligned with pandas_obj containing variable type string values. Defaults to GRB.CONTINUOUS.

index_formatter

Can be used to provide custom conversion of index values to variable names. The default behaviour is usually sufficient.

Returns:

Series

A Series of vars with the the index of pandas_obj

gurobipy_pandas.api.add_constrs(model, lhs, sense, rhs, *, name=None, index_formatter='default')

Add a constraint to the model for each row in lhs & rhs. At least one of lhs and rhs must be a Series, while the other side may be a constant or a single gurobipy expression. If both sides are Series, then their indexes must match.

Parameters:

modelModel

A Gurobi model to which new constraints will be added

lhsSeries

A series of expressions forming the left hand side of constraints, a constant, or a single expression.

senseSeries or str

Constraint sense; can be a series if senses vary, or a single string if all constraints have the same sense

rhsSeries or float

A series of expressions forming the right hand side of constraints, a constant, or a single expression.

namestr

Used as the returned series name, as well as the base name for added Gurobi constraints. Constraint name suffixes come from the lhs/rhs index.

index_formatter

Can be used to provide custom conversion of index values to variable names. The default behaviour is usually sufficient.

Returns:

Series

A Series of Constr objects

gurobipy_pandas.api.set_interactive(flag=True)

Enables or disables interactive mode. In interactive mode, model updates are run immediately after any invocation of add_vars or add_constrs functions or accessors. This is useful when building models in interactive code environments like Jupyter notebooks, since variable and constraint names and attributes can be immediately queried after they are created. Interactive mode is disabled by default, since frequent update calls can be expensive.

>>> import gurobipy as gp
>>> import pandas as pd
>>> import gurobipy_pandas as gppd
>>> model = gp.Model()
>>> index = pd.RangeIndex(5)
>>> gppd.add_vars(model, index, name="x")
0    <gurobi.Var *Awaiting Model Update*>
1    <gurobi.Var *Awaiting Model Update*>
2    <gurobi.Var *Awaiting Model Update*>
3    <gurobi.Var *Awaiting Model Update*>
4    <gurobi.Var *Awaiting Model Update*>
Name: x, dtype: object
>>> gppd.set_interactive()
>>> gppd.add_vars(model, index, name="y")
0    <gurobi.Var y[0]>
1    <gurobi.Var y[1]>
2    <gurobi.Var y[2]>
3    <gurobi.Var y[3]>
4    <gurobi.Var y[4]>
Name: y, dtype: object
>>> gppd.set_interactive(False)
>>> gppd.add_vars(model, index, name="z")
0    <gurobi.Var *Awaiting Model Update*>
1    <gurobi.Var *Awaiting Model Update*>
2    <gurobi.Var *Awaiting Model Update*>
3    <gurobi.Var *Awaiting Model Update*>
4    <gurobi.Var *Awaiting Model Update*>
Name: z, dtype: object

Note that interactive mode only applies to gurobipy_pandas calls. If you call methods of gurobipy.Model directly, updates will not be run automatically.

Parameters:

flagbool, optional

Pass True to enable interactive mode, False to disable. Defaults to True.

class gurobipy_pandas.accessors.GRBDataFrameAccessor(pandas_obj)

Accessor class for methods invoked as pd.DataFrame(...).gppd.*. The accessor does not expect particular types in the dataframe. This class should not be instantiated directly; it should be used via Pandas’ accessor API

Methods

add_constrs(model, lhs[, sense, rhs, ...])	Add a constraint to the model for each row in the dataframe referenced by this accessor.
add_vars(model, *, name[, lb, ub, obj, ...])	Add a variable to the given model for each row in the dataframe referenced by this accessor.

add_constrs(model, lhs, sense=None, rhs=None, *, name, index_formatter='default')

Add a constraint to the model for each row in the dataframe referenced by this accessor.

>>> import pandas as pd
>>> import gurobipy as gp
>>> from gurobipy import GRB
>>> import gurobipy_pandas as gppd
>>> m = gp.Model()
>>> df = (
...     pd.DataFrame({"c": [1, 2, 3]})
...     .gppd.add_vars(m, name="x")
...     .gppd.add_vars(m, name="y")
... )
>>> m.update()
>>> df
   c                  x                  y
0  1  <gurobi.Var x[0]>  <gurobi.Var y[0]>
1  2  <gurobi.Var x[1]>  <gurobi.Var y[1]>
2  3  <gurobi.Var x[2]>  <gurobi.Var y[2]>

Constraints can be added using a pd.DataFrame.eval-like syntax. In this case, a constraint is added to the model for each row in the dataframe, specifying e.g. \(x_0 + y_0 <= 1\) in the first row.

>>> df2 = df.gppd.add_constrs(m, "x + y <= c", name="constr")
>>> m.update()
>>> df2
   c                  x                  y                     constr
0  1  <gurobi.Var x[0]>  <gurobi.Var y[0]>  <gurobi.Constr constr[0]>
1  2  <gurobi.Var x[1]>  <gurobi.Var y[1]>  <gurobi.Constr constr[1]>
2  3  <gurobi.Var x[2]>  <gurobi.Var y[2]>  <gurobi.Constr constr[2]>

Alternatively, you can use explicit column references in place of a string expression. This case specifies that \(x_i <= y_i\) must hold for every row in the dataframe.

>>> df3 = df.gppd.add_constrs(m, "x", GRB.LESS_EQUAL, "y", name="xy")
>>> m.update()
>>> df3
   c                  x                  y                     xy
0  1  <gurobi.Var x[0]>  <gurobi.Var y[0]>  <gurobi.Constr xy[0]>
1  2  <gurobi.Var x[1]>  <gurobi.Var y[1]>  <gurobi.Constr xy[1]>
2  3  <gurobi.Var x[2]>  <gurobi.Var y[2]>  <gurobi.Constr xy[2]>

Scalar values can also be used in place of a column reference for either the left or right-hand sides. The following case specifies that \(x_i + y_i <= 1\) must hold for every row.

>>> df4 = df.assign(expr=df["x"] + df["y"])
>>> df4
   c                  x                  y         expr
0  1  <gurobi.Var x[0]>  <gurobi.Var y[0]>  x[0] + y[0]
1  2  <gurobi.Var x[1]>  <gurobi.Var y[1]>  x[1] + y[1]
2  3  <gurobi.Var x[2]>  <gurobi.Var y[2]>  x[2] + y[2]
>>> df4 = df4.gppd.add_constrs(m, "expr", GRB.LESS_EQUAL, 1, name="c4")
>>> m.update()
>>> df4[["expr", "c4"]]
          expr                     c4
0  x[0] + y[0]  <gurobi.Constr c4[0]>
1  x[1] + y[1]  <gurobi.Constr c4[1]>
2  x[2] + y[2]  <gurobi.Constr c4[2]>

Parameters:

modelModel

A Gurobi model to which new constraints will be added

lhsstr

A string representation of the entire constraint expression, or the name of a column

sensestr, optional

Constraint sense. Can be a column name or a string value representing the sense. Required if lhs is not a complete expression including a comparator

rhsstr or float, optional

Constraint right hand side. Can be a column name or float value. Required if lhs is not a complete expression including a comparator

namestr

Used as the appended column name, as well as the base name for added Gurobi constraints. Constraint name suffixes come from the dataframe index.

Returns:

DataFrame

A new DataFrame with new Constrs appended as a column

Using some simple example data and variables to demo:

add_vars(model, *, name, lb=0.0, ub=1e+100, obj=0.0, vtype='C', index_formatter='default')

Add a variable to the given model for each row in the dataframe referenced by this accessor.

Parameters:

modelModel

A Gurobi model to which new variables will be added

namestr

Used as the appended column name, as well as the base name for added Gurobi variables

lbfloat or str, optional

Lower bound for created variables. May be a single value or the name of a column in the dataframe, defaults to 0.0

ubfloat or str, optional

Upper bound for created variables. May be a single value or the name of a column in the dataframe, defaults to GRB.INFINITY

obj: float or str, optional

Objective function coefficient for created variables. May be a single value, or the name of a column in the dataframe, defaults to 0.0

vtype: str, optional

Gurobi variable type for created variables, defaults to GRB.CONTINUOUS

Returns:

DataFrame

A new DataFrame with new Vars appended as a column

class gurobipy_pandas.accessors.GRBSeriesAccessor(pandas_obj)

Accessor class for methods invoked as pd.Series(...).gppd.*. The accessor expects a series containing gurobipy objects, and can return new series by evaluating a target value across all objects in the series. This class should not be instantiated directly; it should be used via Pandas’ accessor API

Methods

get_attr(attr)	Retrieve the given Gurobi attribute for every object in the Series held by this accessor.
get_value()	Return a new series, on the same index, containing the result of obj.getValue() for each gurobipy object in the series held by this accessor.
set_attr(attr, value)	Change the given Gurobi attribute for every object in the Series held by this accessor.

get_attr(attr)

Retrieve the given Gurobi attribute for every object in the Series held by this accessor. Analogous to Var.getAttr, series-wise.

For example, after solving a model, the solution can be retrieved

>>> import pandas as pd
>>> import gurobipy as gp
>>> from gurobipy import GRB
>>> import gurobipy_pandas as gppd
>>> m = gp.Model()
>>> x = gppd.add_vars(m, pd.RangeIndex(3), name='x')
>>> m.optimize()  
Gurobi Optimizer version...
>>> x.gppd.get_attr("X")
0    0.0
1    0.0
2    0.0
Name: x, dtype: float64

Parameters:

attrstr

The name of the Gurobi attribute to retrieve

Returns:

Series

A new series with the evaluated attributes

get_value()

Return a new series, on the same index, containing the result of obj.getValue() for each gurobipy object in the series held by this accessor. Note that this assumes that the wrapped objects are gurobipy expressions (LinExpr or QuadExpr)

Returns:

Series

A series with the evaluated expression values

set_attr(attr, value)

Change the given Gurobi attribute for every object in the Series held by this accessor. Analogous to Var.setAttr, series-wise.

For example, after creating a series of variables, their upper bounds can be set and retrieved.

>>> import pandas as pd
>>> import gurobipy as gp
>>> from gurobipy import GRB
>>> import gurobipy_pandas as gppd
>>> m = gp.Model()
>>> x = gppd.add_vars(m, pd.RangeIndex(3), name='x')
>>> m.update()
>>> x.gppd.set_attr("LB", 3.0).gppd.set_attr("UB", 5.0)
0    <gurobi.Var x[0]>
1    <gurobi.Var x[1]>
2    <gurobi.Var x[2]>
Name: x, dtype: object
>>> m.update()
>>> x.gppd.get_attr("LB")
0    3.0
1    3.0
2    3.0
Name: x, dtype: float64
>>> x.gppd.get_attr("UB")
0    5.0
1    5.0
2    5.0
Name: x, dtype: float64

Parameters:

attrstr

The name of the Gurobi attribute to be modified

valueint, float, str, or Series

The value(s) to which the attributes should be set

Returns:

Series

The original series (allowing method chaining)