Samplers

A sampler accepts a problem in quadratic model (e.g., BQM, CQM) or nonlinear model format and returns variable assignments. Samplers generally try to find minimizing values but can also sample from distributions defined by the problem.

These samplers are non-blocking: the returned SampleSet is constructed from a Future-like object that is resolved on the first read of any of its properties; for example, by printing the results. Your code can query its status with the done() method or ensure resolution with the resolve() method.

Other Ocean packages provide additional samplers; for example, dimod provides samplers for testing your code.

DWaveSampler

class DWaveSampler(failover=False, retry_interval=-1, **config)

Bases: Sampler, Structured

Submits binary quadratic models directly to D-Wave quantum computers.

Linear and quadratic terms of the binary quadratic model (BQM) must map directly to qubit and coupler indices of the selected QPU. Typically this mapping (minor-embedding) is handled by software (e.g., the EmbeddingComposite class) but for small problems can be manual. You can configure your solver selection and usage by setting parameters, hierarchically, in a configuration file, as environment variables, or explicitly as input arguments. For more information, see the get_solvers() method. By default, online QPUs are returned ordered by highest number of qubits.

Parameters:

• failover (bool, optional, default=False) –

  Signal a failover condition if a sampling error occurs. When True, raises FailoverCondition or RetryCondition on sampleset resolve() to signal failover. Actual failover (i.e., selection of a new solver) has to be handled by the user. A convenience method trigger_failover() is available for this. Note that hardware graphs vary between QPUs, so triggering failover results in regenerated nodelist, edgelist, properties and parameters.

  Changed in version 1.16.0: In the past, the sample() method was blocking and failover=True caused a solver failover and sampling retry. However, this failover implementation broke when sample() became non-blocking (asynchronous), Setting failover=True had no effect.

• retry_interval (number, optional, default=-1) –

  Ignored, but kept for backward compatibility.

  Changed in version 1.16.0: Ignored since 1.16.0. See note for failover parameter above.

• **config – Keyword arguments passed to from_config().

Added in version 1.29.0: Support for context manager protocol.

Note

Prior to version 1.0.0, DWaveSampler used the base client, allowing non-QPU solvers to be selected. To reproduce the old behavior, instantiate DWaveSampler with client='base'.

Note

The recommended way to use DWaveSampler is from a runtime context:

>>> with DWaveSampler() as sampler:
...     sampler.sample_ising(...)       

Alternatively, call the close() method to terminate the sampler resources:

>>> sampler = DWaveSampler()
...
>>> sampler.close()

Examples

This example submits a two-variable Ising problem mapped directly to two adjacent qubits on a QPU. qubit_a is the first qubit in the QPU’s indexed list of qubits and qubit_b is one of the qubits coupled to it. Other required parameters for communication with the system, such as its URL and an authentication token, are implicitly set in a configuration file or as environment variables, as described in the Configuring Access to the Leap Service (Basic) section. Given sufficient reads (here 100), the quantum computer should return the best solution, \({1, -1}\) on qubit_a and qubit_b, respectively, as its first sample (samples are ordered from lowest energy).

>>> from dwave.system import DWaveSampler
...
>>> with DWaveSampler() as sampler:
...     qubit_a = sampler.nodelist[0]
...     qubit_b = next(iter(sampler.adjacency[qubit_a]))
...     sampleset = sampler.sample_ising({qubit_a: -1, qubit_b: 1},
...                                      {},
...                                      num_reads=100)
...     print(sampleset.first.sample[qubit_a] == 1 and sampleset.first.sample[qubit_b] == -1)
True

For additional examples, see:

• Beginner examples of using DWaveSampler.

• Basic QPU Configuration.

Properties

For parameters and properties of D-Wave systems, see the QPU Solver Properties and QPU Solver Parameters sections.

adjacency	Adjacency structure formatted as a dict, where keys are the nodes of the structured sampler and values are sets of all adjacent nodes for each key node.
edgelist	List of active couplers for the solver.
nodelist	List of active qubits for the solver.
parameters	Solver parameters as returned by a SAPI query.
properties	Solver properties as returned by a SAPI query.
structure	Structure of the structured sampler formatted as a namedtuple() where the 3-tuple values are the nodelist, edgelist and adjacency attributes.
warnings_default	Defines default behavior for warnings keyword arguments of the sample_ising() and sample_qubo() methods.

Methods

