Fixing various physics documentation issues (#1928)

* lots of changes

* fixing temperature info

* fixing note about convergence plots

* fixing hyperlink

docs/physics/montecarlo/initialization.ipynb

@@ -7,6 +7,8 @@
    "source": [
     "# Energy Packet Initialization\n",
     "\n",
+    "## Theory\n",
+    "\n",
     "While it is instructive to think about tracking the propagation history of\n",
     "individual photons when illustrating the basic idea behind Monte Carlo radiative transfer\n",
     "techniques, there are important numerical reasons for using a different\n",
@@ -17,7 +19,9 @@
     "are commonly referred to as \"energy packets\" or simply \"packets\", and are composed of many photons with the same frequency.\n",
     "\n",
     "During a Monte Carlo calculation, $N$ (a large number) packets, all with a certain\n",
-    "energy $\\varepsilon$, are created at the inner boundary of the computational domain (which is discussed in [Model of Supernova Domain](../setup/model.rst)) known as the photosphere. Currently, the photosphere is modeled as a spherical blackbody with a radius $R_\\mathrm{phot}$ and temperature $T_\\mathrm{phot}$. In TARDIS, all packets are assigned identical energies, and the total energy of the packets is 1 erg (and thus each packet has an energy of $\\frac{1}{N}$ ergs).\n",
+    "energy $\\varepsilon$, are created at the inner boundary of the computational domain (which is discussed in the [model section](../setup/model.rst)) known as the photosphere. Currently, the photosphere is modeled as a spherical [blackbody](https://en.wikipedia.org/wiki/Black-body_radiation) with a radius $r_\\mathrm{boundary\\_inner}$ and temperature $T_\\mathrm{inner}$. Both of these quantities are calculated as a part of the [model](../setup/model.ipynb), and $T_\\mathrm{inner}$ is additionally updated throughout the simulation as a part of the [convergence](../est_and_conv/convergence.rst) process.\n",
+    "\n",
+    "In TARDIS, all packets are assigned identical energies **in the lab frame** (see [Reference Frames](propagation.rst#reference-frames)), and the total (lab-frame) energy of the packets is 1 erg (and thus each packet has an energy of $\\frac{1}{N}$ ergs).\n",
     "\n",
     "<div class=\"alert alert-info\">\n",
     "    \n",
@@ -27,20 +31,40 @@
     "\n",
     "</div>\n",
     "\n",
-    "Since the photosphere is modeled as a blackbody, its total luminosity $L$ (recall that luminosity is energy emitted divided by the time in which it is emitted) is\n",
-    "$$L=\\frac{N\\varepsilon}{\\Delta t}=4 \\pi R_{\\mathrm{phot}}^2 \\sigma_{\\mathrm{R}} T_{\\mathrm{phot}}^4$$\n",
+    "<div class=\"alert alert-info\">\n",
+    "    \n",
+    "Note\n",
+    "\n",
+    "Since all packets have the same total, and photon energy is proportional to frequency, higher-frequency packets will represent less real photons than lower-frequency packets.\n",
+    "\n",
+    "</div>\n",
+    "\n",
+    "Since the photosphere is modeled as a blackbody, its total luminosity $L_\\mathrm{inner}$ (recall that luminosity is energy emitted divided by the time in which it is emitted) is\n",
+    "$$L_\\mathrm{inner}=\\frac{N\\varepsilon}{\\Delta t}=4 \\pi r_\\mathrm{boundary\\_inner}^2 \\sigma_{\\mathrm{R}} T_{\\mathrm{inner}}^4$$\n",
     "where $\\sigma_\\mathrm{R}$ is the Stefan-Boltzmann constant and $\\Delta t$ is the physical duration of the simulation. In order to make this relationship hold (remembering that $N\\varepsilon = 1$ erg), we use\n",
-    "$$\\Delta t = \\frac{1}{L}=\\frac{1}{4 \\pi R_{\\mathrm{phot}}^2 \\sigma_{\\mathrm{R}} T_{\\mathrm{phot}}^4}.$$\n",
+    "$$\\Delta t = \\frac{1}{L_\\mathrm{inner}}=\\frac{1}{4 \\pi r_\\mathrm{boundary\\_inner}^2 \\sigma_{\\mathrm{R}} T_{\\mathrm{inner}}^4}.$$\n",
     "\n",
-    "During packet initialization, each packet is assigned an initial propagation direction $\\mu$ which is the cosine of the angle $\\theta$ which the packet's path makes with the radial direction. Using a pseudo-random number generator which generates numbers $z$ uniformly distributed on the interval $[0,1]$, the propagation direction is determined according to\n",
+    "<div class=\"alert alert-info\">\n",
+    "    \n",
+    "Note\n",
+    "\n",
+    "As will be shown in the code example, this will lead to unphysically small values for $\\Delta t$. It may be easier to think of the Monte Carlo packets not as packets of energy $\\epsilon$ going through a simulation of duration $\\Delta t$, but as packets of luminosity that carry an energy $\\epsilon$ over a time $\\Delta t$ (and thus truly being luminosity packets of luminosity $\\frac{\\epsilon}{\\Delta t}$). Indeed, this view of the packets will be useful when deriving the [Monte Carlo Estimators](../est_and_conv/estimators.ipynb).\n",
+    "\n",
+    "</div>\n",
+    "\n",
+    "During packet initialization, each packet is assigned an initial propagation direction $\\mu$ which is the cosine of the angle $\\theta$ which the packet's path makes with the radial direction (see the image below). Using a pseudo-random number generator which generates numbers $z$ uniformly distributed on the interval $[0,1]$, the propagation direction is determined (due to physical considerations beyond the scope of this documentation) according to\n",
     "$$\\mu = \\sqrt{z}.$$\n",
-    "This sampling is demonstrated in the code below.\n",
+    "This sampling is shown in the \"Code Example\" section.\n",
+    "\n",
+    "<img src=\"../images/propagation_direction.png\" width=500>\n",
     "\n",
     "Finally, each packet is assigned an initial frequency (or more precisely, the initial frequency of its constituent photons). Note that since each packet has the same energy, each packet will represent a different number of real photons. The sampling on packet frequencies is more involved than that of the propagation direction, as it involves sampling the Planck distribution (see below). TARDIS uses the technique described in <strong data-cite=\"Carter1975\">[]</strong> and summarized in <strong data-cite=\"Bjorkman2001\">[]</strong> for this purpose.\n",
     "\n",
     "During the simulation, the energy of the packet remains constant in the local\n",
     "co-moving frame (see [Reference Frames](propagation.rst#reference-frames)). This naturally ensures energy\n",
-    "conservation and constitutes the main advantage of this discretization scheme. **However, while the energy of the packets is conserved in the co-moving frame, the frequency of the constituent photons (in the local co-moving frame) may vary over the course of the simulation. Thus, a packet may represent several different numbers of real photons throughout their lifetimes.**\n",
+    "conservation and constitutes the main advantage of this discretization scheme. **However, while the energy of the packets is conserved in the co-moving frame, the co-moving frequency of the packet (and thus the photons represented by the packet) may vary over the course of the simulation. Thus, a packet may represent several different numbers of real photons throughout their lifetimes.**\n",
+    "\n",
+    "## Code Example\n",
     "\n",
     "We now demonstrate the TARDIS packet initialization framework:"
    ]
@@ -67,7 +91,7 @@
    "id": "4ae02998",
    "metadata": {},
    "source": [
-    "The following cell contains values that you can change to see how it affects the spectrum:"
+    "The following cell contains values that you can change to see how it affects the spectrum (in an actual simulation, the seed and number of packets are set in the [Monte Carlo configuration](../../io/configuration/components/montecarlo.rst), and the photospheric radius is calculated as a part of the [model](../setup/model.ipynb)):"
    ]
   },
   {
@@ -80,55 +104,37 @@
     "# Seed for the pseudo-random number generator\n",
     "seed = 1\n",
     "\n",
-    "# Radius of the supernova's photosphere in cm\n",
-    "r_phot = 1e15 * u.cm\n",
-    "\n",
     "# Number of packets generated\n",
-    "n_packets = 40000"
+    "n_packets = 40000\n",
+    "\n",
+    "# Radius of the supernova's photosphere in cm\n",
+    "r_boundary_inner = 1e15 * u.cm"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "450faf76",
    "metadata": {},
    "source": [
-    "You can either set a temperatature of the photosphere, which will determine its luminosity; or you can set the luminosity of the photosphere, which will determine its temperature."
+    "We set the temperature of the photosphere $T_\\mathrm{inner}$, which will determine the photospheric luminosity (in an actual simulation, $T_\\mathrm{inner}$ is initially calculated as a part of the [model](../setup/model.ipynb) and updated as a part of the [convergence](../est_and_conv/convergence.rst) process):"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "8f2c15a9",
+   "id": "3fb3ca8c",
    "metadata": {},
    "outputs": [],
    "source": [
     "# Temperature in K\n",
-    "temperature = 10000 * u.K\n",
+    "temperature_inner = 10000 * u.K\n",
     "\n",
-    "luminosity = 4 * np.pi * (r_phot**2) * const.sigma_sb * (temperature**4)\n",
+    "luminosity_inner = 4 * np.pi * (r_boundary_inner**2) * const.sigma_sb * (temperature_inner**4)\n",
     "\n",
     "# Makes sure the luminosity is given in erg/s\n",
-    "luminosity = luminosity.to('erg/s')\n",
-    "\n",
-    "print('Luminosity:', luminosity)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "3fb3ca8c",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Luminosity in erg/s\n",
-    "luminosity = 7e42 * u.erg / u.s\n",
-    "\n",
-    "temperature = (luminosity / (4 * np.pi * const.sigma_sb))**0.25 / np.sqrt(r_phot)\n",
-    "\n",
-    "# Makes sure the termperature is given in K\n",
-    "temperature = temperature.to('K')\n",
+    "luminosity_inner = luminosity_inner.to('erg/s')\n",
     "\n",
-    "print('Temperature:', temperature)"
+    "print('Luminosity of photosphere:', luminosity_inner)"
    ]
   },
   {
@@ -150,10 +156,10 @@
     "packet_source = BlackBodySimpleSource(seed)\n",
     "\n",
     "radii, nus, mus, energies = packet_source.create_packets(\n",
-    "    temperature.value, \n",
+    "    temperature_inner.value, \n",
     "    n_packets, \n",
     "    rng, \n",
-    "    r_phot)\n",
+    "    r_boundary_inner)\n",
     "\n",
     "# Sets the energies in units of ergs\n",
     "energies *= u.erg\n",
@@ -181,7 +187,7 @@
    "outputs": [],
    "source": [
     "# Time of simulation\n",
-    "t_simulation = 1 * u.erg / luminosity\n",
+    "t_simulation = 1 * u.erg / luminosity_inner\n",
     "print('Time of simulation:', t_simulation)\n",
     "\n",
     "# Array of luminosity contribution by each packet\n",
@@ -195,7 +201,7 @@
    "metadata": {},
    "source": [
     "We define important constants, and for comparison's sake, we code the Planck distribution function\n",
-    "$$L_\\nu (\\nu)=\\frac{8\\pi R_\\mathrm{phot}^2 h\\nu^3}{c^2}\\frac{1}{\\exp\\left(\\frac{h\\nu}{k_BT_\\mathrm{phot}}\\right)-1}$$\n",
+    "$$L_\\nu (\\nu)=\\frac{8\\pi r_\\mathrm{boundary\\_inner}^2 h\\nu^3}{c^2}\\frac{1}{\\exp\\left(\\frac{h\\nu}{k_BT_\\mathrm{inner}}\\right)-1}$$\n",
     "where $L_\\nu$ is the luminosity density (see [Basic Spectrum Generation](../spectrum/basic.ipynb)) with respect to frequency, $\\nu$ is frequency, $h$ is Planck's constant, $c$ is the speed of light, and $k_B$ is Boltzmann's constant:"
    ]
   },
@@ -213,7 +219,7 @@
     "kB = const.k_B.cgs\n",
     "\n",
     "def planck_function(nu):\n",
-    "    return 8 * np.pi**2 * r_phot**2 * h * nu**3 / (c2 * (np.exp(h * nu / (kB * temperature)) - 1))"
+    "    return 8 * np.pi**2 * r_boundary_inner**2 * h * nu**3 / (c2 * (np.exp(h * nu / (kB * temperature_inner)) - 1))"
    ]
   },
   {
@@ -304,7 +310,7 @@
  "metadata": {
   "celltoolbar": "Raw Cell Format",
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -318,7 +324,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.10"
+   "version": "3.7.12"
   }
  },
  "nbformat": 4,

