Adding Interactive Initialization Documentation (#1589)

* creating energypackets notebook

* more additions to energypackets page

* finished notebook aspect of energy packet docs

* important small changes

* wrote a section before the python code

* final changes

* fixing typos

* a few changes

* adding more info to the custom_source notebook

* working on custom_source notebook

* grammar

* grammar in the notebook title

* fixing typo

* fixing hyperlink

* fixing hyperlink again

* pep 8

* more pep8

* formatting

* getting opinions

* adding units

docs/io/optional/custom_source.ipynb

@@ -4,7 +4,24 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Running TARDIS with a custom packet source"
+    "# Running TARDIS with a Custom Packet Source"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "By default, TARDIS generates energy packets using its `BasePacketSource` class, which models the photosphere of the supernova as a perfect blackbody (see [Energy Packet Initialization](../../physics/montecarlo/initialization.ipynb)). However, users may create their own packet source, as will be shown in this notebook. In order to do this, a user must create a class (that can but does not have to inherit from `BasePacketSource`) which contains a method `create_packets` that takes in (in this order):\n",
+    "- the photospheric temperature\n",
+    "- the number of packets\n",
+    "- a random number generator\n",
+    "- the photospheric radius\n",
+    "\n",
+    "and returns arrays of the radii, frequencies, propogation directions, and energies of the ensemble of packets (once again see [Energy Packet Initialization](../../physics/montecarlo/initialization.ipynb) for more information). To use your packet source in a run of TARDIS, you must pass an instance of your class into the `run_tardis` function under the `packet_source` keyword argument.\n",
+    "\n",
+    ".. note:: In both the `BasePacketSource` class and in the example here, all packets are generated at the same radius. This need not be true in general (although the `create_packets` method should only take in a single radius as its argument).\n",
+    "\n",
+    "We show an example of how a custom packet source is used:"
    ]
   },
   {
@@ -13,6 +30,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Import necessary packages\n",
     "import numpy as np\n",
     "from tardis import constants as const\n",
     "from astropy import units as u\n",
@@ -28,22 +46,17 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Download the atomic data used for a run of TARDIS\n",
     "download_atom_data('kurucz_cd23_chianti_H_He')"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Custom packet source class that is derived from BasePacketSource. The method create_packets (which returns ```radii, nus, mus, energies```) has to be defined."
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Create a packet source class that contains a create_packets method\n",
     "class TruncBlackbodySource(BasePacketSource):\n",
     "    \"\"\"\n",
     "        Custom inner boundary source class to replace the Blackbody source\n",
@@ -112,11 +125,19 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Call an instance of the packet source class\n",
     "packet_source = TruncBlackbodySource(\n",
     "    53253, truncation_wavelength=2000\n",
     ")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We now run TARDIS both with and without our custom packet source, and we compare the results:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -137,10 +158,10 @@
     "%matplotlib inline\n",
     "plt.plot(mdl.runner.spectrum_virtual.wavelength,\n",
     "         mdl.runner.spectrum_virtual.luminosity_density_lambda,\n",
-    "         color='red', label='truncated blackbody')\n",
+    "         color='red', label='truncated blackbody (custom packet source)')\n",
     "plt.plot(mdl_norm.runner.spectrum_virtual.wavelength,\n",
     "         mdl_norm.runner.spectrum_virtual.luminosity_density_lambda,\n",
-    "         color='blue', label='normal blackbody')\n",
+    "         color='blue', label='normal blackbody (default packet source)')\n",
     "plt.xlabel('$\\lambda [\\AA]$')\n",
     "plt.ylabel('$L_\\lambda$ [erg/s/$\\AA$]')\n",
     "plt.xlim(500, 10000)\n",
@@ -169,4 +190,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

docs/physics/montecarlo/basicprinciples.rst

@@ -20,7 +20,7 @@ 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 :doc:`Discretization <discretization>`)
+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

docs/physics/montecarlo/index.rst

@@ -13,7 +13,7 @@ can also be found in various papers by L. Lucy and in the main TARDIS publicatio
 
 .. toctree::
     basicprinciples
-    discretization
+    initialization
     propagation
     lineinteraction
     estimators