Configuration

Configuration for communicating with a solver.

Communicating with a solver—submitting a problem, monitoring its progress, receiving samples—requires configuration of several parameters such as the selected solver, its URL, an API token, etc. D-Wave Cloud Client provides multiple options for configuring those parameters:

  • One or more locally saved configuration files.

  • Environment variables

  • Direct setting of key values in functions

These options can be flexibly used together. The standard use is through the from_config() classmethod.

Configuration values can be specified in multiple ways, ranked in the following order (with 1 the highest ranked):

  1. Values specified as keyword arguments.

  2. Values specified as environment variables.

  3. Values specified in the configuration file.

  4. Values specified in Client instance defaults.

  5. Values specified in Client class DEFAULTS.

Configuration files comply with standard Windows INI-like format, parsable with Python’s configparser. An optional defaults section provides default key-value pairs for all other sections. User-defined key-value pairs (unrecognized keys) are passed through to the client.

Typically configuration files are created, inspected, and changed using interactive CLI commands from your system’s console, such as dwave config create and dwave config inspect (run dwave --help for information on CLI options).

Environment variables:

DWAVE_CONFIG_FILE: Configuration file path.

DWAVE_PROFILE: Name of profile (section).

DWAVE_API_CLIENT: API client class. Supported values are qpu, sw and hybrid.

DWAVE_API_REGION: API region code.

DWAVE_API_ENDPOINT: API endpoint URL.

DWAVE_METADATA_API_ENDPOINT: Metadata API endpoint URL.

DWAVE_API_TOKEN: API authorization token.

DWAVE_API_SOLVER: Default solver.

DWAVE_API_PROXY: URL for proxy connections to D-Wave API.

DWAVE_API_HEADERS: Optional additional HTTP headers.

Examples

The following are typical examples of using from_config() to create a configured client.

This first example initializes Client from an explicitly specified configuration file, “~/jane/my_path_to_config/my_cloud_conf.conf”:

[defaults]
token = ABC-123456789123456789123456789

[first-qpu]
solver = {"qpu": true}

[feature]
endpoint = https://url.of.some.dwavesystem.com/sapi
token = DEF-987654321987654321987654321
solver = {"num_qubits__gte": 2000, "max_anneal_schedule_points__gte": 4}

The example code below creates a client object that connects to a D-Wave QPU, using dwave.cloud.qpu.Client and the first available online D-Wave system at the default API endpoint URL (https://cloud.dwavesys.com/sapi). The feature profile specifies a solver selected based on available features, namely we’re requesting the first solver that has at least 2000 qubits and the anneal schedule can be described with at least 4 points.

>>> from dwave.cloud import Client
>>> client = Client.from_config(config_file='~/jane/my_path_to_config/my_cloud_conf.conf')  
>>> # code that uses client
>>> client.close()

This second example auto-detects a configuration file on the local system following the user/system configuration paths of get_configfile_paths(). It passes through to the instantiated client an unrecognized key-value pair my_param=`my_value`.

>>> from dwave.cloud import Client
>>> client = Client.from_config(my_param="my_value")    
>>> # code that uses client
>>> client.close()

This third example instantiates two clients, for managing both QPU and software solvers. Common key-value pairs are taken from the defaults section of a shared configuration file:

[defaults]
token = ABC-123456789123456789123456789

[primary-qpu]
solver = {"qpu": true}

[sw-solver]
client = sw
solver = c4-sw_sample
endpoint = https://url.of.some.software.resource.com/my_if
token = DEF-987654321987654321987654321

[backup-qpu]
solver = {"qpu": true, "num_qubits__gte": 2000}
endpoint = https://url.of.some.dwavesystem.com/sapi
proxy = http://user:pass@myproxy.com:8080/
token = XYZ-0101010100112341234123412341234

The example code below creates client objects for two QPU solvers (at the same URL but each with its own solver ID and token) and one software solver.

>>> from dwave.cloud import Client
>>> client_qpu1 = Client.from_config(profile='primary-qpu')    
>>> client_qpu1 = Client.from_config(profile='backup-qpu')    
>>> client_sw1 = Client.from_config(profile='sw-solver')   
>>> client_qpu1.default_solver   
'EXAMPLE_2000Q_SYSTEM_A'
>>> client_qpu2.endpoint   
'https://url.of.some.dwavesystem.com/sapi'
>>> # code that uses client
>>> client_qpu1.close() 
>>> client_qpu2.close() 
>>> client_sw1.close()

This fourth example loads configurations auto-detected in more than one configuration file, with the higher priority file (in the current working directory) supplementing and overriding values from the lower priority user-local file. After instantiation, an endpoint from the default section and client from the profile section is provided from the user-local /usr/local/share/dwave/dwave.conf file:

[defaults]
solver = {"qpu": true}

[dw2000]
endpoint = https://int.se.dwavesystems.com/sapi
token = ABC-123456789123456789123456789

A solver is supplemented from the file in the current working directory, which also overrides the token value. ./dwave.conf is the file in the current directory:

[dw2000]
token = DEF-987654321987654321987654321

>>> from dwave.cloud import Client
>>> client = Client.from_config()  
>>> client.default_solver   
'EXAMPLE_2000Q_SYSTEM_A'
>>> client.endpoint  
'https://int.se.dwavesystems.com/sapi'
>>> client.token  
'DEF-987654321987654321987654321'
>>> # code that uses client
>>> client.close()

The next example uses load_config() to load profile values. Most users do not need to use this method. It loads from the following configuration file, dwave_c.conf, located in the current working directory, and specified explicitly:

[defaults]
endpoint = https://url.of.some.dwavesystem.com/sapi
solver = {"qpu": true}

[dw2000a]
solver = {"software": true, "name": "EXAMPLE_2000Q"}
token = ABC-123456789123456789123456789

[dw2000b]
solver = {"qpu": true}
token = DEF-987654321987654321987654321

This configuration file contains two profiles in addition to the defaults section. In the following example code, first no profile is specified, and the first profile after the defaults section is loaded with the solver overridden by the environment variable. Next, the second profile is selected with the explicitly named solver overriding the environment variable setting.

>>> import dwave.cloud
>>> import os
>>> os.environ['DWAVE_API_SOLVER'] = 'EXAMPLE_2000Q_SYSTEM'   
>>> dwave.cloud.config.load_config("./dwave_c.conf")   
{'client': 'sw',
 'endpoint': 'https://url.of.some.dwavesystem.com/sapi',
 'proxy': None,
 'headers': None,
 'solver': 'EXAMPLE_2000Q_SYSTEM',
 'token': 'ABC-123456789123456789123456789'}
>>> dc.config.load_config("./dwave_c.conf", profile='dw2000b', solver='Solver3')   
{'client': 'qpu',
 'endpoint': 'https://url.of.some.dwavesystem.com/sapi',
 'proxy': None,
 'headers': None,
 'solver': 'Solver3',
 'token': 'DEF-987654321987654321987654321'}

Methods

Most users do not need to use these methods.

Loading Configuration

These functions deploy D-Wave Cloud Client settings from a configuration file.

load_config([config_file, profile])

Load D-Wave Cloud Client configuration based on a configuration file.

Managing Files

These functions manage your D-Wave Cloud Client configuration files. It’s recommended you set up your configuration through the interactive CLI utility instead.

get_configfile_paths([system, user, local, ...])

Return a list of local configuration file paths.

get_configfile_path()

Return the highest-priority local configuration file.

get_default_configfile_path()

Return the default configuration-file path.