Models

TARDIS requires a model of the ejecta in order to run a simulation. A model typically includes information for the velocity shell structure, density, and abundances. See Model for more information on the TARDIS model. TARDIS offers two ways of specifying the model: either directly in the configuration YAML file or separately in a CSVY file. See here for an explanation of the CSVY file format.

TARDIS has several built-in models for the shell structure, density, and abundance. If only these are being used, we recommend using the YAML configuration method. For creating a custom model (which will be discussed below), we recommend using the CSVY method.

Model Configuration

The following schema shows how the model section of the YAML configuration is set up:

type	object
properties
structure	oneOf	Specific Structure
		File Structure
abundances	oneOf	File Abundance
		Uniform Abundance
additionalProperties	False

Several examples are shown in the following sections; additionally, see TARDIS Example Configuration to see an example model configuration section within the full TARDIS configuration. This configuration allows for both built-in structures and abundances, which will be described in later sections, as well as custom models for the shell structure and abundances. For the latter, while we recommend using the CSVY model, one can specify custom structures and abundances using other files.

Note

If using a custom shell structure, you must also use a custom density profile (and vice versa), as they are recorded in the same file (see below). Therefore, if you wish to use a built-in shell structure you must also use a built-in density profile, and vice versa.

Custom Model Configurations

The following two sections demonstrate how to specify custom structures and abundances in the model configuration.

File Structure

One can use a file referenced in the model configuration to create a custom structure model and density profile.

type	object
properties
type	enum	file
filename	file name (with path) to structure model
	type	string
filetype	file type
	type	string
	enum	simple_ascii, artis, cmfgen_model
v_inner_boundary	location of the inner boundary chosen from the model
	type	quantity
	default	-1 km/s
v_outer_boundary	location of the inner boundary chosen from the model
	type	quantity
	default	-1 km/s
additionalProperties	False

For example:

model:
    structure:
        type: file
        filename: density.dat
        filetype: simple_ascii
        v_inner_boundary: 11000 km/s
        v_outer_boundary: 20000 km/s

In this example, our configuration references a file named density.dat. For more information on what this file would entail, see:

• Using a custom density profile

File Abundance

One can use a file referenced in the model configuration to create a custom elemental abundances.

type	object
properties
type	enum	file
filetype	type of abundance file to read in
	type	string
filename	filename
	type	string
additionalProperties	False

For example:

model:
    
    abundances:
        type: file
        filename: abund.dat
        filetype: simple_ascii

In this example, our configuration references a file named abund.dat. For more information on what this file would entail, see:

• Using a custom stratified composition

Custom Model Tutorial

• How to run TARDIS with a custom ejecta model
  • Your custom density file
  • Your custom abundance file
  • Running TARDIS with the custom files
  • Specifying boundary velocities in the config file
  • Example 1) v_inner_boundary lower than first velocity in density file
  • Example 2) v_outer_boundary larger than last velocity in density file
  • Example 3) v_boundaries in config file are within density file velocity range

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.

• Converting STELLA Files to be usable by TARDIS
• Convert CMFGEN files to TARDIS file format
• Converting Arepo snapshots to be usable by TARDIS
  • What is Arepo?
  • Loading the simulation data
  • Extracting a profile and converting it to a csvy file
  • Manually rebinning the data

Built-in Structure, Density, and Abundance

TARDIS’s built-in models for structure, density, and abundance are described in the following sections:

Structure

When using the built-in structure functionality, 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. See Shell Structure for more information.

Specific Structure

The following schema shows how to use the built-in structure model and density profiles.

type	object
properties
type	enum	specific
velocity	description of the boundaries of the shells
	type	object
	properties
	start	type	quantity
	stop	type	quantity
	num	type	number
		multipleOf	1.0
density	oneOf	Branch85_w7 Density
		Exponential Density
		Power_law Density
		Uniform Density
additionalProperties	False

We present an example of the above schema:

model:
    structure:
        type: specific
        velocity:
            start: 1000 km/s
            stop: 2000 km/s
            num: 15
        density:
            type: branch85_w7 #see density schemas below for all options in the density section

Density

In the densities section of the specific structure, the type parameter decides on the parameters. The physics of these density models is further discussed in Model.

Branch85_w7 Density

The type branch85_w7 uses a seventh-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.

type	object
properties
type	enum	branch85_w7
w7_time_0	This needs no change - DO NOT TOUCH
	type	quantity
	default	0.000231481 day
w7_rho_0	This needs no change - DO NOT TOUCH
	type	quantity
	default	3e29 g/cm^3
w7_v_0	This needs no change - DO NOT TOUCH
	type	quantity
	default	1 km/s
additionalProperties	False

For example:

model:
    structure:
        type: specific

        density:
            type: branch85_w7

For more information, see Branch85 W7 Density.

Exponential Density

This schema shows how to configure an exponential density profile (see the page linked below).

type	object
properties
type	enum	exponential
time_0	Time at which the pure model densities are right
	type	quantity
rho_0	density at time_0
	type	quantity
v_0	at what velocity the density rho_0 applies
	type	quantity
additionalProperties	False

For example:

model:
    structure:
        type: specific

        density:
            type: exponential
            rho_0: 1e-10 g/cm^3
            v_0: 10000 km/s

For more information, see Exponential Density.

Power_law Density

This schema shows how to configure a power law density profile (see the page linked below).

