Merge pull request #532 from unoebauer/improved_docs

Documentation overhaul

docs/conf.py

@@ -8,7 +8,7 @@
 # Note that not all possible configuration values are present in this file.
 #
 # All configuration values have a default. Some values are defined in
-# the global Astropy configuration which is loaded here before anything else. 
+# the global Astropy configuration which is loaded here before anything else.
 # See astropy.sphinx.conf for which values are set there.
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -39,7 +39,8 @@
     'astropy': ('http://docs.astropy.org/en/stable/', None)
 }
 
-import sphinx_bootstrap_theme
+# import sphinx_bootstrap_theme
+import sphinx_rtd_theme
 
 extensions = [
     'sphinx.ext.autodoc',
@@ -110,8 +111,8 @@
 # a list of builtin themes. To override the custom theme, set this to the
 # name of a builtin theme or the name of a custom theme in html_theme_path.
 #html_theme = None
-html_theme = 'bootstrap'
-html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = sphinx_rtd_theme.get_html_theme_path()
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}

docs/configuration/configuration.rst

@@ -2,5 +2,12 @@
 Configuration File
 ******************
 
+.. note::
+    The following block shows the contents of
+    ''tardis/data/tardis_config_definition.yml'' and thus gives an account of all
+    the  configuration keys TARDIS recognises, whether it considers these entries
+    mandatory and which default values the validator will use if they are not
+    provided in the YAML file.
+
 .. literalinclude:: ../../tardis/data/tardis_config_definition.yml
-    :language: yaml
+    :language: yaml

docs/configuration/index.rst

@@ -2,15 +2,38 @@
 TARDIS Configuration
 ********************
 
-Most of the configuration for TARDIS uses the YAML format. If a YAML file is
-handed to TARDIS it is first checked using a configuration validator to
-see if the required keywords of the required type exist and produces a dictionary
-with that has the validated types as well as sensible defaults for missing values
-built-in. This validator uses a default validation file that already explains
-a lot about the required configuration items.
+Overview
+========
 
-.. toctree::
-    :maxdepth: 1
+The bulk of the parameters for a TARDIS simulation are provided via a YAML
+configuration file. In a first step, the integrity of the specified
+configuration file is checked by a configuration validator. During this
+process, missing entries are replaced by default values. The following sections
+and pages provide more details concerning the TARDIS configuration process.
 
-    configuration
-    config_validator
+Configuration Details
+=====================
+
+* :doc:`In depth description of config options <configuration_old>`
+* :doc:`Validation Process <config_validator>`
+* :doc:`Example Configuration with Default Values <configuration>`
+
+
+.. warning::
+    We are currently in the process of overhauling the configuration system.
+    See `TEP 006 <https://github.com/tardis-sn/tep/blob/master/TEP006_configuration_tags.rst>`_
+    and stay tuned!
+
+..
+  Most of the configuration for TARDIS uses the YAML format. If a YAML file is
+  handed to TARDIS it is first checked using a configuration validator to
+  see if the required keywords of the required type exist and produces a dictionary
+  with that has the validated types as well as sensible defaults for missing values
+  built-in. This validator uses a default validation file that already explains
+  a lot about the required configuration items.
+  
+  .. toctree::
+      :maxdepth: 1
+  
+      configuration
+      config_validator

docs/credits.rst

@@ -1,17 +1,80 @@
-*******
-Credits
-*******
+.. _credits:
 
