This class allows you to limit the branch-and-cut search within certain subtrees. For example, you may consider doing so in order to limit the number of branches or nodes to use when exploring a certain decision. Such search limits can be implemented in the context of Cplex goals by means of Cplex.SearchLimit objects.

To create your own search limit, you must subclass Cplex.SearchLimit and implement the method check. You may optionally implement the method init.

Also, if the default implementation of method clone is not adequate and the goal is to be used for parallel optimization, this method needs also be implemented by the user. Recall that the default clone method performs a shallow copy, so typically a user implementation would perform a deep copy for objects that should be local to threads or use the synchronize keyword where synchronization is required.

Prior to calling the methods check or init, Cplex initializes the search limit object as the node for which to determine whether a search limit has been encountered. This node is referred to as the current node.

The method check must be implemented in such a way that it returns true if the limit has been reached and false otherwise. Information about the current node can be queried through the protected API of the class Cplex.SearchLimit.

Before the method check is called for the first time, the virtual method init is called at that node. This method is called only once and allows you to initialize the search limit. As for the method check, information about the current node can be queried through the protected API of class Cplex.SearchLimit.

The method Cplex.LimitSearch is used to create a goal that imposes a limit on a search controlled by a goal, as shown in this example:

               Cplex.Goal limitGoal = cplex.LimitSearch(goal1, limit);
             

In this example limit is of type Cplex.SearchLimit and goal1 is of type Cplex.Goal. The method Cplex.LimitSearch creates and returns a new goal that performs branch-and-cut search as specified by goal1 until the limit specified by limit is reached. In doing so, the search limit defined by limit is active only for the search subtree generated by goal1. For example, if you created two branches with the goal

               cplex.Or(limitGoal, goal2);
             

only the subtree defined by goal1 is subjected to the search limit limit, while the subtree defined by goal2 is not.

The possibility of specifying search limits for subtrees leads to the possible situation where certain branches are subject to more than one search limit. Nodes with multiple search limits attached to them are processed only if none of the search limits has been reached, or, in other words, if all the search limits return false when the check method is called by Cplex.

The fact that search limits are tied to goals implies that as soon as the goal stack becomes empty and Cplex proceeds with built-in search strategies, the search limit is deactivated. In order to impose a search limit while using a built-in Cplex branch strategy, a goal such as the following one can be used.

               class DefaultSearchGoal extends Cplex.Goal {
                 public Cplex.Goal execute(Cplex cplex) throws ILOG.Concert.Exception {
                   if (!isIntegerFeasible())
                     return cplex.And(cplex.BranchAsCplex(), this);
                   return null;
                 }
               }