
bb_min(+Goal, ?Cost, ?Options)

   Find a minimal solution using the branch-and-bound method

Arguments
   Goal                The (nondeterministic) search goal
   Cost                A (usually numeric domain) variable representing the cost
   Options             A bb_options structure or variable

Type
   library(branch_and_bound)

Description
	A solution of the goal Goal is found that minimizes
	the value of Cost.  Cost should be a
	variable that is affected, and eventually instantiated, by
	Goal.  Usually, Goal is the search procedure
	of a constraint problem and Cost is the variable
	representing the cost.  The solution is found using the branch
	and bound method:  as soon as a solution is found, it gets
	remembered and the search is continued or restarted with an
	additional constraint on the Cost variable which
	requires the next solution to be better than the previous one. 
	Iterating this process yields an optimal solution in the end.
	
	The possible options are
	
	strategy:
	    
	    continue (default)
	    	after finding a solution, continue search with the newly
		found bound imposed on Cost
	    restart
	    	after finding a solution, restart the whole search with
		the newly found bound imposed on Cost
	    step
	    	a synonym for 'restart'
	    dichotomic
	    	after finding a solution, split the remaining cost range
		and restart search to find a solution in the lower sub-range.
		If that fails, assume the upper sub-range as the remaining
		cost range and split again.
	    
	    The new bound or the split point, respectively, are computed
	    from the current best solution, while taking into account the
	    parameters delta and factor.
	    
	from:
	    number - an initial lower bound for the cost (default -1.0Inf)

	to:
	    number - an initial upper bound for the cost (default +1.0Inf)

	delta:	
	    number - minimal absolute improvement required for each step
	    (default 1.0), applies to all strategies

	factor:
	    number - minimal improvement ratio (with respect to the lower
	    cost bound) for strategies 'continue' and 'restart' (default 1.0),
	    or split factor for strategy 'dichotomic' (default 0.5)

	timeout:
	    number - maximum seconds of cpu time to spend (default: no limit)

	report_success:
	    GoalPrefix - an atom (predicate name) or structure (goal prefix),
	    specifying a goal to be invoked whenever the branch-and-bound
	    process finds a better solution.  The invoked goal is constructed
	    by adding three arguments (Cost, Handle, Module) to GoalPrefix.
	    Cost is a float number representing the cost of the solution found,
	    Handle is a handle as accepted by bb_cost/2 or bb_solution/2,
	    and Module is the context module of the minimisation.
	    The default handler prints a message.

	report_failure:
	    GoalPrefix - an atom (predicate name) or structure (goal prefix),
	    specifying a goal to be invoked whenever the branch-and-bound
	    process cannot find a solution in a cost range.  The invoked goal
	    is constructed by adding three arguments (Cost, Handle, Module) to
	    GoalPrefix.  Cost is a From..To structure representing the range
	    of cost in which no solution could be found, Handle is a handle
	    as accepted by bb_cost/2 or bb_solution/2, and Module is the
	    context module of the minimisation.
	    The default handler prints a message.
	
	The default options can be selected by passing a free variable as
	the Options-argument. To specify other options, pass a bb_options-
	structure in struct-syntax, e.g.
	
	bb_options{strategy:dichotomic, timeout:60}
	
	In order to maximize instead of minimizing, introduce a negated
	cost variable in your model and minimize that instead.
	
	Compatibility note: For backward compatibility, the report_success and
	report_failure options also accept Name/Arity specifications with
	maximum arity 3 for the handler goals. The three optional arguments
	are then Cost, Handle, and Module.
	

Modules
   This predicate is sensitive to its module context (tool predicate, see @/2).

Examples
   
?- bb_min(member(X,[9,6,8,4,7,2,4,7]), X, O).
Found a solution with cost 9
Found a solution with cost 6
Found a solution with cost 4
Found a solution with cost 2
Found no solution with cost -1.0Inf .. 1
X = 2
O = bb_options(continue, -1.0Inf, 1.0Inf, 1, 1, 0, 0, _, _)
yes.

[eclipse 6]: bb_min(member(X,[9,6,8,4,7,2,4,7]), X, bb_options{delta:4}).
Found a solution with cost 9
Found a solution with cost 4
Found no solution with cost -1.0Inf .. 0
X = 4
yes.

[eclipse 10]: bb_min(member(X,[99,60,80,40,70,30,70]), X,
	bb_options{strategy:dichotomic, from:0}).
Found a solution with cost 99
Found a solution with cost 40
Found no solution with cost 0.0 .. 20.0
Found a solution with cost 30
Found no solution with cost 20.0 .. 25.0
Found no solution with cost 25.0 .. 27.5
Found no solution with cost 27.5 .. 28.75
Found no solution with cost 28.75 .. 29.0

X = 30
yes.


See Also
   bb_min / 6
