qcodes.configuration¶

Classes:

`Config`([path])	QCoDeS config system
`DotDict`([value])	Wrapper dict that allows to get dotted attributes

class qcodes.configuration.Config(path: str | None = None)[source]¶

Bases: object

QCoDeS config system

Start with sane defaults, which you can’t change, and then customize your experience using files that update the configuration.

Parameters:: path – Optional path to directory containing a qcodesrc.json config file

Attributes:

`config_file_name`	Name of config file
`schema_file_name`	Name of schema file
`default_file_name`	Filename of default config
`current_config_path`	Path of the last loaded config file
`schema_default_file_name`	Filename of default schema
`home_file_name`	Filename of home config
`schema_home_file_name`	Filename of home schema
`env_file_name`	Filename of env config
`schema_env_file_name`	Filename of env schema
`cwd_file_name`	Filename of cwd config
`schema_cwd_file_name`	Filename of cwd schema
`current_schema`	Validators and descriptions of config values
`current_config`	Valid config values
`defaults`	The default configuration
`defaults_schema`	The default schema

Methods:

`load_default`()
`update_config`([path])	Load defaults updates with cwd, env, home and the path specified and validates.
`validate`([json_config, schema, ...])	Validate configuration; if no arguments are passed, the default config is validated against the default schema.
`add`(key, value[, value_type, description, ...])	Add custom config value in place
`load_config`(path)	Load a config JSON file
`save_config`(path)	Save current config to file at given path.
`save_schema`(path)	Save current schema to file at given path.
`save_to_home`()	Save config and schema to files in home dir
`save_to_env`()	Save config and schema to files in path specified in env variable
`save_to_cwd`()	Save config and schema to files in current working dir
`describe`(name)	Describe a configuration entry

config_file_name = 'qcodesrc.json'¶: Name of config file

schema_file_name = 'qcodesrc_schema.json'¶: Name of schema file

default_file_name = '/opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages/qcodes/configuration/qcodesrc.json'¶: Filename of default config

current_config_path = '/opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages/qcodes/configuration/qcodesrc.json'¶: Path of the last loaded config file

schema_default_file_name = '/opt/hostedtoolcache/Python/3.11.11/x64/lib/python3.11/site-packages/qcodes/configuration/qcodesrc_schema.json'¶: Filename of default schema

home_file_name = '/home/runner/qcodesrc.json'¶: Filename of home config

schema_home_file_name = '/home/runner/qcodesrc_schema.json'¶: Filename of home schema

env_file_name = ''¶: Filename of env config

schema_env_file_name = ''¶: Filename of env schema

cwd_file_name = '/home/runner/work/Qcodes/Qcodes/docs/qcodesrc.json'¶: Filename of cwd config

schema_cwd_file_name = '/home/runner/work/Qcodes/Qcodes/docs/qcodesrc_schema.json'¶: Filename of cwd schema

current_schema: DotDict | None = None¶: Validators and descriptions of config values

current_config: DotDict | None = None¶: Valid config values

defaults: DotDict¶: The default configuration

defaults_schema: DotDict¶: The default schema

load_default() → tuple[DotDict, DotDict][source]¶

update_config(path: str | None = None) → dict[str, Any][source]¶

Load defaults updates with cwd, env, home and the path specified and validates. A configuration file must be called qcodesrc.json A schema file must be called qcodesrc_schema.json Configuration files (and their schema) are loaded and updated from the directories in the following order:

default json config file from the repository

user json config in user home directory

user json config in $QCODES_CONFIG

user json config in current working directory

user json file in the path specified

If a key/value is not specified in the user configuration the default is used. Key/value pairs loaded later will take preference over those loaded earlier. Configs are validated after every update. Validation is also performed against a user provided schema if it’s found in the directory.

Parameters:: path – Optional path to directory containing a qcodesrc.json config file

validate(json_config: Mapping[str, Any] | None = None, schema: Mapping[str, Any] | None = None, extra_schema_path: str | None = None) → None[source]¶

Validate configuration; if no arguments are passed, the default config is validated against the default schema. If either json_config or schema is passed the corresponding default is not used.

Parameters:

json_config – json dictionary to validate
schema – schema dictionary
extra_schema_path – schema path that contains extra validators to be added to schema dictionary

add(key: str, value: Any, value_type: str | None = None, description: str | None = None, default: Any | None = None) → None[source]¶

Add custom config value in place

