Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Modifying Solver Behavior - Callbacks

int GRBcbsetdblparam(void *cbdata, const char *paramname, double newvalue)

  Allows to modify callback settable double-valued parameters during a deterministic callback.

  That is, when the `where` value is `GRB_CB_PRESOLVED`, `GRB_CB_SIMPLEX`, `GRB_CB_MIP`, `GRB_CB_MIPSOL`, `GRB_CB_MIPNODE`, `GRB_CB_BARRIER`, or `GRB_CB_MULTIOBJ` (see the Callback Codes section for more information)

  In case of a remote server, the change of a parameter from within a callback may not be taken into account immediately.

  Return value:

    A non-zero return value indicates that a problem occurred while modifying the parameter. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling `GRBgeterrormsg`.

  Arguments:

    - cbdata – The `cbdata` argument that was passed into the user callback by the Gurobi Optimizer. This argument must be passed unmodified from the user callback to `GRBcbsetdblparam()`.

    - paramname – The name of the parameter. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

    - newvalue – The desired new value for the parameter.

  Example:

        error = GRBcbsetdblparam(cbdata, "TimeLimit", 100.0);

int GRBcbsetintparam(void *cbdata, const char *paramname, int newvalue)

  Allows to modify callback settable integer-valued parameters during a deterministic callback.

  That is, when the `where` value is `GRB_CB_PRESOLVED`, `GRB_CB_SIMPLEX`, `GRB_CB_MIP`, `GRB_CB_MIPSOL`, `GRB_CB_MIPNODE`, `GRB_CB_BARRIER`, or `GRB_CB_MULTIOBJ` (see the Callback Codes section for more information)

  In case of a remote server, the change of a parameter from within a callback may not be taken into account immediately.

  Return value:

    A non-zero return value indicates that a problem occurred while modifying the parameter. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling `GRBgeterrormsg`.

  Arguments:

    - cbdata – The `cbdata` argument that was passed into the user callback by the Gurobi Optimizer. This argument must be passed unmodified from the user callback to `GRBcbsetintparam()`.

    - paramname – The name of the parameter. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

    - newvalue – The desired new value of the parameter.

  Example:

        error = GRBcbsetintparam(cbdata, "BarIterLimit", 10);

int GRBcbsetstrparam(void *cbdata, const char *paramname, const char *newvalue)

  Allows to modify callback settable string-valued parameters during a deterministic callback.

  That is, when the `where` value is `GRB_CB_PRESOLVED`, `GRB_CB_SIMPLEX`, `GRB_CB_MIP`, `GRB_CB_MIPSOL`, `GRB_CB_MIPNODE`, `GRB_CB_BARRIER`, or `GRB_CB_MULTIOBJ` (see the Callback Codes section for more information)

  In case of a remote server, the change of a parameter from within a callback may not be taken into account immediately.

  Return value:

    A non-zero return value indicates that a problem occurred while modifying the parameter. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling `GRBgeterrormsg`.

  Arguments:

    - cbdata – The `cbdata` argument that was passed into the user callback by the Gurobi Optimizer. This argument must be passed unmodified from the user callback to `GRBcbsetstrparam()`.

    - paramname – The name of the parameter. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

    - newvalue – The desired new value of the parameter.

int GRBcbsetparam(void *cbdata, const char *paramname, const char *newvalue)

  Allows to modify callback settable parameters during a deterministic callback.

  That is, when the `where` value is `GRB_CB_PRESOLVED`, `GRB_CB_SIMPLEX`, `GRB_CB_MIP`, `GRB_CB_MIPSOL`, `GRB_CB_MIPNODE`, `GRB_CB_BARRIER`, or `GRB_CB_MULTIOBJ` (see the Callback Codes section for more information)

  In case of a remote server, the change of a parameter from within a callback may not be taken into account immediately.

  Return value:

    A non-zero return value indicates that a problem occurred while modifying the parameter. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling `GRBgeterrormsg`.

  Arguments:

    - cbdata – The `cbdata` argument that was passed into the user callback by the Gurobi Optimizer. This argument must be passed unmodified from the user callback to `GRBcbsetparam()`.

    - paramname – The name of the parameter. Please consult the parameter section for a complete list of Gurobi parameters, including descriptions of their purposes and their minimum, maximum, and default values.

    - newvalue – The desired new value of the parameter.

  Example:

        error = GRBcbsetparam(cbdata, "BarIterLimit", "10");

