{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Custom Abundance Widget\n",
    "\n",
    "The Custom Abundance Widget is a Graphical User Interface (GUI) that allows you\n",
    "to develop custom model compositions graphically and output the model to a new\n",
    "file — all within a Jupyter Notebook.\n",
    "\n",
    "The GUI consists of three parts:\n",
    "\n",
    "1. **Visualization plot** — An interactive step graph that shows abundances and\n",
    "   densities as a function of velocity.\n",
    "\n",
    "2. **Data editor** — An interface to edit abundances, densities, and velocity\n",
    "   shells.\n",
    "\n",
    "3. **File output** — An output module to save the model compositions as a CSVY\n",
    "   file.\n",
    "\n",
    "![Energy Level Widget Options Demo](../images/custom_abundance_demo.gif)\n",
    "\n",
    "## Interacting with the GUI\n",
    "\n",
    "### Edit Abundances\n",
    "There are two radio buttons that let you edit either a single shell or multiple\n",
    "shells. The new input is applied to the selected shell(s) immediately and the\n",
    "plot updates at the same time. To edit multiple shells at once, choose the second\n",
    "radio button and set the range of shell numbers using the int slider. The selected\n",
    "shell(s) are highlighted in the plot.\n",
    "\n",
    "### Normalize Abundances\n",
    "Click the **Normalize** button to normalize the abundances of the selected\n",
    "shell(s) to 1. To keep the abundance of a particular element unchanged during\n",
    "normalization, select the checkbox next to that element to lock it. The\n",
    "normalization is applied to the other elements so that the total still sums to 1.\n",
    "\n",
    "### Edit Densities\n",
    "In the **Edit Density** tab, you can edit either a single shell or the whole\n",
    "density profile. Choose a density type and supply the required parameters to\n",
    "calculate a new profile.\n",
    "\n",
    "### Add a New Element\n",
    "The symbol input box at the bottom of the editor lets you add a new element or\n",
    "isotope to the model. It automatically checks whether the symbol is valid and\n",
    "whether the element is already present in the model.\n",
    "\n",
    "### Add a New Shell\n",
    "You can add a new shell to the model by specifying its velocity range. Abundances\n",
    "for the new shell are initialized to 0. Existing shells are resized automatically\n",
    "if the new shell overlaps with any of them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generating the Widget\n",
    "\n",
    "Import `CustomAbundanceWidget` from the `visualization` subpackage to create the\n",
    "widget."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from tardis.visualization import CustomAbundanceWidget"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are four ways to initialize the widget. You can generate it from a\n",
    "`.yml` or `.csvy` configuration file before running any simulation, or from a\n",
    "Simulation object or saved HDF file after a simulation."
   ]
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**Warning**\n",
    "\n",
    "Custom abundance widget currently exhibits unintended behavior when run in a notebook where a simulation has already been run.\n",
    "It is recommended to run the widget in a fresh notebook without running any simulation first.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "### Using a YAML file"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "widget = CustomAbundanceWidget.from_yml(\"tardis_example.yml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using a CSVY File"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# widget = CustomAbundanceWidget.from_csvy(\"demo.csvy\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using a Simulation Object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# sim = run_tardis(\"tardis_example.yml\")\n",
    "# widget = CustomAbundanceWidget.from_simulation(sim)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using an HDF File"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# widget = CustomAbundanceWidget.from_hdf(\"demo.h5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Display the Widget\n",
    "\n",
    "Regardless of which initialization method you use, call `.display()` to render\n",
    "the GUI."
   ]
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "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": [
    "widget.display()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "tardis",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.13.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}