% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}
\usepackage{multirow}


\title{TARDIS Documentation}
\date{September 17, 2013}
\release{0.9.dev574}
\author{Stuart Sim and Wolfgang Kerzendorf}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex

\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
    \let\PYG@ul=\relax \let\PYG@tc=\relax%
    \let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
    \PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
    \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}

\expandafter\def\csname PYG@tok@gd\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gu\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@gt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.27,0.87}{##1}}}
\expandafter\def\csname PYG@tok@gs\endcsname{\let\PYG@bf=\textbf}
\expandafter\def\csname PYG@tok@gr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@cm\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@vg\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@m\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@cs\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}
\expandafter\def\csname PYG@tok@ge\endcsname{\let\PYG@it=\textit}
\expandafter\def\csname PYG@tok@vc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@il\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@go\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\expandafter\def\csname PYG@tok@cp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@gi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gh\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@ni\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}}
\expandafter\def\csname PYG@tok@nl\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}}
\expandafter\def\csname PYG@tok@nn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@no\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}}
\expandafter\def\csname PYG@tok@na\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@nb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@nd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\expandafter\def\csname PYG@tok@ne\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\expandafter\def\csname PYG@tok@si\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}}
\expandafter\def\csname PYG@tok@s2\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@vi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@nt\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}}
\expandafter\def\csname PYG@tok@nv\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@s1\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@gp\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@sh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@ow\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@sx\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@bp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c1\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@kc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@mf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@err\endcsname{\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}
\expandafter\def\csname PYG@tok@kd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@ss\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}}
\expandafter\def\csname PYG@tok@sr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}}
\expandafter\def\csname PYG@tok@mo\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@kn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@o\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}}
\expandafter\def\csname PYG@tok@kr\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@s\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@kp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@w\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\expandafter\def\csname PYG@tok@kt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}}
\expandafter\def\csname PYG@tok@sc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@k\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@se\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sd\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}

