tardis-sn · andrewfullard · Dec 10, 2021 · Jul 26, 2021 · Jul 27, 2021 · Jul 29, 2021
diff --git a/docs/io/output/index.rst b/docs/io/output/index.rst
@@ -12,4 +12,5 @@ In addition to the widgets, TARDIS can output information in several other forms
     to_hdf
     callback
     vpacket_logging
-    progress_bars
+    progress_bars
+    rpacket_tracking
diff --git a/docs/io/output/rpacket_tracking.ipynb b/docs/io/output/rpacket_tracking.ipynb
@@ -0,0 +1,333 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "f57cd4fe",
+   "metadata": {},
+   "source": [
+    "# Tracking the Properties of Real Packets"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c103617c",
+   "metadata": {},
+   "source": [
+    "**TARDIS** has the functionality to track the properties of the *RPackets* that are generated when running the Simulation. The `rpacket_tracker` can track all the interactions a packet undergoes & thus keeps a track of the various properties, a packet may have.<br>Currently, the `rpacket_tracker` tracks the properties of all the packets in the *Last Iteration of the Simulation*. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ce6214b9",
+   "metadata": {},
+   "source": [
+    "<html>\n",
+    "    <body>\n",
+    "        The properties that are tracked are as follows :\n",
+    "        <ol>\n",
+    "            <li><b>index</b> - Index of the Packet</li>\n",
+    "            <li><b>seed</b> - Seed of the Packet</li>\n",
+    "            <li><b>status</b> - Current Status for the Packet Interaction</li>\n",
+    "            <li><b>r</b> - Radius of the Current Shell</li> \n",
+    "            <li><b>nu</b> - Packet's Frequency</li> \n",
+    "            <li><b>mu</b> - Propagation Direction of the Packet (cosine of the angle the packet’s path makes with the radial direction)</li>\n",
+    "            <li><b>energy</b> - Energy of the Packet</li>\n",
+    "            <li><b>shell_id</b> - Current Shell Id where the Packet is present</li>\n",
+    "        </ol>\n",
+    "    </body>\n",
+    "</html>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1686d9f1",
+   "metadata": {},
+   "source": [
+    "## How to Setup the Tracking for the RPackets?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "29e14475",
+   "metadata": {},
+   "source": [
+    "**TARDIS**' `rpacket_tracker` is configured via the `YAML` file. This functionality of tracking the packets is turned **off**, by default. This is due to that fact that using this property, may slow down the execution time for the Simulation. An example configuration can be seen below for setting up the *tracking*:\n",
+    "\n",
+    "```yaml\n",
+    "... \n",
+    "montecarlo:\n",
+    "...\n",
+    "tracking:\n",
+    "    r_packet_tracking: true\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "13b6420b",
+   "metadata": {},
+   "source": [
+    "The `montecarlo` section of the **YAML** file now has a `tracking` sub section which holds the configuration properties for the `rpacket_tracker` & the `initial_array_length` (discussed later in the tutorial)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2634c571",
+   "metadata": {},
+   "source": [
+    "Let us see, the new `rpacket_tracker` in action."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a0e975b6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from tardis.io.config_reader import Configuration"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "adbf5f75",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Reading the Configuration stored in `tardis_config_packet_tracking.yml` into config\n",
+    "\n",
+    "config = Configuration.from_yaml(\"tardis_example.yml\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "975766e9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Checking the `tracking` section via the Schema\n",
+    "\n",
+    "config[\"montecarlo\"][\"tracking\"]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b00bc2ca",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Setting `r_packet_tracking` to True to turn on the Tracking \n",
+    "\n",
+    "config[\"montecarlo\"][\"tracking\"][\"track_rpacket\"] = True"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b25271d6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from tardis import run_tardis"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f9e51fd3",
+   "metadata": {
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "# Running the simulation from the config\n",
+    "\n",
+    "sim = run_tardis(config, show_cplots=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "532bfafc",
+   "metadata": {},
+   "source": [
+    "Now, the `tracked` properties can be accessed via the `rpacket_tracker` attribute of the `sim.runner` object. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f8b3424f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim.runner.rpacket_tracker"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4771d92a",
+   "metadata": {},
+   "source": [
+    "It can be seen from the above code, that the `sim.runner.rpacket_tracker` is an instance of the `RPacketCollection` *Numba jitclass*. The `RPacketCollection` class has the following structure for the properties : {More information in the **TARDIS API** for `RPacketCollection` class}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ce587807",
+   "metadata": {},
+   "source": [
+    "```python\n",
+    "# Basic structure for the RPacketCollection Class\n",
+    "class RPacketCollection:\n",
+    "   # Properties\n",
+    "    index\n",
+    "    seed\n",
+    "    status\n",
+    "    r\n",
+    "    nu\n",
+    "    mu\n",
+    "    energy\n",
+    "    shell_id\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "411f2ef9",
+   "metadata": {},
+   "source": [
+    "To access these different properties, we may consider the following examples for the `rpacket_tracker`:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a4772b00",
+   "metadata": {},
+   "source": [
+    "- Accessing the `index` property for the packets:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "de7b8877",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim.runner.rpacket_tracker.index"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d81fbbf7",
+   "metadata": {},
+   "source": [
+    "- Accessing the `seed` property for the packets:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "39e2dbd2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim.runner.rpacket_tracker.seed"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7afe2110",
+   "metadata": {},
+   "source": [
+    "- Accessing the `status` property for the packets:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e82427ea",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim.runner.rpacket_tracker.status"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ea308a55",
+   "metadata": {},
+   "source": [
+    "Thus, all other properties {`r`, `nu`, `mu`, `energy`, `shell_id`} can be accessed accordingly."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c83dd906",
+   "metadata": {},
+   "source": [
+    "We can also see the total number of interactions all the packets had, with the following example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "090b1517",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "len(sim.runner.rpacket_tracker.index)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9136fba1",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "Warning\n",
+    "\n",
+    "If we  try to access `sim.runner.rpacket_tracker` property when we have the `track_rpacket` property in the `tracking` subsection of `montecarlo` config, turned off as follows `config[\"montecarlo\"][\"tracking\"][\"track_rpacket\"] = False`, it will return `None`.  Error will be raised if we try to access the properties i.e. `seed`, `index`, etc.\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "afa3c7f4",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "Note\n",
+    "    \n",
+    "When we initialise the `RPacketCollection()` class, the properties arrays {`index`, `seed`, `status`, etc} are allocated certain length based on the `initial_array_length` parameter that can be set via the `initial_array_length` property under `montecarlo -> tracking` section of the configuration. The default size of the array is `10`. This variable is important as the number of interactions a packet may have is variable, thus we need to allocate space dynamically. This variable is used to compute the size and expand the array such that the properties are able to hold these values for the packet interaction. Higher number, allocates more space initially leading to lesser times the arrays expands and vice versa. It can be set in the following manner `config[\"montecarlo\"][\"tracking\"][\"initial_array_length\"] = {value}`.\n",
+    "</div>"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "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.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/tardis/io/schemas/montecarlo.yml b/tardis/io/schemas/montecarlo.yml
@@ -64,6 +64,20 @@ properties:
     default: false
     description: Enables a more complete treatment of relativitic effects. This includes
       angle aberration as well as use of the fully general Doppler formula.
+  tracking:
+    type: object
+    default: {}
+    properties:
+      track_rpacket:
+        type: boolean
+        default: false
+        description: Allows for Tracking the properties of the RPackets in Single Packet Loop
+      initial_array_length:
+        type: number
+        default: 10
+        multiple: 1
+        description: Configures the initial array length for the RPacketCollection Properties arrays
+      description: Sets up tracking for Montecarlo 
   debug_packets:
     type: boolean
     default: false