Restructure Documentation pt. 2 (#1659)

* making new files

* editing physics content and moving images

* error fixes and writing content

* basic spectrum and pyplot filepath

* more content and hyperlink fixes

* [build docs]

* making basic principles in terms of photons and fixing headings in propagation

* [build docs]

* [build docs]

docs/physics/est_and_conv/convergence.rst

@@ -0,0 +1,7 @@
+.. _convergence:
+
+***********
+Convergence
+***********
+
+Coming soon.

docs/physics/est_and_conv/index.rst

@@ -4,6 +4,29 @@
 Estimators and Convergence
 **************************
 
+As light travels through a real plasma, it has effects on the properties of the plasma due to light-matter
+interactions as well as the presence of extra energy from the light. Additionally, as :ref:`previously discussed
+<propagation>`, properties of the plasma affect how light travels through it. Things like this (where two things
+both affect each other on different ways) frequently occur in physics. The solution is finding a steady-state for
+the plasma properties; that is, the actual plasma will be in a state such that the plasma state will not change as
+light propagates through it, because the effects of the light on the plasma and the effects of the plasma on the
+light have been "balenced out."
+
+One of TARDIS's main goals is to determine this plasma state (as we need the actual plasma properties in order to
+get an accurate spectrum). This is done in an iterative process. After each :ref:`Monte Carlo iteration
+<montecarlo>` (which sends light through the supernova ejecta), TARDIS uses objects called estimators to determine
+how the propagating light affects the plasma state, after which the plasma state is updated (as will be demonstrated
+in the eatimators page linked below). We do this many times, and attempt to have the plasma state converge
+to the steady-state we are looking for. In fact, all but the last Monte Carlo iteration is used for this purpose
+(after which TARDIS will have the needed plasma state for its last iteration which calculates the spectrum).
+
+.. note::
+    For all but the last iteration, TARDIS uses the number of Monte Carlo packets specified in the
+    :ref:`configuration file <montecarlo-config>` under the ``no_of_packets`` argument. This is because
+    a different number of packets may be necessary to calculate the spectrum as opposed to calculate the
+    plasma state.
+
 .. toctree::
 
-    estimators
+    estimators
+    convergence

docs/physics/montecarlo/basicprinciples.rst

@@ -4,25 +4,126 @@
 Monte Carlo Radiative Transfer - Basic Principles
 *************************************************
 
