Configuration

Module name: pennylane.configuration

This module contains the Configuration class, which is used to load, store, save, and modify configuration options for PennyLane and all supported plugins and devices.

Behaviour

On first import, PennyLane attempts to load the configuration file config.toml, by scanning the following three directories in order of preference:

  1. The current directory
  2. The path stored in the environment variable PENNYLANE_CONF
  3. The default user configuration directory:
    • On Linux: ~/.config/pennylane
    • On Windows: ~C:\Users\USERNAME\AppData\Local\Xanadu\pennylane
    • On MacOS: ~/Library/Preferences/pennylane

If no configuration file is found, a warning message will be displayed in the logs, and all device parameters will need to be passed as keyword arguments when loading the device.

The user can access the initialized configuration via pennylane.config, view the loaded configuration filepath, print the configurations options, access and modify them via keys (i.e., pennylane.config['main.shots']), and save/load new configuration files.

Configuration files

The configuration file config.toml uses the TOML standard, and has the following format:

[main]
# Global PennyLane options.
# Affects every loaded plugin if applicable.
shots = 0

[strawberryfields.global]
# Options for the Strawberry Fields plugin
hbar = 1
shots = 100

  [strawberryfields.fock]
  # Options for the Strawberry Fields Fock plugin
  cutoff_dim = 10
  hbar = 0.5

  [strawberryfields.gaussian]
  # Indentation doesn't matter in TOML files,
  # but helps provide clarity.

[projectq.global]
# Options for the Project Q plugin

  [projectq.simulator]
  gate_fusion = true

  [projectq.ibm]
  user = "johnsmith"
  password = "secret123"
  use_hardware = true
  device = "ibmqx4"
  num_runs = 1024

Main PennyLane options, that are passed to all loaded devices, are provided under the [main] section. Alternatively, options can be specified on a per-plugin basis, by setting the options under [plugin.global].

For example, in the above configuration file, the Strawberry Fields devices will be loaded with a default of shots = 100, rather than shots = 0. Finally, you can also specify settings on a device-by-device basis, by placing the options under the [plugin.device] settings.

Summary of methods

path Return the path of the loaded configuration file.
load(filepath) Load a configuration file.
save(filepath) Save a configuration file.

Helper methods

safe_set(dct, value, *keys) Safely set the value of a key from a nested dictionary.
safe_get(dct, *keys) Safely return value from a nested dictionary.

Code details

class Configuration(name)[source]

Configuration class.

This class is responsible for loading, saving, and storing PennyLane and plugin/device configurations.

Parameters:
  • name (str) – filename of the configuration file.
  • should be a valid TOML file. You may also pass an absolute (This) –
  • a relative file path to the configuration file. (or) –
__init__(name)[source]

Initialize self. See help(type(self)) for accurate signature.

__str__()[source]

Return str(self).

__repr__()[source]

Return repr(self).

path

Return the path of the loaded configuration file.

Returns:If no configuration is loaded, this returns None.
Return type:str
load(filepath)[source]

Load a configuration file.

Parameters:filepath (str) – path to the configuration file.
save(filepath)[source]

Save a configuration file.

Parameters:filepath (str) – path to the configuration file.
static safe_set(dct, value, *keys)[source]

Safely set the value of a key from a nested dictionary.

If any key provided does not exist, a dictionary containing the remaining keys is dynamically created and set to the required value.

Parameters:
  • dct (dict) – the dictionary to set the value of.
  • value – the value to set. Can be any valid type.
  • *keys – each additional argument corresponds to a nested key.
__weakref__

list of weak references to the object (if defined)

static safe_get(dct, *keys)[source]

Safely return value from a nested dictionary.

If any key provided does not exist, an empty dictionary is returned.

Parameters:
  • dct (dict) – the dictionary to set the value of.
  • *keys – each additional argument corresponds to a nested key.
Returns:

value corresponding to dct[keys[0]][keys[1]] etc.