Configuring Access to Leap’s Solvers¶

D-Wave’s Solver API (SAPI) provides access to the solvers—compute resources for solving problems, such as a D-Wave quantum computers and quantum-classical hybrid solvers—hosted in the Leap quantum cloud.1

1: SAPI is used similarly for on-premises systems. Differences for such systems are noted below.

This page provides the following information:

Section Interacting with SAPI provides information on viewing and configuring SAPI resources.
Section Create a Configuration File steps you through creating a configuration file, which enables you to interact conveniently with SAPI.
Section Verify Your Configuration ensures that your environment is set up correctly.
Section Accessing Solvers in Multiple Regions provides information for users interested in using solvers hosted outside their default region.

Interacting with SAPI¶

SAPI is an application layer that provides resource discovery, permissions, and scheduling for D-Wave solvers. Problem submission through SAPI requires the following information, typically provided by your work environment from either Ocean’s default values or your configuration.

API Token (required)

An authentication token used to authenticate the client session when you connect to the remote environment.

Finding your API Token

The Viewing Your SAPI Token table shows various options to view your SAPI token.

Viewing Your SAPI Token¶
Where	How	Defaults	Usage Notes
Leap dashboard	Log in to your Leap account.	For users that belong to multiple projects, your SAPI token for the current project is displayed; switch the current project if needed.
dwave-cloud-client	Use the dwave CLI tool.	For users that belong to multiple projects, you can specify the relevant project.	Requires that you authorize Leap access.

Example: using dwave CLI to see your SAPI token (the output shown below is illustrative only).

$ dwave leap project token --project Demo-Proj
Solver API token for project Demo-Proj (ABC) is ABC-1234567890...12345.

Using your API Token

Typically, you configure your work environment so Ocean tools can automatically submit your API token when interacting with SAPI. Because tokens provide authentication, user names and passwords are not required in your code. The Using your API Token table shows various options of configuring and directly using your API token.

Using your API Token¶
Where	How	Usage Notes
Configuration file	Configure using the dwave CLI tool or edit the file manually.	You can override this configuration by setting an environment variable or explicitly in your code.
Environment variables	Configure `DWAVE_API_TOKEN`. For example, `export DWAVE_API_TOKEN=ABC-1234 ... 789` in a Unix shell.	You can override this configuration explicitly in your code.
Explicit parameters	You can set your API token directly in your code; for example, `sampler = LeapHybridCQMSampler(token="ABC-1234 ... 789")`	Not recommended outside of testing (for security reasons).

Note

For non-Ocean clients, you set your token in the HTTP header; see the SAPI REST Developer Guide guide for information.

Solver (default: feature-based selection)

A D-Wave resource to be used to solve your submitted problems; for example, a quantum-classical hybrid solver or an Advantage quantum computer.

Viewing Available Solvers

The Viewing Available Solvers table shows various options to view available solvers.

Viewing Available Solvers¶
Where	How	Defaults	Usage Notes
Leap dashboard	Log in to your Leap account.	For users that belong to multiple projects, solvers accessible to the current project are displayed; switch the current project if needed.	Solvers may be local to a region.
dwave-cloud-client	Use the dwave CLI tool or Ocean’s `get_solvers()` method.	For users that belong to multiple projects, queries return solvers accessible to the current API token; switch to another project’s API token if needed.	Solvers may be local to a region; see the Accessing Solvers in Multiple Regions section to query solvers outside your default region.

Example: using dwave CLI to see the available solvers, their parameters, and properties (the output shown below is illustrative only).

$ dwave solvers  --list --all
DW_2000Q_6
hybrid_binary_quadratic_model_version2
hybrid_discrete_quadratic_model_version1
Advantage_system4.1

Example: using dwave-cloud-client to query for hybrid solvers.

>>> from dwave.cloud import Client
>>> with Client.from_config() as client:         
...    print(client.get_solvers(hybrid=True))
[BQMSolver(id='hybrid_binary_quadratic_model_version2'),
DQMSolver(id='hybrid_discrete_quadratic_model_version1'),
CQMSolver(id='hybrid_constrained_quadratic_model_version1')]

Note

For non-Ocean clients, you can retrieve a list of supported remote solvers by sending an HTTP GET request to the <SAPI base URL>/solvers/ endpoint; see the SAPI REST Developer Guide guide for information.

Selecting a Solver

By default Ocean selects solvers based on a set of preferred features; for example, by default a problem submitted to a quantum computer with the DWaveSampler class sampler might prefer the less busy of two available QPUs. The Selecting a Solver table shows various options to configure solver selection.

Selecting a Solver¶
Where	How	Usage Notes
Configuration file	Configure using the dwave CLI tool or edit the file manually.	You can override this configuration by setting a solver in an environment variable or explicitly in your code.
Environment variables	Configure `DWAVE_API_SOLVER`. For example, `export DWAVE_API_SOLVER='{"num_qubits__gt": 2000}'` in a Unix shell.	You can override this configuration by selecting a solver explicitly in your code.
Explicit parameter	You can set your solver selection directly in your code; for example, `sampler = DWaveSampler(solver=dict(topology__type='pegasus'))`

Region/Endpoint (default: North American URL)

A URL for a region’s remote resources.

By default, Ocean connects to North American (region na-west-1) Leap quantum cloud resources at URL https://na-west-1.cloud.dwavesys.com/sapi/v2/.

Finding Supported Regions and Endpoints

The Viewing Available Regions and Endpoints table shows various options for viewing available regions and their URLs.

Viewing Available Regions and Endpoints¶
Where	How	Usage Notes
Leap dashboard	Log in to your Leap account	Solvers available to your account are grouped by region.
dwave-cloud-client	Use the Interactive CLI or `get_regions()`

Example: using dwave-cloud-client to query supported regions.

>>> from dwave.cloud import Client
>>> with Client.from_config() as client:          
...    regions = client.get_regions()
...    for code, info in regions.items():
...        print(f"{info['name']} ({code}): {info['endpoint']}")
North America (na-west-1): https://na-west-1.cloud.dwavesys.com/sapi/v2/
Europe (eu-central-1): https://eu-central-1.cloud.dwavesys.com/sapi/v2/

Note

Users of on-premises systems should request the SAPI endpoint from system administrator.

Note

For non-Ocean clients, you can retrieve a list of supported regions by sending an HTTP GET request to the https://cloud.dwavesys.com/metadata/v1/regions endpoint.

For information about using solvers in alternative geographical regions, see the Accessing Solvers in Multiple Regions section below.

Create a Configuration File¶

The simplest way to configure solver access is to use the interactive CLI, which is installed as part of the dwave-ocean-sdk installation.

If you did not already do so with the dwave setup command in the Set Up Your Environment section, or want to make changes at a later time, you can use the dwave config command.

$ dwave config --help
Usage: dwave config [OPTIONS] COMMAND [ARGS]...

Create, update or inspect cloud client configuration file(s).

Options:
  --help  Show this message and exit.

Commands:
  create   Create and/or update cloud client configuration file.
  inspect  Inspect existing configuration/profile.
  ls       List configuration files detected (and/or examined paths).

Creating a configuration file using the dwave config is done as follows (the dwave setup command of the Set Up Your Environment section runs these same configuration steps):

In the virtual environment you created as part of Installing Ocean Tools, run the dwave config create command2 (the output shown below includes the interactive prompts and placeholder replies).

$ dwave config create --auto-token
Using the simplified configuration flow.
Try 'dwave config create --full' for more options.

Creating new configuration file: /home/jane/.config/dwave/dwave.conf
Updating existing profile: defaults
Access token expired (or expires soon), refreshing it.
Fetched SAPI token for project 'ABC' (ABC) from Leap API.
Configuration saved.

2: You can use the --auto-token option if you have authorized Leap access.

If needed, enter SAPI information (e.g. your API token) found as described in the Interacting with SAPI section above. To get started, create a minimum configuration by accepting the command’s defaults (pressing Enter) for all prompts3. You can in the future update the file if needed.

