{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The Experiment Container\n",
    "\n",
    "This notebook explains how the database works as an experiment container."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Required imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "from qcodes.dataset import (\n",
    "    connect,\n",
    "    experiments,\n",
    "    get_default_experiment_id,\n",
    "    initialise_or_create_database_at,\n",
    "    load_experiment,\n",
    "    load_experiment_by_name,\n",
    "    load_last_experiment,\n",
    "    load_or_create_experiment,\n",
    "    new_data_set,\n",
    "    new_experiment,\n",
    "    reset_default_experiment_id,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The experiments inside the database"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Upgrading database; v0 -> v1: : 0it [00:00, ?it/s]\n",
      "Upgrading database; v1 -> v2: 100%|█████████████████████████████████████████████████████| 1/1 [00:00<00:00, 510.01it/s]\n",
      "Upgrading database; v2 -> v3: : 0it [00:00, ?it/s]\n",
      "Upgrading database; v3 -> v4: : 0it [00:00, ?it/s]\n",
      "Upgrading database; v4 -> v5: 100%|█████████████████████████████████████████████████████| 1/1 [00:00<00:00, 253.45it/s]\n",
      "Upgrading database; v5 -> v6: : 0it [00:00, ?it/s]\n",
      "Upgrading database; v6 -> v7: 100%|█████████████████████████████████████████████████████| 1/1 [00:00<00:00, 142.87it/s]\n",
      "Upgrading database; v7 -> v8: 100%|█████████████████████████████████████████████████████| 1/1 [00:00<00:00, 506.07it/s]\n",
      "Upgrading database; v8 -> v9: 100%|█████████████████████████████████████████████████████| 1/1 [00:00<00:00, 338.55it/s]\n"
     ]
    }
   ],
   "source": [
    "db_file_path = os.path.join(os.getcwd(), 'exp_container_tutorial.db')\n",
    "initialise_or_create_database_at(db_file_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The database holds a certain number of **experiments**. They may be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "experiments()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Not surprisingly, our new database is empty.\n",
    "\n",
    "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](https://microsoft.github.io/Qcodes/examples/DataSet/DataSet-class-walkthrough.html) and [Performing measurements using qcodes parameters and dataset](https://microsoft.github.io/Qcodes/examples/DataSet/Performing-measurements-using-qcodes-parameters-and-dataset.html) for what we mean from `DataSet` and how we can pass an experiment explicitly.\n",
    "\n",
    "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. \n",
    "\n",
    "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.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We need a connection to our database to get which experiment is the default one:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "conn = connect(db_file_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "exp_a = new_experiment('first_exp', sample_name='old_sample')\n",
    "exp_b = new_experiment('second_exp', sample_name='slightly_newer_sample')\n",
    "exp_c = load_or_create_experiment('third_exp', sample_name='brand_new_sample')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[first_exp#old_sample#1@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       " -----------------------------------------------------------------------------,\n",
       " second_exp#slightly_newer_sample#2@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       " -----------------------------------------------------------------------------------------,\n",
       " third_exp#brand_new_sample#3@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       " -----------------------------------------------------------------------------------]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "experiments()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check to see which experiment is the default now:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_default_experiment_id(conn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "run_a #1@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "---------------------------------------------------------------"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "new_data_set('run_a')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since the default experiment is exp_c (`exp_id`=3), the above `DataSet` belongs to this experiment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "third_exp#brand_new_sample#3@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "-----------------------------------------------------------------------------------\n",
       "1-run_a-1--0"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "exp_c"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "second_exp#slightly_newer_sample#2@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "-----------------------------------------------------------------------------------------"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "load_or_create_experiment('second_exp', sample_name='slightly_newer_sample')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's confirm that actually the second experiment (`exp_id`=2) is the default now:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_default_experiment_id(conn)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "first_run_b #2@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "---------------------------------------------------------------------"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "new_data_set('first_run_b')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "second_run_b #3@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "----------------------------------------------------------------------"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "new_data_set('second_run_b')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Two above `DataSet`s should belong to `exp_b`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "second_exp#slightly_newer_sample#2@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "-----------------------------------------------------------------------------------------\n",
       "2-first_run_b-1--0\n",
       "3-second_run_b-2--0"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "exp_b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also explicitly use `exp_id` in creating `DataSet`s, so let's add a `DataSet` to the first experiment:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "first_run #4@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "-------------------------------------------------------------------"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "new_data_set('first_run', exp_id=1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "first_exp#old_sample#1@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "-----------------------------------------------------------------------------\n",
       "4-first_run-1--0"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "exp_a"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "initialise_or_create_database_at(db_file_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_default_experiment_id(conn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, we load an experiment other than the last experiment and check the default experiment is the just loaded experiment:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "first_exp#old_sample#1@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "-----------------------------------------------------------------------------\n",
       "4-first_run-1--0"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "load_experiment(1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_default_experiment_id(conn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we reset the default experiment and expect to see the last experiment (`exp_id`=3) is the default one:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "reset_default_experiment_id() # the explicit database connection can be used as an optional argument"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_default_experiment_id(conn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's make sure it is truly the default experiment by creating a new `DataSet`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "default_run #5@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "---------------------------------------------------------------------"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "new_data_set('default_run')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This `DataSet` should belong to `exp_c`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "third_exp#brand_new_sample#3@C:\\Users\\a-fbonabi\\temp_work\\exp_container_tutorial.db\n",
       "-----------------------------------------------------------------------------------\n",
       "1-run_a-1--0\n",
       "5-default_run-2--0"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "exp_c"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are a few other useful functions to load experiments:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "load_experiment_by_name('second_exp', sample='slightly_newer_sample')  # loads using name and sample"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "load_last_experiment() # loads the last experiment in the database"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.11"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}