Python API Overview

This section documents the Gurobi Python interface. It begins with an overview of the global functions, which can be called without referencing any Python objects. It then discusses the different types of objects that are available in the interface, and the most important methods on those objects. Finally, it gives a comprehensive presentation of all of the available classes and methods.

Important note for AIX users: due to limited Python support on AIX, our AIX port does not include the Python interface.

Global Functions

The Gurobi shell contains a set of Global Functions that can be called without referring to any Gurobi objects. The most important of these functions is probably the read function, which allows you to read a model from a file. Other useful global functions are system, which allows you to issue shell commands from within the Gurobi shell, and models, which gives you a list of the currently loaded models. Other global functions allow you to read, modify, or write Gurobi parameters (readParams, setParam, and writeParams).

Models

Most actions in the Gurobi Python interface are performed by calling methods on Gurobi objects. The most commonly used object is the Model. A model consists of a set of decision variables (objects of class Var), a linear or quadratic objective function on these variables (specified using Model.setObjective), and a set of constraints on these variables (objects of class Constr, QConstr, or SOS). Each variable has an associated lower bound, upper bound, and type (continuous, binary, etc.). Each linear or quadratic constraint has an associated sense (less-than-or-equal, greater-than-or-equal, or equal), and right-hand side value.

An optimization model may be specified all at once, by loading the model from a file (using the previously mentioned read function), or it may be built incrementally, by first constructing an empty object of class Model and then subsequently calling Model.addVar to add additional variables, and Model.addConstr or Model.addQConstr to add additional constraints.

Linear constraints are specified by building linear expressions (objects of class LinExpr), and then specifying relationships between these expressions (for example, requiring that one expression be equal to another). Quadratic constraints are built in a similar fashion, but using quadratic expressions (objects of class QuadExpr) instead.

Models are dynamic entities; you can always add or remove variables or constraints.

We often refer to the class of an optimization model. A model with a linear objective function, linear constraints, and continuous variables is a Linear Program (LP). If the objective is quadratic, the model is a Quadratic Program (QP). If any of the constraints are quadratic, the model is a Quadratically-Constrained Program (QCP). We'll sometimes also discuss a special case of QCP, the Second-Order Cone Program (SOCP). If the model contains any integer variables, semi-continuous variables, semi-integer variables, or Special Ordered Set (SOS) constraints, the model is a Mixed Integer Program (MIP). We'll also sometimes discuss special cases of MIP, including Mixed Integer Linear Programs (MILP), Mixed Integer Quadratic Programs (MIQP), Mixed Integer Quadratically-Constrained Programs (MIQCP), and Mixed Integer Second-Order Cone Programs (MISOCP). The Gurobi Optimizer handles all of these model classes.

Solving a Model

Once you have built a model, you can call Model.optimize to compute a solution. By default, optimize will use the concurrent optimizer to solve LP models, the barrier algorithm to solve QP and QCP models, and the branch-and-cut algorithm to solve mixed integer models. The solution is stored in a set of attributes of the model, which can be subsequently queried (we will return to this topic shortly).

The Gurobi algorithms keep careful track of the state of the model, so calls to Model.optimize will only perform further optimization if relevant data has changed since the model was last optimized. If you would like to discard previously computed solution information and restart the optimization from scratch without changing the model, you can call Model.reset.

After a MIP model has been solved, you can call Model.fixed to compute the associated fixed model. This model is identical to the input model, except that all integer variables are fixed to their values in the MIP solution. In some applications, it is useful to compute information on this continuous version of the MIP model (e.g., dual variables, sensitivity information, etc.).

Infeasible Models

You have a few options if a model is found to be infeasible. You can try to diagnose the cause of the infeasibility, attempt to repair the infeasibility, or both. To obtain information that can be useful for diagnosing the cause of an infeasibility, call Model.computeIIS to compute an Irreducible Inconsistent Subsystem (IIS). This method can be used for both continuous and MIP models, but you should be aware that the MIP version can be quite expensive. This method populates a set of IIS attributes.

To attempt to repair an infeasibility, call Model.feasRelaxS or Model.feasRelax to compute a feasibility relaxation for the model. This relaxation allows you to find a solution that minimizes the magnitude of the constraint violation.

Querying and Modifying Attributes

Most of the information associated with a Gurobi model is stored in a set of attributes. Some attributes are associated with the variables of the model, some with the constraints of the model, and some with the model itself. To give a simple example, solving an optimization model causes the x variable attribute to be populated. Attributes such as x that are computed by the Gurobi optimizer cannot be modified directly by the user, while others, such as the variable lower bound (the lb attribute) can.

Attributes can be accessed in two ways in the Python interface. The first is to use the getAttr() and setAttr() methods, which are available on variables (Var.getAttr/ Var.setAttr), linear constraints (Constr.getAttr/ Constr.setAttr), quadratic constraints (QConstr.getAttr/ QConstr.setAttr), SOSs (SOS.getAttr), and models (Model.getAttr/ Model.setAttr). These are called with the attribute name as the first argument (e.g., var.getAttr("x") or constr.setAttr("rhs", 0.0)). The full list of available attributes can be found in the Attributes section of this manual.

