Merge 2fa1172 into 319310c

docs/conf.py

@@ -33,7 +33,7 @@
     'numpy': ('http://docs.scipy.org/doc/numpy/', None),
     'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
     'matplotlib': ('http://matplotlib.sourceforge.net/', None),
-    'astropy': ('http://www.astropy.org/', None),
+    'astropy': ('http://docs.astropy.org/en/stable/', None),
     'h5py': ('http://h5py.alfven.org/docs-2.1/', None),
     'pandas': ('http://pandas.pydata.org/pandas-docs/dev/', None)
 }

docs/examples/abund.dat

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

docs/examples/density.dat

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

docs/examples/examples.rst

@@ -0,0 +1,28 @@
+**************
+Example Models
+**************
+
+
+Here's an overview of some of the different modes of operation and models for TARDIS
+
+.. toctree::
+    :maxdepth: 1
+
+    profileuniform
+
+    profilemodel
+
+
+.. note:: 
+
+   Increasing the number of virtual packets will improve the
+   signal-to-noise of TARDIS spectra. You may wish to consider using a
+   filter (e.g. Savitzky–Golay) to suppress the Monte Carlo noise for
+   some applications.
+
+.. warning::
+
+   The usefulness of any TARDIS calculations depends on the
+   quality of the input atomic data. For further information on the atomic data -
+   including details of how to develop your own dataset to suit your
+   needs - please contact us.

docs/examples/profilemodel.rst

@@ -0,0 +1,109 @@
+***********************************************
+Model with custom density and abundance profile
+***********************************************
+
+TARDIS can be used to compute a synthetic spectrum for a model with user-specified density and abundance profiles -
+this makes it possible to experiment with 1D profiles based on explosion models or with any empirical description of a
+model with stratified abundances or density.
+
+
+Arbitrary density profile
+=========================
+
+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.
+
+Stratified abundance profile
+============================
+
+For a model with density profile supplied via a file (see above), uniform abundances can be supplied as normal.
+Alternatively, a set of stratified elemental abundances can also be supplied. As with the density,
+the abundances are specified via an ascii file. An ascii file that could work with the example density file given
+above should be formatted like this:
+
+.. literalinclude:: abund.dat
+
+
+
+In this file:
+
+- there should be the same number of rows as there were indexed points in the density profile file
+- 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 density profile file (called "density.dat") and abundance profile file (called "abund.dat"),
+you can use them in TARDIS by putting the following lines in the model section of the yaml file (and remove all other lines from these sections):
+
+.. literalinclude:: tardis_configv1_ascii_density_abund.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/profileuniform.rst

@@ -0,0 +1,90 @@
+***********************************************
+Model with custom density profile and uniform abundances
+***********************************************
+
+TARDIS can be used to compute a synthetic spectrum for a model with a
+user-specified density and chosen set of abundances -
+this makes it possible to experiment with 1D density profiles and
+simple specifications of the composition
+
+
+Arbitrary density profile
+=========================
+
+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.
+
+Uniform abundances
+============================
+
+For a model with density profile supplied via a file (see above),
+uniform 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
+=================
+
+If you create a correctly formatted density profile file (called
+"density.dat"), here is an example of how it can be combined with a uniform set of
+abundances:  
+
+.. literalinclude:: tardis_configv1_ascii_density_uniabund.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/tardis_configv1_ascii_density_abund.yml

@@ -0,0 +1 @@
+../../tardis/io/tests/data/tardis_configv1_ascii_density_abund.yml

docs/examples/tardis_configv1_ascii_density_uniabund.yml

@@ -0,0 +1 @@
+../../tardis/io/tests/data/tardis_configv1_ascii_density_uniabund.yml