{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "67d6982f",
   "metadata": {},
   "source": [
    "# Configuring the Logging Output for TARDIS"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac4ba612",
   "metadata": {},
   "source": [
    "**TARDIS** has a Notebook logger that logs information of Simulation runs. The logs allows to access vital information regarding the execution sequence, data for plasma stratification & progress of the simulation.<br>\n",
    "**TARDIS** allows configuring the logger via *Functional Arguments* as well as *YAML Parameters*.\n",
    "The following code snippets are some of the possible configuration that is available for the notebook logging done with TARDIS simulation."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce886182",
   "metadata": {},
   "source": [
    "## Default Configuration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "34e59abc",
   "metadata": {},
   "source": [
    "The default configuration of the Notebook Simulation logger is such that it doesn't output any logs."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41da9db6",
   "metadata": {},
   "source": [
    "The output simulation logging, while executing the **TARDIS** simulation (default behaviour), can be seen below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "018bb127",
   "metadata": {},
   "outputs": [],
   "source": [
    "from tardis import run_tardis\n",
    "from tardis.io.atom_data.util import download_atom_data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ad59aa05",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "# We download the atomic data needed to run the simulation\n",
    "download_atom_data('kurucz_cd23_chianti_H_He')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "64cf4bb2",
   "metadata": {},
   "outputs": [],
   "source": [
    "sim = run_tardis(\"tardis_config_logger.yml\", show_cplots=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9bf77405",
   "metadata": {},
   "source": [
    "It can be examined that the logs are not printed.<br> The logging level, by default, is set to `CRITICAL`. Logs will only be captured if any `CRITICAL` level logs are encountered while running the simulation."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "420dd7c2",
   "metadata": {},
   "source": [
    "## Logging Configuration (Functional Arguments)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac8d5088",
   "metadata": {},
   "source": [
    "The `run_tardis()` function from the `tardis module` has two functional arguments:`log_level` & `specific_log_level`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d58f2d9c",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "\n",
    "Both <strong>log_level</strong> & <strong>specific</strong> are optional arguments for the <strong>run_tardis()</strong> function, however, if <strong>specific</strong> argument is used then, <strong>log_level</strong> must be set to a particular level.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1176f370",
   "metadata": {},
   "source": [
    "### The `log_level` Argument"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3547b04",
   "metadata": {},
   "source": [
    "The `log_level` argument can be passed in `run_tardis()` to set the logging level for the simulation. The input for this argument **must be** one of the following: **Notset, Debug, Info, Warning, Error** or **Critical**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dc2dcd71",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "sim = run_tardis(\"tardis_config_logger.yml\", log_level=\"Info\", show_cplots=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "52e778bc",
   "metadata": {},
   "source": [
    "By setting up the `log_level` parameter to **\"Info\"** in the above example, we can check that the logs are at the **\"Info\"** or higher logging level. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "25277fe8",
   "metadata": {},
   "source": [
    "### The `specific` Argument"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56a5ef36",
   "metadata": {},
   "source": [
    "The `specific_log_level` argument tells the logger to capture log messages set by the `log_level` parameter. It can only take *Boolean* values for input, which are `True` or `False`. Take for example the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a0df43d1",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "sim = run_tardis(\"tardis_config_logger.yml\", log_level=\"Debug\", specific_log_level=True, show_cplots=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5c6ff57c",
   "metadata": {},
   "source": [
    "It can be examined that, when we set `specific_log_level` to `True`, the log messages captured were only at the `DEBUG` log level.<br> This allows for logging only specified logging messages for inspection."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5083321b",
   "metadata": {},
   "source": [
    "The changes in the captured log messages can be seen when we set `specific_log_level` to `False`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "566919b3",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "sim = run_tardis(\"tardis_config_logger.yml\", log_level=\"Debug\", specific_log_level=False, show_cplots=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "42ddc98b",
   "metadata": {},
   "source": [
    "It can be examined in this example that when we kept `specific_log_level` to `False`, the captured log output includes all log messages from `DEBUG` and higher logging levels, which is the default behavior of the logger."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9f478f6",
   "metadata": {},
   "source": [
    "## Logging Configuration (YAML Configuration)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d672a8d",
   "metadata": {},
   "source": [
    "The behavior of the logging output for the simulation can be configured via the `tardis_config_logger.yml` *(**YAML** Configuration)* file. For setting up the logger via the YAML file, the configuration file must include a `debug` section. An example configuration for the `debug` section can be seen below:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd8c3eed",
   "metadata": {},
   "source": [
    "```YAML\n",
    "...\n",
    "debug:\n",
    "  log_level: \"Info\"\n",
    "  specific_log_level : False\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85ea7ae2",
   "metadata": {},
   "source": [
    "The `debug` schema includes the `log_level` & `specific_log_level` parameters."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "65204c82",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "    \n",
    "The <strong>debug</strong> section of the <strong>YAML</strong> config file is <i>optional</i>. The <strong>log_level</strong> and the <strong>specific</strong> arguments are <i>optional</i> as well. If none of the parameters are defined, then the values of these parameter fall back on the <strong>default values</strong>.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "62750463",
   "metadata": {},
   "source": [
    "Let us load the `tardis_config_logger.yml` configuration to a variable & check out the schema:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d9a5e83b",
   "metadata": {},
   "outputs": [],
   "source": [
    "from tardis.io.configuration.config_reader import Configuration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a1fa5e1b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Loading the Schema \n",
    "config = Configuration.from_yaml(\"tardis_config_logger.yml\")\n",
    "\n",
    "# Checking the Debug Schema via dictionary\n",
    "config[\"debug\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7f5f2d9f",
   "metadata": {},
   "source": [
    "### The `log_level` Entry"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1389e902",
   "metadata": {},
   "source": [
    "The `log_level` parameter, in the `debug` section of the config file, is similar in functionality to the `log_level` functional argument that can be passed via the `run_tardis()` function. The value of this parameter **must be** one of the following: **Notset, Debug, Info, Warning, Error** or **Critical**."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3bdd9972",
   "metadata": {},
   "source": [
    "Let us see an example of the captured simulation logging output, when the `log_level` parameter is set to `\"Info\"` log level in the `tardis_config_logger.yml` config file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "88223ed0",
   "metadata": {},
   "outputs": [],
   "source": [
    "config[\"debug\"][\"log_level\"] = \"Info\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ad8eac94",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "# Running the simulation by passing the config dictionary to `run_tardis()` function\n",
    "sim = run_tardis(config, show_cplots=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3fadc651",
   "metadata": {},
   "source": [
    "### The `specific` Entry"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "df50d2e1",
   "metadata": {},
   "source": [
    "The `specific_log_level` parameter in the `debug` section of the schema is similar in functionality to the `specific_log_level` functional argument. It takes **Boolean** values, i.e., `True` or `False`. It is an optional parameter. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b71946ad",
   "metadata": {},
   "source": [
    "Let us see an example when we set `specific_log_level` to `True` at the `Debug` level."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "64ce1048",
   "metadata": {},
   "outputs": [],
   "source": [
    "config[\"debug\"][\"log_level\"] = \"Debug\"\n",
    "config[\"debug\"][\"specific_log_level\"] = True"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "33696bdd",
   "metadata": {},
   "outputs": [],
   "source": [
    "sim = run_tardis(config, show_cplots=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e895aec",
   "metadata": {},
   "source": [
    "Setting `specific_log_level` to `False` to check the actual output at the `DEBUG` level for the simulation logs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "762c858f",
   "metadata": {},
   "outputs": [],
   "source": [
    "config[\"debug\"][\"specific_log_level\"] = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "581f2d8d",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "sim = run_tardis(config,show_cplots=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5e8f1dbe",
   "metadata": {},
   "source": [
    "### What Happens When Both Parameters Are Specified? { Function & YAML Arguments }"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f32403c7",
   "metadata": {},
   "source": [
    "If a user specifies both the parameters passed through the `log_level` & `log_level` in the **YAML** configuration file, then the `log_level` parameter *(Functional Argument)* takes precedence & is used to determine the logging level for the simulation logs."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f2a24e11",
   "metadata": {},
   "source": [
    "Let us consider the following example for the configuration:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "863042a4",
   "metadata": {},
   "source": [
    "Continuing from the previous example, the `config[\"debug\"][\"log_level\"]` is set to `Debug` via the **YAML** file. The user will also set the `log_level` {Functional Argument} to `Info`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "30763e52",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "sim = run_tardis(config, log_level=\"Info\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "674f4972",
   "metadata": {},
   "source": [
    "A new message can be seen from the execution of the simulation,\n",
    "```\n",
    "log_level is defined both in Functional Argument & YAML Configuration {debug section}\n",
    "log_level = Info will be used for Log Level Determination\n",
    "```\n",
    "that is informing the user which input log level value will determine the logging level. Thus, `log_level = \"Info\"` is used for logging the simulation output."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ff806bd",
   "metadata": {},
   "source": [
    "In regards to the `specific_log_level` parameter, if any of the config input value is `True`, then `specific_log_level` will be set to `True` for the simulation output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5d1900f5",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "sim = run_tardis(config, log_level=\"Info\", specific=True)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}