int GRBcbcut(void *cbdata, int cutlen, const int *cutind, const double *cutval, char cutsense, double cutrhs)

  Add a new cutting plane to the MIP model from within a user callback routine. Note that this routine can only be called when the `where` value on the callback routine is `GRB_CB_MIPNODE` (see the Callback Codes section for more information).

  Cutting planes can be added at any node of the branch-and-cut tree. Note that cuts should be added sparingly, since they increase the size of the relaxation model that is solved at each node and can significantly degrade node processing speed.

  Cutting planes are typically used to cut off the current relaxation solution. To retrieve the relaxation solution at the current node, call `GRBcbget` with `what = GRB_CB_MIPNODE_REL`.

  You should consider setting parameter PreCrush to value 1 when adding your own cuts. This setting shuts off a few presolve reductions that can sometimes prevent your cut from being applied to the presolved model (which would result in your cut being silently ignored).

  One very important note: you should only add cuts that are implied by the constraints in your model. If you cut off an integer solution that is feasible according to the original model constraints, you are likely to obtain an incorrect solution to your MIP problem.

  Return value:

    A non-zero return value indicates that a problem occurred while adding the cut. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling `GRBgeterrormsg`.

  Arguments:

    - cbdata – The `cbdata` argument that was passed into the user callback by the Gurobi Optimizer. This argument must be passed unmodified from the user callback to `GRBcbcut()`.

    - cutlen – The number of non-zero coefficients in the new cutting plane.

    - cutind – Variable indices for non-zero values in the new cutting plane.

    - cutval – Numerical values for non-zero values in the new cutting plane.

    - cutsense – Sense for the new cutting plane. Options are `GRB_LESS_EQUAL`, `GRB_EQUAL`, or `GRB_GREATER_EQUAL`.

    - cutrhs – Right-hand side value for the new cutting plane.

  Example:

        if (where == GRB_CB_MIPNODE) {
          int cutind[] = {0, 1};
          double cutval[] = {1.0, 1.0};
          error = GRBcbcut(cbdata, 2, cutind, cutval, GRB_LESS_EQUAL, 1.0);
          if (error) return 0;
        }

int GRBcblazy(void *cbdata, int lazylen, const int *lazyind, const double *lazyval, char lazysense, double lazyrhs)

  Add a new lazy constraint to the MIP model from within a user callback routine. Note that this routine can only be called when the `where` value on the callback routine is either `GRB_CB_MIPNODE` or `GRB_CB_MIPSOL` (see the Callback Codes section for more information).

  Lazy constraints are typically used when the full set of constraints for a MIP model is too large to represent explicitly. By only including the constraints that are actually violated by solutions found during the branch-and-cut search, it is sometimes possible to find a proven optimal solution while only adding a fraction of the full set of constraints.

  You would typically add a lazy constraint by querying the current node solution (by calling `GRBcbget` from a `GRB_CB_MIPSOL` or `GRB_CB_MIPNODE` callback, using `what=GRB_CB_MIPSOL_SOL` or `what=GRB_CB_MIPNODE_REL`), and then calling `GRBcblazy()` to add a constraint that cuts off the solution. Gurobi guarantees that you will have the opportunity to cut off any solutions that would otherwise be considered feasible.

  MIP solutions may be generated outside of a MIP node. Thus, generating lazy constraints is optional when the `where` value in the callback function equals `GRB_CB_MIPNODE`. To avoid this, we recommend to always check when the `where` value equals `GRB_CB_MIPSOL`.

  Your callback should be prepared to cut off solutions that violate any of your lazy constraints, including those that have already been added. Node solutions will usually respect previously added lazy constraints, but not always.

  Note that you must set the LazyConstraints parameter if you want to use lazy constraints.

  Return value:

    A non-zero return value indicates that a problem occurred while adding the lazy constraint. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling `GRBgeterrormsg`.

  Arguments:

    - cbdata – The `cbdata` argument that was passed into the user callback by the Gurobi Optimizer. This argument must be passed unmodified from the user callback to `GRBcblazy()`.

    - lazylen – The number of non-zero coefficients in the new lazy constraint.

    - lazyind – Variable indices for non-zero values in the new lazy constraint.

    - lazyval – Numerical values for non-zero values in the new lazy constraint.

    - lazysense – Sense for the new lazy constraint. Options are `GRB_LESS_EQUAL`, `GRB_EQUAL`, or `GRB_GREATER_EQUAL`.

    - lazyrhs – Right-hand side value for the new lazy constraint.

  Example:

        if (where == GRB_CB_MIPSOL) {
          int lazyind[] = {0, 1};
          double lazyval[] = {1.0, 1.0};
          error = GRBcblazy(cbdata, 2, lazyind, lazyval, GRB_LESS_EQUAL, 1.0);
          if (error) return 0;
        }

