C Reference Manual

This section documents the Gurobi C interface. This manual begins with a quick overview of the functions in the interface, and continues with descriptions of all of the available interface routines.

Environments

The first step in using the Gurobi C optimizer is to create an environment, using the GRBloadenv call. The environment acts as the container for all data associated with a set of optimization runs. Once you are done with the environment, you should call GRBfreeenv to release the associated resources.

Models

You can create one or more optimization models within an environment. A model consists of a set of variables and a set of constraints. Each variable has an associated lower bound, upper bound, type (continuous, binary, integer, semi-continuous, or semi-integer), and objective coefficient. Each 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, through the GRBloadmodel routine, or built incrementally, by first calling GRBnewmodel and then subsequently calling GRBaddvars or GRBaddconstrs to add additional variables or constraints. Models are dynamic entities; you can always add or delete variables or constraints.

Specific variables and constraints are referred to throughout the Gurobi C interface using their indices. Indices are assigned as these variables and constraints are added to the model, in a contiguous fashion. In adherence to C language conventions, these indices all start at 0.

Solving a Model

Once you have built a model, you can call GRBoptimize to compute a solution. By default, GRBoptimize() will use the dual simplex algorithm to solve continuous models, and the branch-and-cut algorithm to solve mixed integer models. The solution is stored as a set of attributes of the model. The C interface contains an extensive set of routines for querying these attributes.

The Gurobi algorithms keep careful track of the state of the model, so calls to GRBoptimize() 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 GRBresetmodel.

If a model is found to be infeasible, you can call GRBcomputeIIS to compute an Irreducible Inconsistent Subsystem (IIS) for the model. This routine can be used for both continuous and MIP models, but you should be aware that the MIP version can be quite expensive. This routine populates a set of IIS attributes.

After a MIP model has been solved, you can call GRBfixedmodel 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.).

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 engine cannot be modified directly by the user, while others, such as the variable lower bound array (the LB attribute) can.

The Gurobi C interface contains an extensive set of routines for querying or modifying attribute values. The exact routine to use for a particular attribute depends on the type of the attribute. As mentioned earlier, attributes can be either variable attributes, constraint attributes, or model attributes. Variable and constraint attributes are arrays, and use a set of array attribute routines. Model attributes are scalars, and use a set of scalar routines. Attribute values can additionally be of type char, int, double, or string (really char *).

Scalar model attributes are accessed through a set of GRBget*attr() routines (e.g., GRBgetintattr). In addition, those model attributes that can be set directly by the user (e.g., the objective sense) may be modified through the GRBset*attr() routines (e.g., GRBsetdblattr).

Array attributes are accessed through three sets of routines. The first set, the GRBget*attrarray() routines (e.g., GRBgetcharattrarray) return a contiguous sub-array of the attribute array, specified using the index of the first member and the length of the desired sub-array. The second set, the GRBget*attrelement() routines (e.g., GRBgetcharattrelement) return a single entry from the attribute array. Finally, the GRBget*attrlist() routines (e.g., GRBgetdblattrlist) retrieve attribute values for a list of indices.

Array attributes that can be set by the user are modified through the GRBset*attrarray(), GRBset*attrelement, and GRBset*attrlist() routines.

The full list of Gurobi attributes can be found in the Attributes section.

Additional Model Modification Information

Most modifications to an existing model are done through the attribute interface (e.g., changes to variable bounds, objective coefficients, constraint right-hand sides, etc.). The main exception is modification of the constraint matrix. The constraint matrix can be modified in a few ways. The first is to call GRBchgcoeffs to change a single matrix coefficient. This routine 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 other way to modify the non-zeros in an existing constraint matrix is to remove constraints (through GRBdelconstrs) or variables (through GRBdelvars). The non-zero values associated with the deleted constraints or variables are removed along with the constraints or variables themselves.

One very important item to note about 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 GRBoptimize or GRBupdatemodel. 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 GRBupdatemodel() in order to see the effect of your changes.

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 the GRBset*param() routines (e.g., GRBsetintparam). Current values can be retrieved with the GRBget*param() routines (e.g., GRBgetdblparam). Parameters can be of type int, double, or char * (string). You can also read a set of parameter settings from a file using GRBreadparams, or write the set of changed parameters using GRBwriteparams.

One thing we should note is that each model gets its own copy of the environment when it is created. Parameter changes to the original environment therefore have no effect on existing models. Use GRBgetenv to retrieve the environment associated with a particular model if you want to change a parameter for that model.

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. If you would like to direct output to a file as well as to the screen, specify the log file name in GRBloadenv when you create your environment. You can modify the LogfileName parameter if you wish to to redirect the log to a different file after creating the environment. 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 the Gurobi callback function. The GRBsetcallbackfunc routine allows you to install a function that the Gurobi optimizer will call regularly during the optimization process. You can call GRBcbget from within the callback to obtain additional information about the state of the optimization.

Modifying Solver Behavior - Callbacks

Callbacks can also be used to modify the behavior of the Gurobi optimizer. If you call routine GRBterminate from within a callback, for example, the optimizer will terminate at the earliest convenient point. Routine GRBcbsolution allows you to inject a feasible solution (or partial solution) during the solution of a MIP model. Routine GRBcbcut allows you to add a cutting plane during a MIP optimization.

Error Handling

Most of the Gurobi C library routines return an integer error code. A zero return value indicates that the routine completed successfully, while a non-zero value indicates that an error occurred. The list of possible error return codes can be found in the Error Code section.

When an error occurs, additional information on the error can be obtained by calling GRBgeterrormsg.

Subsections