% COBOLD manual
% 2001-12-30, 2002-01-02, 2002-01-31, 2002-02-16
%
\documentclass[a4paper,11pt,twoside]{article}

%\usepackage{amsmath}
%\usepackage{epsfig}
%\usepackage[dvips]{color}

\usepackage{latexsym}
\usepackage{makeidx}
\usepackage{html}


% --- Page format ---
\setlength{\unitlength}{1cm}
\setlength{\textwidth}{16.2cm}
\setlength{\textheight}{26cm}
\addtolength{\oddsidemargin}{-0.9cm}    % right page (single-side)
\addtolength{\evensidemargin}{-2.2cm}
\addtolength{\topmargin}{-2.3cm}        % Distance header-text

% --- New LaTeX commands ---
\newcommand{\papa}[2] { \frac{\partial #1}{\partial #2} }
\newcommand{\papaco}[3] {{ \left. \frac{\partial #1}{\partial #2}\right|_{#3}}}
\newcommand{\tildepapaco}[3] {{ \left. \widetilde{\frac{\partial #1}{\partial #2}}\right|_{#3}}}

% --- HD abbreviations ---
\newcommand{\I}[1] {i{\rm #1}}
\newcommand{\m}[1] {m{\rm #1}}
\newcommand{\n}[1] {n{\rm #1}}
\newcommand{\mghost}[1] {m{\rm #1}_{\rm ghost}}
\newcommand{\nghost}[1] {n{\rm #1}_{\rm ghost}}
\newcommand{\dx}[1] {\Delta x{\rm #1}}
\newcommand{\xc}[1] {x{\rm c#1}}
\newcommand{\xb}[1] {x{\rm b#1}}
\newcommand{\g}[1]{g{\rm #1}}
\newcommand{\phic}{\phi{\rm c}}
\newcommand{\phib}{\phi{\rm b}}
\newcommand{\rhov}[1]{\rho v{\rm #1}}
\newcommand{\rhoei} {\rho e{\rm i}}
\newcommand{\rhoeik} {\rho e{\rm ik}}
\newcommand{\rhoeip} {\rho e{\rm ip}}
\newcommand{\rhoek} {\rho e{\rm k}}
\newcommand{\rhoeg} {\rho e{\rm g}}
\newcommand{\rhoeikg} {\rho e{\rm ikg}}
\newcommand{\V}[1]{v{\rm #1}}
\newcommand{\tildeV}[1]{\tilde{v}{\rm #1}}
\newcommand{\ei} {e{\rm i}}
\newcommand{\eg} {e{\rm g}}
\newcommand{\tildeei} {\tilde{e}{\rm i}}
\newcommand{\tildeeik} {\tilde{e}{\rm ik}}
\newcommand{\tildeek} {\tilde{e}{\rm k}}
\newcommand{\tildeeip} {\tilde{e}{\rm ip}}
\newcommand{\eikp} {e{\rm ikp}}
\newcommand{\tildeeikp} {\tilde{e}{\rm ikp}}
\newcommand{\dPdei} {\papaco{P}{\ei}{\rho}}
\newcommand{\dPdrho} {\papaco{P}{\rho}{\ei}}
\newcommand{\drhoeidP} {\papaco{\rhoei}{P}{s}}
\newcommand{\drhoeidrho} {\papaco{\rhoei}{\rho}{P}}
\newcommand{\tildedrhoeidP} {\tildepapaco{\rhoei}{P}{s}}
\newcommand{\CCour} {C_{\rm Courant}}
\newcommand{\CCourmax} {C_{\rm Courant,max}}
\newcommand{\iup} {i_{\rm up}}
\newcommand{\cs} {c}
\newcommand{\wL} {w{\rm L}}
\newcommand{\wR} {w{\rm R}}
\newcommand{\Pred}{{P_{\rm st}}}
\newcommand{\Deltat}{\mbox{\small $\Delta$} t}
\newcommand{\dvdx}[2] { \frac{\Delta \V{#1}}{\dx{#2}} }

\newcommand{\negsp}{\begin{latexonly}$\!$\end{latexonly}}

\sloppy

\makeindex

\begin{document}

%\renewcommand{\labelitemii}{\color{blue} $\Box$}
%\renewcommand{\labelitemii}{$\Box$}
\renewcommand{\labelitemii}{$\circ$}


%\markboth{COBOLD User Manual}{COBOLD User Manual}
%\pagestyle{myheadings}
\pagestyle{headings}

\title{COBOLD User Manual}
\author{Bernd Freytag \and Matthias Steffen \and Sven Wedemeyer}
\date{\today}

\maketitle

\clearpage
%==================================================================================================
%\begin{latexonly}
\tableofcontents
%\ end{latexonly}

%\tableofchildlinks

\clearpage
%==================================================================================================
\section{Introduction}

COBOLD\index{COBOLD} or CO$^5$BOLD is the short form of
``COnservative COde for the COmputation of COmpressible COnvection
in a BOx of L Dimensions with l=2,3''.

It is used to model solar and stellar surface convection.
For solar-type stars only a small fraction of the stellar surface layers are included
in the computational domain.
In the case of red supergiants the computational box contains the entire star.

COBOLD solves the coupled non-linear equations
of compressible hydro\-dynamics\index{hydrodynamics}
in an external gravity field
together with non-local frequency-dependent radiation transport\index{radiation transport}.
Operator splitting is applied to solve
the equations of hydro\-dynamics (including gravity),
the radiative energy transfer (with a long-characteristics or
a short-characteristics ray scheme),
and possibly additional 3D (turbulent) diffusion
in individual sub steps.
The 3D hydro\-dynamics step is further simplified with directional splitting.
The 1D sub steps are performed with a Roe solver,
accounting for an external gravity field
and an arbitrary equation of state from a table.


The radiation transport is computed with either one of three modules:
\begin{itemize}

\item \verb|MSrad| module\index{MSrad}:
  It uses long characteristics. The lateral boundaries have to be periodic.
  Top and bottom can be closed or open (``solar module'').

\item \verb|LHDrad| module\index{LHDrad}:
  It uses long characteristics and is restricted to an equidistant grid and
  open boundaries at all surfaces (old ``supergiant module'').

\item \verb|SHORTrad| module\index{SHORTrad}:
  It uses short characteristics and is restricted to an equidistant grid and
  open boundaries at all surfaces (new ``supergiant module'').

\end{itemize}
COBOLD is written in Fortran90\index{Fortran}.
The parallelization is done with OpenMP directives\index{OpenMP}.

\vspace{5mm}

To get a brief overview you might want to look into the
``Quickstart Sections''
``How to compile COBOLD'' (Sect.~\ref{s:quickstart_compile}),
``Introduction to UIO'' (Sect.~\ref{s:quickstart_UIO}),
``How to make a proper Parameter File'' (Sect.~\ref{s:quickstart_parameterfile}),
``How to run COBOLD'' (Sect.~\ref{s:quickstart_runCOBOLD}).


%==================================================================================================
\section{Basic Equations}

The 3D hydro\-dynamics\index{hydrodynamics} equations,
including source terms due to gravity, are
the mass conservation equation
\begin{equation} \label{eq:3dhydrorho}
  \papa{\rho}{t} + \papa{\; \rho \; \V{1}}{x1}
                 + \papa{\; \rho \; \V{2}}{x2}
                 + \papa{\; \rho \; \V{2}}{x3} = 0 \enspace ,
\end{equation}
the momentum equation
\begin{equation} \label{eq:3dhydrov}
  \papa{}{t}
    \left( \!
      \begin{array}{c}
        \rhov{1} \\
        \rhov{2} \\
        \rhov{3}
      \end{array}
    \! \right)
  +
  \papa{}{x1}
    \left( \!
      \begin{array}{l}
        \rhov{1}  \; \V{1} + P \! \\
        \rhov{2}  \; \V{1} \\
        \rhov{3}  \; \V{1}
      \end{array}
    \right)
  +
  \papa{}{x2}
    \left( \!
      \begin{array}{l}
        \rhov{1}  \; \V{2} \\
        \rhov{2}  \; \V{2} + P \! \\
        \rhov{3}  \; \V{2}
      \end{array}
    \right)
  +
  \papa{}{x3}
    \left( \!
      \begin{array}{l}
        \rhov{1}  \; \V{3} \\
        \rhov{2}  \; \V{3} \\
        \rhov{3}  \; \V{3} + P \!
      \end{array}
    \right)
  \! = \!
    \left( \!
      \begin{array}{c}
        \rho \; \g{1} \\
        \rho \; \g{2} \\
        \rho \; \g{3}
      \end{array}
    \! \right)
\end{equation}
and the energy equation
\begin{equation}  \label{eq:3dhydroe}
   \papa{\rhoeik}{t} + \papa{\; (\rhoeik + P) \; \V{1}}{x1}
                     + \papa{\; (\rhoeik + P) \; \V{2}}{x2}
                     + \papa{\; (\rhoeik + P) \; \V{3}}{x3} = \rho \; ( \g{1} \; \V{1} + \g{2} \; \V{2} + \g{3} \; \V{3} ) .
\end{equation}
In addition, there are equations for the 3D tensor viscosity and the non-local radiation transport.


%==================================================================================================
\section{Program Files, Installation, Compilation}\index{compilation|(}

In this section all the files and modules COBOLD contains are listed.
The installation procedure is outlined
and compiler switches necessary to compile COBOLD and to optimize its performance
are described.

%--------------------------------------------------------------------------------------------------
\subsection{Quickstart: How to compile COBOLD\label{s:quickstart_compile}}\index{compilation}

If you are going to install COBOLD on a machine with a ``known''
(to setup script and makefile)
operating system and compiler
(see Sections \ref{s:directorystructure} and \ref{s:optimization})
then the procedure should be fairly easy:

\begin{enumerate}

\item Choose/create a proper base directory.
  (This will usually be \verb|$HOME|.
  Then the master directory will typically be \verb|$HOME/for| --
  this is the default created by the tar file.
  Some prefer to rename it to \verb|$HOME/HYDRO|.)

\item Put all source and makefiles there.
  This can be done e.g.\ by expanding the the gzipped tar file \verb|for.tar.gz| or
  copying all files from an existing installation.
  The tar file creates a sub directory \verb|for| in the local directory.
  You get sub sub directories as described in Sect.~\ref{s:directorystructure}
  and files as listed in Tab.~\ref{t:allmodules}.

\item Set the necessary environment variables as described in
  Sect.~\ref{s:directorystructure}. This includes the selection of the paths
  which lead to the makefiles appropriate for the architecture of your machine.

\item To compile the main executable \verb|rhd.exe| it should be sufficient
-- all files installed -- to type
\begin{verbatim}
cd ${RHDEXEPATH}
make
\end{verbatim}
which uses the master makefile\index{makefile} in \verb|${RHDEXEPATH}| which in turn
``calls'' the makefiles corresponding to the modules in the STR, UIO, EOS, HDRAD directories.
The makefiles have the same structure on all machines.
For a certain architecture (and optimization level)
the compiler name and corresponding switches in
the master makefile \verb|${RHDEXEPATH}/Makefile|
have to be edited (see Sect.~\ref{s:optimization}).

\end{enumerate}

A simple sample installation may look like the following
(the sub directory \verb|for| is put into the home directory.
It is assumed that the script \verb|setarcdeppaths.sh| is
made for the current machine and is appropriate for the shell).

\begin{verbatim}
# --- Choose base directory ---
cd ${HOME}

# --- Put tar file there ---
# ...

# --- Expand tar file ---
tar -zxvf for.tar.gz

# --- Go into (default) master directory ---
cd for

# --- Start script to set environment variables with paths ---
. setarcdeppaths.sh

# --- Jump into directory with main makefile ---
cd ${RHDEXEPATH}

# --- Compile ---
make

echo 'Voila!'
\end{verbatim}


%--------------------------------------------------------------------------------------------------
\subsection{Directory Structure\label{s:directorystructure}}

The files necessary to compile COBOLD are distributed over a few directories.
The paths are stored in environment variables\index{environment variables}
and can be set with the scripts
\verb|setarcdeppaths.csh|
or
\verb|setarcdeppaths.ksh|.
A typical setup would be to put everything into the main directory \verb|for|.
Then the source files would be located as in table~\ref{t:alldirs}.

\begin{table}[htb]
 \begin{center}
  \begin{tabular}{|lll|} \hline
Paths                            & Abb. & Description \\ \hline
\verb|${HOME}/for/mat/str/|      & STR  & string handling \\
\verb|${HOME}/for/uio/f90/|      & UIO  & I/O routines \\
\verb|${HOME}/for/eos/f90/|      & EOS  & equation of state \\
\verb|${HOME}/for/rad/hdrad/|    & RAD  & opacities, Matthias' radiation transport \\
\verb|${HOME}/for/hd/rhd/|       & RHD  & main rhd routines \\ \hline
  \end{tabular} 
  \caption[List of source directories]{List of source directories
     with path and file name, abbreviation, and a short description.
     }\label{t:alldirs}
 \end{center}
\end{table}

The executables (and makefiles, object files, module information files) are typically
located in subdirectories of the source code directories.
These subdirectories should have the name of the machine, architecture, or
operating system the executable is compiled for.
The environment variables\index{environment variables} for the UIO routines can be e.g.\
\begin{verbatim}
UIOSRCPATH=/home/user/for/uio/f90
UIOEXEPATH=/home/user/for/uio/f90/sun .
\end{verbatim}
A script to set all necessary variables and paths can be (here for the bash shell for Linux)
{\small \begin{verbatim}
#!/bin/bash
#
# --- Disk where all Fortran programs are located ---
FORTRANDISK=${HOME}/for ; export FORTRANDISK
#
# --- Machine dependent modules ---
UIOMAC=uio_mac_sun_module; export UIOMAC
RHDMAC=rhd_mac_sun_module; export RHDMAC
#
# --- Architecture dependent sub directory names ---
# --- for object file and executables            ---
MAC=linux
#
# --- Individual libraries ---
# --- uio ---
UIOPATH=${FORTRANDISK}/uio ; export UIOPATH
UIOSRCPATH=${UIOPATH}/f90 ; export UIOSRCPATH
#
# --- String handling ---
STRPATH=${FORTRANDISK}/mat/str ; export STRPATH
STRSRCPATH=${STRPATH} ; export STRSRCPATH
#
# --- Mathe ---
MATPATH=${FORTRANDISK}/mat ; export MATPATH
MATSRCPATH=${MATPATH}/f90 ; export MATSRCPATH
#
# --- gas ---
GASPATH=${FORTRANDISK}/eos/gas ; export GASPATH
GASSRCPATH=${GASPATH} ; export GASSRCPATH
#
# --- EOS ---
EOSPATH=${FORTRANDISK}/eos ; export EOSPATH
EOSSRCPATH=${EOSPATH}/f90 ; export EOSSRCPATH
#
# --- rad ---
RADPATH=${FORTRANDISK}/rad/hdrad ; export RADPATH
RADSRCPATH=${RADPATH} ; export RADSRCPATH
#
# --- RHD ---
RHDPATH=${FORTRANDISK}/hd/rhd ; export RHDPATH
RHDSRCPATH=${RHDPATH} ; export RHDSRCPATH
#
# --- Architecture dependent directories for object file and executables ---
UIOEXEPATH=${UIOSRCPATH}/${MAC}  ; export UIOEXEPATH
STREXEPATH=${STRPATH}/${MAC}     ; export STREXEPATH
MATEXEPATH=${MATSRCPATH}/${MAC}  ; export MATEXEPATH
GASEXEPATH=${GASPATH}/${MAC}     ; export GASEXEPATH
EOSEXEPATH=${EOSSRCPATH}/${MAC}  ; export EOSEXEPATH
RADEXEPATH=${RADPATH}/${MAC}     ; export RADEXEPATH
RHDEXEPATH=${RHDPATH}/${MAC}     ; export RHDEXEPATH
\end{verbatim}}
\noindent This script can be executed with
\begin{verbatim}
. $HOME/bin/setarcdeppaths.sh
\end{verbatim}
This line can be put e.g.\ into the \verb|.bashrc| file.

Some lines can be edited to account for individual choices and the
target machine.
With
\begin{verbatim}
FORTRANDISK=$HOME/for ; export FORTRANDISK
\end{verbatim}
the master directory is specified.
With
\begin{verbatim}
UIOMAC=uio_mac_sun_module; export UIOMAC
RHDMAC=rhd_mac_sun_module; export RHDMAC
\end{verbatim}
you specify some machine dependent modules. The \verb|sun| modules
work for most machines (e.g.\ for Linux PCs).
With
\begin{verbatim}
MAC=linux
\end{verbatim}
you specify the name of the subdirectories with the makefiles\index{makefile}.
The other lines only have to be edited if you want to organize
the directories in a completely different way.


%--------------------------------------------------------------------------------------------------
\subsection{Fortran Files\label{s:fortran_files}}\index{Fortran}

Table~\ref{t:allmodules} shows a list of all source files necessary to compile COBOLD.

\begin{table}[htb]
 \begin{center}
  \begin{tabular}{|lll|} \hline
File and path                             & Abb. & Description \\ \hline
\verb|mat/str/str_module.f90|             & STR  & string handling \\ \hline
\verb|uio/f90/uio_base_module.f90|        & UIO  & I/O routines \\
\verb|uio/f90/uio_bulk_module.f90|        & UIO  & I/O routines \\
\verb|uio/f90/uio_filedef_module.f90|     & UIO  & I/O routines \\
\verb|uio/f90/uio_mac_crayxmp_module.f90| & UIO  & I/O routines, machine dependent part \\ \hline
\verb|eos/f90/gasinter_routines.f90|      & EOS  & equation of state \\ \hline
\verb|rad/hdrad/cubit_module.f|           & RAD  & cubic interpolation \\
\verb|rad/hdrad/opta_par_module.f90|      & RAD  & parameters for opacity routines \\
\verb|rad/hdrad/opta_routines.f|          & RAD  & opacity \\ \hline
\verb|rad/hdrad/MSrad3D.F90|              & RAD  & Matthias' radiation transport routines\index{MSrad}, \\
                                          &      & long characteristics, periodic sides \\ \hline
\verb|hd/rhd/timing_module.f90|           & RHD  & timing routines \\ \hline
\verb|hd/rhd/rhd_const_module.f90|        & RHD  & physical and mathematical constants \\
\verb|hd/rhd/rhd_gl_module.f90|           & RHD  & global parameters \\
\verb|hd/rhd/rhd_action_module.f90|       & RHD  & routines for control parameter passing \\
\verb|hd/rhd/rhd_box_module.f90|          & RHD  & box handling routines \\
\verb|hd/rhd/rhd_dat_module.f90|          & RHD  & handling of additional data (averages) \\
\verb|hd/rhd/rhd_mean_module.f90|         & RHD  & averaging routines \\
\verb|hd/rhd/rhd_io_module.f90|           & RHD  & input/output routines \\
\verb|hd/rhd/rhd_mac_cray_module.f90|     & RHD  & machine dependent routines (CRAY) \\
\verb|hd/rhd/rhd_mac_default_module.f90|  & RHD  & machine dependent routines (default) \\
\verb|hd/rhd/rhd_mac_sun_module.f90|      & RHD  & machine dependent routines (Sun) \\
\verb|hd/rhd/rhd_sub_module.f90|          & RHD  & additional routines \\
\verb|hd/rhd/rhd_hyd_module.F90|          & RHD  & hydrodynamics routines\index{hydrodynamics routines} \\
\verb|hd/rhd/rhd_vis_module.F90|          & RHD  & tensor viscosity routines\index{tensor viscosity routine} \\
\verb|hd/rhd/rhd_rad_module.f90|          & RHD  & interface for Matthias' radiation routine \\
\verb|hd/rhd/rhd_lhdrad_module.F90|       & RHD  & radiative transfer routines,\index{LHDrad} \\
                                          &      & long characteristics, supergiant case \\
\verb|hd/rhd/rhd_shortrad_module.F90|     & RHD  & radiative transfer routines,\index{SHORTrad} \\
                                          &      & short characteristics, supergiant case \\
\verb|hd/rhd/rhd.F90|                     & RHD  & main program \\ \hline
  \end{tabular} 
  \caption[List of all modules]{List of all modules:
the table shows the file name with part of its path,
the shortcut for the directory,
and its description.
     }\label{t:allmodules}
 \end{center}
\end{table}


%--------------------------------------------------------------------------------------------------
\subsection{Compiler Macros}\index{compiler macro|(}

Some of the modules of the COBOLD code (with suffix ``.F90'') employ compiler macros
to switch between code versions during compile time.
Typically you define at least on of the three switches \verb|rhd_r01|, \verb|rhd_r02|,
or \verb|rhd_r03| to choose a radiation transport module.
The others have reasonable default values.
To find the combination with the optimal performance, you should look into Sect.~\ref{s:optimization}

\begin{itemize}

\item \verb|rhd_r01|: in \verb|rhd.F90|,\index{compiler macro!rhdr01@\verb/rhd_r01/}\label{s:rhd_r01}
  (``rhd radiation 01''). \\
  Switch to include LHDrad radiation transport module.
  It uses long characteristics and is restricted to an equidistant grid and
  open boundaries at all surfaces (old ``supergiant module'').
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) LHDrad routines are deactivated.
  \item \verb|1|:         LHDrad routines are recognized by the compiler.
  \end{itemize}

\item \verb|rhd_r02|: in \verb|rhd.F90|,\index{compiler macro!rhdr02@\verb/rhd_r02/}\label{s:rhd_r02}
  (``rhd radiation 02''). \\
  Switch to include MSrad\index{MSrad} radiation transport module.
  It uses long characteristics. The lateral boundaries have to be periodic.
  Top and bottom can be closed or open (``solar module'').
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) MSrad routines are deactivated.
  \item \verb|1|:         MSrad routines are recognized by the compiler.
  \end{itemize}

\item \verb|rhd_r03|: in \verb|rhd.F90|,\index{compiler macro!rhdr03@\verb/rhd_r03/}\label{s:rhd_r03}
  (``rhd radiation 03''). \\
  Switch to include SHORTrad radiation transport module.
  It uses short characteristics and is restricted to an equidistant grid and
  open boundaries at all surfaces (new ``supergiant module'').
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) SHORTrad routines are deactivated.
  \item \verb|1|:         SHORTrad routines are recognized by the compiler.
  \end{itemize}

\item \verb|IDF|: in \verb|rhd_hyd_module.F90|,\index{compiler macro!IDF@\verb/IDF/}
  (``Integer Delta Flux''). \\
  Number of padding cells for flux-like variables. This number was introduced to check
  whether the increase of the size of vectors for flux-like quantities (defined at
  cell boundaries) can improve the performance (especially on a CRAY machine).
  The gain is marginal (if present at all). The parameter is usually set to zero
  or left undefined.
  Values:
  \begin{itemize}
  \item \verb|0|: (default) no padding cells
  \item \verb|1,2,3,|\ldots: extra padding cells
  \end{itemize}

\item \verb|rhd_hyd_gravcorr_p01|: in \verb|rhd_hyd_module.F90|,\index{compiler macro!rhdhydgravcorrp01@\verb/rhd_hyd_gravcorr_p01/}\label{s:rhd_hyd_gravcorr_p01}
  (``rhd hydrodynamics gravitation correction parameter 01''). \\
  This parameter controls the way the Roe solver handles the source terms
  due to gravity. A different choice results in different simulation results
  and not just in slightly faster (or slower) code.
  The problem is that the original Roe solver interpretes the pressure gradient
  in a hydrostatic stratification a fluctuation due to shock waves.
  In case of strong stratification this can lead to weird effects.
  With activated correction the Roe solver treats only the deviations from
  a hydrostatic stratification as due to waves (or shocks).
  Several correction formulas have been tried.
  The latest is the recommended default.
  Values:
  \begin{itemize}
  \item \verb|0|: No pressure correction terms in Roe solver.
  \item \verb|1|: Simple correction with rhomean, no new average pressure.
  \item \verb|2|: Simple correction with rhomean, new average pressure.
  \item \verb|3|: Correction with local rho, limited, new average pressure.
  \item \verb|4|: Correction with local rho, new (different formula) average pressure.
  \item \verb|5|: (default) Correction with local rho, new limit, new average pressure.
  \end{itemize}

\item \verb|rhd_hyd_entropyfix_p01|: in \verb|rhd_hyd_module.F90|,\index{entropy fix}\index{compiler macro!rhdhydentropyfixp01@\verb/rhd_hyd_entropyfix_p01/}\label{s:rhd_hyd_entropyfix_p01}
  (``rhd hydrodynamics entropy fix parameter 01''). \\
  The entropy fix can be done in one of two ways
  to get optimum performance (with essentially the same results).
  Values:
  \begin{itemize}
  \item \verb|0|: (default) ``if\ldots then\ldots else'' construction
  \item \verb|1|: use a mask and the signum function
  \end{itemize}

\item \verb|rhd_hyd_upwind_p01|: in \verb|rhd_hyd_module.F90|,\index{compiler macro!rhdhydupwindp01@\verb/rhd_hyd_upwind_p01/}
  (``rhd hydrodynamics upwind parameter 01''). \\
  The determination of the upwind direction can be done in one of two ways
  to get optimum performance (with essentially the same results).
  Values:
  \begin{itemize}
  \item \verb|0|: (default) ``if\ldots then\ldots else'' construction
  \item \verb|1|: use a mask and the signum function
  \end{itemize}

\item \verb|rhd_hyd_roe1d_l01|: in \verb|rhd_hyd_module.F90|,\index{compiler macro!rhdhydroe1dl01@\verb/rhd_hyd_roe1d_l01/}\label{s:rhd_hyd_roe1d_l01}
  (``rhd hydrodynamics roe 1 dimension loop 01''). \\
  The computation of the Roe fluxes can be done by either of two sets of routines
  to find the set which gives optimum performance (with essentially the same results).
  Values:
  \begin{itemize}
  \item \verb|0|: (default) lots of small routines acting on scalars, inlining needed,
                    cache reuse is optimized
  \item \verb|1|: routines acting on arrays, more temporary arrays necessary,
                    vectorization is easier
  \end{itemize}

\item \verb|rhd_bound_t01|: in \verb|rhd_hyd_module.F90|,\index{compiler macro!rhdboundt01@\verb/rhd_bound_t01/}
  (``rhd bound timing 01''). \\
  Produce timing information for ``inner boundary'' routine (central potential)
  or lower and upper boundary routines (constant gravitation).
  It can be used together with OpenMP.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) no timing information
  \item \verb|defined|: call subroutines to measure elapsed time
  \end{itemize}

\item \verb|rhd_roe1d_flux_t01|: in \verb|rhd_hyd_module.F90|,\index{compiler macro!rhdroe1dfluxt01@\verb/rhd_roe1d_flux_t01/}
  (``rhd roe 1 dimension flux timing 01''). \\
  Produce timing information for the routine which computes the Roe fluxes.
  It should not be used in conjunction with OpenMP.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) no timing information
  \item \verb|defined|: call subroutines to measure elapsed time
  \end{itemize}

\item \verb|rhd_roe1d_step_t01|: in \verb|rhd_hyd_module.F90|,\index{compiler macro!rhdroe1dstept01@\verb/rhd_roe1d_step_t01/}
  (``rhd roe 1 dimension step timing 01''). \\
  Produce timing information for the routine which performs the Roe step.
  It should not be used in conjunction with OpenMP.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) no timing information
  \item \verb|defined|: call subroutines to measure elapsed time
  \end{itemize}

\item \verb|rhd_h02|: in \verb|rhd.F90|, \verb|rhd_hyd_module.F90|,\index{compiler macro!rhdh02@\verb/rhd_h02/}
  (``rhd hydrodynamics 02''). \\
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) Skip routine \verb|vanLeer1d_step| during compilation
  \item \verb|defined|: Compile routine \verb|vanLeer1d_step|
  \end{itemize}


\item \verb|rhd_vis_density_p01|: in \verb|rhd_vis_module.F90|,\index{compiler macro!rhdvisdensityp01@\verb/rhd_vis_density_p01/}
  (``rhd viscosity density parameter 01''). \\
  Choose formula for density average at cell boundary in tensor viscosity routines.
  Values:
  \begin{itemize}
  \item \verb|0|: rhomean=min(rholeft,rhoright)
  \item \verb|1|: (default) rhomean=0.5 * (rholeft + rhoright)
  \end{itemize}

\item \verb|rhd_vis_t01|: in \verb|rhd_vis_module.F90|,\index{compiler macro!rhdvist01@\verb/rhd_vis_t01/}
  (``rhd viscosity timing 01''). \\
  Produce timing information for 2D/3D tensor viscosity routines.
  It should not be used in conjunction with OpenMP.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) no timing information
  \item \verb|defined|: call subroutines to measure elapsed time
  \end{itemize}


\item \verb|rhd_rad3d_toray_l01|: in \verb|rhd_lhdrad_module.F90|,\index{compiler macro!rhdrad3dtorayl01@\verb/rhd_rad3d_toray_l01/}
  (``rhd radiation 3 dimensions to ray loop 01''). \\
  There might be a performance gain by splitting the main loop in routine \verb|rhd_rad3d_toray|
  into three separate loops. Typically, one big loop is to be preferred.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) One big loop
  \item \verb|defined|: Three smaller loops
  \end{itemize}

\item \verb|rhd_rad3d_fromray_l01|: in \verb|rhd_lhdrad_module.F90|,\index{compiler macro!rhdrad3dfromrayl01@\verb/rhd_rad3d_fromray_l01/}
  (``rhd radiation 3 dimensions from ray loop 01''). \\
  There might be a performance gain by splitting a big loop in routine \verb|rhd_rad3d_fromray|
  into two separate loops. Typically, one big loop is to be preferred.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) One big loop
  \item \verb|defined|: Two smaller loops
  \end{itemize}

\item \verb|rhd_rad3d_r02|: in \verb|rhd_lhdrad_module.F90|,\index{compiler macro!rhdrad3dr02@\verb/rhd_rad3d_r02/}
  (``rhd radiation 3 dimensions radiation 02''). \\
  Module \verb|rhd_lhdrad_module| contains a routine for the handling of periodic
  boundaries.
  It is in an experimental state and is deactivated by default.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) Skip routine \verb|rhd_rad3d_dirper| during compilation
  \item \verb|defined|: Compile routine \verb|rhd_rad3d_dirper|
  \end{itemize}

\item \verb|rhd_rad3d_solve_t01|: in \verb|rhd_lhdrad_module.F90|,\index{compiler macro!rhdrad3dsolvet01@\verb/rhd_rad3d_solve_t01/}
  (``rhd radiation 3 dimensions solve timing 01''). \\
  Produce timing information for the routines which solves the 1D radiation transport
  equation along single ray.
  This routine is called very frequently. The timing measurement might slow it down somewhat.
  It should not be used in conjunction with OpenMP.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) no timing information
  \item \verb|defined|: call subroutines to measure elapsed time
  \end{itemize}

\item \verb|rhd_rad3d_dir_t01|: in \verb|rhd_lhdrad_module.F90|,\index{compiler macro!rhdrad3ddirt01@\verb/rhd_rad3d_dir_t01/}
  (``rhd radiation 3 dimensions direction timing 01''). \\
  Produce timing information for the routines which solves the radiation transport
  equation for one direction field.
  The timing measurement are called very frequently and might slow down the code.
  It should not be used in conjunction with OpenMP.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) no timing information
  \item \verb|defined|: call subroutines to measure elapsed time
  \end{itemize}

\item \verb|rhd_rad3d_step_t01|: in \verb|rhd_lhdrad_module.F90|,\index{compiler macro!rhdrad3dstept01@\verb/rhd_rad3d_step_t01/}
  (``rhd radiation 3 dimensions step timing 01''). \\
  Produce timing information with main 3D radiation transport routine.
  It can be used together with OpenMP and should cause no noticeable performance loss.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) no timing information
  \item \verb|defined|: call subroutines to measure elapsed time
  \end{itemize}


\item \verb|rhd_shortrad_operator_l01|: in \verb|rhd_shortrad_module.F90|,\index{compiler macro!rhdshortradoperatorl01@\verb/rhd_shortrad_operator_l01/}\label{s:rhd_shortrad_operator_l01}
  (``rhd short-characteristics radiation operator loop 01''). \\
  Choose type of short characteristics operator.
  Values:
  \begin{itemize}
  \item \verb|0|: simple test operator, fast but results are utterly useless!
  \item \verb|1|: (default) case distinction with ``if..then..else'' construct
  \item \verb|2|: case distinction with masks (weights 0.0 or 1.0)
  \end{itemize}

\item \verb|rhd_shortrad_formal_l01|: in \verb|rhd_shortrad_module.F90|,\index{compiler macro!rhdshortradformall01@\verb/rhd_shortrad_formal_l01/}\label{s:rhd_shortrad_formal_l01}
  (``rhd short-characteristics radiation formal loop 01''). \\
  Select version of loop splitting for exp(-dtau) computation.
  Values:
  \begin{itemize}
  \item \verb|0|: (default) \verb|dtauhalf|, \verb|exp_mdtauhalf|, \verb|expl2t_mdtauhalf|
                    are computed in single loop
  \item \verb|1|: (\verb|dtauhalf|, \verb|exp_mdtauhalf|), (\verb|expl2t_mdtauhalf|)
                    are computed in separate loops.
                    This prevents the SUN1 machine (Sunfire, Solaris, Forte~6.2) from doing
                    some performance degrading optimization
  \end{itemize}

\item \verb|rhd_shortrad_dir1_l01|: in \verb|rhd_shortrad_module.F90|,\index{compiler macro!rhdshortraddir1l01@\verb/rhd_shortrad_dir1_l01/}\label{s:rhd_shortrad_dir1_l01}
  (``rhd short-characteristics radiation direction 1 loop 01''). \\
  Choose routine version for rays in x1 direction.
  Values:
  \begin{itemize}
  \item \verb|0|: (default) Use routine with permuted indices for rays in x1 direction.
                    In this case the innermost loop index is the third array index.
                    The transposition of arrays is not needed but some machines (e.g.\ SUN1) do not like
                    this index arrangement.
  \item \verb|1|: Transpose arrays and use routine \verb|rhd_shortrad_dir3| for rays in x1 direction.
                    The extra step for the transposition of some arrays (and the reverse procedure)
                    needs some time. But now the routine with the optimum index ordering can be used.
  \end{itemize}

\item \verb|rhd_shortrad_dir_l02|: in \verb|rhd_shortrad_module.F90|,\index{compiler macro!rhdshortraddirl02@\verb/rhd_shortrad_dir_l02/}
  (``rhd short-characteristics radiation direction loop 02''). \\
  Determine position of PARALLEL statement relative to outer loop in \verb|rhd_shortrad_dirX|.
  Both settings give the same results but might show a different performance on a specific machine.
  Values:
  \begin{itemize}
  \item \verb|0|: (default) PARALLEL statement inside of outer loop
  \item \verb|1|: PARALLEL statement outside of outer loop
  \end{itemize}

\item \verb|rhd_shortrad_formal_t01|: in \verb|rhd_shortrad_module.F90|,\index{compiler macro!rhdshortradformalt01@\verb/rhd_shortrad_formal_t01/}
  (``rhd short-characteristics radiation formal timing 01''). \\
  Produce timing information for routine which gives the formal solution of the
  radiation transport equation with the help of short characteristics.
  It can be used together with OpenMP and should cause no noticeable performance loss.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) no timing information
  \item \verb|defined|: call subroutines to measure elapsed time
  \end{itemize}

\item \verb|rhd_shortrad_step_t01|: in \verb|rhd_shortrad_module.F90|,\index{compiler macro!rhdshortradstept01@\verb/rhd_shortrad_step_t01/}
  (``rhd short-characteristics radiation step timing 01''). \\
  Produce timing information for main short characteristics routine.
  It can be used together with OpenMP and should cause no noticeable performance loss.
  Values:
  \begin{itemize}
  \item \verb|undefined|: (default) no timing information
  \item \verb|defined|: call subroutines to measure elapsed time
  \end{itemize}

%\item \verb||: in \verb|rhd__module.F90|,
%  (``''). \\
%  Values:
%  \begin{itemize}
%  \item \verb||: (default)
%  \item \verb||: 
%  \end{itemize}

\end{itemize}

\index{compiler macro|)}

%--------------------------------------------------------------------------------------------------
\subsection{Optimization, Compiler Switches\label{s:optimization}}

In this section some mandatory or useful compiler flags are described.
These have different functions:
\begin{itemize}

\item Enable necessary macro processing/expansion for the \verb|F90| files.

\item Force proper handling of binary I/O.

\item Choose module for radiative transfer.

\item Enable parallelization with OpenMP\index{OpenMP} directives.

\item Choose a version of a subroutine or loop which is optimized for
  a specific architecture.

\item Tell the compiler if and what to inline\index{inlining}.

\item Improve the general performance.

\end{itemize}


\subsubsection{Cray: SV1}\index{Cray}\index{craSHi}\index{compiler!Cray}

On \htmladdnormallinkfoot{craSHi}{http://www.uni-kiel.de/zentr/rz/nvv/craSHi/}
in Kiel (a ``CRAY SV1 20-32768 SN9542'')
COBOLD can use all 4 processors per board.
Documentation about the system and the compiler can be found with the
\htmladdnormallinkfoot{CRAYdoc}{http://www.cray.com/craydoc/} system.

In some cases the non-default versions of loops in the COBOLD code
vectorize better and are preferred over the standard ones:

\begin{itemize}

\item \verb|-F|: Enable macro expansion

\item \verb|-Otask1|: Parallelization: Enable tasking (in this case OpenMP\index{OpenMP!on Cray VX1}).

\item \verb|-Oinline3|: Optimization: enable (high level) of inlining\index{inlining!Cray VX1}.

\item \verb|-Ovector3 -Oscalar3|: General optimization

\item \verb|-Drhd_hyd_roe1d_l01=1|: Optimization: Choose non-standard set of routines for
  Roe solver\index{Roe solver}.
  See Sect.~\ref{s:rhd_hyd_roe1d_l01}.

\item \verb|-Drhd_hyd_entropyfix_p01=1|: Optimization: version with masks (weights).
  See Sect.~\ref{s:rhd_hyd_entropyfix_p01}

\item \verb|-Drhd_hyd_upwind_p01=1|: Optimization: version with masks (weights).

\item \verb|-Drhd_shortrad_operator_l01=2|: Optimization:
  short characteristics operator with masks (weights).

\item \verb|-Drhd_shortrad_dir_l02=1|: Optimization:
  \verb|OMP PARALLEL| statement outside of outer loop in \verb|rhd_shortrad_dirX|.

\end{itemize}


\subsubsection{DECalpha}\index{DECalpha}\index{compiler!DECalpha}

\htmladdnormallinkfoot{Documentation about the Compaq Fortran compiler}{http://www.compaq.com/fortran/docs/index.html}.

\begin{itemize}

\item \verb|-assume byterecl|: Necessary for the UIO routines\index{UIO}:
  specify that the length of a record is measured in bytes (and not in words).
 
\item \verb|-cpp|: invoke the preprocessor on all source files
 
\item \verb|-inline speed|: Force automatic inlining\index{inlining!DECalpha},
  optimized for speed.
 
\item \verb|-O4|: General optimization.
 
\item \verb|-Drhd_hyd_roe1d_l01=0|: Optimization: Choose standard set of routines for
  Roe solver\index{Roe solver}.
  See Sect.~\ref{s:rhd_hyd_roe1d_l01}.
 
\item \verb|-DMSrad_raytas1|: Optimization: choose non-default version
  of \verb|SUBROUTINE raytas| in file \verb|MSrad3D.F90|.\index{MSrad}
 
\end{itemize}


\subsubsection{Hewlett-Packard: V2500}\index{Hewlett-Packard}\index{compiler!Hewlett-Packard}

The 12-processor machine ``zeipel'' from
\htmladdnormallinkfoot{Hewlett-Packard}{http://devresource.hp.com/devresource/Tools/lang.html}
is a ``V2500 PA 2.0'' system.
Yet, there is no success to make it accept all the OpenMP directives in COBOLD
(and to run COBOLD in parallel mode).
And the single-processor performance is mediocre.
Some macros, which seem to be necessary:

\begin{itemize}

\item \verb|+U77|: Link proper library to make the machine understand
  e.g.\ \verb|call flush(6)|.

\item \verb|+cpp=yes|: Switch on the C preprocessor. Note that all Fortran90 files have to
  end with ``.f90''. The ``.F90'' suffix does not seem to work.

\item \verb|+Oparallel +Oopenmp +Onoautopar|: Try to enable parallelization with
  OpenMP directives, disable auto-parallelization. Does not work!

\item \verb|+Onoinline|: Disable inlining. That's too complicated.

\item \verb|+O3 +Olimit|: General optimization with limited resource usage
  during compilation.

\end{itemize}


\subsubsection{Hitachi}\index{Hitachi}\index{compiler!Hitachi}

\begin{itemize}

\item \verb|-conti199|: Up to 199 continuation lines can be interpreted
  (otherwise not more than 39 continuation lines are accepted).

\item \verb|-limit|: Limits the amount of time and memory for compilation.

\item \verb|-opt=ss|: use highest possible optimization level.

\item \verb|-nopredicate|: this option switches off a sub-option activated
  by opt=ss. It is necessary to disable the -predicate option because
  the code crashes otherwise (segmentation violation). The switch must
  appear \emph{after} setting \verb|-opt=ss|.

\item \verb|-pvfunc=2|: References the pseudo-vectorizing mathematical
  function and applies the temporary array to reference the pseudo-vectorizing
  mathematical function.
 
\item \verb|-omp -parallel=1|: parallelize based on
  OpenMP\index{OpenMP!on Hitachi} directives only.
 
\item \verb|-orphaned=1|: Checks if the regions sequentially executed
  contain orphaned directives during run-time when PROCNUM=8 is specified.
  If a sequentially executed region contains an orphaned directive, the
  system outputs a message and terminates the program.
 
\item \verb|-nestcheck=1|: Checks for nesting errors in parallel regions.
  If a parallel region is nested, the system returns an error and terminates
  the program. {\em Without this option, the code aborts with an error message,
  indicating illegal nesting. Compiler bug?}
 
\item \verb|-procnum=8|: generated code for 8 processors on one node
 
\item \verb|-pmpar|: Collects the performance monitor information for each
parallelization unit.
 
\item \verb|-pmfunc|: Collects the performance monitor information for each
procedure.
 
\item \verb|-Drhd_hyd_roe1d_l01=1|: Optimization: Choose non-standard set of routines for
  Roe solver\index{Roe solver}.
  See Sect.~\ref{s:rhd_hyd_roe1d_l01}.
 
\item \verb|-DMSrad_raytas1|: Optimization: choose non-default version
  of \verb|SUBROUTINE raytas| in file \verb|MSrad3D.F90|.\index{MSrad}
 
\item {\bfseries Important note:}
  The UIO routines need in addition the compiler
  option \verb|-subchk|: Array bound checking. Without this checking
  option, some UIO routines are not working properly (compiler bug?).
 
\end{itemize}


\subsubsection{Linux: PGI Compiler}\index{Linux}\index{compiler!PGI}

So far, under Linux the compiler of the
\htmladdnormallinkfoot{Portland Group}{http://www.pgroup.com/}
usually has been used to compile COBOLD.
The compiler is called with \verb|pgf90|.
Important switches are:

\begin{itemize}

\item \verb|-byteswapio|: With this flag set, binary files in
  \verb|big_endian|\index{bigendian@\verb/big_endian/} format
  (the standard for UIO files)
  are automatically transformed to
  \verb|little_endian|\index{littleendian@\verb/little_endian/}
  and vice versa.

\item \verb|-fast|: General optimization flag to choose (close to)
  optimum optimization for local machine.

\item \verb|-Mvect=sse|: Optimization: Allow Pentium~III vector commands.

\item \verb|-Mcache_align|: Optimization: Align some data object
  on cache-line boundaries.

\item \verb|-Minline=...|: Optimization: Routines that should be
  inlined\index{inlining!PGI compiler on Linux}: \\
 file \verb|rhd_hyd_module.F90|: \verb|rhd_hyd_avg|,
  \verb|rhd_hyd_upwind|,
  \verb|rhd_hyd_pred0|,
  \verb|rhd_hyd_predm|,
  \verb|rhd_hyd_predp|,
  \verb|rhd_hyd_alpha|,
  \verb|rhd_hyd_constanteq|,
  \verb|rhd_hyd_minmodeq|,
  \verb|rhd_hyd_minmod|,
  \verb|rhd_hyd_vanleereq|,
  \verb|rhd_hyd_vanleer|,
  \verb|rhd_hyd_superbeeeq|,
  \verb|rhd_hyd_superbee|,
  \verb|rhd_hyd_ppeq|,
  \verb|rhd_hyd_pp|,
  \verb|rhd_hyd_hdflux|, \\
 file \verb|rhd_lhdrad_module.F90|:
  \verb|rhd_rad3d_raylhd|,
  \verb|rhd_rad3d_solve|,
  \verb|rhd_rad3d_solveeq|, \\
 file \verb|rhd_shortrad_module.F90|:
  \verb|rhd_shortrad_operator|.

\item \verb|-DMSrad_raytas1=1|: Optimization: choose non-default version
  of \verb|SUBROUTINE raytas| in file \verb|MSrad3D.F90|.\index{MSrad}

\item \verb|-Drhd_shortrad_operator_l01=1|: Optimization: version of operator
  for short characteristics method\index{short characteristics}

\end{itemize}


\subsubsection{Linux: Intel Compiler}\index{Linux}\index{compiler!Intel}

First experiments with the
\htmladdnormallinkfoot{Intel compiler}{http://developer.intel.com/software/products/compilers/f50/linux/} for Linux
have been startet to compile COBOLD.
So far, the executable is able to read unformatted files in
\verb|little_endian|\index{littleendian@\verb/little_endian/} format only
(and of course all formatted UIO files).
The appropriate module is \verb|uio_mac_intel_module.f90|.
The compiler is called with \verb|ifc|.
Important switches are:

\begin{itemize}

\item \verb|-Vaxlib|: Link proper library to make the machine understand
  e.g.\ \verb|call flush(6)|.

\item \verb|-O3|: General optimization flag

\item \verb|-tpp6 -xK|: Optimization especially for Pentium~III
  (includes SSE vector commands).

\item \verb|-ip|: Optimization: activate interprocedural optimization within
  each source file. This enables inlining.\index{inlining!Intel compiler on Linux}

\item \verb|-Drhd_shortrad_dir1_l01=1|: Optimization:
  Transpose arrays and use routine \verb|rhd_shortrad_dir3| for rays in x1 direction.
  See Sect.~\ref{s:rhd_shortrad_dir1_l01}.

\end{itemize}


\subsubsection{SGI: Origin}\index{SGI}\index{compiler!SGI}

COBOLD has been compiled and tested on up to 8 processors on the
SGI~2000 machine at TAC in Copenhagen and the
\htmladdnormallinkfoot{SGI~3800 machine at the NSC}{http://www.nsc.liu.se/sgi3k/}
in Link{\"o}ping.
See e.g.\ the excellent
\htmladdnormallinkfoot{SGI Fortran90 manual}{http://techpubs.sgi.com/library/tpl/cgi-bin/init.cgi}
\begin{htmlonly}
\htmladdnormallink{(or here)}{http://techpubs.sgi.com:80/library/tpl/cgi-bin/browse.cgi?coll=0650\&db=bks\&cmd=toc\&pth=/SGI\_Developer/MPro7F90CD\_RM}
\end{htmlonly}.
Important switches are:

\begin{itemize}

\item \verb|-macro_expand|: Enable macro expansion

\item \verb|-mp|: Enable parallelization with OpenMP directives\index{OpenMP!on SGI}

\item \verb|-INLINE:aggressive=ON -INLINE:list -INLINE:preempt=ON|: General keywords
  for inlining\index{inlining!SGI}

\item \verb|-INLINE:must=...|: Optimization: Routines that should be
  inlined: \\
 file \verb|rhd_hyd_module.F90|: \verb|rhd_hyd_avg|,
  \verb|rhd_hyd_upwind|,
  \verb|rhd_hyd_pred0|,
  \verb|rhd_hyd_predm|,
  \verb|rhd_hyd_predp|,
  \verb|rhd_hyd_alpha|,
  \verb|rhd_hyd_constanteq|,
  \verb|rhd_hyd_minmodeq|,
  \verb|rhd_hyd_minmod|,
  \verb|rhd_hyd_vanleereq|,
  \verb|rhd_hyd_vanleer|,
  \verb|rhd_hyd_superbeeeq|,
  \verb|rhd_hyd_superbee|,
  \verb|rhd_hyd_ppeq|,
  \verb|rhd_hyd_pp|,
  \verb|rhd_hyd_hdflux|, \\
 file \verb|rhd_lhdrad_module.F90|:
  \verb|rhd_rad3d_raylhd|,
  \verb|rhd_rad3d_solve|,
  \verb|rhd_rad3d_solveeq|, \\
 file \verb|rhd_shortrad_module.F90|:
  \verb|rhd_shortrad_operator|.

\item \verb|-O3 -OPT:Olimit=0|: General optimization

\item \verb|-IPA:plimit=5500|: Even more optimization

\end{itemize}


\subsubsection{Sun: SunFire}\index{Sun}\index{compiler!Sun}

COBOLD has been used on the
SunFire machines``fire1'' and ``fire2'' in Uppsala with
compiler version ``Sun WorkShop 6 update 2 Fortran 95 6.2 2001/05/15''.
The previous version was not able to compile COBOLD properly.
Information about Fortran and the Sun compiler can be found on the
\htmladdnormallinkfoot{Sun Forte page}{http://www.sun.com/forte/fortran/}
under ``documentation''.
Important switches are:

\begin{itemize}

\item \verb|-openmp|: Enable OpenMP.\index{OpenMP!on Sun}

\item \verb|-fast -xvector=yes/no|: General optimization.
  On the Sun the \verb|-fast| option switches on more or less all optimization
  features of the compiler. That works reasonable well. However, during the
  compilation of \verb|gasinter_routines.f90| (and only there)
  the switch \verb|-xvector=no| is needed!

\item \verb|-inline=...|: Optimization: Routines that should be
  inlined\index{inlining!Sun}: \\
 file \verb|rhd_hyd_module.F90|: \verb|rhd_hyd_avg|,
  \verb|rhd_hyd_upwind|,
  \verb|rhd_hyd_pred0|,
  \verb|rhd_hyd_predm|,
  \verb|rhd_hyd_predp|,
  \verb|rhd_hyd_alpha|,
  \verb|rhd_hyd_constanteq|,
  \verb|rhd_hyd_minmodeq|,
  \verb|rhd_hyd_minmod|,
  \verb|rhd_hyd_vanleereq|,
  \verb|rhd_hyd_vanleer|,
  \verb|rhd_hyd_superbeeeq|,
  \verb|rhd_hyd_superbee|,
  \verb|rhd_hyd_ppeq|,
  \verb|rhd_hyd_pp|,
  \verb|rhd_hyd_hdflux|, \\
 file \verb|rhd_lhdrad_module.F90|:
  \verb|rhd_rad3d_raylhd|,
  \verb|rhd_rad3d_solve|,
  \verb|rhd_rad3d_solveeq|, \\
 file \verb|rhd_shortrad_module.F90|:
  \verb|rhd_shortrad_operator|.

\item \verb|-Drhd_shortrad_operator_l01=2|: Optimization:
  short characteristics operator with masks (weights).
  See Sect.~\ref{s:rhd_shortrad_operator_l01}.

\item \verb|-Drhd_shortrad_formal_l01=1|: Optimization:
  split loop for exp(-dtau) computation into two loops.
  See Sect.~\ref{s:rhd_shortrad_formal_l01}.

\item \verb|-Drhd_shortrad_dir1_l01=1|: Optimization:
  Transpose arrays and use routine \verb|rhd_shortrad_dir3| for rays in x1 direction.
  See Sect.~\ref{s:rhd_shortrad_dir1_l01}.

\item \verb|-Drhd_hyd_entropyfix_p01=1|: Optimization: version with masks (weights).
  See Sect.~\ref{s:rhd_hyd_entropyfix_p01}.

\end{itemize}

\index{compilation|)}


%==================================================================================================
\section{UIO Data Format\label{s:uio}}\index{UIO|(}\index{data format}


%--------------------------------------------------------------------------------------------------
\subsection{Quickstart: Introduction to UIO\label{s:quickstart_UIO}}

The UIO (``Universal Input Output'') routines are a set of routines in
Fortran90 and IDL to manage I/O of scalars, arrays and a certain table type.
Files can be formatted or unformatted.

The formatted (ASCII text) data representation is machine-independent and
appropriate for human reading.

The unformatted (binary) representation provides much faster I/O, gives
smaller files and the IEEE format is a quasi-standard among many
platforms/compilers.
On all platforms the native binary representation can be chosen.
On some machines additional
conversion types are offered (IEEE on most machines, CRAY format an CRAYs).

Files produced with UIO are not automatically readable on
all machines. But it is always possible to produce
(formatted) UIO files on a machine which are readable on all others.
And with some fiddling with compile options or the call of machine-specific
subroutines provided by the compiler vendor it was up to now always possible
to enable the access to binary UIO files on all machine tested.

Each file entry is a header-data-unit.
The header contains information on the one hand to identify the entry
and on the other hand to specify the format and size of the following data
block.
This data block usually consists of a scalar or an array. In some cases it
is empty (e.g.\ for labels) or it contains more complex information (for
tables).

The first version of UIO routines was written in FORTRAN77\index{Fortran}.
They still exist. But further development was done with the
Fortran90 versions.
Therefore, the use of the FORTRAN77 routines is not recommended anymore.
The current Fortran version of the UIO routines is a set of Fortran90 modules.

To allow a communication between Fortran and IDL\index{IDL} programs,
an IDL version of the UIO routines has been written.
The correspondence between Fortran and IDL routines
is rather close. But in detail, there are differences.
Currently, IDL Version~5.4 (sunos sparc) is used.
Amazingly, the UIO routines also used to work under {\em PV-WAVE\/} (Version~6.01
(sun4 solaris sparc)).
The UIO routines have been successfully compiled and used on
Cray, DECalpha, HP, Hitachi, Linux (with PGI and Intel compiler), SGI, and Sun
machines.

So far, there exist three UNIX shell scripts
(calling Fortran routines) useful to quickly examine
data sets or to change the format or conversion type of files.


%--------------------------------------------------------------------------------------------------
\subsection{Example of UIO Data File\label{s:fileexample}}

To give a first impression about the data structure,
here follows a simple test file\index{UIO!example}, which contains
the header, a label, a couple of scalars, an array, and a short table:

{\small \begin{verbatim}
fileform uio form=formatted convert=native version=0.1.1997.11.29 &
date='29.11.1997 21:23:39.835' system=IRIX machine=atlas osrelease=6.3 &
osversion=12161207 hardware=IP32 language=Fortran90 program=uiotst

label testdata n='sample test data field' date='29.11.1997 21:23:39.835'

integer ia f=I3 b=4 n='This is the answer'
 42
complex ca f='''('',E13.6,'','',E13.6,'')''' b=8 n='This is a complex answer'
( 0.400000E+01, 0.200000E+01)
real da f=E23.15 b=8 n='precise answer'
  0.420000000000000E+02
real answer f=F4.0 b=4 n=answer u=1
 42.

real real2d d=(100:103,200:204) f=E13.6 p=4 b=4
 0.100000E+01 0.200000E+01 0.300000E+01 0.400000E+01
 0.500000E+01 0.600000E+01 0.700000E+01 0.800000E+01
 0.900000E+01 0.100000E+02 0.110000E+02 0.120000E+02
 0.130000E+02 0.140000E+02 0.150000E+02 0.160000E+02
 0.170000E+02 0.180000E+02 0.190000E+02 0.200000E+02

table f77table d=(1:5,1:7) f=1X b=1 n='test table to test the table routines'
integer   int1  f=I5    b=4  n='Integer: 1. Spalte'
real      real1 f=F5.1  b=4  n='Real: 2. Spalte'
character char1 f=A16   b=16 n='Char: 3. Spalte'
real      real2 f=E13.6 b=4  n='Real: 4. Spalte'
integer   int2  f=I5    b=4  n='Integer: 5. Spalte'
 int1 real1            char1         real2  int2
    1   2.0 a                 0.100000E+02     1
    2   4.0 ab                0.200000E+02     2
    3   6.0 abc               0.300000E+02     3
    4   8.0 abcd              0.400000E+02     4
    5  10.0 abcde             0.500000E+02     5
    6  12.0 abcdef            0.600000E+02     6
    7  14.0 abcdefg           0.700000E+02     7
\end{verbatim} }


%--------------------------------------------------------------------------------------------------
\subsection{Structure of UIO Files}


%--------------------------------------------------------------------------------------------------
\subsubsection{Data Representation: ASCII or Binary\label{s:UIO_data_representation}}

While opening a file for writing, the file format
(``formatted''\index{formatted} or ``unformatted''\index{unformatted})
and the conversion type (``native'', e.g.\ ``ieee\_4'', \ldots) have to be
specified.

The {\em formatted\/} ASCII data representation allows I/O independent of platform or
compiler. It is useful for parameter files which can be read and edited
by hand, for the direct inspection of data, the transfer between very different
systems, or for the import of data which exist e.g.\ in a table format.
From the specified conversion type only the default output format for numbers
(e.g.\ ``E13.6'' for 4 byte reals) is determined.

The {\em unformatted\/} binary I/O is much faster and gives usually more compact
files with higher accuracy (ideally exact) in the numerical data representation.
But -- in principle -- the file format is machine dependent. 
Fortunately, the IEEE format turns out to become a quasi-standard among a
variety of machines. Most workstations work internally with this format.
Some CRAYS which have a different internal data representation allow the hidden
transformation between the internal and IEEE format during the I/O process.
The UIO routines support this feature of CRAY FORTRAN compilers by means of a
module (\verb|uio_mac_module|) individually designed for (two types of) CRAY
machines using certain CRAY specific system calls (CRAY FFIO assign logic).
Nevertheless, there is also a machine independent version of this module,
written completely in standard Fortran90 but providing less features
than the machine-dependent versions.

Besides the format the conversion type (see table~\ref{t:conversiontypes})
has to be specified.
The ``native'' conversion type is the internal binary data representation,
which is also standard for unformatted Fortran output. If this representation
happens to be conformal with the IEEE standard the conversion type
``ieee\_4'' should be used. It gives the same data format, but in the header
of the file the term ``convert=ieee\_4'' instead of ``convert=native''
describes the data format precisely -- in a way also understandable by other
machines.
On CRAY machines the native format is equal to the conversion type
``crayxmp\_8'', but also the conversion types ``ieee\_4'',
``ieee\_4\_limit'', and ``ieee\_8'' can be chosen.
The last three conversion types correspond to the CRAY internal types
``ieee\_32'', ``ieee\_dp'', and ``ieee\_64'', respectively.

On a machine with an internal data representation not within the list in
the existing \verb|uio_mac*_module.f90| files one could use the standard file
\verb|uio_mac_module.f90| and is restricted to the ``native'' conversion type.
But it is better to invent an appropriate name for the new data format and
to build a proper machine dependent UIO file, e.g.\ from
\verb|uio_mac_ieee_module.f90|.

\begin{table}[htb]
 \begin{center}
  \begin{tabular}{|lrrrl|} \hline
conversion type    & I & R & D & description \\ \hline
\verb|native|      & ? & ? & ? & internal data format on all machines \\
                   &   &   &   & (sometimes useful but not recommended) \\
\verb|ieee_4|      & 4 & 4 & 8 & standard IEEE \verb|big_endian| format (recommended)\index{bigendian@\verb/big_endian/} \\
\verb|ieeele_4|    & 4 & 4 & 8 & IEEE \verb|little_endian| format\index{littleendian@\verb/little_endian/} \\
\verb|ieee_8|      & 8 & 8 &16 & double precision IEEE \verb|big_endian| format \\
                   &   &   &   & (on some machines possible) \\
\verb|crayxmp_8|   & 8 & 8 &16 & CRAY internal data format \\
\verb|idl|         & 4 & 4 & 8 & IDL format (but IDL also supports \verb|ieee_4|) \\
\verb|xdr|         & 4 & 4 & 8 & format possible with IDL \\ \hline
\verb|ieee_4_limit|& 4 & 8 & 8 & standard IEEE format $\rightarrow$ \verb|ieee_4|\\
\verb|ieee|        & ? & ? & ? & IEEE format, unknown length (not recommended) \\ \hline
  \end{tabular}
\caption[Conversion types]{Conversion types with length of integers, single
precision reals, and double precision reals in bytes, and an explanation.
}\label{t:conversiontypes}
 \end{center}
\end{table}

Some attention has to be paid if weird compiler switches (as e.g.\ -r16 -i2)
are used to modify the accuracy and standard memory size of variables.

If an existing file is opened for reading, the file format and conversion type
are determined automatically from the file if the conversion type of the data
in the file is among the conversion types supported by the compiler.
If the file has a conversion type ``native'' but is created on a machine with
different internal data representation, the file header might be readable, but
an error will probably occur during the reading of a real variable.


%--------------------------------------------------------------------------------------------------
\subsubsection{Data File Structure}

The UIO routines only handle sequential files.
Each file consists of a list of entries. The first entry describes the file
format, conversion type, and the machine who is responsible for it. The
following entries contain data
(scalars and 1D \ldots 4D arrays of type integer, real (single \& double
precision), complex (single precision), character;
tables with columns of type integer, real (single precision), or character),
or structuring information (labels).

Each entry consists of the header and the (possibly empty) data block.

Each header is a list of at most 20 terms separated by blanks.
The first term is the entry type (see table~\ref{t:entrytypes}),
followed by an identifier. This identifier should follow the standard rules
for variables (small capital letters, numbers, underline; starting with letter),
a name as e.g.\ \verb|rho|, \verb|v_1|.
The rest of the terms come in the form ``keyword=value''.
See Tab.~\ref{t:headkeywords}.

\begin{table}[htb]
 \begin{center}
  \begin{tabular}{|ll|} \hline
entry type       & entry contents \\ \hline
\verb|fileform|  & file description (first entry) \\
\verb|integer|   & scalars, 1D \ldots 4D arrays \\
\verb|real|      & scalars, 1D \ldots 4D arrays, single \& double precision \\
\verb|complex|   & scalars, 1D \ldots 4D arrays, single precision \\
\verb|character| & scalars, 1D \ldots 4D arrays \\
\verb|table|     & table with integer, real, character columns \\
\verb|label|     & label entry for file structuring \\ \hline
  \end{tabular}
\caption[Entry types]{Entry types
}\label{t:entrytypes}
 \end{center}
\end{table}

\begin{table}[htb]
 \begin{center}
  \begin{tabular}{|llllll|} \hline
keyword & description    & example & descriptor&info.\ & necessary\\ \hline
b       & byte number    & 4       & format    &       & yes \\
d       & dimension      & (0:9)   & format    &       & yes (arrays) \\
ds      & dimension shift& (1:1)   &           & yes   & \\
f       & Fortran format & E13.6   & format    &       & yes \\
p       & values per line& 4       & format    &       & yes (arrays) \\
t       & transformation & log10   & format    &       & \\
n       & name           & density &           & yes   & \\
u       & unit           & g/cm**3 &           & yes   & \\
date    & date           & 1.1.98  &           & yes   & \\
c0\ldots9&comment        & Dichte  &           & yes   & \\ \hline
form    & file format    &formatted& file      &       & yes (file header) \\
convert & conversion     & ieee\_4 & file      &       & yes (file header) \\
version & version        & 0.1.1997.11.29 &    & yes   & \\
system  & system         & IRIX    &           & yes   & \\
machine & machine name   & atlas   &           & yes   & \\
osrelease&OS release     & 6.3     &           & yes   & \\
osversion&OS version     &12161207 &           & yes   & \\
hardware&machine hardware& IP32    &           & yes   & \\
language&program.\ language&Fortran90&         & yes   & \\
program & program        & uiotst  &           & yes   & \\ \hline
xyz\ldots&user defined   & source  &           & yes   & \\ \hline
  \end{tabular}
\caption[Header keywords]{Standard entry header keywords
}\label{t:headkeywords}
 \end{center}
\end{table}

A header line has a maximum length of 80~characters.
A continuation line is indicated by \verb*| &| at the end of the line.
A header consists of 20~lines at maximum.
It can be preceded by empty lines (except for the file header entry).
Example\index{UIO!example}:
{\small \begin{verbatim}
real time f=F9.2 b=4 n='Time' u=s c0='Simulation time in seconds' &
  c1='Time count starts at 0.0'
    12.34
\end{verbatim} }

The entry header is followed by the entry data block. This block is empty for
labels and the fileform entry but non-empty otherwise.

In an {\em unformatted\/} file each header line is an individual record
containing a string with exactly 80~characters.
The following data block (scalar or array) is one single record.

In a {\em formatted\/} file each header line is a string of at most 80~characters
delimited by a \verb|LINEFEED| of whatever the operating system decided to be
appropriate as \verb|EOL| character (sequence).
The following data block is written as sequence of lines.
The number of items per line is specified by the ``p=?'' keyword in the header.


%--------------------------------------------------------------------------------------------------
\subsubsection{Tables\label{s:uiotables}}

For a table the entry header is followed by a list of headers for the individual
table columns, a single table header line consisting of (abbreviations of)
the table entry identifiers and the table itself (see the example in
section~\ref{s:fileexample}).
The dimension keyword gives the number of columns and rows in the form
``d=(1:columns,1:rows)''.

The Holweger-M{\"u}ller-Atmosphere is chosen as the following
``real world'' example\index{UIO!example} for a file with a table in UIO format:
\begin{verbatim}
fileform uio form=formatted convert=ieee_4 version=0.0.1996.10.29 &
  date='20-Feb-1997 18:40:45' system=SunOS machine=saturn osrelease=4.1.3 &
  osversion=3 hardware=sun4m language='IDL 4.0' program='by hand'

character description d=(0:3) f=A80 p=1 b=80 d='13-Nov-1996 18:29:48'
Holweger-Mueller-Atmosphere,
Hartmut Holweger & Edith Mueller (1974) Solar Physics 39, 19-30, table II,
empirical solar temperature stratification to fit solar spectral lines and
limb darkening

character history d=(0:3) f=A80 p=1 b=80 d='13-Nov-1996 18:29:52'
Holweger-Mueller-Atmosphere, from 1974
uio-form:              13-Nov-1996 18:29:52
conversion type added: 20-Feb-1997 18:21:01
xi -> vmicro:          20-Feb-1997 18:23:43

real teff f=F6.1 b=4 n='effective temperature' u=K texa='T_{\rm eff}'
5780.0

table atmosphere d=(1:7,1:29) f=X b=1 n=Holweger-Mueller-Atmosphere &
c0='Hartmut Holweger & Edith Mueller (1974) Solar Physics 39, 19-30, table II' &
  c1=Teff(Sun)=5780K
real tauross f=E9.2 b=4 n='optical depth (Rosseland)' u=1
real tau5000 f=F7.3 b=4 n='optical depth (lambda5000)' u=1 t=log10
real t       f=F7.0 b=4 n=temperature u=K
real pgas    f=F6.3 b=4 n='gas pressure' u=dyn/cm^2
real pel     f=F6.3 b=4 n='electron pressure' u=dyn/cm^2
real vmicro  f=F4.2 b=4 n=microturbulence u=km/s
real q       f=F8.5 b=4 n='Hopf function' u=1 c0='q=((T(tau)/Teff)^4)/0.75)-tau'
  tauross tau5000       t   pgas    pel vmic        q
 2.00E-07  -6.539   3900.  0.769 -3.140 0.00  0.27637
 2.50E-07  -6.279   3920.  1.171 -2.752 0.00  0.28208
 5.00E-07  -5.868   3970.  1.598 -2.342 0.00  0.29675
 1.00E-06  -5.588   4030.  1.842 -2.105 0.00  0.31510
 2.00E-06  -5.334   4080.  2.042 -1.910 0.00  0.33103
 5.00E-06  -5.001   4160.  2.279 -1.674 0.00  0.35776
 1.00E-05  -4.747   4210.  2.450 -1.508 0.00  0.37527
 2.00E-05  -4.486   4270.  2.618 -1.341 0.00  0.39712
 5.00E-05  -4.131   4340.  2.835 -1.128 0.00  0.42377
 1.00E-04  -3.856   4400.  2.999 -0.967 0.50  0.44765
 2.00E-04  -3.577   4460.  3.162 -0.804 0.50  0.47248
 5.00E-04  -3.200   4530.  3.377 -0.596 0.50  0.50256
 1.00E-03  -2.912   4590.  3.541 -0.437 0.50  0.52925
 2.00E-03  -2.621   4640.  3.704 -0.279 0.50  0.55173
 5.00E-03  -2.233   4720.  3.919 -0.070 0.50  0.58792
 1.00E-02  -1.939   4800.  4.083  0.094 0.50  0.62415
 2.00E-02  -1.645   4900.  4.245  0.266 0.65  0.66867
 5.00E-02  -1.256   5080.  4.460  0.504 0.85  0.74558
 1.00E-01  -0.961   5260.  4.622  0.705 1.00  0.81447
 2.50E-01  -0.571   5560.  4.830  1.002 1.25  0.89163
 4.00E-01  -0.371   5850.  4.926  1.251 1.40  0.99911
 7.00E-01  -0.133   6260.  5.022  1.613 1.50  1.13453
 1.00E+00   0.019   6570.  5.070  1.879 1.60  1.22581
 1.50E+00   0.191   6880.  5.114  2.140 1.70  1.17659
 2.00E+00   0.312   7160.  5.140  2.363 1.80  1.13964
 4.00E+00   0.597   7920.  5.191  2.889 1.80  0.70033
 6.00E+00   0.761   8250.  5.213  3.092 1.80 -0.46595
 8.00E+00   0.877   8420.  5.229  3.196 1.80 -1.99552
 1.00E+01   0.967   8500.  5.242  3.245 1.80 -3.76404
\end{verbatim}


%--------------------------------------------------------------------------------------------------
\subsubsection{Recommendations for standard File Structure}

The very first entry in an UIO file is always the \verb|fileform uio| entry,
containing information about the file format and conversion type.
Afterwards, entries can follow in any order.
But it is perhaps a good idea to start the file with three special entries
(\verb|file_id|, \verb|description|, \verb|history|) as in
{\small \begin{verbatim}
fileform uio form=formatted convert=ieee_4 ...             

character file_id f=A80 b=80 n='File identification'                            
uio-demofile

character description d=(1:2) f=A80 p=1 b=80 n='File description'               
This is a file to demonstrate the recommended start entries for all
UIO files.

character history d=(1:1) f=A80 p=1 b=80 n='File history'
UIO demo file: 22-Dec-1997 14:15:15
\end{verbatim} }

A recommended format for sets of multi-dimensional arrays (e.g.\ hydrodynamics:
x-axis, y-axis, z-axis, density, velocities, energy, \ldots) is shown in
Sect.~\ref{s:modelfiles}.


%--------------------------------------------------------------------------------------------------
\subsection{Files \& Directories \& Paths}

All UIO-routines are located in subdirectories of a common directory (called
e.g.\ \verb|uio|), which also contains a Readme file.
The subdirectories and their contents are \\
\verb|bin     |: shell scripts: \verb|uiolook|, \verb|uiocat|, \verb|uioinfo| \\
\verb|f90     |: Fortran90 source codes, object files, executables \\
\verb|idl     |: IDL routines \\
\verb|man/man1|: manual pages for shell scripts: \verb|uiolook|, \verb|uiocat|, \verb|uioinfo| \\
\verb|tex     |: old description files in \LaTeX, the most recent version is part of this document \\

To use the UNIX scripts and the makefile
you need a global system variable {\bf UIOPATH} pointing to this directory.
The path to the shell scripts and to the man-pages should be added to your
shell path variables e.g. in one of the login scripts:

\mbox{ }

\noindent C-shell (\verb|.cshrc|):
\begin{verbatim}
# --- uio ---
setenv UIOPATH "${HOME}/uio"
setenv PATH "${PATH}:${UIOPATH}/bin"
setenv MANPATH "${MANPATH}:${UIOPATH}/man"
# --- *** ---
\end{verbatim}

\noindent Korn-shell (\verb|.kshrc|):
\begin{verbatim}
# --- uio ---
UIOPATH=$HOME/uio
export UIOPATH
PATH=$PATH:$UIOPATH/bin
export PATH
MANPATH=$MANPATH:$UIOPATH/man
export MANPATH
# --- *** ---
\end{verbatim}


%--------------------------------------------------------------------------------------------------
\subsection{Fortran90}\index{UIO!Fortran}\index{Fortran}


%--------------------------------------------------------------------------------------------------
\subsubsection{Files}

The Fortran UIO package is a collection of Fortran90 modules and programs described in
Table~\ref{t:fortranfiles}.

\begin{table}[hbt]
 \begin{center}
  \begin{tabular}{|ll|} \hline
File                              & contents \\ \hline
\verb|uio_base_module.f90|        & Collection of basic modules \\
\verb|uio_mac_module.f90|         & (Possibly) machine dependent routines \\
                                  & Standard version (all machines) \\
\verb|uio_mac_ieee_module.f90|    & Machine dependent routines: IEEE format \\
\verb|uio_mac_sun_module.f90|     & Machine dependent routines: Sun, SGI, Linux PGI \\
\verb|uio_mac_intel_module.f90|   & Machine dependent routines: Linux Intel \\
\verb|uio_mac_crayts_module.f90|  & Machine dependent routines: CRAY \\
\verb|uio_mac_crayxmp_module.f90| & Machine dependent routines: CRAY \\
\verb|uio_mac_decalpha_module.f90|& Machine dependent routines: DECalpha \\
\verb|uio_bulk_module.f90|        & Main part of UIO routines \\
\verb|uio_filedef_module.f90|     & Standard file descriptors and labels \\
\verb|uio_table_module.f90|       & Table manipulation routines \\ \hline
\verb|uio_var_module.f90|         & definition and handling of UIO flexible variable \\
\verb|uio_varfile_module.f90|     & definition and handling of file structure of \\
                                  & UIO flexible variables \\ \hline
\verb|uiocop.f90|                 & Program to copy and transform UIO files \\
\verb|uiolok.f90|                 & Program to look into UIO files \\
\verb|uioinf.f90|                 & Program to give information about conversion types \\
\verb|uiotst.f90|                 & Program to produce test UIO file \\ \hline
  \end{tabular}
\caption[UIO Fortran90 files]{UIO Fortran90 files
}\label{t:fortranfiles}
 \end{center}
\end{table}

The file \verb|uio_base_module.f90| contains the basic set of modules
(see Table~\ref{t:uiobasemodulef90}).

\begin{table}[hbt]
 \begin{center}
  \begin{tabular}{|ll|} \hline
module            & contents \\ \hline
uio\_cst\_module  & channel status information \\
uio\_cvl\_module  & convert type list of current machine \\
uio\_inf\_module  & information about environment \\
uio\_nam\_module  & definition of names \\
uio\_siz\_module  & string length, table size \\
uio\_base\_module & basic set of UIO-routines: string processing, \\
                  & header handling, I/O channel management \\ \hline
  \end{tabular}
\caption[Contents of uio\_base\_module.f90]{Contents of
uio\_base\_module.f90
}\label{t:uiobasemodulef90}
 \end{center}
\end{table}

The files \verb|uio_mac*_module.f90| contain (possibly) machine dependent
routines collected in the module uio\_mac\_module.

\begin{table}[hbt]
 \begin{center}
  \begin{tabular}{|ll|} \hline
routine     & purpose \\ \hline
uio\_getenv & Get information about environment \\
uio\_mkcvls & Make list with possible conversion types \\
uio\_uopen  & Open file with special handling for conversion type \\
uio\_uclose & Close file with special handling for conversion type \\ \hline
  \end{tabular}
\caption[Contents of uio\_mac\_module]{Contents of
uio\_mac\_module
}\label{t:uiobasemodule}
 \end{center}
\end{table}

It comes in various flavors.
The machine-independent version is
\verb|uio_mac_module.f90|
which can be used for first tests but does not provide all possible features.
Therefore, it should be discarded afterwards and replaced by a version more
suitable for the platform in use.
The file
\verb|uio_mac_ieee_module.f90|
is appropriate for all machines with IEEE \verb|big_endian|\index{bigendian@\verb/big_endian/}
binary format.
Additionally there exist files containing calls of machine library routines \\
\verb|uio_mac_crayts_module.f90|,
\verb|uio_mac_crayxmp_module.f90|,
\verb|uio_mac_sun_module.f90|.
These make it possible to write information about the platform in use into the
file header. The CRAY versions allow unformatted I/O in the CRAY specific
format and additionally (via the FFIO ASSIGN logic) in IEEE format.
The file
\verb|uio_mac_intel_module.f90|
is appropriate for all machines with IEEE \verb|little_endian|\index{littleendian@\verb/little_endian/}
binary format (and no mechanism for automatic conversion).

The main set of routines is contained in \verb|uio_bulk_module.f90| in the
module uio\_bulk\_module.

The three files \verb|uio_base_module.f90|, \verb|uio_mac_module.f90|, and
\verb|uio_bulk_module.f90| comprise the standard set of UIO routines.

Additionally there exists a file \verb|uio_table_module.f90| with the single
module uio\_table\_module
which permits the I/O and manipulation of a certain table format (see the
example in section~\ref{s:fileexample}).

The latest extension comes within the modules
\verb|uio_var_module.f90| and \verb|uio_varfile_module.f90|.
The module \verb|uio_var_module.f90| contains a type definition for a variable
(``uio flexible variable'')
of general type (i.e.\ it may be a scalar integer value or a 1D character
array or a 3D real array\ldots) together with some routines for the
basic handling of the variables
(I/O in UIO format, construction and modification of variables\ldots).
The module \verb|uio_varfile_module.f90| contains a type definition for
a file built of UIO flexible variables together with routines for the handling
of these files.


%--------------------------------------------------------------------------------------------------
\subsubsection{Use of UIO Modules in Fortran90}

To make the UIO routines available in a Fortran program
the appropriate modules have to be specified.
At maximum four modules play a role:
The \verb|uio_bulk_module| contains the main part of the UIO routines
(and also uses the relevant sub-modules). 
Instead of \verb|uio_bulk_module| the module \verb|uio_table_module| is used
if the UIO table routines are needed.
The modules \verb|uio_siz_module| and \verb|uio_nam_module| contain
specifications about the size of some arrays and the length of strings, and
the names of types and keywords, respectively.
A typical case for the use of UIO modules is
{\small \begin{verbatim}
use uio_bulk_module
use uio_siz_module
use uio_nam_module
\end{verbatim} }


%--------------------------------------------------------------------------------------------------
\subsubsection{Compiling and Makefiles}\index{makefile!UIO}\index{UIO!makefile}

There is a Makefile for the UIO routines.
For a certain platform it is necessary to change the name of the module
file with the machine dependent routines (\verb|uio_mac*_module.f90|).
For this purpose the environment variable \verb|UIOMAC| has to set to
name of the appropriate routine (see Sect.~\ref{s:directorystructure}).
Many compilers generate module information files with suffixes like
\verb|.M|, \verb|.mod|, or \verb|.kmo|. To clean up information files with
other suffixes, they have to be included in the cleaning step.

Calling examples:
\begin{verbatim}
make
make UIO
make UIO "F90FLAGS=-g"
make clean
make cleanall
make remove
make removeall
\end{verbatim}
A section of a typical makefile using the UIO routines may be
{\small \begin{verbatim}
...
# --- Compiler options ---
F90C=f90
F90FLAGS=
# --- Libraries ---
UIOMAC=uio_mac_sun_module
...
# --- Dependencies of exe-files on object files and libraries ---
test.exe: test.o
        $(F90C) $(F90FLAGS) -o ${@} \
          $(UIOPATH)/f90/uio_base_module.o $(UIOPATH)/f90/$(UIOMAC).o \
          $(UIOPATH)/f90/uio_bulk_module.o

test.o: $(UIOPATH)/f90/UIO test.f90
        $(F90C) -c $(F90FLAGS) \
          -M$(UIOPATH)/f90 \
        test.f90
...
# --- Dependencies on used modules ---
$(UIOPATH)/f90/UIO:
        cd ${UIOPATH}/f90 ; make UIO "F90FLAGS=${F90FLAGS}"
\end{verbatim} }


%--------------------------------------------------------------------------------------------------
\subsubsection{Sample Calls of Fortran UIO Routines}

The needed modules have to be declared by a \verb|use| statement like:
{\small \begin{verbatim}
use uio_bulk_module
\end{verbatim} }

In the initial phase of the program the UIO routine package has to
initialized by exactly one call of the \verb|uio_init| routine with the name
of the program as optional parameter:
{\small \begin{verbatim}
call uio_init(progrm='uiotst')
\end{verbatim} }
The internal list of logical I/O unit numbers may be changed with
calls of \verb|uio_chunit| and \verb|uio_chconv|.

A file can be opened for writing with
{\small \begin{verbatim}
file='test.txt'
form='formatted'   ! or: 'unformatted'
conv='ieee_4'      ! or: 'native', 'crayxmp_8',...
call uio_openwr(ncout, file, form=form,conv=conv)
\end{verbatim} }

Header and data block are written together with one command as e.g.\ in:
{\small
\begin{verbatim}
call uio_wr(ncout, time,       'time', name='time',    unit='s'     )
call uio_wr(ncout, rho(1:10),  'rho',  name='density', unit='g/cm^3')
\end{verbatim}}

There are two different routines to close a file after reading or writing.
A file opened for writing is closed by:
{\small \begin{verbatim}
uio_closwr(ncout)
\end{verbatim} }


To open a file for reading, only the file name has to specified. File form
and conversion type are determined automatically:
{\small \begin{verbatim}
file='test.txt'
call uio_openrd(ncin, file)
\end{verbatim} }

In contrast to the writing of an entry by one routine call the reading is
performed in two separate sub-steps for the header and the data part.
After the reading of the header e.g.\ with
{\small \begin{verbatim}
use uio_siz_module
use uio_nam_module
...
integer                                 :: ntt
character*(let)                         :: termt(2,nttmx)
...
call uio_rdhd(ncin, termt,ntt)
\end{verbatim} }
the identifier, type, and dimension (if any)
of the entry is contained in the character array \verb|termt| with \verb|ntt| entries
and special actions may be taken: The data part may be skipped with
{\small \begin{verbatim}
uio_skipda(ncin, termt,ntt)
\end{verbatim} }
or it can be read with:
{\small \begin{verbatim}
call uio_rd(ncin, termt,ntt, time, ident)
\end{verbatim}}
If the entry is an array it may be necessary to allocate memory:
{\small \begin{verbatim}
call uio_exkeyw(termt,ntt,  dimna,dimstr)
call uio_st2dim(dimstr, ilow, iup, ndim=ndim)
allocate(rho(ilow(1):iup(1)))
call uio_rd(ncin, termt,ntt, rho, ident, ilb=ilow(1:1))
\end{verbatim}}

Alternatively, it is possible to search in the file for a special entry or
to search in an specially generated entry list with:
{\small \begin{verbatim}
call uio_srhd(ncin, termt,ntt, type='real',ident='rho',outstr=outstr,ierr=ierr)
\end{verbatim}}

Additionally, the module \verb|uio_var_module| makes it possible to read any
entry into an UIO flexible variable,
and the module \verb|uio_varfile_module| allows the reading of a complete file
into a special file structure of UIO flexible variables.

To close file after reading use
{\small \begin{verbatim}
uio_closrd(ncin)
\end{verbatim} }

There are several examples of programs with UIO routines like
\verb|uio_var_test.f90|,
\verb|uio_varfile_test.f90|,
\verb|uiotst.f90|,
(\verb|uio_demo.f90|).


%--------------------------------------------------------------------------------------------------
\subsection{UNIX Scripts\label{s:uioscripts}}\index{UIO!Unix scripts}

So far, there exist three UNIX shell scripts useful
to quickly examine data sets (\verb|uiolook|),
to change the format or conversion type of files (\verb|uiocat|),
or to print some information about the conversion types possible on the local
machine (\verb|uioinfo|).


%--------------------------------------------------------------------------------------------------
\subsubsection{Quick Examination of Files: uiolook}\index{uiolook@\verb/uiolook/}

The shell script \verb|uiolook| calls the Fortran program \verb|uiolok.f90|. The man-page:
{\small \begin{verbatim}
UIOLOOK(1V)       Misc. Reference Manual Pages        UIOLOOK(1V)

NAME
     uiolook - print entry headers of file in uio form

SYNOPSIS
     uiolook [ -h ] [ -p ] [ filename ...  ]

AVAILABILITY

DESCRIPTION
     The routine uiolook reads each filename (file in  uio  form)
     in  sequence  and  displays  the  headers  of the entries in
     pretty form.

OPTIONS
     -h    Print usage of uiolook.

     -p    Entry header keywords in (long) pretty form

SunOS 5.5.1       Last change: 27 November 1996                 1
\end{verbatim} }


%--------------------------------------------------------------------------------------------------
\subsubsection{Transformation of Files: uiocat}\index{uiocat@\verb/uiocat/}

The shell script \verb|uiocat| calls the Fortran program \verb|uiocat.f90|. The man-page:
{\small \begin{verbatim}
UIOCAT(1V)        Misc. Reference Manual Pages         UIOCAT(1V)

NAME
     uiocat - concatenate file(s) in uio form

SYNOPSIS
     uiocat [ -c conversion ] [ -f format ] [ -h ] [ -l  copylist
     ] [ -o outputfilename ] [ filename ...  ]

DESCRIPTION
     The routine uiocat reads each filename (file in uio form) in
     sequence  and  displays  its  contents formatted on standard
     output or writes it into a file.  In  the  latter  case  the
     format  change  from  'formatted'  to  'unformatted' or vice
     versa is possible.

OPTIONS
     -c    Conversion  type:  'native',  'ieee_4',  ...  (machine
          dependent),  its  specification is only relevant, if an
          output file is specified with the -o option and  output
          format='unformatted'.

     -f    Output  format:  'formatted'  or  'unformatted'.   Its
          specification  is  only  relevant, if an output file is
          specified with the -o option.

     -h    Help: print usage of uiocat.

     -l    List of entries to be copied. E.g.
            uiocat ... -l"real rho"
            uiocat ... -l"real rho,integer i"
            uiocat ... -l"label *,real rho,integer i"
            uiocat ... -l"label *,real rho,* i"
            Here, copylist is a list, separated by ",". Each item
          consists of exactly two items, separated by a blank. No
          additional blanks are allowed.  Use copylist with "" as
          above.

     -o    Output file name. If omitted, standard output is  used
          and "-c" and "-f" are meaningless.

SunOS 5.5.1       Last change: 12 January 1998                  1
\end{verbatim} }


%--------------------------------------------------------------------------------------------------
\subsubsection{Information about Conversion Types: uioinfo}\index{uioinfo@\verb/uioinfo/}

The shell script \verb|uioinfo| calls the Fortran program \verb|uioinf.f90|. The man-page:
{\small \begin{verbatim}
uioinfo(1V)       Misc. Reference Manual Pages        uioinfo(1V)

NAME
     uioinfo - print machine dependent information

SYNOPSIS
     uioinfo

DESCRIPTION
     The routine uioinfo prints information about its environment
     and a list of possible conversion types.

OPTIONS

SunOS 5.5.1       Last change: 12 January 1998                  1
\end{verbatim} }


%--------------------------------------------------------------------------------------------------
\subsection{IDL Routines}\index{IDL!UIO routines}\index{UIO!IDL}

The UIO package in IDL comes as a list of routines with names quite similar to
the Fortran90 version. Instead of using global variables as in Fortran90
there are now common blocks in Include-files.
{\small \begin{verbatim}
;******************************************************************************
; Routines, functions : uio_*.pro:
;               (!: most important, +: user-routine, -: comfortable, .:useful) 
; . adkey1:     Add one keyword to term table, keyword-value=' ', no link character
; . adkey2:     Add one keyword to term table with keyword-value
; . adkey3:     Add one keyword to term table with keyword-value or default
; . chconv:     Actualize list of conversion types for all channels
; + chpos:      Give current file position or jump to specified position
; . chunit:     Initialize, store and actualize a list of free and occupied unit
;               numbers
; + closrd:     Close file after reading
; + closwr:     Close file after writing
; - cpentr:     Copy entry from one file to another
; + d:          Read data from uio-file(s) in quasi direct access mode
; + data:       Handle uio-file(s) in quasi direct access mode
; ! dataset_rd: Read uio file and put data into anonymous structure
; ! uio_datasetlist_rd: Read data from list of files and put it into an. structure
;   deform:     Determine the default output format for numbers
;   dim2st:     Compose dimension string
; . exkeyw:     Extract value of keyword from table
;   ex1trm:     Extract one term from the input line
;   exmtrm:     Transform a list of items into its components
; . filcon:     Determine file contents: list of all entries with its positions
;   getenv:     Get information about environment
; ! init:       Initialization procedure for input/output routines
;   me1trm:     Merge the input term: 'keyword', 'value' -> 'keyword=value'
;   memtrm:     Merge a list of terms (keywords and their values) into a line table
;   mkcvls:     Make list with possible conversion types
; . nc2nt:      From column number or entry name find table entry number
; + openrd:     Open file for reading, read header
; + openwr:     Open file for writing, write header
; - pptrmt:     Print term table in pretty form
;   qmaadd:     Transform a string into a string with quotation marks if necessary
;   qmadel:     Parse string "inline" and remove quotation marks if necessary
; + rd:         Reading scalar and array data of all types
; . rdfifo:     Read file header
; + rdhdex:     Read header of variable and extract keywords
;   rdhead:     Read header
; + rdlabl:     Read label
; + rdtab:      Read table of integer, real, and/or character data from file
; + skipda:     Skip data block
; - slhdex:     Search header of variables given by list and extract keywords
; . st2dim:     Parse dimension string
; ! struct_rd:  Read uio file and put data into anonymous structure
; . tab0:       Create empty table structure
; + tabc:       Change and modify table contents: rearrange lines.
; + tabm:       Merge two tables in different ways
; + tabr:       Read 1d array from 2d table array (all types)
; + tabw:       Write 1d array into table (all types)
;   uclose:     Close file with special handling for conversion type
;   uopen:      Open file with special handling for conversion type
;   vnanrm:     Transform a string to give a correct name of a variable
;   wf2rf:      Produce from write format string corresponding read format string
; + wr:         Writing scalar and array data of all types
; . wrfifo:     Write file header
;   wrhdme:     Write header of variable, input: term table.
;   wrhead:     Write header of variable, input: line table.
; + wrlabl:     Write label
; + wrtab:      Write table of integer, real, and/or character data to file
;******************************************************************************
; Include-Files uio_*.pro:
;   filedefinc: 
;   uiocstinc:  channel status information (common uio_chainf)
;   uiocvlinc:  convert type list of current machine (common uio_cvlist)
;   uionaminc:  names of types, keywords, identifiers; default formats
;               (common uio_defnam)
;   uiosizinc:  length of strings, size of tables (trmtab, lintab)
;   uiotabinc:  empty table structure (common uio_taborg)
;******************************************************************************
\end{verbatim}}

Most of the routines are low-level ones and do not have to be worried about
because they rarely will be used directly.

For accessing data in UIO format within IDL
the initialization routine \verb|uio_init| (see Sect.~\ref{s:uio_init})
and the high-level reading routines (\verb|uio_struct_rd.pro|, \verb|uio_dataset_rd.pro|, and
\verb|uio_datasetlist_rd.pro|, see Sect.~\ref{s:uio_dataset_rd}).
might suffice.


%--------------------------------------------------------------------------------------------------
\subsubsection{Initialization of UIO Routines under IDL\label{s:uio_init}}\index{IDL!uioinit@\verb/uio_init/}

The directory containing the IDL UIO routines should be added to the
IDL variable !PATH.
This could be done by a program segment in the startup procedure, like:
{\small \begin{verbatim}
; --- Try to determine language ---
if (n_elements(!X.TICKV) eq 150) then langua='WAVE' else langua='IDL'
;
; --- Add user IDL directory to search path ---
if (langua eq 'IDL') then begin &$
  addpath=expand_path('+$UIOPATH/idl') &$
endif else begin &$
  addpath='/home/supas024/uio/idl' + ':' + '/home/supas024/wave' &$
endelse
if strtrim(addpath,2) ne '' then !path=addpath+':'+!path
delvar, addpath
\end{verbatim} }
It is reasonable to include the UIO initialization in the startup procedure
as e.g.:
{\small \begin{verbatim}
; --- Initialize uio-routines ---
uio_init, progrm='by hand'
\end{verbatim} }

IDL can handle the conversion types
\verb|native|, \verb|ieee_4|, \verb|ieeele_4|, \verb|ieee|, \verb|idl|, \verb|xdr|.
Here, \verb|ieee_4| is the default and should be used as a standard.

{\bf Attention}: The IDL type ``long'' corresponds to the standard Fortran type
``integer''. The IDL types ``byte'' and ``integer'' are not known in standard
Fortran and are therefore transformed to the IDL type ``long'' before writing
(in the IDL routine \verb|uio_wr|).

{\bf Be aware of}: The parsing and interpretation of the entry headers can only
be done by scalar operations which are comparatively slow in IDL.


%--------------------------------------------------------------------------------------------------
\subsubsection{Reading Data with uio\_data.pro}\index{IDL!uiodata@\verb/uio_data/}


The IDL routine \verb|uio_data| and the IDL function \verb|uio_d| were
the first set of ``high-level'' routines to read UIO data in IDL.
They were useful for the easy reading of not too complex data files.
By now, they are replaced by the routines \verb|uio_struct_rd|
and \verb|uio_dataset_rd| (see see next Section and Sect~\ref{s:IDL}).

The old routines allow the opening:
{\small \begin{verbatim}
  uio_data, mode='open', filename='model.dat'
  uio_data, mode='open', filename='model*.txt'
  uio_data, mode='open', filename='model.dat', family='mod1'
  uio_data, mode='open', filename='model*.txt', family='mod2'
\end{verbatim} }
\noindent examination:
{\small \begin{verbatim}
  uio_data, mode='content'
  uio_data, mode='files'
\end{verbatim} }
\noindent reading:
{\small \begin{verbatim}
  uio_data, mode='read', value=rho, 'rho'
  uio_data, value=temp, 'temp'
  uio_data, value=p, 'p', filename='model.dat'
  uio_data, value=p, 'p', family='mod1'
  plot_oi, uio_d('p'), uio_d('t')
\end{verbatim} }
\noindent and closing:
{\small \begin{verbatim}
  uio_data, mode='close', filename='model.dat'
  uio_data, mode='close', filename='model*.txt'
  uio_data, mode='close', family='mod2'
  uio_data, mode='allclose'
\end{verbatim} }
\noindent of UIO files.


%--------------------------------------------------------------------------------------------------
\subsubsection{Reading Data with uio\_dataset\_rd.pro\label{s:uio_dataset_rd}}\index{IDL!uiodatasetrd@\verb/uio_dataset_rd/}

For a detailed description of how to handle UIO files in IDL see Sect~\ref{s:IDL}.

With the new IDL routines \verb|uio_struct_rd.pro|, \verb|uio_dataset_rd.pro|, and
\verb|uio_datasetlist_rd.pro|
files are not read entry by entry anymore but in larger blocks (or ``data sets'').

With \verb|uio_struct_rd|\index{uiostructrd@\verb/uio_struct_rd/}
all entries in a file are read and put into an
IDL structure variable. This is appropriate for the COBOLD parameter file\index{rhd.par!reading in IDL}
or for the UIO table file in Sect.~\ref{s:uiotables}, e.g.
\begin{verbatim}
  par=uio_struct_rd('st35gm04n05_03.par')
  atm=uio_struct_rd('holmu.atm')
\end{verbatim}

When groups of entries in an UIO file are properly marked with
\verb|label dataset| and \verb|label enddataset| delimiters
(confer the example in Sect.~\ref{s:modelfiles})
each group can be accessed with \verb|uio_dataset_rd|\index{uiodatasetrd@\verb/uio_dataset_rd/}.
The first block can be read with
\begin{verbatim}
  ful=uio_dataset_rd('st35gm04n05_03.full')
\end{verbatim}
or
\begin{verbatim}
  ful=uio_dataset_rd('st35gm04n05_03.full', ndataset=0)
\end{verbatim}
Dataset number \verb|i+1| (counting starts at zero) can be read with
\begin{verbatim}
  ful=uio_dataset_rd('st35gm04n05_03.full', ndataset=i)
\end{verbatim}
If a dataset with that number does not exist, an empty structure is returned.
In this case, when called with additional keywords like
\begin{verbatim}
  ful=uio_dataset_rd('st35gm04n05_03.full', ndataset=i, outstr=outstr,ierr=ierr)
\end{verbatim}
an error message is returned in \verb|outstr| and \verb|ierr| is set to a value
larger than $0$.

To read all entries in a list of files in sequence the routine
\verb|uio_datasetlist_rd.pro|\index{uiodatasetlistrd@\verb/uio_datasetlist_rd/}
is convenient, as in
{\small \begin{verbatim}
model='st33gm06n03' & modelident='_??' & parmodelident='_01'
modeldisk=getenv('HOME') + '/dat/rhd/d' + model + '/'
;
modelfile=modeldisk + model + modelident    + '.full'
parfile  =modeldisk + model + parmodelident + '.par'
;
; --- Read parameter file ---
par=uio_struct_rd(parfile)
;
; --- Open first dataset to get some information about array sizes ---
delvar, listdata
ful=uio_datasetlist_rd(modelfile, listdata=listdata, ierr=ierr)
uio_closrd, listdata.channel
delvar, listdata
;
nxc1=n_elements(ful.z.xc1)
nxc2=n_elements(ful.z.xc2)
nxc3=n_elements(ful.z.xc3)
;
n_timestep=1000  ; --- Some huge value to get everything. Reduce for tests! ---
ierr=0
i=0
;
; --- Loop over all datasets ---
while ((ierr eq 0) and (i lt n_timestep)) do begin &$
  ; --- Read the next dataset ---
  ful=uio_datasetlist_rd(modelfile, listdata=listdata, ierr=ierr) &$
  if (ierr eq 0) then begin &$
    print, '--- ', i, ful.z.itime, ful.z.time, format='(A,I4,I6,E15.8)' &$
    ;
    ; --- Now do the data handling (demo) ---
    print, 'Mean density: ', avg(ful.z.rho) &$
    ;
    i=i+1 &$
  endif &$
endwhile
\end{verbatim}}
\noindent Note that you can specify an entire group of files with \verb|modelident='_??'|.

\index{UIO|)}


%==================================================================================================
\section{Control and Data Files}

Table~\ref{t:allfiles} shows a list of all files necessary to run COBOLD.
Executing the makefiles produces an executable \verb|rhd.exe|.
Its name can of course be changed afterwards.
The names of the three control files \verb|rhd.par|, \verb|rhd.stop|, and \verb|rhd.cont|
cannot be changed (without modification of the source code).
The names of EOS, opacity, and COBOLD data files can be chosen freely in the
parameter file \verb|rhd.par|.\index{rhd.par}
Table~\ref{t:allfiles} only contains dummy names.

\begin{table}[htb]
 \begin{center}
  \begin{tabular}{|lcll|} \hline
File     & \negsp I/O \negsp & Type                  & Description \\ \hline
\verb|rhd.exe|   &     & executable              & main program \\ \hline
\verb|rhd.par|   &  I  & control/data: UIO\negsp & central control file \\
\verb|rhd.stop|  &  I  & control                 & file to force controlled stop of simulation \\
\verb|rhd.cont|  &  I  & control                 & file to force continuation after stop \\ \hline
\verb|data.eos|  &  I  & data: UIO               & tabulated equation of state \\
\verb|data.opta| &  I  & data                    & tabulated opacities         \\ \hline
\verb|rhd.sta|   &  I  & data: UIO               & start model (e.g.\ end model of previous simulation) \\
\verb|rhd.end|   &  O  & data: UIO               & end model \\
\verb|rhd.full|  &  O  & data: UIO               & sequence of (2D or 3D) snapshots, typically large \\
\verb|rhd.mean|  &  O  & data: UIO               & sequence of derived data: mean flux, surface intensity\negsp \\
\verb|rhd.out|   &  O  & data                    & human readable text output \\ \hline
  \end{tabular} 
  \caption[Control and data files]{List of all control and data files
     }\label{t:allfiles}
 \end{center}
\end{table}


%--------------------------------------------------------------------------------------------------
\subsection{Model Files: sta, end, full files\label{s:modelfiles}}

If the UIO scripts (Sect.~\ref{s:uioscripts}) are properly installed,
you can view the contents (more precisely the headers of the data entries) of an UIO file
with \verb|uiolook filename|, e.g.\
\begin{verbatim}
uiolook st35gm04n05_03.end
\end{verbatim}
gives the output (slightly edited)
{\small \begin{verbatim}
----------------------------------------------------------------------------------
fileform uio form=unformatted convert=ieee_4 version=0.1.2000.11.26 &           
  date='02.01.2002 16:17:26.036' system=craSHi machine=craSHi osrelease=10.0.0.6 &
  osversion=UoK.4 hardware='CRAY SV1' language=Fortran90 program=RHD              

character file_id f=A8 b=8 n='File identification'                              
character description d=(1:1) f=A24 p=1 b=24 n='File description'               
character history d=(1:20) f=A80 p=1 b=80 n='File history'                      
character version f=A80 b=80 n='Program version'                                

label dataset n='RHD model' date='02.01.2002 16:17:26.043'                      
  character dataset_id f=A10 b=10 n='Type of box hierarchy'                       
  real modeltime f=E13.6 b=4 n=time u=s                                           
  integer modelitime f=I11 b=4 n='time step number' u=1                           
  real dtime f=E13.6 b=4 n='time step' u=s                                        
  real time_out_full_last f=E13.6 b=4 n='Time of last output of full model' u=s   
  real time_out_mean_last f=E13.6 b=4 n='Time of last output of averaged data' &  
    u=s                                                                             
  label box date='02.01.2002 16:17:26.049'                                        
    character box_id f=A80 b=80 n='Block identification'                            
    integer dimension d=(1:2,1:3) f=I7 p=6 b=4                                      
    real time f=E13.6 b=4 n=time u=s                                                
    integer itime f=I11 b=4 n='time step number' u=1                                
    real xc1 d=(-63:63,-63:-63,-63:-63) f=E13.6 p=4 b=4 &                           
    n='x1 coordinates of cell centers' u=cm ds=(0:0,0:1,0:1)                        
    real xc2 d=(-63:-63,-63:63,-63:-63) f=E13.6 p=4 b=4 &                           
      n='x2 coordinates of cell centers' u=cm ds=(0:1,0:0,0:1)                        
    real xc3 d=(-63:-63,-63:-63,-63:63) f=E13.6 p=4 b=4 &                           
      n='x3 coordinates of cell centers' u=cm ds=(0:1,0:1,0:0)                        
    real xb1 d=(-63:64,-63:-63,-63:-63) f=E13.6 p=4 b=4 &                           
      n='x1 coordinates of cell boundaries' u=cm ds=(0:1,0:1,0:1)                     
    real xb2 d=(-63:-63,-63:64,-63:-63) f=E13.6 p=4 b=4 &                           
      n='x2 coordinates of cell boundaries' u=cm ds=(0:1,0:1,0:1)                     
    real xb3 d=(-63:-63,-63:-63,-63:64) f=E13.6 p=4 b=4 &                           
      n='x3 coordinates of cell boundaries' u=cm ds=(0:1,0:1,0:1)                     
    real rho d=(-63:63,-63:63,-63:63) f=E13.6 p=4 b=4 n=Density u=g/cm^3            
    real ei d=(-63:63,-63:63,-63:63) f=E13.6 p=4 b=4 n='Internal energy' u=erg/g    
    real v1 d=(-63:63,-63:63,-63:63) f=E13.6 p=4 b=4 n='Velocity 1' u=cm/s          
    real v2 d=(-63:63,-63:63,-63:63) f=E13.6 p=4 b=4 n='Velocity 2' u=cm/s          
    real v3 d=(-63:63,-63:63,-63:63) f=E13.6 p=4 b=4 n='Velocity 3' u=cm/s          
  label endbox                                                                    
label enddataset date='02.01.2002 16:17:43.322'                                 
----------------------------------------------------------------------------------
\end{verbatim}}

The UIO format is described in some detail in Sect~\ref{s:uio}.
Each entry has a type (e.g.\ ``\verb|label|'', ``\verb|real|'', ``\verb|character|''),
an identifier (e.g.\ ``\verb|box|'', ``\verb|time|'', ``\verb|description|''),
and additional information about array size (e.g. ``\verb|d=(-63:63,-63:63,-63:63)|''),
data format (e.g.\ ``\verb|f=E13.6 p=4 b=4|''),
and properties of the quantity (e.g.\ ``\verb|n=Density u=g/cm^3|'').

Each start (``\verb|rhd.sta|'') or final (``\verb|rhd.end|'') model file has a structure
as shown above. The (``\verb|rhd.full|'') file usually contains a sequence of these
data sets, which of course can also be used as start model of a simulation.


%--------------------------------------------------------------------------------------------------
\subsection{File with additional Data: mean file\label{s:meanfiles}}

A ``\verb|rhd.mean|'' file has more entries than a full model file
which are much smaller.
Its format is usually Fortran ``unformatted'' (binary).

A mean file usually consists of several datasets. The overall structure is
{\small \begin{verbatim}
fileform uio form=unformatted convert=ieee_4

character file_id f=A8 b=8 n='File identification'                              
character description d=(1:1) f=A14 p=2 b=14 n='File description'               
character history d=(1:20) f=A80 p=1 b=80 n='File history'                      
character version f=A80 b=80 n='Program version'                                

label dataset n='RHD model'
...
label enddataset

label dataset n='RHD model'
...
label enddataset
.
.
.
\end{verbatim}}
\noindent Each dataset has the following structure (for a supergiant simulation):
{\small \begin{verbatim}
label dataset n='RHD model' date='25.05.2001 09:41:29.405'
...

label box date='25.05.2001 09:41:29.408'
character box_id f=A80 b=80 n='Block identification'
rad
...
label endbox

label box date='25.05.2001 09:41:29.983'
character box_id f=A2 b=2 n='Block identification'
z1
...
label endbox

label box date='25.05.2001 09:41:30.078'
character box_id f=A2 b=2 n='Block identification'
z2
...
label endbox

label box date='25.05.2001 09:41:30.170'
character box_id f=A2 b=2 n='Block identification'
z3
...
label endbox

label box date='25.05.2001 09:41:30.260'
character box_id f=A1 b=1 n='Block identification'
r
...
label endbox

label box date='25.05.2001 09:41:30.359'
character box_id f=A80 b=80 n='Block identification'
z
...
label endbox
label enddataset date='25.05.2001 09:41:30.489'
\end{verbatim}}
\noindent There a six sub-blocks delimited with \verb|box| and \verb|endbox| labels.
They contain
surface intensity and flux arrays (\verb|rad|),
averages in
the 23-plane (\verb|z1|),
the 13-plane (\verb|z2|),
the 12-plane (\verb|z3|),
and over spherical shells (\verb|r|),
and a 2D slice through the model (\verb|z|).


%--------------------------------------------------------------------------------------------------
\subsection{Parameter File: rhd.par file}\index{rhd.par|(}

The parameter file \verb|rhd.par| also has the UIO format.
But it will be usually Fortran ``formatted'' (ASCII).

It contains a list of parameter entries.
which are collected in groups to make it easier to find an entry.
Otherwise, the order is arbitrary (except for the very first \verb|fileform uio| entry).
If there are more than one entry with the same name, the first occurence
will be used by COBOLD.
But the doubling of entries is strongly discouraged because it will almost certainly
lead to confusion at some time. In addition, the IDL routine to read the parameter
file will fail with an error message.

Additional entries can be added if the names differ from the standard ones
described below.
Theses entries will be ignored by COBOLD but read by the IDL input routine.
They can be used to provide comments, additional information about the model,
or control parameters for further processing.


%--------------------------------------------------------------------------------------------------
\subsubsection{Quickstart: How to make a proper Parameter File\label{s:quickstart_parameterfile}}

You will never write a new parameter file from scratch.
Typically, you take an old file (e.g.\ the one controlling the
simulation which produced the model which is used to start the
new run) and edit it:

\begin{enumerate}

\item Take the parameter file corresponding to the model you want
  the new simulation to start with.

\item Most of the parameters should be already OK.
  E.g.\ most of the parameters controlling the boundaries do not have
  to be changed.

\item Write a brief description of the purpose of the planned simulation
  into the \verb|character description| array.
  You might but a remark about the parent file of the parameter file under construction
  and the current date
  into the \verb|character history| array.

\item Check/modify the name of start model and output files:
  \verb|infile_start|, \verb|outfile_end|, \verb|outfile_full|, \verb|outfile_mean|.
  On a system with batch queue this has not to be done in the parameter
  file itself but in the external command file.

\item Check/modify the fundamental parameters
 \begin{itemize}
  \item effective temperature control (\verb|s_inflow|, \verb|teff|, \verb|C_radHtautop|)
  \item gravity (\verb|grav_mode|, \verb|grav|, \verb|mass_star|, \ldots)
  \item abundances (\verb|eosfile|, \verb|opafile|)
 \end{itemize}

\item If the gravity of the new model (and therefore the characteristic time scale)
  significantly deviates from the old one,
  the time specifications controlling the output frequency
    (\verb|dtime_out_full|, \verb|dtime_out_mean|),
  the total length of the simulation
    (if specified as stellar time: \verb|endtime|, \verb|plustime|), and
  absolute boundaries/specifications for the time step
    (\verb|dtime_min|, \verb|dtime_min_stop|, \verb|dtime_max|, \verb|dtime_start|)
  have to be scaled.
  Look for parameters with units \verb|u=s|.

\item The rest of the parameters controls additional details.
  Most of the constants are specified in dimensionless form and keep
  their value in a class of related simulations.
  The previously used values will probably be reasonable for the new simulation, too.

\end{enumerate}


%--------------------------------------------------------------------------------------------------
\subsubsection{Header}\index{rhd.par!header}

The header of the parameter file contains information about the file format
and contents.
The \verb|description| array can be used to specify the goal
of the simulation, special model characteristics, or important parameter
changes compared to a previous or standard model.
The history array may contain the predecessor of the parameter file
to simplify a tracing of parameter changes.


\begin{itemize}

\item \verb|fileform uio|:\index{rhd.par!fileform uio@\verb/fileform uio/} \\
The header of the parameter file, e.g.\
\begin{verbatim}
fileform uio form=formatted convert=ieee_4  date='01.01.2002' &
  program='by hand'
\end{verbatim}
can be abbreviated to
\begin{verbatim}
fileform uio form=formatted convert=ieee_4
\end{verbatim}
which indicates that the file is in UIO form and Fortran ``formatted'' (ASCII).
The specification of the conversion type (``\verb|convert=ieee_4|'') is
more relevant for unformatted files.
These terms should not be changed.
But it can be of interest to append e.g.\ the date of the last
modification (e.g.\ ``\verb|date='01.01.2002'|'').

\item \verb|character file_id|:\index{rhd.par!character fileid@\verb/character file_id/} \\
The file identification string
\begin{verbatim}
character file_id  f=A80 b=80  n='File identification'
rhd-parameter
\end{verbatim}
indicates the intended use of the file as parameter file for the RHD code COBOLD.
Do not edit!

\item \verb|character description|:\index{rhd.par!character description@\verb/character description/} \\
The header of the file can (should) contain a short description
of the simulation, as in e.g.\
\begin{verbatim}
character description  d=(1:4) f=A80 p=1 b=80  n='File description'
Parameter file for RHD code:
Full size 3D Betelgeuse model: 5 M_Sun, 650 R_Sun
Start with st35gm04n03_09.end (127^3 -> 171^3)
Run with SHORTrad
\end{verbatim}
This entry is optional (it can be omitted completely) but it is
recommended to put at least some relevant keywords into this array.
If you change the number of lines (between 1 and 20) you have to
adjust the size specification (``\verb|d=(1:4)|'' in the example above).


\item \verb|character history|:\index{rhd.par!character history@\verb/character history/} \\
The file history has a similar purpose as the previous entry.
It can be used to keep information about the ``parent'' parameter file, as in
\begin{verbatim}
character history  d=(1:2) f=A80 p=1 b=80  n='File history'
Taken from st35gm04n03_09.par
Last Modification:           01.01.2002
\end{verbatim}
Its use is optional.

\end{itemize}


%--------------------------------------------------------------------------------------------------
\subsubsection{Fundamental Model Parameters}

\begin{itemize}

\item \verb|real teff|:\index{rhd.par!real teff@\verb/real teff/}\index{rhd.par!effective temperature} \\
The effective temperature is one of the basic model parameters and is
specified e.g.\ with
\begin{verbatim}
real teff  f=F13.3 b=4  n='Effective Temperature' u=K
 3500.0
\end{verbatim}
(for a relatively cool star).
Note that the actual effective temperature can only be determined a posteriori
and that the entropy of the instreaming entropy (see below) is more important
than \verb|teff| itself. In fact, \verb|teff| is only used to control
material properties at the outer boundary. Its value should be close to
the expected effective temperature of the model.


\item \verb|character grav_mod|:\index{rhd.par!character gravmode@\verb/character grav_mode/}\index{rhd.par!gravity} \\
Gravity is another characteristic of a stellar atmosphere. The type (or geometry)
of the external gravity field has to be specified e.g.\ with
\begin{verbatim}
character grav_mode  f=A80 b=80  n='Type of gravity field' &
  c0='constant/central'
central
\end{verbatim}
Two values are possible so far:
\begin{itemize}
\item \verb|constant|: In the standard ``solar'' case the constant gravity specified with
  \verb|real grav| is directed downward in x3 direction.
\item \verb|central|: For the ``supergiant'' case a central potential is assumed with an origin
  at x=0. The stellar mass as well as inner and outer smoothing radius have to be specified.
\end{itemize}


\item \verb|real grav|:\index{rhd.par!real grav@\verb/real grav/} \\
In the case of a constant gravity the amount of the acceleration has to specified with
\begin{verbatim}
real grav  f=E15.8 b=4  n='Gravity' u=cm/s^2
27500.0
\end{verbatim}
Setting this value to zero switches off gravity (oh wonder).


\item \verb|real mass_star|:\index{rhd.par!real massstar@\verb/real mass_star/} \\
In the case of a central the mass (in cgs units) of the star has to be specified with
\begin{verbatim}
real mass_star f=E15.8 b=4 n='Stellar Mass'              u=g
 9.94500e+33
\end{verbatim}


\item \verb|real r0_grav|:\index{rhd.par!real r0grav@\verb/real r0_grav/} \\
To avoid the central singularity in a 1/r potential it is smoothed in
the center to give a central potential of 1/\verb|r0_grav|, specified with
\begin{verbatim}
real r0_grav   f=E15.8 b=4 n='Inner Smoothing Radius'    u=cm
 9.45833e+12
\end{verbatim}
This parameter should always be non-zero for a central potential.

\item \verb|real r1_grav|:\index{rhd.par!real r1grav@\verb/real r1_grav/} \\
The density in an atmosphere in hydrostatic equilibrium can decline to very
low values. To artificial enlarge the pressure (and density) scale height
in the outer layers of the star (the corners of the box) the gravity can
be reduced by defining the potential at infinity to be
1/\verb|r1_grav|, specified with
\begin{verbatim}
real r1_grav   f=E15.8 b=4 n='Outer Smoothing Radius'    u=cm &
  c0='0.0: Not used'
 11.35000e+13
\end{verbatim}
Setting this parameter to zero gives the usual 1/r behavior of the potential
in the outer layers but also chooses another smoothing formula in the central
part (where \verb|real r0_grav| is relevant).
But a value somewhat larger than the remotest corner of the box effectively
cancels this artificial smoothing in the outer layers without changing
the formula for the potential.


\end{itemize}


%--------------------------------------------------------------------------------------------------
\subsubsection{Boundary Conditions}\index{rhd.par!boundary conditions}\index{boundary conditions}


The boundary conditions at the six sides of the computational box
cannot be specified independently.
For the naming convention of the boundaries a gravitational acceleration
in -x3 direction is assumed.
Accordingly, there is a bottom, a top, and four side boundaries.

\begin{itemize}


\item \verb|character side_bound|:\index{rhd.par!character sidebound@\verb/character side_bound/} \\
The boundary condition at all four sides is given by e.g.
\begin{verbatim}
character side_bound   f=A80 b=80 n='side boundary conditions' &
  c0='closed, transmitting, periodic'
transmitting
\end{verbatim}
Possible values are:
\begin{itemize}
\item \verb|reflective|: closed wall, no gravity, no radiation
\item \verb|constant|: open boundary with constant extrapolation of all values,
                       no gravity, no radiation
\item \verb|closed|, \verb|closedtop|: closed wall, can handle gravity, open for outward radiation
\item \verb|closedbottom|: closed wall, handles gravity, radiation in diffusion approximation
\item \verb|periodic|: periodic boundaries for hydrodynamics and radiation
\item \verb|transmitting|: transmitting boundary for hydro and outward radiation
\end{itemize}
Any of these values can be specified. But in fact, not all of them are recognized by all
modules. Therefore some parameters are for test purposes (e.g.\ shock calculations) only.
In simulations of a solar-like star with the \verb|MSrad| radiation transport module
the side boundaries {\em have\/} to be \verb|periodic|.
In simulations of a red supergiant all boundaries (including the sides) will typically
be \verb|transmitting|. As an alternative, \verb|closed| boundaries can be chosen in this case.


\item \verb|character top_bound|:\index{rhd.par!character topbound@\verb/character top_bound/} \\
The boundary condition at the top of the model is given by for instance
\begin{verbatim}
character top_bound    f=A80 b=80 n='top boundary conditions'
transmitting
\end{verbatim}
Possible values are:
\begin{itemize}
\item \verb|reflective|: closed wall, no gravity, no radiation
\item \verb|constant|: open boundary with constant extrapolation of all values,
                       no gravity, no radiation
\item \verb|closed|, \verb|closedtop|: closed wall, can handle gravity, open for outward radiation
\item \verb|periodic|: periodic boundaries for hydrodynamics and radiation
\item \verb|transmitting|: transmitting boundary for hydro and outward radiation
\end{itemize}
In almost every simulation of stellar convection a \verb|transmitting| top
boundary will be selected, the \verb|closed| one is an alternative.
The \verb|periodic| condition is only recognized by the hydrodynamics routines
and not by any radiation transport routine.


\item \verb|character bottom_bound|:\index{rhd.par!character bottombound@\verb/character bottom_bound/} \\
The boundary condition at the bottom of the model is given for instance by
\begin{verbatim}
character bottom_bound f=A80 b=80 n='bottom boundary conditions' &
  c0=closedbottom
transmitting
\end{verbatim}
Possible values are:
\begin{itemize}
\item \verb|reflective|: closed wall, no gravity, no radiation
\item \verb|constant|: open boundary with constant extrapolation of all values,
                       no gravity, no radiation
\item \verb|closed|, \verb|closedtop|: closed wall, can handle gravity, open for outward radiation
\item \verb|closedbottom|: closed wall, handles gravity, radiation in diffusion approximation
\item \verb|periodic|: periodic boundaries for hydrodynamics and radiation
\item \verb|transmitting|: transmitting boundary for hydro and outward radiation.
                           The parameters \verb|real c_tchange|, \verb|real c_tsurf|, and
                           \verb|real c_hptopfactor| have to be specified.
\item \verb|inoutflow|: "classical" open lower boundary for deep convection,
                        gravity and radiation possible.
                        The parameters \verb|real s_inflow|, \verb|real c_schange|, and
                        \verb|real c_pchange| have to be specified.
\end{itemize}
In simulations of a solar-like star with the \verb|MSrad| radiation transport module
the bottom boundary is typically of type ``\verb|inoutflow|''.
A supergiant simulation will have a \verb|transmitting| lower boundary.


\item \verb|real s_inflow|:\index{rhd.par!real sinflow@\verb/real s_inflow/} \\
The entropy of the material streaming through an open boundary of type ``\verb|inoutflow|''
into the model can be specified e.g.\ with
\begin{verbatim}
real s_inflow f=E15.8 b=4 n='Entropy of core material' &
  u=erg/K/g
3.25E+09
\end{verbatim}
In the case of a \verb|central| potential the entropy in a sphere with radius
\verb|r0_grav| is adjusted towards this entropy value.
In both geometry (supergiant as well as solar) this value is very important as
it finally (but indirectly) determines the luminosity\index{rhd.par!luminosity} and
effective temperature\index{rhd.par!effective temperature} of the star.

\item \verb|real c_schange|:\index{rhd.par!real cschange@\verb/real c_schange/} \\
The entropy \verb|s_inflow| of the material in the bottom layer
(solar case, \verb|inoutflow| boundary condition)
or the central region of the model (supergiant case) is not just
set to the specified but adjusted towards it. The adjustment rate can be
controlled with e.g.
\begin{verbatim}
real c_schange f=E15.8 b=4 &
  n='Rate of entropy change for open lower boundary' u=1
 0.3
\end{verbatim}
Guide values are
\begin{itemize}
  \item \verb|1.0|: fast adjustment
  \item \verb|0.3|: typical value
  \item \verb|0.1|: slow adjustment
  \item \verb|<=0.0|: not allowed
\end{itemize}

\item \verb|real c_pchange|:\index{rhd.par!real cpchange@\verb/real c_pchange/} \\
The \verb|inoutflow| boundary condition not only controls entropy and velocity
but also the pressure in the bottom layers:
It is locally adjusted towards the global average to damp out possible
instabilities.
The adjustment rate can be specified e.g.\ with
\begin{verbatim}
real c_pchange f=E15.8 b=4 &
  n='Rate of pressure change for open lower boundary' u=1
 1.0
\end{verbatim}


\item \verb|real c_tchange|:\index{rhd.par!real ctchange@\verb/real c_tchange/} \\
In the case of a \verb|transmitting| upper or outer boundary
the temperature of the material streaming into the model
is adjusted with a rate given e.g.\ by
\begin{verbatim}
real c_tchange f=E15.8 b=4 &
  n='Rate of temperature change for open upper boundary' u=1
 0.3
\end{verbatim}

\item \verb|real c_tsurf|:\index{rhd.par!real ctsurf@\verb/real c_tsurf/} \\
In the case of a \verb|transmitting| upper or outer boundary
the temperature of the material streaming into the model
is adjusted towards a temperature \verb|teff|*\verb|c_tsurf|.
This temperature can be specified as fraction of the effective temperature
e.g.\ with
\begin{verbatim}
real c_tsurf f=E15.8 b=4 n='Temperature factor for open upper boundary' u=1
 0.62
\end{verbatim}
The value depends on where the outer boundary is located relative to
the photosphere:
If the boundary lies at a point where the solar photospheric minimum temperature
is located, it can be fairly small.
If the boundary is far away from the photosphere of a red supergiant,
the value can be even smaller.
On the other hand, if the boundary lies somewhere within the solar chromosphere
even values above 1.0 might be reasonable.

\item \verb|real c_hptopfactor|:\index{rhd.par!real chptopfactor@\verb/real c_hptopfactor/} \\
In the case of a \verb|transmitting| upper or outer boundary
the density stratification outside the model has to be extrapolated properly.
Assumptions about this density affects the amount of mass flowing
into the model.
For the extrapolation it is assumed that the density scale $H_{\rho}$ scales
with the pressure scale height $H_p$ as
  $H_{\rho}$=$H_p$/\verb|c_hptopfactor|.
\begin{verbatim}
real c_hptopfactor f=E15.8 b=4 &
  n='Correction factor for surface pressure scale height' u=1
0.8
\end{verbatim}
Possible values are
\begin{itemize}
\item C $<$    \verb|0.0|: No effect (actually, a value of \verb|1.0| is chosen).
\item \verb|0.0| $\leq$ C $<$ \verb|1.0|: The density scale height is enlarged to account for
                                          possible effects of turbulent pressure on the scale height:
                                          The density decays less rapidly with height than in
                                          an (isothermal) hydrostatic stratification.
\item C $=$    \verb|1.0|: Density scale height is pressure scale height.
\item C $\geq$ \verb|1.0|: Density scale height is smaller than pressure scale height.
                           Not really useful.
\end{itemize}


\item \verb|real c_radhtautop|:\index{rhd.par!real cradhtautop@\verb/real c_radhtautop/} \\
The \verb|MSrad|\index{MSrad} radiation transport module needs the specification
of the scale height of the optical depth at the upper boundary, e.g.\ with
\begin{verbatim}
real c_radhtautop f=E15.8 b=4 n='Scale height of optical depth at top' u=cm
60.0E+05
\end{verbatim}

\end{itemize}


%--------------------------------------------------------------------------------------------------
\subsubsection{Equation of State}\index{equation of state}\index{EOS}\index{rhd.par!equation of state}

\begin{itemize}

\item \verb|character eosfile|:\index{rhd.par!character eosfile@\verb/character eosfile/} \\
The equation of state\index{equation of state}\index{EOS} file
together with the opacity file implicitly determine the
chemical composition\index{chemical composition}.
The EOS file can be specified for instance with
\begin{verbatim}
character eosfile f=A80 b=80 n='EOS file name' &
  c0=eos_gamma140.eos/eos_mm20_l.eos
eos_mm00_l3.eos
\end{verbatim}
So far, there exists only a relatively small number of files:
\begin{itemize}
\item \verb|eos_mm00_l3.eos|: Standard EOS file for solar composition with extra large
                              density range (towards low densities).
                              There exist two other files for the same composition but
                              smaller density range (\verb|eos_mm00.eos|, \verb|eos_mm00_l.eos|)
\item \verb|eos_mm20_l.eos|: Standard EOS file for metal-poor star ([M/H]=-2.0) with
                             extended range in internal energy and density (towards lower values).
                             The older file (\verb|eos_mm20.eos|) did not reach far enough.
\item \verb|eos_gamma140.eos|: EOS table for simple gas with constant $\Gamma$=1.4.
                               In this case all quantities could be faster computed than
                               by interpolation in a table.
                               Nevertheless, for compatibility reasons (to be able to use the
                               existing EOS Fortran routines), the table is provided.
\item \verb|eos_gamma166.eos|: EOS table for simple gas with constant $\Gamma$=5/3.
\end{itemize}

\item \verb|character eospath|:\index{rhd.par!character eospath@\verb/character eospath/} \\
The equation of state file does not have to be in the working directory.
Instead, its path can be specified e.g.\ with
\begin{verbatim}
character eospath f=A80 b=80 n='path of EOS file' &
  c0=/astro/b/bf/for/eos/dat
/home/a_bf/for/eos/dat
\end{verbatim}

\end{itemize}


%--------------------------------------------------------------------------------------------------
\subsubsection{Opacities}\index{opacities}\index{rhd.par!opacities}

\begin{itemize}

\item \verb|character opafile|:\index{rhd.par!character opafile@\verb/character opafile/} \\
The opacity file can be specified with e.g.
\begin{verbatim}
character opafile f=A80 b=80 n='opacity file name' &
  c0=g2va.opta/big_grey.opta &
  c1='empty -> no radiation transport'
phoenix_opal_grey.opta
\end{verbatim}
So far, there exist already a couple of files:
\begin{itemize}
\item \verb|davmf.opta|:
\item \verb|f5v.opta|:
\item \verb|g2va.opta|:
\item \verb|g2v_lowhe.opta|:
\item \verb|g2v_m20.opta|:
\item \verb|g2v.opta|:
\item \verb|hmin_p00.opta|:
\item \verb|opal_lowhe.opta|:
\item \verb|opal_m05.opta|:
\item \verb|opal_m10.opta|:
\item \verb|opal_m20.opta|:
\item \verb|phoenix_dust_grey.opta|:
\item \verb|phoenix_dust_ob4.opta|:
\item \verb|phoenix_opal_grey.opta|:
\item \verb|ross_m05.opta|:
\item \verb|ross_m10.opta|:
\item \verb|ross_m20.opta|:
\item \verb|sunur1.opta|:
\item \verb|sunur2.opta|:
\item \verb|t5000g44mm20.opta|:
\item \verb|t5000g47mm20.opta|:
\item \verb|t6300g40mm20.opta|:
\item \verb|t6500g44mm20.opta|:
\item \verb|zzceti1g.opta|:
\item \verb|zzceti1.opta|:
\end{itemize}

\item \verb|character opapath|:\index{rhd.par!character opapath@\verb/character opapath/} \\
The opacity file does not have to be in the working directory.
Instead, its path can be specified e.g.\ with
\begin{verbatim}
character opapath f=A80 b=80 n='path of opacity file' &
  c0=/astro/b/bf/for/opa/dat
/home/a_bf/for/opa/dat
\end{verbatim}

\end{itemize}



%--------------------------------------------------------------------------------------------------
\subsubsection{Hydrodynamics Control}\index{hydrodynamics}\index{rhd.par!hydrodynamics}

\begin{itemize}

\item \verb|character hdscheme|:\index{rhd.par!character hdscheme@\verb/character hdscheme/} \\
With this parameter the type of the hydrodynamics scheme can be specified as in
\begin{verbatim}
character hdscheme f=A80 b=80 n='Hydrodynamics scheme' &
  c0='Roe (approximate Riemann solver of Roe type)' &
  c1='VanLeer (operator splitting: advection + source terms)' &
  c2='None (skip hydrodynamics step entirely)'
Roe
\end{verbatim}
Possible values are
\begin{itemize}
\item \verb|None|: The hydrodynamics step is skipped entirely (for test purposes). Note that in this
                   case some initializations necessary for the generation of the mean file are omitted, too.
\item \verb|Roe|: (default) The standard Riemann solver of Roe type is activated.
                  This value will in almost every case be chosen.
\item \verb|VanLeer|: A half ready simple VanLeer advection scheme is activated. Avoid!
\end{itemize}

\item \verb|character reconstruction|:\index{rhd.par!character reconstruction@\verb/character reconstruction/} \\
This parameter determines the order and ``aggressiveness'' of the reconstruction scheme with e.g.\
\begin{verbatim}
character reconstruction f=A80 b=80 n='Reconstruction method' &
  c0=Constant c1=Minmod/VanLeer/Superbee c2=PP
Minmod
\end{verbatim}
Possible values are
\begin{itemize}
\item \verb|Constant|: The run of the partial waves inside the cells is assumed to be constant.
                       A highly dissipative first order scheme results.
                       This values will usually only be used for test (or comparison) purposes.
\item \verb|Minmod|: Chooses the smallest slope which still results in a second order scheme.
                     It is the most diffusive (and most stable) one in this class.
\item \verb|VanLeer|: (default) The recommended second order scheme.
\item \verb|Superbee|: The ``most aggressive'' stable 2nd order scheme.
                       It results in the steepest shocks, which works well in some test cases
                       but might be to difficult for the radiation transport module to handle.
\item \verb|PP|: Chooses the piecewise parabolic reconstruction of the PPM scheme
                 (``Piecewise Parabolic Method'', Colella \& Woodward 1984).
                 Results in 3rd order accuracy for the advection.
\end{itemize}
Usually, the \verb|VanLeer| reconstruction is a good choice.
If a more stable (and diffusive) scheme is needed, take \verb|Minmod|.
The \verb|PP| reconstruction gives the highest accuracy.

\item \verb|integer n_hydcellsperchunk|:\index{rhd.par!integer nhydcellsperchunk@\verb/integer n_hydcellsperchunk/}\label{s:n_hydcellsperchunk} \\
In every directional sub-step neighboring 1D columns are independent from each other.
They can be grouped and computed in chunks of arbitrary size.
The approximate number of grid cells per chunk can be specified e.g.\ with
\begin{verbatim}
integer n_hydcellsperchunk f=I9 b=4 &
  n='Number of cells per hydro chunk' &
  c0='0 => one 2D slice at a time' &
  c0='1 => minimum chunk size (inefficient)' &
  c0='2500: reasonable value' &
  c0='1000000000: maximum chunk size (inefficient and memory intensive)'
20000
\end{verbatim}
The exact number is determined at run time to get (approximately) equal sizes of the individual
chunks.
The choice of this parameter does not affect the result of the computation but
the memory usage and performance:
Smaller (and more) chunks may result in an optimum cache usage and need the smallest
amount of memory, but result in additional overhead due to frequent subroutine calls.
Bigger (and less) chunks are to be preferred for vector machines and processors
with large caches.
Very rough guide values may be
\begin{itemize}
\item \verb|2500|: Pentium III processor
\item \verb|20000|: RISC processor
\item \verb|100000|: Vector machine
\end{itemize}
Note: For simulations with activated OpenMP\index{OpenMP!chunk size}
on a parallel machine the chunk size has to be made small enough to
allow at least as many chunks as processors available. This is
particularly important for models with a small number of grid points
(e.g.\ 2D models).

\item \verb|real c_visdrag|:\index{rhd.par!real cvisdrag@\verb/real c_visdrag/} \\
This viscosity parameter controls the drag force which is (if requested)
applied inside the hydrodynamics routines themselves.
It does not act on velocity gradients as usual viscosity but applies a force proportional to the
velocity itself (but with the opposite sign).
The amount can be specified e.g.\ with
\begin{verbatim}
real c_visdrag f=E15.8 b=4 &
    n='Drag viscosity parameter' u=1
0.001
\end{verbatim}
The value gives the fraction the velocity is reduced per time step.
Therefore, reasonable values lie between \verb|0.0| and \verb|1.0|.
In almost every case the drag forces will be switched off (\verb|c_visdrag|=\verb|0.0|).
If e.g.\ strong pulsation have to be damped in the initial phase of a simulation
a value around \verb|0.001-0.01| seems appropriate.

\item \verb|real c_visbound|:\index{rhd.par!real cvisbound@\verb/real c_visbound/} \\
An additional drag force can be added locally in inflow cells in the outer layer
when the \verb|transmitting| boundary condition is chosen. The value can be
set e.g.\ with
\begin{verbatim}
real c_visbound f=E15.8 b=4 &
    n='Boundary drag viscosity parameter' u=1
0.001
\end{verbatim}
This extra drag force is usually not necessary and should be switched off
(with \verb|c_visbound|=\verb|0.0|).

\end{itemize}


%--------------------------------------------------------------------------------------------------
\subsubsection{Radiation Transport Control\label{s:radiationtransport}}\index{radiation transport}\index{rhd.par!radiation transport}

In this part of the parameter file the radiation transport module has to be selected.
Depending on this selection a couple of additional parameters have to be specified.


\begin{itemize}

\item \verb|character radscheme|:\index{rhd.par!character radscheme@\verb/character radscheme/} \\
So far, there exist three different radiation transport modules. The active on
can be selected e.g.\ with
\begin{verbatim}
character radscheme f=A80 b=80 n='Radiation transport scheme' &
  c0='LHDrad/MSrad/SHORTrad' &
  c1='None (skip radiation transport step entirely)'
SHORTrad
\end{verbatim}
Possible values are
\begin{itemize}
\item \verb|None|: Skip radiation transport entirely.
\item \verb|LHDrad|:\index{LHDrad}
  (old ``supergiant module'')
  It uses long characteristics and is restricted to an equidistant grid and
  open boundaries at all surfaces.
  Note that the switch \verb|-Drhd_r01=1| has to be set during compilation
  (see Sect.~\ref{s:rhd_r01}).
\item \verb|MSrad|:\index{MSrad}
  (``solar module'')
  It uses long characteristics. The lateral boundaries have to be periodic.
  Top and bottom can be closed or open.
  Note that the switch \verb|-Drhd_r02=1| has to be set during compilation
  (see Sect.~\ref{s:rhd_r02}).
\item \verb|SHORTrad|:\index{SHORTrad}
  (new ``supergiant module'')
  It uses short characteristics and is restricted to an equidistant grid and
  open boundaries at all surfaces.
  Note that the switch \verb|-Drhd_r03=1| has to be set during compilation
  (see Sect.~\ref{s:rhd_r03}).
\end{itemize}


\item \verb|integer n_radminiter|:\index{rhd.par!integer nradminiter@\verb/integer n_radminiter/} \\
Usually the stability considerations dictate a radiative time step\index{time step}
smaller than the hydrodynamics or tensor viscosity time step.
To remedy this situation it is possible to allow several radiation transport steps
per global time step.
Hitherto, all three radiation transport modules support this iteration.
The minimum number of iterations (radiative sub-steps) can be specified e.g.\ with
\begin{verbatim}
integer n_radminiter f=I4 b=4 &
  n='Minimum number of radiation transport iterations' c0=8
1
\end{verbatim}
If less iterations are needed the time step limit for the next step is increased.
This value will in almost any case (for explicit radiation transport) be set to \verb|1|.
In the implicit case it is set to a higher value (typically \verb|5|).

\item \verb|integer n_raditer|:\index{rhd.par!integer nraditer@\verb/integer n_raditer/} \\
After each complete radiative time step the recommendation for the next time step
will be chosen so that \verb|n_raditer| iterations will (probably) needed.
The parameter can be set e.g.\ with
\begin{verbatim}
integer n_raditer f=I4 b=4 &
    n='Number of radiation transport iterations' c0=10
8
\end{verbatim}
For a simulation of a solar-type star (with comparatively long radiative time scales)
it will typically be set to \verb|1|.
For starts with shorter radiative time scales values around \verb|10| may be considered.
All three radiation transport modules understand this parameter.

\item \verb|integer n_radmaxiter|:\index{rhd.par!integer n_radmaxiter@\verb/integer n_radmaxiter/} \\
The absolute maximum number of iterations can be specified e.g.\ with
\begin{verbatim}
integer n_radmaxiter f=I4 b=4 &
    n='Maximum number of rad. transport iterations' c0=30
0
\end{verbatim}
If more iterations are needed the computation for the current
time step is stopped and resumed with a smaller one (which means that the hydrodynamics
and the tensor viscosity step have to be done again).
Usually, \verb|n_radmaxiter| will either be set to a values somewhat larger
than the recommended number of iterations (\verb|n_raditer|)
or to \verb|0| which disable the check for too many iterations completely.
This can be safely allowed in many cases and has the advantage that there is
no need to save the initial model before calling the radiation transport module,
which saves some memory.
To disable the iteration of the radiation transport sub-step set
\verb|n_radminiter|=\verb|n_raditer|=\verb|n_radmaxiter|=\verb|1|.
All three radiation transport modules understand this parameter.


\item \verb|character radraybase|:\index{rhd.par!character radraybase@\verb/character radraybase/} \\
Using the modules \verb|LHDrad| or \verb|SHORTrad| the orientation of the base axis system
can be selected e.g.\ with
\begin{verbatim}
character radraybase f=A80 b=80 n='Base axis system' &
  c0='unity/random/randomgroup'
random
\end{verbatim}
Allowed values are
\begin{itemize}
\item \verb|unity|: (default) During all time steps and radiative sub-steps
                    the direction of the rays stays the same.
\item \verb|random|: At each time step (and radiative sub-step) a new base axis system is
                     chosen at random
\item \verb|randomgroup|: At each new time step a new base axis system is
                          chosen at random. It is kept for all radiative sub-steps.
\end{itemize}
Because typically only a relatively small number of rays is chosen per time step
(with \verb|radraystar|) it is advisable to vary the directions of the rays
(by choosing  \verb|radraybase|=\verb|random| or \verb|randomgroup|) to cover
the entire sphere at least over a longer time.

\item \verb|character radraystar|:\index{rhd.par!character radraystar@\verb/character radraystar/} \\
Using the modules \verb|LHDrad| or \verb|SHORTrad|
the list of ray directions (i.e.\ the number of rays and their coordinates)
relative to the base axis system can be specified with e.g.
\begin{verbatim}
character radraystar f=A80 b=80 n='List of relative ray directions' &
  c0='x1(1)/x2(1)/x3(1)/oktaeder(3)/tetraeder(4)/cube(4)' &
  c1='ikosaeder(6)/dodekaeder(10)'
oktaeder
\end{verbatim}
Examples for allowed values are
\begin{itemize}
\item \verb|x1|: (N=1) one single ray along x1 axis (not enough to specify fluxes in all directions)
\item \verb|x2|: (N=1) one single ray along x2 axis (not enough to specify fluxes in all directions)
\item \verb|x3|: (N=1) one single ray along x3 axis (not enough to specify fluxes in all directions)
\item \verb|oktaeder|: (N=3, default) octahedron
\item \verb|tetraeder|: (N=4) tetrahedron
\item \verb|cube|: (N=4)
\item \verb|ikosaeder|: (N=6) icosahedron
\item \verb|dodekaeder|: (N=10) dodecahedron
\end{itemize}
Several other choices are possible, which are meant for test purposes only.
Choosing one of the five Platonic solids (Ops! ``German-Greek'' names only, so far)
means that the 3 to 10 rays are equally distributed over the solid angle
(from the center to each {\em corner\/} of the respective solid).




\item \verb|integer n_radtheta|:\index{rhd.par!integer nradtheta@\verb/integer n_radtheta/} \\
Using the \verb|MSrad| module the ray directions have to specified in a different way:
The number of ray sets in theta direction can be chosen with e.g.\
\begin{verbatim}
integer n_radtheta f=I4 b=4 &
    n='NTHETA: Number of ray sets in theta direction' c0=2
2
\end{verbatim}

\item \verb|integer n_radphi|:\index{rhd.par!integer nradphi@\verb/integer n_radphi/} \\
Using the \verb|MSrad| module
the number of ray sets in phi direction can be set e.g.\ with
\begin{verbatim}
integer n_radphi f=I4 b=4 &
    n='NPHI: Number of ray sets in phi direction' c0=2
2
\end{verbatim}

\item \verb|integer n_radsubray|:\index{rhd.par!integer nradsubray@\verb/integer n_radsubray/} \\
Using the \verb|MSrad| module
the number of rays per cell (with the same direction)
can be specified e.g.\ with
\begin{verbatim}
integer n_radsubray f=I4 b=4 n='KPHI: Number of rays per cell' c0=2
2
\end{verbatim}


\item \verb|integer n_radband|:\index{rhd.par!integer n_radband@\verb/integer n_radband/} \\
It can be specified whether the grey opacity table or the binned frequency-dependent
part of the opacity table is used during the computation.
The grey part contains only one bin. The other (possibly non-grey) contains one or more
bins depending on the table chosen.
The parameter is specified with e.g.\
\begin{verbatim}
integer n_radband f=I4 b=4 n='Number of frequency bins' &
  c0='1: grey opacities' &
  c1='2: non-grey opacities (if available from table)'
1
\end{verbatim}
Allowed values are
\begin{itemize}
\item \verb|1|: Use the grey part of the table
\item \verb|2|: Use the other (possibly non-grey, frequency-dependent) part of the table
\end{itemize}
Only the \verb|MSrad| module so far can handle non-grey tables.


\item \verb|real c_radimplicitmu|:\index{rhd.par!real cradimplicitmu@\verb/real c_radimplicitmu/} \\
So far only the \verb|LHDrad| module (tentatively) supports
implicit radiation transport.
It can be activated with the parameter
\begin{verbatim}
real c_radimplicitmu f=E15.8 b=4 &
    n='Implicitness parameter for radiation transport'            u=1 &
    c0='0.0: explicit / 0.5: time centered / 1.0: fully implicit'
0.0
\end{verbatim}
Allowed values are
\begin{itemize}
\item \verb|0.0|: Fully explicit radiation transport
                  (possible with all modules)
\item \verb|0.0| $<$ C $<$ \verb|1.0|: Partly implicit radiation transport
\item \verb|0.5|: Radiation transport time-centered
\item \verb|1.0|: Fully implicit radiation transport
\end{itemize}
Values outside this range do not have much meaning.
The implicit transport does not work efficiently yet: It does not yield larger
time steps than possible with a sequence of purely explicit sub time steps.

\item \verb|real c_raditereps|:\index{rhd.par!real craditereps@\verb/real c_raditereps/} \\
With activated implicit radiation transport (\verb|LHDrad| module only)
the requested convergence accuracy of the iteration can be set e.g.\ with
\begin{verbatim}
real c_raditereps f=E15.8 b=4 &
    n='Relative accuracy for radiation iteration'                 u=1 &
    c0='Typical value: 1.0E-03'
2.0E-03
\end{verbatim}

\item \verb|real c_raditerstep|:\index{rhd.par!real craditerstep@\verb/real c_raditerstep/} \\
With activated implicit radiation transport (\verb|LHDrad| module only)
the step size of the iteration can be restricted with e.g.\
\begin{verbatim}
real c_raditerstep f=E15.8 b=4 &
    n='Step size of radiation iteration'                          u=1 &
    c0='Typical values: 0.7,0.81'
1.0
\end{verbatim}
Allowed values are
\begin{itemize}
\item \verb|0.0| $<$ \verb|1.0|: Restricted step size
\item \verb|1.0|: No restriction, standard step size
\item $>$ \verb|1.0|: Extra large steps
\end{itemize}
This value has to be chosen carefully to get optimal performance.
Is the step size too small the convergence is safe but too slow.
A too large step size inhibits convergence and leads to a decrease in
the time step, which results in a bad performance, too.


\item \verb|real c_radtvisdtau|:\index{rhd.par!real cradtvisdtau@\verb/real c_radtvisdtau/} \\
Using the \verb|LHDrad| module 
the limit in delta optical depth (rho*kappa*dx) below which the
``radiative temperature viscosity'' (=temperature smoothing) is to be applied
can be set with e.g.
\begin{verbatim}
real c_radtvisdtau f=E15.8 b=4 &
  n='Optical depth limit for temperature viscosity' u=1
0.1
\end{verbatim}
The introduction of this ``temperature diffusion'' is a somewhat desperate and
inelegant attempt to improve the behavior of the Greens function (hot cells should
be cooled, cool cells should be heated).
This diffusion is necessary for not well resolved models.
It is switched off with \verb|c_radtvisdtau| $\leq$ \verb|0.0|.

\item \verb|real c_radtvis|:\index{rhd.par!real cradtvis@\verb/real c_radtvis/} \\
Using the \verb|LHDrad| module
the amount of the ``radiative temperature viscosity'' (=temperature smoothing)
can be specified e.g.\ with
\begin{verbatim}
real c_radtvis f=E15.8 b=4 n='Temperature viscosity' u=1
1.6
\end{verbatim}
For well resolved models it should be
switched off (with \verb|c_radtvis| $\leq$ \verb|0.0|).
But often its use is necessary.

\end{itemize}


%--------------------------------------------------------------------------------------------------
\subsubsection{Tensor Viscosity Control\label{s:tensorviscosity}}\index{tensor viscosity}\index{rhd.par!tensor viscosity}

In many test problems it is not necessary to activate the 2D/3D tensor viscosity.
But when strong slow shock fronts are aligned with the grid the Roe solver
runs into problems and at least some additional 2D or 3D viscosity is necessary.
And even if the Roe solver can handle sharp shocks by its own, the
radiation transport algorithm might cause trouble because of the enormous
opacity variations across a shock front. Here the tensor viscosity is useful, too.

\begin{itemize}

\item \verb|real c_vissmagorinsky|:\index{rhd.par!real cvissmagorinsky@\verb/real c_vissmagorinsky/} \\
A turbulent viscosity of Smagorinsky type can be activated e.g.\ with
\begin{verbatim}
real c_vissmagorinsky f=E15.8 b=4 &
    n='Turbulent eddy viscosity parameter (Smagorinsky type)'     u=1
1.2
\end{verbatim}
In many cases values around \verb|0.5| are sufficient to stabilize the code.
Larger values (\verb|1.2| in the example above) are only necessary for some
nasty under-resolved supergiant models.
Setting \verb|c_vissmagorinsky| = \verb|c_visartificial| = \verb|0.0| skips
the tensor viscosity step entirely.

\item \verb|real c_visartificial|:\index{rhd.par!real cvisartificial@\verb/real c_visartificial/} \\
A standard artificial viscosity can be activated e.g.\ with
\begin{verbatim}
real c_visartificial f=E15.8 b=4 &
    n='Artificial viscosity tensor parameter'                     u=1
1.2
\end{verbatim}
In many cases values around \verb|0.5| are sufficient to stabilize the code.
Larger values (\verb|1.2| in the example above) are only necessary for some
nasty under-resolved supergiant models.
Setting \verb|c_vissmagorinsky| = \verb|c_visartificial| = \verb|0.0| skips
the tensor viscosity step entirely.

\item \verb|real c_visprturb|:\index{rhd.par!real cvisprturb@\verb/real c_visprturb/} \\
The Prandtl number for turbulent mixing can be specified e.g.\ with
\begin{verbatim}
real c_visprturb f=E15.8 b=4 &
    n='Turbulent Prandtl number'                                  u=1
8.0
\end{verbatim}
Values between \verb|1.0| and \verb|10.0| appear reasonable.
Note that larger values lead to smaller amounts of turbulent mixing!
A value of \verb|0.0| switches off the turbulent mixing terms
(but not the entire tensor viscosity).


\item \verb|real c_vistensordiag|:\index{rhd.par!real cvistensordiag@\verb/real c_vistensordiag/} \\
The factor in the stress tensor in front of of the diagonal terms
can be set with
\begin{verbatim}
real c_vistensordiag f=E15.8 b=4 &
    n='Diagonal factor for viscous stress tensor'                 u=1 &
    c0='typically 1.0
1.0
\end{verbatim}
This is not really parameter one would try to adjust.
The total amount of viscosity should be controlled with 
\verb|real c_vissmagorinsky| and \verb|real c_visartificial|.
But the parameter can be used to tentatively switch off the diagonal terms completely
or to change its importance compared to the other terms.

\item \verb|real c_vistensoroff|:\index{rhd.par!real cvistensoroff@\verb/real c_vistensoroff/} \\
The factor in the stress tensor in front of of the off-diagonal terms
can be set with e.g.
\begin{verbatim}
real c_vistensoroff f=E15.8 b=4 &
    n='Off-diagonal factor for viscous stress tensor'             u=1 &
    c0='typically 0.5
0.5
\end{verbatim}
This is not really parameter one would try to adjust.
The total amount of viscosity should be controlled with 
\verb|real c_vissmagorinsky| and \verb|real c_visartificial|.
But the parameter can be used to tentatively switch off the off-diagonal terms completely
or to change its importance compared to the other terms.

\item \verb|real c_vistensordiv|:\index{rhd.par!real cvistensordiv@\verb/real c_vistensordiv/} \\
The factor in the stress tensor in front of of the divergence terms (also on the diagonal)
can be set with e.g.
\begin{verbatim}
real c_vistensordiv f=E15.8 b=4 &
    n='Divergence factor for viscous stress tensor'               u=1 &
    c0='typically -1./3.
0.0
\end{verbatim}
This is not really parameter one would try to adjust.
The total amount of viscosity should be controlled with 
\verb|real c_vissmagorinsky| and \verb|real c_visartificial|.
But the parameter can be used to switch off the divergence terms completely
or to change its importance compared to the other terms.
These divergence terms can be used to reduce the effect of
the tensor viscosity in the case of isotropic compression.
But this reduction
(\verb|c_vistensordiv| = \verb|-0.333333| in 3D,
 \verb|c_vistensordiv| = \verb|-0.5| in 2D)
is usually switched off.

\item \verb|integer n_viscellsperchunk|:\index{rhd.par!integer nviscellsperchunk@\verb/integer n_viscellsperchunk/} \\
The number of cells per box (or ``chunk'')
treated by the tensor viscosity scheme at one call (and by one thread)
can be set e.g.\ with
\begin{verbatim}
integer n_viscellsperchunk f=I9 b=4 &
  n='Number of cells per viscosity chunk' &
  c0='0 => old chopping' &
  c0='12000: reasonable value'
20000
\end{verbatim}
It can be adjusted to improve cache efficiency and to
modify the work load distribution onto the threads
(in case of parallel runs with OpenMP).
Due to the special handling of boundary cells the overhead per call increases
significantly for small chunks.
Typically larger chunk sizes (compared the the hydrodynamics chunk sizes set with
\verb|integer n_hydcellsperchunk|, see Sect.~\ref{s:n_hydcellsperchunk})
are adequate.
On the other hand they should not be too large to limit the usage of temporary
memory and to allow parallelization (the distribution of chunks to threads):
For simulations with activated OpenMP\index{OpenMP!chunk size} on a parallel machine the
chunk size has to be made small enough to allow at least as many chunks as processors available.
This is particularly important for models with a small number of grid points (e.g.\ 2D models).

\end{itemize}


%--------------------------------------------------------------------------------------------------
\subsubsection{Process Time Management}\index{rhd.par!process management}

In this group several parameters can be set which control the
start of the time counting during a simulation
and the total length of a job.
If either one of the halt conditions below is met, COBOLD finishes the current
step, writes a final model (plus some final information to other files),
and stops execution.

For example on a CRAY\index{Cray} one typically wants to use most of the CPU time
given for an individual batch job. In this case one can set e.g.\
\verb|real cputime_remainlimit|=\verb|2000.0|
and the values for the other halt conditions to \verb|-1.0| or \verb|-1|.

\begin{itemize}

\item \verb|real starttime|:\index{rhd.par!real starttime@\verb/real starttime/} \\
The start time of a simulation is usually taken from the start model file.
But sometimes is simulation is to be started with the final model of
a previous run but should start at time=0.0.
This can be achieved by setting the start time with
\begin{verbatim}
real starttime f=E15.8 b=4 n='Start time'                              u=s
0.0
\end{verbatim}
Allowed values are
\begin{itemize}
\item $\geq$ \verb|0.0|: Set the initial time of the simulation to this value
                         and override value from start model.
\item $<$ \verb|0.0|: (default) Take the initial time from start model.
\end{itemize}

\item \verb|integer starttimestep|:\index{rhd.par!integer starttimestep@\verb/integer starttimestep/} \\
The start time step count of a simulation is usually taken from the start model file.
But sometimes is simulation is to be started with the final model of
a previous run but should start at time step=0.
This can be achieved by setting the start time step count with
\begin{verbatim}
integer starttimestep f=I11 b=4 n='Start time step number'             u=1
0
\end{verbatim}
Allowed values are
\begin{itemize}
\item $\geq$ \verb|0|: Set the initial time step of the simulation to this value
                       and override value from start model.
\item $<$ \verb|0|: (default) Take the initial time step count from start model.
\end{itemize}


\item \verb|real cputime|:\index{rhd.par!real cputime@\verb/real cputime/} \\
Because of the long simulation time usually COBOLD will run in some sort of
batch mode which might impose limits on the execution time per run.
On a CRAY\index{Cray} the CPU time that is left can be accessed with a
special subroutine (in \verb|call tremain| in \verb|rhd_mac_cray_module.f90|).
On other machines it is possible to specify the allowed total time
for the job e.g.\ with
\begin{verbatim}
real cputime f=E15.8 b=4 n='CPU time'                                  u=s
1000000.0
\end{verbatim}
During the run of COBOLD the leftover CPU time is computed
by subtracting the used CPU time
(which is given by \verb|e_time=etime(tarray)| in \verb|rhd_mac_sun_module.f90|)
from the specified total CPU time for the job.

\item \verb|real cputime_remainlimit|:\index{rhd.par!real cputime_remainlimit@\verb/real cputime_remainlimit/} \\
Because COBOLD needs some time to finish the last time step
it should start exiting well before all CPU time is used up.
This amount of buffer CPU time can be specified e.g.\ with
\begin{verbatim}
real cputime_remainlimit f=E15.8 b=4 n='maximum remaining CPU time'    u=s
2000.0
\end{verbatim}
Its value depends on the size of the model and the speed of the machine
(more precisely the maximum CPU time per time step).


\item \verb|real endtime|:\index{rhd.par!real endtime@\verb/real endtime/} \\
If the simulation should run up to a certain (stellar) time, its values
can be specified e.g.\ with
\begin{verbatim}
real endtime f=E15.8 b=4 n='total simulation time limit'               u=s
10000.0
\end{verbatim}
A value $<$ \verb|0.0| deactivates this halt condition: it is not checked at all.
If this parameter is set to a non-negative value a follow-up simulation
should not use the same parameter file: it would stop immediately.

\item \verb|real plustime|:\index{rhd.par!real plustime@\verb/real plustime/} \\
If the initial model should be advanced by a certain (stellar) time span,
this value can be set e.g.\ with
\begin{verbatim}
real plustime f=E15.8 b=4 n='simulation advance time'                  u=s
5.0E+07
\end{verbatim}
A value $<$ \verb|0.0| cancels this halt condition: it is not checked at all.
This condition assures (if it is the only one) that all individual
simulation runs cover (approximately) the same stellar time.

\item \verb|integer endtimestep|:\index{rhd.par!integer endtimestep@\verb/integer endtimestep/} \\
If the simulation should run up to a certain time step, its values
can be specified e.g.\ with
\begin{verbatim}
integer endtimestep f=I11 b=4 n='total simulation time step number'    u=1
1234
\end{verbatim}
This might be useful to advance the simulation up to a point shortly before
a previous simulation crashed.
A value $<$ \verb|0| cancels this halt condition: it is not checked at all.

\item \verb|integer plustimestep|:\index{rhd.par!integer plustimestep@\verb/integer plustimestep/} \\
If the initial model should be advanced by a certain number of time steps
their number can be set e.g.\ with
\begin{verbatim}
integer plustimestep f=I11 b=4 n='simulation advance time step number' u=1
2000
\end{verbatim}
A value $<$ \verb|0| deactivates this halt condition: it is not checked at all.

\end{itemize}


%--------------------------------------------------------------------------------------------------
\subsubsection{Time Step Control}\index{rhd.par!time step}

In this group parameters to control the time step restrictions can be set.

They are important because decide about performance and stability of COBOLD.
They should be tested and adjusted for a simulation of a new type of object.
But all the dimensionless parameters can stay unchanged for a group of similar
simulations. Only the parameters with an explicit time dimension should
be checked in all cases (they scale with characteristic timescales and
depend particularly on gravity).

\begin{itemize}

\item \verb|real dtime_start|:\index{rhd.par!real dtimestart@\verb/real dtime_start/} \\
The initial time step recommendation of a simulation is usually taken from the start model file.
It can be overwritten e.g.\ with
\begin{verbatim}
real dtime_start f=E15.8 b=4 n='Start time step'                     u=s
1.0E+03
\end{verbatim}
A value $<$ \verb|0.0| means that the original value from the start model is used.

\item \verb|real dtime_min|:\index{rhd.par!real dtimemin@\verb/real dtime_min/} \\
In some rare cases it might be useful to specify explicitly the minimum time step
with e.g.\
\begin{verbatim}
real dtime_min f=E15.8 b=4 n='Minimum time step'                     u=s &
  c0='dtime_min=0.0 => no restriction'
1.0
\end{verbatim}
This value is used even if restrictions from the Courant condition try to
enforce a smaller value.
A fixed time step can be prescribed by setting
\verb|dtime_min| = \verb|dtime_max| to some positive value.
A value \verb|dtime_min| $\leq$ 0.0 means that this time step restriction
is completely ignored, which is the case that should usually be chosen.

\item \verb|real dtime_max|:\index{rhd.par!real dtimemax@\verb/real dtime_max/} \\
It is possible to explicitly specify the maximum time step too,
e.g.\ with
\begin{verbatim}
real dtime_max f=E15.8 b=4 n='Maximum time step'                     u=s &
  c0='dtime_max=0.0 => no restriction'
1.0E+05
\end{verbatim}
A fixed time step can be prescribed by setting
\verb|dtime_min| = \verb|dtime_max| to some positive value.
A value \verb|dtime_max| $\leq$ 0.0 means that this time step restriction
is completely ignored, which is the case that should usually be chosen.

\item \verb|real dtime_min_stop|:\index{rhd.par!real dtimeminstop@\verb/real dtime_min_stop/} \\
Sometimes a simulation can run into a pathological state where the time step
decreases rapidly without recovering.
To prevent a simulation in such a case from running forever (or until some other
process time restriction applies) without actually advancing significantly in
time, it is possible to specify an absolute minimum time step, e.g.\ with
\begin{verbatim}
real dtime_min_stop f=E15.8 b=4 n='Minimum time step'                u=s &
  c0='dtime_min_stop=0.0 => no restriction' &
  c1='dtime < dtime_min_stop => program stop'
1.0
\end{verbatim}
If the actual time step falls below this value, the simulation finishes gracefully.
This values has to specified as absolute time and has to be chosen carefully for
each individual model (or each group of models).
This time step restriction can be switched off by setting
\verb|real dtime_min_stop|=\verb|0.0|.
But in general, one should keep it activated and try to find a proper positive value.

\item \verb|real dtime_incmax|:\index{rhd.par!real dtimeincmax@\verb/real dtime_incmax/} \\
Sometimes a time step restriction can lead to a sudden drastic drop in the time step.
To prevent unwanted oscillations in the size of the time step
its increase can be restricted e.g.\ with
\begin{verbatim}
real dtime_incmax f=E15.8 b=4 n='Maximum time step increment factor' u=1 &
  c0='dtime_max<1.0 => no restriction' c1='typically 1.1'
1.2
\end{verbatim}
This value specifies the maximum factor by which the time step can be increased
from step to step (even if the new Courant condition etc.\ would allow more).
A value value $<$ \verb|0.0| deactivates this restriction.

\item \verb|real c_courant|:\index{rhd.par!real ccourant@\verb/real c_courant/} \\
A typical Courant factor for each 1D hydrodynamics step can be specified with e.g.
\begin{verbatim}
real c_courant f=E15.8 b=4 n='HD Courant factor'                     u=1 &
  c0='range: 0.0 < C_Courant <= 1.0, typically: 0.5'
 0.5
\end{verbatim}
From the minimum cell crossing time of a partial wave and this factor
a recommendation for the {\em next\/} time step is computed.
A value of \verb|1.0| is the upper limit which guarantees stability
for some simple linear test problems.
Values around \verb|0.5| are recommended for fully non-linear simulations.

\item \verb|real c_courantmax|:\index{rhd.par!real ccourantmax@\verb/real c_courantmax/} \\
A typical Courant factor for each 1D hydrodynamics step can be specified with e.g.
\begin{verbatim}
real c_courantmax f=E15.8 b=4 n='maximum HD Courant factor'          u=1 &
  c0='range: C_Courant < C_Courantmax <= 1.0, typically: 0.9'
 0.8
\end{verbatim}
From the minimum cell crossing time of a partial wave and this factor
an upper limit for the {\em current\/} time step is computed.
If this limit is exceeded the computation is interrupted and resumed with a smaller
time step (based on \verb|c_courant|).
Usually this parameter should be restricted by
\verb|c_courant| $<$ \verb|c_courantmax| $\leq$ \verb|1.0|.
A value around \verb|0.8| appears to be a good choice.

\item \verb|real c_maxeichange|:\index{rhd.par!real cmaxeichange@\verb/real c_maxeichange/} \\
The relative change in internal during a single 1D hydrodynamics step
can be used to restrict the time step by specifying
\begin{verbatim}
real c_maxeichange f=E15.8 b=4 n='maximum hydro energy change'       u=1 &
  c0='range: 0.1 - 1.0, typically 0.5, off:0.0'
 0.5
\end{verbatim}
The default is \verb|0.9|.
Nevertheless, since the Roe solver is constructed to handle shocks and
rapid changes in density and energy, this check is usually not needed.
It can be switched off by setting \verb|c_maxeichange|=\verb|0.0|.


\item \verb|real c_radcourant|:\index{rhd.par!real cradcourant@\verb/real c_radcourant/} \\
The radiation transport routines are subject so time step restrictions, too.
And in typical scenarios, its the radiative timescale are the shortest one and
poses the tightest restriction.
Contrary to the hydrodynamics routines the timescale relevant for the stability
of the radiation transport scheme can only be estimated
using the characteristic timescale of a small sinusoidal temperature disturbance
with a wavelength of the grid size in a homogeneous background and grey radiative
energy exchange.
The ``radiative Courant'' factor can be set e.g.\ with
\begin{verbatim}
real c_radcourant f=E15.8 b=4 n='RAD Courant factor'                 u=1 &
  c0='range: 0.0 < C_radCourant, typically: 1.0'
 2.5
\end{verbatim}
If the estimate of the timescale would be correct a value of \verb|2.0|
would cause the temperature fluctuation on the shortest scale to flip its sign,
setting the absolute stability limit.
A value of \verb|1.0| would lead to a damping of theses fluctuations within one
time step.
But in practice, even higher values (for example \verb|2.5|) show a reasonable
behavior.
This might be due to the effect that the shortest radiative timescale only occurs
at single points (or in 2D layers) but that already the immediate neighbors have
longer timescales and can damp the ``most sensitive points''.
Based on \verb|real c_radcourant| the recommended typical radiative time step is
computed.

\item \verb|real c_radcourantmax|:\index{rhd.par!real c_radcourantmax@\verb/real c_radcourantmax/} \\
With this parameter the maximum allowed radiative time step is prescribed as e.g.\ in
\begin{verbatim}
real c_radcourantmax f=E15.8 b=4 n='maximum RAD Courant factor'      u=1 &
  c0='range: C_radCourant <= C_radCourantmax, typically: 2.0'
 3.0
\end{verbatim}
This value will typically be somewhat larger than \verb|real c_radcourant|.

\item \verb|real c_radmaxeichange|:\index{rhd.par!real cradmaxeichange@\verb/real c_radmaxeichange/} \\
The relative energy change per radiative sub step can be restricted e.g.\ with
\begin{verbatim}
real c_radmaxeichange f=E15.8 b=4 n='maximum radiative energy change' &
  u=1 c0='range: 0.01 - 1.0'
 0.25
\end{verbatim}
The default is \verb|0.5|.
Values between \verb|0.1| and \verb|0.5| seem reasonable.
A value $\leq$~\verb|0.0| deactivates this time step check.
However, the check of the radiative energy change should usually be performed.
A way to maximize the radiative time step (and therefore the performance of the entire code)
can be to first set \verb|real c_radmaxeichange| to a proper value (say \verb|0.25|).
Then, \verb|real c_radcourant| (and \verb|real c_radcourantmax|) are adjusted
(by trial and error) in a way that the radiative time step is almost always
restricted by the ``Courant'' condition and only sometimes in extreme cases by
the maximum energy change restriction.
The computed output intensity should be checked for the size of its fluctuations
due to a possibly too large value of \verb|c_radmaxeichange|.


\item \verb|real c_radthintimefac|:\index{rhd.par!real c_radthintimefac@\verb/real c_radthintimefac/} \\
In the \verb|LHDrad| module only the radiative time step restriction due to energy changes
can be relaxed further in the optically thin by specifying e.g.\
\begin{verbatim}
real c_radthintimefac f=E15.8 b=4 &
  n='time scale reduction in optically thin'                         u=1 &
  c0='range: 0.1 - 1.0, typically: 0.5'
 0.60
\end{verbatim}
A value $\leq$ \verb|0.0| or \verb|real c_radtvisdtau| $\leq$ \verb|0.0| switches off this
relaxation.


\item \verb|real c_viscourant|:\index{rhd.par!real c_viscourant@\verb/real c_viscourant/} \\
The tensor viscosity routines have their own time step restriction.
The recommended typical viscous time step can be set e.g.\ with
\begin{verbatim}
real c_viscourant f=E15.8 b=4 n='viscous Courant factor'             u=1 &
  c0='range: 0.0 < C_visCourant, typically: 0.5-1.0, better 0.25'
 0.5
\end{verbatim}
As the corresponding viscous timescale is typically longer than the radiative one
(and even the Courant timescale from the Roe hydrodynamics routines)
this factor is often irrelevant.
The absolute upper stability limit is located at \verb|c_viscourant|=\verb|2.0|.
Values around \verb|0.5| to \verb|1.0| are more typical.
In some extreme cases in simulations of the solar chromosphere it has turned out
that an even lower value (\verb|0.2|) is necessary to prevent some spikes
in the neighborhood of strong colliding shocks.

\item \verb|real c_viscourantmax|:\index{rhd.par!real c_viscourantmax@\verb/real c_viscourantmax/} \\
The absolute upper limit for the viscous time scale can be set with
\begin{verbatim}
real c_viscourantmax f=E15.8 b=4 n='maximum viscous Courant factor'  u=1 &
  c0='range: C_visCourant <= C_visCourantmax, typically smaller than 2.0'
 1.0
\end{verbatim}
Its value should be slightly above \verb|c_viscourant| and below \verb|2.0|.

\end{itemize}


%--------------------------------------------------------------------------------------------------
\subsubsection{Input/Output Control}\index{rhd.par!input/output}

With this group of parameters
the start model and the type and amount of output can be specified.
Parameters with the suffix \verb|_start| describe the initial model,
these with suffix \verb|_end| the corresponding final model.
Additional data can be written
into the file described by the parameters with suffix \verb|_full|
(full 2D/3D model dumps, huge, see Sect.~\ref{s:modelfiles})
or
into the file described by the parameters with suffix \verb|_mean|
(additional information, see Sect.~\ref{s:meanfiles}).

\begin{itemize}

\item \verb|real dtime_out_full|:\index{rhd.par!real dtimeoutfull@\verb/real dtime_out_full/} \\
The interval between datasets in the \verb|full| file can be set e.g.\ with
\begin{verbatim}
real dtime_out_full f=E15.8 b=4 n='Output time step'                 u=s &
  c0='dtime_out_full < 0.0 => no output' &
  c1='dtime_out_full = 0.0 => output every time step'
 2.0E+06
\end{verbatim}
Allowed values are
\begin{itemize}
\item $<$ \verb|0.0|: No output to this file
\item $=$ \verb|0.0|: Output at every time step. Attention: This can produce HUGE files in no time.
\item $>$ \verb|0.0|: Output to \verb|full| file approximately every \verb|dtime_out_full| seconds.
\end{itemize}
Some examples: The ``classical'' value for this output for simulations of solar granulation
is 20\,sec.
To save memory this can be increased to 30\,sec.
But in this case chromospheric shocks are very badly resolved.
To cover them properly, a sampling rate of 10\,sec or below is needed.

\item \verb|real dtime_out_mean|:\index{rhd.par!real dtimeoutmean@\verb/real dtime_out_mean/} \\
The interval between datasets in the \verb|mean| file can be set e.g.\ with
\begin{verbatim}
real dtime_out_mean f=E15.8 b=4 n='Output time step'                 u=s &
  c0='dtime_out_mean<0.0 => no output'
 0.5E+06
\end{verbatim}
Allowed values are
\begin{itemize}
\item $<$ \verb|0.0|: No output to this file
\item $=$ \verb|0.0|: Output at every time step.
\item $>$ \verb|0.0|: Output to \verb|mean| file approximately every \verb|dtime_out_mean| seconds.
\end{itemize}
Because the size of one \verb|mean| dataset is much smaller than one \verb|full| dataset,
it is possible to request a higher sampling rate without using too much disk space.

\item \verb|character infile_start|:\index{rhd.par!character infilestart@\verb/character infile_start/} \\
The filename of the initial model is specified e.g.\ with
\begin{verbatim}
character infile_start f=A80 b=80 n='File name of start model'
rhd.sta
\end{verbatim}
Default is \verb|rhd.sta| (for a parameter file used within a batch system).
Typical filenames are \verb|st35gm04n01_01.sta| or \verb|gt57g44n20dz.end|.

\item \verb|character outfile_end|:\index{rhd.par!character outfileend@\verb/character outfile_end/} \\
The file name for the final model can be specified with e.g.\
\begin{verbatim}
character outfile_end f=A80 b=80 n='Output file name'
rhd.end
\end{verbatim}
The default is \verb|rhd.end|.
Leaving it empty means that no final model is written. This of course inhibits
follow-up simulations but can be useful to save time and disk space for some tests.

\item \verb|character outfile_full|:\index{rhd.par!character outfile_full@\verb/character outfile_full/} \\
The name of the file for the output of additional full models at regular intervals
(see Sect.~\ref{s:modelfiles}) can be given with e.g.\
\begin{verbatim}
character outfile_full f=A80 b=80 n='Output file name'
rhd.full
\end{verbatim}
Leaving it empty means that no file of this type is written.

\item \verb|character outfile_mean|:\index{rhd.par!character outfilemean@\verb/character outfile_mean/} \\
The name of the file for the output of additional information (average stratification,
mean fluxes, surface intensities) at regular intervals (see Sect.~\ref{s:meanfiles})
can be specified with e.g.\
\begin{verbatim}
character outfile_mean f=A80 b=80 n='Output file name'
rhd.mean
\end{verbatim}
Leaving it empty means that no file of this type is written.


\item \verb|character outform_end|:\index{rhd.par!character outformend@\verb/character outform_end/} \\
The format (see Sect.~\ref{s:UIO_data_representation}) of the final model files
can be chosen e.g.\ with
\begin{verbatim}
character outform_end f=A80 b=80 n='Output file format' &
  c0='formatted/unformatted'
unformatted
\end{verbatim}
Allowed values are
\begin{itemize}
\item \verb|unformatted|: (default) fast compact (possibly machine-dependent) output:
                          strongly recommended
\item \verb|formatted|: slow (machine-independent) output, big files
\end{itemize}

\item \verb|character outconv_end|:\index{rhd.par!character outconvend@\verb/character outconv_end/} \\
The conversion type (see Sect.~\ref{s:UIO_data_representation}) of the final model files
can be specified e.g.\ with
\begin{verbatim}
character outconv_end f=A80 b=80 n='Output file conversion' &
  c0='ieee_4/ieee_8/crayxmp_8/native'
ieee_4
\end{verbatim}
The allowed values depend on the machine.
Leaving this field empty means that the default is chosen that is build into the local UIO module.
If the type \verb|ieee_4| is supported (which is always the case, so far) it should be chosen.


\item \verb|character outform_full|:\index{rhd.par!character outformfull@\verb/character outform_full/} \\
The format (see Sect.~\ref{s:UIO_data_representation}) of the \verb|full| model files
can be chosen e.g.\ with
\begin{verbatim}
character outform_full f=A80 b=80 n='Output file format' &
  c0='formatted/unformatted'
unformatted
\end{verbatim}
Allowed values are
\begin{itemize}
\item \verb|unformatted|: (default) fast compact (possibly machine-dependent) output:
                          strongly recommended
\item \verb|formatted|: slow (machine-independent) output, big files
\end{itemize}

\item \verb|character outconv_full|:\index{rhd.par!character outconvfull@\verb/character outconv_full/} \\
The conversion type (see Sect.~\ref{s:UIO_data_representation}) of the  \verb|full| model files
can be specified e.g.\ with
\begin{verbatim}
character outconv_full f=A80 b=80 n='Output file conversion' &
  c0='ieee_4/ieee_8/crayxmp_8/native'
ieee_4
\end{verbatim}
The allowed values depend on the machine.
Leaving this field empty means that the default is chosen that is build into the local UIO module.
If the type \verb|ieee_4| is supported (which is always the case, so far) it should be chosen.


\item \verb|character outform_mean|:\index{rhd.par!character outformmean@\verb/character outform_mean/} \\
The format (see Sect.~\ref{s:UIO_data_representation}) of the additional data files
can be chosen e.g.\ with
\begin{verbatim}
character outform_mean f=A80 b=80 n='Output file format' &
  c0='formatted/unformatted'
unformatted
\end{verbatim}
Allowed values are
\begin{itemize}
\item \verb|unformatted|: (default) fast compact (possibly machine-dependent) output:
                          strongly recommended
\item \verb|formatted|: slow (machine-independent) output, big files
\end{itemize}

\item \verb|character outconv_mean|:\index{rhd.par!character outconvmean@\verb/character outconv_mean/} \\
The conversion type (see Sect.~\ref{s:UIO_data_representation}) of the additional data files
can be specified e.g.\ with
\begin{verbatim}
character outconv_mean f=A80 b=80 n='Output file conversion' &
  c0='ieee_4/ieee_8/crayxmp_8/native'
ieee_4
\end{verbatim}
The allowed values depend on the machine.
Leaving this field empty means that the default is chosen that is build into the local UIO module.
If the type \verb|ieee_4| is supported (which is always the case, so far) it should be chosen.


%\item \verb||:\index{rhd.par!@\verb//} \\
%\begin{verbatim}
%\end{verbatim}
%Allowed values are
%\begin{itemize}
%\item \verb||:
%\end{itemize}

\end{itemize}


%--------------------------------------------------------------------------------------------------
\subsubsection{Additional Information, Obsolete and Test Parameters}

\begin{itemize}

\item \verb|real abux|:\index{rhd.par!real abux@\verb/real abux/} \\
This optional information parameter can be specified with
\begin{verbatim}
real abux f=E15.8 b=4 n='hydrogen abundance (number fraction)' u=1 &
              c0='standard solar mixture'
 0.90851003E+00
\end{verbatim}
It has no practical consequences because the actually used
chemical composition is determined by the files for equation of state and opacity.

\item \verb|real abuy|:\index{rhd.par!real abuy@\verb/real abuy/} \\
This optional information parameter can be specified with
\begin{verbatim}
real abuy f=E15.8 b=4 n='helium abundance (number fraction)'   u=1 &
          c0='standard solar mixture'
 0.90850003E-01
\end{verbatim}
It has no practical consequences because the actually used
chemical composition is determined by the files for equation of state and opacity.

\item \verb|real qmol|:\index{rhd.par!real qmol@\verb/real qmol/} \\
This optional information parameter can be specified with
\begin{verbatim}
real qmol f=E15.8 b=4 n='mean molecular weight'                u=u &
          c0='standard solar mixture'
 0.13018000E+01
\end{verbatim}
It has no practical consequences because the actually used
chemical composition is determined by the files for equation of state and opacity.

\item \verb|real gamma|:\index{rhd.par!real gamma@\verb/real gamma/} \\
This optional information parameter can be specified with
\begin{verbatim}
real gamma f=E15.8 b=4 n='Adiabatic coefficient'               u=1 &
          c0='0.0/1.6666666666666/1.4'
 0.0
\end{verbatim}
It has no practical consequences because the actually used
chemical composition is determined by the files for equation of state and opacity.


\item \verb|gravcorr_terms|:\index{rhd.par!character gravcorrterms@\verb/character gravcorr_terms/} \\
In former versions of COBOLD the type of the coupling of gravity into the Roe solver
could be specified with
\begin{verbatim}
character gravcorr_terms  f=A80 b=80 &
  n='Type of gravity correction in Roe solver' &
  c0='off0/default0/default/default2/default3'
default5
\end{verbatim}
In recent versions this coupling has to be specified at compile time
with the switch \verb|rhd_hyd_gravcorr_p01|,
see Sect.~\ref{s:rhd_hyd_gravcorr_p01}


\item \verb|real c_test1|:\index{rhd.par!real ctest1@\verb/real c_test1/} \\
As test, the density in the outer extrapolated layers can be limited (lower boundary)
e.g.\ by
\begin{verbatim}
real c_test1 f=E15.8 b=4 n='rho_min' u=g/cm^3
1.0E-25
\end{verbatim}


\item \verb|real c_visneu1|:\index{rhd.par!real cvisneu1@\verb/real c_visneu1/} \\
\begin{verbatim}
real c_visneu1 f=E15.8 b=4 &
    n='Linear viscosity parameter (von Neumann-Richtmyer type)'   u=1
0.0
\end{verbatim}

\item \verb|real c_visneu2|:\index{rhd.par!real cvisneu2@\verb/real c_visneu2/} \\
\begin{verbatim}
real c_visneu2 f=E15.8 b=4 &
    n='Quadratic viscosity parameter (von Neumann-Richtmyer type)' u=1
0.0
\end{verbatim}


\item \verb|integer n_radthickpoint|:\index{rhd.par!integer nradthickpoint@\verb/integer n_radthickpoint/} \\
The \verb|LHDrad| module partly supports periodic boundaries (not complete yet, do not use!).
In this version the lower part of the model can be computed in diffusion approximation.
The number of points in diffusion approximation can be set with e.g.\
\begin{verbatim}
integer n_radthickpoint f=I4 b=4 &
  n='Number of grid points with optically thick (diff.) approximation' &
  c0='0: no diffusion approximation'
0
\end{verbatim}
Setting this value to \verb|0| means that the diffusion approximation is not used
in any part of the model.


\item \verb|real c_radkappasmooth|:\index{rhd.par!real c_radkappasmooth@\verb/real c_radkappasmooth/} \\
In the \verb|LHDrad| module the opacity along each ray can be smoothed.
The amount of smoothing can be set e.g.\ with
\begin{verbatim}
real c_radkappasmooth f=E15.8 b=4 n='Opacity smoothing parameter' u=1 &
    c0='0.0: no smoothing, 0.25: light smoothing, 0.666: strong smoothing'
0.0
\end{verbatim}
The smoothing can perhaps reduce the noise in the intensity images somewhat but
has no general beneficial effect and should usually not be used.

\item \verb|real c_radtsmooth|:\index{rhd.par!real cradtsmooth@\verb/real c_radtsmooth/} \\
In the \verb|LHDrad| module the 3D temperature array can be smoothed.
The amount of smoothing can be set e.g.\ with
\begin{verbatim}
real c_radtsmooth f=E15.8 b=4 n='Temperature smoothing parameter' u=1 &
    c0='0.0: no smoothing, 0.5: reasonable smoothing, 1.0: max. smoothing'
0.0
\end{verbatim}
The smoothing can sometimes reduce the noise in the intensity images
but causes/amplifies some anomalies of the radiative Greens function:
Some cool cell just above the sharp sub-photospheric temperature drop are not heated but cool
further down. Negative temperature spikes may result.
This smoothing should not be used anymore.


\item \verb|character radpressure|:\index{rhd.par!character radpressure@\verb/character radpressure/} \\
In the \verb|LHDrad| module
there exists a simple prescription for the radiative pressure
(reasonable in the optically thin)
which can be activated with
\begin{verbatim}
character radpressure f=A80 b=80 n='Radiation pressure mode' &
  c0='on/off'
on
\end{verbatim}
Allowed values are
\begin{itemize}
\item \verb|on|: Radiation pressure on.
\item \verb|off|: Radiation pressure off.
\end{itemize}
The scheme is pretty slow and wrong in the optically thick.
Do not use!


\item \verb|real c_radtintminfac|:\index{rhd.par!real cradtintminfac@\verb/real c_radtintminfac/} \\
In the \verb|LHDrad| module:
The fraction the interpolated temperature (at a point on the ray)
may exceed the minimum temperature at its four neighbors on the HD grid
can be set e.g.\ with
\begin{verbatim}
real c_radtintminfac f=E15.8 b=4 &
  n='Temperature interpolation parameter' u=1 &
  c0='<1.0: only bilinear, 1.1: reasonable weighting between min. und bil.'
0.0
\end{verbatim}
The introduction of this parameter was an attempt to reduce the negative (cooling)
effect of a single hot cell on its cool neighbors.
It should be switched off e.g.\ by setting it to \verb|0.0|.


\item \verb|integer dtimestep_out_fine|:\index{rhd.par!integer dtimestepoutfine@\verb/integer dtimestep_out_fine/} \\
This parameter can be specified but there is no corresponding output file in COBOLD yet.
\begin{verbatim}
integer dtimestep_out_fine f=I4 b=4 n='Output time step number'       u=1 &
  c0='dtimestep_out_fine<0 => no output'
-1
\end{verbatim}

\item \verb|character outfile_fine|:\index{rhd.par!character outfilefine@\verb/character outfile_fine/} \\
The name of the file for the output of additional information
at regular (small) intervals
can be specified with e.g.\
\begin{verbatim}
character outfile_fine f=A80 b=80 n='Output file name'
rhd.fine
\end{verbatim}
Leaving it empty means that no file of this type is written.
Specifying it means the same (yet).

\item \verb|character outform_fine|:\index{rhd.par!character outformfine@\verb/character outform_fine/} \\
The format (see Sect.~\ref{s:UIO_data_representation}) of the files with frequent output
can be chosen e.g.\ with
\begin{verbatim}
character outform_fine f=A80 b=80 n='Output file format' &
  c0='formatted/unformatted'
unformatted
\end{verbatim}
Allowed values are
\begin{itemize}
\item \verb|unformatted|: (default) fast compact (possibly machine-dependent) output:
                          strongly recommended
\item \verb|formatted|: slow (machine-independent) output, big files
\end{itemize}
This parameter can be specified but there is no corresponding output file in COBOLD yet.

\item \verb|character outconv_fine|:\index{rhd.par!character outconvfine@\verb/character outconv_fine/} \\
The conversion type (see Sect.~\ref{s:UIO_data_representation}) of the files with frequent output
can be specified e.g.\ with
\begin{verbatim}
character outconv_fine f=A80 b=80 n='Output file conversion' &
  c0='ieee_4/ieee_8/crayxmp_8/native'
ieee_4
\end{verbatim}
The allowed values depend on the machine.
Leaving this field empty means that the default is chosen that is build into the local UIO module.
If the type \verb|ieee_4| is supported (which is always the case, so far) it should be chosen.
This parameter can be specified but there is no corresponding output file in COBOLD yet.

\end{itemize}

\index{rhd.par|)}


%--------------------------------------------------------------------------------------------------
\subsection{Additional Control Files: rhd.stop and rhd.cont file}\index{rhd.cont}\index{rhd.stop}

Before each time step COBOLD checks in the working directory
whether the file \verb|rhd.stop| exists.
If it has been generated (e.g.\ with \verb|touch rhd.stop|),
the code exits gracefully, i.e.\ it produces a
proper final model, which can be used to restart the code.
This method of stopping a simulation is to be preferred over
a simple \verb|kill| or \verb|qdel| command because it allows
to analyze the state of the model just at the end of the simulation
and a smooth restart.

Before the restart the \verb|rhd.stop| file has to be deleted!
The simulation can be continued by just initiating a new run.
If the file \verb|rhd.cont| exists at the beginning of a
simulation, the code tries to resume an interrupted computation:
The initial model will not be taken from the start model file
(\verb|infile_start|) but from the final model (\verb|outfile_end|).
The data for the full and the mean file is not written into new files
but will be appended to the existing ones.

In this way a simulation can be interrupted and continued in a fairly
safe way. It is possible to analyze the final model and to changes
values in the parameter file.
Keep in mind that after a restart with \verb|rhd.cont| the specifications
about the length of the job (e.g.\ the number of time steps) will be
counted from the restart point and not from the beginning of the original
simulation.

To interrupt a job with \verb|rhd.stop| can be very handy.
The continuation with \verb|rhd.cont| and the old parameter file
is not to be preferred over an ordinary restart with a new parameter file.


%==================================================================================================
\section{Running a Simulation}

%--------------------------------------------------------------------------------------------------
\subsection{Quickstart: How to run COBOLD\label{s:quickstart_runCOBOLD}}

The generation of a start file and the modification of the parameter file is a somewhat
complex process. In short, the following steps have to be performed.

\begin{enumerate}

\item Produce an executable \verb|rhd.exe| (see Sect.~\ref{s:quickstart_compile})
   and put it into your working directory.

\item Choose a start model (e.g.\ the final model of an earlier simulation
  or a model produced with an IDL routine).

\item Edit the parameter file \verb|rhd.par|:
  typically, you will start with an existing file and edit it.
  You should check that the paths and names of EOS, opacity, and start file are set correctly
  (Watch the username!).
  For details about the parameter file see Sect.~\ref{s:quickstart_parameterfile}.

\item Start the simulation with \\
\verb|nice nohup rhd.exe > rhd.out &|

\item You can see how the simulation proceeds with \\
\verb|tail -f rhd.out|

\item The other data files usually are in a binary format (this can be changed to ASCII ``formatted''
in \verb|rhd.par|).
Their contents can be read and analyzed with IDL routines (see Sect.~\ref{s:uio_dataset_rd}).

\end{enumerate}

For machines with batch queue (CRAYs in Kiel, SUN1 in Uppsala) there is the script (originally) from
Hans-G\"{u}nter Ludwig, which can handle an entire sequence of simulations.


%--------------------------------------------------------------------------------------------------
\subsection{Running COBOLD on a Machine with Batch System}\index{batch queue}

From Sven's manual: ...


%==================================================================================================
\section{Data Analysis with IDL\label{s:IDL}}\index{IDL}


In this section some basic commands for handling COBOLD data in IDL
are described.\\
\ \\
{\bf NOTE: Before using IDL the environment variables for the
  COBOLD paths should have been set. Use setarcdeppaths.sh (or .ksh,
  .csh) for this purpose.}\\
\ \\
%{\bf Subsections:}

%--------------------------------------------------------------------------------
\subsection{Preparations}
We recommend to create an initialisation file (e.g. named \ttfamily
start.pro\normalfont\,) which should be called after starting IDL
(e.g. \ttfamily @start\normalfont\,). 
This is necessary to define relevant paths of IDL subroutines and to
provided the UIO package. 
Thus, the file should contain the following: \\
\ \\
\ttfamily
; --- Add user IDL directory to search path ---\\
addpath=expand\_path('+\$UIOPATH/idl') \\
addpath=addpath+':'+expand\_path('+\$HOME/HYDRO/IDL/rhdpro') \\
if strtrim(addpath,2) ne '' then !path=addpath+':'+!path\\
delvar, addpath\\
; --- Initialize uio-routines ---\\
uio\_init, progrm='by hand'\\
\normalfont
\ \\
%--------------------------------------------------------------------------------
\subsection{COBOLD data in IDL}
Important to know is that all operations can be performed in the
command line of IDL. This allows an interactive processing of COBOLD
data. 
Moreover, there are already prepared IDL scripts for this purpose but
most of them are rather complex and still have to be edited (e.g.
changing file names). 
For the beginning it is more clear to use single commands.  
We give a short overview of some essential commands.
%----------------------------------------
\subsubsection{Loading the parameter file}
\ttfamily
IDL> parfile='mymodel.par'\\
IDL> par=uio\_struct\_rd(parfile)\\
\normalfont
\ \\
All control parameters are provided in the structure \ttfamily
PAR\normalfont. 
%----------------------------------------
\subsubsection{Loading COBOLD data (.full, .sta, .end)} 
\ttfamily
IDL> modelfile='/home/user/mymodel.full' \& n=0\\
IDL> ful=uio\_dataset\_rd(modelfile,n=n)\\
\ \\
\normalfont
First the name and full path (if not in the actual directory) of the
model file and the wanted time step should be defined. Here, time
step means the consecutive number of the model snapshot in the file. 
Declaring a time step number greater than the number of snapshots
contained in the file will cause an error.\\ 
Otherwise all data of the particular time step \ttfamily
n\normalfont\, will be provided in the structure 
werden in der Struktur \ttfamily FUL\normalfont.\\
Loading more than one timestep from the same file could be achieved as 
follows: \\
\ \\
\ttfamily
IDL> uio\_openrd, nc, modelfile, outstr, ierr \\
IDL> for i=0,ntime-1 do begin \&\$\\ 
IDL>   ful=uio\_dataset\_rd(modelfile, channel=nc,ierr=ierr, outstr=err\_msg) \&\$\\ 
IDL> endfor \&\$ \\
IDL> uio\_closrd, nc \\
\normalfont
Again this operation would cause an error if the wanted time step is
not contained in the file. 
Via checking the error flag \ttfamily ierr\normalfont\, of the routine \ttfamily
uio\_dataset\_rd\normalfont\,  such errors can be avoided.  
This way it is unnecessary to know exactly of how many time steps the
model file consists. \\
\ \\
\ttfamily
IDL> uio\_openrd, nc, modelfile, outstr, ierr \\
IDL> i=0 \\
IDL> repeat begin \&\$ \\
IDL> \quad ful=uio\_dataset\_rd(modelfile, channel=nc,ierr=ierr, outstr=err\_msg)  \&\$\\ 
IDL> \quad if (ierr eq 0) then begin \&\$ \\
IDL> \quad \quad ;--- hier Daten bearbeiten oder in anderer Variable speichern ---\\
IDL> \quad \quad i=i+1 \&\$ \\
IDL> \quad endif else begin \&\$\\ 
IDL> \quad \quad print,'IDL> Reached EOF.' \&\$\\ 
IDL> \quad endelse \&\$ \\
IDL> endrep until (ierr ne 0) or (EOF(nc)) \\ 
IDL> uio\_closrd, nc  
\normalfont
%----------------------------------------
\subsubsection{Loading the equation of state}
\label{sec.loadeos}
\ttfamily
     IDL> eosfile='../eos/dat/'+par.eosfile\\
     IDL> tabinter\_rdcoeff,eosfile, eos \\
\normalfont
\ \\
The table for the equation of state is provided in the structure
\ttfamily EOS\normalfont. \\
{\bf NOTE:  Always check file name and path!}
%----------------------------------------
\subsubsection{Loading the opacity table}
\label{sec.loadopa}
\ttfamily
     IDL> opafile='../opa/dat/'+par.opafile\\
     IDL> dfopta,opafile\\
\normalfont
\ \\
The opacity table will be stored as common block \ttfamily
OPTA\_COMMON\normalfont. \\
{\bf NOTE:  Always check file name and path!}
%----------------------------------------
\subsubsection{Computation of deduced quantities}
\label{sec.eosbox}
After having read the model data (\ttfamily FUL\normalfont) 
and the tables for the equation of state (\ttfamily EOS\normalfont)
and opacity (\ttfamily OPTA\_COMMON\normalfont) (see \ref{sec.loadeos},
\ref{sec.loadopa}), more quantities can be calculated: \\
\ \\
\ttfamily
IDL> eosbox, ful, eos=eos , /opa ,ierror=ierror \\
\normalfont
This operation adds the tags 
\ttfamily EOS \normalfont 
and \ttfamily OPA \normalfont to the data structure \ttfamily
FUL\normalfont\, which contain more quantities like e.g. the
temperature (see Sect.\ref{sec.idldatastruct}).
%--------------------------------------------------------------------------------
\subsection{IDL-Datenstruktur}
\label{sec.idldatastruct}
The data structure \ttfamily FUL \normalfont  contains the following
variables and substructures (use \normalfont
help,/str,ful\normalfont\, to get this information):\\ 
\ \\
\ttfamily
** Structure <8287a0c>, 9 tags, length=78404128, refs=1:\\
   TYPE            STRING    'uio'\\
   HEAD            STRUCT    -> <Anonymous> Array[1]\\
   DATASET\_ID      STRING    'single\_box'\\
   MODELTIME       FLOAT           10050.1\\
   MODELITIME      LONG             64088\\
   DTIME           FLOAT          0.176381\\
   TIME\_OUT\_FULL\_LAST\\
                   FLOAT     =       10050.1\\
   TIME\_OUT\_MEAN\_LAST\\
                   FLOAT     =       10040.0\\
   Z               STRUCT    -> <Anonymous> Array[1]\\
\normalfont
If the command in Sect.\ref{sec.eosbox} has been performed, the
following substructures are present: \\
\ \\
\ttfamily
   EOS             STRUCT    -> <Anonymous> Array[1]\\
   OPA             STRUCT    -> <Anonymous> Array[1]\\
\normalfont
The substructure \ttfamily FUL.Z\normalfont\, contains the original
data arrays from the model file like the spatial axes, density
\ttfamily rho\normalfont, 
internal energy \ttfamily ei\normalfont, and the three spatial
components of the velocity (\ttfamily v1\normalfont, \ttfamily v2\normalfont,
\ttfamily v3\normalfont):\\
\ \\ 
\ttfamily
** Structure <8274184>, 16 tags, length=78403900, refs=2:\\
   TYPE            STRING    'uio'\\
   BOX\_ID          STRING    'z'\\
   DIMENSION       LONG      Array[2, 3]\\
   TIME            FLOAT           10050.1\\
   ITIME           LONG             64088\\
   XC1             FLOAT     Array[140, 1, 1]\\
   XC2             FLOAT     Array[1, 140, 1]\\
   XC3             FLOAT     Array[1, 1, 200]\\
   XB1             FLOAT     Array[141, 1, 1]\\
   XB2             FLOAT     Array[1, 141, 1]\\
   XB3             FLOAT     Array[1, 1, 201]\\
   RHO             FLOAT     Array[140, 140, 200]\\
   EI              FLOAT     Array[140, 140, 200]\\
   V1              FLOAT     Array[140, 140, 200]\\
   V2              FLOAT     Array[140, 140, 200]\\
   V3              FLOAT     Array[140, 140, 200]\\
\normalfont
\ \\
{\bf Spatial axes: } 
\ttfamily XC1\normalfont,
\ttfamily XC2\normalfont,
\ttfamily XC3\normalfont,
\ttfamily XB1\normalfont,
\ttfamily XB2\normalfont,
\ttfamily XB3\normalfont): 
The indices stand for 
\ttfamily1\normalfont:x ,
\ttfamily2\normalfont:y, 
\ttfamily3\normalfont:z. \ttfamily C \normalfont for the grid cell
centre, \ttfamily B \normalfont for the boundaries. 
Most of the quantities are defined for the cell centres. 
In case of doubt, this can be found out by checking the array
dimensions.\\  
The substructure \ttfamily FUL.EOS \normalfont contains important
quantities like the temperature \ttfamily T\normalfont, 
gas pressure \ttfamily P\normalfont, entropy \ttfamily S\normalfont: \\
\ \\
\ttfamily
** Structure <826a03c>, 7 tags, length=109760000, refs=2:\\
   P               FLOAT     Array[140, 140, 200]\\
   DPDRHO          FLOAT     Array[140, 140, 200]\\
   DPDEI           FLOAT     Array[140, 140, 200]\\
   T               FLOAT     Array[140, 140, 200]\\
   DTDEI           FLOAT     Array[140, 140, 200]\\
   S               FLOAT     Array[140, 140, 200]\\
   CS              FLOAT     Array[140, 140, 200]\\
\normalfont
The substructure \ttfamily FUL.OPA  \normalfont only contains the
opacity \ttfamily KAPPA \normalfont: \\
\ \\
\ttfamily
** Structure <826a5b4>, 1 tags, length=15680000, refs=2:\\
   KAPPA           FLOAT     Array[140, 140, 200]\\
\normalfont
%--------------------------------------------------------------------------------
\subsection{More IDL routines}
In the directory \ttfamily IDL/rhdpro \normalfont a lot of useful
routines can be found which can be used for further processing and
visualisation of COBOLD data. 
For the visualisation of 2-D models or 2-D data slices in general we
recommend \ttfamily plotfield.pro\normalfont. With \ttfamily combox.pro
\normalfont (unfortunately not commented yet) 
further quantities can be calculated.\\ 
Furthermore, we currently develop a widget-based analysis tool called 
{\bf COBOLD~AT} (abbrev.: CAT) which will help to work with COBOLD
data without having to write and edit own IDL code. 
The routines are stored (if available) in the directory \ttfamily
IDL/COBOLDAT \normalfont and have to be started with \ttfamily
@cat\normalfont. A more detailed documentation is planned. 
%


\clearpage
%==================================================================================================
\section{Glossary\label{s:glossary}}

\begin{itemize}

\item {\bf COBOLD}\index{COBOLD} or {\bf CO$^5$BOLD} is the short form of
``COnservative COde for the COmputation of COmpressible COnvection
in a BOx of L Dimensions with l=2,3''.

\item {\bf UIO}: the ``Universal Input Output'' format.
  It is used in COBOLD for parameter, model, and EOS files.

\end{itemize}


%==================================================================================================
\printindex

\end{document}
