This page was generated from docs/examples/DataSet/The-Experiment-Container.ipynb. Interactive online version: Binder badge.

The Experiment Container

This notebook explains how the database works as an experiment container.

Required imports

[1]:

import os

from qcodes.dataset import (
    connect,
    experiments,
    get_default_experiment_id,
    initialise_or_create_database_at,
    load_experiment,
    load_experiment_by_name,
    load_last_experiment,
    load_or_create_experiment,
    new_data_set,
    new_experiment,
    reset_default_experiment_id,
)

Logging hadn't been started.
Activating auto-logging. Current session state plus future input saved.
Filename       : /home/runner/.qcodes/logs/command_history.log
Mode           : append
Output logging : True
Raw input log  : False
Timestamping   : True
State          : active
Qcodes Logfile : /home/runner/.qcodes/logs/241218-16842-qcodes.log

The experiments inside the database

[2]:

db_file_path = os.path.join(os.getcwd(), "exp_container_tutorial.db")
initialise_or_create_database_at(db_file_path)

The database holds a certain number of experiments. They may be viewed:

[3]:

experiments()

[3]:

[]

Not surprisingly, our new database is empty.

We now introduce a term that we call the default experiment. In short, it is the experiment that will be used for a QCoDeS DataSet, if the user do not explicitly pass an experiment into objects that create that DataSet. In another word, that DataSet will be belong to the default experiment. We do not want to go into the details of DataSet here, and refer to the DataSet notebook and Performing measurements using qcodes parameters and dataset for what we mean from DataSet and how we can pass an experiment explicitly.

By default, the last experiment in the database is the default experiment. The default experiment can be changed if another experiment in the database is created or loaded. We will explore this in this notebook.

Users should not worry about checking the default experiment in their normal workflow, but in this notebook, we show how it works to let them have an idea what the default experiment is and how it changes.

We need a connection to our database to get which experiment is the default one:

[4]:

conn = connect(db_file_path)

Because our database is empty now, asking for the default experiment will rasie an error asking to create an experiment. So, let’s add some experiments to explore more:

[5]:

exp_a = new_experiment("first_exp", sample_name="old_sample")
exp_b = new_experiment("second_exp", sample_name="slightly_newer_sample")
exp_c = load_or_create_experiment("third_exp", sample_name="brand_new_sample")

We recommend using the load_or_create_experiment function as the primary function dealing with experiments, not only because it is the most versatile function, but also because it can prevent creating duplicate experiments in one database.

[6]:

experiments()

[6]:

[first_exp#old_sample#1@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
 ------------------------------------------------------------------------------------------------------,
 second_exp#slightly_newer_sample#2@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
 ------------------------------------------------------------------------------------------------------------------,
 third_exp#brand_new_sample#3@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
 ------------------------------------------------------------------------------------------------------------]

We notice that each experiment is labelled by an integer number, which is the exp_id. This ID can be used when looking up properties of each experiment.

Let’s check to see which experiment is the default now:

[7]:

get_default_experiment_id(conn)

[7]:

3

The latest created or loaded experiment in the database becomes the default experiment, and the function returns the exp_id of that experiment, which in this case it is exp_c with exp_id of 3.

Let us add some DataSet to our experiments. For the sake of clarity, we don’t add any data to the DataSet here, and refer to the above-mentioned notebooks for the details. Note that the new_data_set function is used here ONLY for the sake of exercise and should NOT be used in the actual experiment.

[8]:

new_data_set("run_a")

[8]:

run_a #1@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
----------------------------------------------------------------------------------------

Since the default experiment is exp_c (exp_id=3), the above DataSet belongs to this experiment.

[9]:

exp_c

[9]:

third_exp#brand_new_sample#3@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
------------------------------------------------------------------------------------------------------------
1-run_a-1-None-0

Let’s load another experiment (exp_b). We know that the latest created/ loaded experiment should be the default experiment, meaning any new DataSet should belong to this experiment:

[10]:

load_or_create_experiment("second_exp", sample_name="slightly_newer_sample")

[10]:

second_exp#slightly_newer_sample#2@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
------------------------------------------------------------------------------------------------------------------

Let’s confirm that actually the second experiment (exp_id=2) is the default now:

[11]:

get_default_experiment_id(conn)

[11]:

2

[12]:

new_data_set("first_run_b")

[12]:

first_run_b #2@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
----------------------------------------------------------------------------------------------

[13]:

new_data_set("second_run_b")

[13]:

second_run_b #3@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
-----------------------------------------------------------------------------------------------

Two above DataSets should belong to exp_b:

[14]:

exp_b

[14]:

second_exp#slightly_newer_sample#2@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
------------------------------------------------------------------------------------------------------------------
2-first_run_b-1-None-0
3-second_run_b-2-None-0

We can also explicitly use exp_id in creating DataSets, so let’s add a DataSet to the first experiment:

[15]:

new_data_set("first_run", exp_id=1)

[15]:

first_run #4@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
--------------------------------------------------------------------------------------------

[16]:

exp_a

[16]:

first_exp#old_sample#1@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
------------------------------------------------------------------------------------------------------
4-first_run-1-None-0

The default experiment gets reset upon initialization of a database. Let’s check this by initializing our database again (note that our database is not empty anymore):

[17]:

initialise_or_create_database_at(db_file_path)

The default experiment was exp_id=2. As we initialized our database again, the default experiment has been reset, meaning the last experiment in the database should be the default one now (we know the last experiment in the database is exp_id=3). Let’s check this:

[18]:

get_default_experiment_id(conn)

[18]:

3

Users may not need to use the reset function explicitly, but in the case they want to use it, here we show how to do that:

First, we load an experiment other than the last experiment and check the default experiment is the just loaded experiment:

[19]:

load_experiment(1)

[19]:

first_exp#old_sample#1@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
------------------------------------------------------------------------------------------------------
4-first_run-1-None-0

[20]:

get_default_experiment_id(conn)

[20]:

1

Now, we reset the default experiment and expect to see the last experiment (exp_id=3) is the default one:

[21]:

reset_default_experiment_id()  # the explicit database connection can be used as an optional argument

[22]:

get_default_experiment_id(conn)

[22]:

3

Let’s make sure it is truly the default experiment by creating a new DataSet:

[23]:

new_data_set("default_run")

[23]:

default_run #5@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
----------------------------------------------------------------------------------------------

This DataSet should belong to exp_c:

[24]:

exp_c

[24]:

third_exp#brand_new_sample#3@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
------------------------------------------------------------------------------------------------------------
1-run_a-1-None-0
5-default_run-2-None-0

There are a few other useful functions to load experiments:

[25]:

load_experiment_by_name(
    "second_exp", sample="slightly_newer_sample"
)  # loads using name and sample

[25]:

second_exp#slightly_newer_sample#2@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
------------------------------------------------------------------------------------------------------------------
2-first_run_b-1-None-0
3-second_run_b-2-None-0

[26]:

load_last_experiment()  # loads the last experiment in the database

[26]:

third_exp#brand_new_sample#3@/home/runner/work/Qcodes/Qcodes/docs/examples/DataSet/exp_container_tutorial.db
------------------------------------------------------------------------------------------------------------
1-run_a-1-None-0
5-default_run-2-None-0