Merge 7bee957 into 1ee849e

docs/_static/tardis.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: none;
+}

docs/_templates/layout.html

@@ -7,3 +7,6 @@
   {{ super() }}
   <a href="http://github.com/wkerzendorf/tardis"><img style="position: fixed; top: 0px; right: 0; border: 0; z-index: 100000;image-orientation: 90deg;" src="https://s3.amazonaws.com/github/ribbons/forkme_left_darkblue_121621.png" alt="Fork me on GitHub"/></a>
 {% endblock %}
+{% block extrahead %}
+    <link href="{{ pathto("_static/tardis.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}

docs/conf.py

@@ -50,6 +50,8 @@
     'sphinx.ext.graphviz',
     'numpydoc',
     'nbsphinx',
+    'sphinx.ext.autodoc',
+    'sphinx-jsonschema'
 ]
 
 source_suffix = '.rst'
@@ -122,6 +124,7 @@
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
+html_static_path = ['_static']
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

docs/configuration/configuration.rst

@@ -2,5 +2,167 @@
 Configuration File
 ******************
 
+TARDIS uses the `YAML markup language <https://en.wikipedia.org/wiki/YAML>`_
+for its configuration files. There are several sections which allow different
+settings for the different aspects of the TARDIS calculation. An example
+configuration file can be downloaded :download:`here
+<../examples/tardis_example.yml>`.
+
+.. warning::
+    One should note that currently floats in YAML need to be specified in a special format:
+    any pure floats need to have a +/- after the e e.g. 2e+5
+
+
+The TARDIS configuration consists of multiple sections that pertain to certain parts of the code. We will use the
+schemas to show what options are available. Our schema mark-up defines names in bold-fat as required.
+can be seen here:
+
 .. note::
