qcodes.dataset

The dataset module contains code related to storage and retrieval of data to and from disk

Classes:

AbstractSweep()

Abstract sweep class that defines an interface for concrete sweep classes.

ArraySweep(param, array[, delay, post_actions])

Sweep the values of a given array.

DataSetProtocol(*args, **kwargs)

DataSetType(value)

An enumeration.

LinSweep(param, start, stop, num_points[, ...])

Linear sweep.

LogSweep(param, start, stop, num_points[, ...])

Logarithmic sweep.

Measurement([exp, station, name])

Measurement procedure container.

ParamSpec(name, paramtype[, label, unit, ...])

param name

name of the parameter

SQLiteSettings()

Class that holds the machine's sqlite options.

SequentialParamsCaller(*param_meas)

ThreadPoolParamsCaller(*param_meas[, ...])

Context manager for calling given parameters in a thread pool.

Functions:

call_params_threaded(param_meas)

Function to create threads per instrument for the given set of measurement parameters.

do0d(*param_meas[, write_period, ...])

Perform a measurement of a single parameter.

do1d(param_set, start, stop, num_points, ...)

Perform a 1D scan of param_set from start to stop in num_points measuring param_meas at each step.

do2d(param_set1, start1, stop1, num_points1, ...)

Perform a 1D scan of param_set1 from start1 to stop1 in num_points1 and param_set2 from start2 to stop2 in num_points2 measuring param_meas at each step.

dond(*params[, write_period, ...])

Perform n-dimentional scan from slowest (first) to the fastest (last), to measure m measurement parameters.

experiments([conn])

List all the experiments in the container (database file from config)

extract_runs_into_db(source_db_path, ...[, ...])

Extract a selection of runs into another DB file.

get_default_experiment_id(conn)

Returns the latest created/ loaded experiment's exp_id as the default experiment.

get_guids_by_run_spec(*[, captured_run_id, ...])

Get a list of matching guids from one or more pieces of runs specification.

import_dat_file(location[, exp])

This imports a QCoDeS legacy qcodes.data.data_set.DataSet into the database.

initialise_database([journal_mode])

Initialise a database in the location specified by the config object and set atomic commit and rollback mode of the db.

initialise_or_create_database_at(...[, ...])

This function sets up QCoDeS to refer to the given database file.

initialised_database_at(db_file_with_abs_path)

Initializes or creates a database and restores the 'db_location' afterwards.

load_by_counter(counter, exp_id[, conn])

Load a dataset given its counter in a given experiment

load_by_guid(guid[, conn])

Load a dataset by its GUID

load_by_id(run_id[, conn])

Load a dataset by run id

load_by_run_spec(*[, captured_run_id, ...])

Load a run from one or more pieces of runs specification.

load_experiment(exp_id[, conn])

Load experiment with the specified id (from database file from config)

load_experiment_by_name(name[, sample, ...])

Try to load experiment with the specified name.

load_from_netcdf(path[, path_to_db])

Create a in memory dataset from a netcdf file.

load_last_experiment()

Load last experiment (from database file from config)

load_or_create_experiment(experiment_name[, ...])

Find and return an experiment with the given name and sample name, or create one if not found.

new_data_set(name[, exp_id, specs, values, ...])

Create a new dataset in the currently active/selected database.

new_experiment(name, sample_name[, ...])

Create a new experiment (in the database file from config)

plot_by_id(run_id[, axes, colorbars, ...])

Construct all plots for a given run_id.

plot_dataset(dataset[, axes, colorbars, ...])

Construct all plots for a given dataset

reset_default_experiment_id([conn])

Resets the default experiment id to to the last experiment in the db.

class qcodes.dataset.AbstractSweep[source]

Bases: ABC

Abstract sweep class that defines an interface for concrete sweep classes.

Methods:

get_setpoints()

Returns an array of setpoint values for this sweep.

Attributes:

param

Returns the Qcodes sweep parameter.

delay

Delay between two consecutive sweep points.

num_points

Number of sweep points.

post_actions

actions to be performed after setting param to its setpoint.

abstract get_setpoints() ndarray[source]

Returns an array of setpoint values for this sweep.

abstract property param: qcodes.parameters.parameter_base.ParameterBase

Returns the Qcodes sweep parameter.

abstract property delay: float

Delay between two consecutive sweep points.

abstract property num_points: int

Number of sweep points.

abstract property post_actions: Sequence[Callable[[], None]]

actions to be performed after setting param to its setpoint.

class qcodes.dataset.ArraySweep(param: ParameterBase, array: Union[Sequence[float], ndarray], delay: float = 0, post_actions: Sequence[Callable[[], None]] = ())[source]

Bases: AbstractSweep

Sweep the values of a given array.

Parameters
  • param – Qcodes parameter for sweep.

  • array – array with values to sweep.

  • delay – Time in seconds between two consecutive sweep points.

  • post_actions – Actions to do after each sweep point.

Methods:

get_setpoints()

Returns an array of setpoint values for this sweep.

Attributes:

param

Returns the Qcodes sweep parameter.

delay

Delay between two consecutive sweep points.

num_points

Number of sweep points.

post_actions

actions to be performed after setting param to its setpoint.

get_setpoints() ndarray[source]

Returns an array of setpoint values for this sweep.

property param: qcodes.parameters.parameter_base.ParameterBase

Returns the Qcodes sweep parameter.

property delay: float

Delay between two consecutive sweep points.

property num_points: int

Number of sweep points.

property post_actions: Sequence[Callable[[], None]]

actions to be performed after setting param to its setpoint.

class qcodes.dataset.DataSetProtocol(*args, **kwargs)[source]

Bases: Protocol, Sized

Attributes:

persistent_traits

pristine

running

completed

run_id

captured_run_id

counter

captured_counter

guid

number_of_results

name

exp_name

exp_id

sample_name

run_timestamp_raw

completed_timestamp_raw

snapshot

