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(**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 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.

  • compress_qpu_problem_data (bool, default=True) – Enable QPU problem data compression on upload to SAPI. Enabled by default. Set to False to disable compression.

  • 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_strategy (str, 'backoff' | 'long-polling', default='long-polling') –

    Polling strategy for problem status. Supported options are short polling with exponential back-off, configured with poll_backoff_* parameters, and long polling, configured with poll_wait_time and poll_pause parameters.

    Added in version 0.13.0: Added support for long polling strategy. Long polling is the new default, but the "backoff" strategy can still be used if desired.

  • poll_backoff_min (float, default=0.05) – When problem status is polled with exponential back-off schedule, the duration of the first interval (between first and second poll) is set to poll_backoff_min seconds.

  • poll_backoff_max (float, default=60) – When problem status is polled with exponential back-off schedule, the maximum back-off period is limited to poll_backoff_max seconds.

  • poll_backoff_base (float, default=1.3) –

    When 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.

  • poll_wait_time (int, in range [0, 30], default=30) –

    When problem status is polled using long polling, this value sets the maximum time, in seconds, a long polling connection waits for the API response.

    Added in version 0.13.0.

  • poll_pause (float, default=0.0) –

    When problem status is polled using long polling, this value limits the delay, in seconds, between two successive long polling connections. It’s preferred to keep this value at zero.

    Added in version 0.13.0.

  • 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.

  • leap_api_endpoint (str, optional) – Leap API endpoint.

  • leap_client_id (str, optional) – Leap OAuth 2.0 Ocean client id. Reserved for testing, otherwise don’t override.

  • cache_enabled (bool, optional, default=True) –

    A flag to explicitly disable cache. Can also be done by setting cache_home to "off".

    Added in version 0.14.2.

  • cache_home (str, optional) –

    Disk cache base directory. Set to "off" to disable caching, and set to "default" (or leave unspecified) to use the default cache directory inferred from the environment, as returned by get_cache_dir().

    Added in version 0.14.2.

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

Changed in version 0.11.0: Added the leap_api_endpoint parameter and config option (also available via environment variable DWAVE_LEAP_API_ENDPOINT).

Added the leap_client_id parameter and config option (also available via environment variable DWAVE_LEAP_CLIENT_ID). This option is reserved for testing.

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.

Removed in version 0.12.0: Positional arguments in Client constructor, deprecated in 0.10.0, are removed in 0.12.0. Use keyword arguments instead.

Removed in version 0.13.0: Config attributes on Client, deprecated in 0.11.0, are removed in 0.13.0. Use config model attributes on Client.config instead.

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_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([wait])

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