dimod samplers sample from a problem’s objective function, such as a BQM, and return an iterable of samples contained in a SampleSet class. In addition to containing the returned solutions and some additional information, and providing methods to work with the solutions, SampleSet is also used, for example, by dwave-hybrid, which iterates sets of samples through samplers to solve arbitrary QUBOs. dimod provides functionality for creating and manipulating samples.

sample_like Objects

as_samples(samples_like[, dtype, copy, order]) Convert a samples_like object to a NumPy array and list of labels.


class SampleSet(record, variables, info, vartype)[source]

Samples and any other data returned by dimod samplers.

  • record (numpy.recarray) – A NumPy record array. Must have ‘sample’, ‘energy’ and ‘num_occurrences’ as fields. The ‘sample’ field should be a 2D NumPy array where each row is a sample and each column represents the value of a variable.
  • variables (iterable) – An iterable of variable labels, corresponding to columns in record.samples.
  • info (dict) – Information about the SampleSet as a whole, formatted as a dict.
  • vartype (Vartype/str/set) –

    Variable type for the SampleSet. Accepted input values:

    • Vartype.SPIN, 'SPIN', {-1, 1}
    • Vartype.BINARY, 'BINARY', {0, 1}


This example creates a SampleSet out of a samples_like object (a NumPy array).

>>> import dimod
>>> import numpy as np
>>> dimod.SampleSet.from_samples(np.ones(5, dtype='int8'), 'BINARY', 0)   # doctest: +SKIP
SampleSet(rec.array([([1, 1, 1, 1, 1], 0, 1)],
...       dtype=[('sample', 'i1', (5,)), ('energy', '<i4'), ('num_occurrences', '<i4')]),
...       [0, 1, 2, 3, 4], {}, 'BINARY')


SampleSet.first Sample with the lowest-energy. Dict of information about the SampleSet as a whole.
SampleSet.record numpy.recarray containing the samples, energies, number of occurences, and other sample data.
SampleSet.variables VariableIndexView of variable labels.
SampleSet.vartype Vartype of the samples.


SampleSet.aggregate() Create a new SampleSet with repeated samples aggregated.
SampleSet.append_variables(samples_like[, …]) Create a new sampleset with the given variables and values.
SampleSet.change_vartype(vartype[, …]) Return the SampleSet with the given vartype.
SampleSet.copy() Create a shallow copy.[fields, sorted_by, name, …]) Iterate over the data in the SampleSet.
SampleSet.done() Return True if a pending computation is done.
SampleSet.from_future(future[, result_hook]) Construct a SampleSet referencing the result of a future computation.
SampleSet.from_samples(samples_like, …[, …]) Build a SampleSet from raw samples.
SampleSet.from_samples_bqm(samples_like, …) Build a sample set from raw samples and a binary quadratic model.
SampleSet.from_serializable(obj) Deserialize a SampleSet.
SampleSet.lowest([rtol, atol]) Return a sample set containing the lowest-energy samples.
SampleSet.resolve() Ensure that the sampleset is resolved if constructed from a future.
SampleSet.relabel_variables(mapping[, inplace]) Relabel the variables of a SampleSet according to the specified mapping.
SampleSet.samples([n, sorted_by]) Return an iterable over the samples.
SampleSet.slice(*slice_args, **kwargs) Create a new sample set with rows sliced according to standard Python slicing syntax.
SampleSet.to_pandas_dataframe([sample_column]) Convert a sample set to a Pandas DataFrame
SampleSet.to_serializable([use_bytes, …]) Convert a SampleSet to a serializable object.
SampleSet.truncate(n[, sorted_by]) Create a new sample set with up to n rows.

Utility Functions

concatenate(samplesets[, defaults]) Combine sample sets.