Class AcceptanceBandSampling<T extends Copyable<T>>
 java.lang.Object

 org.cicirello.search.ss.AcceptanceBandSampling<T>

 Type Parameters:
T
 The type of object under optimization.
 All Implemented Interfaces:
Splittable<TrackableSearch<T>>
,Metaheuristic<T>
,SimpleMetaheuristic<T>
,TrackableSearch<T>
public final class AcceptanceBandSampling<T extends Copyable<T>> extends Object
The AcceptanceBandSampling class implements a form of stochastic sampling search that uses a constructive heuristic to guide the random decisions. When making a random decision, all options are evaluated with the heuristic. An acceptance band is then defined based upon the option with the highest heuristic evaluation. Specifically, all options with a heuristic evaluation within B% of the highest heuristic evaluation of the available options are considered equivalent. A choice is then made uniformly at random from the set of equivalents.
The search generates N random candidate solutions to the problem, using a problemspecific heuristic for guidance. It evaluates each of the N candidate solutions with respect to the optimization problem's cost function, and returns the best of the N candidate solutions.
Although AcceptanceBandSampling itself is not restricted to permutation problems, the examples that follow in this documentation focus on permutations for illustrative purposes.
The acceptance bands are defined in terms of a parameter β, which must be in the interval [0.0, 1.0]. Imagine that we have a set of k alternatives, a[0], a[1], ..., a[k], to pick from that have heuristic values: h[0], h[1], ..., h[k]. We assume in this implementation that higher heuristic values imply the options perceived better by the heuristic. We compute: h' = max {h[0], h[1], ..., h[k]}. We define an acceptance threshold: T = (1.0  beta)h'. The set S of equivalent choices is then computed as: S = { a[k]  h[k] ≥ T}. We then choose uniformly at random from the set S.
If beta=1.0, then all alternatives are considered equivalent (we assume heuristic values are nonnegative) since the threshold T would be 0.0 regardless of the heuristic values. If beta=0.0, then only the choices whose heuristic value is equal to the highest heuristic value are considered, since in this case the threshold T is h'. This implementation allows you to specify your choice of beta, and also provides a default of beta=0.1. That default means that all choices within 10% of the option perceived as best by the heuristic are considered equivalent.
To use this implementation of acceptance bands, you will need to implement a constructive heuristic for your problem using the
ConstructiveHeuristic
interface.Assuming that the length of the permutation is L, and that the runtime of the constructive heuristic is O(f(L)), the runtime to construct one permutation using acceptance bands is O(L^{2} f(L)). If the cost, f(L), to heuristically evaluate one permutation element is simply, O(1), constant time, then the cost to heuristically construct one permutation is simply O(L^{2}).
The term "acceptance bands", as we use here, was introduced to describe a stochastic sampling algorithm for finding feasible solutions to a job scheduling problem, as an alternative to systematic backtracking in the following paper:
 Angelo Oddi and Stephen F. Smith. 1997. Stochastic procedures for generating feasible schedules. Proceedings of the 14th National Conference on Artificial Intelligence. AAAI Press, 308–314.
An approach, referred to as "heuristic equivalency", has been used to randomize variableordering/valueordering heuristics within a systematic backtracking search. The randomization technique of heuristic equivalency is the same as that of acceptance bands, but for a different purpose. Heuristic equivalency was used within a backtracking search, while acceptance bands was used to replace backtracking. Heuristic equivalency is described in the following paper:
 Carla P. Gomes, Bart Selman, and Henry Kautz. 1998. Boosting combinatorial search through randomization. Proceedings of the 15th National Conference on Artificial Intelligence. AAAI Press, 431–437.
The implementation of the AcceptanceBandSampling class in our library implements the stochastic sampling version, and does not involve any backtracking.


