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:

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.

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:

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:

Custom Model Tutorial

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.

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.

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.

For example:

model:
    structure:
        type: specific

        density:
            type: branch85_w7

For more information, see Branch85 W7 Density.

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.

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.

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.

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:

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 boundaries.
    -  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 Updating Plasma 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!