{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Energy Level Diagram Widget\n",
    "\n",
    "The Energy Level Diagram Widget (also called the Grotrian Widget) lets you\n",
    "visualize the last line interactions in a simulation as an energy level diagram.\n",
    "\n",
    "By selecting an ion present in the simulation, you can see its energy level\n",
    "diagram along with information about the last line interactions experienced by\n",
    "packets.\n",
    "\n",
    "- The **y-axis** represents energy.\n",
    "- **Horizontal lines** show discrete energy levels. The thickness of each line\n",
    "  reflects the level population — thicker lines indicate a greater population.\n",
    "- **Arrows** represent line interactions between levels. Upward arrows show\n",
    "  excitation (lower → higher energy) and downward arrows show de-excitation\n",
    "  (higher → lower energy). The thickness of each arrow indicates the number of\n",
    "  packets that underwent that interaction, and the color encodes the wavelength\n",
    "  of the transition.\n",
    "\n",
    "## Interacting with the GUI\n",
    "\n",
    "You can filter the last line interactions and level populations using several\n",
    "controls:\n",
    "\n",
    "- **Wavelength range slider** — restrict which transitions are shown.\n",
    "- **Shell selector** — filter by a specific model shell. If no shell is selected,\n",
    "  all last line interactions are plotted and level populations are averaged across\n",
    "  all shells.\n",
    "- **Maximum number of levels** — set how many levels (beginning from the lowest\n",
    "  energy) to display on the plot.\n",
    "- **Y-axis scale** — switch between Linear and Log scaling.\n",
    "\n",
    "![Energy Level Widget Options Demo](../images/energy_level_widget_demo.gif)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generating the Widget\n",
    "\n",
    "First, create and run a simulation (see [Quickstart](https://tardis-sn.github.io/tardis/quickstart/quickstart.html)\n",
    "for details), then import `GrotrianWidget` from the `visualization` subpackage."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from tardis import run_tardis\n",
    "from tardis.io.atom_data import download_atom_data\n",
    "from tardis.io.configuration.config_reader import Configuration\n",
    "from tardis.visualization import GrotrianWidget\n",
    "\n",
    "# Download the atomic data needed to run the simulation\n",
    "download_atom_data('kurucz_cd23_chianti_H_He_latest')\n",
    "\n",
    "config = Configuration.from_yaml(\"tardis_example.yml\")\n",
    "config.montecarlo.tracking.track_rpacket = True\n",
    "\n",
    "sim = run_tardis(config, virtual_packet_logging=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**Note for Documentation Viewers**\n",
    "\n",
    "The interactive widget below will not function in the published documentation.\n",
    "To use this widget, please run this notebook locally in a Jupyter environment\n",
    "with TARDIS installed.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "energy_level_widget = GrotrianWidget.from_simulation(sim)\n",
    "energy_level_widget.display()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "tardis",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.13.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}