
BfsInstance:solver_setup(+OptSense, +Solver, ++ListOfOptions)

   Setup a bfs solver tree for bfs instance BfsInstance.

Arguments
   OptSense            Optimisation direction: min or max
   Solver              Node relaxation solver
   ListOfOptions       List of solver options

Type
   library(bfs)

Description

  Setup a new solver tree for the bfs instance BfsInstance. The tree
  will be associated with BfsInstance; BfsInstance must not already
  have a solver tree associated with it. Once the solver tree is setup,
  it can be optimised via solve/1. This predicate allow various
  options to be specified when setting up the  solver state via
  ListOfOptions.

  OptSense is the optimisation direction. Note that this
  is assumed to be the same as the sense of optimisation used in
  Solver. It is the user's responsibility to ensure 
  that this is in fact the case. OptSense is used internally
  for bound updates and pruning, and for node ordering with the built-in
  best-first and best-estimate node selection methods.

  Solver is the node relaxed problem solver. It is either a
  user-defined predicate or an eplex instance or handle, for which a
  built-in node relaxation solver is available.


ListOfOptions are:




separation(+Separation)
    Use the specified method to separate the current node.
    Separation is either a user-defined predicate, or one of
    the atoms fracvar, enhanced, strong, deg_est
    corresponding to the built-in separation methods. Note that the
    methods enhanced, strong, deg_est are only available when
    the node relaxation solver involves an eplex instance.
    Separation defaults to fracvar.


node_select(+Select)
    Use the specified method (depth_first, best_first,
    best_estimate) to select the next open node for solution and
    separation. Select defaults to best_first.


alpha(?AlphaMin, ?AlphaMax)
    When using estimate- or lower-bounding based dichotomic node
    separation methods the overall value assigned to branching on a
    particular variable or constraint is calculated as a weighted sum
    of the estimates obtained for the two branches it would produce.
    AlphaMin is the weighting given to the minimum of the two estimates
    and AlphaMax to the maximum. AlphaMin and AlphaMax
    are numbers and default to 2 and 1 respectively.


beta(?BetaConst, ?BetaPC, ?BetaLB)
    When using estimate- or lower-bounding based node separation
    methods with a problem involving an eplex instance the estimate
    assigned to each branch produced by branching on a particular
    variable or constraint is calculated as a weighted sum  of the
    pseudo-cost estimate and the lower bound. BetaPC is the weighting
    given to the pseudo-cost estimate and BetaLB to the lower bound.
    BetaConst is a constant offset only used when linear regression is
    employed to update these values during search. BetaConst,
    BetaPC, BetaLB are numbers and default to 0, 1,
    1 respectively.


pseudo_cost(?PCInit, ?PCUpdate, ?PCRatio)
    
    When using estimate-based dichotomic node separation methods
    with a problem involving an eplex instance up and down pseudo-costs
    are assigned to each variable and generalised upper bound constraint 
    branch-point representing the estimated degradation in objective
    cost per unit change in variable or constraint value incurred on
    that branch.
    PCInit specifies the method used to initialise these
    values when a variable or constraint branch-point is first considered
    for branching:
    
    average : the pseudocosts are initialised to the average
    of the observed changes in cost of all up or down branches in the
    search tree.
    cost : variable pseudocosts are initialised to the
    objective cost coefficient of the variable, constraint branch-point
    pseudocosts to the average of the cost coefficients of variables
    involved.
    calculated : the pseudocosts are initialised to a
    value calculated by performing a number of external solver iterations
    equal to (PCRatio * #iterations in root node)/(2* #fractional
    vars in root node).
    
    The default is calculated.
    PCUpdate is an atom specifying the method used to
    update these values throughout the search tree once the variable
    or constraint has been branched on:
    
    average : the pseudocosts are updated to the average
    of the observed changes in cost of all up or down branches in the
    search tree for that variable or constraint. 
    first : the pseudocosts are fixed to the observed
    change in cost at the first up or down branch in the search tree for
    that variable or constraint.
    last : the pseudocosts are fixed to the observed
    change in cost at the last up or down branch in the search tree for
    that variable or constraint.
    
    The default is average.
    PCRatio is a float between 0 and 1 and is used in
    calculating the number of external solver iterations to perform
    when explicitly calculating initial pseudo-cost estimates; the
    default value is 0.05. Setting small ratios will result in faster
    node separation, but the initial estimates for variables and
    constraints on which the branching decisions are taken will be less
    accurate. Setting larger values will result in more work being performed
    in node separation and better estimates for the branching
    decisions. The optimum value will be problem specific, although in 
    general the overhead of performing a total number of iterations
    more than a small ratio of the root node iterations will outweigh the
    benefit obtained.


lower_bound(+Limit)
    When using lower-bounding based node separation methods with a
    problem involving an eplex instance, specify how many external solver
    iterations should be performed to calculate the lower bound.
    Limit is an integer and defaults to 1. Setting small
    values of iterations will result in faster node separation, but the
    lower bounds on which the branching decisions are taken will be less
    tight. Setting larger values will result in more work being performed
    in node separation and tighter lower bounds for the branching
    decisions. The optimum value will be problem specific, although in
    general the overhead of performing more than a few iterations will
    outweigh the benefit obtained.


int_tolerance(+IntTol)
    Specify how far from integrality an integer variable's node
    solution can fall before it is considered for separation by the
    built-in separation methods. IntTol is a float and
    defaults to 0.00001.  

info_messages(+OnOff)
    Specify whether information messages should be output at
    various points during solution. This option is most useful for
    debugging purposes. OnOff is one of the atoms on or
    off, the default is off.




See Also
   integers / 1, bfs_branch / 1, node_info / 5, solver_setup / 2, solve / 1, get / 2, var_get / 3, statistics / 0
