From 239e04bd87a8c0ef56cf91d7800671056acb1438 Mon Sep 17 00:00:00 2001 From: Le Truong <43793681+PommesFrittes@users.noreply.github.com> Date: Mon, 27 Feb 2023 21:42:39 +0100 Subject: [PATCH] Add docstrings to subpackages (#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 --------- Co-authored-by: kim Co-authored-by: Sona Chitchyan --- .mailmap | 5 +++++ tardis/analysis.py | 4 +++- tardis/base.py | 4 +++- tardis/grid/__init__.py | 6 ++++++ tardis/gui/__init.py__ | 0 tardis/gui/__init__.py | 9 +++++++++ tardis/io/__init__.py | 4 ++++ tardis/io/atom_data/__init__.py | 4 ++++ tardis/io/logger/__init__.py | 3 +++ tardis/io/parsers/__init__.py | 9 +++++++++ tardis/model/__init__.py | 8 ++++++++ tardis/model/geometry/__init__.py | 10 ++++++++++ tardis/montecarlo/__init__.py | 9 +++++++++ tardis/montecarlo/montecarlo_numba/__init__.py | 4 ++++ tardis/plasma/__init__.py | 4 ++++ tardis/plasma/properties/__init__.py | 7 +++++++ tardis/plasma/properties/util/__init__.py | 4 +++- tardis/scripts/__init__.py | 3 +++ tardis/simulation/__init__.py | 4 ++++ tardis/stats/__init__.py | 4 +++- tardis/transport/__init__.py | 4 +++- tardis/transport/geometry/__init__.py | 4 +++- tardis/util/__init__.py | 4 +++- 23 files changed, 110 insertions(+), 7 deletions(-) delete mode 100644 tardis/gui/__init.py__ create mode 100644 tardis/gui/__init__.py diff --git a/.mailmap b/.mailmap index 469c9342f1b..f90fdfc9f16 100644 --- a/.mailmap +++ b/.mailmap @@ -227,3 +227,8 @@ Youssef Eweis Youssef Eweis Rohith Varma Buddaraju rohithvarma3000 Rohith Varma Buddaraju Rohith + +Le Truong + +Kim Lingemann kimsina +Kim Lingemann kim diff --git a/tardis/analysis.py b/tardis/analysis.py index c2f469ed8b7..b6aad9fced4 100644 --- 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 index fd9b5457f3d..3f429bdfbba 100644 --- 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 index eb8bb8410b2..1b5b3213ca9 100644 --- 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__ deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/tardis/gui/__init__.py b/tardis/gui/__init__.py new file mode 100644 index 00000000000..a22e23fccfd --- /dev/null +++ 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 index ca4d671e64b..c1d44a57897 100644 --- 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 index 5fd5f11b1ce..39d2bbdfef1 100644 --- 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 index e69de29bb2d..78bc5622358 100644 --- 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 index ef3825cde24..2ae18fa4d7b 100644 --- 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 index 66f102eba18..3399f042e29 100644 --- 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 index e69de29bb2d..44b4461913d 100644 --- 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 index 222ee95b0b8..eeb3ef212bd 100644 --- 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 index d73c539a7a9..a4eb6dc3c3a 100644 --- 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 index 67591ed64b5..ec0d4cd7358 100644 --- 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 index 002e45bc1fb..8ec73b81bcb 100644 --- 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 index 8b137891791..9aec5b1c60a 100644 --- 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 index e69de29bb2d..63fb31fbbbd 100644 --- 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 index 8c88a5ab087..101ac28d6f7 100644 --- 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 index 8b137891791..b174821c479 100644 --- 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 index 8d1c8b69c3f..41612a06e1d 100644 --- 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 index 8d1c8b69c3f..d585337f711 100644 --- 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 index 6dd4694b3ef..e1b28566f74 100644 --- a/tardis/util/__init__.py +++ b/tardis/util/__init__.py @@ -1 +1,3 @@ -# Utilities for TARDIS +""" +Utilities for TARDIS. +"""