| Overview | Group | Tree | Graph | Index | Concepts |
This is an advanced class. Advanced classes typically demand a profound understanding of the algorithms used by ILOG CPLEX. Thus they incur a higher risk of incorrect behavior in your application, behavior that can be difficult to debug. Therefore, ILOG encourages you to consider carefully whether you can accomplish the same task by means of other classes instead.
Goals can be used to control the branch & cut search in
IloCplex. Goals are implemented in
subclasses of the class IloCplex::GoalI. This is the base
class for user-written implementation classes of CPLEX goals.
To implement your own goal you need to create a subclass of
IloCplex::GoalI and implement its pure virtual methods
execute and duplicateGoal.
You may use one of the ILOCPLEXGOAL0
macros to assist you in doing so. After
implementing your goal class, you use an instance of the class
by passing it to the
solve method when solving the model.
The method duplicateGoal may
be called by IloCplex to create copies of a
goal when needed for parallel branch & cut search. Thus the
implementation of this method must create and return an exact copy of the
invoked object itself.
The method execute controls the branch & cut search of
IloCplex by the goal it returns. When
IloCplex processes a node, it pops the top
goal from the node's goal stack and calls method
execute of that goal. It continues executing the top goal
from the stack until the node is deactivated or
the goal stack is empty. If
the goal stack is empty, IloCplex proceeds
with the built-in search strategy for the subtree rooted at the current
node.
The class IloCplex::GoalI provides several
methods for querying
information about the current node. The method execute
controls how to proceed with the branch & cut
search via the goal it returns. The returned goal, unless it is the 0 goal,
is pushed on the goal stack and will thus be executed next.
See also the chapter about goals in the ILOG CPLEX User's Manual.
| Constructor Summary | |
|---|---|
public | GoalI(IloEnv env) |
| Inner Enumeration |
|---|
| GoalI::BranchType |
| GoalI::IntegerFeasibility |
| Inner Typedef |
|---|
| GoalI::IntegerFeasibilityArray |
| Constructor Detail |
|---|
The goal constructor. It requires an instance of the same
IloEnv as the IloCplex object with which to
use the goal. The environment can later be queried by calling method
getEnv.
| Method Detail |
|---|
The static methods AndGoal all return a goal that
pushes the goals passed as parameters onto the goal stack in reverse
order. As a consequence, the goals will be executed in the order
they are passed as parameters to the AndGoal function.
This static function returns a goal that creates the same branches as
the currently selected built-in branch strategy of
IloCplex would choose at the current node. This goal
allows you to proceed with the IloCplex
search strategy, but keeps the search under goal control, thereby giving
you the option to intervene at any point.
This goal is also important when you use node evaluators while you use a built-in branching strategy.
For example, consider the execute method
of a goal starting like this:
if (!isIntegerFeasible())
return AndGoal(BranchAsCplexGoal(getEnv()), this);
// do something
It would do something only when
IloCplex found a solution it considers to be a candidate
for a new incumbent. Note there is a test of integer feasibility before
returning BranchAsCplexGoal. Without the test,
BranchAsCplex would be executed for a solution
IloCplex considers to be feasible, but
IloCplex would not know how to branch on
it. An endless loop would result.
This static method creates a goal that fails. That means that the branch where the goal is executed will be pruned or, equivalently, the search is discontinued at that node and the node is discarded.
This method creates a goal that when executed adds the constraints
(provided in the paramter array con) as global cuts to the
model.
These global cuts must be valid for the entire model, not only for the
current subtree. In other words, these global cuts will be respected at
every node.
IloCplex takes over memory managment for the cuts
passed to the method GlobalCutGoal.
Thus IloCplex will call the method end
as soon as it can be discarded after
the goal executes. Calling end yourself
or the constraints in the
array con passed to method GlobalCutGoal or
the array itself is an error and must be avoided.
This method creates a goal that when executed adds the constraint
con (provided as a parameter) as global cuts to the model.
These global cuts must be valid for the entire model, not only for the
current subtree. In other words, these global cuts will be respected at
every node.
IloCplex takes over memory managment for the cut
passed to the method GlobalCutGoal.
Thus IloCplex
will call the method end
as soon as it can be discarded after
the goal executes. Calling end yourself for the constraint
passed to method GlobalCutGoal is an error and must be
avoided.
The static methods OrGoal all return a goal that creates
as many branches (or, equivalently, subproblems) as there are parameters.
Each of the subnodes will be initialized with the remaining goal stack
of the current node. In addition, the goal parameter will be pushed on
the goal stack of the corresponding subgoal. If more than six branches
need to be created, instances of OrGoal can be combined.
This static method creates and returns a goal that attempts to
inject a solution specified by setting the variables listed in array
vars to the corresponding values listed in the array
vals.
IloCplex will not blindly accept
such a solution as a new incumbent. Instead, it will make sure that
this solution is compatible with both the model and the goals. When
checking feasibility with goals, it checks feasibility with both the
goals that have already been executed and the goals that are still
on the goal stack. Thus, in particular,
IloCplex will reject any solution that
is not compatible with the branching that has been done so far.
IloCplex takes over memory managment
for arrays vars and vals passed to
SolutionGoal. Thus IloCplex
will call method end for these arrays as soon as they can be
discarded. Calling end for the arrays passed to
SolutionGoal is an error and must be avoided.
This static method creates and returns a goal that attempts to
inject a solution specified by setting the variables listed in array
vars to the corresponding values listed in the array
vals.
IloCplex will not blindly accept
such a solution as a new incumbent. Instead, it will make sure that
this solution is compatible with both the model and the goals. When
checking feasibility with goals, it checks feasibility with both the
goals that have already been executed and the goals that are still
on the goal stack. Thus, in particular,
IloCplex will reject any solution that
is not compatible with the branching that has been done so far.
IloCplex takes over memory managment
for arrays vars and vals passed to
SolutionGoal. Thus IloCplex
will call method end for these arrays as soon as they can be
discarded. Calling end for the arrays passed to
SolutionGoal is an error and must be avoided.
Abort the optimization, that is,
the execution of method
IloCplex::solve currently in process.
This virtual method must be implemented by the user.
It must return a copy of the invoking goal object. This
method may be called by IloCplex when
doing parallel branch & cut search.
This virtual method must be implemented by the
user to specify the logic of the goal. The
instance of IloCplex::Goal
returned by this method will be added to the goal stack of the node
where the invoking goal is being executed
for further execution.
This method returns the currently best known bound on the optimal
solution value of the problem at the time the invoking goal is
executed by an instance of IloCplex while solving a MIP.
When a model has been solved to optimality, this value matches the
optimal solution value. Otherwise, this value is computed for a
minimization (maximization) problem as the minimum (maximum) objective
function value of all remaining unexplored nodes.
This method accesses branching information for the i-th
branch that the invoking instance of
IloCplex
is about to create. The parameter i must be between 0
(zero) and getNbranches - 1; that is, it must be a valid
index of a branch; normally, it will be zero or one.
A branch is normally defined by a set of variables and the bounds for these variables. Branches that are more complex cannot be queried. The return value is the node estimate for that branch.
vars contains the variables for which
new bounds will be set in the i-th branch.bounds contains the new bounds for the
variables listed in vars; that is, bounds[j]
is the new bound for vars[j].dirs specifies the branching direction
for the variables in vars. dir[j] == IloCplex::BranchUp
means that bounds[j] specifies a lower bound for
vars[j].
dirs[j] == IloCplex::BranchDown
means that bounds[j] specifies an upper bound for
vars[j].
This method returns the type of branching
IloCplex
is going to do for the current node.
The method returns the current cutoff value.
An instance of IloCplex uses
the cutoff value (the value of the objective
function of the subproblem at a node in the
search tree) to decide when to prune nodes
from the search tree (that is, when to cut off that
node and discard the nodes beyond it). The cutoff value is updated
whenever a new incumbent is found.
This method returns the branch direction previously assigned to
variable var with method
IloCplex::setDirection or
IloCplex::setDirections.
If no direction has been assigned,
IloCplex::BranchGlobal will be returned.
This method returns the branch direction previously assigned to
variable var with method
IloCplex::setDirection or
IloCplex::setDirections.
If no direction has been assigned,
IloCplex::BranchGlobal will be returned.
This method returns the current pseudo cost for branching
downward on the variable var.
This method returns the current pseudo cost for branching
downward on the variable var.
Returns the instance of IloEnv
passed to the constructor of the goal.
This method considers whether each of the variables in the array
vars is integer feasible, integer infeasible, or implied
integer feasible and puts the status in the corresponding element
of the array stats.
This method considers whether each of the variables in the array
vars is integer feasible, integer infeasible, or implied
integer feasible and puts the status in the corresponding element
of the array stats.
This method specifies whether the SOS sos is
integer feasible, integer infeasible, or implied integer feasible in
the current node solution.
This method specifies whether the SOS sos is
integer feasible, integer infeasible, or implied integer feasible in
the current node solution.
This method specifies whether the variable var is
integer feasible, integer infeasible, or implied integer feasible in
the current node solution.
This method specifies whether the variable var is
integer feasible, integer infeasible, or implied integer feasible in
the current node solution.
This method returns the value of the objective function of the incumbent solution (that is, the best integer solution found so far). If there is no incumbent, this method throws an exception.
This method returns the value of var in the
incumbent solution. If there is no incumbent, this method throws an
exception.
This method returns the value of var in the
incumbent solution. If there is no incumbent, this method throws an
exception.
Returns the value of each variable in the array
vars with respect to the current incumbent
solution, and it puts those values into the
corresponding array vals.
If there is no incumbent, this method
throws an exception.
Returns the value of each variable in the array
vars with respect to the current incumbent
solution, and it puts those values into the
corresponding array vals.
If there is no incumbent, this method
throws an exception.
This method returns the lower bound of var in the
current node relaxation. This bound is likely to be different from
the bound in the original model because an instance of
IloCplex tightens bounds when it
branches from a node to its subnodes.
Unbounded Variables
If a variable lacks a lower bound, then getLB
returns a value greater than or equal to -IloInfinity
for greater than or equal to constraints with no lower bound.
This method returns the lower bound of var in the
current node relaxation. This bound is likely to be different from
the bound in the original model because an instance of
IloCplex tightens bounds when it
branches from a node to its subnodes.
Unbounded Variables
If a variable lacks a lower bound, then getLB
returns a value greater than or equal to -IloInfinity
for greater than or equal to constraints with no lower bound.
This method puts the lower bound in the current node relaxation of
each element of the array vars into the corresponding
element of the array vals. These bounds are likely to be
different from the bounds in the original model because an instance of
IloCplex tightens bounds when it
branches from a node to its subnodes.
Unbounded Variables
If a variable lacks a lower bound, then getLBs
returns a value greater than or equal to -IloInfinity
for greater than or equal to constraints with no lower bound.
This method puts the lower bound in the current node relaxation of
each element of the array vars into the corresponding
element of the array vals. These bounds are likely to be
different from the bounds in the original model because an instance of
IloCplex tightens bounds when it
branches from a node to its subnodes.
Unbounded Variables
If a variable lacks a lower bound, then getLBs
returns a value greater than or equal to -IloInfinity
for greater than or equal to constraints with no lower bound.
This method returns the model currently extracted for the
instance of IloCplex where the
invoking goal applies.
Returns the identifier of the parallel thread being currently
executed. This number is between 0 (zero) and the value
returned by the method getUserThreads()-1.
Returns the total number of GUB cover cuts that have been added to the model so far during the current optimization.
Returns the total number of MIR cuts that have been added to the model so far during the current optimization.
This method returns the number of branches
IloCplex is going to create at the current node.
Returns the total number of clique cuts that have been added to the model so far during the current optimization.
This method returns the number of columns in the current optimization model.
Returns the total number of cover cuts that have been added to the model so far during the current optimization.
Returns the total number of disjunctive cuts that have been added to the model so far during the current optimization.
Returns the total number of flow cover cuts that have been added to the model so far during the current optimization.
Returns the total number of flow path cuts that have been added to the model so far during the current optimization.
Returns the total number of fractional cuts that have been added to the model so far during the current optimization.
Returns the total number of implied bound cuts that have been added to the model so far during the current optimization.
Returns the total number of iterations executed so far during the current optimization to solve the node relaxations.
This method returns the number of nodes already processed in the current optimization.
This method returns the number of nodes left to explore in the current optimization.
This method returns the number of rows in the current optimization model.
Returns the linear objective coefficient for var
in the model currently being solved.
Returns the linear objective coefficient for var
in the model currently being solved.
This method puts the linear objective coefficient of each of the
variables in the array vars into the corresponding element
of the array vals.
This method puts the linear objective coefficient of each of the
variables in the array vars into the corresponding element
of the array vals.
This method returns the objective value of the solution of the current node.
If you need the object representing the objective itself,
consider the method
IloCplex::getObjective instead.
Returns the branch priority used for
variable var in the current optimization.
Returns the branch priority used for
variable var in the current optimization.
This method returns the slack value for
the constraint specified by rng in
the solution of the current node relaxation.
This method puts the slack value in the solution of the current
node relaxation of each
of the constraints in the array of ranges rngs
into the corresponding element of the array vals.
This method returns the upper bound of the variable var
in the current node relaxation. This bound is likely to be different
from the bound in the original model because an instance of
IloCplex tightens bounds when it
branches from a node to its subnodes.
Unbounded Variables
If a variable lacks an upper bound, then getUB
returns a value less than or equal to IloInfinity
for less than or equal to constraints with no lower bound.
This method returns the upper bound of the variable var
in the current node relaxation. This bound is likely to be different
from the bound in the original model because an instance of
IloCplex tightens bounds when it
branches from a node to its subnodes.
Unbounded Variables
If a variable lacks an upper bound, then getUB
returns a value less than or equal to IloInfinity
for less than or equal to constraints with no lower bound.
This method puts the upper bound in the current node relaxation of
each element of the array vars into the corresponding
element of the array vals. These bounds are likely to be
different from the bounds in the original model because an instance of
IloCplex tightens bounds when it
branches from a node to its subnodes.
Unbounded Variables
If a variable lacks an upper bound, then getUBs
returns a value less than or equal to IloInfinity
for less than or equal to constraints with no lower bound.
This method puts the upper bound in the current node relaxation of
each element of the array vars into the corresponding
element of the array vals. These bounds are likely to be
different from the bounds in the original model because an instance of
IloCplex tightens bounds when it
branches from a node to its subnodes.
Unbounded Variables
If a variable lacks an upper bound, then getUBs
returns a value less than or equal to IloInfinity
for less than or equal to constraints with no lower bound.
This method returns the current pseudo cost for branching
upward on the variable var.
This method returns the current pseudo cost for branching
upward on the variable var.
This method returns the total number of parallel threads currently running.
This method returns the value of the variable var
in the solution of the current node relaxation.
This method returns the value of the variable var
in the solution of the current node relaxation.
This method returns the value of the expression
expr in the solution of the current node relaxation.
This method puts the current node relaxation solution value of each
variable in the array vars into the corresponding element
of the array vals.
This method puts the current node relaxation solution value of each
variable in the array vars into the corresponding element
of the array vals.
This method returns IloTrue if an integer feasible
solution has been found.
This method returns IloTrue if the solution of the
current node is integer feasible.
This method returns IloTrue if the solution of the
current node is SOS feasible for the special ordered set specified in
its argument. The SOS passed as a parameter to this method must be
of type 2; the equivalent method for an SOS of type 1 is also available.
See the
User's Manual for more about these types of special
ordered sets.
This method returns IloTrue if the solution of the
current node is SOS feasible for the special ordered set specified in
its argument. The SOS passed as a parameter to this method must be
of type 1; the equivalent method for an SOS of type 2 is also available.
See the
User's Manual for more about these types of special
ordered sets.
| Inner Enumeration Detail |
|---|
IloCplex::GoalI::BranchType is an enumeration limited in
scope to the class IloCplex::GoalI. This
enumeration is used by the method
IloCplex::GoalI::getBranchType
to tell what kind of branch
IloCplex is about to make:
BranchOnVariable
specifies branching on a single variable.BranchOnAny
specifies multiple bound changes and
constraints will be used for branching. BranchOnSOS1
specifies branching on an SOS of type 1.BranchOnSOS2
specifies branching on an SOS of type 2.See Also:
| Fields |
|---|
| BranchOnVariable |
= CPX_TYPE_VAR
|
| BranchOnSOS1 |
= CPX_TYPE_SOS1
|
| BranchOnSOS2 |
= CPX_TYPE_SOS2
|
| BranchOnAny |
= CPX_TYPE_ANY
|
| UserBranch |
The enumeration IloCplex::GoalI::IntegerFeasibility
is an enumeration limited in scope to the class
IloCplex::GoalI.
This enumeration is used by
IloCplex::GoalI::getFeasibility to access the integer
feasibility of a variable or SOS in the current node solution:
Feasible specifies the variable or SOS is integer
feasible.ImpliedFeasible specifies the variable or SOS has
been presolved out. It will be feasible when all other integer variables
or SOS are integer feasible.Infeasible specifies the variable or SOS is
integer infeasible.See Also:
IloCplex, GoalI::IntegerFeasibilityArray, ControlCallbackI::IntegerFeasibility
| Fields |
|---|
| ImpliedInfeasible | |
| Feasible |
= CPX_INTEGER_FEASIBLE
|
| Infeasible |
= CPX_INTEGER_INFEASIBLE
|
| ImpliedFeasible |
= CPX_IMPLIED_INTEGER_FEASIBLE
|
| Inner Typedef Detail |
|---|
IloArray< IntegerFeasibility > IntegerFeasibilityArray
This type defines an array type for
IloCplex::GoalI::IntegerFeasibility.
The fully qualified name of an integer feasibility array is
IloCplex::GoalI::IntegerFeasibilityArray.
See Also: