Java Reference Manual

This section documents the Gurobi Java interface. This manual begins with a quick overview of the classes exposed in the interface and the most important methods on those classes. It then continues with a comprehensive presentation of all of the available classes and methods.

Environments

The first step in using the Gurobi Java interface is to create an environment object. Environments are represented using the GRBEnv class. An environment acts as the container for all data associated with a set of optimization runs.

Models

You can create one or more optimization models within an environment. Each model is represented as an object of class GRBModel. A model consists of a set of decision variables (objects of class GRBVar), and a set of linear constraints (objects of class GRBConstr) or SOS constraints (objects of class GRBSOS) on these variables. Each variable has an associated lower bound, upper bound, objective coefficient, and type (continuous, binary, etc.). Each linear constraint has an associated sense (less-than-or-equal, greater-than-or-equal, or equal), and right-hand side value.

Constraints are specified by building linear expressions (objects of class GRBLinExpr), and then specifying relationships between these expressions (for example, requiring that one expression be equal to another).

An optimization model may be specified all at once, by loading the model from a file (using the appropriate GRBModel constructor, or built incrementally, by first constructing an empty object of class GRBModel and then subsequently calling GRBModel.addVar or GRBModel.addVars to add additional variables, and GRBModel.addConstr or GRBModel.addConstrs to add additional constraints. Models are dynamic entities; you can always add or remove variables or constraints.

Solving a Model

Once you have built a model, you can call GRBModel.optimize to compute a solution. By default, optimize 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 in a set of attributes of the model. These attributes can be queried using a set of attribute query methods on the GRBModel, GRBVar, and GRBConstr classes.

The Gurobi algorithms keep careful track of the state of the model, so calls to GRBModel.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 GRBModel.reset.

If a model is found to be infeasible, you can call GRBModel.computeIIS to compute an Irreducible Inconsistent Subsystem (IIS) for the model. 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.

After a MIP model has been solved, you can call GRBModel.fixedModel 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 (the LB attribute) can.

Attributes are queried using GRBVar.get, GRBConstr.get, or GRBModel.get, and modified using GRBVar.set, GRBConstr.set, or GRBModel.set. Attributes are grouped into a set of enums by type (GRB.CharAttr, GRB.DoubleAttr, GRB.IntAttr, GRB.StringAttr). The get() and set() methods are overloaded, so the type of the attribute determines the type of the returned value. Thus, constr.get(GRB_DoubleAttr_RHS) returns a double, while constr.get(GRB_CharAttr_Sense) returns a char.

If you wish to retrieve attribute values for a set of variables or constraints, it is usually more efficient to use the array methods on the associated GRBModel object. Method GRBModel.get includes signatures that allow you to query or modify attribute values for one-, two-, and three-dimensional arrays of variables or constraints.

The full list of 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 the chgCoeff method on a GRBModel object to change a single matrix coefficient. 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. Another way to modify the non-zeros in an existing constraint matrix is to remove a variable or constraint (through the GRBModel.remove method). The non-zero values associated with the deleted constraint or variable are removed along with the constraint or variable itself.

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 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.

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 GRBEnv.set. Current values may also be retrieved with GRBEnv.get. Parameters can be of type int, double, or String. You can also read a set of parameter settings from a file using GRBEnv.readParams, or write the set of changed parameters using GRBEnv.writeParams.

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 GRBModel.getEnv to retrieve the environment associated with a particular model if you want to change a parameter for that model.

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. If you would like to direct output to a file as well as to the screen, specify the log file name in the GRBEnv constructor. You can modify the LogfileName parameter if you wish to redirect the log to a different file after creating the environment object. 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 GRBCallback class. The GRBModel.setCallback method allows you to receive a periodic callback from the Gurobi optimizer. You do this by sub-classing the GRBCallback abstract class, and writing your own Callback() method on this class. You can call GRBCallback.getDoubleInfo, GRBCallback.getIntInfo, or GRBCallback.getSolution 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. The simplest control callback is GRBCallback.terminate, which asks the optimizer to terminate at the earliest convenient point. Method GRBCallback.solution allows you to inject a feasible solution (or partial solution) during the solution of a MIP model. Method GRBCallback.cut allows you to add a cutting plane during a MIP optimization.

Error Handling

All of the methods in the Gurobi Java library can throw an exception of type GRBException. When an exception occurs, additional information on the error can be obtained by retrieving the error code (using method GRBException.getErrorCode), or by retrieving the exception message (using method GRBException.getMessage from the parent class). The list of possible error return codes can be found in the Error Code section.

Subsections