Constructor Summary
Constructors Constructor Description AcceptanceBandSampling(ConstructiveHeuristic<T> heuristic)
Constructs an AcceptanceBandSampling search object.AcceptanceBandSampling(ConstructiveHeuristic<T> heuristic, double beta)
Constructs an AcceptanceBandSampling search object.AcceptanceBandSampling(ConstructiveHeuristic<T> heuristic, double beta, ProgressTracker<T> tracker)
Constructs an AcceptanceBandSampling search object.AcceptanceBandSampling(ConstructiveHeuristic<T> heuristic, ProgressTracker<T> tracker)
Constructs an AcceptanceBandSampling search object.

Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Problem<T>
getProblem()
Gets a reference to the problem that this search is solving.ProgressTracker<T>
getProgressTracker()
Gets theProgressTracker
object that is in use for tracking search progress.long
getTotalRunLength()
Gets the total run length of the metaheuristic.SolutionCostPair<T>
optimize()
Executes a single run of a metaheuristic whose run length cannot be specified (e.g., a hill climber that terminates when it reaches a local optima, or a stochastic sampler that terminates when it constructs one solution, etc).SolutionCostPair<T>
optimize(int numSamples)
Generates multiple stochastic heuristic samples.void
setProgressTracker(ProgressTracker<T> tracker)
Sets theProgressTracker
object that is in use for tracking search progress.AcceptanceBandSampling<T>
split()
Generates a functionally identical copy of this object, for use in multithreaded implementations of search algorithms.



Constructor Detail

AcceptanceBandSampling
public AcceptanceBandSampling(ConstructiveHeuristic<T> heuristic)
Constructs an AcceptanceBandSampling search object. Uses a default value of beta = 0.1. This default has the effect of considering all heuristic values within 10% of that of the option perceived best by the heuristic to be considered equivalent. A ProgressTracker is created for you. Parameters:
heuristic
 The constructive heuristic. Throws:
NullPointerException
 if heuristic is null

AcceptanceBandSampling
public AcceptanceBandSampling(ConstructiveHeuristic<T> heuristic, ProgressTracker<T> tracker)
Constructs an AcceptanceBandSampling search object. Uses a default value of beta = 0.1. This default has the effect of considering all heuristic values within 10% of that of the option perceived best by the heuristic to be considered equivalent. Parameters:
heuristic
 The constructive heuristic.tracker
 A ProgressTracker Throws:
NullPointerException
 if heuristic or tracker is null

AcceptanceBandSampling
public AcceptanceBandSampling(ConstructiveHeuristic<T> heuristic, double beta)
Constructs an AcceptanceBandSampling search object. A ProgressTracker is created for you. Parameters:
heuristic
 The constructive heuristic.beta
 The acceptance band parameter. When making a decision, if h is the max of the heuristic evaluations of all of the options, then the search will consider all options whose heuristic evaluation is at least h(1.0  beta) as equivalent and choose uniformly at random from among those equivalent options. The value of beta must satisfy: 0.0 ≤ beta ≤ 1.0. If beta is closer to 0.0, then heuristic values must be closer to the heuristic value of the perceived best option to be considered equivalent to it. If beta is 1.0, then all options will be considered equivalent. Throws:
NullPointerException
 if heuristic is nullIllegalArgumentException
 if beta is less than 0.0 or greater than 1.0.

AcceptanceBandSampling
public AcceptanceBandSampling(ConstructiveHeuristic<T> heuristic, double beta, ProgressTracker<T> tracker)
Constructs an AcceptanceBandSampling search object. Parameters:
heuristic
 The constructive heuristic.beta
 The acceptance band parameter. When making a decision, if h is the max of the heuristic evaluations of all of the options, then the search will consider all options whose heuristic evaluation is at least h(1.0  beta) as equivalent and choose uniformly at random from among those equivalent options. The value of beta must satisfy: 0.0 ≤ beta ≤ 1.0. If beta is closer to 0.0, then heuristic values must be closer to the heuristic value of the perceived best option to be considered equivalent to it. If beta is 1.0, then all options will be considered equivalent.tracker
 A ProgressTracker Throws:
NullPointerException
 if heuristic or tracker is nullIllegalArgumentException
 if beta is less than 0.0 or greater than 1.0.


Method Detail

