Clients

The solvers that provide sampling for a binary quadratic model problem, such as an Advantage quantum computer, or a quantum-classical hybrid sampler, such as Leap’s LeapHybridCQMSampler hybrid constrained quadratic model (CQM) 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:   
...     solver = client.get_solver(num_qubits__gt=5000)

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

>>> client = Client.from_config(client="hybrid")   
>>> # code that uses client
>>> client.close()

Typically you use the Client class. You can also instantiate specialized QPU, hybrid, and CPU clients directly.

Client (Base Client)

Class

class Client(*args, **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

  • region (str, optional, default='na-west-1') – D-Wave Solver API region. To see available regions use Client.get_regions().

  • endpoint (str, optional) – D-Wave Solver API endpoint URL. If undefined, inferred from region code.

  • token (str) – Authentication token for the D-Wave API.

  • solver (dict/str, optional) –

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

    Defined via dictionary of solver feature constraints (see Client.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.

  • poll_backoff_base (float, default=1.3) –

    Problem status is polled with exponential back-off schedule. The exponential function base is defined with poll_backoff_base. Interval between poll_idx and poll_idx + 1 is given with:

    poll_backoff_min * poll_backoff_base ** poll_idx

    with upper bound set to poll_backoff_max.

  • http_retry_total (int, default=10) – Total number of retries of failing idempotent HTTP requests to allow. Takes precedence over other counts. See total in Retry for details.

  • http_retry_connect (int, default=None) – How many connection-related errors to retry on. See connect in Retry for details.

  • http_retry_read (int, default=None) – How many times to retry on read errors. See read in Retry for details.

  • http_retry_redirect (int, default=None) – How many redirects to perform. See redirect in Retry for details.

  • http_retry_status (int, default=None) – How many times to retry on bad status codes. See status in Retry for details.

  • http_retry_backoff_factor (float, default=0.01) –

    A backoff factor to apply between attempts after the second try. Sleep between retries, in seconds:

    {backoff factor} * (2 ** ({number of total retries} - 1))

    See backoff_factor in Retry for details.

  • http_retry_backoff_max (float, default=60) – Maximum backoff time in seconds. See BACKOFF_MAX for details.

  • metadata_api_endpoint (str, optional) – D-Wave Metadata API endpoint. Central for all regions, used for regional SAPI endpoint discovery.

  • defaults (dict, optional) – Defaults for the client instance that override the class Client.DEFAULTS.

Note

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

Instance-level defaults can be specified via defaults argument.

Deprecated since version 0.10.0: Positional arguments in Client constructor are deprecated and will be removed in 0.12.0.

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')     
>>> # code that uses client
>>> client.close()

Properties

Client.DEFAULTS

Methods

Client.from_config([config_file, profile, ...])

Client factory method to instantiate a client instance from configuration.

Client.get_regions([refresh])

Retrieve available API regions.

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.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. You can also instantiate a QPU, hybrid, or CPU 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(*args, **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 Client

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

Class

class Client(*args, **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(supported_problem_types__issubset={"bqm"})
    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(supported_problem_types__issubset={"cqm"})
    response = solver.sample_cqm(...)

Software 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(*args, **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(...)