Clients

The solvers that provide sampling for solving Ising and QUBO problems, such as a D-Wave 2000Q QPU or a software sampler such as the dimod simulated annealing sampler, are typically remote resources. The D-Wave Cloud Client Client class manages such remote solver resources.

Preferred use is with a context manager—a with Client.from_config(...) as construct—to ensure proper closure of all resources. The following example snippet creates a client based on an auto-detected configuration file and instantiates a solver.

>>> with Client.from_config() as client:   # doctest: +SKIP
...     solver = client.get_solver(num_qubits__gt=2000)

Alternatively, the following example snippet creates a client for software resources that it later explicitly closes.

>>> client = Client.from_config(software=True)   # doctest: +SKIP
>>> # code that uses client
>>> client.close()    # doctest: +SKIP

Typically you use the Client class. By default, it instantiates a QPU client. You can also use the specialized QPU and CPU/GPU clients directly.

Client (Base Client)

D-Wave API clients handle communications with solver resources: problem submittal, monitoring, samples retrieval, etc.

Examples

This example creates a client using the local system’s default D-Wave Cloud Client configuration file, which is configured to access a D-Wave 2000Q QPU, submits a QUBO problem (a Boolean NOT gate represented by a penalty model), and samples 5 times.

>>> from dwave.cloud import Client
>>> Q = {(0, 0): -1, (0, 4): 0, (4, 0): 2, (4, 4): -1}
>>> with Client.from_config() as client:  # doctest: +SKIP
...     solver = client.get_solver()
...     computation = solver.sample_qubo(Q, num_reads=5)
...
>>> for i in range(5):     # doctest: +SKIP
...     print(computation.samples[i][0], computation.samples[i][4])
...
(1, 0)
(1, 0)
(0, 1)
(0, 1)
(0, 1)

Class

class Client(endpoint=None, token=None, solver=None, **kwargs)[source]

Base client class for all D-Wave API clients. Used by QPU, software and hybrid sampler classes.

Manages workers and handles thread pools for submitting problems, cancelling tasks, polling problem status, and retrieving results.

Parameters:
  • endpoint (str, optional) – D-Wave API endpoint URL.
  • token (str) – Authentication token for the D-Wave API.
  • solver (dict/str, optional) –

    Default solver features (or simply solver name) to use in get_solver().

    Defined via dictionary of solver feature constraints (see get_solvers()). For backward compatibility, a solver name, as a string, is also accepted and converted to {"name": <solver name>}.

  • proxy (str, optional) – Proxy URL to be used for accessing the D-Wave API.
  • permissive_ssl (bool, default=False) – Disables SSL verification.
  • request_timeout (float, default=60) – Connect and read timeout, in seconds, for all requests to the D-Wave API.
  • polling_timeout (float, optional) – Problem status polling timeout, in seconds, after which polling is aborted.
  • connection_close (bool, default=False) – Force HTTP(S) connection close after each request. Set to True to prevent intermediate network equipment closing idle connections.
  • headers (dict/str, optional) – Newline-separated additional HTTP headers to include with each API request, or a dictionary of (key, value) pairs.
  • client_cert (str, optional) – Path to client side certificate file.
  • client_cert_key (str, optional) – Path to client side certificate key file.
  • poll_backoff_min (float, default=0.05) – Problem status is polled with exponential back-off schedule. Duration of the first interval (between first and second poll) is set to poll_backoff_min seconds.
  • poll_backoff_max (float, default=60) – Problem status is polled with exponential back-off schedule. Maximum back-off period is limited to poll_backoff_max seconds.
  • defaults (dict, optional) – Defaults for the client instance that override the class DEFAULTS.

Note

Default values of all constructor arguments listed above are kept in a class variable DEFAULTS.

Instance-level defaults can be specified via defaults argument.

Examples

This example directly initializes a Client. Direct initialization uses class constructor arguments, the minimum being a value for token.

>>> from dwave.cloud import Client
>>> client = Client(token='secret')     # doctest: +SKIP
>>> # code that uses client
>>> client.close()       # doctest: +SKIP

