dwave.samplers.TabuSampler.sample

TabuSampler.sample(bqm: BinaryQuadraticModel, initial_states: Sequence[float | floating | integer] | Mapping[Hashable, float | floating | integer] | tuple[Sequence[float | floating | integer], Sequence[Hashable]] | tuple[ndarray, Sequence[Hashable]] | ndarray | Sequence[Sequence[float | floating | integer]] | tuple[Sequence[Sequence[float | floating | integer]], Sequence[Hashable]] | Sequence[Sequence[float | floating | integer] | Mapping[Hashable, float | floating | integer] | tuple[Sequence[float | floating | integer], Sequence[Hashable]] | tuple[ndarray, Sequence[Hashable]] | ndarray] | Iterator[Sequence[float | floating | integer] | Mapping[Hashable, float | floating | integer] | tuple[Sequence[float | floating | integer], Sequence[Hashable]] | tuple[ndarray, Sequence[Hashable]] | ndarray] | None = None, initial_states_generator: Literal['none', 'tile', 'random'] = 'random', num_reads: int | None = None, seed: int | None = None, tenure: int | None = None, timeout: int = 20, num_restarts: int = 1000000, energy_threshold: float | None = None, coefficient_z_first: int | None = None, coefficient_z_restart: int | None = None, lower_bound_z: int | None = None, **kwargs) → SampleSet

Run a multistart tabu search on a given binary quadratic model.

Parameters:

• bqm – Binary quadratic model (BQM) to be sampled.

• initial_states – One or more samples, each defining an initial state for all the problem variables. Initial states are given one per read, but if fewer than num_reads initial states are defined, additional values are generated as specified by initial_states_generator.

• initial_states_generator –

  Defines the expansion of initial_states if fewer than num_reads are specified:

  • ”none”:

    If the number of initial states specified is smaller than num_reads, raises ValueError.

  • ”tile”:

    Reuses the specified initial states if fewer than num_reads or truncates if greater.

  • ”random”:

    Expands the specified initial states with randomly generated states if fewer than num_reads or truncates if greater.

• num_reads – Number of reads. Each read is generated by one run of the tabu algorithm. If num_reads is not explicitly given, it is selected to match the number of initial states given. If initial states are not provided, only one read is performed.

• seed – 32-bit unsigned integer seed to use for the PRNG. If the timeout parameter is not None, results from the same seed may not be identical between runs due to finite clock resolution.

• tenure – Tabu tenure, which is the length of the tabu list, or number of recently explored solutions kept in memory. Default is a quarter of the number of problem variables up to a maximum value of 20.

• timeout – Maximum running time per read in milliseconds.

• num_restarts – Maximum number of tabu search restarts per read. Setting this value to zero results in a simple tabu search.

• energy_threshold – Terminate when an energy lower than or equal to energy_threshold is found.

• coefficient_z_first – max(bqm.num_variables*coefficient_z_first, lower_bound_z) bounds the number of variable updates considered in the first simple tabu search (STS). Variable updates arising from the STS greedy-descent subroutine, invoked upon discovery of new global optima, are excluded from the count. The coefficient defaults to 10000 for small problems (up to 500 variables) and 25000 for larger problems.

• coefficient_z_restart – Controls the number of variable updates on restarted simple tabu search stages, matching the description for coefficient_z_first. The coefficient defaults to coefficient_z_first/4

• lower_bound_z – Sets a minimum number of variable updates on all simple tabu searches, see coefficient_z_first. The bound defaults to 500000.

Examples

This example samples a simple two-variable Ising model.

>>> import dimod
>>> bqm = dimod.BQM.from_ising({'a': -1}, {'ab': 1})

>>> from dwave.samplers import TabuSampler
>>> sampler = TabuSampler()

>>> sampleset = sampler.sample(bqm, num_restarts=0)
>>> print(sampleset)
   a  b energy num_oc. num_re.
0 +1 -1   -2.0       1       0
['SPIN', 1 rows, 1 samples, 2 variables]