lib(branch_and_bound)


    This is a solver-independent library implementing branch-and-bound
    optimization. It can be used with any nondeterministic search routine
    that instantiates a cost variable when a solution is found. The cost
    variable can be an arbitrary numerical domain variable or even a
    simple domain-less Prolog variable.

    The main primitive is bb_min/3.  Assume we have the following
    collection of facts:

        % item(Food, Calories, Price)
        item(bread,  500, 1.50).
        item(eggs,   600, 1.99).
        item(milk,   400, 0.99).
        item(apples, 200, 1.39).
        item(butter, 800, 1.89).

   Then we can find a minimum-calorie solution as follows:

        ?- bb_min(item(Food,Cal,Price), Cal, _).
        Found a solution with cost 500
        Found a solution with cost 400
        Found a solution with cost 200
        Found no solution with cost -1.0Inf .. 199

        Food = apples
        Cal = 200
        Price = 1.39
        Yes (0.00s cpu)

    In this example, the item/3 predicate serves as a nondeterministic
    generator of solutions with different values for the variable Cal,
    which we have chosen as our cost variable.  As can be seen from the
    progress messages, the optimization procedure registers increasingly
    good solutions (i.e. solutions with smaller cost), and finally delivers
    the minimum-cost solution with Cal=200.

    Alternatively, we can minimize the item price:

        ?- bb_min(item(Food,Cal,Price), Price, bb_options{delta:0.05}).
        Found a solution with cost 1.5
        Found a solution with cost 0.99
        Found no solution with cost -1.0Inf .. 0.94

        Food = milk
        Cal = 400
        Price = 0.99
        Yes (0.00s cpu)

    Because the price is non-integral, we had to adjust the step-width
    of the optimization procedure using the delta-option.

Optimization with Constraints

    This library is designed to work together with arbitrary constraint
    solvers, for instance library(ic).  The principle there is to wrap
    the solver's nondeterministic search procedure into a bb_min/3 call.
    This turns a program that finds all solutions into one that finds
    the best solution.  For example:

        ?- [X,Y,Z] #:: 1..5,                   % constraints (model)
           X+Z #>= Y,

           C #= 3*X - 5*Y + 7*Z,               % objective function

           bb_min(labeling([X,Y,Z]), C, _).    % nondet search + b&b

        Found a solution with cost 5
        Found a solution with cost 0
        Found a solution with cost -2
        Found a solution with cost -4
        Found a solution with cost -6
        Found no solution with cost -15.0 .. -7.0
        X = 4
        Y = 5
        Z = 1
        C = -6
        Yes (0.00s cpu)

    The code shows the general template for such an optimization solver:
    All constraints should be set up BEFORE the call to bb_min/3,
    while the nondeterministic search procedure (here labeling/1)
    must be invoked WITHIN bb_min/3.  The branch-and-bound procedure
    only works if it envelops all nondeterminism.

    The cost variable (here C) must be defined in such a way that it is
    instantiated (possibly by propagation) whenever the search procedure
    succeeds with a solution.  Moreover, good, early bounds on the cost
    variable are important for efficiency, as they help the branch-and-bound
    procedure to prune the search.  Redundant constraints on the cost
    variable can sometimes help.


Note on the treatment of bounded reals

    The library allows the cost to be instantiated to a number of type
    breal.  This is useful e.g. when using lib(ic) to solve problems
    with continuous variables.  When the variable domains have been
    narrowed sufficiently, the problem variables (in particular the
    cost variable) should be instantiated to a bounded real, e.g.
    using the following idiom:
    
	    X is breal_from_bounds(get_min(X),get_max(X))
    
    Bounded reals contain some uncertainty about their true value. If
    this uncertainty is too large, the branch-and-bound procedure may
    not be able to compare the quality of two solutions. In this case,
    a warning is issued and the search terminated prematurely.  The
    problem can be solved by increasing the delta-parameter, or by
    locating the cost value more precisely.