close()	Close the underlying cloud client to release system resources such as threads.
remove_unknown_kwargs(**kwargs)	Remove with warnings any keyword arguments not accepted by the sampler.
sample(bqm[, warnings])	Sample from the specified binary quadratic model.
sample_ising(h, *args, **kwargs)	Sample from an Ising model using the implemented sample method.
sample_qubo(Q, **parameters)	Sample from a QUBO using the implemented sample method.
to_networkx_graph()	Output the QPU's working graph in NetworkX format.
trigger_failover()	Trigger a failover and connect to a new solver.
valid_bqm_graph(bqm)	Validate that problem defined by dimod.BinaryQuadraticModel matches the graph provided by the sampler.
validate_anneal_schedule(anneal_schedule)	Raise an exception if the specified schedule is invalid for the sampler.

DWaveCliqueSampler

class DWaveCliqueSampler(*, failover: bool = False, retry_interval: Number = -1, **config)

Submits clique binary quadratic models to D-Wave quantum computers.

This sampler wraps find_clique_embedding() to generate an embedding with even chain length. These embeddings work well for a dense binary quadratic model. For sparse models, using EmbeddingComposite with DWaveSampler is preferred.

Configuration such as solver selection is similar to that of DWaveSampler.

Clique embeddings are cached for each QPU but the initial finding of embeddings can take several minutes.

Parameters:

• failover (bool, optional, default=False) –

  Signal a failover condition if a sampling error occurs. When True, raises FailoverCondition or RetryCondition on sampleset resolve() to signal failover. Actual failover (i.e., selection of a new solver) has to be handled by the user. A convenience method trigger_failover() is available for this. Note that hardware graphs vary between QPUs, so triggering failover results in regenerated nodelist, edgelist, properties and parameters.

  Changed in version 1.16.0: In the past, the sample() method was blocking and failover=True caused a solver failover and sampling retry. However, this failover implementation broke when sample() became non-blocking (asynchronous), Setting failover=True had no effect.

• retry_interval (number, optional, default=-1) –

  Ignored, but kept for backward compatibility.

  Changed in version 1.16.0: Ignored since 1.16.0. See note for failover parameter above.

• **config – Keyword arguments, as accepted by DWaveSampler.

Added in version 1.29.0: Support for context manager protocol.

Note

The recommended way to use DWaveCliqueSampler is from a runtime context:

>>> with DWaveCliqueSampler() as sampler:   
...     sampler.sample(...)

Alternatively, call the close() method to terminate the sampler resources:

>>> sampler = DWaveCliqueSampler()      
...
>>> sampler.close()     

Examples

This example creates a BQM based on a 6-node clique (complete graph), with random \(\pm 1\) values assigned to nodes, and submits it to a D-Wave system. Parameters for communication with the system, such as its URL and an authentication token, are implicitly set in a configuration file or as environment variables, as described in the Configuring Access to the Leap Service (Basic) section.

>>> from dwave.system import DWaveCliqueSampler
>>> import dimod
...
>>> bqm = dimod.generators.ran_r(1, 6)
...
>>> with DWaveCliqueSampler() as sampler:   
...     print(sampler.largest_clique_size > 5)
...     sampleset = sampler.sample(bqm, num_reads=100)
True

See also

busgraph_cache.

Properties

largest_clique_size	Maximum number of variables that can be embedded.
parameters	Parameters as a dict, where keys are keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
properties	Properties as a dict containing any additional information about the sampler.
qpu_linear_range	Range of linear biases allowed by the QPU.
qpu_quadratic_range	Range of quadratic biases allowed by the QPU.
target_graph	Selected QPU's working graph in NetworkX format.

Methods