-Core Team
-=========
+******************************
+Credits & Publication Policies
+******************************
+
+We provide TARDIS as a free, open-source tool. If you are using it, please
+adhere to a few policies and acknowledge the TARDIS Team.
+
+
+Publication Policies
+====================
+
+If you use this code for any publications or presentations please acknowledge
+it accordingly. Please cite `Kerzendorf & Sim 2014
+<http://adsabs.harvard.edu/abs/2014MNRAS.440..387K>`_ and the `zenodo record
+<https://zenodo.org/record/17630>`_ of the TARDIS version you are using
+
+You can use the following bibtex entry:
+
+.. code-block:: none
+
+  @ARTICLE{2014MNRAS.440..387K,
+     author = {{Kerzendorf}, W.~E. and {Sim}, S.~A.},
+      title = "{A spectral synthesis code for rapid modelling of supernovae}",
+    journal = {\mnras},
+  archivePrefix = "arXiv",
+     eprint = {1401.5469},
+   primaryClass = "astro-ph.SR",
+   keywords = {radiative transfer, methods: numerical, supernovae: general},
+       year = 2014,
+      month = may,
+     volume = 440,
+      pages = {387-404},
+        doi = {10.1093/mnras/stu055},
+     adsurl = {http://adsabs.harvard.edu/abs/2014MNRAS.440..387K},
+    adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+  }
+ 
+User modifications and additions that lead to publications need to be handed
+back to the community by incorporating them into this publicly available
+version of TARDIS. Please contact the TARDIS team via the `github page
+<https://github.com/tardis-sn/tardis>`_ if you have questions or need
+assistance.
+
+TARDIS Team
+===========
+
+Principle Investigator
+----------------------
 
  * Wolfgang Kerzendorf
- * Stuart Sim
+
+Core Team
+---------
+
+ * Aoife Boyle
+ * Vytautas Jancauskas
  * Michael Klauser
  * Markus Kromer
+ * Stefan Lietzau
+ * Ulrich Noebauer
+ * Stuart Sim
+ * Christian Vogl
+
+
+Current and Former GSoC and SOCIS Students
+------------------------------------------
+
+ * Aoife Boyle (GSoC 2015)
+ * Karan Desai (GSoC 2016)
+ * Vytautas Jancauskas (GSoC 2015)
+ * Mikhail Mishin (GSoC 2016)
+ * Fotis Tsamis (GSoC 2016)
 
-Contributers
-============
+Contributors
+------------
 
  * Maryam Patel (documentation, test environment)
  * Adam Suban-Loewen (GUI, profiling and parallelization)

docs/examples/abundancecust.rst

@@ -0,0 +1,57 @@
+*************************************
+Using a custom stratified composition
+*************************************
+
+Overview
+========
+
+To use a stratified ejecta composition in TARDIS, the elemental abundances may
+be specified on a per-cell basis via an external ascii file (similar to setting
+up a :doc:`custom density <densitycust>` profile). An ascii file that could
+work on a mesh with ten cells should be formatted like this:
+
+.. literalinclude:: abund.dat
+
+In this file:
+
+- there should be the same number of rows as there are cells specified in the velocity/density structure part of the TARDIS setup
+- each row contains 31 numbers, the first of which is the index (i.e. matching the zone to the density profile file)
+- the remaining 30 entries in each row give the set of elemental abundances for atomic number Z=1 to Z=30 (in order)
+
+The abundances are specified as mass fractions (i.e. the sum of columns 1 to 30
+in each row should be 1.0).  TARDIS does not currently include any elements
+heavier that Z=30.  The mass fractions specified will be adopted directly in
+the TARDIS calculations - so if your model is e.g. based on an explosion
+simulation you may need to calculate the state of any radioactive decay chains
+at the correct epoch.
+
+The example file shown here has three simple layers: 
+
+- an innermost region (indices 0 to 2) that is composed of Si (Z=14), S (Z=16), Ar (Z=18), Ca (Z=20), Fe (Z=26), Co (Z=27) and Ni (Z=28)
+
+- a middle region (indices 3 to 7) that is composed of O (Z=8), Mg (Z=12), Si, S, Ar and Ca
+
+- an outer region (indices 8 and 9) that is composed of C (Z=6) and O.
+
+.. warning::
+
+   The example given here is to show the format only. It is not a
+   realistic model. In any real calculation better resolution
+   (i.e. more grid points) should be used.
+
+.. warning::
+
+   The calculation can be no better / more complete than the atomic
+   data set. For further information on the atomic database -
+   including details of how to develop your own dataset to suit your
+   needs, please contact us.
+
+TARDIS input file
+=================
+
+If you create a correctly formatted abundance profile file (called "abund.dat"
+in this example), you can use it in TARDIS by putting the following lines in
+the model section of the yaml file:
+
+.. literalinclude:: tardis_configv1_abundance_cust_example.yml
+    :language: yaml

docs/examples/abundanceuni.rst

@@ -0,0 +1,36 @@
+***************************
+Using a uniform composition
+***************************
+
+Overview
+========
+
+The simplest possibility for specifying an ejecta composition is to use a
+uniform abundance pattern in all cells specified in the density profile setup
+step. These constant abundances  can be supplied directly in the input (yaml)
+file. Elemental abundances are set in the "abundances" subsection of the "model"
+section, following the "type: uniform" specifier (see example input
+file below). They are specified as mass fractions. E.g.
+
+.. code-block:: none
+
+    Si: 0.6
+    S: 0.4
+
+will set the mass fraction of silicon (Z=14) to 0.6 and sulphur (Z=16) to 0.4.
+
+.. note::
+
+    The mass fractions must sum to one. If mass fractions are supplied that do not sum to one, TARDIS will
+    renormalise all the supplied abundances and print a "WARNING" message.
+
+
+TARDIS input file
+=================
+
+The following example shows the relevant section of a TARDIS input yaml file
+which specifies a uniform ejecta composition;
+
+.. literalinclude:: tardis_configv1_abundance_uniform_example.yml
+    :language: yaml
+

docs/examples/densitycust.rst

@@ -0,0 +1,66 @@
+******************************
+Using a custom density profile
+******************************
+
+Overview
+========
+
+TARDIS has also the capability to work with arbitrary density profiles. This is
+particularly useful if the results of detailed explosion simulations should be
+mapped into TARDIS. The density profile is supplied in the form of a simple
+ascii file that should look something like this:
+
+.. literalinclude:: density.dat
+
+In this file:
+
+- the first line gives the reference time (see below)
+
+- (the second line in our example is a comment)
+
+- the remaining lines (ten in our example) give an indexed table of points that specify mass density (g / cm^3) as a function of velocity (km /s). 
+
+TARDIS will use this table of density versus velocity to specify the density
+distribution in the ejecta.  For the calculation, TARDIS will use the reference
+time given in the file to scale the mass densities to whatever epoch is
+requested by assuming homologous expansion:
+
+.. math::
+
+     \rho (t_{exp}) = \rho (t_{ref}) (t_{ref} / t_{exp})^{3}
+
+The values in the example here define a density profile that is dropping off with
+
+.. math::
+
+    \rho \propto v^{-5}
+
+.. note::
+
+    The grid of points specified in the input file is interpreted by
+    TARDIS as defining a grid in which the tabulated velocities are
+    taken as the outer boundaries of grid cells and the density is
+    assumed to be uniform with each cell.
+
+.. warning::
+
+   The example given here is to show the format only. It is not a
+   realistic model. In any real calculation better resolution
+   (i.e. more grid points) should be used.
+
+
+TARDIS input file
+=================
+
+If you create a correctly formatted density profile file (called "density.dat"
+in this example), you can use it in TARDIS by putting the following lines in
+the model section of the yaml file:
+
+.. literalinclude:: tardis_configv1_density_cust_example.yml
+    :language: yaml
+
+.. note::
+    The specifications for the velocities of the inner and outer boundary values can be neglected
+    (in which case TARDIS will default to using the full velocity range specified in the density.txt file).
+    Values for the boundary velocities that lie outside the range covered by density.txt will not be accepted.
+

docs/examples/densityexp.rst

@@ -0,0 +1,33 @@
+************************************
+Using an exponential density profile
+************************************
+
+Overview
+========
+
+In this mode, the density profile (function of velocity and time since
+explosion) is assumed to follow a functional form:
+
+.. math::
+
+    \rho (v, t_{exp}) = \rho_0 (t_{0} / t_{exp})^{3} \exp( -v / v_0)
+
+defined by reference density, velocity and time parameters. These
+parameters are set in the input yaml file, specifically in the "structure"
+subsection of the "model" section, under the "density" heading (see
+example below).
+
+.. note::
+
+   In this mode, the velocity grid has to be explicitly defined in the yml file (see example below)
+
+
+TARDIS input file example
+=========================
+
+The following example shows the relevant sections of a TARDIS input yaml file,
+specifying an exponential density:
+
+.. literalinclude:: tardis_configv1_density_exponential_example.yml
+    :language: yaml
+