Class AcceptanceBandSampling<T extends Copyable<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 problem-specific 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 non-negative) 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(L2 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(L2).

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 variable-ordering/value-ordering 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
Modifier and Type Method Description
`Problem<T>` `getProblem()`
Gets a reference to the problem that this search is solving.
`ProgressTracker<T>` `getProgressTracker()`
Gets the `ProgressTracker` 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 the `ProgressTracker` 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.
• Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
• 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 null
`IllegalArgumentException` - 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 null
`IllegalArgumentException` - 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 the `Copyable` 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 interface `Metaheuristic<T extends Copyable<T>>`
Specified by:
`split` in interface `SimpleMetaheuristic<T extends Copyable<T>>`
Specified by:
`split` in interface `Splittable<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 interface `SimpleMetaheuristic<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 interface `Metaheuristic<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 the `ProgressTracker` 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 the `ProgressTracker` documentation for more information about the search data tracked by this object.
Specified by:
`getProgressTracker` in interface `TrackableSearch<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 the `ProgressTracker` object that is in use for tracking search progress. Any previously set ProgressTracker is replaced by this one.
Specified by:
`setProgressTracker` in interface `TrackableSearch<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 interface `TrackableSearch<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 interface `TrackableSearch<T extends Copyable<T>>`
Returns:
a reference to the problem.