Adds key, value with optional value_type to user config and schema. If value_type is specified then the new value is validated.

Parameters:

key – key to be added under user config
value – value to add to config
value_type – type of value, allowed are string, boolean, integer
description – description of key to add to schema
default – default value, stored only in the schema

Examples

>>> defaults.add("trace_color", "blue", "string", "description")

will update the config:

...
"user": { "trace_color": "blue"}
...

and the schema:

...
"user":{
    "type" : "object",
    "description": "controls user settings of qcodes"
    "properties" : {
                "trace_color": {
                "description" : "description",
                "type": "string"
                }
        }
}
...

Todo

Add enum support for value_type
finish _diffing

static load_config(path: str) → DotDict[source]¶

Load a config JSON file

Parameters:: path – path to the config file
Returns:: a dot accessible dictionary config object
Raises:: FileNotFoundError – if config is missing

save_config(path: str) → None[source]¶

Save current config to file at given path.

Parameters:: path – path of new file

save_schema(path: str) → None[source]¶

Save current schema to file at given path.

Parameters:: path – path of new file

save_to_home() → None[source]¶: Save config and schema to files in home dir

save_to_env() → None[source]¶: Save config and schema to files in path specified in env variable

save_to_cwd() → None[source]¶: Save config and schema to files in current working dir

describe(name: str) → str[source]¶

Describe a configuration entry

Parameters:: name – name of entry to describe in ‘dotdict’ notation, e.g. name=”user.scriptfolder”

class qcodes.configuration.DotDict(value: Mapping[str, Any] | None = None)[source]¶

Bases: dict[str, Any]

Wrapper dict that allows to get dotted attributes

Requires keys to be strings.

Methods:

`clear`()
`copy`()
`fromkeys`([value])	Create a new dictionary with keys from iterable and values set to value.
`get`(key[, default])	Return the value for key if key is in the dictionary, else default.
`items`()
`keys`()
`pop`(k[,d])	If the key is not found, return the default if given; otherwise, raise a KeyError.
`popitem`()	Remove and return a (key, value) pair as a 2-tuple.
`setdefault`(key[, default])	Insert key with a value of default if key is not in the dictionary.
`update`([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
`values`()
`__getattr__`(name)	Overwrite `__getattr__` to provide dot access
`__setattr__`(key, value)	Overwrite `__setattr__` to provide dot access

clear() → None. Remove all items from D.¶

copy() → a shallow copy of D¶

fromkeys(value=None, /)¶: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)¶: Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()¶

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)¶

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from dict/iterable E and F.¶: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values¶

__getattr__(name: str) → Any[source]¶: Overwrite __getattr__ to provide dot access

__setattr__(key: str, value: Any) → None[source]¶: Overwrite __setattr__ to provide dot access

qcodes default configuration¶

The following table contains 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	False
		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
	GUID_type	Type of GUID to use. Currently possible to chose between an explicitly assigned ‘Sample identification code’ and a random string as the first part of the GUID.
		type	string
		enum	explicit_sample, random_sample
		default	random_sample
	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
	callback_percent	If user wants to callback a function while loading data, the callback is done every callback_percent
		type	number
		default	5.0
	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. {db_location} is a directory in the same folder as the .db file with a matching name i.e. for ~experiments.db will netcdf files will be exported to ~experiments_db
		type	string
		default	{db_location}
	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_
	export_name_elements	Elements to use in export file name, elements are dataset properties. Names will be formatted like ‘{export_prefix}_{export_name_elements[0]}_{…}.file_extension}’ respecting the order of the elements
		type	array
		default	captured_run_id
			guid
		items	type	string
			enum	captured_run_id, guid, exp_name, sample_name, name, captured_counter
	export_chunked_export_of_large_files_enabled	Should large dataset be exported to netcdf in chuncks and then recombined into one file. This reduces the memory requirements for exporting the dataset but may be slower and fail in some corner cases
		type	boolean
		default	False
	export_chunked_threshold	Estimated size in MB above which the dataset will be exported in chuncks and recombined.
		type	integer
		default	1000
	load_from_exported_file	Flag to load metadata and raw data from exported file of type specified in export_type. If set to true, qcodes will try to import from file first, if it exists.
		type	boolean
		default	False
	in_memory_cache	Should the data be cached in memory as it is measured. Useful to disable for large datasets to save on memory consumption.
		type	boolean
		default	True
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