Atomic Data — TARDIS v0.9.dev692

# Atomic Data

The atomic data for tardis is stored in hdf5 files. TARDIS ships with a relatively simple atomic dataset which only contains silicon lines and levels. TARDIS also has a full atomic dataset which contains the complete Kurucz dataset (http://kurucz.harvard.edu/LINELISTS/GFALL/). This full dataset also contains recombination coefficients from the ground state (\(\zeta-\textrm{factor}\) used in Calculating Zeta) and data for calculating the branching or macro atom line interaction (macroatom).

## HDF5 Dataset

As mentioned previously, all atomic data is stored in hdf5 files which contain tables that include mass, ionization, levels and lines data. The atom data that ships with TARDIS is located in data/atom

The dataset `basic_atom_set` contains the Atomic Number, Symbol of the elements and average mass of the elements.

### Basic Atomic Data

Name | Description | Unit
--- | --- | ---
atomic_number | Atomic Number (e.g. He = 2) | z
symbol | Symbol (e.g. He, Fe, Ca, etc.) | None
mass | Average mass of atom | u

The ionization data is stored in `ionization_data`.

### Ionization Data

Name | Description | Unit
--- | --- | ---
atomic_number(z) | Atomic Number | 1
ion_number | Ion Number | 1
ionization_energy | Ionization Energy of atom | eV

The levels data is stored in `levels_data`.

### Levels Data

Name | Description | Unit
--- | --- | ---
atomic_number(z) | Atomic Number | 1
ion_number | Ion Number | 1
level_number | Level Number | 1
energy | Energy of a particular level | eV
g |  | 1
metastable |  | bool

All lines are stored in `lines_data`.

### Lines Data

Name | Description | Unit
--- | --- | ---
wavelength | Waveslength | angstrom
atomic_number(z) | Atomic Number | 1
ion_number | Ion Number | 1
f_ul | Upper level probability | 1
f_lu | Lower level probability | 1
level_id_lower | Upper level id | 1
level_id_upper | Lower level id | 1

The next three datasets are only contained in the full dataset available upon request from the authors.

The factor correcting for photo-ionization from excited levels (needed in Calculating Zeta) is stored in the dataset `zeta_data`. The data is stored in a special way as one large `numpy.ndarray` where the first two columns are Atomic Number and Ion Number. All further columns are the \(\zeta-\textrm{factors}\) for different temperatures. The temperatures are stored in the attribute `t_rads`.

Name | Description | Unit
--- | --- | ---
atomic_number(z) | Atomic Number | 1
ion_number | Ion Number | 1
T_XXXX | Temperature for column | K
... | ... | ...
T_XXXX | Temperature for column | K

There are two datasets for using the macro atom and branching line interactions. The `macro_atom_data` and `macro_atom_references`:

The `macro_atom_data` contains blocks of transition probabilities, several indices and flags. The Transition Type flag has three states -1 for downwards emitting, 0 for downwards internal and 1 for upwards internal (for more explanations please refer to macroatom)

### Macro Atom Data

Name | Description | Unit
--- | --- | ---
atomic_number(z) | Atomic Number | 1
ion_number | Ion Number | 1
source_level_number | Source Level Number | 1
destination_level_number | Destination Level Number | 1
transition_type | Transition Type | 1
transition_probability | Transition Probability | 1
transition_line_id | Transition Line ID | 1

Here’s the structure of the probability block. The atomic number, ion number and source level number are the same within each block, the destination level number the transition type and transition probability are changing. The transition probabilities are only part of the final probability and will be changed during the calculation. For details on the macro atom please refer to macroatom.

Atomic Number | Ion Number | Source Level Number | Destination Level Number | Transition Type | Transition probabilities | Transition Line ID
--- | --- | --- | --- | --- | --- | ---
Z1 | I1 | i1 | j1 | -1 | Pemission down 1 | k1
Z1 | I1 | i1 | j2 | -1 | Pemission down 2 | k2
... | ... | ... | ... | ... | ... | ...
Z1 | I1 | i1 | jn | -1 | Pemission down n | kn
Z1 | I1 | i1 | j1 | 0 | Pinternal down 1 | k1
Z1 | I1 | i1 | j2 | 0 | Pinternal down 2 | k2
... | ... | ... | ... | ... | ... | ...
Z1 | I1 | i1 | jn | 0 | Pinternal down n | kn
Z1 | I1 | i1 | j1 | 1 | Pinternal up 1 | k1
Z1 | I1 | i1 | j2 | 1 | Pinternal up 2 | k2
... | ... | ... | ... | ... | ... | ...
Z1 | I1 | i1 | jn | 1 | Pinternal up n | kn

The `macro_references` dataset contains the numbers for each block:

### Macro Atom References

Name | Description | Unit
--- | --- | ---
atomic_number(z) | Atomic Number | 1
ion_number | Ion Number | 1
source_level_number | Source Level Number | 1
count_down | Number of down transitions | 1
count_up | Number of up transitions | 1
count_total | Total number of transitions | 1

## The Atom Data Class

Atom Data is stored inside TARDIS in the `AtomData`-class. The class method `AtomData.from_hdf5()` will instantiate a new AtomData-class from an HDF5 file. If none is given it will automatically take the default HDF5-dataset shipped with TARDIS. A second function `AtomData.prepare_atom_data()` will cut the levels and lines data to only the required atoms and ions. In addition, it will create the intricate system of references needed by macro atom or branching line interactions.

## Indexing fun

The main problem with the atomic data is indexing. Most of these references require multiple numbers, e.g. atomic number, ion number and level number. The :py:module:`pandas`-framework provides the ideal functions to accomplish this. In TARDIS we extensively use `pandas.MultiIndex`, `pandas.Series` and `pandas.DataFrame`

TO BE BETTER DOCUMENTED ...