metadata

path_to_db

paramspecs

description

parent_dataset_links

export_info

cache

dependent_parameters

Methods:

prepare(*, snapshot, interdeps[, shapes, ...])

mark_completed()

run_timestamp([fmt])

completed_timestamp([fmt])

add_snapshot(snapshot[, overwrite])

add_metadata(tag, metadata)

export([export_type, path, prefix])

get_parameter_data(*params[, start, end])

get_parameters()

to_xarray_dataarray_dict(*params[, start, end])

to_xarray_dataset(*params[, start, end])

to_pandas_dataframe_dict(*params[, start, end])

to_pandas_dataframe(*params[, start, end])

persistent_traits: Tuple[str, ...] = ('name', 'guid', 'number_of_results', 'exp_name', 'sample_name', 'completed', 'snapshot', 'run_timestamp_raw', 'description', 'completed_timestamp_raw', 'metadata', 'parent_dataset_links', 'captured_run_id', 'captured_counter')
prepare(*, snapshot: Mapping[Any, Any], interdeps: InterDependencies_, shapes: Optional[Dict[str, Tuple[int, ...]]] = None, parent_datasets: Sequence[Mapping[Any, Any]] = (), write_in_background: bool = False) None[source]
property pristine: bool
property running: bool
property completed: bool
mark_completed() None[source]
property run_id: int
property captured_run_id: int
property counter: int
property captured_counter: int
property guid: str
property number_of_results: int
property name: str
property exp_name: str
property exp_id: int
property sample_name: str
run_timestamp(fmt: str = '%Y-%m-%d %H:%M:%S') Optional[str][source]
property run_timestamp_raw: Optional[float]
completed_timestamp(fmt: str = '%Y-%m-%d %H:%M:%S') Optional[str][source]
property completed_timestamp_raw: Optional[float]
property snapshot: Optional[Dict[str, Any]]
add_snapshot(snapshot: str, overwrite: bool = False) None[source]
add_metadata(tag: str, metadata: Any) None[source]
property metadata: Dict[str, Any]
property path_to_db: Optional[str]
property paramspecs: Dict[str, qcodes.dataset.descriptions.param_spec.ParamSpec]
property description: qcodes.dataset.descriptions.rundescriber.RunDescriber
export(export_type: Optional[Union[DataExportType, str]] = None, path: Optional[str] = None, prefix: Optional[str] = None) None[source]
property export_info: qcodes.dataset.exporters.export_info.ExportInfo
property cache: DataSetCache[DataSetProtocol]
get_parameter_data(*params: Union[str, ParamSpec, ParameterBase], start: Optional[int] = None, end: Optional[int] = None) ParameterData[source]
get_parameters() List[ParamSpec][source]
property dependent_parameters: Tuple[qcodes.dataset.descriptions.param_spec.ParamSpecBase, ...]
to_xarray_dataarray_dict(*params: Union[str, ParamSpec, ParameterBase], start: Optional[int] = None, end: Optional[int] = None) Dict[str, xr.DataArray][source]
to_xarray_dataset(*params: Union[str, ParamSpec, ParameterBase], start: Optional[int] = None, end: Optional[int] = None) xr.Dataset[source]
to_pandas_dataframe_dict(*params: Union[str, ParamSpec, ParameterBase], start: Optional[int] = None, end: Optional[int] = None) Dict[str, pd.DataFrame][source]
to_pandas_dataframe(*params: Union[str, ParamSpec, ParameterBase], start: Optional[int] = None, end: Optional[int] = None) pd.DataFrame[source]
class qcodes.dataset.DataSetType(value)[source]

Bases: str, Enum

An enumeration.

Attributes:

DataSet

DataSetInMem

DataSet = 'DataSet'
DataSetInMem = 'DataSetInMem'
class qcodes.dataset.LinSweep(param: ParameterBase, start: float, stop: float, num_points: int, delay: float = 0, post_actions: Sequence[Callable[[], None]] = ())[source]

Bases: AbstractSweep

Linear sweep.

Parameters
  • param – Qcodes parameter to sweep.

  • start – Sweep start value.

  • stop – Sweep end value.

  • num_points – Number of sweep points.

  • delay – Time in seconds between two consequtive sweep points

Methods:

get_setpoints()

Linear (evenly spaced) numpy array for supplied start, stop and num_points.

Attributes:

param

Returns the Qcodes sweep parameter.

delay

Delay between two consecutive sweep points.

num_points

Number of sweep points.

post_actions

actions to be performed after setting param to its setpoint.

get_setpoints() ndarray[source]

Linear (evenly spaced) numpy array for supplied start, stop and num_points.

property param: qcodes.parameters.parameter_base.ParameterBase

Returns the Qcodes sweep parameter.

property delay: float

Delay between two consecutive sweep points.

property num_points: int

Number of sweep points.

property post_actions: Sequence[Callable[[], None]]

actions to be performed after setting param to its setpoint.

class qcodes.dataset.LogSweep(param: ParameterBase, start: float, stop: float, num_points: int, delay: float = 0, post_actions: Sequence[Callable[[], None]] = ())[source]

Bases: AbstractSweep

Logarithmic sweep.

Parameters
  • param – Qcodes parameter for sweep.

  • start – Sweep start value.

  • stop – Sweep end value.

  • num_points – Number of sweep points.

  • delay – Time in seconds between two consequtive sweep points.

Methods:

get_setpoints()

Logarithmically spaced numpy array for supplied start, stop and num_points.

Attributes:

param

Returns the Qcodes sweep parameter.

delay

Delay between two consecutive sweep points.

num_points

Number of sweep points.

post_actions

actions to be performed after setting param to its setpoint.

get_setpoints() ndarray[source]

Logarithmically spaced numpy array for supplied start, stop and num_points.

property param: qcodes.parameters.parameter_base.ParameterBase

Returns the Qcodes sweep parameter.

property delay: float