-Radiative transfer describes how the properties of the electromagnetic
-radiation field change as it propagates through an ambient material. Due to the
-complex coupling induced by the many interactions the photons which constitute
-the radiation field may perform with the surrounding material, solving the
-radiative transfer problem is in most astrophysical cases only possible by
-means of numerical calculations. While there are many different numerical
-techniques available to tackle this, Monte Carlo techniques have become a
-successful and elegant tool particularly for radiative transfer problems in
-supernovae.
-
-Monte Carlo Radiative Transfer methods are probabilistic techniques and draw
-inspiration from the microscopical interpretation of how photons propagate
-through and interact with the ambient material. A sufficiently large number of
-representative "machine photons" are considered and their propagation history
-solved in a stochastic process. The initial properties of these photons are
-randomly (in a probabilistic sense) assigned in accordance with the macroscopic
-properties of the radiation field (see :ref:`Energy Packets <initialization>`)
-and in a similar manner the decisions about when, where and how the machine
-photons interact with the surrounding material are made (see :ref:`Propagation
-<propagation>`). If this process is repeated for a large enough number of machine
-photons, the ensemble behaviour and thus the macroscopic evolution of the
-radiation field is recovered (see :ref:`Estimators <estimators>`).
+Radiative transfer describes how electromagnetic radiation (light) propagates through a medium. Since there are
+a large number of light-matter interactions that have the possibility of affecting the light propagation, solving
+the radiative transfer problem is in most astrophysical cases only possible by means of numerical calculations.
+While there are many different numerical techniques available to tackle this, Monte Carlo techniques have become a
+successful and elegant tool particularly for radiative transfer problems in supernovae.
+
+Monte Carlo Radiative Transfer methods track a sufficiently large number of photons (light particles) as they
+propagate through the supernova ejecta. The initial properties of these photons are randomly (in a probabilistic
+sense) assigned in accordance with the macroscopic properties of the radiation field (see :ref:`initialization`)
+and in a similar manner the decisions about when, where and how the photons interact with the surrounding material
+are made (see :ref:`Propagation <propagation>`). Given a large enough sample, these photons behave as a microcosom
+of all of the light traveling through the ejecta -- that is, based on the behavior of these photons, we can draw
+conclusions about the propagation of light through the ejecta as a whole. This is eventually used to determine the
+actual steady-state plasma properties (see :ref:`est_and_conv`) and the emitted spectrum (see :ref:`spectrum`).
+
+
+.. _randomsampling:
+
+Random Sampling Basics
+======================
+
+During both the initialization of these photons and their propagation through the ejecta are modeled through
+probabilistic processes. This involves assigning probabilities to the occurrence of certain events or properties.
+For example, during isotropic scattering, finding a photon scattering into any given direction is equally likely.
+During the Monte Carlo simulation, assignments
+according to these probabilities have to be frequently performed. For this purpose, so-called Random
+Number Generators are available. These produce (pseudo-) random numbers
+:math:`z` uniformly distributed on the interval :math:`[0,1]`. The challenge
+now lies in using these numbers to sample any physical process involved in the
+Radiative transfer calculation. From a probability theory point of view, this
+just implies finding a mapping between the probability distribution governing the
+physical process and the one underlying the Random Number Generator. This
+process is typically referred to as random sampling.
+
+Inverse transformation method
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+    This is a very superficial and sloppy description of Random sampling. More
+    detailed and rigorous accounts are found in the standard literature, for
+    example in :cite:`Kalos2008`.
+
+The simplest and most-used technique in Monte Carlo radiative transfer
+applications is referred to as the inverse transformation method and involves
+the cumulative distribution function. In general, a random process captured by
+the random variable :math:`X` is governed by a probability density
+:math:`\rho_X(x)` (the continuous counterpart to discrete probabilities), with
+:math:`\rho_X(x) \mathrm{d}x` describing the probability of the variable taking
+values in the interval :math:`[x, x+\mathrm{d}x]`. The cumulative distribution
+function in turn describes, as the name suggests, the probability of the
+variable taking any value between :math:`-\infty` and :math:`x`:
+
+.. math::
+
+    f_X(x) = \int_{-\infty}^x \mathrm{d}x \rho_X(x)
+
+Since the probability density is by definition always positive, the cumulative
+distribution function is monotonically increasing. This constitutes the basis
+for the inverse transformation function. Consider two random variables,
+:math:`X` and :math:`Y`. A mapping between those may be established by equating
+their cumulative distribution functions. Numbers :math:`y` distributed
+according to one of the probability densities (in this case :math:`\rho_Y(y)`)
+may then be used to sample the other process by
+
+.. math::
+
+  x = f_X^{-1}\left(f_Y(y)\right).
+
+For the Random Number Generators described above, the cumulative distribution
+function is trivial, namely :math:`f_Z(z) = z`. However, the inverse
+distribution sampling method relies on finding the analytic inverse function of
+the cumulative distribution function governing the physical processes to be
+sampled. If this is not possible, other sampling methods, such as von-Neumann
+rejection sampling techniques, have to be used.
+
+Examples
+^^^^^^^^
+
+A few examples are provided to illustrate the random sampling process using the
+inverse transformation technique.
+
+Isotropic Scattering
+--------------------
+
+Consider the case of an isotropic scattering.
+Here, all scattering angles are equally likely. Thus, the corresponding
+(normalized) probability density and the cumulative distribution function are given by
+
+.. math::
+
+    \rho_{\mu}(\mu) &= \frac{1}{2}\\
+    f_{\mu}(\mu) &= \frac{1}{2} (\mu - 1).
+
+This leads to the sampling rule
+
+.. math::
+
+    \mu = 2 z - 1.
+
+Next Interaction Location
+-------------------------
+
+The probability of a photon interacting after covering an optical depth
+:math:`\tau` is given by (see :ref:`propagation`)
+
+.. math::
+
+    \rho_{\tau}(\tau) &= \exp(-\tau)\\
+    f_{\tau}(\tau) &= 1 - \exp(-\tau).
+
+
+With the inverse transformation method, the optical depth to the next interaction location may then be sampled by 
+
+.. math::
+
+    \tau = - \mathrm{ln}(1 - z)
+  
+    
+which is equivalent to
+
+.. math::
+
+    \tau = - \mathrm{ln}z.

docs/physics/montecarlo/index.rst

@@ -4,6 +4,12 @@
 Monte Carlo Iteration
 *********************
 
+After setting up the simulation, TARDIS runs the simulation using the ``.run()`` method. This runs several Monte
+Carlo iterations (which will be described in the links below), corresponding to the number of iterations specified
+in the :ref:`Monte Carlo Configuration <montecarlo-config>`. As will be decribed in :ref:`est_and_conv` and
+:ref:`spectrum`, most of these iterations will eventually be used to calculate the steady-state plasma properties,
+with the last iteration being used to determine the spectrum.
+
 The following pages provide a very basic introduction to Monte Carlo radiative
 transfer techniques as they are used in TARDIS. All the information listed here
 can also be found in various papers by L. Lucy and in the main TARDIS publication
@@ -12,11 +18,9 @@ can also be found in various papers by L. Lucy and in the main TARDIS publicatio
 :cite:`Kerzendorf2014`).
 
 .. toctree::
+    :maxdepth: 2
+
     basicprinciples
     initialization
     propagation
-    lineinteraction
-    estimators
-    virtualpackets
-    sourceintegration
-    randomsampling
+    lineinteraction

docs/physics/montecarlo/initialization.ipynb

@@ -20,7 +20,7 @@
    "metadata": {},
    "source": [
     "While it is instructive to think about tracking the propagation history of\n",
-    "photons when illustrating the basic idea behind Monte Carlo radiative transfer\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",
     "discretization scheme. Instead of thinking in the photon picture, it brings\n",
     "significant advantages to follow the idea of <strong data-cite=\"Abbott1985\">[]</strong> and\n",
@@ -29,7 +29,7 @@
     "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 (as will be discussed in [Packet Propagation](propagation.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 [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",
     "\n",
     ".. note:: The indivisible energy packet scheme does not require that all packets have the same energy. This is just a convenient and simple choice adopted in TARDIS.\n",
     "\n",
@@ -329,4 +329,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

docs/physics/montecarlo/lineinteraction.rst

@@ -96,5 +96,5 @@ shows the situation in the resonant scatter mode, the middle one for the
 downbranching scheme and the right one the macro atom results.
 
 .. image::
-    images/scatter_downbranch_ma.png
+    ../images/scatter_downbranch_ma.png
     :width: 700