clique(variables)	Return a clique embedding of the given size.
close()	Close the child sampler to release system resources such as threads.
largest_clique()	Return the clique embedding with the maximum number of variables.
remove_unknown_kwargs(**kwargs)	Remove with warnings any keyword arguments not accepted by the sampler.
sample(bqm[, chain_strength])	Sample from the specified binary quadratic model.
sample_ising(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
sample_qubo(Q, **parameters)	Sample from a QUBO using the implemented sample method.
trigger_failover()	Trigger a failover and connect to a new solver.

LeapHybridSampler

class LeapHybridSampler(**config)

Submits binary quadratic models to a hybrid solver in the Leap service.

The Leap service’s quantum-classical hybrid binary quadratic model (BQM) solvers are intended to solve arbitrary application problems formulated as BQMs.

You can configure your solver selection as described in the Configuration section.[1]

Parameters:

**config – Keyword arguments passed to from_config().

Examples

This example samples a randomly generated binary quadratic model with 10 variables and 15 interactions.

>>> from dimod.generators import gnm_random_bqm
>>> from dwave.system import LeapHybridSampler
...
>>> bqm = gnm_random_bqm(10, 15, 'SPIN')
>>> with LeapHybridSampler() as sampler:    
...     sampleset = sampler.sample(bqm)

[1]

dwave-cloud-client’s get_solvers() method filters solvers you have access to by solver properties category=hybrid and supported_problem_type=bqm. By default, online hybrid BQM solvers are returned ordered by latest version.

The default specification for filtering and ordering solvers by features is available as default_solver property. Explicitly specifying a solver in a configuration file, an environment variable, or keyword arguments overrides this specification.

Properties

default_solver
parameters	Solver parameters as returned by a SAPI query.
properties	Solver properties as returned by a SAPI query.

Methods

close()	Close the underlying cloud client to release system resources such as threads.
min_time_limit(bqm)	Return the minimum time_limit accepted for the given problem.
remove_unknown_kwargs(**kwargs)	Remove with warnings any keyword arguments not accepted by the sampler.
sample(bqm[, time_limit])	Sample from the specified binary quadratic model.
sample_ising(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
sample_qubo(Q, **parameters)	Sample from a QUBO using the implemented sample method.

LeapHybridCQMSampler

class LeapHybridCQMSampler(**config)

Submits constrained quadratic models to a hybrid solver in the Leap service.

The Leap service’s quantum-classical hybrid constrained quadratic model (CQM) solvers are intended to solve arbitrary application problems formulated as CQMs.

You can configure your solver selection as described in the Configuration section.[2]

Parameters:

**config – Keyword arguments passed to from_config().

Examples

This example solves a simple problem of finding the rectangle with the greatest area when the perimeter is limited. In this example, the perimeter of the rectangle is set to 8 (meaning the largest area is for the \(2X2\) square).

A CQM is created that will have two integer variables, \(i, j\), each limited to half the maximum perimeter length of 8, to represent the lengths of the rectangle’s sides:

>>> from dimod import ConstrainedQuadraticModel, Integer
>>> i = Integer('i', upper_bound=4)
>>> j = Integer('j', upper_bound=4)
>>> cqm = ConstrainedQuadraticModel()

The area of the rectangle is given by the multiplication of side \(i\) by side \(j\). The goal is to maximize the area, \(i*j\). Because D-Wave samplers minimize, the objective should have its lowest value when this goal is met. Objective \(-i*j\) has its minimum value when \(i*j\), the area, is greatest:

>>> cqm.set_objective(-i*j)

Finally, the requirement that the sum of both sides must not exceed the perimeter is represented as constraint \(2i + 2j <= 8\):

>>> cqm.add_constraint(2*i+2*j <= 8, "Max perimeter")
'Max perimeter'

Instantiate a hybrid CQM sampler and submit the problem for solution by a remote solver provided by the Leap quantum cloud service:

>>> from dwave.system import LeapHybridCQMSampler   
>>> with LeapHybridCQMSampler() as sampler:         
...     sampleset = sampler.sample_cqm(cqm)
...     print(sampleset.first)
Sample(sample={'i': 2.0, 'j': 2.0}, energy=-4.0, num_occurrences=1,
...            is_feasible=True, is_satisfied=array([ True]))

The best (lowest-energy) solution found has \(i=j=2\) as expected, a solution that is feasible because all the constraints (one in this example) are satisfied.

[2]

dwave-cloud-client’s get_solvers() method filters solvers you have access to by solver properties category=hybrid and supported_problem_type=cqm. By default, online hybrid CQM solvers are returned ordered by latest version.

The default specification for filtering and ordering solvers by features is available as default_solver property. Explicitly specifying a solver in a configuration file, an environment variable, or keyword arguments overrides this specification.

Properties

default_solver
properties	Solver properties as returned by a SAPI query.
parameters	Solver parameters as returned by a SAPI query.

Methods

close()	Close the underlying cloud client to release system resources such as threads.
min_time_limit(cqm)	Return the minimum time_limit, in seconds, accepted for the given problem.
sample_cqm(cqm[, time_limit])	Sample from the specified constrained quadratic model.

LeapHybridNLSampler

class LeapHybridNLSampler(**config)

Submits nonlinear models to a hybrid solver in the Leap service.

The Leap service’s quantum-classical hybrid nonlinear model solvers are intended to solve arbitrary application problems formulated as nonlinear models.

You can configure your solver selection as described in the Configuration section.[3]

Parameters:

**config – Keyword arguments passed to from_config().

Examples

This example submits a model for a flow-shop-scheduling problem.

>>> from dwave.optimization.generators import flow_shop_scheduling
>>> from dwave.system import LeapHybridNLSampler
...
>>> with LeapHybridNLSampler() as sampler:      
...     processing_times = [[10, 5, 7], [20, 10, 15]]
...     model = flow_shop_scheduling(processing_times=processing_times)
...     results = sampler.sample(model, label="Small FSS problem")
...     job_order = next(model.iter_decisions())
...     print(f"State 0 of {model.objective.state_size()} has an "
...           f"objective value {model.objective.state(0)} for order "
...           f"{job_order.state(0)}.")
State 0 of 8 has an objective value 50.0 for order [1. 2. 0.].

[3]

dwave-cloud-client’s get_solvers() method filters solvers you have access to by solver properties category=hybrid and supported_problem_type=nl. By default, online hybrid NL solvers are returned ordered by latest version.

The default specification for filtering and ordering solvers by features is available as default_solver property. Explicitly specifying a solver in a configuration file, an environment variable, or keyword arguments overrides this specification.

Properties

default_solver
parameters	Solver parameters as returned by a SAPI query.
properties	Solver properties as returned by a SAPI query.

Methods

close()	Close the underlying cloud client to release system resources such as threads.
estimated_min_time_limit(nlm)	Return the minimum required time, in seconds, estimated for the given problem.
sample(model[, time_limit])	Sample from the specified nonlinear model.

LeapHybridDQMSampler

class LeapHybridDQMSampler(**config)

Submits discrete quadratic models to a hybrid solver in the Leap service.

The Leap service’s quantum-classical hybrid discrete quadratic model (DQM) solvers are intended to solve arbitrary application problems formulated as DQMs.

You can configure your solver selection as described in the Configuration section.[4]

Parameters:

**config – Keyword arguments passed to from_config().

Examples

This example solves a small, illustrative problem: a game of rock-paper-scissors. The DQM has two variables representing two hands, with cases for rock, paper, scissors. Quadratic biases are set to produce a lower value of the DQM for cases of variable my_hand interacting with cases of variable their_hand such that the former wins over the latter; for example, the interaction of rock-scissors is set to -1 while scissors-rock is set to +1.

>>> import dimod
>>> from dwave.system import LeapHybridDQMSampler
...
>>> cases = ["rock", "paper", "scissors"]
>>> win = {"rock": "scissors", "paper": "rock", "scissors": "paper"}
...
>>> dqm = dimod.DiscreteQuadraticModel()
>>> dqm.add_variable(3, label='my_hand')
'my_hand'
>>> dqm.add_variable(3, label='their_hand')
'their_hand'
>>> for my_idx, my_case in enumerate(cases):
...    for their_idx, their_case in enumerate(cases):
...       if win[my_case] == their_case:
...          dqm.set_quadratic('my_hand', 'their_hand',
...                            {(my_idx, their_idx): -1})
...       if win[their_case] == my_case:
...          dqm.set_quadratic('my_hand', 'their_hand',
...                            {(my_idx, their_idx): 1})
...
>>> with LeapHybridDQMSampler() as dqm_sampler:     
...     sampleset = dqm_sampler.sample_dqm(dqm)
...     print(f"{} beats {}".format(cases[sampleset.first.sample['my_hand']],
...                                 cases[sampleset.first.sample['their_hand']]))
rock beats scissors

[4]

dwave-cloud-client’s get_solvers() method filters solvers you have access to by solver properties category=hybrid and supported_problem_type=dqm. By default, online hybrid DQM solvers are returned ordered by latest version.

The default specification for filtering and ordering solvers by features is available as default_solver property. Explicitly specifying a solver in a configuration file, an environment variable, or keyword arguments overrides this specification.

Properties

default_solver
parameters	Solver parameters as returned by a SAPI query.
properties	Solver properties as returned by a SAPI query.

Methods

close()	Close the underlying cloud client to release system resources such as threads.
min_time_limit(dqm)	Return the minimum time_limit accepted for the given problem.
sample_dqm(dqm[, time_limit, compress, ...])	Sample from the specified discrete quadratic model.