docs/physics/montecarlo/propagation.rst

@@ -260,7 +260,9 @@ interaction with the corresponding atomic line transition. In both of these case
 interaction location, the interaction will be performed (as will be described in the next section), and the process
 of accumulating optical depth starts over. Finally, if the packet reaches the shell boundary before the optical depth
 value necessary for a physical interaction is achieved (as in case III), the packet will be moved to the next cell,
-the plasma properties will be updated, and the accumulation of optical depth will continue in the next cell.
+the plasma properties will be updated, and the accumulation of optical depth will **restart** in the next cell.
+
+.. note:: While it would make physical sense for the accumulation of optical depth to continue between cells until the packet eventually interacts, due do the exponential nature of optical depth and interaction probabilities, both continuing and restarting the accumulation of optical depth between cells can be mathematically shown to yield the same overall statistical results. Restarting the optical depth accumulation is computationally easier, and hence it is the method employed by TARDIS.
 
 Performing an Interaction
 -------------------------

docs/physics/setup/model.ipynb

@@ -469,17 +469,17 @@
    "id": "9fded236",
    "metadata": {},
    "source": [
-    "## Radiative Temperature\n",
+    "## Temperatures\n",
     "\n",
-    "Next, TARDIS finds the temperature of the plasma in each cell, called the radiative temperature. In fact, this temperature changes throughout the simulation based on light-matter interations (see [Estimators and Convergence](../est_and_conv/index.ipynb)). When the model is initiated, TARDIS must calculate an initial guess for the radiative temperature in each shell.\n",
+    "The model also includes information about the temperature of the photosphere/inner boundary, labeled as $T_\\mathrm{inner}$, and the temperature of the plasma in each cell, called the radiative temperature and labeled as $T_\\mathrm{rad}$. As will be explained, both of these quantities are be updated throughout the simulation, so the calculations in this section are the initial guesses.\n",
     "\n",
-    "To do this, TARDIS also calculates the temperature at the surface of the photosphere $T_\\mathrm{inner}$. This is calculated as the temperature of a blackbody:\n",
+    "TARDIS initially calculates $T_\\mathrm{inner}$ as the temperature of a [blackbody](https://en.wikipedia.org/wiki/Black-body_radiation) such that the luminosity of the photosphere (see [initialization](../montecarlo/initialization.ipynb)) matches the requested output luminosity of the entire supernova $L_\\mathrm{requested}$, which is specified in the [spectrum configuration](../../io/configuration/components/spectrum.rst):\n",
     "\n",
-    "$$T_{\\mathrm{inner}}=\\left(\\frac{L}{4 \\pi r_{\\mathrm{boundary\\_inner}}^2 \\sigma_{\\mathrm{R}}}\\right)^{1/4}$$\n",
+    "$$T_{\\mathrm{inner}}=\\left(\\frac{L_\\mathrm{requested}}{4 \\pi r_{\\mathrm{boundary\\_inner}}^2 \\sigma_{\\mathrm{R}}}\\right)^{1/4}$$\n",
     "\n",
-    "where $\\sigma_{\\mathrm{R}}$ is the Stefan-Boltzmann constant, $r_{\\mathrm{boundary\\_inner}}$ is the radius of the photosphere, and $L$ is the luminosity of the photosphere (this is initially taken as the requested luminosity of the supernova, though it is changed throughout the simulation as part of the [convergence](../est_and_conv/convergence.rst)). This calculation is also described in [Energy Packet Initialization](../montecarlo/initialization.ipynb).\n",
+    "where $\\sigma_{\\mathrm{R}}$ is the Stefan-Boltzmann constant and $r_{\\mathrm{boundary\\_inner}}$ is once again the radius of the photosphere, calculated as part of the shell structure. Because of light-matter interactions, the output luminosity of the supernova will not be the same as the luminosity of the photosphere, so the photospheric temperature is updated throughout the simulation as part of the convergence process in order to match the output luminosity to the requested luminosity (see [convergence](../est_and_conv/convergence.rst)).\n",
     "\n",
-    "TARDIS calculates the initial guess for the radiative temperature using Wein's Law. Wein's Law states that the temperature of a blackbody is inversely proportional to the blackbody's peak wavelength. The proportionality constant, labeled $b$, is approximately $2.898*10^{-3} m*K$. In equation form,\n",
+    "Next, TARDIS calculates the initial guess for the radiative temperature in each shell. This temperature is also updated throughout the simulation based on light-matter interactions (see [Estimators and Convergence](../est_and_conv/index.ipynb)). The initial guess for $T_\\mathrm{rad}$ is calculated using Wein's Law. Wein's Law states that the temperature of a blackbody is inversely proportional to the blackbody's peak wavelength. The proportionality constant, labeled $b$, is approximately $2.898*10^{-3} m*K$. In equation form,\n",
     "\n",
     "$$T=\\frac{b}{\\lambda_\\mathrm{peak}}.$$\n",
     "\n",
@@ -489,7 +489,7 @@
     "\n",
     "Thus, the temperature at a velocity $v$ is\n",
     "\n",
-    "$$T(v)=\\frac{b}{\\lambda_\\mathrm{peak}(v)}=\\frac{T_\\mathrm{inner}}{1-\\frac{v-v_\\mathrm{boundary\\_inner}}{c}}.$$\n",
+    "$$T_\\mathrm{rad}(v)=\\frac{b}{\\lambda_\\mathrm{peak}(v)}=\\frac{T_\\mathrm{inner}}{1-\\frac{v-v_\\mathrm{boundary\\_inner}}{c}}.$$\n",
     "\n",
     "As with density, the radiative temperature is modeled as constant throughout the shell, so we determine the temperature of the shell based on the ejecta's velocity at the center of the shell.\n",
     "\n",

docs/physics/spectrum/basic.ipynb

@@ -147,6 +147,20 @@
     "len(nus), len(energies)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "70c979d2",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "Note\n",
+    "\n",
+    "The energies used for the spectrum are in the lab frame (see [Reference Frames](../montecarlo/propagation.rst#reference-frames)). Recall that while packets are all initialized with the same energy in the lab frame, throughout the simulation energy is conserved in the co-moving frame, allowing the lab frame energies of the packets to change though interactions (see [Performing an Interaction](../montecarlo/propagation.rst#performing-an-interaction)), creating the varied lab-frame energies that we see at the end of the simulation.\n",
+    "    \n",
+    "</div>"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "54466d70",
@@ -414,7 +428,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -428,7 +442,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.10"
+   "version": "3.7.12"
   }
  },
  "nbformat": 4,

docs/quickstart.ipynb

@@ -92,19 +92,6 @@
     "sim = run_tardis('tardis_example.yml')"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "<div class=\"alert alert-info\">\n",
-    "    \n",
-    "Note\n",
-    "\n",
-    "When running this notebook locally or in interactive mode, a [convergence plot](io/visualization/convergence_plot.ipynb) will show up.\n",
-    "\n",
-    "</div>"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -140,7 +127,8 @@
    "hash": "14c438b85bc0c5441332c56c5d68185f391ef15672c5492b27fc26d9164316c1"
   },
   "kernelspec": {
-   "display_name": "Python 3.7.10 64-bit ('tardis': conda)",
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
    "name": "python3"
   },
   "language_info": {
@@ -153,7 +141,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.10"
+   "version": "3.7.12"
   }
  },
  "nbformat": 4,