-    This page is Work in Progress.
+
+    The following shows all the options (and their default settings) that are available for TARDIS. No other options
+    are allowed or available
+
+Configuration Schema
+====================
+
+.. jsonschema:: schemas/base.yml
+
+
+The base schema links to several other configuration parts
+
+
+Supernova
+---------
+
+.. jsonschema:: schemas/supernova.yml
+
+
+Model
+-----
+
+The next sections, describing the model, are very hierarchical. The base level is ``model`` and contains two subsections:
+``structure`` and ``abundances``. Both sections can either contain a ``file`` subsection which specifies a file and
+file type where the information is stored or a number of other sections.
+
+.. jsonschema:: schemas/model.yml
+
+In the ``structure`` section, one can specify a ``file`` section containing a ``type`` parameter
+(currently only ``artis`` is supported``) and a ``name`` parameter giving a path top a file. For the ``artis`` type,
+one can specify the inner and outermost shell by giving a ``v_lowest`` and ``v_highest`` parameter. This will result in
+the selection of certain shells which will be obeyed in the abundance section as well if ``artis`` is selected there as
+well.
+
+.. warning::
+    If a ``file`` section is given, all other parameters and sections in the ``structure`` section are ignored!
+
+If one doesn't specify a ``file`` section, the code requires two sections (``velocities`` and ``densities``) and a
+parameter ``no_of_shells``. ``no_of_shells`` is the requested number of shells for a model. The ``velocity`` section
+requires a ``type``. Currently, only ``linear`` is supported and needs two parameters ``v_inner`` and ``v_outer`` with
+velocity values for the inner most and outer most shell.
+
+In the ``densities`` section the ``type`` parameter again decides on the parameters. The type ``uniform`` only needs a
+ ``value`` parameter with a density compatible quantity. The type ``branch85_w7`` uses a seven order polynomial fit to
+ the W7 model and is parametrised by time since explosion. The parameters ``time_0`` and ``density_coefficient`` are set
+ to sensible defaults and should not be changed.
+
+The ``abundance`` section again has a possible ``file`` parameter with ``type`` (currently only ``artis`` is allowed)
+and a ``name`` parameter giving a path to a file containing the abundance information.
+
+.. warning::
+    In contrast to the ``structure`` section, the ``abundance`` section will not ignore abundances set in the rest of
+    the section, but merely will overwrite the abundances given in the file section.
+
+In this section we also specify the species that will be calculated with our :ref:`nlte` formalism using the
+``nlte_species`` parameter (they are specified in a list using astrophysical notation, e.g. [Si2, Ca2, Mg2, H1]).
+The rest of the section can be used to configure uniform abundances for all shells, by giving the atom name and a
+relative abundance fraction. If it does not add up to 1., TARDIS will warn - but normalize the numbers.
+
+
+
+Plasma
+------
+
+.. jsonschema:: schemas/plasma.yml
+
+``inital_t_inner`` is temperature of the black-body on the inner boundary. ``initial_t_rad`` is the
+radiation temperature for all cells. For debugging purposes and to compare to :term:`synapps` calculations one can
+disable the electron scattering. TARDIS will issue a warning that this is not physical.
+There are currently two ``plasma_type`` options available: ``nebular`` and ``lte`` which tell TARDIS how to run the
+ionization equilibrium and level population calculations (see :ref:`plasmas` for more information).
+The radiative rates describe how to calculate the :math:`J_\textrm{blue}` needed for the :ref:`nlte` calculations and
+:ref:`macroatom` calculations. There are three options for ``radiative_rates_type``: 1) ``lte`` in which
+:math:`J_\textrm{blue} = \textrm{Blackbody}(T_\textrm{rad})`, 2) ``nebular`` in which
+:math:`J_\textrm{blue} = W \times \textrm{Blackbody}(T_\textrm{rad})`, 3) ``detailed`` in which the :math:`J_\textrm{blue}`
+are calculated using an estimator (this is described in ??????).
+
+TARDIS currently supports three different kinds of line interaction: ``scatter`` - a resonance scattering implementation,
+``macroatom`` - the most complex form of line interaction described in :ref:`macroatom` and ``downbranch`` a simplified
+version of ``macroatom`` in which only downward transitions are allowed.
+
+Finally, ``w_epsilon`` describes the dilution factor to use to calculate :math:`J_\textrm{blue}` that are 0, which
+causes problem with the code (so :math:`J_\textrm{blue}` are set to a very small number).
+
+NLTE
+^^^^
+
+.. code-block:: yaml
+
+    nlte:
+        coronal_approximation: True
+        classical_nebular: False
+
+The NLTE configuration currently allows setting ``coronal_approximation`` which sets all :math:`J_\textrm{blue}` to 0.
+This is useful for debugging with :term:`chianti` for example. Furthermore one can enable 'classical_nebular' to set all
+:math:`\beta_\textrm{Sobolev}` to 1. Both options are used for checking with other codes and should not be enabled in
+normal operations.
+
+
+
+Monte Carlo
+-----------
+
+The ``montecarlo`` section describes the parameters for the MonteCarlo radiation transport and convergence criteria:
+
+.. jsonschema:: schemas/montecarlo.yml
+
+The ``seed`` parameter seeds the random number generator first for the creation of the packets
+(:math:`\nu` and :math:`\mu`) and then the interactions in the actual MonteCarlo process.
+The ``no_of_packets`` parameter can take a float number for input convenience and gives the number of packets normally
+used in each MonteCarlo loop. The parameters ``last_no_of_packets`` and ``no_of_virtual_packets`` influence the last run
+of the MonteCarlo loop when the radiation field should have converged. ``last_no_of_packets`` is normally higher than
+``no_of_packets`` to create a less noisy output spectrum. ``no_of_virtual_packets`` can also be set to greater than 0 to
+use the Virtual Packet formalism (reference missing ?????). The ``iterations`` parameter describes the maximum number of
+MonteCarlo loops executed in a simulation before it ends. Convergence criteria can be used to make the simulation stop
+sooner when the convergence threshold has been reached.
+
+The ``convergence_criteria`` section again has a ``type`` keyword. Two types are allowed: ``damped`` and ``specific``.
+All convergence criteria can be specified separately for the three variables for which convergence can be checked
+(``t_inner``, ``t_rad``, ``ws``) by specifying subsections in the ``convergence_criteria`` of the same name. These
+override then the defaults.
+
+
+#. ``damped`` only has one parameter ``damping-constant`` and does not check for convergence.
+
+#. ``specific`` checks for the convergence threshold specified in ``threshold``. For ``t_rad`` and ``w`` only a given
+    fraction (specified in ``fraction``) has to cross the ``threshold``. Once a convergence  threshold is read, the simulation
+    needs to hold this state for ``hold`` number of iterations.
+
+
+Spectrum
+--------
+
+Start and end are given as Quantities with units. If they are given in
+frequency space they are switched around if necessary. The number of bins is
+just an integer. Finally, the method option selects the final spectral synthesis mode. Currently, there are three options:
+
+* real: construct spectrum from the real packet population alone
+* virtual: use the :doc:`virtual packet scheme <../montecarlo/virtualpackets>` for spectral synthesis
+* integrated: use the :doc:`formal integral method <../montecarlo/sourceintegration>` of Lucy 1999
+
+.. warning::
+
+  Currently, the "integrated" mode only works with the downbranching line
+  interaction mode. Note also the limitations listed at the bottom of the
+  dedicated page.
+
+.. jsonschema:: schemas/spectrum.yml

docs/configuration/configuration_old.rst

@@ -1,8 +1,8 @@
 .. _config-file:
 
-******************
-Configuration File
-******************
+**********************
+Old Configuration File
+**********************
 
 .. :currentmodule:: tardis.config_reader
 
