Configuring QCoDeS

QCoDeS uses a JSON based configuration system. The configuration is modeled after the module structure plus some higher level switches.

Config files

QCoDeS config files are read in the following order:

  • Package defaults

  • User’s home directory

  • QCODES_CONFIG environment variable

  • Current working directory

This means that something specified in your current working directory will overwrite the package defaults.

Config files are backed by a json-schema, meaning that they will be validated before use, and if an error occurs the default settings are kept, and the user is informed.

Note

A change in the configuration requires reimporting the package, or restarting the notebook kernel.

Default config

The following table explains the default configuration of qcodes.

schema for a qcodes config file

type

object

properties

  • core

controls core settings of qcodes

type

object

properties

  • default_fmt

default location formatter used for the legacy dataset

type

string

default

data/{date}/#{counter}_{name}_{time}

  • loglevel

deprecated - use logger.console_level

type

string

enum

CRITICAL, ERROR, WARNING, INFO, DEBUG

default

DEBUG

  • file_loglevel

deprecated - use logger.file_level

type

string

enum

CRITICAL, ERROR, WARNING, INFO, DEBUG

default

INFO

  • register_magic

Register QCoDeS magic when in IPython. Can be set to True, False, or a list of magic commands to be registered

default

True

anyOf

type

boolean

type

array

  • import_legacy_api

Import the legacy api in main qcodes namespace

type

boolean

default

False

  • db_debug

Use debugging mode in sqlite

type

boolean

default

False

  • db_location

location of the database

type

string

default

./experiments.db

  • logger

controls all settings related to the logging module qcodes.utils.logger.

type

object

properties

  • start_logging_on_import

whether to call start_all_logging on qcodes import time. Valid values are ‘always’, ‘never’, ‘if_telemetry_set_up’.

type

string

enum

always, never, if_telemetry_set_up

default

if_telemetry_set_up

  • console_level

control logging level of console output

type

string

enum

CRITICAL, ERROR, WARNING, INFO, DEBUG

default

DEBUG

  • file_level

control logging level of file output.

type

string

enum

CRITICAL, ERROR, WARNING, INFO, DEBUG

default

INFO

  • logger_levels

type

object

default

pyvisa

INFO

additionalProperties

type

string

  • subscription

Controls how subscriptions to the dataset, for e.g. live plotting, are handled. Here subscribers can be registered so that they will be available through DataSet.subscribe_from_config. Additionally default subscribers for every DataSet that is generated by the Measurement object can be defined.

type

object

properties

  • subscribers

List of available pre-configured subscribers. The names of the subscriber entries are available as arguments of the DataSet.subscribe_from_config method and can be used in this conifg in the subscription.default_subscribers property.

type

object

  • gui

controls legacy gui of qcodes

type

object

properties

  • notebook

Use notebook frontend

type

boolean

default

True

  • plotlib

Plotting library set to null to run without plotting

type

string / null

enum

QT, matplotlib, all, None

default

null

  • pyqtmaxplots

Maximum number of PyQtPlots to automatically keep in memory

type

integer

default

100

  • plotting

controls plotting functions i.e. plot_dataset

type

object

properties

  • default_color_map

Default colormap to use for plot_dataset.

type

string

default

viridis

  • rasterize_threshold

Scatter plots and heatmaps with more than this number of points will have their data rasterized by default when saved in vector format

type

integer

default

5000

  • auto_color_scale

Control of a auto color scale, that scales such that potential outliers of the data will not be included in the min/max range.

type

object

properties

  • enabled

Enable automatic color scaling

type

boolean

default

False

  • cutoff_percentile

Upper and lower percentage of datapoints that may maximally be discarded by the auto color scale. For example for [1,1] the auto color scale will in a set of 10 0000 points not clip more than the 100 points of lowest and highest value.

type

array

default

0.5

0.5

items

type

number

type

number

  • color_over

Matplotlib color representing the datapoints clipped by the upper limit

default

white

  • color_under

Matplotlib color representing the datapoints clipped by the lower limit

default

grey

  • user

Optional feature for qdev-wrappers package: controls user settings of qcodes

type

object

properties

  • scriptfolder

Location of scripts for general experiments

type

string

default

/

  • mainfolder

Location of experiments

type

string

default

  • station

Settings for QCoDeS Station.

