Add RandomSampler

.gitignore

@@ -111,6 +111,8 @@ venv.bak/
 # cython files
 dwave/samplers/greedy/*.cpp
 dwave/samplers/greedy/*.html
+dwave/samplers/random/*.cpp
+dwave/samplers/random/*.html
 dwave/samplers/sa/*.cpp
 dwave/samplers/sa/*.html
 dwave/samplers/tabu/*.cpp

README.rst

@@ -24,13 +24,32 @@ or locally on your CPU.
 *dwave-samplers* implements the following classical algorithms for solving
 :term:`binary quadratic model`\ s (BQM):
 
+* Random: a sampler that draws uniform random samples.
 * `Simulated Annealing`_: a probabilistic heuristic for optimization and approximate
   Boltzmann sampling well suited to finding good solutions of large problems.
 * `Steepest Descent`_: a discrete analogue of gradient descent, often used in
   machine learning, that quickly finds a local minimum.
 * `Tabu`_: a heuristic that employs local search with methods to escape local minima.
 * `Tree Decomposition`_: an exact solver for problems with low treewidth.
 
+Random
+======
+
+Random samplers provide a useful baseline performance comparison. The variable
+assignments in each sample are chosen by a coin flip.
+
+>>> from dwave.samplers import RandomSampler
+>>> sampler = RandomSampler()
+
+Create a random binary quadratic model.
+
+>>> import dimod
+>>> bqm = dimod.generators.gnp_random_bqm(100, .5, 'BINARY')
+
+Get the 20 best random samples found in .2 seconds of searching.
+
+>>> sampleset = sampler.sample(bqm, num_reads=20, time_limit=.2)
+
 Simulated Annealing
 ===================
 

docs/reference.rst

@@ -4,6 +4,34 @@ Reference Documentation
 
 .. currentmodule:: dwave.samplers
 
+Random
+=======
+
+RandomSampler
+-------------
+
+.. autoclass:: RandomSampler
+
+Attributes
+~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~RandomSampler.parameters
+   ~RandomSampler.properties
+
+Methods
+~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~RandomSampler.sample
+   ~RandomSampler.sample_ising
+   ~RandomSampler.sample_qubo
+
+
 Simulated Annealing
 ===================
 

dwave/samplers/__init__.py

@@ -16,6 +16,8 @@
 
 from dwave.samplers.greedy import *
 
+from dwave.samplers.random import *
+
 from dwave.samplers.sa import *
 
 from dwave.samplers.tabu import *

dwave/samplers/random/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2022 D-Wave Systems Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+from dwave.samplers.random.sampler import *

dwave/samplers/random/cyrandom.pyx

@@ -0,0 +1,174 @@
+# distutils: language = c++
+# cython: language_level = 3
+
+# Copyright 2022 D-Wave Systems Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+cimport cython
+
+from cpython.pycapsule cimport PyCapsule_IsValid, PyCapsule_GetPointer
+from libc.time cimport time, time_t
+from libcpp.algorithm cimport sort
+from libcpp.vector cimport vector
+from posix.time cimport clock_gettime, timespec, CLOCK_REALTIME
+
+import dimod
+cimport dimod
+import numpy as np
+cimport numpy as np
+cimport numpy.random
+
+cdef extern from *:
+    """
+    #if defined(_WIN32) || defined(_WIN64)
+
+    #include <Windows.h>
+
+    double realtime_clock() {
+        LARGE_INTEGER frequency;
+        LARGE_INTEGER now;
+
+        QueryPerformanceFrequency(&frequency);
+        QueryPerformanceCounter(&now);
+
+        return now.QuadPart / frequency.QuadPart;
+    }
+
+    #else
+
+    double realtime_clock() {
+        struct timespec ts;
+        clock_gettime(CLOCK_MONOTONIC, &ts);
+        return ts.tv_sec + ts.tv_nsec / 1e9;
+    }
+
+    #endif
+    """
+    double realtime_clock()
+
+
+cdef struct state_t:
+    np.float64_t energy
+    vector[np.int8_t] sample
+
+
+cdef bint comp_state(const state_t& a, const state_t& b) nogil:
+    return a.energy < b.energy
+
+
+cdef state_t get_sample(dimod.cyBQM_float64 cybqm,
+                        numpy.random.bitgen_t* bitgen,
+                        bint is_spin = False,
+                        ):
+    # developer note: there is a bunch of potential optimization here
+    cdef state_t state
+
+    # generate the sample
+    state.sample.reserve(cybqm.num_variables())
+    cdef Py_ssize_t i
+    for i in range(cybqm.num_variables()):
+        state.sample.push_back(bitgen.next_uint32(bitgen.state) % 2)
+
+    if is_spin:
+        # go back through and convert to spin
+        for i in range(state.sample.size()):
+            state.sample[i] = 2 * state.sample[i] - 1
+
+    state.energy = cybqm.data().energy(state.sample.begin())
+
+    return state
+
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def sample(bqm, Py_ssize_t num_reads, object seed, np.float64_t time_limit):
+
+    cdef double preprocessing_start_time = realtime_clock()
+
+    cdef Py_ssize_t i, j  # counters for use later
+
+    # Get Cython access to the BQM. We could template to avoid the copy,
+    # but honestly everyone just uses float64 anyway so...
+    cdef dimod.cyBQM_float64 cybqm = dimod.as_bqm(bqm, dtype=float).data
+    cdef bint is_spin = bqm.vartype is dimod.SPIN
+
+    # Get Cython access to the rng
+    rng = np.random.default_rng(seed)
+    cdef numpy.random.bitgen_t *bitgen
+    cdef const char *capsule_name = "BitGenerator"
+    capsule = rng.bit_generator.capsule
+    if not PyCapsule_IsValid(capsule, capsule_name):
+        raise ValueError("Invalid pointer to anon_func_state")
+    bitgen = <numpy.random.bitgen_t *> PyCapsule_GetPointer(capsule, capsule_name)
+
+    cdef double sampling_start_time = realtime_clock()
+
+    cdef double sampling_stop_time
+    if time_limit < 0:
+        sampling_stop_time = float('inf')
+    else:
+        sampling_stop_time = sampling_start_time + time_limit
+
+    # try sampling
+    cdef Py_ssize_t num_drawn = 0
+    cdef vector[state_t] samples
+    for i in range(num_reads):
+        samples.push_back(get_sample(cybqm, bitgen, is_spin))
+        num_drawn += 1
+
+        if realtime_clock() > sampling_stop_time:
+            break
+
+    if time_limit >= 0:
+        while realtime_clock() < sampling_stop_time:
+
+            samples.push_back(get_sample(cybqm, bitgen, is_spin))
+            sort(samples.begin(), samples.end(), comp_state)
+            samples.pop_back()
+
+            num_drawn += 1
+
+    cdef double postprocessing_start_time = realtime_clock()
+
+    if time_limit < 0:
+         # for consistency we sort in this case as well, though we count
+         # it towards postprocessing since it's not necessary
+        sort(samples.begin(), samples.end(), comp_state)
+
+    record = np.rec.array(np.empty(num_reads,
+                      dtype=[('sample', np.int8, (cybqm.num_variables(),)),
+                             ('energy', float),
+                             ('num_occurrences', int)]))
+
+    record['num_occurrences'][:] = 1
+
+    cdef np.float64_t[:] energies_view = record['energy']
+    for i in range(num_reads):
+        energies_view[i] = samples[i].energy
+
+    cdef np.int8_t[:, :] sample_view = record['sample']
+    for i in range(num_reads):
+        for j in range(cybqm.num_variables()):
+            sample_view[i, j] = samples[i].sample[j]
+
+    sampleset = dimod.SampleSet(record, bqm.variables, info=dict(), vartype=bqm.vartype)
+
+    sampleset.info.update(
+        num_drawn=num_drawn,
+        prepreocessing_time=sampling_start_time-preprocessing_start_time,
+        sampling_time=postprocessing_start_time-sampling_start_time,
+        postprocessing_time=realtime_clock()-preprocessing_start_time,
+        )
+
+    return sampleset

dwave/samplers/random/sampler.py

@@ -0,0 +1,122 @@
+# Copyright 2022 D-Wave Systems Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+import typing
+
+import dimod
+import numpy as np
+
+from dwave.samplers.random.cyrandom import sample
+
+
+__all__ = ['RandomSampler']
+
+
+class RandomSampler(dimod.Sampler):
+    """A random sampler, useful as a performance baseline and for testing.
+
+    Examples:
+
+        >>> from dwave.samplers import RandomSampler
+        >>> sampler = RandomSampler()
+
+        Create a random binary quadratic model.
+
+        >>> import dimod
+        >>> bqm = dimod.generators.gnp_random_bqm(100, .5, 'BINARY')
+
+        Get the 20 best random samples found in .2 seconds of searching.
+
+        >>> sampleset = sampler.sample(bqm, num_reads=20, time_limit=.2)
+
+    """
+
+    parameters: typing.Mapping[str, typing.List] = dict(
+        num_reads=[],
+        seed=[],
+        time_limit=[],
+        )
+    """Keyword arguments accepted by the sampling methods.
+
+    Examples:
+
+        >>> from dwave.samplers import RandomSampler
+        >>> sampler = RandomSampler()
+        >>> sampler.parameters
+        {'num_reads': [], 'seed': [], 'time_limit': []}
+
+    """
+
+    properties: typing.Mapping[str, typing.Any] = dict(
+        )
+    """Information about the solver. Empty.
+
+    Examples:
+
+        >>> from dwave.samplers import RandomSampler
+        >>> sampler = RandomSampler()
+        >>> sampler.properties
+        {}
+
+    """
+
+    def sample(self,
+               bqm: dimod.BinaryQuadraticModel,
+               *,
+               num_reads: int = 10,
+               seed: typing.Union[None, int, np.random.Generator] = None,
+               time_limit: typing.Optional[float] = None,
+               **kwargs,
+               ) -> dimod.SampleSet:
+        """Return random samples for a binary quadratic model.
+
+        Args:
+            bqm: Binary quadratic model to be sampled from.
+
+            num_reads: The number of samples to be returned.
+
+            seed:
+                Seed for the random number generator.
+                Passed to :func:`numpy.random.default_rng()`.
+
+            time_limit:
+                The maximum sampling time in seconds.
+                If given and non-negative, samples are drawn until ``time_limit``.
+                Only the best ``num_reads`` (or fewer) samples are kept.
+
+        Returns:
+            A sample set.
+            Some additional information is provided in the
+            :attr:`~dimod.SampleSet.info` dictionary:
+
+                * **num_drawn**: The total number of samples generated.
+                * **prepreocessing_time**: The time to parse the ``bqm`` and to
+                  initialize the random number generator.
+                * **sampling_time**: The time used to generate the samples
+                  and calculate the energies. This is the number controlled by
+                  ``time_limit``.
+                * **postprocessing_time**: The time to construct the sample
+                  set.
+
+        """
+
+        # we could count this towards preprocesing time but IMO it's fine to
+        # skip for simplicity.
+        self.remove_unknown_kwargs(**kwargs)
+
+        return sample(bqm,
+                      num_reads=num_reads,
+                      seed=seed,
+                      time_limit=-1 if time_limit is None else time_limit,
+                      )