From 59ff077da10f7265d23c1f0dc344f3ce9d2c2124 Mon Sep 17 00:00:00 2001
From: Dhruv Sondhi <66117751+DhruvSondhi@users.noreply.github.com>
Date: Fri, 10 Dec 2021 20:40:15 +0530
Subject: [PATCH 01/45] Tracking RPacket Properties in Montecarlo Single Packet
Loop Function (#1748)
* Added functionality to track properties for r_packets, configured from YAML
* Tried implementation of record based tracking of the r_packet properties
* Implemented array based packet property tracking
* Added functionality to reduce the array size inside the RPacketCollection
* Reverted formatting changes within montecarlo_numba/base.py
* Changed the searching implementation for finding the exact size of the resultant arrays in RPacketCollection
* Added docstring for the newly added RPacketCollection Class
* Made array length for the properties in the RPacketCollection configurable via the YAML Config
* Added tests for r_packet tracking
* Changed initial_array_length to const value,
Changed the implementation of the finalize_array function to reduce the array size
Implemented tests with Setup & Teardown mechanics for INITIAL_TRACKING_ARRAY_LENGTH
* Added demarcation for Setup & Teardown in tests
* Changed set_properties func to track,
Removed track_r_packet func from r_packet.py
* Renamed r_packet_tracking to track_rpacket for consistency
* Added Documentation for RPacket Tracking
* Changed formatting for the documentation
* Reverted whitespace addition
* Made required changes,
Renamed tracked_rpacket to rpacket_tracker
* Made changes as requested
* [build docs]
* Restructured code for multithreading
* Restructured the tracking to happen after conditionals in single_packet_loop
* Added Docstrings to RPacketCollection JITClass
* Refactored original tests to be consistent with the new changes
---
docs/io/output/index.rst | 3 +-
docs/io/output/rpacket_tracking.ipynb | 333 ++++++++++++++++++
tardis/io/schemas/montecarlo.yml | 14 +
tardis/montecarlo/base.py | 11 +
tardis/montecarlo/montecarlo_configuration.py | 3 +
tardis/montecarlo/montecarlo_numba/base.py | 30 +-
.../montecarlo_numba/numba_interface.py | 107 ++++++
.../montecarlo_numba/single_packet_loop.py | 37 +-
tardis/montecarlo/tests/test_montecarlo.py | 46 +++
9 files changed, 553 insertions(+), 31 deletions(-)
create mode 100644 docs/io/output/rpacket_tracking.ipynb
diff --git a/docs/io/output/index.rst b/docs/io/output/index.rst
index 46036596261..bb9f5650bc0 100644
--- 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
\ No newline at end of file
+ progress_bars
+ rpacket_tracking
diff --git a/docs/io/output/rpacket_tracking.ipynb b/docs/io/output/rpacket_tracking.ipynb
new file mode 100644
index 00000000000..cc8b167b641
--- /dev/null
+++ 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.
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": [
+ "\n",
+ "
\n",
+ " The properties that are tracked are as follows :\n",
+ " \n",
+ " - index - Index of the Packet
\n",
+ " - seed - Seed of the Packet
\n",
+ " - status - Current Status for the Packet Interaction
\n",
+ " - r - Radius of the Current Shell
\n",
+ " - nu - Packet's Frequency
\n",
+ " - mu - Propagation Direction of the Packet (cosine of the angle the packet’s path makes with the radial direction)
\n",
+ " - energy - Energy of the Packet
\n",
+ " - shell_id - Current Shell Id where the Packet is present
\n",
+ "
\n",
+ " \n",
+ ""
+ ]
+ },
+ {
+ "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": [
+ "\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",
+ "
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "afa3c7f4",
+ "metadata": {},
+ "source": [
+ "\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",
+ "
"
+ ]
+ }
+ ],
+ "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
index e8a77ad963e..4a31f5228c5 100644
--- 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
diff --git a/tardis/montecarlo/base.py b/tardis/montecarlo/base.py
index 7dfa116ca8f..da7d9c725f0 100644
--- a/tardis/montecarlo/base.py
+++ b/tardis/montecarlo/base.py
@@ -100,6 +100,7 @@ def __init__(
debug_packets=False,
logger_buffer=1,
single_packet_seed=None,
+ tracking_rpacket=False,
):
self.seed = seed
@@ -134,10 +135,15 @@ def __init__(
self.virt_packet_initial_rs = np.ones(2) * -1.0
self.virt_packet_initial_mus = np.ones(2) * -1.0
+ # Setting up the Tracking array for RPacketCollection
+ self.rpacket_tracker = None
+
# set up logger based on config
mc_tracker.DEBUG_MODE = debug_packets
mc_tracker.BUFFER = logger_buffer
+ mc_config_module.RPACKET_TRACKING = tracking_rpacket
+
if self.spectrum_method == "integrated":
self.optional_hdf_properties.append("spectrum_integrated")
@@ -602,6 +608,10 @@ def from_config(
config.plasma.disable_line_scattering
)
+ mc_config_module.INITIAL_TRACKING_ARRAY_LENGTH = (
+ config.montecarlo.tracking.initial_array_length
+ )
+
return cls(
seed=config.montecarlo.seed,
spectrum_frequency=spectrum_frequency,
@@ -622,4 +632,5 @@ def from_config(
config.spectrum.virtual.virtual_packet_logging
| virtual_packet_logging
),
+ tracking_rpacket=config.montecarlo.tracking.track_rpacket,
)
diff --git a/tardis/montecarlo/montecarlo_configuration.py b/tardis/montecarlo/montecarlo_configuration.py
index 438d9b15f19..2547ba121a0 100644
--- a/tardis/montecarlo/montecarlo_configuration.py
+++ b/tardis/montecarlo/montecarlo_configuration.py
@@ -11,5 +11,8 @@
disable_line_scattering = False
survival_probability = 0.0
tau_russian = 10.0
+
+INITIAL_TRACKING_ARRAY_LENGTH = None
LEGACY_MODE_ENABLED = False
VPACKET_LOGGING = False
+RPACKET_TRACKING = False
diff --git a/tardis/montecarlo/montecarlo_numba/base.py b/tardis/montecarlo/montecarlo_numba/base.py
index dbac64d17e1..02cb6310455 100644
--- a/tardis/montecarlo/montecarlo_numba/base.py
+++ b/tardis/montecarlo/montecarlo_numba/base.py
@@ -11,6 +11,7 @@
from tardis.montecarlo.montecarlo_numba.numba_interface import (
PacketCollection,
VPacketCollection,
+ RPacketCollection,
NumbaModel,
numba_plasma_initialize,
Estimators,
@@ -77,6 +78,7 @@ def montecarlo_radial1d(
virt_packet_last_interaction_type,
virt_packet_last_line_interaction_in_id,
virt_packet_last_line_interaction_out_id,
+ tracked_rpackets,
) = montecarlo_main_loop(
packet_collection,
numba_model,
@@ -124,6 +126,10 @@ def montecarlo_radial1d(
).ravel()
update_iterations_pbar(1)
+ # Condition for Checking if RPacket Tracking is enabled
+ if montecarlo_configuration.RPACKET_TRACKING:
+ runner.rpacket_tracker = tracked_rpackets
+
@njit(**njit_dict)
def montecarlo_main_loop(
@@ -185,6 +191,11 @@ def montecarlo_main_loop(
)
)
+ # Configuring the Tracking for R_Packets
+ tracked_rpackets = List()
+ for i in range(len(output_nus)):
+ tracked_rpackets.append(RPacketCollection())
+
# Arrays for vpacket logging
virt_packet_nus = []
virt_packet_energies = []
@@ -198,7 +209,7 @@ def montecarlo_main_loop(
for i in prange(len(output_nus)):
if show_progress_bars:
with objmode:
- update_amount = 1
+ update_amount = 1
update_packet_pbar(
update_amount,
current_iteration=iteration,
@@ -221,12 +232,16 @@ def montecarlo_main_loop(
i,
)
vpacket_collection = vpacket_collections[i]
+ rpacket_collection = tracked_rpackets[i]
- loop = single_packet_loop(
- r_packet, numba_model, numba_plasma, estimators, vpacket_collection
+ single_packet_loop(
+ r_packet,
+ numba_model,
+ numba_plasma,
+ estimators,
+ vpacket_collection,
+ rpacket_collection,
)
- # if loop and 'stop' in loop:
- # raise MonteCarloException
output_nus[i] = r_packet.nu
last_interaction_in_nus[i] = r_packet.last_interaction_in_nu
@@ -311,6 +326,10 @@ def montecarlo_main_loop(
)
)
+ if montecarlo_configuration.RPACKET_TRACKING:
+ for rpacket_collection in tracked_rpackets:
+ rpacket_collection.finalize_array()
+
packet_collection.packets_output_energy[:] = output_energies[:]
packet_collection.packets_output_nu[:] = output_nus[:]
@@ -328,4 +347,5 @@ def montecarlo_main_loop(
virt_packet_last_interaction_type,
virt_packet_last_line_interaction_in_id,
virt_packet_last_line_interaction_out_id,
+ tracked_rpackets,
)
diff --git a/tardis/montecarlo/montecarlo_numba/numba_interface.py b/tardis/montecarlo/montecarlo_numba/numba_interface.py
index 8a3bbf32622..1745c6f5ce0 100644
--- a/tardis/montecarlo/montecarlo_numba/numba_interface.py
+++ b/tardis/montecarlo/montecarlo_numba/numba_interface.py
@@ -266,6 +266,7 @@ def set_properties(
temp_last_interaction_type = np.empty(temp_length, dtype=np.int64)
temp_last_interaction_in_id = np.empty(temp_length, dtype=np.int64)
temp_last_interaction_out_id = np.empty(temp_length, dtype=np.int64)
+
temp_nus[: self.length] = self.nus
temp_energies[: self.length] = self.energies
temp_initial_mus[: self.length] = self.initial_mus
@@ -304,6 +305,112 @@ def set_properties(
self.idx += 1
+rpacket_collection_spec = [
+ ("length", int64),
+ ("seed", int64[:]),
+ ("index", int64[:]),
+ ("status", int64[:]),
+ ("r", float64[:]),
+ ("nu", float64[:]),
+ ("mu", float64[:]),
+ ("energy", float64[:]),
+ ("shell_id", int64[:]),
+ ("interact_id", int64),
+]
+
+
+@jitclass(rpacket_collection_spec)
+class RPacketCollection(object):
+ """
+ Numba JITCLASS for storing the information for each interaction a RPacket instance undergoes.
+
+ Parameters
+ ----------
+ length : int
+ Length of the initial array that is instantiated
+ seed : int
+ Seed for each RPacket
+ index : int
+ Index position of each RPacket
+ status : int
+ Current status of the RPacket as per interactions
+ r : float
+ Radius of the shell where the RPacket is present
+ nu : float
+ Luminosity of the RPacket
+ mu : float
+ Cosine of the angle made by the direction of movement of the RPacket from its original direction
+ energy : float
+ Energy possessed by the RPacket at a particular shell
+ shell_id : int
+ Current Shell No in which the RPacket is present
+ interact_id : int
+ Internal counter for the interactions that a particular RPacket undergoes
+ """
+
+ def __init__(self):
+ self.length = montecarlo_configuration.INITIAL_TRACKING_ARRAY_LENGTH
+ self.seed = np.empty(self.length, dtype=np.int64)
+ self.index = np.empty(self.length, dtype=np.int64)
+ self.status = np.empty(self.length, dtype=np.int64)
+ self.r = np.empty(self.length, dtype=np.float64)
+ self.nu = np.empty(self.length, dtype=np.float64)
+ self.mu = np.empty(self.length, dtype=np.float64)
+ self.energy = np.empty(self.length, dtype=np.float64)
+ self.shell_id = np.empty(self.length, dtype=np.int64)
+ self.interact_id = 0
+
+ def track(self, r_packet):
+ if self.interact_id >= self.length:
+ temp_length = self.length * 2
+ temp_index = np.empty(temp_length, dtype=np.int64)
+ temp_seed = np.empty(temp_length, dtype=np.int64)
+ temp_status = np.empty(temp_length, dtype=np.int64)
+ temp_r = np.empty(temp_length, dtype=np.float64)
+ temp_nu = np.empty(temp_length, dtype=np.float64)
+ temp_mu = np.empty(temp_length, dtype=np.float64)
+ temp_energy = np.empty(temp_length, dtype=np.float64)
+ temp_shell_id = np.empty(temp_length, dtype=np.int64)
+
+ temp_index[: self.length] = self.index
+ temp_seed[: self.length] = self.seed
+ temp_status[: self.length] = self.status
+ temp_r[: self.length] = self.r
+ temp_nu[: self.length] = self.nu
+ temp_mu[: self.length] = self.mu
+ temp_energy[: self.length] = self.energy
+ temp_shell_id[: self.length] = self.shell_id
+
+ self.index = temp_index
+ self.seed = temp_seed
+ self.status = temp_status
+ self.r = temp_r
+ self.nu = temp_nu
+ self.mu = temp_mu
+ self.energy = temp_energy
+ self.shell_id = temp_shell_id
+ self.length = temp_length
+
+ self.index[self.interact_id] = r_packet.index
+ self.seed[self.interact_id] = r_packet.seed
+ self.status[self.interact_id] = r_packet.status
+ self.r[self.interact_id] = r_packet.r
+ self.nu[self.interact_id] = r_packet.nu
+ self.mu[self.interact_id] = r_packet.mu
+ self.energy[self.interact_id] = r_packet.energy
+ self.shell_id[self.interact_id] = r_packet.current_shell_id
+ self.interact_id += 1
+
+ def finalize_array(self):
+ self.index = self.index[: self.interact_id]
+ self.seed = self.seed[: self.interact_id]
+ self.status = self.status[: self.interact_id]
+ self.r = self.r[: self.interact_id]
+ self.nu = self.nu[: self.interact_id]
+ self.mu = self.mu[: self.interact_id]
+ self.energy = self.energy[: self.interact_id]
+
+
estimators_spec = [
("j_estimator", float64[:]),
("nu_bar_estimator", float64[:]),
diff --git a/tardis/montecarlo/montecarlo_numba/single_packet_loop.py b/tardis/montecarlo/montecarlo_numba/single_packet_loop.py
index c3d105e1d82..62c372ab206 100644
--- a/tardis/montecarlo/montecarlo_numba/single_packet_loop.py
+++ b/tardis/montecarlo/montecarlo_numba/single_packet_loop.py
@@ -31,13 +31,15 @@
C_SPEED_OF_LIGHT = const.c.to("cm/s").value
-from tardis.io.logger.montecarlo_tracking import log_decorator
-from tardis.io.logger import montecarlo_tracking as mc_tracker
-# @log_decorator
@njit
def single_packet_loop(
- r_packet, numba_model, numba_plasma, estimators, vpacket_collection
+ r_packet,
+ numba_model,
+ numba_plasma,
+ estimators,
+ vpacket_collection,
+ rpacket_collection,
):
"""
Parameters
@@ -47,6 +49,7 @@ def single_packet_loop(
numba_plasma : tardis.montecarlo.montecarlo_numba.numba_interface.NumbaPlasma
estimators : tardis.montecarlo.montecarlo_numba.numba_interface.Estimators
vpacket_collection : tardis.montecarlo.montecarlo_numba.numba_interface.VPacketCollection
+ rpacket_collection : tardis.montecarlo.montecarlo_numba.numba_interface.RPacketCollection
Returns
-------
@@ -67,12 +70,8 @@ def single_packet_loop(
r_packet, vpacket_collection, numba_model, numba_plasma
)
- if mc_tracker.DEBUG_MODE:
- r_packet_track_nu = [r_packet.nu]
- r_packet_track_mu = [r_packet.mu]
- r_packet_track_r = [r_packet.r]
- r_packet_track_interaction = [InteractionType.BOUNDARY]
- r_packet_track_distance = [0.0]
+ if montecarlo_configuration.RPACKET_TRACKING:
+ rpacket_collection.track(r_packet)
while r_packet.status == PacketStatus.IN_PROCESS:
distance, interaction_type, delta_shell = trace_packet(
@@ -114,21 +113,9 @@ def single_packet_loop(
trace_vpacket_volley(
r_packet, vpacket_collection, numba_model, numba_plasma
)
- if mc_tracker.DEBUG_MODE:
- r_packet_track_nu.append(r_packet.nu)
- r_packet_track_mu.append(r_packet.mu)
- r_packet_track_r.append(r_packet.r)
- r_packet_track_interaction.append(interaction_type)
- r_packet_track_distance.append(distance)
-
- if mc_tracker.DEBUG_MODE:
- return (
- r_packet_track_nu,
- r_packet_track_mu,
- r_packet_track_r,
- r_packet_track_interaction,
- r_packet_track_distance,
- )
+
+ if montecarlo_configuration.RPACKET_TRACKING:
+ rpacket_collection.track(r_packet)
# check where else initialize line ID happens!
diff --git a/tardis/montecarlo/tests/test_montecarlo.py b/tardis/montecarlo/tests/test_montecarlo.py
index 19b59427762..f63dd08b2d6 100644
--- a/tardis/montecarlo/tests/test_montecarlo.py
+++ b/tardis/montecarlo/tests/test_montecarlo.py
@@ -54,6 +54,7 @@
import tardis.montecarlo.montecarlo_configuration as mc
from tardis import constants as const
from tardis.montecarlo.montecarlo_numba.numba_interface import Estimators
+from tardis.montecarlo.montecarlo_numba.numba_interface import RPacketCollection
from tardis.montecarlo.montecarlo_numba import macro_atom
from tardis.montecarlo.montecarlo_numba.frame_transformations import (
@@ -816,3 +817,48 @@ def test_compute_distance2line_relativistic(
assert_allclose(comov_nu, nu_line, rtol=1e-14)
+
+"""
+Tests for Tracking RPacket Properties
+"""
+
+
+@pytest.mark.parametrize("seed", [2274437677])
+@pytest.mark.parametrize(
+ ["index", "r", "nu", "mu", "energy"],
+ [
+ (0, 0, 0, 0, 0),
+ (10, 1.43e15, 6.57e14, 0.92701038, 0.00010347),
+ (20, 2.04e15, 9.59e14, 0.96005622, 0.00010347),
+ (30, 1.12e15, 2.17e14, 0.96787487, 0.00010347),
+ (40, 2.15e15, 9.17e14, 0.96428633, 0.00010347),
+ (100000, 2.23e15, 8.56e14, 0.96946856, 0.00010347),
+ ],
+)
+def test_rpacket_tracking(index, seed, r, nu, mu, energy):
+ # Setup Montecarlo_Configuration.INITIAL_TRACKING_ARRAY_LENGTH
+ mc.INITIAL_TRACKING_ARRAY_LENGTH = 10
+
+ tracked_rpacket_properties = RPacketCollection()
+ test_rpacket = r_packet.RPacket(
+ index=index,
+ seed=seed,
+ r=r,
+ nu=nu,
+ mu=mu,
+ energy=energy,
+ )
+
+ # TearDown Montecarlo_Configuration.INITIAL_TRACKING_ARRAY_LENGTH
+ mc.INITIAL_TRACKING_ARRAY_LENGTH = None
+
+ tracked_rpacket_properties.track(test_rpacket)
+ tracked_rpacket_properties.finalize_array()
+
+ assert test_rpacket.index == tracked_rpacket_properties.index
+ assert test_rpacket.seed == tracked_rpacket_properties.seed
+ assert test_rpacket.r == tracked_rpacket_properties.r
+ assert test_rpacket.nu == tracked_rpacket_properties.nu
+ assert test_rpacket.mu == tracked_rpacket_properties.mu
+ assert test_rpacket.energy == tracked_rpacket_properties.energy
+ assert tracked_rpacket_properties.interact_id == 1
From 48f56f1b732c588a697be53b09a722c1bc2cc9dd Mon Sep 17 00:00:00 2001
From: Isaac Smith <71480393+smithis7@users.noreply.github.com>
Date: Fri, 10 Dec 2021 12:30:04 -0500
Subject: [PATCH 02/45] Reorganizing docs for website release (#1835)
* restructuring docs for new website release
* moving quickstart
* removing unnecessary images
* fixing quickstart links
* fixing tardis example symlink in development directory
* fixing hyperlinks
* changing grid page name and linking website
* Jaladh's comments
---
.gitignore | 2 +-
docs/CHANGELOG.md | 1 -
docs/CODE_OF_CONDUCT.md | 1 -
docs/CONTRIBUTING.md | 1 -
docs/conf.py | 4 +-
docs/contributing/CHANGELOG.md | 1 +
docs/contributing/CONTRIBUTING.md | 1 +
.../development/azure_links.inc | 0
.../development/code_quality.rst | 0
.../development/continuous_integration.rst | 0
.../development/debug_numba.rst | 0
.../development/developer_faq.rst | 0
.../development/documentation_guidelines.rst | 10 +-
.../development/git_links.inc | 0
.../development/git_workflow.rst | 2 +-
.../development/images/Bootcamp-Fork.png | Bin
.../development/images/branch_dropdown.png | Bin
.../development/images/pull_button.png | Bin
.../development/images/variables.png | Bin
docs/{ => contributing}/development/index.rst | 0
.../development/integration.yml | 0
.../{ => contributing}/development/issues.rst | 0
.../development/known_projects.inc | 0
docs/{ => contributing}/development/links.inc | 0
.../development/matterbridge.inc | 0
.../development/matterbridge.rst | 0
.../cpu_threads_dict_128_threads_1_node.csv | 0
.../development/profiling/index.rst | 0
.../profiling/profiling_example.ipynb | 0
.../development/profiling/tardis_example.yml | 1 +
.../development/profiling/tardis_prof.png | Bin
.../profiling/tardis_profiling_threads.ipynb | 0
.../threads_dict_128_threads_1_node.csv | 0
.../development/running_tests.rst | 0
.../development/this_project.inc | 0
.../development/update_refdata.rst | 2 +-
docs/{ => contributing}/roadmap.rst | 0
docs/development/profiling/tardis_example.yml | 1 -
docs/graphics/esa.png | Bin 51548 -> 0 bytes
docs/graphics/github.png | Bin 27280 -> 0 bytes
docs/graphics/google.png | Bin 28751 -> 0 bytes
docs/graphics/numfocus.png | Bin 19455 -> 0 bytes
docs/index.rst | 52 +++------
docs/io/configuration/example.rst | 2 +-
docs/io/grid/TardisGridTutorial.ipynb | 86 +++++++--------
docs/news.rst | 102 ------------------
docs/physics/spectrum/basic.ipynb | 2 +-
docs/{quickstart => }/quickstart.ipynb | 78 +++++++-------
docs/quickstart/tardis_example.yml | 1 -
docs/research/index.rst | 15 ---
.../code_comparison/index.rst | 0
.../plasma_compare/plasma_compare.ipynb | 0
.../plasma_compare/tardis_example.yml | 0
.../toy_models/blondin_compare.csvy | 0
.../toy_models/blondin_compare_01.csvy | 0
.../toy_models/blondin_compare_06.csvy | 0
.../toy_models/blondin_model_compare_01.yml | 0
.../toy_models/blondin_model_compare_06.yml | 0
.../toy_models/reading blondin toymodel.ipynb | 0
docs/{ => resources}/credits.rst | 0
.../research_done_using_TARDIS/ads.ipynb | 0
.../research_papers.rst | 0
docs/{ => resources}/zreferences.rst | 40 ++-----
docs/sponsors.rst | 41 -------
docs/team_and_governance/alumni.rst | 30 ------
docs/team_and_governance/governance.rst | 40 -------
docs/team_and_governance/index.rst | 8 --
docs/team_and_governance/team.rst | 98 -----------------
68 files changed, 122 insertions(+), 500 deletions(-)
delete mode 120000 docs/CHANGELOG.md
delete mode 120000 docs/CODE_OF_CONDUCT.md
delete mode 120000 docs/CONTRIBUTING.md
create mode 120000 docs/contributing/CHANGELOG.md
create mode 120000 docs/contributing/CONTRIBUTING.md
rename docs/{ => contributing}/development/azure_links.inc (100%)
rename docs/{ => contributing}/development/code_quality.rst (100%)
rename docs/{ => contributing}/development/continuous_integration.rst (100%)
rename docs/{ => contributing}/development/debug_numba.rst (100%)
rename docs/{ => contributing}/development/developer_faq.rst (100%)
rename docs/{ => contributing}/development/documentation_guidelines.rst (92%)
rename docs/{ => contributing}/development/git_links.inc (100%)
rename docs/{ => contributing}/development/git_workflow.rst (99%)
rename docs/{ => contributing}/development/images/Bootcamp-Fork.png (100%)
rename docs/{ => contributing}/development/images/branch_dropdown.png (100%)
rename docs/{ => contributing}/development/images/pull_button.png (100%)
rename docs/{ => contributing}/development/images/variables.png (100%)
rename docs/{ => contributing}/development/index.rst (100%)
rename docs/{ => contributing}/development/integration.yml (100%)
rename docs/{ => contributing}/development/issues.rst (100%)
rename docs/{ => contributing}/development/known_projects.inc (100%)
rename docs/{ => contributing}/development/links.inc (100%)
rename docs/{ => contributing}/development/matterbridge.inc (100%)
rename docs/{ => contributing}/development/matterbridge.rst (100%)
rename docs/{ => contributing}/development/profiling/cpu_threads_dict_128_threads_1_node.csv (100%)
rename docs/{ => contributing}/development/profiling/index.rst (100%)
rename docs/{ => contributing}/development/profiling/profiling_example.ipynb (100%)
create mode 120000 docs/contributing/development/profiling/tardis_example.yml
rename docs/{ => contributing}/development/profiling/tardis_prof.png (100%)
rename docs/{ => contributing}/development/profiling/tardis_profiling_threads.ipynb (100%)
rename docs/{ => contributing}/development/profiling/threads_dict_128_threads_1_node.csv (100%)
rename docs/{ => contributing}/development/running_tests.rst (100%)
rename docs/{ => contributing}/development/this_project.inc (100%)
rename docs/{ => contributing}/development/update_refdata.rst (94%)
rename docs/{ => contributing}/roadmap.rst (100%)
delete mode 120000 docs/development/profiling/tardis_example.yml
delete mode 100644 docs/graphics/esa.png
delete mode 100644 docs/graphics/github.png
delete mode 100644 docs/graphics/google.png
delete mode 100644 docs/graphics/numfocus.png
delete mode 100644 docs/news.rst
rename docs/{quickstart => }/quickstart.ipynb (78%)
delete mode 120000 docs/quickstart/tardis_example.yml
delete mode 100644 docs/research/index.rst
rename docs/{research => resources}/code_comparison/index.rst (100%)
rename docs/{research => resources}/code_comparison/plasma_compare/plasma_compare.ipynb (100%)
rename docs/{research => resources}/code_comparison/plasma_compare/tardis_example.yml (100%)
rename docs/{research => resources}/code_comparison/toy_models/blondin_compare.csvy (100%)
rename docs/{research => resources}/code_comparison/toy_models/blondin_compare_01.csvy (100%)
rename docs/{research => resources}/code_comparison/toy_models/blondin_compare_06.csvy (100%)
rename docs/{research => resources}/code_comparison/toy_models/blondin_model_compare_01.yml (100%)
rename docs/{research => resources}/code_comparison/toy_models/blondin_model_compare_06.yml (100%)
rename docs/{research => resources}/code_comparison/toy_models/reading blondin toymodel.ipynb (100%)
rename docs/{ => resources}/credits.rst (100%)
rename docs/{research => resources}/research_done_using_TARDIS/ads.ipynb (100%)
rename docs/{research => resources}/research_done_using_TARDIS/research_papers.rst (100%)
rename docs/{ => resources}/zreferences.rst (63%)
delete mode 100644 docs/sponsors.rst
delete mode 100644 docs/team_and_governance/alumni.rst
delete mode 100644 docs/team_and_governance/governance.rst
delete mode 100644 docs/team_and_governance/index.rst
delete mode 100644 docs/team_and_governance/team.rst
diff --git a/.gitignore b/.gitignore
index f32d4132fc0..e06afd9f6e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,7 +20,7 @@ MANIFEST
# Sphinx
docs/api
docs/_build
-docs/ZENODO.rst
+docs/resources/ZENODO.rst
docs/tutorials.rst
docs/io/configuration/components/models/converters/density_parse.csv
docs/io/configuration/components/models/converters/abund_parse.csv
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
deleted file mode 120000
index 04c99a55caa..00000000000
--- a/docs/CHANGELOG.md
+++ /dev/null
@@ -1 +0,0 @@
-../CHANGELOG.md
\ No newline at end of file
diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md
deleted file mode 120000
index 0400d574603..00000000000
--- a/docs/CODE_OF_CONDUCT.md
+++ /dev/null
@@ -1 +0,0 @@
-../CODE_OF_CONDUCT.md
\ No newline at end of file
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
deleted file mode 120000
index 44fcc634393..00000000000
--- a/docs/CONTRIBUTING.md
+++ /dev/null
@@ -1 +0,0 @@
-../CONTRIBUTING.md
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
index 8ee8ed0b19d..3e0a96be777 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -63,7 +63,7 @@
exclude_patterns.append("_templates")
exclude_patterns.append("_build")
exclude_patterns.append("**.ipynb_checkpoints")
-exclude_patterns.append("research/research_done_using_TARDIS/ads.ipynb")
+exclude_patterns.append("resources/research_done_using_TARDIS/ads.ipynb")
# This is added to the end of RST files - a good place to put substitutions to
# be used globally.
@@ -345,7 +345,7 @@ def generate_ZENODO(app):
"""Creating ZENODO.rst
Adapted from: https://astrodata.nyc/posts/2021-04-23-zenodo-sphinx/"""
CONCEPT_DOI = "592480" # See: https://help.zenodo.org/#versioning
- zenodo_path = pathlib.Path("ZENODO.rst")
+ zenodo_path = pathlib.Path("resources/ZENODO.rst")
try:
headers = {"accept": "application/x-bibtex"}
diff --git a/docs/contributing/CHANGELOG.md b/docs/contributing/CHANGELOG.md
new file mode 120000
index 00000000000..699cc9e7b7c
--- /dev/null
+++ b/docs/contributing/CHANGELOG.md
@@ -0,0 +1 @@
+../../CHANGELOG.md
\ No newline at end of file
diff --git a/docs/contributing/CONTRIBUTING.md b/docs/contributing/CONTRIBUTING.md
new file mode 120000
index 00000000000..f939e75f21a
--- /dev/null
+++ b/docs/contributing/CONTRIBUTING.md
@@ -0,0 +1 @@
+../../CONTRIBUTING.md
\ No newline at end of file
diff --git a/docs/development/azure_links.inc b/docs/contributing/development/azure_links.inc
similarity index 100%
rename from docs/development/azure_links.inc
rename to docs/contributing/development/azure_links.inc
diff --git a/docs/development/code_quality.rst b/docs/contributing/development/code_quality.rst
similarity index 100%
rename from docs/development/code_quality.rst
rename to docs/contributing/development/code_quality.rst
diff --git a/docs/development/continuous_integration.rst b/docs/contributing/development/continuous_integration.rst
similarity index 100%
rename from docs/development/continuous_integration.rst
rename to docs/contributing/development/continuous_integration.rst
diff --git a/docs/development/debug_numba.rst b/docs/contributing/development/debug_numba.rst
similarity index 100%
rename from docs/development/debug_numba.rst
rename to docs/contributing/development/debug_numba.rst
diff --git a/docs/development/developer_faq.rst b/docs/contributing/development/developer_faq.rst
similarity index 100%
rename from docs/development/developer_faq.rst
rename to docs/contributing/development/developer_faq.rst
diff --git a/docs/development/documentation_guidelines.rst b/docs/contributing/development/documentation_guidelines.rst
similarity index 92%
rename from docs/development/documentation_guidelines.rst
rename to docs/contributing/development/documentation_guidelines.rst
index 02fdaa1f494..75019b91245 100644
--- a/docs/development/documentation_guidelines.rst
+++ b/docs/contributing/development/documentation_guidelines.rst
@@ -18,17 +18,17 @@ When making or adding changes to the functionality of an aspect of TARDIS, an ``
RST Documentation
-----------------
-Documentation not featuring interactive code examples is written in Sphinx's reStructuredText (see `here `_). Files written in reStructuredText have a ``.rst`` file extension, and are then built as HTML filed by Sphinx during the documentation build. Only the RST file, not the built HTML file, are committed to the repository. Documentation should be clear and concise. See :doc:`../io/visualization/using_widgets` as a good example of an RST-generated page.
+Documentation not featuring interactive code examples is written in Sphinx's reStructuredText (see `here `_). Files written in reStructuredText have a ``.rst`` file extension, and are then built as HTML filed by Sphinx during the documentation build. Only the RST file, not the built HTML file, are committed to the repository. Documentation should be clear and concise. See :doc:`../../io/visualization/using_widgets` as a good example of an RST-generated page.
IPYNB Documentation
-------------------
-Often, code examples can help explain concepts better. The TARDIS utilizes `Jupyter notebooks `_ (``.ipynb`` file extension) to demonstrate features of the code package within our documentation. See :doc:`../quickstart/quickstart` or :doc:`../physics/montecarlo/initialization` for good examples.
+Often, code examples can help explain concepts better. The TARDIS utilizes `Jupyter notebooks `_ (``.ipynb`` file extension) to demonstrate features of the code package within our documentation. See :doc:`../../quickstart` or :doc:`../../physics/montecarlo/initialization` for good examples.
TARDIS uses the `nbsphinx `_ extension to turn these notebooks into HTML pages in the documentation. During a documentation build, nbsphinx runs all notebooks in the documentation with cleared output and places their output in the HTML. **Thus, notebook output must always be cleared before it is submitted** to ensure that the notebooks are run by nbsphinx. Running these notebooks during the documentation build helps ensure that the documentation is kept up-to-date, as notebook output will reflect the current state of the TARDIS code. Additionally, if updates in the code are inconsistent with the documentation, the documentation build will return an error, alerting TARDIS developers to the inconsistency.
-An added benefit of IPYNB documentation is the ability to have interactive tutorials. All notebooks in the TARDIS documentation feature a button at the top encouraging users to launch the interactive version of the notebook (see the previously mentioned examples). This directs users to the TARDIS repository on `Binder `_, where the notebook can be run using an online Jupyter kernel. Additionally, all notebooks in the Input/Output section of the documentation are automatically linked to on the :doc:`../tutorials` page.
+An added benefit of IPYNB documentation is the ability to have interactive tutorials. All notebooks in the TARDIS documentation feature a button at the top encouraging users to launch the interactive version of the notebook (see the previously mentioned examples). This directs users to the TARDIS repository on `Binder `_, where the notebook can be run using an online Jupyter kernel. Additionally, all notebooks in the Input/Output section of the documentation are automatically linked to on the :doc:`../../tutorials` page.
Including Your Page in the TARDIS Documentation
@@ -37,8 +37,8 @@ Including Your Page in the TARDIS Documentation
Whether your page is written in reStructuredText or as a Jupyter notebook, it must be included in the TARDIS documentation. This has three steps:
1. Determine the appropriate location for the page within the documentation. Feel free to reach out to someone in the TARDIS collaboration for help with this step.
-2. Place your file in the corresponding directory in the ``docs/`` directory of the repository. For example, the :doc:`../io/visualization/using_widgets` is a subpage of "Visualization Tools and Widgets" under the Input/Output section of the documentation, so it is placed in ``docs/io/visualization/``.
-3. Include your file in the/a `toctree `_ of the corresponding ``index.rst``. For example, :doc:`../io/visualization/using_widgets` was included in a toctree of ``docs/io/visualization/index.rst``.
+2. Place your file in the corresponding directory in the ``docs/`` directory of the repository. For example, the :doc:`../../io/visualization/using_widgets` is a subpage of "Visualization Tools and Widgets" under the Input/Output section of the documentation, so it is placed in ``docs/io/visualization/``.
+3. Include your file in the/a `toctree `_ of the corresponding ``index.rst``. For example, :doc:`../../io/visualization/using_widgets` was included in a toctree of ``docs/io/visualization/index.rst``.
.. note::
diff --git a/docs/development/git_links.inc b/docs/contributing/development/git_links.inc
similarity index 100%
rename from docs/development/git_links.inc
rename to docs/contributing/development/git_links.inc
diff --git a/docs/development/git_workflow.rst b/docs/contributing/development/git_workflow.rst
similarity index 99%
rename from docs/development/git_workflow.rst
rename to docs/contributing/development/git_workflow.rst
index 9d381583d6f..f49414f8faf 100644
--- a/docs/development/git_workflow.rst
+++ b/docs/contributing/development/git_workflow.rst
@@ -29,7 +29,7 @@ Preparation and Working with Git
================================
In this document, we refer to the TARDIS ``master`` branch as the *trunk*. The first step is to setup up a python environment. We recommend using
-Anaconda for this purpose; refer to our :doc:`Installation guide <../installation>` which covers this topic.
+Anaconda for this purpose; refer to our :doc:`Installation guide <../../installation>` which covers this topic.
.. _forking:
diff --git a/docs/development/images/Bootcamp-Fork.png b/docs/contributing/development/images/Bootcamp-Fork.png
similarity index 100%
rename from docs/development/images/Bootcamp-Fork.png
rename to docs/contributing/development/images/Bootcamp-Fork.png
diff --git a/docs/development/images/branch_dropdown.png b/docs/contributing/development/images/branch_dropdown.png
similarity index 100%
rename from docs/development/images/branch_dropdown.png
rename to docs/contributing/development/images/branch_dropdown.png
diff --git a/docs/development/images/pull_button.png b/docs/contributing/development/images/pull_button.png
similarity index 100%
rename from docs/development/images/pull_button.png
rename to docs/contributing/development/images/pull_button.png
diff --git a/docs/development/images/variables.png b/docs/contributing/development/images/variables.png
similarity index 100%
rename from docs/development/images/variables.png
rename to docs/contributing/development/images/variables.png
diff --git a/docs/development/index.rst b/docs/contributing/development/index.rst
similarity index 100%
rename from docs/development/index.rst
rename to docs/contributing/development/index.rst
diff --git a/docs/development/integration.yml b/docs/contributing/development/integration.yml
similarity index 100%
rename from docs/development/integration.yml
rename to docs/contributing/development/integration.yml
diff --git a/docs/development/issues.rst b/docs/contributing/development/issues.rst
similarity index 100%
rename from docs/development/issues.rst
rename to docs/contributing/development/issues.rst
diff --git a/docs/development/known_projects.inc b/docs/contributing/development/known_projects.inc
similarity index 100%
rename from docs/development/known_projects.inc
rename to docs/contributing/development/known_projects.inc
diff --git a/docs/development/links.inc b/docs/contributing/development/links.inc
similarity index 100%
rename from docs/development/links.inc
rename to docs/contributing/development/links.inc
diff --git a/docs/development/matterbridge.inc b/docs/contributing/development/matterbridge.inc
similarity index 100%
rename from docs/development/matterbridge.inc
rename to docs/contributing/development/matterbridge.inc
diff --git a/docs/development/matterbridge.rst b/docs/contributing/development/matterbridge.rst
similarity index 100%
rename from docs/development/matterbridge.rst
rename to docs/contributing/development/matterbridge.rst
diff --git a/docs/development/profiling/cpu_threads_dict_128_threads_1_node.csv b/docs/contributing/development/profiling/cpu_threads_dict_128_threads_1_node.csv
similarity index 100%
rename from docs/development/profiling/cpu_threads_dict_128_threads_1_node.csv
rename to docs/contributing/development/profiling/cpu_threads_dict_128_threads_1_node.csv
diff --git a/docs/development/profiling/index.rst b/docs/contributing/development/profiling/index.rst
similarity index 100%
rename from docs/development/profiling/index.rst
rename to docs/contributing/development/profiling/index.rst
diff --git a/docs/development/profiling/profiling_example.ipynb b/docs/contributing/development/profiling/profiling_example.ipynb
similarity index 100%
rename from docs/development/profiling/profiling_example.ipynb
rename to docs/contributing/development/profiling/profiling_example.ipynb
diff --git a/docs/contributing/development/profiling/tardis_example.yml b/docs/contributing/development/profiling/tardis_example.yml
new file mode 120000
index 00000000000..94d76bc1bf2
--- /dev/null
+++ b/docs/contributing/development/profiling/tardis_example.yml
@@ -0,0 +1 @@
+../../../tardis_example.yml
\ No newline at end of file
diff --git a/docs/development/profiling/tardis_prof.png b/docs/contributing/development/profiling/tardis_prof.png
similarity index 100%
rename from docs/development/profiling/tardis_prof.png
rename to docs/contributing/development/profiling/tardis_prof.png
diff --git a/docs/development/profiling/tardis_profiling_threads.ipynb b/docs/contributing/development/profiling/tardis_profiling_threads.ipynb
similarity index 100%
rename from docs/development/profiling/tardis_profiling_threads.ipynb
rename to docs/contributing/development/profiling/tardis_profiling_threads.ipynb
diff --git a/docs/development/profiling/threads_dict_128_threads_1_node.csv b/docs/contributing/development/profiling/threads_dict_128_threads_1_node.csv
similarity index 100%
rename from docs/development/profiling/threads_dict_128_threads_1_node.csv
rename to docs/contributing/development/profiling/threads_dict_128_threads_1_node.csv
diff --git a/docs/development/running_tests.rst b/docs/contributing/development/running_tests.rst
similarity index 100%
rename from docs/development/running_tests.rst
rename to docs/contributing/development/running_tests.rst
diff --git a/docs/development/this_project.inc b/docs/contributing/development/this_project.inc
similarity index 100%
rename from docs/development/this_project.inc
rename to docs/contributing/development/this_project.inc
diff --git a/docs/development/update_refdata.rst b/docs/contributing/development/update_refdata.rst
similarity index 94%
rename from docs/development/update_refdata.rst
rename to docs/contributing/development/update_refdata.rst
index dd770664455..1fa151375e2 100644
--- a/docs/development/update_refdata.rst
+++ b/docs/contributing/development/update_refdata.rst
@@ -36,7 +36,7 @@ If you think your could be dealing with scenario B, then:
.. note::
- If you don't have enough privileges to run the pipelines, tag a TARDIS developer capable of doing so.
- - If any of these two pipelines fail, please tag the :ref:`CI/CD responsible `.
+ - If any of these two pipelines fail, please tag a `TARDIS team member `_ responsible for CI/CD.
If everything went well, the reference data will have been updated by the TARDIS bot and the commit
message should include the pull request number that triggered the update.
diff --git a/docs/roadmap.rst b/docs/contributing/roadmap.rst
similarity index 100%
rename from docs/roadmap.rst
rename to docs/contributing/roadmap.rst
diff --git a/docs/development/profiling/tardis_example.yml b/docs/development/profiling/tardis_example.yml
deleted file mode 120000
index 665fe53411f..00000000000
--- a/docs/development/profiling/tardis_example.yml
+++ /dev/null
@@ -1 +0,0 @@
-../../tardis_example.yml
\ No newline at end of file
diff --git a/docs/graphics/esa.png b/docs/graphics/esa.png
deleted file mode 100644
index 6c2900577154c862a02a64db4126f8f3ca8e8313..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 51548
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