type	object
properties
type	enum	power_law
time_0	Time at which the pure model densities are right
	type	quantity
rho_0	density at time_0
	type	quantity
v_0	at what velocity the density rho_0 applies
	type	quantity
exponent	exponent for exponential density profile
	type	number
additionalProperties	False

For example:

model:
    structure:
        type: specific

        density:
            type: power_law
            rho_0: 1e-10 g/cm^3
            v_0: 10000 km/s
            exponent: 3

For more information, see Power Law Density.

Uniform Density

For a uniform density profile, one need only specify a single parameter – the value of the uniform density.

type	object
properties
type	enum	uniform
time_0	Time at which the pure model densities are right
	type	quantity
value	value for uniform density
	type	quantity
additionalProperties	False

For example:

model:
    structure:
        type: specific

        density:
            type: uniform
            value: 1e-10 g/cm^3

For more information, see Uniform Density.

Abundance

This section can be used to configure uniform abundances for all shells, by giving the atom or isotope name and a relative abundance fraction. If it does not add up to 1, TARDIS will warn – but normalize the numbers.

Uniform Abundance

The following schema shows how to use TARDIS’s built-in uniform abundance configuration.

type	object
properties
type	enum	uniform
additionalProperties	type	number
	maximum	1
	minimum	0

For example:

model:

    abundances:
        type: uniform
        H: 0.2
        He: 0.4
        O: 0.15
        Ni56: 0.25

For more information, see Abundance.

CSVY Model

TARDIS allows users to use a CSVY file to input information about the model. To do this, instead of a model section, one includes csvy_model: <file path to CSVY file> in the main TARDIS configuration file.

The CSVY model has a YAML part as well as a CSV part, separated by the YAML delimiter ---. 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, then another line with just the YAML delimiter, and finally the CSV portion of the CSVY file. This is shown in the example CSVY file later in this section.

The YAML portion of the CSVY file allows the user to use most of the features of the YAML model configuration, as shown in the schema below:

type	object
properties
name	name of the model being run
	type	string
model_density_time_0	Initial time for the density in the model
	type	quantity
model_isotope_time_0	Initial time for isotope decay. Set to 0 for no isotopes.
	type	quantity
description	description of the model being run
	type	string
tardis_model_config_version	Version of the configuration file
	type	string
datatype	fields found in csv part of csvy file
	type	object
	properties
	fields	type	array
	additionalProperties	False
v_inner_boundary	velocity of the inner boundary
	type	quantity
v_outer_boundary	velocity of the outer boundary of the last shell
	type	quantity
velocity	type	object
	properties
	start	type	quantity
	stop	type	quantity
	num	type	number
		multipleOf	1.0
density	oneOf	Branch85_w7 Density
		Exponential Density
		Power_law Density
		Uniform Density
abundance	Uniform Abundance
additionalProperties	False

The CSV part of the CSVY file creates a table that can include information about shell velocities, densities, and abundances in each cell. The column headers (the first row of the CSV part) may contain velocity, density, t_rad, dilution_factor, or the name of any element or isotope (e.g. H, Mg, Ni56). These columns are explained in the following example:

---
name: csvy_full
model_density_time_0: 1 day
model_isotope_time_0: 0 day
description: Example csvy config file for TARDIS.
tardis_model_config_version: v1.0
datatype:
  fields:
    -  name: velocity
       unit: km/s
       desc: velocities of shell outer bounderies.
    -  name: density
       unit: g/cm^3
       desc: density of shell.
    -  name: t_rad
       unit: K
       desc: radiative temperature.
    -  name: dilution_factor
       desc: dilution factor of shell.
    -  name: H
       desc: fractional H abundance.
    -  name: He
       desc: fractional He abundance.
    -  name: Ni56
       desc: fractional Ni56 abundance.

---
velocity,density,t_rad,dilution_factor,H,He,Ni56
9000, 5e-10, 7000, .9, 1.0, 1.0, 1.0
10500, 2.0e-10, 7000, .8, 0.0, 0.99, 0.01
12000, 9e-11, 7000, .1, 0.4, 0.58, 0.02

Notice that for each column that is used in the CSV section of the file, there is a corresponding field under datatype in the YAML section of the file. In our example, each of the fields under datatype has a brief description to go along with it. While the description is not necessary for any of the fields, the unit section is required for velocity, density, and t_rad.

Since the velocity column contains the outer shell velocity, the first entry in the velocity column is the velocity of the photosphere – i.e. the inner boundary of the computational domain (see Model). Consequently, none of the other information in the first row is used. In our example, there are only two shells, and the first shell will have an inner boundary with a velocity of \(9000 \mathrm{ km/s}\), an outer boundary with a velocity of \(10500 \mathrm{ km/s}\), a density of \(2.0*10^{-10} \mathrm{ g/cm^3}\), a dilution factor of .8, etc.

Note

None of the CSV columns are required. However, if velocity, density, or the abundances are missing, they must be specified in the YAML portion of the file. If t_rad or dilution_factor are missing, they will be automatically calculated (see Model).

Note

t_rad and dilution_factor are the values of the temperature and dilution factor for the first iteration, and will be updated in subsequent iterations (see Estimators and Convergence). To prevent these quantities from being changed, you must set the damping constant to zero in the Damped Convergence Configuration in the Monte Carlo section of the configuration file.

CSVY Model Tutorial

Coming soon!