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

# GRBCallback

GRBCallback

  Gurobi callback class. This is an abstract class. To implement a callback, you should create a subclass of this class and implement a `callback()` method. If you pass an object of this subclass to method `GRBModel.SetCallback` before calling `GRBModel.Optimize` or `GRBModel.ComputeIIS`, the `callback()` method of the class will be called periodically. Depending on where the callback is called from, you will be able to obtain various information about the progress of the optimization.

  Note that this class contains one protected int member variable: `where`. You can query this variable from your `callback()` method to determine where the callback was called from.

  Gurobi callbacks can be used both to monitor the progress of the optimization and to modify the behavior of the Gurobi Optimizer. A simple user callback function might call the `GRBCallback.GetIntInfo` or `GRBCallback.GetDoubleInfo` methods to produce a custom display, or perhaps to terminate optimization early (using `GRBCallback.Abort`) or to proceed to the next phase of the computation (using `GRBCallback.Proceed`). More sophisticated MIP callbacks might use `GRBCallback.GetNodeRel` or `GRBCallback.GetSolution` to retrieve values from the solution to the current node, and then use `GRBCallback.AddCut` or `GRBCallback.AddLazy` to add a constraint to cut off that solution, or `GRBCallback.SetSolution` to import a heuristic solution built from that solution. For multi-objective problems, you might use `GRBCallback.StopOneMultiObj` to interrupt the optimization process of one of the optimization steps in a multi-objective MIP problem without stopping the hierarchical optimization process.

  When solving a model using multiple threads, the user callback is only ever called from a single thread, so you don’t need to worry about the thread-safety of your callback.

  A few parameters are callback settable. These parameters can be modified from within a callback call using `GRBCallback.Set` methods.

  You can look at the callback_cs.cs example for details of how to use Gurobi callbacks.

  GRBCallback GRBCallback()

    Callback constructor.

    Returns:

      A callback object.

  void Abort()

    Abort optimization. When the optimization stops, the Status attribute will be equal to `GRB.Status.INTERRUPTED`.

  void AddCut(GRBLinExpr lhsExpr, char sense, double rhsVal)

    Add a cutting plane to the MIP model from within a callback function. Note that this method can only be invoked when the `where` member variable is equal to `GRB.Callback.MIPNODE` (see the Callback Codes section for more information).

    Cutting planes can be added at any node of the branch-and-cut tree. However, they 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, you should first call `GetNodeRel`.

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

    Note that cutting planes added through this method must truly be cutting planes – they can cut off continuous solutions, but they may not cut off integer solutions that respect the original constraints of the model. Ignoring this restriction will lead to incorrect solutions.

    Parameters:

      - lhsExpr – Left-hand side expression for new cutting plane.

      - sense – Sense for new cutting plane (`GRB.LESS_EQUAL`, `GRB.EQUAL`, or `GRB.GREATER_EQUAL`).

      - rhsVal – Right-hand side value for new cutting plane.

  void AddCut(GRBTempConstr tempConstr)

    Add a cutting plane to the MIP model from within a callback function. Note that this method can only be invoked when the `where` member variable is equal to `GRB.Callback.MIPNODE` (see the Callback Codes section for more information).

    Cutting planes can be added at any node of the branch-and-cut tree. However, they 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, you should first call `GetNodeRel`.

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

    Note that cutting planes added through this method must truly be cutting planes – they can cut off continuous solutions, but they may not cut off integer solutions that respect the original constraints of the model. Ignoring this restriction will lead to incorrect solutions.

    Parameters:

      tempConstr – Temporary constraint object, created by an overloaded comparison operator.

  void AddLazy(GRBLinExpr lhsExpr, char sense, double rhsVal)

    Add a lazy constraint to the MIP model from within a callback function. Note that this method can only be invoked when the `where` member variable is `GRB.Callback.MIPNODE` or `GRB.Callback.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 first querying the current node solution (by calling `GetSolution` from a `GRB.Callback.MIPSOL` callback, or `GetNodeRel` from a `GRB.Callback.MIPNODE` callback), and then calling `AddLazy()` 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.Callback.MIPNODE`. To avoid this, we recommend to always check when the `where` value equals `GRB.Callback.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.

    Parameters:

      - lhsExpr – Left-hand side expression for new lazy constraint.

      - sense – Sense for new lazy constraint (`GRB.LESS_EQUAL`, `GRB.EQUAL`, or `GRB.GREATER_EQUAL`).

      - rhsVal – Right-hand side value for new lazy constraint.

  void AddLazy(GRBTempConstr tempConstr)

    Add a lazy constraint to the MIP model from within a callback function. Note that this method can only be invoked when the `where` member variable is `GRB.Callback.MIPNODE` or `GRB.Callback.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 first querying the current node solution (by calling `GetSolution` from a `GRB.Callback.MIPSOL` callback, or `GetNodeRel` from a `GRB.Callback.MIPNODE` callback), and then calling `AddLazy()` 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.Callback.MIPNODE`. To avoid this, we recommend to always check when the `where` value equals `GRB.Callback.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.

    Parameters:

      tempConstr – Temporary constraint object, created by an overloaded comparison operator.

  double GetDoubleInfo(int what)

    Request double-valued callback information. The available information depends on the value of the `where` member. For information on possible values of `where`, and the double-valued information that can be queried for different values of `where`, please refer to the Callback section.

    Parameters:

      what – Information requested (refer the list of Gurobi Callback Codes for possible values).

    Returns:

      Value of requested callback information.

  int GetIntInfo(int what)

    Request int-valued callback information. The available information depends on the value of the `where` member. For information on possible values of `where`, and the int-valued information that can be queried for different values of `where`, please refer to the Callback section.

    Parameters:

      what – Information requested (refer the list of Gurobi Callback Codes for possible values).

    Returns:

      Value of requested callback information.

  double GetNodeRel(GRBVar v)

    Retrieve a value from the node relaxation solution at the current node. Only available when the `where` member variable is equal to `GRB.Callback.MIPNODE`, and `GRB.Callback.MIPNODE_STATUS` is equal to `GRB.Status.OPTIMAL` (see the Callback Codes section for more information).

    Note that the relaxation solution retrieved at a node is not necessarily feasible for the user model.

    Parameters:

      v – The variable whose value is desired.

    Returns:

      The value of the specified variable in the node relaxation for the current node.

  double[] GetNodeRel(GRBVar[] xvars)

    Retrieve values from the node relaxation solution at the current node. Only available when the `where` member variable is equal to `GRB.Callback.MIPNODE`, and `GRB.Callback.MIPNODE_STATUS` is equal to `GRB.Status.OPTIMAL` (see the Callback Codes section for more information).

    Note that the relaxation solution retrieved at a node is not necessarily feasible for the user model.

    Parameters:

      xvars – The list of variables whose values are desired.

    Returns:

      The values of the specified variables in the node relaxation for the current node.

  double[][] GetNodeRel(GRBVar[][] xvars)

    Retrieve values from the node relaxation solution at the current node. Only available when the `where` member variable is equal to `GRB.Callback.MIPNODE`, and `GRB.Callback.MIPNODE_STATUS` is equal to `GRB.Status.OPTIMAL` (see the Callback Codes section for more information).

    Note that the relaxation solution retrieved at a node is not necessarily feasible for the user model.

    Parameters:

      xvars – The array of variables whose values are desired.

    Returns:

      The values of the specified variables in the node relaxation for the current node.

  double GetSolution(GRBVar v)

    Retrieve values from the current solution vector. Only available when the `where` member variable is equal to `GRB.Callback.MIPSOL` or `GRB.Callback.MULTIOBJ`.

    Parameters:

      v – The variable whose value is desired.

    Returns:

      The value of the specified variable in the current solution vector.

  double[] GetSolution(GRBVar[] xvars)

    Retrieve values from the current solution vector. Only available when the `where` member variable is equal to `GRB.Callback.MIPSOL` or `GRB.Callback.MULTIOBJ`.

    Parameters:

      xvars – The list of variables whose values are desired.

    Returns:

      The values of the specified variables in the current solution.

  double[][] GetSolution(GRBVar[][] xvars)

    Retrieve values from the current solution vector. Only available when the `where` member variable is equal to `GRB.Callback.MIPSOL` or `GRB.Callback.MULTIOBJ`.

    Parameters:

      xvars – The array of variables whose values are desired.

    Returns:

      The values of the specified variables in the current solution.

  string GetStringInfo(int what)

    Request string-valued callback information. The available information depends on the value of the `where` member. For information on possible values of `where`, and the string-valued information that can be queried for different values of `where`, please refer to the Callback section.

    Parameters:

      what – Information requested (refer the list of Gurobi Callback Codes for possible values).

    Returns:

      Value of requested callback information.

  void Proceed()

    Generate a request to proceed to the next phase of the computation. 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.

  void Set(GRB.DoubleParam param, double newvalue)

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

    That is, when the `where` value is `GRB.Callback.PRESOLVED`, `GRB.Callback.SIMPLEX`, `GRB.Callback.MIP`, `GRB.Callback.MIPSOL`, `GRB.Callback.MIPNODE`, `GRB.Callback.BARRIER`, or `GRB.Callback.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.

    Parameters:

      - param – The parameter being modified.

      - newvalue – The desired new value for the parameter.

  void Set(GRB.IntParam param, int newvalue)

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

    That is, when the `where` value is `GRB.Callback.PRESOLVED`, `GRB.Callback.SIMPLEX`, `GRB.Callback.MIP`, `GRB.Callback.MIPSOL`, `GRB.Callback.MIPNODE`, `GRB.Callback.BARRIER`, or `GRB.Callback.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.

    Parameters:

      - param – The parameter being modified.

      - newvalue – The desired new value for the parameter.

  void Set(GRB.StringParam param, string newvalue)

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

    That is, when the `where` value is `GRB.Callback.PRESOLVED`, `GRB.Callback.SIMPLEX`, `GRB.Callback.MIP`, `GRB.Callback.MIPSOL`, `GRB.Callback.MIPNODE`, `GRB.Callback.BARRIER`, or `GRB.Callback.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.

    Parameters:

      - param – The parameter being modified.

      - newvalue – The desired new value for the parameter.

  void SetSolution(GRBVar v, double val)

    Import solution values for a heuristic solution. Only available when the `where` member variable is equal to `GRB.Callback.MIP`, `GRB.Callback.MIPNODE`, or `GRB.Callback.MIPSOL` (see the Callback Codes section for more information).

    When you specify a heuristic solution from a callback, variables initially take undefined values. You should use this method to specify variable values. You can make multiple calls to `SetSolution` from one callback invocation to specify values for multiple sets of variables. After the callback, if values have been specified for any variables, the Gurobi Optimizer will try to compute a feasible solution from the specified values, possibly filling in values for variables whose values were left undefined. You can also optionally call `UseSolution` within your callback function to try to immediately compute a feasible solution from the specified values.

    In the context of a Compute Server environment, for performance reasons, the solutions sent through `SetSolution` 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.

    Parameters:

      - v – The variable whose values is being set.

      - val – The value of the variable in the new solution.

  void SetSolution(GRBVar[] xvars, double[] sol)

    Import solution values for a heuristic solution. Only available when the `where` member variable is equal to `GRB.Callback.MIP`, `GRB.Callback.MIPNODE`, or `GRB.Callback.MIPSOL` (see the Callback Codes section for more information).

    When you specify a heuristic solution from a callback, variables initially take undefined values. You should use this method to specify variable values. You can make multiple calls to `SetSolution` from one callback invocation to specify values for multiple sets of variables. After the callback, if values have been specified for any variables, the Gurobi Optimizer will try to compute a feasible solution from the specified values, possibly filling in values for variables whose values were left undefined. You can also optionally call `UseSolution` within your callback function to try to immediately compute a feasible solution from the specified values.

    In the context of a Compute Server environment, for performance reasons, the solutions sent through `SetSolution` 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.

    Parameters:

      - xvars – The variables whose values are being set.

      - sol – The desired values of the specified variables in the new solution.

  void StopOneMultiObj(int objcnt)

    Interrupt the optimization process of one of the optimization steps in a multi-objective MIP problem without stopping the hierarchical optimization process. Only available for multi-objective MIP models and when the where member variable is not equal to GRB.Callback.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:

        using Gurobi;

        class callback : GRBCallback
        {

          private int objcnt;
          private long starttime;

          protected override void Callback() {
            try {
              if (where == GRB.Callback.MULTIOBJ) {
                /* get current objective number */
                objcnt    = GetIntInfo(GRB.Callback.MULTIOBJ_OBJCNT);

                /* reset start time to current time */
                starttime = DateTime.Now.Ticks;

              } else if (DateTime.Now.Ticks - starttime > BIG ||
                         /* takes too long or good enough */) {
                /* stop only this optimization step */
                StopOneMultiObj(objcnt);
              }
            }
          }
        }

    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.

    Parameters:

      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.

  double UseSolution()

    Once you have imported solution values using `SetSolution`, you can optionally call `UseSolution` in a `GRB.Callback.MIPNODE` callback to immediately use these values to try to compute a heuristic solution. Alternatively, you can call `UseSolution` in a `GRB.Callback.MIP` or `GRB.Callback.MIPSOL` callback, which will store the solution until it can be processed internally.

    Returns:

      The objective value for the solution obtained from your solution values. It equals `GRB.INFINITY` if no improved solution is found or the method has been called from a callback other than `GRB.Callback.MIPNODE` as, in these contexts, the solution is stored instead of being processed immediately.

Help and Feedback

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