Properties

Client.DEFAULTS

Methods

Client.from_config([config_file, profile, …]) Client factory method to instantiate a client instance from configuration.
Client.get_solver([name, refresh]) Load the configuration for a single solver.
Client.get_solvers([refresh, order_by]) Return a filtered list of solvers handled by this client.
Client.solvers([refresh]) Deprecated in favor of get_solvers().
Client.is_solver_handled(solver) Determine if the specified solver should be handled by this client.
Client.retrieve_answer(id_) Retrieve a problem by id.
Client.close() Perform a clean shutdown.

Specialized Clients

Typically you use the Client class. By default, it instantiates a QPU client. You can also instantiate a QPU or CPU/GPU client directly.

QPU Client

An implementation of the REST client for D-Wave Solver API (SAPI) service.

SAPI servers provide authentication, queuing, and scheduling services, and provide a network interface to solvers. This API enables you submit a binary quadratic (Ising or QUBO) model and receive samples from a distribution over the model as defined by a selected solver.

SAPI server workflow is roughly as follows:

  1. Submitted problems enter an input queue. Each user has an input queue per solver.
  2. Drawing from all input queues for a solver, problems are scheduled.
  3. Results are cached for retrieval by the client.

Class

class Client(endpoint=None, token=None, solver=None, **kwargs)[source]

D-Wave Solver API client specialized to work only with QPU solvers.

This class can be instantiated explicitly, or via (base) Client’s factory method, from_config() by supplying "qpu" for client.

Examples

This example explicitly instantiates a dwave.cloud.qpu.Client. get_solver() is guaranteed to return a QPU solver.

from dwave.cloud.qpu import Client

with Client(token='...') as client:
    solver = client.get_solver()
    response = solver.sample_ising(...)

The following example instantiates a QPU client indirectly. Again, get_solver()/ get_solvers() are guaranteed to return only QPU solver(s).

from dwave.cloud import Client

with Client.from_config(client='qpu') as client:
    solver = client.get_solver()
    response = solver.sample_ising(...)

Hybrid-Samplers Client

Interface to hybrid samplers available through the D-Wave Solver API (SAPI).

Class

class Client(endpoint=None, token=None, solver=None, **kwargs)[source]

D-Wave Solver API client specialized to work only with remote hybrid quantum-classical solvers.

This class can be instantiated explicitly, or via (base) Client’s factory method, from_config() by supplying "hybrid" for client.

Examples

This example explicitly instantiates a dwave.cloud.hybrid.Client. get_solver() is guaranteed to return a hybrid quantum-classical solver.

from dwave.cloud.hybrid import Client

with Client(token='...') as client:
    solver = client.get_solver()
    response = solver.sample_bqm(...)

The following example instantiates a hybrid client indirectly. Again, get_solver()/ get_solvers() are guaranteed to return only hybrid solver(s).

from dwave.cloud import Client

with Client.from_config(client='hybrid') as client:
    solver = client.get_solver()
    response = solver.sample_bqm(...)

Software-Samplers Client

Interface to software samplers available through the D-Wave Solver API (SAPI).

Software samplers have the same interface (response) as QPU samplers, with classical software resources generating samples.

Class

class Client(endpoint=None, token=None, solver=None, **kwargs)[source]

D-Wave Solver API client specialized to work only with remote software solvers.

This class can be instantiated explicitly, or via (base) Client’s factory method, from_config() by supplying "sw" for client.

Examples

This example explicitly instantiates a dwave.cloud.sw.Client. get_solver() is guaranteed to return a software solver.

from dwave.cloud.sw import Client

with Client(token='...') as client:
    solver = client.get_solver()
    response = solver.sample_ising(...)

The following example instantiates a software-solver-only client indirectly. Again, get_solver()/ get_solvers() are guaranteed to return only software solver(s).

from dwave.cloud import Client

with Client.from_config(client='sw') as client:
    solver = client.get_solver()
    response = solver.sample_ising(...)