Tutorial: Getting Started with the Gurobi C API

The example begins by including a few include files. Gurobi C applications should always start by including gurobi_c.h, along with the standard C include files (stdlib.h and stdio.h).

After declaring the necessary program variables, the example continues by creating an environment, by:

• first requesting an empty environment using GRBemptyenv,
• then setting some options — as log file name — using GRBsetstrparam,
• and then starting the environment using GRBstartenv.

As we'll discuss shortly, nearly every Gurobi method returns an error code. A zero value indicates that no error was encountered. It is important that you check every returned error code.

/* Create environment */
error = GRBemptyenv(&env);
if (error) goto QUIT;

error = GRBsetstrparam(env, "LogFile", "mip1.log");
if (error) goto QUIT;

error = GRBstartenv(env);
if (error) goto QUIT;

Later requests to create optimization models will always require an active environment, so environment creation should always be the first step when using the Gurobi optimizer.

Note that environment creation may fail, so you should check the return value of the call.

Once an environment has been created, the next step is to create a model. A Gurobi model holds a single optimization problem. It consists of a set of variables, a set of constraints, and the associated attributes (variable bounds, objective coefficients, variable integrality types, constraint senses, constraint right-hand side values, etc.). The first step towards building a model that contains all of this information is to create an empty model object:

/* Create an empty model */
error = GRBnewmodel(env, &model, "mip1", 0, NULL, NULL, NULL, NULL, NULL);
if (error) goto QUIT;

The first argument to GRBnewmodel is the previously created environment. The second is a pointer to the location where the pointer to the new model should be stored. The third is the name of the model. The fourth is the number of variables to initially add to the model. Since we're creating an empty model, the number of initial variables is 0. The remaining arguments would describe the initial variables (lower bounds, upper bounds, variable types, etc.), had they been present.

Once we create a Gurobi model, we can start adding variables and constraints to it. In our example, we'll begin by adding variables:

/* Add variables */
obj[0] = 1; obj[1] = 1; obj[2] = 2;
vtype[0] = GRB_BINARY; vtype[1] = GRB_BINARY; vtype[2] = GRB_BINARY;
error = GRBaddvars(model, 3, 0, NULL, NULL, NULL, obj, NULL, NULL, vtype,
                   NULL);
if (error) goto QUIT;

The first argument to GRBaddvars is the model to which the variables are being added. The second is the number of added variables (3 in our example).

Arguments three through six describe the constraint matrix coefficients associated with the new variables. The third argument gives the number of non-zero constraint matrix entries associated with the new variables, and the next three arguments give details on these non-zeros. In our example, we'll be adding these non-zeros when we add the constraints. Thus, the non-zero count here is zero, and the following three arguments are all NULL.

The seventh argument to GRBaddvars is the linear objective coefficient for each new variable. Since our example aims to maximize the objective, and by default, Gurobi will minimize the objective, we'll need to change the objective sense. This is done in the next statement. Note we could have multiplied the objective coefficients by -1 instead (since maximizing \(c^Tx\) is equivalent to minimizing \(-c^Tx\).

The next two arguments specify the lower and upper bounds of the variables, respectively. The NULL values indicate that these variables should take their default values (0.0 and 1.0 for binary variables).

The tenth argument specifies the types of the variables. In this example, the variables are all binary (GRB_BINARY).

The final argument gives the names of the variables. In this case, we allow the variable names to take their default values (x0, x1, and x2).

Once the new variables are integrated into the model, the next step is to add our two linear constraints. These constraints are added through the GRBaddconstr routine. To add a constraint, you must specify several pieces of information, including the non-zero values associated with the constraint, the constraint sense, the right-hand side value, and the constraint name. These are all specified as arguments to GRBaddconstr:

/* First constraint: x + 2 y + 3 z <= 4 */
ind[0] = 0; ind[1] = 1; ind[2] = 2;
val[0] = 1; val[1] = 2; val[2] = 3;

error = GRBaddconstr(model, 3, ind, val, GRB_LESS_EQUAL, 4.0, "c0");
if (error) goto QUIT;