Attributes can also be accessed more directly: you can follow an object name by a period, followed by the name of an attribute of that object. Note that upper/lower case is ignored when referring to attributes. Thus, b = constr.rhs is equivalent to b = constr.getAttr("rhs"), and constr.rhs = 0.0 is equivalent to constr.setAttr("rhs", 0.0).

Additional Model Modification Information

Most modifications to an existing model are done through the attribute interface (e.g., changes to variable bounds, constraint right-hand sides, etc.). The main exceptions are modifications to the constraint matrix and to the objective function.

The constraint matrix can be modified in a few ways. The first is to call the Model.chgCoeff method. This method can be used to modify the value of an existing non-zero, to set an existing non-zero to zero, or to create a new non-zero. The constraint matrix is also modified when you remove a variable or constraint from the model (through the Model.remove method). The non-zero values associated with the deleted constraint or variable are removed along with the constraint or variable itself.

The model objective function can also be modified in a few ways. The easiest is to build an expression that captures the objective function (a LinExpr or QuadExpr object), and then pass that expression to method Model.setObjective. If you wish to modify the objective, you can simply call setObjective again with a new LinExpr or QuadExpr object.

For linear objective functions, an alternative to setObjective is to use the Obj variable attribute to modify individual linear objective coefficients.

If your variables have piecewise-linear objectives, you can specify them using the setPWLObj method. Call this method once for each relevant variable. The Gurobi simplex solver includes algorithmic support for convex piecewise-linear objective functions, so for continuous models you should see a substantial performance benefit from using this feature. To clear a previously specified piecewise-linear objective function, simply set the Obj attribute on the corresponding variable to 0.

Lazy Updates

One very important item to note about attribute and model modifications in the Gurobi optimizer is that they are performed in a lazy fashion, meaning that they don't actually affect the model until the next call to optimize or update on that model object. This approach provides the advantage that the model remains unchanged while you are in the process of making multiple modifications. The downside, of course, is that you have to remember to call update in order to see the effect of your changes.

If you forget to call update, your program won't crash. The most common symptom of a missing update is a NOT_IN_MODEL exception, which indicates that the object you are trying to reference isn't in the model yet.

Managing Parameters

The Gurobi optimizer provides a set of parameters to allow you to control many of the details of the optimization process. Factors like feasibility and optimality tolerances, choices of algorithms, strategies for exploring the MIP search tree, etc., can be controlled by modifying Gurobi parameters before beginning the optimization. Parameters are set using method Model.setParam. Current values may also be retrieved with Model.getParamInfo. You can also access parameters more directly through the Model.Params class. To set the MIPGap parameter to 0.0 for model m, for example, you can do either m.setParam('MIPGap', 0) or m.Params.MIPGap = 0.

You can read a set of parameter settings from a file using Model.read, or write the set of changed parameters using Model.write.

We also include an automated parameter tuning tool that explores many different sets of parameter changes in order to find a set that improves performance. You can call Model.tune to invoke the tuning tool on a model. Refer to the parameter tuning tool section for more information.

One thing we should note is that changing a parameter for one model has no effect on the parameter value for other models. Use the global setParam method to set a parameter for all loaded models.

The full list of Gurobi parameters can be found in the Parameters section.

Monitoring Progress - Logging and Callbacks

Progress of the optimization can be monitored through Gurobi logging. By default, Gurobi will send output to the screen. A few simple controls are available for modifying the default logging behavior. You can set the LogFile parameter if you wish to also direct the Gurobi log to a file. The frequency of logging output can be controlled with the DisplayInterval parameter, and logging can be turned off entirely with the OutputFlag parameter.

More detailed progress monitoring can be done through a callback function. If you pass a function taking two arguments, model and where, to Model.optimize, your function will be called periodically from within the optimization. Your callback can then call Model.cbGet to retrieve additional information on the state of the optimization. You can refer to the Callback class for additional information.

Modifying Solver Behavior - Callbacks

Callbacks can also be used to modify the behavior of the Gurobi optimizer. The simplest control callback is Model.terminate, which asks the optimizer to terminate at the earliest convenient point. Method Model.cbSetSolution allows you to inject a feasible solution (or partial solution) during the solution of a MIP model. Methods Model.cbCut and Model.cbLazy allow you to add cutting planes and lazy constraints during a MIP optimization, respectively.

Error Handling

All of the methods in the Gurobi Python library can throw an exception of type GurobiError. When an exception occurs, additional information on the error can be obtained by retrieving the errno or message members of the GurobiError object. A list of possible values for the errno field can be found in the Error Code section.

Try Gurobi for Free

Choose the evaluation license that fits you best, and start working with our Expert Team for technical guidance and support.

Evaluation License
Get a free, full-featured license of the Gurobi Optimizer to experience the performance, support, benchmarking and tuning services we provide as part of our product offering.
Academic License
Gurobi supports the teaching and use of optimization within academic institutions. We offer free, full-featured copies of Gurobi for use in class, and for research.
Cloud Trial

Request free trial hours, so you can see how quickly and easily a model can be solved on the cloud.

Search