Delay between two consecutive sweep points.

property num_points: int

Number of sweep points.

property post_actions: Sequence[Callable[[], None]]

actions to be performed after setting param to its setpoint.

class qcodes.dataset.Measurement(exp: Optional[Experiment] = None, station: Optional[Station] = None, name: str = '')[source]

Bases: object

Measurement procedure container. Note that multiple measurement instances cannot be nested.

Parameters
  • exp – Specify the experiment to use. If not given the default one is used. The default experiment is the latest one created.

  • station – The QCoDeS station to snapshot. If not given, the default one is used.

  • name – Name of the measurement. This will be passed down to the dataset produced by the measurement. If not given, a default value of ‘results’ is used for the dataset.

Attributes:

parameters

write_period

Methods:

register_parent(parent, link_type[, description])

Register a parent for the outcome of this measurement

register_parameter(parameter[, setpoints, ...])

Add QCoDeS Parameter to the dataset produced by running this measurement.

register_custom_parameter(name[, label, ...])

Register a custom parameter with this measurement

unregister_parameter(parameter)

Remove a custom/QCoDeS parameter from the dataset produced by running this measurement

add_before_run(func, args)

Add an action to be performed before the measurement.

add_after_run(func, args)

Add an action to be performed after the measurement.

add_subscriber(func, state)

Add a subscriber to the dataset of the measurement.

set_shapes(shapes)

Set the shapes of the data to be recorded in this measurement.

run([write_in_background, in_memory_cache, ...])

Returns the context manager for the experimental run

property parameters: Dict[str, qcodes.dataset.descriptions.param_spec.ParamSpecBase]
property write_period: float
register_parent(parent: DataSetProtocol, link_type: str, description: str = '') T[source]

Register a parent for the outcome of this measurement

Parameters
  • parent – The parent dataset

  • link_type – A name for the type of parent-child link

  • description – A free-text description of the relationship

register_parameter(parameter: ParameterBase, setpoints: Optional[Sequence[Union[str, ParameterBase]]] = None, basis: Optional[Sequence[Union[str, ParameterBase]]] = None, paramtype: Optional[str] = None) T[source]

Add QCoDeS Parameter to the dataset produced by running this measurement.

Parameters
  • parameter – The parameter to add

  • setpoints – The Parameter representing the setpoints for this parameter. If this parameter is a setpoint, it should be left blank

  • basis – The parameters that this parameter is inferred from. If this parameter is not inferred from any other parameters, this should be left blank.

  • paramtype – Type of the parameter, i.e. the SQL storage class, If None the paramtype will be inferred from the parameter type and the validator of the supplied parameter.

register_custom_parameter(name: str, label: Optional[str] = None, unit: Optional[str] = None, basis: Optional[Sequence[Union[str, ParameterBase]]] = None, setpoints: Optional[Sequence[Union[str, ParameterBase]]] = None, paramtype: str = 'numeric') T[source]

Register a custom parameter with this measurement

Parameters
  • name – The name that this parameter will have in the dataset. Must be unique (will overwrite an existing parameter with the same name!)

  • label – The label

  • unit – The unit

  • basis – A list of either QCoDeS Parameters or the names of parameters already registered in the measurement that this parameter is inferred from

  • setpoints – A list of either QCoDeS Parameters or the names of of parameters already registered in the measurement that are the setpoints of this parameter

  • paramtype – Type of the parameter, i.e. the SQL storage class

unregister_parameter(parameter: Sequence[Union[str, ParameterBase]]) None[source]

Remove a custom/QCoDeS parameter from the dataset produced by running this measurement

add_before_run(func: Callable[[...], Any], args: Sequence[Any]) T[source]

Add an action to be performed before the measurement.

Parameters
  • func – Function to be performed

  • args – The arguments to said function

add_after_run(func: Callable[[...], Any], args: Sequence[Any]) T[source]

Add an action to be performed after the measurement.

Parameters
  • func – Function to be performed

  • args – The arguments to said function

add_subscriber(func: Callable[[...], Any], state: Union[MutableSequence[Any], MutableMapping[Any, Any]]) T[source]

Add a subscriber to the dataset of the measurement.

Parameters
  • func – A function taking three positional arguments: a list of tuples of parameter values, an integer, a mutable variable (list or dict) to hold state/writes updates to.

  • state – The variable to hold the state.

set_shapes(shapes: Optional[Dict[str, Tuple[int, ...]]]) None[source]

Set the shapes of the data to be recorded in this measurement.

Parameters

shapes – Dictionary from names of dependent parameters to a tuple of integers describing the shape of the measurement.

run(write_in_background: Optional[bool] = None, in_memory_cache: bool = True, dataset_class: DataSetType = DataSetType.DataSet) Runner[source]

Returns the context manager for the experimental run

Parameters
  • write_in_background – if True, results that will be added within the context manager with DataSaver.add_result will be stored in background, without blocking the main thread that is executing the context manager. By default the setting for write in background will be read from the qcodesrc.json config file.

  • in_memory_cache – Should measured data be keep in memory and available as part of the dataset.cache object.

  • dataset_class – Enum representing the Class used to store data with.

class qcodes.dataset.ParamSpec(name: str, paramtype: str, label: Optional[str] = None, unit: Optional[str] = None, inferred_from: Optional[Sequence[Union[ParamSpec, str]]] = None, depends_on: Optional[Sequence[Union[ParamSpec, str]]] = None, **metadata: Any)[source]

Bases: ParamSpecBase

Parameters
  • name – name of the parameter

  • paramtype – type of the parameter, i.e. the SQL storage class

  • label – label of the parameter

  • inferred_from – the parameters that this parameter is inferred from

  • depends_on – the parameters that this parameter depends on

Attributes:

inferred_from_

depends_on_

inferred_from

depends_on

allowed_types

Methods:

copy()

Make a copy of self

__hash__()