\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
\def\PYGZam{\char`\&}
\def\PYGZlt{\char`\<}
\def\PYGZgt{\char`\>}
\def\PYGZsh{\char`\#}
\def\PYGZpc{\char`\%}
\def\PYGZdl{\char`\$}
\def\PYGZhy{\char`\-}
\def\PYGZsq{\char`\'}
\def\PYGZdq{\char`\"}
\def\PYGZti{\char`\~}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother

\begin{document}

\maketitle
\tableofcontents
\phantomsection\label{index::doc}


This is the documentation for the TARDIS package.


\chapter{Introduction}
\label{introduction:introduction}\label{introduction::doc}\label{introduction:tardis}
This is a package for supernova radiative transfer called Temporal And Radiative Diffusion In Supernovae.


\chapter{Installation}
\label{installation:installation}\label{installation::doc}
very easy to install


\chapter{Running TARDIS}
\label{running:running-tardis}\label{running::doc}
To run TARDIS requires two files. The atomic database (for more info refer to {\hyperref[atomic:atomic-data]{\emph{Atomic Data}}}) and a
configuration file (more info at {\hyperref[configuration:config-file]{\emph{Configuration File}}}).

Currently there is no script that can run TARDIS. However it is very easy to set one up:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{tardis} \PYG{k+kn}{import} \PYG{n}{config\PYGZus{}reader}\PYG{p}{,} \PYG{n}{model\PYGZus{}radial\PYGZus{}oned}\PYG{p}{,} \PYG{n}{simulation}

\PYG{n}{tardis\PYGZus{}config} \PYG{o}{=} \PYG{n}{config\PYGZus{}reader}\PYG{o}{.}\PYG{n}{TARDISConfiguration}\PYG{o}{.}\PYG{n}{from\PYGZus{}yaml}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{myconfig.yml}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{radial1d\PYGZus{}mdl} \PYG{o}{=} \PYG{n}{model\PYGZus{}radial\PYGZus{}oned}\PYG{o}{.}\PYG{n}{Radial1DModel}\PYG{p}{(}\PYG{n}{tardis\PYGZus{}config}\PYG{p}{)}
\PYG{n}{simulation}\PYG{o}{.}\PYG{n}{run\PYGZus{}radial1d}\PYG{p}{(}\PYG{n}{radial1d\PYGZus{}mdl}\PYG{p}{)}
\end{Verbatim}


\chapter{Graphical User Interface}
\label{gui::doc}\label{gui:graphical-user-interface}
TARDIS uses the \href{http://www.riverbankcomputing.com/software/pyqt/download}{PyQt4 framework} for its cross-platform
interface.

The GUI runs through the \href{http://ipython.org/install.html}{IPython Interpreter} which should be started with the
command \code{ipython-2.7 -{-}pylab=qt}, so that it has acess to pylab.

Creating an instance of the \code{ModelViewer}-class requires that PyQt4 has already been initialized in
IPython. The above command to start IPython accomplishes this.


\section{GUI Layout and Features}
\label{gui:gui-layout-and-features}

\chapter{Configuration File}
\label{configuration:configuration-file}\label{configuration::doc}\label{configuration:config-file}
TARDIS uses the \href{https://en.wikipedia.org/wiki/YAML}{YAML markup language} for its configuration files. There are several sections which allow different
settings for the different aspects of the TARDIS calculation. An example configuration file can be downloaded
\code{here}.

\begin{notice}{warning}{Warning:}
One should note that currently floats in YAML need to be specified in a special format:
any pure floats need to have a +/- after the e e.g. 2e+5
\end{notice}

Every configuration file begins with the most basic settings for the model:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nn}{\PYGZhy{}\PYGZhy{}\PYGZhy{}}
\PYG{c+c1}{\PYGZsh{}Currently only simple1d is allowed}
\PYG{l+lScalar+lScalarPlain}{config\PYGZus{}type}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{simple1d}

\PYG{c+c1}{\PYGZsh{}luminosity any astropy.unit convertible to erg/s}
\PYG{c+c1}{\PYGZsh{}special unit log\PYGZus{}lsun(log(luminosity) \PYGZhy{} log(L\PYGZus{}sun)}
\PYG{l+lScalar+lScalarPlain}{luminosity}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{9.44}\PYG{l+lScalar+lScalarPlain}{ }\PYG{l+lScalar+lScalarPlain}{log\PYGZus{}lsun}

\PYG{c+c1}{\PYGZsh{}time since explosion}
\PYG{l+lScalar+lScalarPlain}{time\PYGZus{}explosion}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{13}\PYG{l+lScalar+lScalarPlain}{ }\PYG{l+lScalar+lScalarPlain}{day}

\PYG{l+lScalar+lScalarPlain}{atom\PYGZus{}data}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{../atom\PYGZus{}data/kurucz\PYGZus{}atom\PYGZus{}chianti\PYGZus{}many.h5}
\end{Verbatim}

The \code{config\_type} currently only allows \code{simple1d}, but might be expanded in future versions of TARDIS. Many
parameters in the TARDIS configuration files make use of units. One can use any unit that is supported by
\href{http://docs.astropy.org/en/stable/units/index.html}{astropy units} as well as the unit \code{log\_lsun}
which is $\log(L) - \log(L_\odot)$. Time since explosion just takes a normal time quantity. \code{atom\_data} requires
the path to the HDF5 file that contains the atomic data (more information about the HDF5 file can be found
here {\hyperref[atomic:atomic-data]{\emph{Atomic Data}}}).


\section{Plasma}
\label{configuration:plasma}
The next configuration block describes the plasma parameters:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{l+lScalar+lScalarPlain}{plasma}\PYG{p+pIndicator}{:}
    \PYG{l+lScalar+lScalarPlain}{initial\PYGZus{}t\PYGZus{}inner}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{10000}\PYG{l+lScalar+lScalarPlain}{ }\PYG{l+lScalar+lScalarPlain}{K}
    \PYG{l+lScalar+lScalarPlain}{initial\PYGZus{}t\PYGZus{}rad}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{10000}\PYG{l+lScalar+lScalarPlain}{ }\PYG{l+lScalar+lScalarPlain}{K}
    \PYG{l+lScalar+lScalarPlain}{disable\PYGZus{}electron\PYGZus{}scattering}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{no}
    \PYG{l+lScalar+lScalarPlain}{plasma\PYGZus{}type}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{nebular}
    \PYG{c+c1}{\PYGZsh{}radiative\PYGZus{}rates\PYGZus{}type \PYGZhy{} currently supported are lte, nebular and detailed}
    \PYG{l+lScalar+lScalarPlain}{radiative\PYGZus{}rates\PYGZus{}type}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{detailed}
    \PYG{c+c1}{\PYGZsh{}line interaction type \PYGZhy{} currently supported are scatter, downbranch and macroatom}
    \PYG{l+lScalar+lScalarPlain}{line\PYGZus{}interaction\PYGZus{}type} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{macroatom}
    \PYG{l+lScalar+lScalarPlain}{w\PYGZus{}epsilon} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{1.0e\PYGZhy{}10}
\end{Verbatim}

\code{inital\_t\_inner} is temperature of the black-body on the inner boundary. \code{initial\_t\_rad} is the
radiation temperature for all cells. For debugging purposes and to compare to {\hyperref[glossary:term-synapps]{\emph{synapps}}} calculations one can
disable the electron scattering. TARDIS will issue a warning that this is not physical.
There are currently two \code{plasma\_type} options available: \code{nebular} and \code{lte} which tell TARDIS how to run the
ionization equilibrium and level population calculations (see {\hyperref[plasma:plasmas]{\emph{Plasma}}} for more information).
The radiative rates describe how to calculate the $J_\textrm{blue}$ needed for the \emph{nlte} calculations and
\emph{macroatom} calculations. There are three options for \code{radiative\_rates\_type}: 1) \code{lte} in which
$J_\textrm{blue} = \textrm{Blackbody}(T_\textrm{rad})$, 2) \code{nebular} in which
$J_\textrm{blue} = W \times \textrm{Blackbody}(T_\textrm{rad})$, 3) \code{detailed} in which the $J_\textrm{blue}$
are calculated using an estimator (this is described in ??????).

TARDIS currently supports three different kinds of line interaction: \code{scatter} - a resonance scattering implementation,
\code{macroatom} - the most complex form of line interaction described in \emph{macroatom} and \code{downbranch} a simplified
version of \code{macroatom} in which only downward transitions are allowed.

Finally, \code{w\_epsilon} describes the dilution factor to use to calculate $J_\textrm{blue}$ that are 0, which
causes problem with the code (so $J_\textrm{blue}$ are set to a very small number).

\textbf{NLTE}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{l+lScalar+lScalarPlain}{nlte}\PYG{p+pIndicator}{:}
    \PYG{l+lScalar+lScalarPlain}{coronal\PYGZus{}approximation}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{True}
    \PYG{l+lScalar+lScalarPlain}{classical\PYGZus{}nebular}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{False}
\end{Verbatim}

The NLTE configuration currently allows setting \code{coronal\_approximation} which sets all $J_\textrm{blue}$ to 0.
This is useful for debugging with \emph{chianti} for example. Furthermore one can enable `classical\_nebular' to set all
$\beta_\textrm{Sobolev}$ to 1. Both options are used for checking with other codes and should not be enabled in
normal operations.


\section{Model}
\label{configuration:model}
The next sections, describing the model, are very hierarchical. The base level is \code{model} and contains two subsections:
\code{structure} and \code{abundances}. Both sections can either contain a \code{file} subsection which specifies a file and
file type where the information is stored or a number of other sections.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{l+lScalar+lScalarPlain}{model}\PYG{p+pIndicator}{:}
    \PYG{l+lScalar+lScalarPlain}{structure}\PYG{p+pIndicator}{:}
        \PYG{l+lScalar+lScalarPlain}{no\PYGZus{}of\PYGZus{}shells} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{20}

        \PYG{l+lScalar+lScalarPlain}{velocity}\PYG{p+pIndicator}{:}
            \PYG{l+lScalar+lScalarPlain}{type} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{linear}
            \PYG{l+lScalar+lScalarPlain}{v\PYGZus{}inner} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{1.1e4}\PYG{l+lScalar+lScalarPlain}{ }\PYG{l+lScalar+lScalarPlain}{km/s}
            \PYG{l+lScalar+lScalarPlain}{v\PYGZus{}outer} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{2e4}\PYG{l+lScalar+lScalarPlain}{ }\PYG{l+lScalar+lScalarPlain}{km/s}


        \PYG{l+lScalar+lScalarPlain}{density}\PYG{p+pIndicator}{:}
            \PYG{c+c1}{\PYGZsh{}showing different configuration options separated by comments}
            \PYG{c+c1}{\PYGZsh{}simple uniform:}
            \PYG{c+c1}{\PYGZsh{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}}
\PYG{c+c1}{\PYGZsh{}            type : uniform}
\PYG{c+c1}{\PYGZsh{}            value : 1e\PYGZhy{}12 g/cm\PYGZca{}3}
            \PYG{c+c1}{\PYGZsh{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}}

            \PYG{c+c1}{\PYGZsh{}branch85\PYGZus{}w7 \PYGZhy{} fit of seven order polynomial to W7 (like Branch 85):}
            \PYG{c+c1}{\PYGZsh{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}}
            \PYG{l+lScalar+lScalarPlain}{type} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{branch85\PYGZus{}w7}
            \PYG{c+c1}{\PYGZsh{}value : 1e\PYGZhy{}12}
            \PYG{c+c1}{\PYGZsh{} default, no need to change!}
            \PYG{c+c1}{\PYGZsh{}time\PYGZus{}0 : 19.9999584 s}
            \PYG{c+c1}{\PYGZsh{} default, no need to change!}
            \PYG{c+c1}{\PYGZsh{}density\PYGZus{}coefficient : 3e29}
            \PYG{c+c1}{\PYGZsh{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}}


\PYG{c+c1}{\PYGZsh{}        file:}
\PYG{c+c1}{\PYGZsh{}            type : artis}
\PYG{c+c1}{\PYGZsh{}            name : artis\PYGZus{}model.dat}
\PYG{c+c1}{\PYGZsh{}            v\PYGZus{}lowest: 10000.0 km/s}
\PYG{c+c1}{\PYGZsh{}            v\PYGZus{}highest: 20000.0 km/s}
\end{Verbatim}

In the \code{structure} section, one can specify a \code{file} section containing a \code{type} parameter
(currently only \code{artis} is supported{}`{}`) and a \code{name} parameter giving a path top a file. For the \code{artis} type,
one can specify the inner and outermost shell by giving a \code{v\_lowest} and \code{v\_highest} parameter. This will result in
the selection of certain shells which will be obeyed in the abundance section as well if \code{artis} is selected there as
well.

\begin{notice}{warning}{Warning:}
If a \code{file} section is given, all other parameters and sections in the \code{structure} section are ignored!
\end{notice}

If one doesn't specify a \code{file} section, the code requires two sections (\code{velocities} and \code{densities}) and a
parameter \code{no\_of\_shells}. \code{no\_of\_shells} is the requested number of shells for a model. The \code{velocity} section
requires a \code{type}. Currently, only \code{linear} is supported and needs two parameters \code{v\_inner} and \code{v\_outer} with
velocity values for the inner most and outer most shell.
\begin{description}
\item[{In the \code{densities} section the \code{type} parameter again decides on the parameters. The type \code{uniform} only needs a}] \leavevmode
\code{value} parameter with a density compatible quantity. The type \code{branch85\_w7} uses a seven order polynomial fit to
the W7 model and is parametrised by time since explosion. The parameters \code{time\_0} and \code{density\_coefficient} are set
to sensible defaults and should not be changed.

\end{description}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+c1}{\PYGZsh{}\PYGZhy{}\PYGZhy{} continued from model block before \PYGZhy{}\PYGZhy{}}
    \PYG{l+lScalar+lScalarPlain}{abundances}\PYG{p+pIndicator}{:}
        \PYG{c+c1}{\PYGZsh{}file:}
        \PYG{c+c1}{\PYGZsh{}    type : artis}
        \PYG{c+c1}{\PYGZsh{}    name : artis\PYGZus{}abundances.dat}

        \PYG{l+lScalar+lScalarPlain}{nlte\PYGZus{}species} \PYG{p+pIndicator}{:} \PYG{p+pIndicator}{[}\PYG{n+nv}{Si2}\PYG{p+pIndicator}{]}
        \PYG{l+lScalar+lScalarPlain}{C}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.01}
        \PYG{l+lScalar+lScalarPlain}{O}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.01}
        \PYG{l+lScalar+lScalarPlain}{Ne}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.01}
        \PYG{l+lScalar+lScalarPlain}{Mg}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.01}
        \PYG{l+lScalar+lScalarPlain}{Si}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.45}
        \PYG{l+lScalar+lScalarPlain}{S}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.35}
        \PYG{l+lScalar+lScalarPlain}{Ar}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.04}
        \PYG{l+lScalar+lScalarPlain}{Ca}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.03}
        \PYG{l+lScalar+lScalarPlain}{Fe}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.07}
        \PYG{l+lScalar+lScalarPlain}{Co}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.01}
        \PYG{l+lScalar+lScalarPlain}{Ni}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.01}
\end{Verbatim}

The \code{abundance} section again has a possible \code{file} parameter with \code{type} (currently only \code{artis} is allowed)
and a \code{name} parameter giving a path to a file containing the abundance information.

\begin{notice}{warning}{Warning:}
In contrast to the \code{structure} section, the \code{abundance} section will not ignore abundances set in the rest of
the section, but merely will overwrite the abundances given in the file section.
\end{notice}

In this section we also specify the species that will be calculated with our \emph{nlte} formalism using the
\code{nlte\_species} parameter (they are specified in a list using astrophysical notation, e.g. {[}Si2, Ca2, Mg2, H1{]}).
The rest of the section can be used to configure uniform abundances for all shells, by giving the atom name and a
relative abundance fraction. If it does not add up to 1., TARDIS will warn - but normalize the numbers.


\section{MonteCarlo}
\label{configuration:montecarlo}
The \code{montecarlo} section describes the parameters for the MonteCarlo radiation transport and convergence criteria:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{l+lScalar+lScalarPlain}{montecarlo}\PYG{p+pIndicator}{:}
    \PYG{l+lScalar+lScalarPlain}{seed}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{23111963171620}
    \PYG{l+lScalar+lScalarPlain}{no\PYGZus{}of\PYGZus{}packets} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{2.e+4}
    \PYG{l+lScalar+lScalarPlain}{iterations}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{100}

    \PYG{l+lScalar+lScalarPlain}{convergence\PYGZus{}criteria}\PYG{p+pIndicator}{:}
        \PYG{l+lScalar+lScalarPlain}{type}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{specific}
        \PYG{l+lScalar+lScalarPlain}{damping\PYGZus{}constant}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.5}
        \PYG{l+lScalar+lScalarPlain}{threshold}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.05}
        \PYG{l+lScalar+lScalarPlain}{fraction}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{0.8}
        \PYG{l+lScalar+lScalarPlain}{hold}\PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{3}

\PYG{c+c1}{\PYGZsh{}    convergence\PYGZus{}criteria:}
\PYG{c+c1}{\PYGZsh{}        type: damped}
\PYG{c+c1}{\PYGZsh{}        damping\PYGZus{}constant: 0.5}
\PYG{c+c1}{\PYGZsh{}        t\PYGZus{}inner:}
\PYG{c+c1}{\PYGZsh{}            damping\PYGZus{}constant: 0.7}
\end{Verbatim}

The \code{seed} parameter seeds the random number generator first for the creation of the packets
($\nu$ and $\mu$) and then the interactions in the actual MonteCarlo process.
The \code{no\_of\_packets} parameter can take a float number for input convenience and gives the number of packets normally
used in each MonteCarlo loop. The parameters \code{last\_no\_of\_packets} and \code{no\_of\_virtual\_packets} influence the last run
of the MonteCarlo loop when the radiation field should have converged. \code{last\_no\_of\_packets} is normally higher than
\code{no\_of\_packets} to create a less noisy output spectrum. \code{no\_of\_virtual\_packets} can also be set to greater than 0 to
use the Virtual Packet formalism (reference missing ?????). The \code{iterations} parameter describes the maximum number of
MonteCarlo loops executed in a simulation before it ends. Convergence criteria can be used to make the simulation stop
sooner when the convergence threshold has been reached.

The \code{convergence\_criteria} section again has a \code{type} keyword. Two types are allowed: \code{damped} and \code{specific}.
All convergence criteria can be specified separately for the three variables for which convergence can be checked
(\code{t\_inner}, \code{t\_rad}, \code{ws}) by specifying subsections in the \code{convergence\_criteria} of the same name. These
override then the defaults.
\begin{enumerate}
\item {} 
\code{damped} only has one parameter \code{damping-constant} and does not check for convergence.

\item {} \begin{description}
\item[{\code{specific} checks for the convergence threshold specified in \code{threshold}. For \code{t\_rad} and \code{w} only a given}] \leavevmode
fraction (specified in \code{fraction}) has to cross the \code{threshold}. Once a convergence  threshold is read, the simulation
needs to hold this state for \code{hold} number of iterations.

\end{description}

\end{enumerate}


\section{Spectrum}
\label{configuration:spectrum}
The spectrum section defines the

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{l+lScalar+lScalarPlain}{spectrum}\PYG{p+pIndicator}{:}
    \PYG{l+lScalar+lScalarPlain}{start} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{500}\PYG{l+lScalar+lScalarPlain}{ }\PYG{l+lScalar+lScalarPlain}{angstrom}
    \PYG{l+lScalar+lScalarPlain}{end} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{20000}\PYG{l+lScalar+lScalarPlain}{ }\PYG{l+lScalar+lScalarPlain}{angstrom}
    \PYG{l+lScalar+lScalarPlain}{bins} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{1000}
    \PYG{l+lScalar+lScalarPlain}{sn\PYGZus{}distance} \PYG{p+pIndicator}{:} \PYG{l+lScalar+lScalarPlain}{lum\PYGZus{}density}
    \PYG{c+c1}{\PYGZsh{}sn\PYGZus{}distance : 10 Mpc}
\end{Verbatim}

Start and end are given as Quantities with units. If they are given in frequency space they are switched around if
necessary. The number of bins is just an integer. Finally the \code{sn\_distance} can either be a distance or the special
parameter \code{lum\_density} which sets the distance to $\sqrt{\frac{1}{4 \pi}}$ to calculate the luminosity density.


\section{Config Reader}
\label{configuration:config-reader}
The YAML file is read by using a classmethod of the \code{from\_yaml()}.


\chapter{Atomic Data}
\label{atomic:id1}\label{atomic::doc}\label{atomic:atomic-data}
The atomic data for tardis is stored in \href{http://www.h5py.org/}{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 (\href{http://kurucz.harvard.edu/LINELISTS/GFALL/}{http://kurucz.harvard.edu/LINELISTS/GFALL/}). This full dataset also contains recombination
coefficients from the ground state ($\zeta-\textrm{factor}$ used in {\hyperref[plasma_doc/nebular_plasma:calc-zeta-label]{\emph{Calculating Zeta}}}) and data for calculating the
branching or macro atom line interaction (\emph{macroatom}).


\section{HDF5 Dataset}
\label{atomic:hdf5-dataset}
As mentioned previously, all atomic data is stored in \href{http://www.h5py.org/}{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 \code{basic\_atom\_set} contains the Atomic Number, Symbol of the elements and average mass of the elements.


\subsection{Basic Atomic Data}
\label{atomic:basic-atomic-data}
\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\textbf{
Name
} & \textbf{
Description
} & \textbf{
Unit
}\\\hline

atomic\_number
 & 
Atomic Number (e.g. He = 2)
 & 
z
\\\hline

symbol
 & 
Symbol (e.g. He, Fe, Ca, etc.)
 & 
None
\\\hline

mass
 & 
Average mass of atom
 & 
u
\\\hline
\end{tabulary}


The ionization data is stored in \code{ionization\_data}.


\subsection{Ionization Data}
\label{atomic:ionization-data}
\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\textbf{
Name
} & \textbf{
Description
} & \textbf{
Unit
}\\\hline

atomic\_number(z)
 & 
Atomic Number
 & 
1
\\\hline

ion\_number
 & 
Ion Number
 & 
1
\\\hline

ionization\_energy
 & 
Ionization Energy of atom
 & 
eV
\\\hline
\end{tabulary}


The levels data is stored in \code{levels\_data}.


\subsection{Levels Data}
\label{atomic:levels-data}
\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\textbf{
Name
} & \textbf{
Description
} & \textbf{
Unit
}\\\hline

atomic\_number(z)
 & 
Atomic Number
 & 
1
\\\hline

ion\_number
 & 
Ion Number
 & 
1
\\\hline

level\_number
 & 
Level Number
 & 
1
\\\hline

energy
 & 
Energy of a particular level
 & 
eV
\\\hline

g
 &  & 
1
\\\hline

metastable
 &  & 
bool
\\\hline
\end{tabulary}


All lines are stored in \code{lines\_data}.


\subsection{Lines Data}
\label{atomic:lines-data}
\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\textbf{
Name
} & \textbf{
Description
} & \textbf{
Unit
}\\\hline

wavelength
 & 
Waveslength
 & 
angstrom
\\\hline

atomic\_number(z)
 & 
Atomic Number
 & 
1
\\\hline

ion\_number
 & 
Ion Number
 & 
1
\\\hline

f\_ul
 & 
Upper level probability
 & 
1
\\\hline

f\_lu
 & 
Lower level probability
 & 
1
\\\hline

level\_id\_lower
 & 
Upper level id
 & 
1
\\\hline

level\_id\_upper
 & 
Lower level id
 & 
1
\\\hline
\end{tabulary}


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 {\hyperref[plasma_doc/nebular_plasma:calc-zeta-label]{\emph{Calculating Zeta}}}) is stored in the dataset \code{zeta\_data}.
The data is stored in a special way as one large \href{http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html\#numpy.ndarray}{\code{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 \code{t\_rads}.

\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\textbf{
Name
} & \textbf{
Description
} & \textbf{
Unit
}\\\hline

atomic\_number(z)
 & 
Atomic Number
 & 
1
\\\hline

ion\_number
 & 
Ion Number
 & 
1
\\\hline

T\_XXXX
 & 
Temperature for column
 & 
K
\\\hline

...
 & 
...
 & 
...
\\\hline

T\_XXXX
 & 
Temperature for column
 & 
K
\\\hline
\end{tabulary}


There are two datasets for using the macro atom and branching line interactions. The \code{macro\_atom\_data} and \code{macro\_atom\_references}:

The \code{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 \emph{macroatom})


\subsection{Macro Atom Data}
\label{atomic:macro-atom-data}
\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\textbf{
Name
} & \textbf{
Description
} & \textbf{
Unit
}\\\hline

atomic\_number(z)
 & 
Atomic Number
 & 
1
\\\hline

ion\_number
 & 
Ion Number
 & 
1
\\\hline

source\_level\_number
 & 
Source Level Number
 & 
1
\\\hline

destination\_level\_number
 & 
Destination Level Number
 & 
1
\\\hline

transition\_type
 & 
Transition Type
 & 
1
\\\hline

transition\_probability
 & 
Transition Probability
 & 
1
\\\hline

transition\_line\_id
 & 
Transition Line ID
 & 
1
\\\hline
\end{tabulary}


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 \emph{macroatom}.

\begin{tabulary}{\linewidth}{|L|L|L|L|L|L|L|}
\hline
\textbf{
Atomic Number
} & \textbf{
Ion Number
} & \textbf{
Source Level Number
} & \textbf{
Destination Level Number
} & \textbf{
Transition Type
} & \textbf{
Transition probabilities
} & \textbf{
Transition Line ID
}\\\hline

Z$_{\text{1}}$
 & 
I$_{\text{1}}$
 & 
i$_{\text{1}}$
 & 
j$_{\text{1}}$
 & 
-1
 & 
P$_{\text{emission down}}$ 1
 & 
k$_{\text{1}}$
\\\hline

Z$_{\text{1}}$
 & 
I$_{\text{1}}$
 & 
i$_{\text{1}}$
 & 
j$_{\text{2}}$
 & 
-1
 & 
P$_{\text{emission down}}$ 2
 & 
k$_{\text{2}}$
\\\hline

...
 & 
...
 & 
...
 & 
...
 & 
...
 & 
...
 & 
...
\\\hline

Z$_{\text{1}}$
 & 
I$_{\text{1}}$
 & 
i$_{\text{1}}$
 & 
j$_{\text{n}}$
 & 
-1
 & 
P$_{\text{emission down}}$ n
 & 
k$_{\text{n}}$
\\\hline

Z$_{\text{1}}$
 & 
I$_{\text{1}}$
 & 
i$_{\text{1}}$
 & 
j$_{\text{1}}$
 & 
0
 & 
P$_{\text{internal down}}$ 1
 & 
k$_{\text{1}}$
\\\hline

Z$_{\text{1}}$
 & 
I$_{\text{1}}$
 & 
i$_{\text{1}}$
 & 
j$_{\text{2}}$
 & 
0
 & 
P$_{\text{internal down}}$ 2
 & 
k$_{\text{2}}$
\\\hline

...
 & 
...
 & 
...
 & 
...
 & 
...
 & 
...
 & 
...
\\\hline

Z$_{\text{1}}$
 & 
I$_{\text{1}}$
 & 
i$_{\text{1}}$
 & 
j$_{\text{n}}$
 & 
0
 & 
P$_{\text{internal down}}$ n
 & 
k$_{\text{n}}$
\\\hline

Z$_{\text{1}}$
 & 
I$_{\text{1}}$
 & 
i$_{\text{1}}$
 & 
j$_{\text{1}}$
 & 
1
 & 
P$_{\text{internal up}}$   1
 & 
k$_{\text{1}}$
\\\hline

Z$_{\text{1}}$
 & 
I$_{\text{1}}$
 & 
i$_{\text{1}}$
 & 
j$_{\text{2}}$
 & 
1
 & 
P$_{\text{internal up}}$   2
 & 
k$_{\text{2}}$
\\\hline

...
 & 
...
 & 
...
 & 
...
 & 
...
 & 
...
 & 
...
\\\hline

Z$_{\text{1}}$
 & 
I$_{\text{1}}$
 & 
i$_{\text{1}}$
 & 
j$_{\text{n}}$
 & 
1
 & 
P$_{\text{internal up}}$   n
 & 
k$_{\text{n}}$
\\\hline
\end{tabulary}


The \code{macro\_references} dataset contains the numbers for each block:


\subsection{Macro Atom References}
\label{atomic:macro-atom-references}
\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\textbf{
Name
} & \textbf{
Description
} & \textbf{
Unit
}\\\hline

atomic\_number(z)
 & 
Atomic Number
 & 
1
\\\hline

ion\_number
 & 
Ion Number
 & 
1
\\\hline

source\_level\_number
 & 
Source Level Number
 & 
1
\\\hline

count\_down
 & 
Number of down transitions
 & 
1
\\\hline

count\_up
 & 
Number of up transitions
 & 
1
\\\hline

count\_total
 & 
Total number of transitions
 & 
1
\\\hline
\end{tabulary}



\section{The Atom Data Class}
\label{atomic:the-atom-data-class}
Atom Data is stored inside TARDIS in the \code{AtomData}-class. The class method \code{AtomData.from\_hdf5()} will
instantiate a new \emph{AtomData}-class from an HDF5 file. If none is given it will automatically
take the default HDF5-dataset shipped with TARDIS. A second function \code{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.


\section{Indexing fun}
\label{atomic: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 {\color{red}\bfseries{}:py:module:{}`pandas{}`}-framework provides the ideal functions to accomplish this. In TARDIS we extensively
use \code{pandas.MultiIndex}, \code{pandas.Series} and \code{pandas.DataFrame}

TO BE BETTER DOCUMENTED ...


\chapter{Plasma}
\label{plasma:plasma}\label{plasma:plasmas}\label{plasma::doc}
This module calculates the ionization balance and level populations in the BasePlasma, give a abundance fraction, temperature
and density. After calculating the state of the plasma, these classes are able to calculate $\tau_\textrm{sobolev}$
for the supernova radiative transfer. The simplest BasePlasma (\code{BasePlasma}) only calculates the atom number densities, but serves
as a base for all BasePlasma classes. The next more complex class is \emph{LTEPlasma} which will calculate the aforementioned quantities in
Local Thermal Equilibrium conditions (LTE). The \code{NebularPlasma}-class inherits from \emph{LTEPlasma} and uses a more complex
description of the BasePlasma (for details see \emph{nebular\_plasma}).

\begin{notice}{note}{Note:}
In this documentation we use the indices $i, j, k$ to mean atomic number, ion number and level number respectively.
\end{notice}

All plasma calculations follow the same basic procedure in calculating the plasma state.
This is always accomplished with the function \code{update\_radiationfield}. This block diagram shows the basic procedure


\section{Base Plasma}
\label{plasma:base-plasma}
\emph{BasePlasma} serves as the base class for all plasmas and can just calculate the atom number densities for a given input of
abundance fraction.
\begin{gather}
\begin{split}N_{atom} = \rho_\textrm{total} \times \textrm{Abundance fraction} / m_\textrm{atom}\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}
In the next step the line and level tables are purged of entries that are not represented in the
abundance fractions are saved in \emph{BasePlasma.levels} and \emph{BasePlasma.lines}. Finally, the function \emph{BasePlasma.update\_t\_rad} is called
at the end of initialization to update the plasma conditions to a new $T_\textrm{radiation field}$ (with the give t\_rad).
This function is the same in the other plasma classes and does the main part of the calculation. In the case of \emph{BasePlasma} this is only
setting \emph{BasePlasma.beta\_rad} to $\frac{1}{k_\textrm{B}T_\textrm{rad}}$.

Here's an example how to instantiate a simple base plasma:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{tardis} \PYG{k+kn}{import} \PYG{n}{atomic}\PYG{p}{,} \PYG{n}{plasma}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atom\PYGZus{}data} \PYG{o}{=} \PYG{n}{atomic}\PYG{o}{.}\PYG{n}{AtomData}\PYG{o}{.}\PYG{n}{from\PYGZus{}hdf5}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{my\PYGZus{}plasma} \PYG{o}{=} \PYG{n}{plasma}\PYG{o}{.}\PYG{n}{BasePlasma}\PYG{p}{(}\PYG{p}{\PYGZob{}}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Fe}\PYG{l+s}{\PYGZsq{}}\PYG{p}{:}\PYG{l+m+mf}{0.5}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Ni}\PYG{l+s}{\PYGZsq{}}\PYG{p}{:}\PYG{l+m+mf}{0.5}\PYG{p}{\PYGZcb{}}\PYG{p}{,} \PYG{l+m+mi}{10000}\PYG{p}{,} \PYG{l+m+mf}{1e\PYGZhy{}13}\PYG{p}{,} \PYG{n}{atom\PYGZus{}data}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{print} \PYG{n}{my\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{abundances}
\PYG{g+go}{atomic\PYGZus{}number abundance\PYGZus{}fraction number\PYGZus{}density}
\PYG{g+go}{\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{} \PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{} \PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}}
\PYG{g+go}{           28                0.5  513016973.936}
\PYG{g+go}{           26                0.5  539183641.472}
\end{Verbatim}


\section{Plasma Types}
\label{plasma:plasma-types}

\subsection{LTE Plasma}
\label{plasma_doc/lte_plasma:lte-plasma}\label{plasma_doc/lte_plasma::doc}
The \emph{LTEPlasma} plasma class is the child of \emph{BasePlasma} but is the first class that actually calculates plasma conditions.
After running exactley through the same steps as \emph{BasePlasma}, \emph{LTEPlasma} will start calculating the \href{http://en.wikipedia.org/wiki/Partition\_function\_(statistical\_mechanics)}{partition functions}.
\begin{gather}
\begin{split}Z_{i, j} = \sum_{k=0}^{max (k)} g_k \times e^{-E_k / (k_\textrm{b} T)}\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}
, where Z is the partition function, g is the degeneracy factor, E the energy of the level and T the temperature of the radiation field.

The next step is to calculate the ionization balance using the \href{http://en.wikipedia.org/wiki/Saha\_ionization\_equation}{Saha ionization equation}.
and then calculating the Number density of the ions (and an electron number density) in a second step.
First $g_e=\left(\frac{2 \pi m_e k_\textrm{B}T_\textrm{rad}}{h^2}\right)^{3/2}$ is calculated (in \emph{LTEPlasma.update\_t\_rad}),
followed by calculating the ion fractions (\emph{LTEPlasma.calculate\_saha}).
\begin{gather}
\begin{split}\frac{N_{i, j+1}\times N_e}{N_{i, j}} &= \Phi_{i, (j+1)/j} \\
\Phi_{i, (j+1)/j} &= g_e \times \frac{Z_{i, j+1}}{Z_{i, j}} e^{-\chi_{j\rightarrow j+1}/k_\textrm{B}T}\\\end{split}\notag
\end{gather}
In the second step (\emph{LTEPlasma.calculate\_ionization\_balance}), we calculate in an iterative process the electron density and the number density for each ion species.
\begin{gather}
\begin{split}N(X) &= N_1 + N_2 + N_3 + \dots\\
N(X) &= N_1 + \frac{N_2}{N_1} N_1 + \frac{N_3}{N_2}\frac{N_2}{N_1} N_1 + \frac{N_4}{N_3}\frac{N_3}{N_2}\frac{N_2}{N_1} N_1 + \dots\\
N(X) &= N_1 (1 + \frac{N_2}{N_1} + \frac{N_3}{N_2}\frac{N_2}{N_1} + \frac{N_4}{N_3}\frac{N_3}{N_2}\frac{N_2}{N_1} + \dots)\\
N(X) &= N_1 \underbrace{(1 + \frac{\Phi_{i, 2/1}}{N_e} + \frac{\Phi_{i, 2/2}}{N_e}\frac{\Phi_{i, 2/1}}{N_e} +
        \frac{\Phi_{i, 4/3}}{N_e}\frac{\Phi_{i, 3/2}}{N_e}\frac{\Phi_{i, 2/1}}{N_e} + \dots)}_{\alpha}\\
N_1 &= \frac{N(X)}{\alpha}\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}
Initially, we set the electron density ($N_e$) to the sum of all atom number densities. After having calculated the
ion species number densities we recalculated the electron density by weighting the ion species number densities with their
ion number (e.g. neutral ion number densities don't contribute at all to the electron number density, once ionized contribute with a
factor of 1, twice ionized contribute with a factor of two, ....).

Finally we calculate the level populations (\emph{LTEPlasma.calculate\_level\_populations}), by using the calculated ion species number densities:
\begin{gather}
\begin{split}N_{i, j, k} = \frac{g_k}{Z_{i, j}}\times N_{i, j} \times e^{-\beta_\textrm{rad} E_k}\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}
This concludes the calculation of the plasma. In the code, the next step is calculating the $\tau_\textrm{Sobolev}$ using
the quantities calculated here.


\subsubsection{Example Calculations}
\label{plasma_doc/lte_plasma:example-calculations}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{os}
\PYG{k+kn}{from} \PYG{n+nn}{matplotlib} \PYG{k+kn}{import} \PYG{n}{pyplot} \PYG{k}{as} \PYG{n}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{matplotlib} \PYG{k+kn}{import} \PYG{n}{colors}
\PYG{k+kn}{from} \PYG{n+nn}{tardis} \PYG{k+kn}{import} \PYG{n}{atomic}\PYG{p}{,} \PYG{n}{plasma}\PYG{p}{,} \PYG{n}{util}
\PYG{k+kn}{import} \PYG{n+nn}{numpy} \PYG{k+kn}{as} \PYG{n+nn}{np}
\PYG{k+kn}{import} \PYG{n+nn}{pandas} \PYG{k+kn}{as} \PYG{n+nn}{pd}

\PYG{c}{\PYGZsh{}Making 2 Figures for ionization balance and level populations}

\PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{)}\PYG{o}{.}\PYG{n}{clf}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{ax1} \PYG{o}{=} \PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{)}\PYG{o}{.}\PYG{n}{add\PYGZus{}subplot}\PYG{p}{(}\PYG{l+m+mi}{111}\PYG{p}{)}

\PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{l+m+mi}{2}\PYG{p}{)}\PYG{o}{.}\PYG{n}{clf}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{ax2} \PYG{o}{=} \PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{l+m+mi}{2}\PYG{p}{)}\PYG{o}{.}\PYG{n}{add\PYGZus{}subplot}\PYG{p}{(}\PYG{l+m+mi}{111}\PYG{p}{)}

\PYG{c}{\PYGZsh{} expanding the tilde to the users directory}
\PYG{n}{atom\PYGZus{}fname} \PYG{o}{=} \PYG{n}{os}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{expanduser}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{\PYGZti{}/.tardis/si\PYGZus{}kurucz.h5}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}

\PYG{c}{\PYGZsh{} reading in the HDF5 File}
\PYG{n}{atom\PYGZus{}data} \PYG{o}{=} \PYG{n}{atomic}\PYG{o}{.}\PYG{n}{AtomData}\PYG{o}{.}\PYG{n}{from\PYGZus{}hdf5}\PYG{p}{(}\PYG{n}{atom\PYGZus{}fname}\PYG{p}{)}

\PYG{c}{\PYGZsh{}The atom\PYGZus{}data needs to be prepared to create indices. The Class needs to know which atomic numbers are needed for the}
\PYG{c}{\PYGZsh{}calculation and what line interaction is needed (for \PYGZdq{}downbranch\PYGZdq{} and \PYGZdq{}macroatom\PYGZdq{} the code creates special tables)}
\PYG{n}{atom\PYGZus{}data}\PYG{o}{.}\PYG{n}{prepare\PYGZus{}atom\PYGZus{}data}\PYG{p}{(}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{]}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{scatter}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}

\PYG{c}{\PYGZsh{}Initializing the NebularPlasma class using the from\PYGZus{}abundance class method.}
\PYG{c}{\PYGZsh{}This classmethod is normally only needed to test individual plasma classes}
\PYG{c}{\PYGZsh{}Usually the plasma class just gets the number densities from the model class}
\PYG{n}{lte\PYGZus{}plasma} \PYG{o}{=} \PYG{n}{plasma}\PYG{o}{.}\PYG{n}{LTEPlasma}\PYG{o}{.}\PYG{n}{from\PYGZus{}abundance}\PYG{p}{(}\PYG{l+m+mi}{10000}\PYG{p}{,} \PYG{p}{\PYGZob{}}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Si}\PYG{l+s}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{1}\PYG{p}{\PYGZcb{}}\PYG{p}{,} \PYG{l+m+mf}{1e\PYGZhy{}13}\PYG{p}{,} \PYG{n}{atom\PYGZus{}data}\PYG{p}{,} \PYG{l+m+mf}{10.}\PYG{p}{)}


\PYG{c}{\PYGZsh{}Initializing a dataframe to store the ion populations  and level populations for the different temperatures}
\PYG{n}{ion\PYGZus{}number\PYGZus{}densities} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{n}{index}\PYG{o}{=}\PYG{n}{lte\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{ion\PYGZus{}populations}\PYG{o}{.}\PYG{n}{index}\PYG{p}{)}
\PYG{n}{level\PYGZus{}populations} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{n}{index}\PYG{o}{=}\PYG{n}{lte\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{level\PYGZus{}populations}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{index}\PYG{p}{)}
\PYG{n}{t\PYGZus{}rads} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{linspace}\PYG{p}{(}\PYG{l+m+mi}{2000}\PYG{p}{,} \PYG{l+m+mi}{20000}\PYG{p}{,} \PYG{l+m+mi}{100}\PYG{p}{)}

\PYG{c}{\PYGZsh{}Calculating the different ion populations and level populuatios for the given temperatures}
\PYG{k}{for} \PYG{n}{t\PYGZus{}rad} \PYG{o+ow}{in} \PYG{n}{t\PYGZus{}rads}\PYG{p}{:}
    \PYG{n}{lte\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{update\PYGZus{}radiationfield}\PYG{p}{(}\PYG{n}{t\PYGZus{}rad}\PYG{p}{,} \PYG{n}{w}\PYG{o}{=}\PYG{l+m+mf}{1.0}\PYG{p}{)}
    \PYG{c}{\PYGZsh{}getting total si number density}
    \PYG{n}{si\PYGZus{}number\PYGZus{}density} \PYG{o}{=} \PYG{n}{lte\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{number\PYGZus{}density}\PYG{o}{.}\PYG{n}{get\PYGZus{}value}\PYG{p}{(}\PYG{l+m+mi}{14}\PYG{p}{)}
    \PYG{c}{\PYGZsh{}Normalizing the ion populations}
    \PYG{n}{ion\PYGZus{}density} \PYG{o}{=} \PYG{n}{lte\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{ion\PYGZus{}populations} \PYG{o}{/} \PYG{n}{si\PYGZus{}number\PYGZus{}density}
    \PYG{n}{ion\PYGZus{}number\PYGZus{}densities}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]} \PYG{o}{=} \PYG{n}{ion\PYGZus{}density}

    \PYG{c}{\PYGZsh{}normalizing the level\PYGZus{}populations for Si II}
    \PYG{n}{current\PYGZus{}level\PYGZus{}population} \PYG{o}{=} \PYG{n}{lte\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{level\PYGZus{}populations}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]} \PYG{o}{/} \PYG{n}{lte\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{ion\PYGZus{}populations}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]}
    \PYG{c}{\PYGZsh{}normalizing with statistical weight}
    \PYG{n}{current\PYGZus{}level\PYGZus{}population} \PYG{o}{/}\PYG{o}{=} \PYG{n}{atom\PYGZus{}data}\PYG{o}{.}\PYG{n}{levels}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{g}

    \PYG{n}{level\PYGZus{}populations}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]} \PYG{o}{=} \PYG{n}{current\PYGZus{}level\PYGZus{}population}

\PYG{n}{ion\PYGZus{}colors} \PYG{o}{=} \PYG{p}{[}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{b}\PYG{l+s}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{g}\PYG{l+s}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{r}\PYG{l+s}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{k}\PYG{l+s}{\PYGZsq{}}\PYG{p}{]}

\PYG{k}{for} \PYG{n}{ion\PYGZus{}number} \PYG{o+ow}{in} \PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{:}
    \PYG{n}{current\PYGZus{}ion\PYGZus{}density} \PYG{o}{=} \PYG{n}{ion\PYGZus{}number\PYGZus{}densities}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{n}{ion\PYGZus{}number}\PYG{p}{]}
    \PYG{n}{ax1}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{n}{current\PYGZus{}ion\PYGZus{}density}\PYG{o}{.}\PYG{n}{index}\PYG{p}{,} \PYG{n}{current\PYGZus{}ion\PYGZus{}density}\PYG{o}{.}\PYG{n}{values}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s+si}{\PYGZpc{}s}\PYG{l+s}{\PYGZhy{}}\PYG{l+s}{\PYGZsq{}} \PYG{o}{\PYGZpc{}} \PYG{n}{ion\PYGZus{}colors}\PYG{p}{[}\PYG{n}{ion\PYGZus{}number}\PYG{p}{]}\PYG{p}{,}
             \PYG{n}{label}\PYG{o}{=}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Si }\PYG{l+s+si}{\PYGZpc{}s}\PYG{l+s}{ W=1.0}\PYG{l+s}{\PYGZsq{}} \PYG{o}{\PYGZpc{}} \PYG{n}{util}\PYG{o}{.}\PYG{n}{int\PYGZus{}to\PYGZus{}roman}\PYG{p}{(}\PYG{n}{ion\PYGZus{}number} \PYG{o}{+} \PYG{l+m+mi}{1}\PYG{p}{)}\PYG{o}{.}\PYG{n}{upper}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}


\PYG{c}{\PYGZsh{}only plotting every 5th radiation temperature}
\PYG{n}{t\PYGZus{}rad\PYGZus{}normalizer} \PYG{o}{=} \PYG{n}{colors}\PYG{o}{.}\PYG{n}{Normalize}\PYG{p}{(}\PYG{n}{vmin}\PYG{o}{=}\PYG{l+m+mi}{2000}\PYG{p}{,} \PYG{n}{vmax}\PYG{o}{=}\PYG{l+m+mi}{20000}\PYG{p}{)}
\PYG{n}{t\PYGZus{}rad\PYGZus{}color\PYGZus{}map} \PYG{o}{=} \PYG{n}{plt}\PYG{o}{.}\PYG{n}{cm}\PYG{o}{.}\PYG{n}{ScalarMappable}\PYG{p}{(}\PYG{n}{norm}\PYG{o}{=}\PYG{n}{t\PYGZus{}rad\PYGZus{}normalizer}\PYG{p}{,} \PYG{n}{cmap}\PYG{o}{=}\PYG{n}{plt}\PYG{o}{.}\PYG{n}{cm}\PYG{o}{.}\PYG{n}{jet}\PYG{p}{)}

\PYG{k}{for} \PYG{n}{t\PYGZus{}rad} \PYG{o+ow}{in} \PYG{n}{t\PYGZus{}rads}\PYG{p}{[}\PYG{p}{:}\PYG{p}{:}\PYG{l+m+mi}{5}\PYG{p}{]}\PYG{p}{:}
    \PYG{n}{ax2}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{n}{level\PYGZus{}populations}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]}\PYG{o}{.}\PYG{n}{index}\PYG{p}{,} \PYG{n}{level\PYGZus{}populations}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]}\PYG{o}{.}\PYG{n}{values}\PYG{p}{,} \PYG{n}{color}\PYG{o}{=}\PYG{n}{t\PYGZus{}rad\PYGZus{}color\PYGZus{}map}\PYG{o}{.}\PYG{n}{to\PYGZus{}rgba}\PYG{p}{(}\PYG{n}{t\PYGZus{}rad}\PYG{p}{)}\PYG{p}{)}
    \PYG{n}{ax2}\PYG{o}{.}\PYG{n}{semilogy}\PYG{p}{(}\PYG{p}{)}

\PYG{n}{t\PYGZus{}rad\PYGZus{}color\PYGZus{}map}\PYG{o}{.}\PYG{n}{set\PYGZus{}array}\PYG{p}{(}\PYG{n}{t\PYGZus{}rads}\PYG{p}{)}
\PYG{n}{cb} \PYG{o}{=} \PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{l+m+mi}{2}\PYG{p}{)}\PYG{o}{.}\PYG{n}{colorbar}\PYG{p}{(}\PYG{n}{t\PYGZus{}rad\PYGZus{}color\PYGZus{}map}\PYG{p}{)}

\PYG{n}{ax1}\PYG{o}{.}\PYG{n}{set\PYGZus{}xlabel}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{T [K]}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{ax1}\PYG{o}{.}\PYG{n}{set\PYGZus{}ylabel}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Number Density Fraction}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{ax1}\PYG{o}{.}\PYG{n}{legend}\PYG{p}{(}\PYG{p}{)}

\PYG{n}{ax2}\PYG{o}{.}\PYG{n}{set\PYGZus{}xlabel}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Level Number for Si II}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{ax2}\PYG{o}{.}\PYG{n}{set\PYGZus{}ylabel}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Number Density Fraction}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{cb}\PYG{o}{.}\PYG{n}{set\PYGZus{}label}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{T [K]}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}

\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{Verbatim}


\subsection{Nebular Plasma}
\label{plasma_doc/nebular_plasma::doc}\label{plasma_doc/nebular_plasma:nebular-plasma}
The \emph{NebularPlasma} class is a more complex description of the Plasma state than the \emph{LTEPlasma}. It takes a dilution factor
(W) into account, which deals with the dilution of the radiation field due to geometric, line-blocking and other effects.

The calculations follow the same steps as \emph{LTEPlasma}, however the calculations are different and often take into account
if a particular level is {\hyperref[glossary:term-meta-stable]{\emph{meta-stable}}} or not.
\emph{NebularPlasma} will start calculating the \href{http://en.wikipedia.org/wiki/Partition\_function\_(statistical\_mechanics)}{partition functions}.
\begin{gather}
\begin{split}Z_{i,j} = \underbrace{\sum_{k=0}^{max(k)_{i,j}} g_k \times e^{-E_k / (k_\textrm{b} T)}}_\textrm{metastable levels} +
        \underbrace{W\times\sum_{k=0}^{max(k)_{i,j}} g_k \times e^{-E_k / (k_\textrm{b} T)}}_\textrm{non-metastable levels}\end{split}\notag
\end{gather}
, where Z is the partition function, g is the degeneracy factor, E the energy of the level, T the temperature of the radiation field
and W the dilution factor.

The next step is to calculate the ionization balance using the \href{http://en.wikipedia.org/wiki/Saha\_ionization\_equation}{Saha ionization equation}.
and then calculating the Number density of the ions (and an electron number density) in a second step.
In the first step, we calculate the ionization balance using the LTE approximation ($\Phi_{i, j}(\textrm{LTE})$). Then we adjust the ionization balance using
two factors $\zeta$ and $\delta$.


\subsubsection{Calculating Zeta}
\label{plasma_doc/nebular_plasma:calc-zeta-label}\label{plasma_doc/nebular_plasma:calculating-zeta}
$\zeta$ is read in for specific temperatures and then interpolated for the target temperature.


\subsubsection{Calculating Delta}
\label{plasma_doc/nebular_plasma:calculating-delta}
$\delta$ is a radiation field correction factors which is calculated according to Mazzali \& Lucy 1993 ({\hyperref[zreferences:a-a-279-447m]{{[}3{]}}}; henceforth ML93)

In ML93 the radiation field correction factor is denoted as $\delta$ and is calculated in Formula 15 \& 20

The radiation correction factor changes according to a ionization energy threshold $\chi_\textrm{T}$
and the species ionization threshold (from the ground state) $\chi_0$.

\textbf{For} $\chi_\textrm{T} \ge \chi_0$
\begin{gather}
\begin{split}\delta = \frac{T_\textrm{e}}{b_1 W T_\textrm{R}} \exp(\frac{\chi_\textrm{T}}{k T_\textrm{R}} -
\frac{\chi_0}{k T_\textrm{e}})\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}
\textbf{For} $\chi_\textrm{T} < \chi_0$
\begin{gather}
\begin{split}\delta = 1 - \exp(\frac{\chi_\textrm{T}}{k T_\textrm{R}} - \frac{\chi_0}{k T_\textrm{R}}) +
\frac{T_\textrm{e}}{b_1 W T_\textrm{R}} \exp(\frac{\chi_\textrm{T}}{k T_\textrm{R}} -
\frac{\chi_0}{k T_\textrm{e}}),\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}
where $T_\textrm{R}$ is the radiation field Temperature, $T_\textrm{e}$ is the electron temperature and W is the
dilution factor.

Now we can calculate the ionization balance using equation 14 in {\hyperref[zreferences:a-a-279-447m]{{[}3{]}}}:
\begin{gather}
\begin{split}\Phi_{i,j} &= \frac{N_{i, j+1} n_e}{N_{i, j}} \\\end{split}\notag\\\begin{split}\Phi_{i, j} &= W \times[\delta \zeta + W ( 1 - \zeta)] \left(\frac{T_\textrm{e}}{T_\textrm{R}}\right)^{1/2}
\Phi_{i, j}(\textrm{LTE}) \\\end{split}\notag
\end{gather}
In the last step, we calculate the ion number densities according using the methods in \code{LTEPlasma}

Finally we calculate the level populations (\code{NebularPlasma.calculate\_level\_populations()}),
by using the calculated ion species number densities:
\begin{gather}
\begin{split}N_{i, j, k}(\textrm{not metastable}) &= W\frac{g_k}{Z_{i, j}}\times N_{i, j} \times e^{-\beta_\textrm{rad} E_k} \\
N_{i, j, k}(\textrm{metastable}) &= \frac{g_k}{Z_{i, j}}\times N_{i, j} \times e^{-\beta_\textrm{rad} E_k} \\\end{split}\notag
\end{gather}
This concludes the calculation of the nebular plasma. In the code, the next step is calculating the $\tau_\textrm{Sobolev}$ using
the quantities calculated here.


\subsubsection{Example Calculations}
\label{plasma_doc/nebular_plasma:example-calculations}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{os}

\PYG{k+kn}{from} \PYG{n+nn}{matplotlib} \PYG{k+kn}{import} \PYG{n}{colors}
\PYG{k+kn}{from} \PYG{n+nn}{tardis} \PYG{k+kn}{import} \PYG{n}{atomic}\PYG{p}{,} \PYG{n}{plasma}\PYG{p}{,} \PYG{n}{util}
\PYG{k+kn}{from} \PYG{n+nn}{matplotlib} \PYG{k+kn}{import} \PYG{n}{pyplot} \PYG{k}{as} \PYG{n}{plt}

\PYG{k+kn}{import} \PYG{n+nn}{numpy} \PYG{k+kn}{as} \PYG{n+nn}{np}
\PYG{k+kn}{import} \PYG{n+nn}{pandas} \PYG{k+kn}{as} \PYG{n+nn}{pd}

\PYG{c}{\PYGZsh{}Making 2 Figures for ionization balance and level populations}

\PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{)}\PYG{o}{.}\PYG{n}{clf}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{ax1} \PYG{o}{=} \PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{)}\PYG{o}{.}\PYG{n}{add\PYGZus{}subplot}\PYG{p}{(}\PYG{l+m+mi}{111}\PYG{p}{)}

\PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{l+m+mi}{2}\PYG{p}{)}\PYG{o}{.}\PYG{n}{clf}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{ax2} \PYG{o}{=} \PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{l+m+mi}{2}\PYG{p}{)}\PYG{o}{.}\PYG{n}{add\PYGZus{}subplot}\PYG{p}{(}\PYG{l+m+mi}{111}\PYG{p}{)}

\PYG{c}{\PYGZsh{} expanding the tilde to the users directory}
\PYG{n}{atom\PYGZus{}fname} \PYG{o}{=} \PYG{n}{os}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{expanduser}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{\PYGZti{}/.tardis/si\PYGZus{}kurucz.h5}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}

\PYG{c}{\PYGZsh{} reading in the HDF5 File}
\PYG{n}{atom\PYGZus{}data} \PYG{o}{=} \PYG{n}{atomic}\PYG{o}{.}\PYG{n}{AtomData}\PYG{o}{.}\PYG{n}{from\PYGZus{}hdf5}\PYG{p}{(}\PYG{n}{atom\PYGZus{}fname}\PYG{p}{)}

\PYG{c}{\PYGZsh{}The atom\PYGZus{}data needs to be prepared to create indices. The Class needs to know which atomic numbers are needed for the}
\PYG{c}{\PYGZsh{}calculation and what line interaction is needed (for \PYGZdq{}downbranch\PYGZdq{} and \PYGZdq{}macroatom\PYGZdq{} the code creates special tables)}
\PYG{n}{atom\PYGZus{}data}\PYG{o}{.}\PYG{n}{prepare\PYGZus{}atom\PYGZus{}data}\PYG{p}{(}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{]}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{scatter}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}

\PYG{c}{\PYGZsh{}Initializing the NebularPlasma class using the from\PYGZus{}abundance class method.}
\PYG{c}{\PYGZsh{}This classmethod is normally only needed to test individual plasma classes}
\PYG{c}{\PYGZsh{}Usually the plasma class just gets the number densities from the model class}
\PYG{n}{nebular\PYGZus{}plasma} \PYG{o}{=} \PYG{n}{plasma}\PYG{o}{.}\PYG{n}{NebularPlasma}\PYG{o}{.}\PYG{n}{from\PYGZus{}abundance}\PYG{p}{(}\PYG{l+m+mi}{10000}\PYG{p}{,} \PYG{l+m+mf}{0.5}\PYG{p}{,} \PYG{p}{\PYGZob{}}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Si}\PYG{l+s}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{1}\PYG{p}{\PYGZcb{}}\PYG{p}{,} \PYG{l+m+mf}{1e\PYGZhy{}13}\PYG{p}{,} \PYG{n}{atom\PYGZus{}data}\PYG{p}{,} \PYG{l+m+mf}{10.}\PYG{p}{)}


\PYG{c}{\PYGZsh{}Initializing a dataframe to store the ion populations  and level populations for the different temperatures}
\PYG{n}{ion\PYGZus{}number\PYGZus{}densities} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{n}{index}\PYG{o}{=}\PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{ion\PYGZus{}populations}\PYG{o}{.}\PYG{n}{index}\PYG{p}{)}
\PYG{n}{level\PYGZus{}populations} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{n}{index}\PYG{o}{=}\PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{level\PYGZus{}populations}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{index}\PYG{p}{)}
\PYG{n}{t\PYGZus{}rads} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{linspace}\PYG{p}{(}\PYG{l+m+mi}{2000}\PYG{p}{,} \PYG{l+m+mi}{20000}\PYG{p}{,} \PYG{l+m+mi}{100}\PYG{p}{)}

\PYG{c}{\PYGZsh{}Calculating the different ion populations and level populuatios for the given temperatures}
\PYG{k}{for} \PYG{n}{t\PYGZus{}rad} \PYG{o+ow}{in} \PYG{n}{t\PYGZus{}rads}\PYG{p}{:}
    \PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{update\PYGZus{}radiationfield}\PYG{p}{(}\PYG{n}{t\PYGZus{}rad}\PYG{p}{,} \PYG{n}{w}\PYG{o}{=}\PYG{l+m+mf}{1.0}\PYG{p}{)}
    \PYG{c}{\PYGZsh{}getting total si number density}
    \PYG{n}{si\PYGZus{}number\PYGZus{}density} \PYG{o}{=} \PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{number\PYGZus{}density}\PYG{o}{.}\PYG{n}{get\PYGZus{}value}\PYG{p}{(}\PYG{l+m+mi}{14}\PYG{p}{)}
    \PYG{c}{\PYGZsh{}Normalizing the ion populations}
    \PYG{n}{ion\PYGZus{}density} \PYG{o}{=} \PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{ion\PYGZus{}populations} \PYG{o}{/} \PYG{n}{si\PYGZus{}number\PYGZus{}density}
    \PYG{n}{ion\PYGZus{}number\PYGZus{}densities}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]} \PYG{o}{=} \PYG{n}{ion\PYGZus{}density}

    \PYG{c}{\PYGZsh{}normalizing the level\PYGZus{}populations for Si II}
    \PYG{n}{current\PYGZus{}level\PYGZus{}population} \PYG{o}{=} \PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{level\PYGZus{}populations}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]} \PYG{o}{/} \PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{ion\PYGZus{}populations}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]}
    \PYG{c}{\PYGZsh{}normalizing with statistical weight}
    \PYG{n}{current\PYGZus{}level\PYGZus{}population} \PYG{o}{/}\PYG{o}{=} \PYG{n}{atom\PYGZus{}data}\PYG{o}{.}\PYG{n}{levels}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{g}

    \PYG{n}{level\PYGZus{}populations}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]} \PYG{o}{=} \PYG{n}{current\PYGZus{}level\PYGZus{}population}

\PYG{n}{ion\PYGZus{}colors} \PYG{o}{=} \PYG{p}{[}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{b}\PYG{l+s}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{g}\PYG{l+s}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{r}\PYG{l+s}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{k}\PYG{l+s}{\PYGZsq{}}\PYG{p}{]}

\PYG{k}{for} \PYG{n}{ion\PYGZus{}number} \PYG{o+ow}{in} \PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{:}
    \PYG{n}{current\PYGZus{}ion\PYGZus{}density} \PYG{o}{=} \PYG{n}{ion\PYGZus{}number\PYGZus{}densities}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{n}{ion\PYGZus{}number}\PYG{p}{]}
    \PYG{n}{ax1}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{n}{current\PYGZus{}ion\PYGZus{}density}\PYG{o}{.}\PYG{n}{index}\PYG{p}{,} \PYG{n}{current\PYGZus{}ion\PYGZus{}density}\PYG{o}{.}\PYG{n}{values}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s+si}{\PYGZpc{}s}\PYG{l+s}{\PYGZhy{}}\PYG{l+s}{\PYGZsq{}} \PYG{o}{\PYGZpc{}} \PYG{n}{ion\PYGZus{}colors}\PYG{p}{[}\PYG{n}{ion\PYGZus{}number}\PYG{p}{]}\PYG{p}{,}
             \PYG{n}{label}\PYG{o}{=}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Si }\PYG{l+s+si}{\PYGZpc{}s}\PYG{l+s}{ W=1.0}\PYG{l+s}{\PYGZsq{}} \PYG{o}{\PYGZpc{}} \PYG{n}{util}\PYG{o}{.}\PYG{n}{int\PYGZus{}to\PYGZus{}roman}\PYG{p}{(}\PYG{n}{ion\PYGZus{}number} \PYG{o}{+} \PYG{l+m+mi}{1}\PYG{p}{)}\PYG{o}{.}\PYG{n}{upper}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}


\PYG{c}{\PYGZsh{}only plotting every 5th radiation temperature}
\PYG{n}{t\PYGZus{}rad\PYGZus{}normalizer} \PYG{o}{=} \PYG{n}{colors}\PYG{o}{.}\PYG{n}{Normalize}\PYG{p}{(}\PYG{n}{vmin}\PYG{o}{=}\PYG{l+m+mi}{2000}\PYG{p}{,} \PYG{n}{vmax}\PYG{o}{=}\PYG{l+m+mi}{20000}\PYG{p}{)}
\PYG{n}{t\PYGZus{}rad\PYGZus{}color\PYGZus{}map} \PYG{o}{=} \PYG{n}{plt}\PYG{o}{.}\PYG{n}{cm}\PYG{o}{.}\PYG{n}{ScalarMappable}\PYG{p}{(}\PYG{n}{norm}\PYG{o}{=}\PYG{n}{t\PYGZus{}rad\PYGZus{}normalizer}\PYG{p}{,} \PYG{n}{cmap}\PYG{o}{=}\PYG{n}{plt}\PYG{o}{.}\PYG{n}{cm}\PYG{o}{.}\PYG{n}{jet}\PYG{p}{)}

\PYG{k}{for} \PYG{n}{t\PYGZus{}rad} \PYG{o+ow}{in} \PYG{n}{t\PYGZus{}rads}\PYG{p}{[}\PYG{p}{:}\PYG{p}{:}\PYG{l+m+mi}{5}\PYG{p}{]}\PYG{p}{:}
    \PYG{n}{ax2}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{n}{level\PYGZus{}populations}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]}\PYG{o}{.}\PYG{n}{index}\PYG{p}{,} \PYG{n}{level\PYGZus{}populations}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]}\PYG{o}{.}\PYG{n}{values}\PYG{p}{,} \PYG{n}{color}\PYG{o}{=}\PYG{n}{t\PYGZus{}rad\PYGZus{}color\PYGZus{}map}\PYG{o}{.}\PYG{n}{to\PYGZus{}rgba}\PYG{p}{(}\PYG{n}{t\PYGZus{}rad}\PYG{p}{)}\PYG{p}{)}
    \PYG{n}{ax2}\PYG{o}{.}\PYG{n}{semilogy}\PYG{p}{(}\PYG{p}{)}

\PYG{c}{\PYGZsh{}Calculating the different ion populations for the given temperatures with W=0.5}
\PYG{n}{ion\PYGZus{}number\PYGZus{}densities} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{n}{index}\PYG{o}{=}\PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{ion\PYGZus{}populations}\PYG{o}{.}\PYG{n}{index}\PYG{p}{)}
\PYG{k}{for} \PYG{n}{t\PYGZus{}rad} \PYG{o+ow}{in} \PYG{n}{t\PYGZus{}rads}\PYG{p}{:}
    \PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{update\PYGZus{}radiationfield}\PYG{p}{(}\PYG{n}{t\PYGZus{}rad}\PYG{p}{,} \PYG{n}{w}\PYG{o}{=}\PYG{l+m+mf}{0.5}\PYG{p}{)}
    \PYG{c}{\PYGZsh{}getting total si number density}
    \PYG{n}{si\PYGZus{}number\PYGZus{}density} \PYG{o}{=} \PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{number\PYGZus{}density}\PYG{o}{.}\PYG{n}{get\PYGZus{}value}\PYG{p}{(}\PYG{l+m+mi}{14}\PYG{p}{)}
    \PYG{c}{\PYGZsh{}Normalizing the ion populations}
    \PYG{n}{ion\PYGZus{}density} \PYG{o}{=} \PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{ion\PYGZus{}populations} \PYG{o}{/} \PYG{n}{si\PYGZus{}number\PYGZus{}density}
    \PYG{n}{ion\PYGZus{}number\PYGZus{}densities}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]} \PYG{o}{=} \PYG{n}{ion\PYGZus{}density}

    \PYG{c}{\PYGZsh{}normalizing the level\PYGZus{}populations for Si II}
    \PYG{n}{current\PYGZus{}level\PYGZus{}population} \PYG{o}{=} \PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{level\PYGZus{}populations}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]} \PYG{o}{/} \PYG{n}{nebular\PYGZus{}plasma}\PYG{o}{.}\PYG{n}{ion\PYGZus{}populations}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]}
    \PYG{c}{\PYGZsh{}normalizing with statistical weight}
    \PYG{n}{current\PYGZus{}level\PYGZus{}population} \PYG{o}{/}\PYG{o}{=} \PYG{n}{atom\PYGZus{}data}\PYG{o}{.}\PYG{n}{levels}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{g}

    \PYG{n}{level\PYGZus{}populations}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]} \PYG{o}{=} \PYG{n}{current\PYGZus{}level\PYGZus{}population}

\PYG{c}{\PYGZsh{}Plotting the ion fractions}

\PYG{k}{for} \PYG{n}{ion\PYGZus{}number} \PYG{o+ow}{in} \PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{:}
    \PYG{k}{print} \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{w=0.5}\PYG{l+s}{\PYGZdq{}}
    \PYG{n}{current\PYGZus{}ion\PYGZus{}density} \PYG{o}{=} \PYG{n}{ion\PYGZus{}number\PYGZus{}densities}\PYG{o}{.}\PYG{n}{ix}\PYG{p}{[}\PYG{l+m+mi}{14}\PYG{p}{,} \PYG{n}{ion\PYGZus{}number}\PYG{p}{]}
    \PYG{n}{ax1}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{n}{current\PYGZus{}ion\PYGZus{}density}\PYG{o}{.}\PYG{n}{index}\PYG{p}{,} \PYG{n}{current\PYGZus{}ion\PYGZus{}density}\PYG{o}{.}\PYG{n}{values}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s+si}{\PYGZpc{}s}\PYG{l+s}{\PYGZhy{}\PYGZhy{}}\PYG{l+s}{\PYGZsq{}} \PYG{o}{\PYGZpc{}} \PYG{n}{ion\PYGZus{}colors}\PYG{p}{[}\PYG{n}{ion\PYGZus{}number}\PYG{p}{]}\PYG{p}{,}
             \PYG{n}{label}\PYG{o}{=}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Si }\PYG{l+s+si}{\PYGZpc{}s}\PYG{l+s}{ W=0.5}\PYG{l+s}{\PYGZsq{}} \PYG{o}{\PYGZpc{}} \PYG{n}{util}\PYG{o}{.}\PYG{n}{int\PYGZus{}to\PYGZus{}roman}\PYG{p}{(}\PYG{n}{ion\PYGZus{}number} \PYG{o}{+} \PYG{l+m+mi}{1}\PYG{p}{)}\PYG{o}{.}\PYG{n}{upper}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}

\PYG{k}{for} \PYG{n}{t\PYGZus{}rad} \PYG{o+ow}{in} \PYG{n}{t\PYGZus{}rads}\PYG{p}{[}\PYG{p}{:}\PYG{p}{:}\PYG{l+m+mi}{5}\PYG{p}{]}\PYG{p}{:}
    \PYG{n}{ax2}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{n}{level\PYGZus{}populations}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]}\PYG{o}{.}\PYG{n}{index}\PYG{p}{,} \PYG{n}{level\PYGZus{}populations}\PYG{p}{[}\PYG{n}{t\PYGZus{}rad}\PYG{p}{]}\PYG{o}{.}\PYG{n}{values}\PYG{p}{,} \PYG{n}{color}\PYG{o}{=}\PYG{n}{t\PYGZus{}rad\PYGZus{}color\PYGZus{}map}\PYG{o}{.}\PYG{n}{to\PYGZus{}rgba}\PYG{p}{(}\PYG{n}{t\PYGZus{}rad}\PYG{p}{)}\PYG{p}{,}
             \PYG{n}{linestyle}\PYG{o}{=}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{\PYGZhy{}\PYGZhy{}}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
    \PYG{n}{ax2}\PYG{o}{.}\PYG{n}{semilogy}\PYG{p}{(}\PYG{p}{)}

\PYG{n}{t\PYGZus{}rad\PYGZus{}color\PYGZus{}map}\PYG{o}{.}\PYG{n}{set\PYGZus{}array}\PYG{p}{(}\PYG{n}{t\PYGZus{}rads}\PYG{p}{)}
\PYG{n}{cb} \PYG{o}{=} \PYG{n}{plt}\PYG{o}{.}\PYG{n}{figure}\PYG{p}{(}\PYG{l+m+mi}{2}\PYG{p}{)}\PYG{o}{.}\PYG{n}{colorbar}\PYG{p}{(}\PYG{n}{t\PYGZus{}rad\PYGZus{}color\PYGZus{}map}\PYG{p}{)}

\PYG{n}{ax1}\PYG{o}{.}\PYG{n}{set\PYGZus{}xlabel}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{T [K]}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{ax1}\PYG{o}{.}\PYG{n}{set\PYGZus{}ylabel}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Number Density Fraction}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{ax1}\PYG{o}{.}\PYG{n}{legend}\PYG{p}{(}\PYG{p}{)}

\PYG{n}{ax2}\PYG{o}{.}\PYG{n}{set\PYGZus{}xlabel}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Level Number for Si II}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{ax2}\PYG{o}{.}\PYG{n}{set\PYGZus{}ylabel}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Number Density Fraction}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{cb}\PYG{o}{.}\PYG{n}{set\PYGZus{}label}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{T [K]}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}

\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{Verbatim}


\section{Sobolev optical depth}
\label{plasma:tau-sobolev}\label{plasma:sobolev-optical-depth}
This function calculates the Sobolev optical depth $\tau_\textrm{Sobolev}$
\begin{gather}
\begin{split}C_\textrm{Sobolev} = \frac{\pi e^2}{m_e c}\end{split}\notag\\\begin{split}\tau_\textrm{Sobolev} = C_\textrm{Sobolev}\,  \lambda\, f_{\textrm{lower}\rightarrow\textrm{upper}}\,
    t_\textrm{explosion}\, N_\textrm{lower}
    (1 - \frac{g_\textrm{lower}}{g_\textrm{upper}}\frac{N_\textrm{upper}}{N_\textrm{lower}})\end{split}\notag
\end{gather}

\section{Macro Atom}
\label{plasma:macro-atom}
The macro atom is described in detail in {\hyperref[zreferences:a-a-384-725l]{{[}1{]}}}. The basic principal is that when an energy packet
is absorbed that the macro atom is on a certain level. Three probabilities govern the next step the P$_{\text{up}}$,
P$_{\text{down}}$ and P$_{\text{down emission}}$ being the probability for going to a higher level, a lower level and a lower
level and emitting a photon while doing this respectively (see Figure 1 in {\hyperref[zreferences:a-a-384-725l]{{[}1{]}}} ).

The macro atom is the most complex idea to implement as a data structure. The setup is done in \emph{\textasciitilde{}tardisatomic}, but
we will nonetheless discuss it here (as \emph{\textasciitilde{}tardisatomic} is even less documented than this one).

For each level we look at the line list to see what transitions (upwards or downwards are possible). We create a two arrays,
the first is a long one-dimensional array containing the probabilities. Each level contains a set of probabilities, The first
part of each set contains the upwards probabilities (internal upward), the second part the downwards probabilities
(internal downward), and the last part is the downward and emission probability.

each set is stacked after the other one to make one long one dimensional \emph{\textasciitilde{}numpy.ndarray}.

The second array is for book-keeping it has exactly the length as levels (with an example for the Si II level 15):

\begin{tabulary}{\linewidth}{|L|L|L|L|L|}
\hline
\textbf{
Level ID
} & \textbf{
Probability index
} & \textbf{
N$_{\text{up}}$
} & \textbf{
N$_{\text{down}}$
} & \textbf{
N$_{\text{total}}$
}\\\hline

14001015
 & 
???
 & 
17
 & 
5
 & 
17 + 5*2 = 27
\\\hline
\end{tabulary}


We now will calculate the transition probabilites, using the radiative rates in Equation 20, 21, and 22
in {\hyperref[zreferences:a-a-384-725l]{{[}1{]}}}. Then we calculate the downward emission probability from Equation 5, the downward and
upward internal transition probabilities in {\hyperref[zreferences:a-a-403-261l]{{[}2{]}}}.
\begin{gather}
\begin{split}p_\textrm{emission down}&= {\cal R}_{\textrm{i}\rightarrow\textrm{lower}}\,(\epsilon_\textrm{upper} - \epsilon_\textrm{lower}) / {\cal D}_{i}\\
p_\textrm{internal down}&= {\cal R}_{\textrm{i}\rightarrow\textrm{lower}}\,\epsilon_\textrm{lower}/{\cal D}_{i}\\,
p_\textrm{internal up}&={\cal R}_{\textrm{i}\rightarrow\textrm{upper}}\,\epsilon_{i}/{\cal D}_{i}\\,\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}\begin{description}
\item[{where $i$ is the current level, $\epsilon$ is the energy of the level, and ${\cal R}$ is the radiative}] \leavevmode
rates.

\end{description}

We ignore the probability to emit a k-packet as TARDIS only works with photon packets.
Next we calculate the radidative
rates using equation 10 in {\hyperref[zreferences:a-a-403-261l]{{[}2{]}}}.
\begin{gather}
\begin{split}{\cal R}_{\textrm{upper}\rightarrow\textrm{lower}} &=
A_{\textrm{upper}\rightarrow\textrm{lower}}\beta_\textrm{Sobolev}n_\textrm{upper}\\
{\cal R}_{\textrm{lower}\rightarrow\textrm{upper}} &=
(B_{\textrm{lower}\rightarrow\textrm{upper}}n_\textrm{lower}-
B_{\textrm{upper}\rightarrow\textrm{lower}}n_\textrm{upper})
\beta_\textrm{Sobolev} J_{\nu}^{b}\\,\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}
with $\beta_\textrm{Sobolev} = \frac{1}{\tau_\textrm{Sobolev}}(1-e^{-\tau_\textrm{Sobolev}})$ .

using the Einstein coefficients
\begin{gather}
\begin{split}A_{\textrm{upper}\rightarrow\textrm{lower}} &= \frac{8 \nu^2 \pi^2 e^2}{m_e c^3}~
    \frac{g_\textrm{lower}}{g_\textrm{upper}}~f_{\textrm{lower}\rightarrow\textrm{upper}}\\
A_{\textrm{upper}\rightarrow\textrm{lower}} &= \underbrace{\frac{4 \pi^2 e^2}{m_e c}}_{C_\textrm{Einstein}}~ \frac{2\nu^2}{c^2}
        \frac{g_\textrm{lower}}{g_\textrm{upper}}~f_{\textrm{lower}\rightarrow\textrm{upper}}\\
B_{\textrm{lower}\rightarrow\textrm{upper}} &= \frac{4\pi^2 e^2}{m_e h\nu c}\,f_{\textrm{lower}\rightarrow\textrm{upper}}\\
B_{\textrm{lower}\rightarrow\textrm{upper}} &= \underbrace{\frac{4 \pi^2 e^2}{m_e c}}_{C_\textrm{Einstein}}\frac{1}{h\nu} f_{\textrm{lower}\rightarrow\textrm{upper}}\\\end{split}\notag\\\begin{split}B_{\textrm{upper}\rightarrow\textrm{lower}} &= \frac{4\pi^2 e^2}{m_e h\nu c}\,f_{\textrm{lower}\rightarrow\textrm{upper}}\\
B_{\textrm{upper}\rightarrow\textrm{lower}} &= \underbrace{\frac{4 \pi^2 e^2}{m_e c}}_{C_\textrm{Einstein}}\frac{1}{h\nu}\frac{g_\textrm{lower}}{g_\textrm{upper}}f_{\textrm{lower}\rightarrow\textrm{upper}}\\\end{split}\notag
\end{gather}
we get
\begin{gather}
\begin{split}{\cal R}_{\textrm{upper}\rightarrow\textrm{lower}} &=
    C_\textrm{Einstein} \frac{2\nu^2}{c^2} \frac{g_\textrm{lower}}{g_\textrm{upper}}~f_{\textrm{lower}\rightarrow\textrm{upper}}
    \beta_\textrm{Sobolev}n_\textrm{upper}\\\end{split}\notag\\\begin{split}{\cal R}_{\textrm{lower}\rightarrow\textrm{upper}} &=
        C_\textrm{Einstein}\frac{1}{h\nu} f_{\textrm{lower}\rightarrow\textrm{upper}}
        (n_\textrm{lower}-\frac{g_\textrm{lower}}{g_\textrm{upper}}n_\textrm{upper})
                    \beta_\textrm{Sobolev} J_{\nu}^{b}\\\end{split}\notag
\end{gather}
This results in the transition probabilities:
\begin{gather}
\begin{split}p_\textrm{emission down}&= C_\textrm{Einstein} \frac{2\nu^2}{c^2} \frac{g_\textrm{lower}}{g_\textrm{i}}~f_{\textrm{lower}\rightarrow\textrm{i}}
                                   \beta_\textrm{Sobolev}n_\textrm{i}\,(\epsilon_\textrm{i} - \epsilon_\textrm{lower}) / {\cal D}_{i}\\
p_\textrm{internal down}&= C_\textrm{Einstein} \frac{2\nu^2}{c^2} \frac{g_\textrm{lower}}{g_\textrm{i}}~f_{\textrm{lower}\rightarrow\textrm{i}}
                                   \beta_\textrm{Sobolev}n_\textrm{i}\,\epsilon_\textrm{lower}/{\cal D}_{i}\\
p_\textrm{internal up}&=C_\textrm{Einstein}\frac{1}{h\nu} f_{\textrm{i}\rightarrow\textrm{upper}}
                                    (n_\textrm{i}-\frac{g_\textrm{i}}{g_\textrm{upper}}n_\textrm{upper})
                                                \beta_\textrm{Sobolev} J_{\nu}^{b}\,\epsilon_{i}/{\cal D}_{i}\\,\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}\begin{description}
\item[{and as we will normalise the transition probabilities numerically later,  we can get rid of $C_\textrm{Einstein}$,}] \leavevmode
$\frac{1}{{\cal D}_i}$ and number densities.

\end{description}
\begin{gather}
\begin{split}p_\textrm{emission down}&= \frac{2\nu^2}{c^2} \frac{g_\textrm{lower}}{g_\textrm{i}}~f_{\textrm{lower}\rightarrow\textrm{i}}
                                   \beta_\textrm{Sobolev}\,(\epsilon_\textrm{i} - \epsilon_\textrm{lower})\\
p_\textrm{internal down}&=  \frac{2\nu^2}{c^2} \frac{g_\textrm{lower}}{g_\textrm{i}}~f_{\textrm{lower}\rightarrow\textrm{i}}
                                   \beta_\textrm{Sobolev}\,\epsilon_\textrm{lower}\\
p_\textrm{internal up}&=\frac{1}{h\nu} f_{\textrm{i}\rightarrow\textrm{upper}}
                                    \underbrace{(1-\frac{g_\textrm{i}}{g_\textrm{upper}}\frac{n_\textrm{upper}}{n_i})}
                                    _\textrm{stimulated emission}
                                                \beta_\textrm{Sobolev} J_{\nu}^{b}\,\epsilon_{i}\\,\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}
There are two parts for each of the probabilities, one that is pre-computed by \emph{\textasciitilde{}tardisatomic} and is in the HDF5 File,
and one that is computed during the plasma calculations:
\begin{gather}
\begin{split}p_\textrm{emission down}&= \underbrace{\frac{2\nu^2}{c^2} \frac{g_\textrm{lower}}{g_\textrm{i}}~f_{\textrm{lower}\rightarrow\textrm{i}}
                                   (\epsilon_\textrm{i} - \epsilon_\textrm{lower})}_\textrm{pre-computed}
                                   \,\beta_\textrm{Sobolev}\\
p_\textrm{internal down} &= \underbrace{\frac{2\nu^2}{c^2} \frac{g_\textrm{lower}}{g_\textrm{i}}~f_{\textrm{lower}\rightarrow\textrm{i}}
                                   \epsilon_\textrm{lower}}_\textrm{pre-computed}\,\beta_\textrm{Sobolev}\\
p_\textrm{internal up} &= \underbrace{\frac{1}{h\nu} f_{\textrm{i}\rightarrow\textrm{upper}}}_\textrm{pre-computed}
                                                \beta_\textrm{Sobolev} J_{\nu}^{b}\,
                                                (1-\frac{g_\textrm{i}}{g_\textrm{upper}}\frac{n_\textrm{upper}}{n_i})
                                                \,\epsilon_{i}.\end{split}\notag\\\begin{split}\end{split}\notag
\end{gather}

\section{NLTE treatment}
\label{plasma:nlte-treatment}
NLTE treatment of lines is available both in \textasciitilde{}LTEPlasma and the \textasciitilde{}NebularPlasma class. This can be enabled by specifying
which species should be treated as NLTE with a simple list of tuples (e.g. {[}(20,1){]} for Ca II).

First let's dive into the basics:

There are two rates to consider from a given level.
\begin{gather}
\begin{split}R_{\textrm{upper}\rightarrow\textrm{lower}} &= \underbrace{A_{ul} n_u}_\textrm{spontaneous emission}
        + \underbrace{B_{ul} n_u \bar{J}_\nu}_\textrm{stimulated emission} +
        \underbrace{C_{ul} n_u n_e}_\textrm{collisional deexcitation}\\
        &= n_u \underbrace{(A_{ul} + B_{ul}\bar{J}_\nu + C_{ul} n_e)}_{r_{ul}} \\\end{split}\notag\\\begin{split}R_{\textrm{lower}\rightarrow\textrm{upper}} &= \underbrace{B_{lu} n_l \bar{J}_\nu}_\textrm{stimulated absorption} +
            \underbrace{C_{lu}\,n_l\,n_e}_\textrm{collisional excitation}\\
            &= n_l \underbrace{(B_{lu}\bar{J}_\nu + C_{ul}n_e)}_{r_{lu}},\end{split}\notag
\end{gather}
where $\bar{J}_\nu$ (in LTE this is $B(\nu, T)$) denotes the mean intensity at the frequency of the line and
$n_e$ the number density of electrons.

Next, we calculate the rate of change of a level by adding up all outgoing and all incoming transitions from level $j$.
\begin{gather}
\begin{split}\frac{dn_j}{dt} = \underbrace{\sum_{i \ne j} R_{ij}}_\textrm{incoming rate} -
                    \underbrace{\sum_{i \ne j} R_{ji}}_\textrm{outgoing rate}\end{split}\notag
\end{gather}
In a statistical equilibrium all incoming rates and outgoing rates add up to 0 ($\frac{dn_j}{dt}=0$). We use this to
calculate the level populations using the rate coefficients ($r_ij, r_ji$).
\begin{gather}
\begin{split}\left(
\begin{matrix}
-(\cal{R}_{12} + \dots + \cal{R}_{1j}) & \dots & \cal{R}_{j1}\\
\vdots & \ddots & \vdots \\
\cal{R}_{1j} & \dots & - (\cal{R} _{j1} + \dots + \cal{R} _{j, j-1}) \\
\end{matrix}
\right)
%
\left(
\begin{matrix}
n_1\\
\vdots\\
n_j\\
\end{matrix}
\right)
%
=
%
\left(
\begin{matrix}
0\\
0\\
0\\
\end{matrix}
\right)\end{split}\notag
\end{gather}
with the additional constrained that all the level number populations need to add up to the current ion population \$N\$ we change this to
\begin{gather}
\begin{split}\left(
\begin{matrix}
1 & 1 & \dots \\
\vdots & \ddots & \vdots \\
\cal{R}_{1j} & \dots & - (\cal{R} _{j1} + \dots + \cal{R} _{j, j-1}) \\
\end{matrix}
\right)
%
\left(
\begin{matrix}
n_1\\
\vdots\\
n_j\\
\end{matrix}
\right)
%
=
%
\left(
\begin{matrix}
N\\
0\\
0\\
\end{matrix}
\right)\end{split}\notag
\end{gather}
For a three level atom we have:
\begin{gather}
\begin{split}\frac{dn_1}{dt} &= \underbrace{n_2 r_{21} + n_3 r_{31}}_\textrm{incoming rate}
                - \underbrace{(n_1 r_{12} + n_1 r_{13})}_\textrm{outgoing rate} = 0\\\end{split}\notag\\\begin{split}\frac{dn_2}{dt} &= \underbrace{n_1 r_{12} + n_3 r_{32}}_\textrm{incoming rate}
                - \underbrace{(n_2 r_{21} + n_2 r_{23})}_{outgoing rate} = 0\\\end{split}\notag\\\begin{split}\frac{dn_3}{dt} &= \underbrace{n_1 r_{13} + n_2 r_{23}}_\textrm{incoming rate}
                - \underbrace{(n_3 r_{32} + n_3 r_{31})}_\textrm{outgoing rate} = 0,\end{split}\notag
\end{gather}
which can be written in matrix from:
\begin{gather}
\begin{split}\left(\begin{matrix}
    -(r_{12} + r_{13}) & r_{21} & r_{31}\\
    r_{12} & -(r_{21} + r_{23}) & r_{32}\\
    r_{13} & r_{23} & -(r_{31} + r_{32}) \\
\end{matrix}\right)
\left(
\begin{matrix}
    n_1\\
    n_2\\
    n_3\\
\end{matrix}
\right)
=
\left(
\begin{matrix}
    0\\
    0\\
    0\\
\end{matrix}
\right)\end{split}\notag
\end{gather}
To solve for the level populations we need an additional constraint: $n_1 + n_2 + n_3 = N$. By setting $N = 1$:
we can get the relative rates:
\begin{gather}
\begin{split}\left(\begin{matrix}
    1 & 1 & 1\\
    r_{12} & -(r_{21} + r_{23}) & r_{32}\\
    r_{13} & r_{23} & -(r_{31} + r_{32}) \\
\end{matrix}\right)
\left(
\begin{matrix}
    n_1\\
    n_2\\
    n_3\\
\end{matrix}
\right)
=
\left(
\begin{matrix}
    1\\
    0\\
    0\\
\end{matrix}
\right)\end{split}\notag
\end{gather}
Now we go back and look at the rate coefficients used for a level population - as an example $\frac{dn_2}{dt}$:
\begin{gather}
\begin{split}\frac{dn_2}{dt} &= n_1 r_{12} - n_2 (r_{21} + r_{23}) + n_3 r_{32}\\
            &= n_1 B_{12} \bar{J}_{12} + n_1 C_{12} n_e - n_2 A_{21} - n_2 B_{21} \bar{J}_{21} - n_2 C_{21} n_e\\
                    - n_2 B_{23} \bar{J}_{23} - n_2 C_{23} n_e + n_3 A_{32} + n_3 B_{32} \bar{J}_{32} + n_3 C_{32} n_e,\\
                     + n_3 A_{32}  + n_3 C_{32} n_e,\end{split}\notag
\end{gather}
Next we will group the stimulated emission and stimulated absorption terms as we can assume $\bar{J_{12}} = \bar{J_{21}}$:
\begin{gather}
\begin{split}\frac{dn_2}{dt} &= n_1 (B_{12} \bar{J}_{12} \underbrace{(1 - \frac{n_2}{n_1}\frac{B_{21}}{B_{12}})}_\textrm{stimulated emission term} + C_{12} n_e)
                - n_2 (A_{21} + C_{23} n_e + n_2 B_{23} \bar{J}_{23} \underbrace{(1 - \frac{n_3}{n_2}\frac{B_{32}}{B_{23}})}_\textrm{stimulated emission term})
                + n_3 (A_{32} + C_{32} n_e)\end{split}\notag
\end{gather}

\chapter{Radiative Monte Carlo}
\label{montecarlo:montecarlo}\label{montecarlo::doc}\label{montecarlo:radiative-monte-carlo}
The radiative monte carlo is initiated once the model is constructed.

Different line interactions

line\_interaction\_id == 0: scatter
line\_interaction\_id == 1: downbranch
line\_interaction\_id == 2: macro


\section{Radiationfield estimators}
\label{montecarlo:radiationfield-estimators}
During the monte-carlo run we collect two estimators for the radiation field:
\begin{gather}
\begin{split}J_\textrm{estimator} &= \sum{\epsilon l}\\
\bar{\nu}_\textrm{estimator} &=  \sum{\epsilon \nu l},\end{split}\notag
\end{gather}
where $\epsilon, \nu$ are comoving energy and comoving frequency of a packet respectively.

To calculate the temperature and dilution factor we first calculate the mean intensity in each cell
( $J = \frac{1}{4\pi\, \Delta t\, V} J_\textrm{estimator}$ )., {\hyperref[zreferences:a-a-403-261l]{{[}2{]}}}.

The weighted mean frequency is used to obtain the radiation temperature. Specifically, the radiation temperature is chosen as the
temperature of a black body that has the same weighted mean frequency as has been computed in the simulation. Accordingly,
\begin{gather}
\begin{split}\frac{h \bar{\nu}}{k_{B} T_{R}} = \frac{h}{k_{B} T_{R}} \frac{\bar{\nu}_\textrm{estimator}}{J_\textrm{estimator}}
  = 24 \zeta(5) \frac{15}{\pi^4},\end{split}\notag
\end{gather}
where the evaluation comes from the mean value of
\begin{gather}
\begin{split}\bar{x} = \frac{ \int_0^{\infty} x^4 / (\exp{x} - 1)dx}{\int_0^{\infty} x^3 / (\exp{x} - 1)dx} =
24 \zeta(5) \frac{15}{\pi^4} = 3.8322\dots\end{split}\notag
\end{gather}
and so
\begin{gather}
\begin{split}T_{R} &= \frac{1}{\bar{x}} \frac{h}{k_{B}} \frac{\bar{\nu}_\textrm{estimator}}{J_\textrm{estimator}} \\
&= 0.260945 \frac{h}{k_{B}} \frac{\bar{\nu}_\textrm{estimator}}{J_\textrm{estimator}}.\end{split}\notag
\end{gather}
With the radiation temperature known, we can then obtain our estimate for for the dilution factor. Our radiation field model in the
nebular approximation is
\begin{gather}
\begin{split}J = W B(T_{R}) = W \frac{\sigma_{SB}}{\pi} T_{R}^4,\end{split}\notag
\end{gather}
i.e. a dilute blackbody. Therefore we use our value of the mean intensity derrived from the estimator (above) to obtain the
dilution factor
\begin{gather}
\begin{split}W = \frac{\pi J}{\sigma_{SB} T_{R}^4} = \frac{1}{4\sigma_{SB} T_{R}^4\, \Delta t\, V} J_\textrm{estimator}.\end{split}\notag
\end{gather}
There endeth the lesson.


\chapter{Glossary}
\label{glossary:glossary}\label{glossary::doc}\begin{description}
\item[{\index{meta-stable|textbf}meta-stable}] \leavevmode\phantomsection\label{glossary:term-meta-stable}
A level is considered meta-stable if there's no line that has this level as the upper state. This means
that these levels can not be reached by absorbing a photon and are only reached when decaying.

\item[{\index{synapps|textbf}synapps}] \leavevmode\phantomsection\label{glossary:term-synapps}
simple radiative transport code for supernovae. Please refer to \href{https://c3.lbl.gov/es/}{Synapps} for more
information

\end{description}


\chapter{References}
\label{zreferences:references}\label{zreferences::doc}


\begin{thebibliography}{1}
\bibitem[1]{1}{\phantomsection\label{zreferences:1} \DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{L.}\DUspan{}{ }\DUspan{}{B.}}\DUspan{}{ }}\DUspan{}{Lucy}}\DUspan{}{.}}\DUspan{}{ }\DUspan{}{\DUspan{}{Monte Carlo transition probabilities}\DUspan{}{.}}}\DUspan{}{ }\DUspan{}{\DUspan{}{\emph{\DUspan{}{\textbackslash{}aap}}\DUspan{}{, }\DUspan{}{\DUspan{}{\DUspan{}{384}\DUspan{}{:}}\DUspan{}{\DUspan{}{725}\DUspan{}{–}\DUspan{}{735}}}}\DUspan{}{, }\DUspan{}{\DUspan{}{March}\DUspan{}{ }\DUspan{}{2002}}\DUspan{}{.}}}}
\bibitem[2]{2}{\phantomsection\label{zreferences:2} \DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{L.}\DUspan{}{ }\DUspan{}{B.}}\DUspan{}{ }}\DUspan{}{Lucy}}\DUspan{}{.}}\DUspan{}{ }\DUspan{}{\DUspan{}{Monte Carlo transition probabilities. II.}\DUspan{}{.}}}\DUspan{}{ }\DUspan{}{\DUspan{}{\emph{\DUspan{}{\textbackslash{}aap}}\DUspan{}{, }\DUspan{}{\DUspan{}{\DUspan{}{403}\DUspan{}{:}}\DUspan{}{\DUspan{}{261}\DUspan{}{–}\DUspan{}{275}}}}\DUspan{}{, }\DUspan{}{\DUspan{}{May}\DUspan{}{ }\DUspan{}{2003}}\DUspan{}{.}}}}
\bibitem[3]{3}{\phantomsection\label{zreferences:3} \DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{P.}\DUspan{}{ }\DUspan{}{A.}}\DUspan{}{ }}\DUspan{}{Mazzali}}\DUspan{}{ and }\DUspan{}{\DUspan{}{\DUspan{}{\DUspan{}{L.}\DUspan{}{ }\DUspan{}{B.}}\DUspan{}{ }}\DUspan{}{Lucy}}}\DUspan{}{.}}\DUspan{}{ }\DUspan{}{\DUspan{}{The application of Monte Carlo methods to the synthesis of early-time supernovae spectra}\DUspan{}{.}}}\DUspan{}{ }\DUspan{}{\DUspan{}{\emph{\DUspan{}{\textbackslash{}aap}}\DUspan{}{, }\DUspan{}{\DUspan{}{\DUspan{}{279}\DUspan{}{:}}\DUspan{}{\DUspan{}{447}\DUspan{}{–}\DUspan{}{456}}}}\DUspan{}{, }\DUspan{}{\DUspan{}{November}\DUspan{}{ }\DUspan{}{1993}}\DUspan{}{.}}}}
\end{thebibliography}



\renewcommand{\indexname}{Index}
\printindex
\end{document}