int GRBcbsolution(void *cbdata, const double *solution, double *objP)

  Provide a new feasible solution for a MIP model from within a user callback routine. Note that this routine can only be called when the `where` value on the callback routine is `GRB_CB_MIP`, `GRB_CB_MIPNODE`, or `GRB_CB_MIPSOL` (see the Callback Codes section for more information).

  Heuristics solutions are typically built from the current relaxation solution. To retrieve the relaxation solution at the current node, call `GRBcbget` with `what = GRB_CB_MIPNODE_REL`.

  When providing a solution, you can specify values for any subset of the variables in the model. To leave a variable value unspecified, set the variable to `GRB_UNDEFINED` in the `solution` vector. The Gurobi MIP solver will attempt to extend the specified partial solution to a complete solution.

  In the context of a Compute Server environment, for performance reasons, the solutions sent through `GRBcbsolution` are not necessarily processed by the Compute Server immediately. They may show up in the solving process a bit later after the client callback has sent them. In extreme cases, it could even be that the Compute Server optimization job terminates before it processes the user solution.

  Return value:

    A non-zero return value indicates that a problem occurred while adding the new solution. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling `GRBgeterrormsg`.

  Arguments:

    - cbdata – The `cbdata` argument that was passed into the user callback by the Gurobi Optimizer. This argument must be passed unmodified from the user callback to `GRBcbsolution()`.

    - solution – The solution vector. You must provide one entry for each variable in the model. Note that you can leave an entry unspecified by setting it to `GRB_UNDEFINED`. The Gurobi optimizer will attempt to find appropriate values for the unspecified variables.

    - objP – Objective value for solution that results from this call. Returns `GRB_INFINITY` if no improved solution is found or the function has been called from a callback other than `GRB_CB_MIPNODE` as, in these contexts, the solution is stored instead of being processed immediately.

  Example:

        if (where == GRB_CB_MIPNODE) {
          error = GRBcbsolution(cbdata, solution, &obj);
          if (error) return 0;
        }

int GRBcbproceed(void *cbdata)

  Generate a request to proceed to the next phase of the computation. This routine can be called from any callback. Note that the request is only accepted in a few phases of the algorithm, and it won’t be acted upon immediately.

  In the current Gurobi version, this callback allows you to proceed from the NoRel heuristic to the standard MIP search. You can determine the current algorithm phase using `MIP_PHASE`, `MIPNODE_PHASE`, or `MIPSOL_PHASE` queries from a callback.

  Return value:

    A non-zero return value indicates that a problem occurred while requesting to proceed. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling `GRBgeterrormsg`.

  Arguments:

    - cbdata – The `cbdata` argument that was passed into the user callback by the Gurobi optimizer. This argument must be passed unmodified from the user callback to `GRBcbproceed()`.

  Example:

        if (solution_objective < target_value) {
          GRBcbproceed(cbdata);
        }

int GRBcbstoponemultiobj(GRBmodel *model, void *cbdata, int objnum)

  Interrupt the optimization process of one of the optimization steps in a multi-objective MIP problem without stopping the hierarchical optimization process. Note that this routine can only be called for multi-objective MIP models and when the `where` value on the callback routine is not equal to `GRB_CB_MULTIOBJ` (see the Callback Codes section for more information).

  You would typically stop a multi-objective optimization step by querying the last finished number of multi-objectives steps, and using that number to stop the current step and move on to the next hierarchical objective (if any) as shown in the following example:

      #include <time.h>

      typedef struct {
        int    objcnt;
        time_t starttime;
      } usrdata_t;

      int mycallback(GRBmodel *model,
                     void     *cbdata,
                     int       where,
                     void     *usrdata)
      {
        int error = 0;
        usrdata_t *ud = (usrdata_t*)usrdata;

        if (where == GRB_CB_MULTIOBJ) {
          /* get current objective number */
          error = GRBcbget(cbdata, where, MULTIOBJ_OBJCNT, (void*)&ud->objcnt);
          if (error) goto QUIT;

          /* reset start time to current time */
          ud->starttime = time();

        } else if (time() - ud->starttime > BIG ||
                   /* takes too long or good enough */) {
          /* stop only this optimization step */
          error = GRBcbstoponemultiobj(model, cbdata, ud->objcnt);
          if (error) goto QUIT;
        }

      QUIT:
        return error;
      }

  You should refer to the section on Multiple Objectives for information on how to specify multiple objective functions and control the trade-off between them.

  Return value:

    A non-zero return value indicates that a problem occurred while stopping the multi-objective step specified by objcnt. Refer to the Error Codes table for a list of possible return values. Details on the error can be obtained by calling `GRBgeterrormsg`.

  Arguments:

    - model – The `model` argument that was passed into the user callback by the Gurobi Optimizer. This argument must be passed unmodified from the user callback to `GRBcbstoponemultiobj()`.

    - cbdata – The `cbdata` argument that was passed into the user callback by the Gurobi Optimizer. This argument must be passed unmodified from the user callback to `GRBcbstoponemultiobj()`.

    - objnum – The number of the multi-objective optimization step to interrupt. For processes running locally, this argument can have the special value -1, meaning to stop the current step.

void GRBterminate(GRBmodel *model)

  Generate a request to terminate the current optimization. This routine can be called at any time during an optimization (from a callback, from another thread, from an interrupt handler, etc.). Note that, in general, the request won’t be acted upon immediately.

  When the optimization stops, the Status attribute will be equal to `GRB_INTERRUPTED`.

  Arguments:

    - model – The model to terminate.

  Example:

        if (time_to_quit)
          GRBterminate(model);

Help and Feedback

Press `/` or click to search this documentation | Gurobi website | Gurobi community forum
Go to other Gurobi documentation | Gurobi download | Contact support