Allow ParamSpecs in data structures that use hashing (i.e.

base_version()

Return a ParamSpecBase object with the same name, paramtype, label and unit as this ParamSpec

sql_repr()

property inferred_from_: List[str]
property depends_on_: List[str]
property inferred_from: str
property depends_on: str
copy() ParamSpec[source]

Make a copy of self

__hash__() int[source]

Allow ParamSpecs in data structures that use hashing (i.e. sets)

base_version() ParamSpecBase[source]

Return a ParamSpecBase object with the same name, paramtype, label and unit as this ParamSpec

allowed_types = ['array', 'numeric', 'text', 'complex']
sql_repr() str
class qcodes.dataset.SQLiteSettings[source]

Bases: object

Class that holds the machine’s sqlite options.

Note that the settings are not dynamically updated, so changes during runtime must be updated manually. But you probably should not be changing these settings dynamically in the first place.

Attributes:

limits

settings

limits = {'MAX_ATTACHED': 10, 'MAX_COLUMN': 2000, 'MAX_COMPOUND_SELECT': 500, 'MAX_EXPR_DEPTH': 1000, 'MAX_FUNCTION_ARG': 100, 'MAX_LENGTH': 1000000000, 'MAX_LIKE_PATTERN_LENGTH': 50000, 'MAX_PAGE_COUNT': 1073741823, 'MAX_SQL_LENGTH': 1000000, 'MAX_VARIABLE_NUMBER': 250000}
settings = {'COMPILER': 'gcc-9.4.0', 'ENABLE_COLUMN_METADATA': True, 'ENABLE_DBSTAT_VTAB': True, 'ENABLE_FTS3': True, 'ENABLE_FTS3_PARENTHESIS': True, 'ENABLE_FTS3_TOKENIZER': True, 'ENABLE_FTS4': True, 'ENABLE_FTS5': True, 'ENABLE_JSON1': True, 'ENABLE_LOAD_EXTENSION': True, 'ENABLE_PREUPDATE_HOOK': True, 'ENABLE_RTREE': True, 'ENABLE_SESSION': True, 'ENABLE_STMTVTAB': True, 'ENABLE_UNLOCK_NOTIFY': True, 'ENABLE_UPDATE_DELETE_LIMIT': True, 'HAVE_ISNAN': True, 'LIKE_DOESNT_MATCH_BLOBS': True, 'MAX_SCHEMA_RETRY': 25, 'OMIT_LOOKASIDE': True, 'SECURE_DELETE': True, 'SOUNDEX': True, 'TEMP_STORE': 1, 'THREADSAFE': 1, 'USE_URI': True, 'VERSION': '3.31.1'}
class qcodes.dataset.SequentialParamsCaller(*param_meas: Union[ParameterBase, Callable[[], None]])[source]

Bases: _ParamsCallerProtocol

class qcodes.dataset.ThreadPoolParamsCaller(*param_meas: Union[ParameterBase, Callable[[], None]], max_workers: Optional[int] = None)[source]

Bases: _ParamsCallerProtocol

Context manager for calling given parameters in a thread pool. Note that parameters that have the same underlying instrument will be called in the same thread.

Usage:

...
with ThreadPoolParamsCaller(p1, p2, ...) as pool_caller:
    ...
    output = pool_caller()
    ...
    # Output can be passed directly into DataSaver.add_result:
    # datasaver.add_result(*output)
    ...
...
Parameters
  • param_meas – parameter or a callable without arguments

  • max_workers – number of worker threads to create in the pool; if None, the number of worker threads will be equal to the number of unique “underlying instruments”

Methods:

__call__()

Call parameters in the thread pool and return (param, value) tuples.

__call__() List[res_type][source]

Call parameters in the thread pool and return (param, value) tuples.

qcodes.dataset.call_params_threaded(param_meas: Sequence[Union[ParameterBase, Callable[[], None]]]) List[res_type][source]

Function to create threads per instrument for the given set of measurement parameters.

Parameters

param_meas – a Sequence of measurement parameters

qcodes.dataset.do0d(*param_meas: Union[ParameterBase, Callable[[], None]], write_period: Optional[float] = None, measurement_name: str = '', exp: Optional[Experiment] = None, do_plot: Optional[bool] = None, use_threads: Optional[bool] = None, log_info: Optional[str] = None) Tuple[DataSetProtocol, List[Axes], List[Optional[Colorbar]]][source]

Perform a measurement of a single parameter. This is probably most useful for an ArrayParameter that already returns an array of data points

Parameters
  • *param_meas – Parameter(s) to measure at each step or functions that will be called at each step. The function should take no arguments. The parameters and functions are called in the order they are supplied.

  • write_period – The time after which the data is actually written to the database.

  • measurement_name – Name of the measurement. This will be passed down to the dataset produced by the measurement. If not given, a default value of ‘results’ is used for the dataset.

  • exp – The experiment to use for this measurement.

  • do_plot – should png and pdf versions of the images be saved after the run. If None the setting will be read from qcodesrc.json

  • use_threads – If True measurements from each instrument will be done on separate threads. If you are measuring from several instruments this may give a significant speedup.

  • log_info – Message that is logged during the measurement. If None a default message is used.

Returns

The QCoDeS dataset.

qcodes.dataset.do1d(param_set: ParameterBase, start: float, stop: float, num_points: int, delay: float, *param_meas: Union[ParameterBase, Callable[[], None]], enter_actions: Sequence[Callable[[], None]] = (), exit_actions: Sequence[Callable[[], None]] = (), write_period: Optional[float] = None, measurement_name: str = '', exp: Optional[Experiment] = None, do_plot: Optional[bool] = None, use_threads: Optional[bool] = None, additional_setpoints: Sequence[ParameterBase] = (), show_progress: None = None, log_info: Optional[str] = None, break_condition: Optional[Callable[[], bool]] = None) Tuple[DataSetProtocol, List[Axes], List[Optional[Colorbar]]][source]

Perform a 1D scan of param_set from start to stop in num_points measuring param_meas at each step. In case param_meas is an ArrayParameter this is effectively a 2d scan.

Parameters
  • param_set – The QCoDeS parameter to sweep over

  • start – Starting point of sweep

  • stop – End point of sweep

  • num_points – Number of points in sweep

  • delay – Delay after setting parameter before measurement is performed

  • param_meas – Parameter(s) to measure at each step or functions that will be called at each step. The function should take no arguments. The parameters and functions are called in the order they are supplied.

  • enter_actions – A list of functions taking no arguments that will be called before the measurements start

  • exit_actions – A list of functions taking no arguments that will be called after the measurements ends

  • write_period – The time after which the data is actually written to the database.

  • additional_setpoints – A list of setpoint parameters to be registered in the measurement but not scanned.

  • measurement_name – Name of the measurement. This will be passed down to the dataset produced by the measurement. If not given, a default value of ‘results’ is used for the dataset.

  • exp – The experiment to use for this measurement.

  • do_plot – should png and pdf versions of the images be saved after the run. If None the setting will be read from qcodesrc.json

  • use_threads – If True measurements from each instrument will be done on separate threads. If you are measuring from several instruments this may give a significant speedup.

  • show_progress – should a progress bar be displayed during the measurement. If None the setting will be read from qcodesrc.json

  • log_info – Message that is logged during the measurement. If None a default message is used.

  • break_condition – Callable that takes no arguments. If returned True, measurement is interrupted.

Returns

The QCoDeS dataset.

qcodes.dataset.do2d(param_set1: ParameterBase, start1: float, stop1: float, num_points1: int, delay1: float, param_set2: ParameterBase, start2: float, stop2: float, num_points2: int, delay2: float, *param_meas: Union[ParameterBase, Callable[[], None]], set_before_sweep: Optional[bool] = True, enter_actions: Sequence[Callable[[], None]] = (), exit_actions: Sequence[Callable[[], None]] = (), before_inner_actions: Sequence[Callable[[], None]] = (), after_inner_actions: Sequence[Callable[[], None]] = (), write_period: Optional[float] = None, measurement_name: str = '', exp: Optional[Experiment] = None, flush_columns: bool = False, do_plot: Optional[bool] = None, use_threads: Optional[bool] = None, additional_setpoints: Sequence[ParameterBase] = (), show_progress: None = None, log_info: Optional[str] = None, break_condition: Optional[Callable[[], bool]] = None) Tuple[DataSetProtocol, List[Axes], List[Optional[Colorbar]]][source]

Perform a 1D scan of param_set1 from start1 to stop1 in num_points1 and param_set2 from start2 to stop2 in num_points2 measuring param_meas at each step.

Parameters
  • param_set1 – The QCoDeS parameter to sweep over in the outer loop

  • start1 – Starting point of sweep in outer loop

  • stop1 – End point of sweep in the outer loop

  • num_points1 – Number of points to measure in the outer loop

  • delay1 – Delay after setting parameter in the outer loop

  • param_set2 – The QCoDeS parameter to sweep over in the inner loop

  • start2 – Starting point of sweep in inner loop

  • stop2 – End point of sweep in the inner loop

  • num_points2 – Number of points to measure in the inner loop

  • delay2 – Delay after setting parameter before measurement is performed

  • param_meas – Parameter(s) to measure at each step or functions that will be called at each step. The function should take no arguments. The parameters and functions are called in the order they are supplied.

  • set_before_sweep – if True the outer parameter is set to its first value before the inner parameter is swept to its next value.

  • enter_actions – A list of functions taking no arguments that will be called before the measurements start

  • exit_actions – A list of functions taking no arguments that will be called after the measurements ends

  • before_inner_actions – Actions executed before each run of the inner loop

  • after_inner_actions – Actions executed after each run of the inner loop

  • write_period – The time after which the data is actually written to the database.

  • measurement_name – Name of the measurement. This will be passed down to the dataset produced by the measurement. If not given, a default value of ‘results’ is used for the dataset.

  • exp – The experiment to use for this measurement.

  • flush_columns – The data is written after a column is finished independent of the passed time and write period.

  • additional_setpoints – A list of setpoint parameters to be registered in the measurement but not scanned.

  • do_plot – should png and pdf versions of the images be saved after the run. If None the setting will be read from qcodesrc.json

  • use_threads – If True measurements from each instrument will be done on separate threads. If you are measuring from several instruments this may give a significant speedup.

  • show_progress – should a progress bar be displayed during the measurement. If None the setting will be read from qcodesrc.json

  • log_info – Message that is logged during the measurement. If None a default message is used.

  • break_condition – Callable that takes no arguments. If returned True, measurement is interrupted.

Returns

The QCoDeS dataset.

qcodes.dataset.dond(*params: Union[AbstractSweep, ParameterBase, Callable[[], None], Sequence[Union[ParameterBase, Callable[[], None]]]], write_period: Optional[float] = None, measurement_name: str = '', exp: Optional[Union[Experiment, Sequence[Experiment]]] = None, enter_actions: Sequence[Callable[[], None]] = (), exit_actions: Sequence[Callable[[], None]] = (), do_plot: Optional[bool] = None, show_progress: Optional[bool] = None, use_threads: Optional[bool] = None, additional_setpoints: Sequence[ParameterBase] = (), log_info: Optional[str] = None, break_condition: Optional[Callable[[], bool]] = None) Union[Tuple[DataSetProtocol, List[Axes], List[Optional[Colorbar]]], Tuple[Tuple[DataSetProtocol, ...], Tuple[List[Axes], ...], Tuple[List[Optional[Colorbar]], ...]]][source]

Perform n-dimentional scan from slowest (first) to the fastest (last), to measure m measurement parameters. The dimensions should be specified as sweep objects, and after them the parameters to measure should be passed.

Parameters
  • params

    Instances of n sweep classes and m measurement parameters, e.g. if linear sweep is considered:

    LinSweep(param_set_1, start_1, stop_1, num_points_1, delay_1), ...,
    LinSweep(param_set_n, start_n, stop_n, num_points_n, delay_n),
    param_meas_1, param_meas_2, ..., param_meas_m
    

    If multiple DataSets creation is needed, measurement parameters should be grouped, so one dataset will be created for each group. e.g.:

    LinSweep(param_set_1, start_1, stop_1, num_points_1, delay_1), ...,
    LinSweep(param_set_n, start_n, stop_n, num_points_n, delay_n),
    [param_meas_1, param_meas_2], ..., [param_meas_m]
    

  • write_period – The time after which the data is actually written to the database.

  • measurement_name – Name of the measurement. This will be passed down to the dataset produced by the measurement. If not given, a default value of ‘results’ is used for the dataset.

  • exp – The experiment to use for this measurement. If you create multiple measurements using groups you may also supply multiple experiments.

  • enter_actions – A list of functions taking no arguments that will be called before the measurements start.

  • exit_actions – A list of functions taking no arguments that will be called after the measurements ends.

  • do_plot – should png and pdf versions of the images be saved and plots are shown after the run. If None the setting will be read from qcodesrc.json

  • show_progress – should a progress bar be displayed during the measurement. If None the setting will be read from qcodesrc.json

  • use_threads – If True, measurements from each instrument will be done on separate threads. If you are measuring from several instruments this may give a significant speedup.

  • additional_setpoints – A list of setpoint parameters to be registered in the measurement but not scanned/swept-over.

  • log_info – Message that is logged during the measurement. If None a default message is used.

  • break_condition – Callable that takes no arguments. If returned True, measurement is interrupted.

Returns

A tuple of QCoDeS DataSet, Matplotlib axis, Matplotlib colorbar. If more than one group of measurement parameters is supplied, the output will be a tuple of tuple(QCoDeS DataSet), tuple(Matplotlib axis), tuple(Matplotlib colorbar), in which each element of each sub-tuple belongs to one group, and the order of elements is the order of the supplied groups.

qcodes.dataset.experiments(conn: Optional[ConnectionPlus] = None) List[Experiment][source]

List all the experiments in the container (database file from config)

Parameters

conn – connection to the database. If not supplied, a new connection to the DB file specified in the config is made

Returns

All the experiments in the container

qcodes.dataset.extract_runs_into_db(source_db_path: str, target_db_path: str, *run_ids: int, upgrade_source_db: bool = False, upgrade_target_db: bool = False) None[source]

Extract a selection of runs into another DB file. All runs must come from the same experiment. They will be added to an experiment with the same name and sample_name in the target db. If such an experiment does not exist, it will be created.

Parameters
  • source_db_path – Path to the source DB file

  • target_db_path – Path to the target DB file. The target DB file will be created if it does not exist.

  • run_ids – The run_id’s of the runs to copy into the target DB file

  • upgrade_source_db – If the source DB is found to be in a version that is not the newest, should it be upgraded?

  • upgrade_target_db – If the target DB is found to be in a version that is not the newest, should it be upgraded?

qcodes.dataset.get_default_experiment_id(conn: ConnectionPlus) int[source]

Returns the latest created/ loaded experiment’s exp_id as the default experiment. If it is not set the maximum exp_id returned as the default. If no experiment is found in the database, a ValueError is raised.

Parameters

conn – Open connection to the db in question.

Returns

exp_id of the default experiment.

Raises

ValueError – If no experiment exists in the given db.

qcodes.dataset.get_guids_by_run_spec(*, captured_run_id: Optional[int] = None, captured_counter: Optional[int] = None, experiment_name: Optional[str] = None, sample_name: Optional[str] = None, sample_id: Optional[int] = None, location: Optional[int] = None, work_station: Optional[int] = None, conn: Optional[ConnectionPlus] = None) List[str][source]

Get a list of matching guids from one or more pieces of runs specification. All fields are optional.

Parameters
  • captured_run_id – The run_id that was originally assigned to this at the time of capture.

  • captured_counter – The counter that was originally assigned to this at the time of capture.

  • experiment_name – name of the experiment that the run was captured

  • sample_name – The name of the sample given when creating the experiment.

  • sample_id – The sample_id assigned as part of the GUID.

  • location – The location code assigned as part of GUID.

  • work_station – The workstation assigned as part of the GUID.

  • conn – An optional connection to the database. If no connection is supplied a connection to the default database will be opened.

Returns

List of guids matching the run spec.

qcodes.dataset.import_dat_file(location: str, exp: Optional[Experiment] = None) List[int][source]

This imports a QCoDeS legacy qcodes.data.data_set.DataSet into the database.

Parameters
  • location – Path to file containing legacy dataset

  • exp – Specify the experiment to store data to. If None the default one is used. See the docs of qcodes.dataset.Measurement for more details.

qcodes.dataset.initialise_database(journal_mode: Optional[Literal['DELETE', 'TRUNCATE', 'PERSIST', 'MEMORY', 'WAL', 'OFF']] = 'WAL') None[source]

Initialise a database in the location specified by the config object and set atomic commit and rollback mode of the db. The db is created with the latest supported version. If the database already exists the atomic commit and rollback mode is set and the database is upgraded to the latest version.

Parameters

journal_mode – Which journal_mode should be used for atomic commit and rollback. Options are DELETE, TRUNCATE, PERSIST, MEMORY, WAL and OFF. If set to None no changes are made.

qcodes.dataset.initialise_or_create_database_at(db_file_with_abs_path: str, journal_mode: Optional[Literal['DELETE', 'TRUNCATE', 'PERSIST', 'MEMORY', 'WAL', 'OFF']] = 'WAL') None[source]

This function sets up QCoDeS to refer to the given database file. If the database file does not exist, it will be initiated.

Parameters
  • db_file_with_abs_path – Database file name with absolute path, for example C:\mydata\majorana_experiments.db

  • journal_mode – Which journal_mode should be used for atomic commit and rollback. Options are DELETE, TRUNCATE, PERSIST, MEMORY, WAL and OFF. If set to None no changes are made.

qcodes.dataset.initialised_database_at(db_file_with_abs_path: str) Iterator[None][source]

Initializes or creates a database and restores the ‘db_location’ afterwards.

Parameters

db_file_with_abs_path – Database file name with absolute path, for example C:\mydata\majorana_experiments.db

qcodes.dataset.load_by_counter(counter: int, exp_id: int, conn: Optional[ConnectionPlus] = None) DataSetProtocol[source]

Load a dataset given its counter in a given experiment

Lookup is performed in the database file that is specified in the config.

Note that the counter used in this function in not preserved when copying data to another db file. We recommend using load_by_run_spec() which does not have this issue and is significantly more flexible.

If the raw data is in the database this will be loaded as a qcodes.dataset.data_set.DataSet otherwise it will be loaded as a DataSetInMemory

Parameters
  • counter – counter of the dataset within the given experiment

  • exp_id – id of the experiment where to look for the dataset

  • conn – connection to the database to load from. If not provided, a connection to the DB file specified in the config is made

Returns

qcodes.dataset.data_set.DataSet or DataSetInMemory of the given counter in the given experiment

qcodes.dataset.load_by_guid(guid: str, conn: Optional[ConnectionPlus] = None) DataSetProtocol[source]

Load a dataset by its GUID

If no connection is provided, lookup is performed in the database file that is specified in the config.

If the raw data is in the database this will be loaded as a qcodes.dataset.data_set.DataSet otherwise it will be loaded as a DataSetInMemory

Parameters
  • guid – guid of the dataset

  • conn – connection to the database to load from

Returns

qcodes.dataset.data_set.DataSet or DataSetInMemory with the given guid

Raises
  • NameError – if no run with the given GUID exists in the database

  • RuntimeError – if several runs with the given GUID are found

qcodes.dataset.load_by_id(run_id: int, conn: Optional[ConnectionPlus] = None) DataSetProtocol[source]

Load a dataset by run id

If no connection is provided, lookup is performed in the database file that is specified in the config.

Note that the run_id used in this function in not preserved when copying data to another db file. We recommend using load_by_run_spec() which does not have this issue and is significantly more flexible.

If the raw data is in the database this will be loaded as a qcodes.dataset.data_set.DataSet otherwise it will be loaded as a DataSetInMemory

Parameters
  • run_id – run id of the dataset

  • conn – connection to the database to load from

Returns

qcodes.dataset.data_set.DataSet or DataSetInMemory with the given run id

qcodes.dataset.load_by_run_spec(*, captured_run_id: Optional[int] = None, captured_counter: Optional[int] = None, experiment_name: Optional[str] = None, sample_name: Optional[str] = None, sample_id: Optional[int] = None, location: Optional[int] = None, work_station: Optional[int] = None, conn: Optional[ConnectionPlus] = None) DataSetProtocol[source]

Load a run from one or more pieces of runs specification. All fields are optional but the function will raise an error if more than one run matching the supplied specification is found. Along with the error specs of the runs found will be printed.

If the raw data is in the database this will be loaded as a qcodes.dataset.data_set.DataSet otherwise it will be loaded as a DataSetInMemory

Parameters
  • captured_run_id – The run_id that was originally assigned to this at the time of capture.

  • captured_counter – The counter that was originally assigned to this at the time of capture.

  • experiment_name – name of the experiment that the run was captured

  • sample_name – The name of the sample given when creating the experiment.

  • sample_id – The sample_id assigned as part of the GUID.

  • location – The location code assigned as part of GUID.

  • work_station – The workstation assigned as part of the GUID.

  • conn – An optional connection to the database. If no connection is supplied a connection to the default database will be opened.

Raises

NameError – if no run or more than one run with the given specification exists in the database

Returns

qcodes.dataset.data_set.DataSet or DataSetInMemory matching the provided specification.

qcodes.dataset.load_experiment(exp_id: int, conn: Optional[ConnectionPlus] = None) Experiment[source]

Load experiment with the specified id (from database file from config)

Parameters
  • exp_id – experiment id

  • conn – connection to the database. If not supplied, a new connection to the DB file specified in the config is made

Returns

experiment with the specified id

Raises

ValueError – If experiment id is not an integer.

qcodes.dataset.load_experiment_by_name(name: str, sample: Optional[str] = None, conn: Optional[ConnectionPlus] = None, load_last_duplicate: bool = False) Experiment[source]

Try to load experiment with the specified name.

Nothing stops you from having many experiments with the same name and sample name. In that case this won’t work unless load_last_duplicate is set to True. Then, the last of duplicated experiments will be loaded.

Parameters
  • name – the name of the experiment

  • sample – the name of the sample

  • load_last_duplicate – If True, prevent raising error for having multiple experiments with the same name and sample name, and load the last duplicated experiment, instead.

  • conn – connection to the database. If not supplied, a new connection to the DB file specified in the config is made

Returns

The requested experiment

Raises

ValueError – either if the name and sample name are not unique, unless load_last_duplicate is True, or if no experiment found for the supplied name and sample.

qcodes.dataset.load_from_netcdf(path: Union[Path, str], path_to_db: Optional[Union[Path, str]] = None) DataSetInMem[source]

Create a in memory dataset from a netcdf file. The netcdf file is expected to contain a QCoDeS dataset that has been exported using the QCoDeS netcdf export functions.

Parameters
  • path – Path to the netcdf file to import.

  • path_to_db – Optional path to a database where this dataset may be exported to. If not supplied the path can be given at export time or the dataset exported to the default db as set in the QCoDeS config.

Returns

The loaded dataset.

qcodes.dataset.load_last_experiment() Experiment[source]

Load last experiment (from database file from config)

Returns

The last experiment

Raises

ValueError – If no experiment exists in the db.

qcodes.dataset.load_or_create_experiment(experiment_name: str, sample_name: Optional[str] = None, conn: Optional[ConnectionPlus] = None, load_last_duplicate: bool = False) Experiment[source]

Find and return an experiment with the given name and sample name, or create one if not found.

Parameters
  • experiment_name – Name of the experiment to find or create.

  • sample_name – Name of the sample.

  • load_last_duplicate – If True, prevent raising error for having multiple experiments with the same name and sample name, and load the last duplicated experiment, instead.

  • conn – Connection to the database. If not supplied, a new connection to the DB file specified in the config is made.

Returns

The found or created experiment

Raises

ValueError – If the name and sample name are not unique, unless load_last_duplicate is True.

qcodes.dataset.new_data_set(name: str, exp_id: Optional[int] = None, specs: Optional[List[ParamSpec]] = None, values: Optional[Sequence[Optional[Union[str, complex, List, ndarray, bool]]]] = None, metadata: Optional[Any] = None, conn: Optional[ConnectionPlus] = None, in_memory_cache: bool = True) DataSet[source]

Create a new dataset in the currently active/selected database.

If exp_id is not specified, the last experiment will be loaded by default.

Parameters
  • name – the name of the new dataset

  • exp_id – the id of the experiments this dataset belongs to, defaults to the last experiment

  • specs – list of parameters to create this dataset with

  • values – the values to associate with the parameters

  • metadata – the metadata to associate with the dataset

  • in_memory_cache – Should measured data be keep in memory and available as part of the dataset.cache object.

Returns

the newly created qcodes.dataset.data_set.DataSet

qcodes.dataset.new_experiment(name: str, sample_name: Optional[str], format_string: str = '{}-{}-{}', conn: Optional[ConnectionPlus] = None) Experiment[source]

Create a new experiment (in the database file from config)

Parameters
  • name – the name of the experiment

  • sample_name – the name of the current sample

  • format_string – basic format string for table-name must contain 3 placeholders.

  • conn – connection to the database. If not supplied, a new connection to the DB file specified in the config is made

Returns

the new experiment

qcodes.dataset.plot_by_id(run_id: int, axes: Optional[Union[Axes, Sequence[Axes]]] = None, colorbars: Optional[Union[Colorbar, Sequence[Colorbar]]] = None, rescale_axes: bool = True, auto_color_scale: Optional[bool] = None, cutoff_percentile: Optional[Union[Tuple[float, float], float]] = None, complex_plot_type: Literal['real_and_imag', 'mag_and_phase'] = 'real_and_imag', complex_plot_phase: Literal['radians', 'degrees'] = 'radians', **kwargs: Any) Tuple[List[Axes], List[Optional[Colorbar]]][source]

Construct all plots for a given run_id. Here run_id is an alias for captured_run_id for historical reasons. See the docs of qcodes.dataset.load_by_run_spec() for details of loading runs. All other arguments are forwarded to plot_dataset(), see this for more details.

qcodes.dataset.plot_dataset(dataset: DataSetProtocol, axes: Optional[Union[Axes, Sequence[Axes]]] = None, colorbars: Optional[Union[Colorbar, Sequence[Colorbar]]] = None, rescale_axes: bool = True, auto_color_scale: Optional[bool] = None, cutoff_percentile: Optional[Union[Tuple[float, float], float]] = None, complex_plot_type: Literal['real_and_imag', 'mag_and_phase'] = 'real_and_imag', complex_plot_phase: Literal['radians', 'degrees'] = 'radians', **kwargs: Any) Tuple[List[Axes], List[Optional[Colorbar]]][source]

Construct all plots for a given dataset

Implemented so far:

  • 1D line and scatter plots

  • 2D plots on filled out rectangular grids

  • 2D scatterplots (fallback)

The function can optionally be supplied with a matplotlib axes or a list of axes that will be used for plotting. The user should ensure that the number of axes matches the number of datasets to plot. To plot several (1D) dataset in the same axes supply it several times. Colorbar axes are created dynamically. If colorbar axes are supplied, they will be reused, yet new colorbar axes will be returned.

The plot has a title that comprises run id, experiment name, and sample name.

**kwargs are passed to matplotlib’s relevant plotting functions By default the data in any vector plot will be rasterized for scatter plots and heatmaps if more than 5000 points are supplied. This can be overridden by supplying the rasterized kwarg.

Parameters
  • dataset – The dataset to plot

  • axes – Optional Matplotlib axes to plot on. If not provided, new axes will be created

  • colorbars – Optional Matplotlib Colorbars to use for 2D plots. If not provided, new ones will be created

  • rescale_axes – If True, tick labels and units for axes of parameters with standard SI units will be rescaled so that, for example, ‘0.00000005’ tick label on ‘V’ axis are transformed to ‘50’ on ‘nV’ axis (‘n’ is ‘nano’)

  • auto_color_scale – If True, the colorscale of heatmap plots will be automatically adjusted to disregard outliers.

  • cutoff_percentile – Percentile of data that may maximally be clipped on both sides of the distribution. If given a tuple (a,b) the percentile limits will be a and 100-b. See also the plotting tuorial notebook.

  • complex_plot_type – Method for converting complex-valued parameters into two real-valued parameters, either "real_and_imag" or "mag_and_phase". Applicable only for the cases where the dataset contains complex numbers

  • complex_plot_phase – Format of phase for plotting complex-valued data, either "radians" or "degrees". Applicable only for the cases where the dataset contains complex numbers

Returns

A list of axes and a list of colorbars of the same length. The colorbar axes may be None if no colorbar is created (e.g. for 1D plots)

Config dependencies: (qcodesrc.json)

qcodes.dataset.reset_default_experiment_id(conn: Optional[ConnectionPlus] = None) None[source]

Resets the default experiment id to to the last experiment in the db.