Add docstrings to subpackages (tardis-sn#2204)

* add docstring to subpackage grid * Add docstrings to subpackages * Change comments to docstrings * add docstrings to subpackages * rename gui/__init__.py * Reformat using black * add contributor infos to mailmap file * add extended summary to docstrings * Add extended summary to plasma/properties * Update tardis/io/parsers/__init__.py Co-authored-by: Sona Chitchyan <[email protected]> --------- Co-authored-by: kim <[email protected]> Co-authored-by: Sona Chitchyan <[email protected]>
shreyas3156 · Mar 27, 2023 · db2c635 · db2c635
1 parent 9ea964d
commit db2c635
Show file tree

Hide file tree

Showing 23 changed files with 110 additions and 7 deletions.
diff --git a/.mailmap b/.mailmap
@@ -230,3 +230,8 @@ Youssef Eweis <[email protected]> Youssef Eweis <[email protected]
 Rohith Varma Buddaraju <[email protected]>
 Rohith Varma Buddaraju <[email protected]> rohithvarma3000 <[email protected]>
 Rohith Varma Buddaraju <[email protected]> Rohith <[email protected]>
+
+Le Truong <[email protected]>
+
+Kim Lingemann <[email protected]> kimsina <[email protected]>
+Kim Lingemann <[email protected]> kim <[email protected]>
diff --git a/tardis/analysis.py b/tardis/analysis.py
@@ -1,4 +1,6 @@
-# codes to for analyse the model.
+"""
+Code to analyse the model.
+"""
 
 import re
 import os

diff --git a/tardis/base.py b/tardis/base.py
@@ -1,4 +1,6 @@
-# Functions that are important for the general usage of TARDIS.
+"""
+Functions that are important for the general usage of TARDIS.
+"""
 
 import logging
 

diff --git a/tardis/grid/__init__.py b/tardis/grid/__init__.py
@@ -1 +1,7 @@
+"""
+Storing a grid of TARDIS parameters that 
+facilitates running large numbers of 
+simulations easily.
+"""
+
 from tardis.grid.base import *
diff --git a/tardis/gui/__init.py__ b/tardis/gui/__init.py__
diff --git a/tardis/gui/__init__.py b/tardis/gui/__init__.py
@@ -0,0 +1,9 @@
+"""
+Creation of the basic framework for the TARDIS GUI.
+
+The data that should be displayed in the GUI is put into 
+respective data structures (either a tree or a table), such 
+that they can be used in the widgets. These widgets are 
+used to form the building blocks of the basic framework for
+the GUI.
+"""
diff --git a/tardis/io/__init__.py b/tardis/io/__init__.py
@@ -1,3 +1,7 @@
+"""
+A collection of subpackages and submodules to handle input and output data. 
+"""
+
 # readin model_data
 from tardis.io.model_reader import (
     read_simple_ascii_density,

diff --git a/tardis/io/atom_data/__init__.py b/tardis/io/atom_data/__init__.py
@@ -1,2 +1,6 @@
+"""
+Getting and handling the atomic data. 
+"""
+
 from tardis.io.atom_data.base import AtomData
 from tardis.io.atom_data.atom_web_download import download_atom_data
diff --git a/tardis/io/logger/__init__.py b/tardis/io/logger/__init__.py
@@ -0,0 +1,3 @@
+"""
+Managing the logging output. 
+"""
diff --git a/tardis/io/parsers/__init__.py b/tardis/io/parsers/__init__.py
@@ -1,3 +1,12 @@
+"""
+A collection of parsers to read data of different formats. 
+
+Accepted data formats are Arepo snapshots, the Blondin toy-model
+format, CSVY files and STELLA files. These are parsed into 
+either CSV files, YAML files or Pandas DataFrames, which are 
+data formats interpretable by TARDIS. 
+"""
+
 from tardis.io.parsers.blondin_toymodel import (
     read_blondin_toymodel,
     convert_blondin_toymodel,

diff --git a/tardis/model/__init__.py b/tardis/model/__init__.py
@@ -1 +1,9 @@
+"""
+Holding information about the TARDIS model. 
+
+This includes information about the shell structure, 
+density, abundance, temperatures and dilution 
+factor of the model used in the simulation.
+"""
+
 from tardis.model.base import *
diff --git a/tardis/model/geometry/__init__.py b/tardis/model/geometry/__init__.py
@@ -0,0 +1,10 @@
+"""
+Holding information about model geometry for radial 1D models.
+
+The information stored about the model are the following attributes:
+r_inner : The radius of the inner shell boundaries
+r_outer : The radius of the outer shell boundaries
+v_inner : The velocity of the inner boundaries of each shell
+v_outer : The velocity of the outer boundaries of each shell
+volume : Volume of each shell computed from r_outer and r_inner
+"""
diff --git a/tardis/montecarlo/__init__.py b/tardis/montecarlo/__init__.py
@@ -1 +1,10 @@
+"""
+Faciliating the MonteCarlo iterations. 
+
+During a simulation run, a number of MonteCarlo iterations specified
+in the configuration are run using the numba compiler.
+Most of the iterations are used to calculate the steady-state plasma 
+properties and with the last iteration, the spectrum is determined.
+"""
+
 from tardis.montecarlo.base import *
diff --git a/tardis/montecarlo/montecarlo_numba/__init__.py b/tardis/montecarlo/montecarlo_numba/__init__.py
@@ -1,3 +1,7 @@
+"""
+Implements the main loop of the MonteCarlo routine.
+"""
+
 from llvmlite import binding
 
 binding.set_option("tmp", "-non-global-value-max-name-size=2048")

diff --git a/tardis/plasma/__init__.py b/tardis/plasma/__init__.py
@@ -1 +1,5 @@
+"""
+Dealing with plasma properties and calculations related to it. 
+"""
+
 from tardis.plasma.base import BasePlasma
diff --git a/tardis/plasma/properties/__init__.py b/tardis/plasma/properties/__init__.py
@@ -1,3 +1,10 @@
+"""
+Store and calculate the properties of the plasma.
+
+Each plasma object has an array of properties which are then used to calculate plasma parameter values.
+Every property has a calculate function that returns the values of its outputs.
+"""
+
 from tardis.plasma.properties.atomic import *
 from tardis.plasma.properties.general import *
 from tardis.plasma.properties.ion_population import *

diff --git a/tardis/plasma/properties/util/__init__.py b/tardis/plasma/properties/util/__init__.py
@@ -1 +1,3 @@
-
+"""
+Calculating transition probabilities for macro_atom interactions.
+"""
diff --git a/tardis/scripts/__init__.py b/tardis/scripts/__init__.py
@@ -0,0 +1,3 @@
+"""
+Translate cmfgen format to a format TARDIS can use.
+"""
diff --git a/tardis/simulation/__init__.py b/tardis/simulation/__init__.py
@@ -1 +1,5 @@
+"""
+Handling simulation runs.
+"""
+
 from tardis.simulation.base import Simulation
diff --git a/tardis/stats/__init__.py b/tardis/stats/__init__.py
@@ -1 +1,3 @@
-
+"""
+Providing Poisson statistics that govern the MonteCarlo processes.
+"""
diff --git a/tardis/transport/__init__.py b/tardis/transport/__init__.py
@@ -1 +1,3 @@
-
+"""
+Handling the packet propagation.
+"""
diff --git a/tardis/transport/geometry/__init__.py b/tardis/transport/geometry/__init__.py
@@ -1 +1,3 @@
-
+"""
+Calculating distances.
+"""
diff --git a/tardis/util/__init__.py b/tardis/util/__init__.py
@@ -1 +1,3 @@
-# Utilities for TARDIS
+"""
+Utilities for TARDIS.
+"""