neal.sampler.SimulatedAnnealingSampler.sample

SimulatedAnnealingSampler.sample(bqm, beta_range=None, num_reads=None, num_sweeps=1000, beta_schedule_type='geometric', seed=None, interrupt_function=None, initial_states=None, initial_states_generator='random', **kwargs)[source]

Sample from a binary quadratic model using an implemented sample method.

Parameters:
  • bqm (dimod.BinaryQuadraticModel) – The binary quadratic model to be sampled.
  • beta_range (tuple, optional) – A 2-tuple defining the beginning and end of the beta schedule, where beta is the inverse temperature. The schedule is applied linearly in beta. Default range is set based on the total bias associated with each node.
  • num_reads (int, optional, default=len(initial_states) or 1) – Number of reads. Each read is generated by one run of the simulated annealing 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.
  • num_sweeps (int, optional, default=1000) – Number of sweeps or steps.
  • beta_schedule_type (string, optional, default='geometric') –

    Beta schedule type, or how the beta values are interpolated between the given ‘beta_range’. Supported values are:

    • linear
    • geometric
  • seed (int, optional) – Seed to use for the PRNG. Specifying a particular seed with a constant set of parameters produces identical results. If not provided, a random seed is chosen.
  • initial_states (dimod.SampleSet or tuple(numpy.ndarray, dict), optional) –

    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 are provided either as:

    • dimod.SampleSet, or
    • [deprecated] tuple, where the first value is a numpy array of initial states to seed the simulated annealing runs, and the second is a dict defining a linear variable labelling. In tuple format, initial states provided are assumed to use the same vartype the BQM is using.
  • initial_states_generator (str, 'none'/'tile'/'random', optional, default='random') –

    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.
  • interrupt_function (function, optional) – If provided, interrupt_function is called with no parameters between each sample of simulated annealing. If the function returns True, then simulated annealing will terminate and return with all of the samples and energies found so far.
Returns:

A dimod Response object.

Return type:

dimod.Response

Examples

This example runs simulated annealing on a binary quadratic model with some different input parameters.

>>> import dimod
>>> import neal
...
>>> sampler = neal.SimulatedAnnealingSampler()
>>> bqm = dimod.BinaryQuadraticModel({'a': .5, 'b': -.5}, {('a', 'b'): -1}, 0.0, dimod.SPIN)
>>> # Run with default parameters
>>> response = sampler.sample(bqm)
>>> # Run with specified parameters
>>> response = sampler.sample(bqm, seed=1234, beta_range=[0.1, 4.2],
...                                num_reads=1, num_sweeps=20,
...                                beta_schedule_type='geometric')
>>> # Reuse a seed
>>> a1 = next((sampler.sample(bqm, seed=88)).samples())['a']
>>> a2 = next((sampler.sample(bqm, seed=88)).samples())['a']
>>> a1 == a2
True