Documentation

Next: gurobi_iis() Up: Solving a Model Previous: Solving a Model

gurobi()

This function optimizes the given model. The algorithm used for the optimization depends on the model type (simplex or barrier for a continuous model; branch-and-cut for a MIP model). Upon successful completion it will return a struct variable containing solution information.

Please consult Variables and Constraints section in the reference manual for a discussion of some of the practical issues associated with solving a precisely defined mathematical model using finite-precision floating-point arithmetic.

Arguments:

model: The model struct must contain a valid Gurobi model. See the model argument section for more information.

params: The params struct, when provided, contains a list of modified Gurobi parameters. See the params argument section for more information.

Example usage:

    result = gurobi(model, params);
    if strcmp(result.status, 'OPTIMAL');
      fprintf('Optimal objective: %e\n', result.objval);
      disp(result.x)
    else
      fprintf('Optimization returned status: %s\n', result.status);
    end

The optimization result

The gurobi function returns a struct, with the various results of the optimization stored in its fields. The specific results that are available depend on the type of model that was solved, the parameters used, and the status of the optimization. The following is a list of fields that might be available in the returned result. We will discuss the circumstances under which each will be available after presenting the list.

Model fields

status

The status of the optimization, returned as a string. The desired result is OPTIMAL, which indicates that an optimal solution to the model was found. Other status are possible, for example if the model has no feasible solution or if you set a Gurobi parameter that leads to early solver termination. See the Status Code section for further information on the Gurobi status codes.

objval

The objective value of the computed solution. Note that for multi-objective models result.objval will be a vector, where result.objval(i) stores the value for model.multiobj(i).

objbound

Best available bound on solution (lower bound for minimization, upper bound for maximization).

objboundc

The best unrounded bound on the optimal objective. In contrast to objbound, this attribute does not take advantage of objective integrality information to round to a tighter bound. For example, if the objective is known to take an integral value and the current best bound is 1.5, objbound will return 2.0 while objboundc will return 1.5.

mipgap

Current relative MIP optimality gap; computed as (where and are the MIP objective bound and incumbent solution objective, respectively). Returns GRB_INFINITY when an incumbent solution has not yet been found, when no objective bound is available, or when the current incumbent objective is 0. This is only available for mixed-integer problems.

runtime

The elapsed wall-clock time (in seconds) for the optimization.

work

The work (in work units) spent on the optimization. As opposed to the runtime in seconds, the work is deterministic. This means that on the same hardware and with the same parameter and attribute settings, solving the same model twice will lead to exactly the same amount of work in each of the two solves. One work unit corresponds very roughly to one second, but this greatly depends on the hardware on which Gurobi is running and on the model that has been solved.

itercount

Number of simplex iterations performed.

baritercount

Number of barrier iterations performed.

nodecount

Number of branch-and-cut nodes explored.

maxvio

Value of the maximal (unscaled) violation of the returned solution.

farkasproof

Magnitude of infeasibility violation in Farkas infeasibility proof. Only available if the model was found to be infeasible. Please refer to Attribute section in the reference manual for details.

Variable fields

x

The computed solution. This vector contains one entry for each column of A.

rc

Variable reduced costs for the computed solution. This vector contains one entry for each column of A.

vbasis

Variable basis status values for the computed optimal basis. You generally should not concern yourself with the contents of this vector. If you wish to use an advanced start later, you would simply copy the vbasis and cbasis fields into the corresponding fields for the next model. This vector contains one entry for each column of A.

unbdray

Unbounded ray. Provides a vector that, when added to any feasible solution, yields a new solution that is also feasible but improves the objective. Only available if the model is found to be unbounded. This vector contains one entry for each column of A.

Linear constraint fields

slack

The constraint slack for the computed solution. This vector contains one entry for each row of A.

pi

Dual values for the computed solution (also known as shadow prices). This vector contains one entry for each row of A.

cbasis

Constraint basis status values for the computed optimal basis. This vector contains one entry for each row of A.

farkasdual

Farkas infeasibility proof. Only available if the model was found to be infeasible. Please refer to Attribute section in the reference manual for details.

Quadratic constraint fields

qcslack

The quadratic constraint slack in the current solution. This vector contains one entry for each quadratic constraint.

qcpi

The dual values associated with the quadratic constraints. This vector contains one entry for each quadratic constraint.

Solution Pool fields

pool

When multiple solutions are found during the optimization call, these solutions are returned in this field. A struct array. When present, each struct has the following fields:

objval

Stores the objective value of the -th solution in result.pool(i).objval. Note that when the model is a multi-objective model, instead of a single value,
result.pool(i).objval(j) stores the value of the -th objective function for the -th solution.

xn

Stores the -th solution in result.pool(i).xn. This vector contains one entry for each column of A.

Note that to query the number of solutions stored, you can query the length of result.pool.

poolobjbound

For single-objective MIP optimization problems, this value gives a bound on the best possible objective of an undiscovered solution. The difference between this value and objbound is that the former gives an objective bound for undiscovered solutions, while the latter gives a bound for any solution.

What is Available When

The status field will be present in all cases. It indicates whether Gurobi was able to find a proven optimal solution to the model. In cases where a solution to the model was found, optimal or otherwise, the objval and x fields will be present.

For linear and quadratic programs, if a solution is available, then the pi and rc fields will also be present. For models with quadratic constraints, if the parameter qcpdual is set to 1, the field qcpi will be present. If the final solution is a basic solution (computed by simplex), then vbasis and cbasis will be present. If the model is an unbounded linear program and the InfUnbdInfo parameter is set to 1, the field unbdray will be present. Finally, if the model is an infeasible linear program and the InfUnbdInfo parameter is set to 1, the fields farkasdual and farkasproof will be set.

For mixed integer problems, no dual information (i.e. pi, slack, rc, vbasis, cbasis, qcslack, qcpi, ubdray or farkasdual) is ever available. When multiple solutions are found, the pool and poolobjbound fields will be present. Depending on the status field value, the fields nodecount, objbound, objbundc and mipgap will be available.

For continuous and mixed-integer models, under normal execution, the fields runtime, work, itercount and baritercount will be available.

---

Next: gurobi_iis() Up: Solving a Model Previous: Solving a Model