The first argument of GRBaddconstr is the model to which the constraint is being added. The second is the total number of non-zero coefficients associated with the new constraint. The next two arguments describe the non-zeros in the new constraint. Constraint coefficients are specified using a list of index-value pairs, one for each non-zero value. In our example, the first constraint to be added is \(x + 2y + 3z \le 4\). We have chosen to make \(x\) the first variable in our constraint matrix, \(y\)  the second, and \(z\) the third (note that this choice is arbitrary). Given our variable ordering choice, the index-value pairs that are required for our first constraint are (0, 1.0), (1, 2.0), and (2, 3.0). These pairs are placed in the ind and val arrays.

The fifth argument to GRBaddconstr provides the sense of the new constraint. Possible values are GRB_LESS_EQUAL, GRB_GREATER_EQUAL, or GRB_EQUAL. The sixth argument gives the right-hand side value (in the C API, all the variables must appear on the left-hand side of the constraint). The final argument gives the name of the constraint (we allow the constraint to take its default name here by specifying NULL for the argument). The second constraint is added in a similar fashion.

Note that routine GRBaddconstrs would allow you to add both constraints in a single call. The arguments for this routine are much more complex, though, without providing any significant advantages, so we recommend that you add one constraint at a time.

The default sense for the objective function is minimization. Since our example aims to maximize the objective, we need to modify the ModelSense attribute:

/* Change objective sense to maximization */
error = GRBsetintattr(model, GRB_INT_ATTR_MODELSENSE, GRB_MAXIMIZE);
if (error) goto QUIT;

Now that the model has been built, the next step is to optimize it:

/* Optimize model */
error = GRBoptimize(model);
if (error) goto QUIT;

This routine performs the optimization and populates several internal model attributes, including the status of the optimization, the solution, etc. Once the function returns, we can query the values of these attributes. In particular, we can query the status of the optimization process by retrieving the value of the Status attribute.

/* Capture solution information */
error = GRBgetintattr(model, GRB_INT_ATTR_STATUS, &optimstatus);
if (error) goto QUIT;

The optimization status has many possible values. An optimal solution to the model may have been found, or the model may have been determined to be infeasible or unbounded, or the solution process may have been interrupted. A list of possible statuses can be found in the Gurobi Reference Manual. For our example, we know that the model is feasible, and we haven't modified any parameters that might cause the optimization to stop early (e.g., a time limit), so the status will be GRB_OPTIMAL.

An important model attribute is the value of the objective function for the computed solution. This is accessed through this call:

error = GRBgetdblattr(model, GRB_DBL_ATTR_OBJVAL, &objval);
if (error) goto QUIT;

Note that the GRBgetdblattr call would return a non-zero error result if no solution was found for this model.

Once we know that the model was solved, we can extract the X attribute of the model, which contains the value for each variable in the computed solution:

error = GRBgetdblattrarray(model, GRB_DBL_ATTR_X, 0, 3, sol);
if (error) goto QUIT;

The GRBgetdblattrarray routine retrieves the values of an array-valued attribute. The third and fourth arguments indicate the index of the first array element to be retrieved, and the number of elements to retrieve, respectively. In this example, we retrieve entries 0 through 2 (i.e., all three of them).

We would like to point out one additional aspect of the example. Almost all of the Gurobi methods return an error code. The code will typically be zero, indicating that no error was encountered, but it is important to check the value of the code in case an error arises.

While you may want to print a specialized error code at each point where an error may occur, the Gurobi interface provides a more flexible facility for reporting errors. The GRBgeterrormsg() routine returns a textual description of the most recent error associated with an environment:

/* Error reporting */
if (error) {
  printf("ERROR: %s\n", GRBgeterrormsg(env));
  exit(1);
}

Once the error reporting is done, the only remaining task in our example is to release the resources associated with our optimization task. In this case, we populated one model and created one environment. We call GRBfreemodel(model) to free the model, and GRBfreeenv(env) to free the environment (in that order).

To build and run the example, please refer to the files in <installdir>/examples/build.

For Linux and macOS platforms, the <installdir>/examples/build directory contains an example Makefile. Typing make mip1_c will build and run this example.

For Windows platforms, this directory contains C_examples_2015.sln, C_examples_2017.sln, and C_examples_2019.sln (Visual Studio 2015, 2017, and 2019 solution files for the C examples). Double-clicking on the solution file will bring up Visual Studio. Clicking on the mip1_c project, and then selecting Run from the Build menu will compile and run the example.

The C example directory <installdir>/examples/c contains a number of examples. We encourage you to browse and modify them in order to become more familiar with the Gurobi C interface. We also encourage you to read the Gurobi Example Tour for more information.