diff --git a/docs/_static/full_configuration.yml b/docs/_static/full_configuration.yml deleted file mode 100644 index a6973497e70..00000000000 --- a/docs/_static/full_configuration.yml +++ /dev/null @@ -1,120 +0,0 @@ -#IMPORTANT any pure floats need to have a +/- after the e e.g. 2e+5 -#Hopefully pyyaml will fix this soon. ---- -#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 - -#time since explosion -time_explosion: 13 day - - -atom_data: ../atom_data/kurucz_atom_chianti_many.h5 - -plasma: - initial_t_inner: 10000 K - initial_t_rad: 10000 K - disable_electron_scattering: no - plasma_type: nebular - #radiative_rates_type - currently supported are lte, nebular and detailed - radiative_rates_type: detailed - #line interaction type - currently supported are scatter, downbranch and macroatom - line_interaction_type : macroatom - w_epsilon : 1.0e-10 - -nlte: - coronal_approximation: True - classical_nebular: False - -model: - structure: - no_of_shells : 20 -# file: -# type : artis -# name : artis_model.dat -# v_lowest: 10000.0 km/s -# v_highest: 20000.0 km/s - - - velocity: - type : linear - v_inner : 1.1e4 km/s - v_outer : 2e4 km/s - - - density: - #showing different configuration options separated by comments - #simple uniform: - #--------------- -# type : uniform -# value : 1e-12 g/cm^3 - #--------------- - - #branch85_w7 - fit of seven order polynomial to W7 (like Branch 85): - #--------------- - type : branch85_w7 - #value : 1e-12 - # default, no need to change! - #time_0 : 19.9999584 s - # default, no need to change! - #density_coefficient : 3e29 - #--------------- - - - abundances: - #file: - # type : artis - # name : artis_abundances.dat - -# abundance_set: -# type: uniform -# name: lucy99 -# nlte_species : [Si2] -# C: 0.01 -# O: 0.01 -# Ne: 0.01 -# Mg: 0.01 -# Si: 0.45 -# S: 0.35 -# Ar: 0.04 -# Ca: 0.03 -# Fe: 0.07 -# Co: 0.01 -# Ni: 0.01 - Cu: 1.00 - - -montecarlo: - seed: 23111963171620 - no_of_packets : 2.e+4 - iterations: 100 - convergence_criteria: - type: specific - damping_constant: 0.5 - threshold: 0.05 - fraction: 0.8 - hold: 3 - - - -# convergence_criteria: -# type: 'tighten' -# tighten_parameters: [1., 1., 0.75, 0.5, 0.25, 0.125] -# convergence_percentage: 0.01 - -# type: 'undampened' -# t_inner_convergence: 0.01 - - -# last_no_of_packets: 2.0e+5 -# no_of_virtual_packets: 10 - - -spectrum: - start : 500 angstrom - end : 20000 angstrom - bins : 1000 - sn_distance : lum_density diff --git a/docs/conf.py b/docs/conf.py index 77b604020ef..c433ac5062d 100644 --- a/docs/conf.py +++ b/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) } diff --git a/docs/examples/abund.dat b/docs/examples/abund.dat new file mode 120000 index 00000000000..7fc5f39eb0a --- /dev/null +++ b/docs/examples/abund.dat @@ -0,0 +1 @@ +../../tardis/io/tests/data/abund.dat \ No newline at end of file diff --git a/docs/examples/density.dat b/docs/examples/density.dat new file mode 120000 index 00000000000..c8ade6bb665 --- /dev/null +++ b/docs/examples/density.dat @@ -0,0 +1 @@ +../../tardis/io/tests/data/density.dat \ No newline at end of file diff --git a/docs/examples/examples.rst b/docs/examples/examples.rst new file mode 100644 index 00000000000..d6f11b4a863 --- /dev/null +++ b/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. diff --git a/docs/examples/profilemodel.rst b/docs/examples/profilemodel.rst new file mode 100644 index 00000000000..4f890515936 --- /dev/null +++ b/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. + diff --git a/docs/examples/profileuniform.rst b/docs/examples/profileuniform.rst new file mode 100644 index 00000000000..d1cebbad193 --- /dev/null +++ b/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. + diff --git a/docs/examples/tardis_configv1_ascii_density_abund.yml b/docs/examples/tardis_configv1_ascii_density_abund.yml new file mode 120000 index 00000000000..997fef91c76 --- /dev/null +++ b/docs/examples/tardis_configv1_ascii_density_abund.yml @@ -0,0 +1 @@ +../../tardis/io/tests/data/tardis_configv1_ascii_density_abund.yml \ No newline at end of file diff --git a/docs/examples/tardis_configv1_ascii_density_uniabund.yml b/docs/examples/tardis_configv1_ascii_density_uniabund.yml new file mode 120000 index 00000000000..7baec5a1656 --- /dev/null +++ b/docs/examples/tardis_configv1_ascii_density_uniabund.yml @@ -0,0 +1 @@ +../../tardis/io/tests/data/tardis_configv1_ascii_density_uniabund.yml \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 6c27b22462e..18c84eb4550 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,22 @@ rapid spectral modelling of supernovae. The code is described in this documentat .. note:: This documentation is currently under construction and does not describe all of the modes of operations available for TARDIS. + +.. toctree:: + :maxdepth: 1 + + installation + running + gui + uses + examples/examples + atomic + plasma + montecarlo + glossary + zreferences + credits + The code is built on a few principles: * **open** - the code is fully open source and we invite usage and contributions from the community @@ -38,19 +54,7 @@ We are using Astropy's excellent workflow - more details can be found at `