diff --git a/.gitignore b/.gitignore index 800b0fc510f..95b55b93422 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,11 @@ *.o *.so __pycache__ +docs/io/output/plasma_graph_default.tex +docs/io/output/plasma_graph_scaled.tex +docs/io/output/plasma_graph_no_eq.tex +docs/io/output/plasma_graph_with_args.tex + # Ignore .c files by default to avoid including generated code. If you want to # add a non-generated .c extension, use `git add -f filename.c`. diff --git a/docs/io/output/default_plasma_graph.png b/docs/io/output/default_plasma_graph.png new file mode 100644 index 00000000000..4e3d9fca5b2 Binary files /dev/null and b/docs/io/output/default_plasma_graph.png differ diff --git a/docs/io/output/index.rst b/docs/io/output/index.rst index bb9f5650bc0..712a8e4e0cb 100644 --- a/docs/io/output/index.rst +++ b/docs/io/output/index.rst @@ -14,3 +14,4 @@ In addition to the widgets, TARDIS can output information in several other forms vpacket_logging progress_bars rpacket_tracking + plasma_graph diff --git a/docs/io/output/plasma_graph.ipynb b/docs/io/output/plasma_graph.ipynb new file mode 100644 index 00000000000..f9f584b98ae --- /dev/null +++ b/docs/io/output/plasma_graph.ipynb @@ -0,0 +1,390 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "c7835cf9", + "metadata": {}, + "source": [ + "# Generating the Plasma Graph" + ] + }, + { + "cell_type": "markdown", + "id": "0329e9f4", + "metadata": {}, + "source": [ + "After running a simulation, TARDIS has the ability to create a [graph](https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)) showcasing how each variable used to compute the plasma state is connected and calculated (see the [Plasma Documentation](../../physics/setup/plasma/index.rst) for more information). To do so, one needs to utilize the `write_to_tex` command to generate a .tex file that displays the graph. This tutorial aims to showcase how the .tex file can be generated and what options can be inputted to display the graph in a preferred method. To start, TARDIS needs to perform a simulation. Here the `tardis_example.yml` configuration file is used as in the [quickstart guide](../../quickstart.ipynb)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b9fbaaa9", + "metadata": {}, + "outputs": [], + "source": [ + "#downloading necessary modules\n", + "from tardis import run_tardis\n", + "from tardis.io.atom_data.util import download_atom_data\n", + "\n", + "import networkx as nx\n", + "\n", + "from IPython.core.display import Image, display" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "631f5cd2", + "metadata": {}, + "outputs": [], + "source": [ + "#downloading atom data\n", + "download_atom_data('kurucz_cd23_chianti_H_He')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2212037a", + "metadata": {}, + "outputs": [], + "source": [ + "#running simulation\n", + "sim = run_tardis('tardis_example.yml')" + ] + }, + { + "cell_type": "markdown", + "id": "2eff6574", + "metadata": {}, + "source": [ + "## Displaying the Graph Within A Jupyter Notebook" + ] + }, + { + "cell_type": "markdown", + "id": "12802d67", + "metadata": {}, + "source": [ + "Now that TARDIS has finished a simulation run, the plasma graph can now be generated. To display the basic graph within a Jupyter Notebook, one can simply use the `nx.draw` as follows: " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ca47e24a", + "metadata": {}, + "outputs": [], + "source": [ + "%pylab inline\n", + "\n", + "nx.draw(sim.plasma.graph)" + ] + }, + { + "cell_type": "markdown", + "id": "54a7c171", + "metadata": {}, + "source": [ + "There are many different ways of displaying the graph in a more readable format. One such example is shown below." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6cf742ed", + "metadata": {}, + "outputs": [], + "source": [ + "position = nx.spring_layout(sim.plasma.graph, k=0.75, iterations=15)\n", + "\n", + "nx.draw(sim.plasma.graph, position, with_labels=True)" + ] + }, + { + "cell_type": "markdown", + "id": "671db7f1", + "metadata": {}, + "source": [ + "
\n", + " \n", + "Note\n", + "\n", + "For the purposes of this tutorial, pylab inline has been used to display the graph within the tutorial page. It is recommended to use pylab notebook when displaying the graph on a local Jupyter Notebook to explore the nodes in depth.\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "31f0fc69", + "metadata": {}, + "source": [ + "## Saving the Graph Onto a .tex File" + ] + }, + { + "cell_type": "markdown", + "id": "c4bbc23e", + "metadata": {}, + "source": [ + "With the `write_to_tex` command, a copy of the graph can be saved within a .tex file. Currently, there are four parameters TARDIS uses to write the graph in [LaTeX](https://en.wikipedia.org/wiki/LaTeX) and save it to a .tex file:\n", + "\n", + " \n", + "\n", + "With these parameters, TARDIS can write the graph in many different ways. For this tutorial, only a few examples will be shown to display what each parameter exactly does and what the resulting graph will look like when generated in a LaTeX environment. " + ] + }, + { + "cell_type": "markdown", + "id": "2347c37b", + "metadata": {}, + "source": [ + "
\n", + " \n", + "Warning\n", + "\n", + "As of now, TARDIS has an issue of not spacing edges correctly, causing the default output to look very condensed and unreadable in certain areas. It is recommended, therefore, to use the given parameters to generate a graph that displays everything in as readable a format as possible. \n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "8bbac606", + "metadata": {}, + "source": [ + "### Default Plasma Graph" + ] + }, + { + "cell_type": "markdown", + "id": "bb12a9e1", + "metadata": {}, + "source": [ + "From above, TARDIS only needs the name of the file it should save the graph to as default." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b3bd85b7", + "metadata": {}, + "outputs": [], + "source": [ + "sim.plasma.write_to_tex(\"plasma_graph_default.tex\")" + ] + }, + { + "cell_type": "markdown", + "id": "d0ab8466", + "metadata": {}, + "source": [ + "With the default settings, the contents of the file will simply be the graph written in LaTeX.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "45288d3b", + "metadata": {}, + "outputs": [], + "source": [ + "with open(\"plasma_graph_default.tex\", \"r\") as file:\n", + " print(file.read())\n", + " file.close()" + ] + }, + { + "cell_type": "markdown", + "id": "33c2a897", + "metadata": {}, + "source": [ + "If one was to build the .tex file, the following graph will be generated:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2ad68ca3", + "metadata": {}, + "outputs": [], + "source": [ + "display(Image('default_plasma_graph.png', unconfined=True))" + ] + }, + { + "cell_type": "markdown", + "id": "e89230d5", + "metadata": {}, + "source": [ + "
\n", + " \n", + "Note\n", + "\n", + "For the remainder of this tutorial, the contents of the .tex file will be omitted and only the generated graph will be shown.\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "815dd554", + "metadata": {}, + "source": [ + "### Plasma Graph with Different Scale" + ] + }, + { + "cell_type": "markdown", + "id": "00ad603d", + "metadata": {}, + "source": [ + "One can change the scaling of the graph by passing in a positive, non-zero float into the `scale` parameter to either make the resulting graph larger (scale > 0.5) or smaller (scale < 0.5)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1f4dab02", + "metadata": {}, + "outputs": [], + "source": [ + "sim.plasma.write_to_tex(\"plasma_graph_scaled.tex\", scale = 1.25)" + ] + }, + { + "cell_type": "markdown", + "id": "73c2a8af", + "metadata": {}, + "source": [ + "With a scale of 1.25, the graph TARDIS will output will look as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9b85ef0a", + "metadata": {}, + "outputs": [], + "source": [ + "display(Image('plasma_graph_scaled.png', unconfined=True))" + ] + }, + { + "cell_type": "markdown", + "id": "6661eeae", + "metadata": {}, + "source": [ + "### Plasma Graph with No Equations\n", + "\n", + "TARDIS has the option to generate a graph without any equations or edge labels via the `latex_label` command. The graph in this case will only consist of nodes containing the names of variables used to calculate the plasma state connected with edges." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "764aa91a", + "metadata": {}, + "outputs": [], + "source": [ + "sim.plasma.write_to_tex(\"plasma_graph_no_eq.tex\", latex_label=False)" + ] + }, + { + "cell_type": "markdown", + "id": "3335a526", + "metadata": {}, + "source": [ + "With these inputs, the graph will look like this:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7e97c276", + "metadata": {}, + "outputs": [], + "source": [ + "display(Image('plasma_graph_no_eq.png', unconfined=True))" + ] + }, + { + "cell_type": "markdown", + "id": "43196f07", + "metadata": {}, + "source": [ + "### Plasma Graph with Inputted Arguments\n", + "\n", + "In order to create the .tex file, TARDIS will first convert the graph into a readable [DOT](https://graphviz.org/doc/info/lang.html) format via the `write_to_dot` function. As such, using the `args` parameter within the `write_to_tex` function, one can pass in any Graphviz attribute for TARDIS to implement as a list. In this example, the following attributes are used:\n", + "\n", + " \n", + "\n", + "For more information on these attributes, visit the [Graphviz attributes documentation](https://graphviz.org/doc/info/attrs.html)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0bd9b8dd", + "metadata": {}, + "outputs": [], + "source": [ + "attributes_list = [r\"nodesep=1.0\", r'edge[lblstyle=\"fill=white\"]', r'margin=0', r'ratio=\"fill\"', r'size=\"8.3,11.7!\"']\n", + "\n", + "sim.plasma.write_to_tex(\"plasma_graph_with_args.tex\", args=attributes_list)" + ] + }, + { + "cell_type": "markdown", + "id": "858b7509", + "metadata": {}, + "source": [ + "With these attributes, the following graph can be generated:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e8018b7f", + "metadata": {}, + "outputs": [], + "source": [ + "display(Image('plasma_graph_args.png', unconfined=True))" + ] + } + ], + "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.12" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/io/output/plasma_graph_args.png b/docs/io/output/plasma_graph_args.png new file mode 100644 index 00000000000..1526f5807ab Binary files /dev/null and b/docs/io/output/plasma_graph_args.png differ diff --git a/docs/io/output/plasma_graph_no_eq.png b/docs/io/output/plasma_graph_no_eq.png new file mode 100644 index 00000000000..938498baba2 Binary files /dev/null and b/docs/io/output/plasma_graph_no_eq.png differ diff --git a/docs/io/output/plasma_graph_scaled.png b/docs/io/output/plasma_graph_scaled.png new file mode 100644 index 00000000000..ec7a5e41fdc Binary files /dev/null and b/docs/io/output/plasma_graph_scaled.png differ diff --git a/docs/physics/setup/plasma/index.rst b/docs/physics/setup/plasma/index.rst index cb6f8369016..6d0c26ad7ff 100644 --- a/docs/physics/setup/plasma/index.rst +++ b/docs/physics/setup/plasma/index.rst @@ -37,10 +37,12 @@ Every property has a `calculate` function that returns the values of its outputs The Plasma Graph ---------------- -If the necessary Python modules (`PyGraphviz `_ and `dot2tex `_) are available, TARDIS can output a .dot and a .tex file at the beginning of each run that can be compiled to produce a PDF image of the plasma module graph via the :code:`write_to_dot()` and :code:`write_to_tex()` functions, respectively. The nodes on this graph are the names of plasma properties, e.g. `Levels`, `TauSobolev`, `IonNumberDensity`, along with a list of outputs from those properties. These nodes are connected by edges linking them with the sources of their inputs. The .tex file contains the name of the input/output linking the properties (e.g. `levels`, :math:`\tau_{\textrm{sobolev}}`, :math:`n_{e}`), as well as the equations used to calculate them, written in LaTeX. Tutorial coming soon! +If the necessary Python modules (`PyGraphviz `_ and `dot2tex `_) are available, TARDIS can output a .dot and a .tex file at the beginning of each run that can be compiled to produce a PDF image of the plasma module graph via the :code:`write_to_dot()` and :code:`write_to_tex()` functions, respectively. The nodes on this graph are the names of plasma properties, e.g. `Levels`, `TauSobolev`, `IonNumberDensity`, along with a list of outputs from those properties. These nodes are connected by edges linking them with the sources of their inputs. The .tex file contains the name of the input/output linking the properties (e.g. `levels`, :math:`\tau_{\textrm{sobolev}}`, :math:`n_{e}`), as well as the equations used to calculate them, written in LaTeX. See the tutorial below! -.. note:: - When building the graph, the length of each edge is randomized to minimize overlap between edge labels. +.. toctree:: + :maxdepth: 2 + + ../../../io/output/plasma_graph Updating the Plasma -------------------