Add new documentation

tardis-sn · Aug 20, 2021 · b7dd739 · b7dd739
1 parent 9862cd3
commit b7dd739
Show file tree

Hide file tree

Showing 2 changed files with 92 additions and 59 deletions.
diff --git a/docs/io/visualization/abundance_widget.ipynb b/docs/io/visualization/abundance_widget.ipynb
@@ -11,7 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The Custom Abundance Widget is a GUI that allows the user to develop custom model compositions graphically. The notebook demonstrates how to generate and use this widget."
+    "This notebook demonstrates how to generate and display Custom Abundance Widget."
    ]
   },
   {
@@ -23,20 +23,9 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "/Users/yuyizheng/opt/anaconda3/envs/tardis/lib/python3.7/importlib/_bootstrap.py:219: QAWarning: pyne.data is not yet QA compliant.\n",
-      "  return f(*args, **kwds)\n",
-      "/Users/yuyizheng/opt/anaconda3/envs/tardis/lib/python3.7/importlib/_bootstrap.py:219: QAWarning: pyne.material is not yet QA compliant.\n",
-      "  return f(*args, **kwds)\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "from tardis.visualization import CustomAbundanceWidget"
    ]
@@ -64,7 +53,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -84,7 +73,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "widget = CustomAbundanceWidget.from_csvy(\"demo.csvy\")"
+    "# widget = CustomAbundanceWidget.from_csvy(\"demo.csvy\")"
    ]
   },
   {
@@ -107,8 +96,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sim = run_tardis(\"tardis_example.yml\")\n",
-    "widget = CustomAbundanceWidget.from_sim(sim)"
+    "# sim = run_tardis(\"tardis_example.yml\")\n",
+    "# widget = CustomAbundanceWidget.from_sim(sim)"
    ]
   },
   {
@@ -124,7 +113,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "widget = CustomAbundanceWidget.from_hdf(\"demo.hdf\")"
+    "# widget = CustomAbundanceWidget.from_hdf(\"demo.hdf\")"
    ]
   },
   {
@@ -141,55 +130,23 @@
     "No matter which way you use to initialize the widget, you can call `.display()` to display the GUI easily."
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "The GUI consists of three parts:\n",
-    "\n",
-    "1. Visualization plot - A step graph that shows abundances and densities as a function of velocity. \n",
-    "\n",
-    "2. Data editor - An interface to edit abundances, densities and velocity shells.\n",
-    "\n",
-    "3. File output - An output module to save the model compositions as a CSVY file."
-   ]
-  },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "application/vnd.jupyter.widget-view+json": {
-       "model_id": "0e931fab89764adba022a129fc4a24ba",
-       "version_major": 2,
-       "version_minor": 0
-      },
-      "text/plain": [
-       "VBox(children=(VBox(children=(ToggleButtons(description='Scale of yaxes: ', options=('Linear', 'Log'), style=T…"
-      ]
-     },
-     "metadata": {},
-     "output_type": "display_data"
-    }
-   ],
+   "outputs": [],
    "source": [
     "widget.display()"
    ]
   },
   {
-   "cell_type": "markdown",
-   "metadata": {},
    "source": [
-    "<div class=\"alert alert-info\">\n",
-    "\n",
-    "Note\n",
-    "    \n",
-    "The GUI is static in the documentation page for demonstration. If you want to interact with the GUI, please run the code in the notebook.\n",
+    "The image below is just a screenshot of the GUI for a demonstration purpose. If you want to interact with the GUI, please run the code in the notebook.\n",
     "\n",
-    "</div>"
-   ]
+    "![Custom Abundance Widget Demo](../images/custom_abundance_widget.png)"
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
   },
   {
    "cell_type": "code",
@@ -39474,4 +39431,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}
diff --git a/docs/io/visualization/using_widgets.rst b/docs/io/visualization/using_widgets.rst
@@ -9,6 +9,82 @@ notebook in action.
 
 Currently, TARDIS supports the following widgets:
 
+Custom Abundance Widget
+#######################
+This widget is a GUI that allows you to develop custom model compositions 
+graphically and output the model to a new file.
+
+.. image:: ../images/custom_abundance_widget.png
+    :alt: Demo of Custom Abundance Widget
+
+The GUI consists of three parts:
+
+1. **Visualization plot** - A step graph generated using `Plotly` that shows 
+abundances and densities as a function of velocity. 
+
+2. **Data editor** - An interface to edit abundances, densities and velocity 
+shells.
+
+3. **File output** - An output module to save the model compositions as a CSVY 
+file.
+
+Interacting with the GUI
+========================
+
+This GUI is developed and composited by `ipywidgets`. Thus you can interact 
+with it in the notebook. There is some main functionality of it.
+
+Edit Abundances
+---------------
+There are two radio buttons which allow you to edit either single shell or 
+mutiple shells. The new input will be applied to selected shell(s) immediately 
+and the plot is updated at the same time. If you want to edit multiple shells 
+at a time, remember to choose the second radio button and set the range of 
+shell number using int slider. The selected shell(s) is highlighted in the 
+plot.
+
+.. image:: ../images/cus_abund_edit_abundance.gif
+    :alt: Demo of editing abundances
+
+Normalize Abundances
+--------------------
+Click `Normalize` button to normalize the abundances on selected shell(s) to 
+1. If you wish to fix the abundance of a certain element during the 
+normalization, you can select the checkbox near that element to lock it. 
+The normalization will be applied to other elements and the sum of the 
+abundances still remains at 1.
+
+.. image:: ../images/cus_abund_norm.gif
+    :alt: Demo of normalization
+
+Edit Densities
+--------------
+In `Edit Density` tab, you also can edit either single shell or the whole 
+density profile. To calculate a new profile, you need to choose the density 
+type and input required parameters.
+
+.. image:: ../images/cus_abund_edit_density.gif
+    :alt: Demo of editing densities
+
+Add New Element
+---------------
+At the bottom of the editor, the symbol input box allows you to add new element 
+or isotope to the model. It automatically recognizes whether the symbol exists 
+or whether the element is already in the model.
+
+.. image:: ../images/cus_abund_add_element.gif
+    :alt: Demo of adding new element
+
+Add New Shell
+-------------
+Another important functionality is to add new shell to the model. You need to 
+specify the velocity range of the new shell and abundances at that new shell 
+will be set to 0. Note that the existing shell(s) might be overwritten after 
+this operation.
+
+.. image:: ../images/cus_abund_add_shell.gif
+    :alt: Demo of adding new shell
+
 Shell Info Widget
 #################