3: Users of on-premises systems should also enter the SAPI endpoint. Users interested in using solvers hosted outside their default region can also configure the SAPI endpoint (see the Accessing Solvers in Multiple Regions section for the recommended way of configuring such access).

Alternatively, you can create and edit a D-Wave Cloud Client configuration file manually.

You can always set or override your configurations in your code or with environment variables. For more information, see the examples in this document or D-Wave Cloud Client.

Verify Your Configuration¶

You can test that your solver access is configured correctly with the interactive CLI.

In your virtual environment, run the dwave ping command (the output shown below is illustrative only).

The example below, for a Bash Unix shell, pings only QPU solvers.

$ dwave ping --client qpu
Using endpoint: https://cloud.dwavesys.com/sapi
Using solver: DW_2000Q_6
Submitted problem ID: 34f773f7-77dc-7fa5-a7d5-7e397d90fc4a

Wall clock time:
 * Solver definition fetch: 1888.499 ms
 * Problem submit and results fetch: 1038.042 ms
 * Total: 2926.541 ms

QPU timing:
 * post_processing_overhead_time = 307.0 us
 * qpu_access_overhead_time = 1185.96 us
 * qpu_access_time = 10995.04 us
 * qpu_anneal_time_per_sample = 20.0 us
 * qpu_delay_time_per_sample = 20.54 us
 * qpu_programming_time = 10756.1 us
 * qpu_readout_time_per_sample = 198.4 us
 * qpu_sampling_time = 238.94 us
 * total_post_processing_time = 307.0 us

Optionally, run the dwave sample --random-problem command to submit a random problem to a remote solver (the output shown below is illustrative only).

$ dwave sample --random-problem
Using endpoint: https://my.dwavesys.url/
Using solver: My_DWAVE_2000Q
Using qubit biases: {0: -1.0345257941434953, 1: -0.5795618633919246, 2: 0.9721956399428491, 3: 1....
Using qubit couplings: {(1634, 1638): 0.721736584181423, (587, 590): 0.9611623181258304, (642, 64...
Number of samples: 1
Samples: [[1, 1, -1, -1, -1, -1, 1, -1, -1, 1, -1, 1, 1, 1, -1, -1, -1, -1, -1, -1, -1, 1, 1, -1,...
Occurrences: [1]
Energies: [-2882.197791239335]

Accessing Solvers in Multiple Regions¶

Leap quantum cloud service is distributed across multiple geographic regions. You can see the supported regions and the solvers available in each for your account in your Leap dashboard. Ocean’s dwave-cloud-client enables you to select solvers from a particular region using one or more of the following options:

Select a default region in your dwave-cloud-client configuration file. You can run the dwave config CLI command with the --full option or edit an existing configuration file to set a preferred region.
Set the appropriate environment variable (for example, export DWAVE_API_REGION=eu-central-1 in a Unix shell) for your current terminal or working session to select solvers from a preferred region.
Explicitly select the region in your code. For example, the region parameter in the code line sampler = DWaveSampler(region="na-west-1") selects a D-Wave quantum computer located in North America.

Note

Keep in mind the relative priorities of configurations set at various levels (in the above bullets, the configuration file, environment variables, and explicit parameters in your code), as described in the dwave-cloud-client documentation. For example, while the setting of both an endpoint and region on the same level (either two lines in the configuration file or two environment variables or two explicit parameters) results in selection based on the endpoint, setting a region explicitly overrides an endpoint configured using an environment variable or in the configuration file.

Example: Viewing a Region’s Solvers¶

You can use interactive CLI to query solvers in a particular region.

$ dwave solvers --list --region eu-central-1
Advantage_system5.1

Example: Using Configuration-File Profiles for Multiple Regions¶

You can set up your configuration file with profiles for multiple regions, as shown below.

[defaults]
token = ABC-123456789123456789123456789

[europe]
region = eu-central-1

You can then set the profile when instantiating a sampler, as below.

>>> from dwave.system import DWaveSampler, EmbeddingComposite
>>> sampler = EmbeddingComposite(DWaveSampler(profile="europe"))   