@@ -16,29 +16,31 @@ configuration file can be downloaded :download:`here
     One should note that currently floats in YAML need to be specified in a special format:
     any pure floats need to have a +/- after the e e.g. 2e+5
 
-Every configuration file begins with the most basic settings for the model:
+..
 
-.. code-block:: yaml
+    Every configuration file begins with the most basic settings for the model:
+
+    .. code-block:: yaml
 
-    ---
-    #Currently only simple1d is allowed
-    config_type: simple1d
+        ---
+        #Currently only simple1d is allowed
+        config_type: simple1d
 
-    #luminosity any astropy.unit convertible to erg/s
-    #special unit log_lsun(log(luminosity) - log(L_sun)
-    luminosity: 9.44 log_lsun
+        #luminosity any astropy.unit convertible to erg/s
+        #special unit log_lsun(log(luminosity) - log(L_sun)
+        luminosity: 9.44 log_lsun
 
-    #time since explosion
-    time_explosion: 13 day
+        #time since explosion
+        time_explosion: 13 day
 
-    atom_data: ../atom_data/kurucz_atom_chianti_many.h5
+        atom_data: ../atom_data/kurucz_atom_chianti_many.h5
 
-The ``config_type`` currently only allows ``simple1d``, but might be expanded in future versions of TARDIS. Many
-parameters in the TARDIS configuration files make use of units. One can use any unit that is supported by
-`astropy units <http://docs.astropy.org/en/stable/units/index.html>`_ as well as the unit ``log_lsun``
-which is :math:`\log(L) - \log(L_\odot)`. Time since explosion just takes a normal time quantity. ``atom_data`` requires
-the path to the HDF5 file that contains the atomic data (more information about the HDF5 file can be found
-here :ref:`atomic-data`).
+    The ``config_type`` currently only allows ``simple1d``, but might be expanded in future versions of TARDIS. Many
+    parameters in the TARDIS configuration files make use of units. One can use any unit that is supported by
+    `astropy units <http://docs.astropy.org/en/stable/units/index.html>`_ as well as the unit ``log_lsun``
+    which is :math:`\log(L) - \log(L_\odot)`. Time since explosion just takes a normal time quantity. ``atom_data`` requires
+    the path to the HDF5 file that contains the atomic data (more information about the HDF5 file can be found
+    here :ref:`atomic-data`).
 
 Plasma
 ^^^^^^

docs/configuration/index.rst

@@ -1,39 +1,25 @@
-********************
-TARDIS Configuration
-********************
+*************
+Configuration
+*************
 
-Overview
-========
 
 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 Details
-=====================
 
-* :doc:`In depth description of config options <configuration_old>`
-* :doc:`Validation Process <config_validator>`
-* :doc:`Example Configuration with Default Values <configuration>`
+.. toctree::
+  :maxdepth: 3
 
+  configuration
+  config_validator
 
 .. 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
+  The following section contains the old configuration description and will be deleted soon
+
+.. toctree::
+  :maxdepth: 1
+
+  configuration_old

docs/configuration/schemas/base.yml

@@ -0,0 +1 @@
+../../../tardis/io/schemas/base.yml

docs/configuration/schemas/model.yml

@@ -0,0 +1 @@
+../../../tardis/io/schemas/model.yml

docs/configuration/schemas/montecarlo.yml

@@ -0,0 +1 @@
+../../../tardis/io/schemas/montecarlo.yml

docs/configuration/schemas/plasma.yml

@@ -0,0 +1 @@
+../../../tardis/io/schemas/plasma.yml

docs/configuration/schemas/spectrum.yml

@@ -0,0 +1 @@
+../../../tardis/io/schemas/spectrum.yml

docs/configuration/schemas/supernova.yml

@@ -0,0 +1 @@
+../../../tardis/io/schemas/supernova.yml

docs/index.rst

@@ -38,6 +38,7 @@ Using Tardis
 
     installation
     running
+    configuration/index
     examples/index
     scripts/index
     credits

tardis/io/schemas/base.yml

@@ -4,9 +4,10 @@ additionalProperties: false
 properties:
   tardis_config_version:
     type: string
-    description: Version of the configuration file
+    description: Version of the configuration file. The current version is 1.0 and no other versions are allowed
   supernova:
     $ref: supernova.yml
+    description: a section pertaining to observations of the supernova
   atom_data:
     type: string
     description: path or filename to the Atomic Data HDF5 file
@@ -18,6 +19,7 @@ properties:
     $ref: montecarlo.yml
   spectrum:
     $ref: spectrum.yml
+    description: Final spectrum sampling
 required:
 - tardis_config_version
 - atom_data

tardis/io/schemas/spectrum.yml

@@ -15,4 +15,3 @@ properties:
             - real
     default: virtual
     description: The method to generate the final spectrum
-  description: Final spectrum sampling

tardis/io/schemas/supernova.yml

@@ -10,7 +10,7 @@ properties:
     description: time since explosion
   distance:
     type: quantity
-    description: distance to supernova
+    description: distance to supernova - **THIS IS DEPRECATED AND NOT IN USE**
   luminosity_wavelength_start:
     type: quantity
     default: 0 angstrom

tardis_env27.yml

@@ -45,3 +45,4 @@ dependencies:
   - pytest-html==1.10.0
   - dokuwiki
   - dot2tex
+  - sphinx-jsonschema