type

object

properties

  • enable_forced_reconnect

If set to true, on instantiation of an existing instrument from station configuration, the existing instrument instance will be closed.

type

boolean

default

False

  • default_folder

Default folder where to look for a YAML station configuration file

type

string / null

default

null

  • default_file

Default file name, specifying a YAML station configuration file to load, when none is specified. The path can be absolute, relative to the current folder or relative to the default folder as specified in the qcodes config.

type

string / null

default

null

  • use_monitor

Update the monitor based on the monitor attribute specified in the instruments section of the station config yaml file.

type

boolean

default

False

  • GUID_components

Identifiers for creating a GUID per run in the dataset database.

type

object

properties

  • location

Geographical location code

type

integer

default

0

  • work_station

Work station identification code

type

integer

default

0

  • sample

Sample identification code

type

integer

default

0

  • dataset

Settings related to the DataSet and Measurement Context manager

type

object

properties

  • write_in_background

Should the data be written from a background thread

type

boolean

default

False

  • write_period

How often should data be written to disk (s)

type

number

default

5.0

  • use_threads

Should instruments be addresesed in parallel for process_params_meas() in doNd measurement

type

boolean

default

False

  • dond_plot

Should dond functions automatically open a plot after the measurement completes

type

boolean

default

False

  • dond_show_progress

Should dond functions show a progress bar during the measurement

type

boolean

default

False

  • export_automatic

Should the data be exported automatically when a measurement is completed? If this is set ‘export_type’ must be set to a non null value.

type

boolean

default

False

  • export_type

Data export type for exporting datasets to disk after a measurement finishes. Does not export if set to null (default). Currently supported type(s): netcdf, csv

type

string / null

enum

netcdf, csv, None

default

null

  • export_path

Data export path for exporting datasets to disk after a measurement finishes. Only activated if export_type is set

type

string

default

~

  • export_prefix

Prefix to add to filename for exporting datasets to disk after a measurement finishes. Only activated if export_type is set

type

string

default

qcodes_

  • telemetry

type

object

properties

  • enabled

Whether or not to enable sending telemetry data to the developers of QCoDeS (or elsewhere)

type

boolean

default

False

  • instrumentation_key

A valid Azure Application Insights instrumentation key

type

string

default

00000000-0000-0000-0000-000000000000

Using the config

QCoDeS exposes the default values in the module namespace as config

>>> import qcodes
>>> qcodes.config
Current values:
{'core': {'default_fmt': 'data/{date}/#{counter}_{name}_{time}', 'register_magic': True, 'db_location': '~/experiments.db', 'db_debug': False, 'loglevel': 'WARNING', 'file_loglevel': 'INFO'}}
Current paths:
['c:\\users\\jenielse\\source\\repos\\qcodes\\qcodes\\configuration\\qcodesrc.json', 'C:\\Users\\jenielse\\qcodesrc.json']
<qcodes.configuration.config.Config object at 0x0000029B9D549A90>

Values can be retrieved by key :

>>> qcodes.config['user']
{}

Values can be retrieved by dotted keys:

>>> qcodes.config['gui.notebook']
True

Values can be described:

>>> qcodes.config.describe("gui")
"controls gui of qcodes.\n Current value: {'notebook': True, 'plotlib': 'matplotlib'}. Type: object. Default: Not defined."

qcodes.config looks like a dictionary (and supports all the dictionary operations you can think about), but it has some additional helpers.

Updating a value

qcodes.config lets you insert a new value which gets stuffed in the “user” part of the config

>>> qcodes.config.add("foo", "bar")
>>> qcodes.config["user.foo"]
'bar'

And also pass a type validator and a description:

>>> qcodes.config.add("foo", "bar", "string", "finds majorana")
>>> qcodes.config.describe("user.foo")
'finds majorana.
Current value: bar. Type: string. Default: Not defined.'

Saving

If you made modifications you may want also to save them. F.ex. this

>>> qcodes.config.save_to_home()

Will do what you think, i.e. saving to your home directory. There is the possibility to save to env variable, and current working directory.

More

For a overview of the API, read this: qcodes.configuration .

Note

for now are supported all the JSON types MINUS enum

Todo

add GUI for creating config, explain saving (note on config loaded at module import so no effect if changed at runtime).