Warning

This page was created from a pull request (#70).

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.

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.

Parameters

modelModel: A Gurobi model to which new constraints will be added
lhsSeries: A series of expressions forming the left hand side of constraints
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, or a common constant
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.

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 \le 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 \le 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 \le 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)