split
public AcceptanceBandSampling<T> split()
Description copied from interface:Splittable
Generates a functionally identical copy of this object, for use in multithreaded implementations of search algorithms. The state of the object that is returned may or may not be identical to that of the original. Thus, this is a distinct concept from the functionality of theCopyable
interface. Classes that implement this interface must ensure that the object returned performs the same functionality, and that it does not share any state data that would be either unsafe or inefficient for concurrent access by multiple threads. The split method is allowed to simply return the this reference, provided that it is both safe and efficient for multiple threads to share a single copy of the Splittable object. The intention is to provide a multithreaded search with the capability to provide spawned threads with their own distinct search operators. Such multithreaded algorithms can call the split method for each thread it spawns to generate a functionally identical copy of the operator, but with independent state. Specified by:
split
in interfaceMetaheuristic<T extends Copyable<T>>
 Specified by:
split
in interfaceSimpleMetaheuristic<T extends Copyable<T>>
 Specified by:
split
in interfaceSplittable<T extends Copyable<T>>
 Returns:
 A functionally identical copy of the object, or a reference to this if it is both safe and efficient for multiple threads to share a single instance of this Splittable object.

optimize
public final SolutionCostPair<T> optimize()
Description copied from interface:SimpleMetaheuristic
Executes a single run of a metaheuristic whose run length cannot be specified (e.g., a hill climber that terminates when it reaches a local optima, or a stochastic sampler that terminates when it constructs one solution, etc). If this method is called multiple times, each call is randomized in some algorithm dependent way (e.g., a hill climber begins at a new randomly generated starting solution), and reinitializes any control parameters that may have changed during the previous call to optimize to the start of run state.
 Specified by:
optimize
in interfaceSimpleMetaheuristic<T extends Copyable<T>>
 Returns:
 The current solution at the end of this run and its cost,
which may or may not be the same as the solution contained
in this metaheuristic's
ProgressTracker
, which contains the best of all runs. Returns null if the run did not execute, such as if the ProgressTracker already contains the theoretical best solution.

optimize
public final SolutionCostPair<T> optimize(int numSamples)
Generates multiple stochastic heuristic samples. Returns the best solution of the set of samples.
 Specified by:
optimize
in interfaceMetaheuristic<T extends Copyable<T>>
 Parameters:
numSamples
 The number of samples to perform. Returns:
 The best solution of this set of samples, which may or may not be the
same as the solution contained
in this search's
ProgressTracker
, which contains the best of all runs across all calls to the various optimize methods. Returns null if no runs executed, such as if the ProgressTracker already contains the theoretical best solution.

getProgressTracker
public final ProgressTracker<T> getProgressTracker()
Description copied from interface:TrackableSearch
Gets theProgressTracker
object that is in use for tracking search progress. The object returned by this method contains the best solution found during the search (including across multiple concurrent runs if the search is multithreaded, or across multiple restarts if the run methods were called multiple times), as well as cost of that solution, among other information. See theProgressTracker
documentation for more information about the search data tracked by this object. Specified by:
getProgressTracker
in interfaceTrackableSearch<T extends Copyable<T>>
 Returns:
 the
ProgressTracker
in use by this metaheuristic.

setProgressTracker
public final void setProgressTracker(ProgressTracker<T> tracker)
Description copied from interface:TrackableSearch
Sets theProgressTracker
object that is in use for tracking search progress. Any previously set ProgressTracker is replaced by this one. Specified by:
setProgressTracker
in interfaceTrackableSearch<T extends Copyable<T>>
 Parameters:
tracker
 The new ProgressTracker to set. The tracker must not be null. This method does nothing if tracker is null.

getTotalRunLength
public final long getTotalRunLength()
Description copied from interface:TrackableSearch
Gets the total run length of the metaheuristic. This is the total run length across all calls to the search. This may differ from what may be expected based on run lengths. For example, the search terminates if it finds the theoretical best solution, and also immediately returns if a prior call found the theoretical best. In such cases, the total run length may be less than the requested run length.
The meaning of run length may vary from one metaheuristic to another. Therefore, implementing classes should provide fresh documentation rather than relying entirely on the interface documentation.
 Specified by:
getTotalRunLength
in interfaceTrackableSearch<T extends Copyable<T>>
 Returns:
 the total run length of the metaheuristic

getProblem
public final Problem<T> getProblem()
Description copied from interface:TrackableSearch
Gets a reference to the problem that this search is solving. Specified by:
getProblem
in interfaceTrackableSearch<T extends Copyable<T>>
 Returns:
 a reference to the problem.

