New TARDIS flowchart and cleaning up physics walkthrough (#2111)

* adding in new flowchart

* moving energy deposition pages

* fixing some light-matter physics stuff

* newline

docs/contributing/in_progress/index.rst

@@ -35,6 +35,10 @@ Simulate Supernovae in the Nebular Phase
 * Deposited energy needs to be thermalized by solving the Spencer-Fano equations, resulting in fractions of the energy going into heating, non-thermal excitation and non-thermal ionization.
 * At late times when the densities are low collisions become too infrequent to quickly de-excite metastable energy levels. Forbidden lines arising from these levels need to be included. Transitions between levels have to include ion-electron collisions.
 
+.. toctree::
+    nebular_phase/gammaray_deposition
+    nebular_phase/positronium
+
 
 Implement More Continuum Interactions
 -------------------------------------

docs/index.rst

@@ -79,7 +79,6 @@ Mission Statement
     physics/montecarlo/index
     physics/update_and_conv/update_and_conv
     physics/spectrum/index
-    physics/energy_input/index
 
 
 .. toctree::

docs/physics/intro/index.rst

@@ -9,10 +9,11 @@ How TARDIS Works
 
 The goal of TARDIS is, given input information about a supernova, to determine (i) properties of the plasma making up the supernova and (ii) the spectrum of light that is emitted from the supernova.
 
-The physics of TARDIS is in four major parts, which are summarized here and in the diagram below. First, the TARDIS simulation is set up (:doc:`../setup/index`). This involves the creation of the supernova model and the initial conditions of the supernova's plasma. Next is the Monte Carlo Iteration (:doc:`../montecarlo/index`) where the heart of TARDIS takes place; packets of light are sent through the supernova and tracked as they interact with matter. Next, TARDIS uses information from the Monte Carlo iteration to update properties of the plasma to eventually find the correct plasma state (:doc:`../update_and_conv/update_and_conv`). This process of doing a Monte Carlo iteration and then updating the plasma is repeated for a specified number of times or until certain aspects of the plasma state converge (as is also discussed in :doc:`../update_and_conv/update_and_conv`). After that, data generated in the Monte Carlo simulation is used to synthesize the output spectrum of the supernova (:doc:`../spectrum/index`).
+The physics of TARDIS is in four major parts, which are summarized here and in the diagram below. First, the TARDIS simulation is set up (:doc:`../setup/index`) from a TARDIS configuration (see :doc:`here <../../io/configuration/read_configuration>` for how the configuration is created). This involves the creation of the supernova model and the initial conditions of the supernova's plasma, as well as initializing the Monte Carlo runner. Next is the Monte Carlo Iteration (:doc:`../montecarlo/index`) where the heart of TARDIS takes place; packets of light are sent through the supernova and tracked as they interact with matter. Next, TARDIS uses information from the Monte Carlo iteration to update properties of the plasma to eventually find the correct plasma state (:doc:`../update_and_conv/update_and_conv`). This process of doing a Monte Carlo iteration and then updating the plasma is repeated for a specified number of times or until certain aspects of the plasma state converge (as is also discussed in :doc:`../update_and_conv/update_and_conv`). After that, data generated in the Monte Carlo simulation is used to synthesize the output spectrum of the supernova (:doc:`../spectrum/index`).
 
-.. image:: images/tardis_flowchart.png
-    :width: 200
+In the diagram, each physics step is shown in a box with the name of the step (bolded and underlined) along with the method that triggers the step (italicized) and the major components of the step. The reading of the configuration and the overall itterative process (comprising the Monte Carlo Iteration step and Updating Plasma and Convergence step) are also shown, again with the methods triggering these processes in italics.
+
+.. graphviz:: tardis_flowchart.dot
 
 
 Background Material
@@ -21,4 +22,4 @@ Background Material
 TARDIS is home to an incredibly diverse, multidiciplinary team. As such, we believe that it is important to make an understanding of the physics of TARDIS accessible to all, from students just getting started with physics and astronomy to expert researchers. The following pages are designed to give an overview of the basic physics that TARDIS relies upon to new students or anyone else in need of a refresher!
 
 .. toctree::
-    light_and_matter
+    light_and_matter

docs/physics/intro/light_and_matter.rst

@@ -70,7 +70,7 @@ Excitation (bound-bound interactions)
 
 The first type of light-matter interaction occurs when a photon carrying some energy :math:`E` is absorbed by an electron bound to an atom at an energy level :math:`l` with energy :math:`E_l`, and the electron "jumps" to a higher energy level :math:`u` with energy :math:`E_u` (:math:`l` meaning "lower" and :math:`u` meaning "upper"), as in the diagram below. We say that the electron is **excited** from the lower to higher energy level, and that it goes through a **transition** :math:`l\rightarrow u`. For this to happen, the photon has to have an energy equal to the difference between the two energy levels involved. That is, for an electron to be excited from :math:`l` to :math:`u`, it will gain an energy :math:`E_u-E_l` and thus the photon exciting the electron must have an energy :math:`E_u-E_l` and therefore a frequency :math:`\frac{E_u-E_l}{h}`.
 
-An electron in a higher energy level :math:`u` can also de-excite to a lower energy level :math:`l`, *releasing* a photon of energy :math:`E_u-E_l` and frequency :math:`\frac{E_u-E_l}{h}` (this would be notated as :math:`u\rightarrow l`. Note that if an electron is excited :math:`l\rightarrow u`, it need not de-excite back to the energy level :math:`l` where it began. It could de-excite to any level with a lower energy than :math:`E_u`.
+An electron in a higher energy level :math:`u` can also de-excite to a lower energy level :math:`l`, *releasing* a photon of energy :math:`E_u-E_l` and frequency :math:`\frac{E_u-E_l}{h}` (this would be notated as :math:`u\rightarrow l`). Note that if an electron is excited :math:`l\rightarrow u`, it need not de-excite back to the energy level :math:`l` where it began. It could de-excite to any level with a lower energy than :math:`E_u`.
 
 .. figure:: images/excitation.png
 
@@ -107,17 +107,19 @@ The final type of interaction is electron scattering. This is when a photon coll
     Image from https://en.wikipedia.org/w/index.php?title=File%3ACompton-scattering.svg.
 
 
+.. _opacity:
+
 Opacity and Optical Depth
 =========================
 
 Consider the following experiment -- you fill a clear glass of water completely, shine a light down on it, and look through the bottom of the glass. Then, you drink half of the cup, and repeat. The light coming out from the bottom will be brighter. This is because as light travels through the water, it has a probability of interacting with the matter that makes up the water, and the longer it travels in the water, the more likely it is for the light to interact and thus not come out the other side.
 
 This is described by the Beer-Lambert law, which says that the intensity :math:`I` of light (related to how bright the light is -- more on this soon) after traveling a distance :math:`d` through some material is related to the initial intensity :math:`I_0` of the light before traveling through the material by
 
-.. math:: \frac{I}{I_0} = e^{-\kappa d}
+.. math:: \frac{I}{I_0} = e^{-\alpha d}
 
-where :math:`\kappa` is called the **opacity**. Note that for our purposes, the intensity at some frequency is proportional to the number of photons at that frequency, so :math:`\frac{I}{I_0}` is the fraction of photons who enter the material who do not interact and thus make it out the other side. Note that the opacity can and typically does depend on the frequency of light, which is why we frequently interpret Beer-Lambert's law as applying to a specific frequency.
+where :math:`\alpha` is called the **opacity**. Note that for our purposes, the intensity at some frequency is proportional to the number of photons at that frequency, so :math:`\frac{I}{I_0}` is the fraction of photons who enter the material who do not interact and thus make it out the other side. Note that the opacity can and typically does depend on the frequency of light, which is why we frequently interpret Beer-Lambert's law as applying to a specific frequency.
 
-We can interpret this in the following way: prior to traveling a distance :math:`d`, a photon will have had a :math:`e^{-\kappa d}` probability of *not* interacting with matter (and thus a :math:`1-e^{-\kappa d}` probability of having gone through an interaction). As you would expect, the larger the distance, the more likely it is that a photon interacts prior to traveling that distance, since it would have "more opportunities" to interact. Additionally, a higher :math:`\kappa` means a photon has a higher likelihood of interacting. So, more dense materials, for example, have a higher :math:`\kappa` since there is more matter for the light to interact with. Because :math:`\kappa` must take into account all three types of light-matter interactions, many of which depend on the frequency of light, it can be very difficult to calculate -- this is one of TARDIS's main tasks.
+We can interpret this in the following way: prior to traveling a distance :math:`d`, a photon will have had a :math:`e^{-\alpha d}` probability of *not* interacting with matter (and thus a :math:`1-e^{-\alpha d}` probability of having gone through an interaction). As you would expect, the larger the distance, the more likely it is that a photon interacts prior to traveling that distance, since it would have "more opportunities" to interact. Additionally, a higher :math:`\alpha` means a photon has a higher likelihood of interacting. So, more dense materials, for example, have a higher :math:`\alpha` since there is more matter for the light to interact with. Because :math:`\alpha` must take into account all three types of light-matter interactions, many of which depend on the frequency of light, it can be very difficult to calculate -- this is one of TARDIS's main tasks.
 
-Finally, the term :math:`\kappa d` has a special name: the **optical depth** :math:`\tau`. It is a dimensionless quantity that gives information about how likely it is for a photon to have gone through an interaction. Specifically, there is a :math:`1-e^{-1}\approx 63.2\%` of a photon interacting prior to traveling an optical depth of 1. The actual distance required to travel and optical depth of 1 depends on :math:`\kappa` and thus the material and the frequency of the light.
+Finally, the term :math:`\alpha d` has a special name: the **optical depth** :math:`\tau`. It is a dimensionless quantity that gives information about how likely it is for a photon to have gone through an interaction. Specifically, there is a :math:`1-e^{-1}\approx 63.2\%` of a photon interacting prior to traveling an optical depth of 1. The actual distance required to travel and optical depth of 1 depends on :math:`\alpha` and thus the material and the frequency of the light.

docs/physics/intro/tardis_flowchart.dot

@@ -0,0 +1,19 @@
+digraph {
+    compound = true
+    graph [nodesep=4, ranksep=1]
+    config [label=<<B>Configuration</B><br/><br/> <i>&lt;Configuration object&gt;=Configuration.from_yaml(...)</i><br/> <i>&lt;Configuration object&gt;=Configuration.from_config_dict(...)</i>>, shape=oval]
+    setup_sim [label=<<B><u>Setting up the Simulation</u></B> <br/><br/> <i>&lt;Simulation object&gt;=Simulation.from_config(...)</i> <br/><br/> - Creates and calculates model <br/> - Creates and calculates plasma <br/> - Initializes Monte Carlo runner>, shape=rectangle]
+    mc_iteration [label=<<B><u>Monte Carlo Iteration</u></B> <br/><br/> <i>&lt;Simulation object&gt;.iterate(...)</i><br/> <br/> - Initializes packets <br/> - Propagates packets <br/> - Calculates estimators>, shape=rectangle]
+    adv_state [label=<<B><u>Updating Plasma and Convergence</u></B> <br/><br/> <i>&lt;Simulation object&gt;.advance_state()</i> <br/><br/> - Estimates and updates t_rad, w, and t_inner in model <br/> - Updates plasma <br/> - Checks for convergence>, shape=rectangle]
+    spec_gen [label=<<B><u>Spectrum Generation</u></B> <br/><br/> <i>From final Monte Carlo iteration</i> <br/><br/> - Basic spectrum generation <br/> - Virtual packets <br/> - Formal integral>, shape=rectangle]
+    subgraph cluster1 {
+        style = rounded
+		margin = .25
+		label=<<br/><br/><i>&lt;Simulation object&gt;.run()</i><br/> >;
+		mc_iteration -> adv_state
+        adv_state -> mc_iteration
+	}
+    config -> setup_sim
+    setup_sim -> mc_iteration [lhead=cluster1, minlen=2]
+    adv_state -> spec_gen [ltail=cluster1]
+}

docs/physics/montecarlo/propagation.rst

@@ -165,12 +165,14 @@ Physical Interactions
 As a packet propagates through the computational domain, physical radiation-matter interactions can trigger changes
 in the packet properties. The probability that a photon/packet will interact with matter is characterized by its
 optical depth :math:`\tau`; the probability that a packet will have interacted after going through an optical depth
-:math:`\Delta \tau` is :math:`1-e^{-\Delta \tau}`. To model this (see :ref:`Random Sampling <randomsampling>`), the
+:math:`\Delta \tau` is :math:`1-e^{-\Delta \tau}` (see :ref:`opacity` for more). To model this
+(see :ref:`Random Sampling <randomsampling>`), the
 packet is assigned a random value of optical depth :math:`\tau_\mathrm{interaction} = -\log z` (for another random
 :math:`z` between 0 and 1), and upon reaching that optical depth, the packet will interact.
 
 TARDIS considers two different radiation-matter interactions within the simulation: electron scattering and atomic
-line interactions. As packets propagate, they accumulate optical depth due to the possibility of going through either
+line interactions (see :ref:`light_and_matter` for a basic introduction to these interactions). As packets propagate,
+they accumulate optical depth due to the possibility of going through either
 of these interactions. Since the main focus of TARDIS is to calculate optical spectra,
 electron-scatterings are treated in the elastic low-energy limit as classical
 Thomson scatterings. In this case, the electron scattering process is frequency-independent. As a consequence to the

docs/tardis.bib

@@ -317,3 +317,17 @@ @book{Jauch1976
 	year = {1976},
 	note = {OCLC: 840300942},
 }
+
+@ARTICLE{Ore1949,
+       author = {{Ore}, A. and {Powell}, J.~L.},
+        title = "{Three-Photon Annihilation of an Electron-Positron Pair}",
+      journal = {Physical Review},
+         year = 1949,
+        month = jun,
+       volume = {75},
+       number = {11},
+        pages = {1696-1699},
+          doi = {10.1103/PhysRev.75.1696},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/1949PhRv...75.1696O},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}