\documentclass[preprint,12pt]{elsarticle}
%
\journal{J. Quant. Spectrosc. Radiat. Transfer}
%
\bibliographystyle{unsrt}


%- Extra packages
%
\usepackage{url}
\usepackage{listings}
\usepackage{color}
\usepackage{lineno}  

\lstset{language=,
        basicstyle=\scriptsize\ttfamily,
        backgroundcolor=\color[rgb]{.9,.9,.9}}

%- Special commands
%
\newcommand{\outline}[1]{
\hspace{0.05\linewidth}%
\begin{minipage}[c]{0.9\linewidth}
  \texttt{#1}
\end{minipage}\vspace{2ex}\\
}
\newcommand{\todo}[1]{[* #1 *]}


%- Symbol definitions
%
\def\ARTS{ARTS}       % To easily change how we write ARTS
\def\V1{ARTS-1}       % To easily change how we write ARTS-1.0.x
%
\def\AUG{AUG}         % ARTS user guide
\def\ADG{ADG}         % ARTS developer guide       
\def\ATD{ATD}         % ARTS theory document       
%
\newcommand{\unit}[1]{{\it#1}}
%
% Use the symbol definitions from AUG as far as possible
\input{symbol_defs}
\renewcommand{\PDir}  {\ensuremath{{\bf \hat{n}}}}
\newcommand{\PPos}    {\ensuremath{{\bf r}}}
\newcommand{\Iv}      {\ensuremath{I_v}}
\newcommand{\Ih}      {\ensuremath{I_h}}
\newcommand{\Ipff}    {\ensuremath{I_{+45^\circ}}}
\newcommand{\Imff}    {\ensuremath{I_{-45^\circ}}}
\newcommand{\Irhc}    {\ensuremath{I_{rhc}}}
\newcommand{\Ilhc}    {\ensuremath{I_{lhc}}}
\newcommand{\BT}      {\aTmp{B}}




\begin{document}

\begin{frontmatter}

%--- Titel + authors ----------------------------------------------------------
\title{ARTS, the Atmospheric Radiative Transfer Simulator, Version 2}

\author[chalmers]{P. Eriksson\corref{cors}}
\ead{patrick.eriksson@chalmers.se}

\author[ltu]{S. A. Buehler\corref{cors}}
\ead{sbuehler@ltu.se}

\author[metservice]{C. P. Davis}
\author[lmu]{C. Emde}
\author[ltu]{O. Lemke}

\address[chalmers]{%
  Department of Earth and Space Sciences,
  Chalmers University of Technology,\\
  SE-41296 Gothenburg,
  Sweden
}
\address[ltu]{%
  Department of Space Science,
  Lule\aa\ University of Technology,
  Space Campus 1,
  SE-98128 Kiruna,
  Sweden
}
\address[metservice]{%
  Meteorological Service of New Zealand Ltd.,
  Wellington 6012,
  New Zealand
}

\address[lmu]{%
  Meteorological Institute,
  Ludwig-Maximilians-Universit\"at,
  Theresienstr. 37,\\
  D-80333 Munich,
  Germany
}
  
\cortext[cors]{Corresponding authors}




%--- Abstract + keywords -----------------------------------------------------
\begin{abstract}
  The second version of the Atmospheric Radiative Transfer Simulator, \ARTS, is
  introduced. This is a general software package for long wavelength
  radiative transfer simulations, with a focus on passive microwave
  observations. The core part provides a workspace environment, in line with
  script languages. New for this version is an agenda mechanism that gives a
  high degree of modularity. The framework is intended to be as general
  as possible: the polarisation state can be fully described, the model
  atmosphere can be one-dimensional (1D), two-dimensional (2D) or
  three-dimensional (3D), a full description of geoid and surface is possible,
  observation geometries from the ground, from satellite, and from aeroplane or
  balloon are handled, and surface reflection can be treated in simple or
  complex manners. Remote sensing applications are supported by a comprehensive
  and efficient treatment of sensor characteristics. Jacobians which are
  required for many retrieval algorithms can be calculated for the most
  important atmospheric variables in non-scattering conditions. Finally, the
  most prominent feature is the rigorous treatment of scattering that has been
  implemented in two modules: A discrete ordinate iterative approach
  mainly used for 1D atmospheres, and a Monte Carlo approach which is the
  preferred algorithm for 3D atmospheres. \ARTS\ is freely available, and
  maintained as an open source project.
\end{abstract}

\begin{keyword}
%% keywords here, in the form: keyword \sep keyword
atmospheric radiative transfer \sep
emission \sep
polarisation \sep
scattering \sep
sensor modelling \sep
remote sensing

%% PACS codes here, in the form: \PACS code \sep code
\PACS 42.68.Ay \sep 42.68.Mj \sep 42.68.Wt \sep 92.60.Ta
\end{keyword}
\end{frontmatter}

\vspace{2ex}
\noindent {\bf Note to editor and reviewers:} Our plan is to sync the official
release of ARTS-2 with the submission of a final manuscript for this article.
This will essentially be the same as the present version (at the time of
writing, 1.14.122), but for simplicity we write below ARTS-2.0. The remaining
time will primarily be used to fix the last details of the other documentation.
%\todo{Remove this note.}


\linenumbers
\setpagewiselinenumbers

\section{Introduction}
%-----------------------------------------------------------------------------
\label{sec:introduction}
%
\ARTS\ is a free open-source software program that simulates atmospheric
radiative transfer. It focuses on thermal radiation from the microwave to the
infrared spectral range. Version 1.0 of \ARTS\ \citep{buehler:artst:05}, which
handles cases without scattering, was mainly developed between 2000 and 2005.
It is well validated \citep{melsheimer:inter:05,
  buehler06:_radiat_trans_calcul_passiv_microw_satel_sensor_jgr,
  saunders07:_atmos_infrar_sound_airs_jgr} and still used, primarily for the
analysis of ground-based and satellite-based measurements in the
millimetre/submillimetre spectral region \citep[e.g.,][]{Urban20051, john05:_station_comp_acp, john04:_amsu_ozone_grl}. A large part
of its popularity is due to the retrieval software Qpack
\citep{eriksson:qpack:05}, which uses \ARTS\ as the forward model. But \ARTS\
version 1.0 has also been used for the simulation of clear-sky broadband
energy fluxes in the thermal infrared spectral range \citep{buehler:recen:06,
  john:under:06}. This model version is below denoted as \V1.

From 2002, the \ARTS\ developer community became increasingly interested in the
remote sensing of clouds, particularly ice clouds. A main driver was the ESA
mission proposal CIWSIR \citep{buehler:aconc:07}, a submillimetre instrument
for the characterisation of ice clouds, which required a radiative transfer
model that could simulate the scattering by ice particles, including
polarisation effects
\citep{miao03:_potential_of_polarization_measurements,davis07:_3d_pol_sim_acp}.

Another strong driver was the treatment of microwave limb sounders: firstly for
the analysis of cloud-affected data from the MLS and Odin-SMR satellite
instruments. Some studies where ARTS was used in this context are
\citep{davis07:_3d_pol_sim_acp,davis05:_cirrus_induc_polar_ghz_aura,
  eriksson:first:07,rydberg:nonga:09}. Secondly, future limb sensors will
sample the atmosphere more densely in order to increase the `tomographic'
capability. This, and the scattering by clouds demand going beyond a 1D
representation of the atmosphere.

The interest in such atmospheric sounding techniques led to a fork in the
\ARTS\ program development. The most active development shifted to version
1.1.x, which included modules to simulate scattering by cloud particles, and
differed also in other important ways from the original \ARTS\ version. \V1\
was still maintained so that those users that just wanted clear-sky radiative
transfer would have a stable version to use. In the meantime, the new version
with scattering has become complete and stable enough to fully replace the old
version, even for pure clear-sky calculations. We mark this by calling the
latest version \ARTS\ 2.0. The purpose of this article is to present \ARTS\
2.0, and give an overview of its features, strengths, and limitations. In the
remaining text ``\ARTS'' refers to the latest 2.0 version.


\section{Overview}
%-----------------------------------------------------------------------------
\label{sec:overview}

\subsection{Scope}
%
The ambition is to accommodate simulations of any type of passive longwave
observation, and \ARTS\ is designed to have no limitations when it comes
to the representation of polarisation state, atmospheric fields and geometrical
aspects: 
\begin{enumerate}
\item The Stokes formalism is used to describe polarisation
(Sec.~\ref{sec:rtvar}). 
\item The model atmosphere can be represented with a one
(1D), two (2D) or three (3D) dimensional view (Sec.~\ref{sec:modelatm}). 
\item No assumption of a ``flat Earth'', the geoid and the surface are either spherical
(by definition for 1D), or can be given arbitrary shapes (Sec.~\ref{sec:rtvar}).
\item Radiative transfer calculations can be made from any position and along any
direction, as long as the resulting calculations make sense with respect to the
model atmosphere (Sec.~\ref{sec:obsgeom}). 
\end{enumerate}
Individual functions can be limited
to some configurations, for example, the Monte Carlo scattering module
(Sec.~\ref{sec:mc}) is restricted to 3D.

As mentioned, handling of scattering is a primary aim of \ARTS,
where the goal is to allow arbitrary complex scattering properties. This goal
has been reached for surface reflection (Sec.~\ref{sec:surfscat}), but not
completely for particle scattering (Sec.~\ref{sec:optprop}). The development
has so far focused on exact algorithms and the model's strongest side is that
complicated simulations can be performed in a stringent manner. \ARTS\ is thus
primarily a research tool. Speed has not been a primary objective, and
extremely fast, but approximative, algorithms like RTTOV
\cite{saunders99:_rttov_qjrms} are not in the scope of \ARTS.

The software is mainly developed for remote sensing applications, and an
extensive support for inclusion of sensor characteristics is provided
(Sec.~\ref{sec:sensor}). In addition, weighting functions (also called
Jacobians) \cite{rodgers90,rodgers:inver:00} can be obtained for a number of
variables in non-scattering conditions; see further Sec.~\ref{sec:jacs}.

\ARTS\ comes with a small amount of input data. The purpose of these data is to
provide some usage examples, and allow the developers to perform standardised
tests before committing changes of the code. Normally, the user has to provide
the bulk of input data, such as temperatures, volume mixing ratios and
spectroscopic parameters. A noticeable exception is that a number of
``absorption models'' are built into the model (Sec.~\ref{sec:abstable}).
Handling of line coupling requires dedicated absorption models.


\subsection{Other radiative transfer models}
%
Many radiative transfer models have been developed since the 1950s. However, it
is beyond our scope to provide a complete review of radiative transfer codes,
instead we give a short overview of freely available models here which can be
applied in the thermal spectral region. The reader is referred to the
references for more detailed information about the individual model features.

Besides ARTS there are some other comprehensive radiative transfer packages
using modular approaches which can be used for simple clear-sky calculations
but also for more complex calculations including multiple scattering. These
packages often provide several radiative transfer solvers that can be chosen
depending on the application and also functions to convert from micro-physical
properties (e.g. trace gas profiles) to optical properties (e.g. absorption
coefficients). Among these packages are the libRadtran software package
\citep{mayer2005} which covers solar and thermal radiative transfer, the AER
codes \citep{clough05:_atmospheric_jqsrt} including the well-known line-by-line
code LBLRTM, the SHDOM model \citep{Evans1998}, and the EarthCare simulator
(\url{c3vp.org/ECARE/ECARE_sim.html}). Some models focus on specific
spectral regions, the MWMOD model \citep{fuhrhop1998} for example has been
developed for the microwave spectral region and the AMATERASU model for the
THz region \citep{baron08:_amaterasu_nict,mendrok08:_amaterasu_nict}.

There are several specialised models to compute line-by-line absorption
coefficients from spectroscopic databases. These models mostly include
clear-sky radiative transfer but no modules to take into account scattering.
Examples for this kind of model are RFM (\url{www.atm.ox.ac.uk/RFM/}),
and Py4CATS \citep{schreier2003}.

Radiative transfer solvers provide a solution to the radiative transfer
equation for given optical properties using specific methods, e.g. the DISORT
solver based on the discrete ordinate method \citep{stamnes1988,stamnes2000},
the MYSTIC solver based on the Monte Carlo method \citep{mayer2009, emde2010},
and the polradtran solver \citep{Evans1991} based on the doubling-and-adding
method. The DISORT solver is often implemented as one of several solvers in the
comprehensive radiative transfer packages.


\subsection{Documentation}
\label{sec:doc}
%
The efforts to document \ARTS\ focus on the practical usage of the software.
This is mainly achieved through the built-in documentation, that provides a
definition and a basic description of individual variables and methods, as
described in Sec.~\ref{sec:concept}. This documentation can be browsed on-line
at \url{www.sat.ltu.se/arts/docserver}. An introduction to the usage of \ARTS\
on a system level is given by some example cases that are distributed along
with the source code.

This article provides a compact overview of ARTS. A more detailed description
can be found in the three documents of guide type that are distributed with
\ARTS. Model definitions and algorithms are described in more detail in the
`\ARTS\ user guide' (\AUG). Some parts are described further, or solely, by
dedicated research articles
\cite{emde:apoli:04,davis05:_monte_carlo_i3etgrs,eriksson:effic:06,buehler:effic:10}.
The `\ARTS\ development guide' (\ADG) gives practical information for
the source code. Background theory for some core subjects is provided by the
`\ARTS\ theory document' (\ATD). See further \url{www.sat.ltu.se/arts/docs/}. 



\subsection{Technical specifications}
%
\ARTS\ is written in ANSI C/C++. The recommended compiler suite for building
\ARTS\ is the GNU Compiler Collection (gcc/g++) version 4. Although other
compilers can be used to build \ARTS, differences in the scope of the
implementation of the C++ standard might require changes to the source code.
\ARTS\ uses the freely available, open-source build system CMake to create
platform-specific Makefiles. \ARTS\ depends also on the open-source zlib
compression library. Optionally, to build the documentation, \LaTeX\ and
doxygen are needed. To run the automated test cases provided with \ARTS\ the
Python 2 interpreter has to be present. Additionally, the NetCDF library, if
installed, enables support for storing certain data types in the network Common
Data Form. On multi-core/multiprocessor systems \ARTS\ will automatically
utilise parallelisation if the compiler (e.g. GCC 4) provides an OpenMP
interface. All these tools are easily accessible in current Linux distributions
as well as in Mac OS X.

Although packaged versions of the \ARTS\ source code are provided on the
\ARTS\ homepage, it is recommended to obtain the source code directly from
the \ARTS\ subversion repository. This gives instant access to the latest
features and bug fixes. Subversion is a widely used version control system
and available on most platforms. Detailed instructions on how to check out
and compile the \ARTS\ source code can be found on the \ARTS\ homepage at
\url{www.sat.ltu.se/arts/getarts/}.



\subsection{Related tools}
%
Functions for creating input files and for reading output files (for e.g.\
plotting) are provided for two popular higher-level and interactive
environments, Python through PyARTS and Matlab through Atmlab. These packages
provide also additional features. For example, PyARTS allows the calculation of
particle optical properties using the T-matrix code by
\citep{mishchenko02:_scatt_absor_emiss_light_small_partic} and a new version of
Qpack is being implemented inside Atmlab. The packages can be downloaded
from the \ARTS\ home page and are documented separately.






\section{Concept}
%-----------------------------------------------------------------------------
\label{sec:concept}
%

\subsection{\ARTS\ as a scripting language}

One of the main goals in the \ARTS\ development was to make the program as
flexible as possible, so that it can be used for a wide range of applications
and new features can be added in a relatively simple manner. As a result,
\ARTS\ behaves like a scripting language. An \ARTS\ controlfile contains a
sequence of instructions. When \ARTS\ is executed, the controlfile is parsed,
and then the instructions are executed sequentially.

A minimal \ARTS\ controlfile example (the well-known `Hello World' program) is
given in Figure \ref{fig:hello}. In this example, the variable \texttt{s} is
called a \emph{workspace variable}. We use this name to distinguish it from the
variables that appear internally in the \ARTS\ source code. 

%When the context is
%clear, we may sometimes drop the workspace qualifier and refer to it just as a
%variable.

In a similar spirit, the functions \texttt{StringCreate},
\texttt{StringSet}, and \texttt{Print} in the example are called
\emph{workspace methods}.  We use this name to distinguish them from
the functions that appear internally in the \ARTS\ source code. For
brevity, we may sometimes drop the workspace qualifier and refer to
them just as methods.

ARTS consists roughly of three parts. Firstly, the \ARTS\ core contains the
controlfile parser, and the engine that executes the controlfile. This part is
quite compact and constitutes only a small fraction of the total source code.
Secondly, there is a large collection of workspace methods that can be used to
carry out various sub-tasks (at the time of writing approximately 300).
Thirdly, there is a large number of predefined workspace variables (at the time
of writing more than 200). These predefined variables make it easier to set up
controlfiles, since they provide hints on how the different workspace methods
fit together.
% (one method's output will usually be another method's input
%variable).

ARTS has built-in documentation for all workspace methods and variables, which
can be accessed by calling the program with various command line switches
(`-m', `-w', `-i', etc.). A comprehensive list of command line switches and
their effect can be obtained by calling `\texttt{arts -h}'. Below, we will
discuss workspace variables and methods in some more detail and give more
examples.

\subsection{Workspace Variables}

Workspace variables (such as the variable \texttt{s} in Figure
\ref{fig:hello}) are the variables that are manipulated by the
workspace methods during the execution of an \ARTS\
controlfile. 
%Typically, first some variables are set to input values,
%for example by reading data from a file. Some other variables are
%created from these along the way, and eventually also some that hold the
%final result. These can then be saved to files, so that the results can
%be visualized or processed by other programs. 
Workspace variables belong to different \emph{groups} (Index, String, Vector,
Matrix, etc.). 
%These groups are similar to variable \emph{types} in other programing languages. 
The command `\texttt{arts -g}' will
list all groups, at the time of writing there are approximately 60 of them.

As the example in Figure \ref{fig:hello} shows, workspace variables
can be freely created by the user with methods like
\texttt{StringCreate}, \texttt{VectorCreate}, and so
on. Each group has its own create method.

However, in most cases it is not necessary to create new variables in
this way, since a lot of variables are predefined in \ARTS. The command 
`\texttt{arts -w all}' will list all predefined variables, the command
`\texttt{arts -d xx}' will print detailed documentation for variable \texttt{xx}.
As an example, Figure \ref{fig:f_grid} shows the output of the command
`\texttt{arts -d f\_grid}'. Variable \texttt{f\_grid} stores the frequency
grid and is used as input by many workspace methods, for example
those that calculate absorption coefficients. From the built-in
documentation, the command  `\texttt{arts -i f\_grid}' will list all
methods that take \texttt{f\_grid} as input. Conversely, `\texttt{arts -m f\_grid}'
will list all methods that produce \texttt{f\_grid} as output. 



\subsection{Workspace Methods}

As shown in Figure \ref{fig:hello}, workspace method names in an \ARTS\
controlfile are followed by their output and input arguments (workspace
variables) in parentheses. (`\texttt{Print(s)}' prints the content of variable
\texttt{s}.)

From the methods point of view, arguments can be either \emph{output}
or \emph{input}, and additionally, they can be either \emph{specific}
(= referring to a predefined variable) or \emph{generic} (= not
referring to a predefined variable). To illustrate this, Figure
\ref{fig:WriteXML} shows the built-in documentation for method
\texttt{WriteXML}, the most common method to write \ARTS\ variables to a
file. The list at the bottom of the documentation shows that
\texttt{output\_file\_format} is a specific input argument, and that
\texttt{v} and \texttt{filename} are generic input arguments.

What this means is that \texttt{output\_file\_format} already
automatically exists as a variable, whereas \texttt{v} and
\texttt{filename} do not. Command `\texttt{arts -d output\_file\_format}'
will provide documentation on the variable and list the allowed values.

The predefined variables, combined with specific method arguments, are
meant to help in combining methods into meaningful
calculations. Predefined variables are typically relevant for more than one method. For example, variable \texttt{output\_file\_format} can be used
to change the format of all produced files at the same time. However,
the use of a specific variable in the controlfile is not mandatory, so
`\texttt{WriteXML( output\_file\_format, v, "test.xml")}',
`\texttt{WriteXML( "ascii", v, "test.xml" )}', and
`\texttt{WriteXML( my\_format, v, "test.xml" )}' are all allowed. (But in
the last example the variable \texttt{my\_format} must have been defined
before.)

Besides the variable names, the built-in documentation also lists the
allowed variable groups (or types). In the example, the groups for workspace variable \texttt{v} are `Any', which means that \texttt{v} can belong to any of the
known groups. The group for \texttt{filename} is `String', which
means that a string is expected here. Method arguments can be a literal, as in
`\texttt{WriteXML( "ascii", v, "test.xml" )}', or a variable, as in
`\texttt{WriteXML( "ascii", v, s )}', where in the latter case variable
\texttt{s} must be already defined.

The built-in documentation further states that argument \texttt{filename}
has a default value (in this case the empty string). Because of this,
the argument can actually be omitted, so 
`\texttt{WriteXML( "ascii", v )}' will also work.

One additional rule has to be mentioned here. If all arguments to a
method are specific, and the user wants to use all the predefined
variables, then the entire argument list (including parentheses) may
be omitted. 

\subsection{Agendas}
\label{sec:agendas}

Agendas are a special group of workspace variables, which allow to
modify how a calculation is performed. A variable of group agenda
holds a list of workspace methods. It can be executed, which means
that the methods it contains are executed one after another.

Figure \ref{fig:agendas} gives an example, for the agenda
\texttt{abs\_scalar\_gas\_agenda}. Several radiative transfer methods
use this agenda as input variable. When they need local absorption
coefficients for a point in the atmosphere, they execute the agenda
with the local pressure, temperature, and trace gas volume mixing
ratio values as inputs. The agenda then provides absorption
coefficients as output. 

The bottom of Figure \ref{fig:agendas} shows two different ways how this agenda
could be defined in the controlfile. In the first case a line-by-line
absorption calculation is performed when the agenda is executed (every time
absorption coefficients are needed). In the second case the absorption
coefficients are extracted from a pre-calculated lookup table.




\section{Model definitions and input}
%-----------------------------------------------------------------------------
\label{sec:input}
%
This section gives some basic model definitions, and comments on mandatory
and other input of general character required for a model run. Units used for
ARTS specific input and output files, as well as internal definitions of
variables, follow the SI system.

\subsection{Radiative transfer, nomenclature and variables}
\label{sec:rtvar}
%

\ARTS\ describes (spectral) radiances using the Stokes vector, \StoVec. The
calculations can be selected to treat one to four elements of the Stokes
vector, all methods adjust automatically to this choice. The phrase ``scalar
radiative transfer'' refers to the case when just the first Stokes vector
element is considered. The other options are all termed as vector radiative
transfer. The four elements of the Stokes vector, $\StoVec=[I,Q,U,V]^T$, are
defined as:
\begin{eqnarray}
  I &=&   \Iv + \Ih = \Ipff + \Imff = \Ilhc + \Irhc,  \label{eq:I}\\
  Q &=&   \Iv - \Ih,                                  \label{eq:Q}\\
  U &=&   \Ipff - \Imff,                              \label{eq:U}\\
  V &=&   \Ilhc - \Irhc,                              \label{eq:V}
\end{eqnarray}
where \Iv, \Ih, \Ipff, and \Imff\ are the intensity of the component linearly
polarised at the vertical, horizontal, +45\degree\ and -45\degree\ direction,
respectively, and \Irhc, and \Ilhc\ are the intensity for the right- and
left-hand circular components. All intensities are time averaged values. Units
are discussed in Sec.~\ref{sec:units}. The definition used here follows
\cite{mishchenko02:_scatt_absor_emiss_light_small_partic}, see also \ATD.

Accordingly, $I$ is the total radiance and the other Stokes
elements give the difference between two orthogonal components. Individual
components are extracted as combinations of $I$ and the other elements, e.g.
\begin{equation}
  \label{eq:Iv}
  \Iv = (I+Q)/2.
\end{equation}

The standard vector radiative transfer equation (VRTE) for cases involving
multiple scattering is \cite{mishchenko02:_scatt_absor_emiss_light_small_partic}
 \begin{eqnarray}
    \label{eq:VRTE}
  \frac {\DiffD\StoVec(\Frq,\PPos,\PDir)}{\DiffD s} =
    &{}-\ExtMat(\Frq,\PPos,\PDir) \StoVec(\Frq,\PPos,\PDir) +
    \AbsVec(\Frq,\PPos,\PDir) \rlap{$B(\Frq,\PPos)$} \\ \nonumber
    &{}+ \int_{4\pi} \DiffD\PDir' \PhaMat(\Frq,\PPos,\PDir,\PDir')
    \StoVec(\Frq,\PPos,\PDir'),
\end{eqnarray}
where \Frq\ is frequency, \PPos\ represents the atmospheric position, \PDir\ is
the propagation direction (at \PPos), $s$ is distance along \PDir, $\ExtMat$ is
the extinction matrix, $\AbsVec$ is the absorption vector, $B$ is the Planck
function and $\PhaMat$ is the phase matrix. This equation assumes local
thermodynamic equilibrium and that the scattering events can be treated as
incoherent. 

Equation~\ref{eq:VRTE}, or some simplified version of it
(Sec.~\ref{sec:csrte}), is solved, giving simulated radiances. The
inclusion of sensor characteristics requires that radiative transfer
calculations are performed for a set of monochromatic frequencies, the
frequency grid, and a number of pencil beams (Sec.~\ref{sec:sensor}). The
frequency grid is a primary input variable; it determines the
frequencies for which absorption and radiative transfer are calculated. Any selection
procedure for the frequency grid must be performed as a pre-calculation. The
propagation through the atmosphere of the unscattered, but possibly refracted,
pencil beam is below denoted as the propagation path.



\subsection{Atmospheric and surface variables}
\label{sec:modelatm}
%
Atmospheric quantities can be defined to vary in one, two and three dimensions.
The atmospheric dimensionality can thus be 1D, 2D or 3D. Pressure is the
vertical coordinate in all cases. The two horizontal dimensions for 3D coincide
with standard latitude and longitude. The second dimension for 2D is for
simplicity denoted as latitude, but has no direct geophysical interpretation.
This “latitude” can, for example, represent the angular distance inside the
plane of a satellite orbit.

Each (active) atmospheric dimension has an associated grid. This gives an
atmospheric grid mesh, for which temperature, geometrical altitude (above the
geoid) and the volume mixing ratio (VMR) for the species must be specified.
Some more details are given in Fig.\ \ref{fig:gridbox}. The basic definition of
the model atmosphere is completed by the geoid radius and the surface altitude,
as a function of latitude and longitude.

The minimum value of the pressure grid sets the upper limit of the model
atmosphere (vacuum assumed above). The lower limit for the calculation is set
by the ground, which constitutes a surface (with arbitrary shape) at the
boundary or inside the atmospheric domain. No vertical gap between the ground
surface and the atmosphere is allowed. The atmosphere is undefined outside the
latitude and longitude grid ranges.


\subsection{Radiative transfer domains}
\label{sec:cloubox}
%
The default assumptions are that scattering can be neglected, and that
absorption and emission are unpolarised. More complicated calculation
conditions are restricted to a special domain of the atmosphere,
introduced initially to handle cloud scattering and consequently called
the ``cloudbox''.  For simplicity, the calculations outside the cloudbox are
denoted as ``clear sky''.

The vertical limits of the cloudbox are two pressure surfaces. For 1D, the
cloudbox extends around the model planet, as implied by the spherical symmetry
for this case. For higher atmospheric dimensions, the horizontal limits are
found at latitude and longitude grid points. A calculation flag controls if the
cloudbox is active or not. The cloudbox can extend below the surface, or be
restricted to the atmosphere. The surface is allowed to cause both scattering
and polarisation effects outside the cloudbox.



\subsection{Particle optical properties}
\label{sec:optprop}
%
The optical properties of cloud droplets and ice crystals (\ExtMat, \AbsVec\ and
\PhaMat; see Eq.~\ref{eq:VRTE}) are required as input for scattering
calculations. They have to be pre-calculated outside the \ARTS\ program.

For liquid water clouds the droplets are in good approximation of spherical
shape and the optical properties can be computed using the well known Mie
theory \citep{mie1908}. The Atmlab toolbox includes a Mie program
\citep{maetzler2002} to generate optical properties of spherical particles. Ice
crystals have complex hexagonal shapes like solid columns, plates, aggregates
etc. The PyARTS package provides tools for the calculation of optical
properties of aspherical particles (cylinders, plates, and spheroids) which may
be used as approximations for the complex ice crystal shapes. PyARTS uses the
T-matrix codes by \citep{mishchenko02:_scatt_absor_emiss_light_small_partic}. 

\ARTS\ offers the possibility to define an arbitrary number of particle types.
For each particle type the user needs to define the particle number density
field, so that the desired mixture is obtained. Size and shape are not
specified specifically. Instead, each particle type is defined by its single
scattering properties. A common assumption is that aspherical cloud particles
are randomly oriented, this is one of the options in \ARTS. A special feature
of \ARTS\ is that it also allows to include oriented, more specifically
horizontally aligned, particles. Such an orientation is realistic for ice
crystals and it is important to consider it correctly in the radiative transfer
calculation, especially for the computation of polarisation effects.
Arbitrarily oriented particles can in principle easily be implemented in \ARTS,
but it is not done yet for the practical reason that the optical properties for
arbitrarily oriented particles require a huge amount of computational memory.
For technical details about how to provide optical properties and particle
number density fields please refer to \AUG. See also
\cite{battaglia-2006-emiss}.

\subsection{Observation geometry}
\label{sec:obsgeom}
%
There are no intrinsic limitations for the observation geometry. Radiative
transfer can be performed for any position inside and above the model
atmosphere, and with arbitrary observation direction, as long as the radiative
transfer does not reach undefined parts of the atmosphere (Sec.\
\ref{sec:modelatm}). As long as this constraint is met, the observation position
can be outside the horizontal region covered by the latitude and
longitude grids. This option is useful for satellite limb sounding where the
angular distance between the sensor and the practical atmospheric entry point
can exceed 15\degree. 

The observation geometry is defined by combinations of sensor position and
line-of-sight (LOS). The term sensor is used here, but this can be a
hypothetical instrument observing monochromatic radiances.
Inclusion of sensor characteristics is discussed in Sec.~\ref{sec:sensor}. The
vertical coordinate used for the sensor position is the radius (distance from
the origin). Horizontal position is defined by latitude and longitude.

The LOS is specified by a zenith angle, and for 3D also an azimuth angle. The
zenith angle is the angle between the observation direction and the radial unit
vector. This angle is inside the range [0\degree,180\degree]. For 2D, zenith
angles down to -180\degree\ are also defined, where a positive / negative value
signifies an observation direction towards higher / lower latitudes. The
azimuth angle is defined as the clockwise angle between the observation
direction and meridional plane north of the observation point. Westward
observations have negative azimuth angles and the allowed range is
[-180\degree,180\degree].

ARTS is designed to handle a complete measurement sequence by default, and the
involved variables can hold a series of position and LOS combinations. Each
combination of position and LOS is denoted as a measurement block. This
reflects that the operations for a single position and LOS combination can
involve numerous radiance calculations, and that the output can correspond
to several measurement spectra. A static sensor is assumed inside each
measurement block and any shift of the observation position requires a new
such block. See further Sec.~\ref{sec:sensor}.




\section{Calculation algorithms}
%-----------------------------------------------------------------------------
\label{sec:calc}
%
%Many of the features described in this section are incorporated through the
%agenda mechanism (Sec.~\ref{sec:agendas}) and this makes it possible to replace
%the described algorithms in a straightforward manner. This remark is not
%repeated below, the text describes just the presently existing algorithm(s). 


\subsection{Interpolation}
\label{sec:interpol}
%
The input specifies the variables for some data grid, but many calculations can
not be restricted to the grid points. Interpolation is thus a frequently
occurring task so must be done efficiently. A detailed description of the \ARTS\ implementation is found in \ADG.
In short, the first step is to determine the position of the interpolation
points with respect to the grid points. This is denoted as the grid position.
For example, interpolation points that are half-way between grid points 1 and 2
have a grid position of 1.5. This step can be performed for each data dimension
separately. 

\ARTS\ operates with polynomial interpolation, including the basic option
of linear interpolation. The result of such an interpolation can be
expressed as the weighted sum of the involved data \citep{press:numer:07}.
These ``interpolation weights'' depend only on the grid position (for each
data dimension) and polynomial interpolation order. Accordingly, the
interpolation weights can be pre-calculated and can be reapplied if the
same interpolation is performed for several quantities.

The general assumption in \ARTS\ is that the quantities vary linearly, in a
multi-dimensional way when applicable. The default option is then to apply
linear interpolation. This is also judged to be the most robust option.
However, a piece-wise linear representation requires a too dense grid for some
variables and also polynomial interpolation is allowed in some parts. This
includes the interpolation of ``raw'' VMR profiles to the common atmospheric
grids (Sec.\ \ref{sec:modelatm}). The same applies to all of the dimensions in
the absorption look-up table (Sec. \ref{sec:abstable}), with the exception of
frequency dimension where no interpolation at all is allowed.



\subsection{Gas absorption}
\label{sec:abstable}
%
The actual gas absorption calculation routines in \ARTS\ are identical to those
in \V1\ \cite{buehler:artst:05}. In particular, \ARTS\ can do
line-by-line absorption calculations, but also includes some predefined
complete absorption models and continua. With line-by-line we here mean that
spectral line data are read explicitly from an external catalogue. Different
catalogues are supported, the most commonly used one being HITRAN
\citep{rothman05:_hitran_jqsrt}.

Complete absorption models are particularly useful for species that exhibit
continuum absorption. Depending on the selected model, they may or may not
include an internal line-by-line component. Complete absorption models include
for example the model for O$_2$ absorption in the microwave spectral region,
including line coupling, by \citep{rosenkranz93:_absorption_microwaves}. Pure
continuum absorption models include for example the MT\_CKD infrared water
vapour continuum by \citep{clough05:_atmospheric_jqsrt}. See AUG for a complete
list of implemented models.

One innovation in \ARTS, compared to the older version, is that due
to the agenda mechanism (Sec.~\ref{sec:agendas}), the user can
now choose whether gas absorption should be calculated `on the fly'
whenever needed, or pre-calculated.  For the latter case a
lookup table approach was implemented, which stores pre-calculated
absorption cross-sections as a function of pressure, temperature, and
water vapour concentration \cite{buehler-absor}.



\subsection{Ray tracing}
\label{sec:ray}
%
The radiative transfer equation is solved along a pre-calculated propagation
path. Such a path is basically described by a set of positions
(Fig.~\ref{fig:ppath}) and the distance between these points. The ray inside
each grid box is calculated separately. There are two reasons for this.
Firstly, the DOIT algorithm (Sec.~\ref{sec:doit}) operates only with such local
propagation paths. Secondly, interpolation tends to cause a smoothing of
atmospheric structures and to decrease this effect it is desirable that the
propagation points include all crossings with the atmospheric grids. A
step-wise approach is then required, considering that these points can not be
calculated in an analytical manner with refraction. The same applies for the
crossings with pressure surfaces, even without refraction, as \ARTS\ allows the
radius for each surface to vary (for 2D and 3D). Propagation path points are
also inserted for the position of the sensor and the tangent point (when
applicable), if these are found inside the model atmosphere. A maximum allowed
distance between the grid points can also be specified, resulting in
additional points being inserted to fulfill the criterion. The
end points of complete paths match either the sensor position, the top of the
atmosphere, the surface or a cloud box boundary.

The details of the path calculations are described in \AUG, and are not
repeated here. Refraction is so far only handled in a very straightforward, but
inefficient, way, and further work is needed on this point.


\subsection{Clear sky radiative transfer}
\label{sec:csrte}
%
As described in Sec.~\ref{sec:cloubox}, the term ``clear sky'' refers in \ARTS\
to the domain outside the cloudbox. For this domain it is assumed that
scattering can be neglected and that absorption and emission are unpolarised.
However, the radiative transfer must be performed in a vector manner, to
correctly propagate polarisation effects generated inside the cloudbox and by
the surface. 

Eq.~\ref{eq:VRTE} can be solved for these conditions and considering smaller
path lengths over which the Planck function can be treated as an approximative
constant. The expression applied for the first Stokes component is
\begin{equation}
  \label{eq:CSRT:I}
  I_{i+1} = I_ie^{-\aOth{i}} + \bar{B}_i(1-e^{-\aOth{i}}),
\end{equation}
with
\begin{eqnarray}
  \bar{B}_i &=& (B(T_i)+B(T_{i+1}))/2, \\
  \aOth{i} &=& \Delta s_i(k_i+k_{i+1})/2, 
  \label{eq:taustep}
\end{eqnarray}
where $I_i$, $T_i$ and $k_i$ are the radiance, temperature and absorption
coefficient, respectively, at point $i$ of the propagation path
(Sec.~\ref{sec:ray}), and $\Delta s_i$ is the distance along the path between
point $i$ and $i+1$. That is, $\bar{B}_i$ is a Planck function average of
the path step, and the absorption is assumed to vary linearly
between the two points. The Beer-Lambert law can be applied for the remaining
Stokes components, for example
\begin{equation}
  \label{eq:CSRT:Q}
  Q_{i+1} = Q_ie^{-\aOth{i}}.
\end{equation}
These recursive expressions are initiated with the Stokes vector at the start
of the propagation path, determined by the ``radiative background''. This can
either be down-welling radiation at the top of the atmosphere (most likely set
to cosmic background radiation), upwelling radiation from the surface
(Sec.~\ref{sec:surfscat}) or radiation leaving the cloudbox.

Depending on the unit used, atmospheric conditions and type of observation, it
could be necessary to incorporate the real part of the refractive index in
Eq.~\ref{eq:CSRT:I} and \ref{eq:CSRT:Q} \cite{matzler-2006-radia}. \ARTS\ is
so far lacking a method to incorporate this effect, but this shortcoming should
be acceptable for most applications. 

%\todo{If I get it correct, the worst case
%  should be emission going straight from the surface to space. In the tropics
%  where the refractive index is the highest, the error should be about 0.3K.
%  Not OK for high accuracy calculations!}

% More elaborated versions of Eq.~\ref{eq:CSRT:I} exist, see e.g.\
% \cite{rodgers:inver:00,matzler-2006-radia}. The clear sky part of \ARTS\ treats
% all frequencies in parallel and this makes it preferable to perform the
% integration in terms of path length ($s$), instead of optical thickness
% ($\Oth$) that varies between the frequencies. For a given $\Delta s$, it is
% more effective to set $\bar{T}$ as a function of $\Oth$. However, this makes
% the application of the chain rule less straightforward for the derivation of
% partial derivatives (Sec.~\ref{sec:jacs}). Further, it causes additional
% computational costs, that with the present scheme instead can be used to set a
% lower maximum value for $\Delta s$. 


\subsection{Surface reflection}
\label{sec:surfscat}
%
The Stokes vector for upwelling radiation from the surface, $\aStoVec{u}$, in
the direction of \PDir, is calculated as
\begin{eqnarray}
  \label{eq:surface}
  \aStoVec{u}(\Frq,\PDir) &=& \aStoVec{e}(\Frq,\PDir) + 
  \int_{2\pi} \DiffD\PDir' \MtrStl{R}(\Frq,\PDir,\PDir')\StoVec^d(\Frq,\PDir')
                                                                   \nonumber\\
  &\approx& \aStoVec{e}(\Frq,\PDir) + 
  \sum_{i=1}^n \MtrStl{R}_i(\Frq,\PDir,\PDir')\StoVec^d_i(\Frq,\PDir')
\end{eqnarray}
The first term, $\aStoVec{e}$, is surface emission for the direction of
concern. The second term treats the reflection of down-welling radiation, where we use a discrete approximation.
This equation can be compared to the last term of Eq.~\ref{eq:VRTE}, that
describes scattering into the line-of-sight. The main differences are that this
integration is performed only over a half sphere and \MtrStl{R}\ is
denoted as the bidirectional polarised reflectance distribution function (BPDF).

Accordingly, the down-welling radiation, $\StoVec^d$, is calculated for $n$
directions, giving $\StoVec^d_i$. Each direction involves the calculation of a
propagation path and radiative transfer. The set of $\StoVec^d_i$ are weighted
with the matrices $\MtrStl{R}_i$ that are a combination of the BPDF and the
solid beam angle that each direction $i$ represents.

The down-welling term of Eq.~\ref{eq:surface} vanishes if the surface is treated
to be a blackbody. For surfaces that can be treated as flat, $n$ is one and
$\PDir'$ is the specular direction. The required value for $n$ and the best
selection of the $\PDir'$-directions for other situations is open for
experimentation. Methods for blackbody, specular and Lambertian surface
conditions have been implemented (applied equations found in \AUG).





\subsection{Cloud scattering}
\label{sec:scattering}
%
Two algorithms that solve the VRTE (Eq.~\ref{eq:VRTE}) have been included into \ARTS, one
algorithm is based on a discrete ordinate iterative scheme, the other one is
based on the Monte Carlo method. Both algorithms are published
\cite{emde:apoli:04,davis05:_monte_carlo_i3etgrs}. Short summaries and updates
are found in the following sections. For details please refer to
\AUG\ and \ATD.


%
\subsubsection{DOIT}
\label{sec:doit}
%
The Discrete Ordinate Iterative (DOIT) algorithm solves the VRTE inside the
cloudbox. The scattering integral term of the VRTE (Eq.~\ref{eq:VRTE}) is
first calculated for all model gridpoints in the cloudbox for all discrete
propagation directions using the clear sky radiation field for
$\StoVec(\Frq,\PPos,\PDir)$. Then the scattering integral may be considered as
an additional source term and Eq.~\ref{eq:VRTE} may be written as
\begin{eqnarray}
  \frac {\DiffD\StoVec(\Frq,\PPos,\PDir)}{\DiffD s} =
  &{}-\ExtMat(\Frq,\PPos,\PDir) \StoVec(\Frq,\PPos,\PDir) +
  \AbsVec(\Frq,\PPos,\PDir) \rlap{$B(\Frq,\PPos)$} \\ \nonumber
  &{}+ {\bf S}^0(\Frq,\PPos,\PDir).
\end{eqnarray}
This equation can be solved analytically yielding the first iteration radiation
field, which can again be used to compute the scattering integral term for all
grid points in the cloudbox. Scattering integral fields and radiation fields
are calculated alternately. As soon as two successive radiation fields are
equal a solution to the VRTE (Eq.~\ref{eq:VRTE}) has been found. The algorithm
has been implemented for one-dimensional plane-parallel, and also for fully
spherical model geometry. The second feature is not common for discrete
ordinate methods and several numerical optimisations were required for
efficiency and accuracy. A detailed description of the algorithm can be found
in \cite{emde:apoli:04}.

When both the surface and the cloudbox exhibit scattering there can be an
interaction between the two, and this must be considered when setting the
cloudbox limits. For DOIT it is assumed that the radiation entering the
cloudbox is not dependent on the conditions inside the cloudbox. Thus, if a
significant amount of outgoing radiation is reflected back into the cloudbox by
the surface, the cloudbox must be extended down to the surface even if there is
a vertical gap between the surface and the clouds causing atmospheric
scattering.

The DOIT algorithm has been used in several scientific studies: A sensitivity
study about the impact of cloud scattering on microwave limb radiances has been
performed \citep{emde:theef:04}. Also the impact of particle shape and
orientation on polarised microwave radiances has been investigated in detail
\citep{teichmann06:_understanding_jqsrt,emde05:_phdthesis}. In order to limit
the extent of validity of the single scattering approximation which is often
applied in radiative transfer codes for the thermal spectral range DOIT was
compared to the single scattering model which is used for MIPAS retrievals
\citep{hoepfneremde05:_ir_comparison}. Another application of the algorithm was
to estimate how the observation of cosmic microwave background polarisation
from the ground (Atacama desert, Chile) is disturbed by thin cirrus clouds
\citep{pietranera07:_cmb_polarization_mnras}. How the AMSU satellite sees a
strong ice cloud event in the various channels has been investigated by
\citep{sreerekha2008}. For the design of a satellite instrument operating in
the sub-mm wavelength range to measure cirrus cloud properties (CloudIce) the
DOIT algorithm was also applied \citep{buehler:aconc:07}: A large dataset of
simulated radiances for CloudIce has been generated, covering a comprehensive
set of possible atmospheric states \citep{rydberg:predi:07}. This dataset was
then used for a performance study using a neural network retrieval algorithm
\citep{jimenez:perfo:07}. Moreover the DOIT algorithm was used as the forward
model for a simple retrieval approach to derive cloud properties from Odin
measurements \cite{eriksson:first:07}.

\subsubsection{MC}
\label{sec:mc}
%
\input{arts2-MC.tex}




\subsection{Sensor characteristics}
\label{sec:sensor}
%
Several instrumental effects can be expressed as (for scalar radiative transfer)
\begin{equation}
  \label{eq:sensorint}
  \int r(x) I(x)\, \DiffD x,
\end{equation}
where $r$ is the instrument's response function, $I$ is the radiance
and $x$ is frequency or some other variable, depending on which
response that is treated. The normal case is that simulations are repeated for
the same sensor characteristics, and a direct implementation of
Eq.~\ref{eq:sensorint} is normally not most efficient. In practise, $I$ is a
discrete quantity, and we have a set of values; $I_i$. The approach taken in
\ARTS\ is based on the observation that the practical calculation of
Eq.~\ref{eq:sensorint} can be written as
\begin{equation}
  \label{eq:sensorsum}
  \sum_i h_i I_i.
\end{equation}
This expression assumes that $r$ is independent of $I$, which  is
in general valid. Some responses are naturally better expressed directly with
Eq.~\ref{eq:sensorsum} (e.g.\ sideband folding). The summation weights $h_i$
are pre-calculated and stored in a matrix \SnsMtr. The \SnsMtr\ of each sensor
component is calculated separately and the total response matrix is calculated as
\begin{equation}
  \label{eq:Hs}
  \SnsMtr = \aSnsMtr{n}\dots\aSnsMtr{2}\aSnsMtr{1},
\end{equation}
where $n$ is the number of sensor components considered. The inclusion of sensor
characteristics is then simply made as
\begin{equation}
  \label{eq:Hi}
   \MsrVct = \SnsMtr\MpiVct,
\end{equation}
where \MpiVct\ is a vector, where the Stokes vectors from each monochromatic
radiance calculation are appended, and \MsrVct\ is the final ``measurement
vector''. This approach was introduced by \cite{eriksson:studi:02} and the
calculation details are found in \cite{eriksson:effic:06}.

Methods exist for including the following sensor components and observation
strategies: antenna, mixer, spectrometer, beam switching and frequency
switching. Instruments having mixers at different frequencies (such as AMSU)
require special attention and have a dedicated method. The description of the
responses can be detailed. For example, the response of the antenna can be
described as a function of polarisation, frequency, zenith angle and azimuth
angle. For flexibility, for dimensions where the corresponding grid has length
1, the convention is that the response is taken as constant or is ignored, and
the antenna response data can be as simple as a vector describing the zenith
angle variation. See the documentation for further details.

%As described in Sec.~\ref{sec:obsgeom}, the calculations are divided into
%measurement blocks. Eq.~\ref{eq:Hi} is applied for each such block and 
%separate \MsrVct-vectors are appended. \SnsMtr\ is set-up in such a
%way that the
%(centre) line-of-sight can be changed between the blocks. The sensor
%characteristics must otherwise be constant over the measurement blocks,
%if to be included in \SnsMtr. For example, cases with changing frequency and
%operations on the complete measurement sequence must be handled in different
%ways. 



\subsection{Jacobian calculations}
\label{sec:jacs}
%
Some retrieval methodologies operate with the partial derivatives of \MsrVct\
with respect to the quantities to be retrieved (\SttVct), denoted as the
weighting function matrix or the Jacobian:
\begin{equation}
  \label{eq:K}
   \WfnMtr = \frac{\PartD \MsrVct}{\PartD \SttVct}.
\end{equation}

%Thus, such derivatives must be provided by a forward model aiming at
%retrieval applications.

%The basic calculation strategies are unchanged from \V1, and we refer to
%\cite{buehler:artst:05} for a more complete treatment of the Jacobian
%calculations. 

\subsubsection{Atmospheric and surface variables}
\label{sec:jacs:atm}
%
Analytical expressions are used as far as possible for atmospheric and surface
quantities. Weighting functions can so far only be calculated for ``clear sky''
conditions. The final radiance obtained through Eq.~\ref{eq:CSRT:I} can be
expressed as
\begin{equation}
  \label{eq:I4J}
  I = I'+ e^{-\Oth'}\left[ \bar{B}_i(1-e^{-\aOth{i}})+I_ie^{-\aOth{i}}\right]
\end{equation}
where $\Oth'$ is the optical thickness between the sensor and point $i+1$
and $I'$ is all emission generated along the same distance.

As example, let $x$ be one element of $\SttVct$, representing the amount of
some gas at some point in the atmosphere. The contribution to the weighting
function for $x$, originating from the radiative transfer step covered by
Eq.~\ref{eq:CSRT:I}, is calculated by applying the chain rule:
\begin{equation}
  \label{eq:chainrule}
  \frac{\PartD \MsrVct}{\PartD x} =  
  \frac{\PartD \MsrVct}{\PartD \MpiVct}
  \frac{\PartD \MpiVct}{\PartD I} \frac{\PartD I}{\PartD \aOth{i}}
  \left[\frac{\PartD \aOth{i}}{\PartD k_i}\frac{\PartD k_i}{\PartD x_i} 
        \frac{\PartD x_i}{\PartD x} +
        \frac{\PartD \aOth{i}}{\PartD k_{i+1}}\frac{\PartD k_{i+1}}{\PartD x_{i+1}}
        \frac{\PartD x_{i+1}}{\PartD x} \right],
\end{equation}
where $x_i$ and $x_{i+1}$ is the amount of the gas at point $i$ and $i+1$,
respectively. Some of these terms can be expressed explicitly:
\begin{eqnarray}
  \frac{\PartD \MsrVct}{\PartD \MpiVct} &=& \SnsMtr, \\
  \frac{\PartD I}{\PartD \aOth{i}} 
      &=& e^{-\Oth'}\left( \bar{B}_i-I_i\right)e^{-\aOth{i}}, \\
  \frac{\PartD \aOth{i}}{\PartD k_i}=\frac{\PartD \aOth{i}}{\PartD k_{i+1}} 
      &=& \Delta s_i/2, \\
  \frac{\PartD k_i}{\PartD x_i}
      &=& \sigma_i, \\
\end{eqnarray}
where $\sigma_i$ is the absorption cross-section for the species (at point $i$
and in a unit matching the unit of $x$). The term $\PartD \MpiVct/\PartD I$
gives the position in \MpiVct\ where the $I$ of concern is stored.

------ Temporary notes (will be moved to AUG): ------ \\
A changed temperature has several non-local effects, originating from
refraction and hydrostatic equilibrium. These non-local effects make the
calculations more difficult for, at least, limb sounding. For example, even
changes at altitudes below the tangent point will have an influence as the
geometrical altitudes of all higher layers is changed through hydrostatic
equilibrium. However, the non-local effects can be neglected for observations
around zenith and nadir and the temperature weighting function can
then be written as:
\begin{equation}
  \frac{\PartD \MsrVct}{\PartD T} =  
  \frac{\PartD \MsrVct}{\PartD \MpiVct} \frac{\PartD \MpiVct}{\PartD I} 
  \left[
  \frac{\PartD I}{\PartD \aOth{i}}\frac{\PartD \aOth{i}}{\PartD T} + 
  \frac{\PartD I}{\PartD \bar{B}_i}\frac{\PartD \bar{B}_i}{\PartD T}
  \right].
\end{equation}
The partial derivative of $\aOth{i}$ must now also consider the term $\Delta
s_i$ due to the constrain of hydrostatic equilibrium:
\begin{equation}
  \frac{\PartD \aOth{i}}{\PartD T} =
  \frac{\PartD \aOth{i}}{\PartD k_i}\frac{\PartD k_i}{\PartD T_i} 
  \frac{\PartD T_i}{\PartD T} +
  \frac{\PartD \aOth{i}}{\PartD k_{i+1}}\frac{\PartD k_{i+1}}{\PartD T_{i+1}}
  \frac{\PartD T_{i+1}}{\PartD T} +
  \frac{\PartD \aOth{i}}{\PartD \Delta s_i}
  \left[
    \frac{\PartD \Delta s_i}{\PartD T_i} \frac{\PartD T_i}{\PartD T} +
    \frac{\PartD \Delta s_i}{\PartD T_{i+1}} \frac{\PartD T_{i+1}}{\PartD T} +
  \right].
\end{equation}
The temperature derivative of the absorption ($\PartD k_i/\PartD T_i$) must be
calculated numercially. This derivative depends on if gas species
concentrations are given as volume mixing ratio (VMR) or number density. As
\ARTS\ uses VMR, the term above will be calculated with the constrain of fixed
VMR. A consequence of this is that it is not possible to mix retrieval of
temperature and number densities.

Eq.~\ref{eq:taustep} gives
\begin{equation}
  \frac{\PartD \aOth{i}}{\PartD \Delta s_i} = \frac{k_i+k_{i+1}}{2}. 
\end{equation}
The path length ($\Delta s_i$), for a given pressure, is linearly proportional
to the temperature, and if $\bar{T}$ is the average temperature along the path
step:
\begin{equation}
  \frac{\PartD \Delta s_i}{\PartD \bar{T}} =   \frac{\Delta s_i}{\bar{T}} 
\end{equation}
Following the other variables, we set $\bar{T}=(T_i+T_{i+1})/2$, and
\begin{equation}
  \frac{\PartD \Delta s_i}{\PartD T_i} = \frac{\Delta s_i}{2T_i}.
\end{equation}
The terms involving $\bar{B}_i$ are
\begin{eqnarray}
   \frac{\PartD I}{\PartD \bar{B}_i} &=&
   e^{-\Oth'}\left(1-e^{-\aOth{i}}\right), \\
   \frac{\PartD \bar{B}_i}{\PartD T_i} &=& \frac{1}{2}
   \frac{\PartD B(T)}{\PartD T}. 
\end{eqnarray}
The term $\PartD B(T)/\PartD T$ can be expressed analytically, but as $B$ is
provided by an agenda this term must anyhow be determined in a pure numerical
manner; it is likely the derivative of the Planck function, but if the
Rayleigh-Jeans approximation is for some reason selected ($B=T$) the term 
is just 1.

Determine expression for BL and higher Stokes, and put into ARTS!\\
------ End notes ------

The term $\PartD x_i/\PartD x$ appears due to the fact that $x_i$ and $x$ are
placed at different positions, and the representation of the atmospheric fields
must be considered here. The fields are treated to vary linearly between grid
points, giving triangular shaped `basis functions' for 1D, pyramid shaped ones
for 2D etc. In practise, the term is calculated as the value of the basis
function for $x$ at the location of $x_i$, see \cite{buehler:artst:05}. This is
a slight approximation with respect to the goal of fully incorporating the
piece-wise linear representation in the weighting functions
\cite{buehler:artst:05}. A low value of $\Delta s_i$ decreases the degree of
approximation. The same basis functions and a more detailed discussion of
representation aspects are found in \cite{read-2006-thecl}.

It can be noted that $\PartD x_i/\PartD x$ is normally non-zero for more than
one element of \SttVct. The exception is if the positions of $x_i$ and $x$ are
identical. Reversely, the weighting function for element $x$ can have
contributions from several propagation path points ($x_i$), as well as from
several radiance spectra.

In practise, all Stokes components are treated in parallel, to simply
incorporate surface scattering (and in the future possibly also cloud
scattering). Transmission $e^{-\Oth'}$ must then be expressed as a matrix,
$\MtrStl{T}'$. For scattered down-welling radiation ($\StoVec^d_i$) the
effective transmission matrix is
\begin{equation}
  \MtrStl{T}' = \MtrStl{T}_2\MtrStl{R}_i\MtrStl{T}_1,
\end{equation}
where $\MtrStl{T}_2$ is the transmission between the surface and the sensor,
$\MtrStl{R}_i$ is defined in Eq.~\ref{eq:surface} and $\MtrStl{T}_1$ is the
transmission between the point $i+1$ and the surface.

The case of gas species retrieval is used above as example. This chain rule
approach (Eq. \ref{eq:chainrule}) can be used for any variable affecting
atmospheric absorption and emission, or surface reflectance and emission.
Expressions for scalar radiative transfer are found in \cite{buehler:artst:05}.

Some terms are best calculated in a numerical manner. For atmospheric
temperature the terms $\PartD k_i/\PartD T$ and $\PartD B/\PartD T$ are found.
The first term can in principle be expressed analytically, but this would
require hard links to the absorption module. Such links are avoided in \ARTS\
and the term is instead calculated with a second call of
\texttt{abs\_scalar\_gas\_agenda} (Sec.~\ref{sec:agendas}), with a slightly
perturbed temperature. The same applies to the second term, even though an
analytical derivation here is straightforward \cite{eriksson:studi:02}. This, like the emission source term, is handled by an agenda, and the user can choose to set $B=T$ (can be a valid approximation for low frequency
observations), instead of $B$ being the Planck function.

A constraint for the analytical expressions above is that the effect of the
variable must only be local. Atmospheric temperature is again the most important
example, that has non-local impacts if hydrostatic equilibrium applies and if
refraction affects the propagation path significantly.


\subsubsection{Numerical perturbations}
%
A pure numerical approach is applied for several variables, see
\cite{buehler:artst:05} for details. In \V1\ this is made in a simple-minded
fashion where the variable of concern is perturbed and large parts of the
calculations are repeated. The code is now restructured to allow different
possible `shortcuts', where the main option should be to perform the
perturbation by an interpolation of existing results. 

%Let's take a zenith angle
%pointing retrieval as example. For a single radiance spectrum, there is
%no information on the zenith angle variation of the radiance and a new
%radiative transfer calculation for a perturbed direction is needed. However,
%the inclusion of antenna characteristics requires calculations for multiple
%zenith angles (Sec.~\ref{sec:sensor}) and the needed information is basically at
%hand; the perturbation step can be done by an interpolation to a slightly
%shifted zenith angle grid.  
%The most general solution is to apply the
%interpolation at the pencil beam stage (i.e.\ on \MpiVct), but could also be
%done for antenna weighted spectra (\MsrVct) if they have small zenith angle
%separation.


\subsubsection{Polynomial basis functions}
%
Some retrieval quantities are expressed using a polynomial basis. Zenith angle
pointing offset is one example, that can be modelled to have a polynomial
variation as a function of time. If the offset is assumed to be constant in
time, a zero order polynomial shall be selected. If there is also a linear
drift with time, use a first order polynomial etc.

In more detail, the explanatory variable (time in the example above) is
normalised to cover the range [-1,1], here denoted as $z$, and the continuous
representation ($f$) of the variable of concern can be written as
\begin{equation}
  f(z) = x_0 + x_1(z-b_1) + x_2(z^2-b_2) + x_3(z^3-b_3) + x_4(z^3-b_4) + \dots  
\end{equation}
where $x_0, x_1, \dots$ are the coefficients to be retrieved (elements of
\SttVct). The interpretation of a retrieval is simplified if the average of $f$
equals $x_0$, and the scalars $b_1, b_2, \dots$ are selected, schematically, as
\begin{equation}
  0 = \int_{-1}^1 \!\left(z^n-b_n\right) \, \DiffD z, \quad n>0.
\end{equation}
According to this expression, $b_n$ is zero for odd $n$. However, $z$ is in
practise a discrete variable ($z_i$, not necessarily symmetric around 0), and
$b_n$ is taken as the average of $z_i^n$: all $b_n$ can be non-zero. The
normalisation of $z$ is not only made for interpretation reasons, it can be
required for pure numerical reasons, such as when $z$ represent frequency (in
Hz).


%\subsubsection{Status and outlook}
%%
%A forward model operates with many variables and the list of potentially useful
%weighting functions is long. As sketched above, the calculations are best
%performed in different ways depending on variable, conditions and accuracy
%demands. Hence, it would be highly demanding to cover all possible
%combinations. At this moment five retrieval quantities are handled, where in no
%case more than a single calculation option is offered, but still sufficient to
%at least handle ground-based observations \cite{Haefele2009}. Other quantities
%or options will be implemented only when a practical need occurs. The reader is
%free to contact us for possible collaboration around some particular retrieval
%case.



\subsection{Batch calculations}
%
\ARTS\ now includes a very general mechanism for batch calculations. This is
handled by an agenda (Sec.~\ref{sec:agendas}) that contains the methods that
should be executed for each batch case. Batch calculations are particularly
efficient with absorption lookup tables (Sec.~\ref{sec:abstable}), since the
table has to be calculated (or read from file) only once, and can then be used
for all cases. A typical application of this is to simulate satellite
measurements for a large number of atmospheric scenarios.



\subsection{Transmission calculations}
%
The sections and equations above are assuming the standard \ARTS\ case of
measurements of direct or scattered emission, but also pure transmission
calculations are handled. The modular approach of \ARTS\ made this addition
simple. The main step was to make a workspace method for the clear-sky
radiative transfer agenda that applies the Beer-Lambert law for all Stokes
components, accompanied with the corresponding changes for the Jacobian
expressions. This method does only need to consider radiative transfer along a
single pencil beam, all other operations are handled by the existing methods.
This was complemented with a method for the cloudbox, including also particle
extinction.

These two methods make it possible to simulate solar occultation and
satellite-to-satellite transmissions. This includes particle effects, as long
as the (re-)scattering into the line-of-sight can be neglected. The radiation
at the top of the atmosphere is then set to solar radiation or a unit Stokes
vector (e.g.\ [1,0,0,$\pm$1]$^T$ if circular polarisation is transmitted),
instead of cosmic background radiation as for the emission case. The agenda for
surface properties should also be configured to not add any emission.



\subsection{Radiance units}
\label{sec:units}
%
The flexibility of \ARTS\ has the consequence that there is no fixed unit for
the measurement vector $\MsrVct$. The unit depends primarily on the methods
selected to set the emission source term.
In addition, the sensor response matrix (\SnsMtr) can include an
operation that changes the unit.

The standard definition inside \ARTS\ of the Planck function is
\begin{equation}
  \label{eq:planck}
  B(T) = \frac{2h\Frq^3}{c^2(exp(h\Frq/k_BT)-1)},
\end{equation}
where $h$ is the Planck constant, $c$ the speed of light and $k_B$ the
Boltzmann constant. This expression gives the (total) power per unit frequency
per unit area per solid angle and the resulting unit for the Stokes
vector is W/(m$^2$\,Hz\,sr).
As long as Eq.~\ref{eq:planck} is followed, \ARTS\ supports conversion to the following
units:
\begin{itemize}
\item W/(m$^2$\,m\,sr), power per unit wavelength per unit area per solid angle
\item W/(m$^2$\,m$^{-1}$\,sr), power per unit wavenumber per unit area per solid angle
\item RJBT, brightness temperature (\BT) following the Rayleigh-Jeans
  approximation of the Planck function [K]
\item PlanckBT, brightness temperature following the Planck function [K]
\end{itemize}
The two first conversions correspond to different linear mappings, and the same
rescaling factor can be applied for all Stokes elements, polarisation
components and the Jacobian. Also RJBT is obtained in a linear manner, but the
conversion to brightness temperatures requires additional considerations.
\ARTS\ makes a distinction here between the Stokes vector and individual
polarisation components, such as \Iv\ and \Ilhc\ (Sec.~\ref{sec:rtvar}).

All Stokes elements are converted to \BT, following Eq.~\ref{eq:planck}, as
\begin{equation}
  \label{eq:rjtb2}
  I' = \frac{c^2}{2\Frq^2k_B} I.
\end{equation}
This deviates from e.g.\ \cite{matzler-2006-radia}, but is preferred for
reasons of generality. A practical consideration for the Stokes vector is that
the ratio between the elements must be the same independent of the selected
unit.
Otherwise it would be needed to adapt optical properties, e.g.\ \ExtMat\ (Eq.~\ref{eq:VRTE}), to the
selected unit. Another way to express this is that, in the Rayleigh-Jeans
limit, the same result shall be obtained if Eq.~\ref{eq:planck} is used and
radiances are converted to RJBT, as if the emission source term ($B$) is
replaced by the physical temperature (\Tmp). \ARTS\ allows the latter, see
\cite{liu-2008-conve} for a discussion of this choice. (It shall be noted that
these two options do not generally give the same \BT).

The measurement vector \MsrVct\ can contain both Stokes elements and
polarisation components. In the later case this is taken as a calibrated
observation and, if the data correspond to a single polarisation, the
conversion to \BT\ must be adapted. The reference for the conversion shall then
be the blackbody radiation for a single polarisation, that is a factor 2 smaller
than Eq.~\ref{eq:planck}. The conversion from radiance to \BT\ of e.g. \Iv\ is
thus
\begin{equation}
  \label{eq:rjtb1}
  \Iv' = \frac{c^2}{\Frq^2k_B} \Iv.
\end{equation}
For flexibility, the unit conversion can be made both on \MpiVct\ and \MsrVct\
(Eq.~\ref{eq:Hi}). The extraction of polarisation components can be made as
part of \SnsMtr, and the setting of this matrix must consider the unit of the
data. For radiances Eq.~\ref{eq:Iv} shall be followed, while if a conversion to
\BT\ has been made: 
\begin{equation}
  \Iv' = I'+Q'.
\end{equation}
Weighting functions are treated as the corresponding intensity value.

For PlanckBT the conversion is done by inverting the Planck function:
\begin{equation}
  \label{eq:invplanck1}
  I' = B^{-1}(I)=\frac{h\Frq}{k_B\ln((p_nh\Frq^3/c^2I)+1)},
\end{equation}
where $p_n$ is 2 for $I$ and 1 for individual polarisation components (cf.\
Eq.\ \ref{eq:rjtb2} and \ref{eq:rjtb1}). The fact that Eq.~\ref{eq:invplanck1}
is a non-linear mapping causes additional complications for the higher
Stokes elements. To maintain the basic properties of the Stokes vector,
elements 2 to 4 must be converted as
\begin{equation}
  \label{eq:invplanck2}
  Q' = \frac{B^{-1}(I+Q) - B^{-1}(I-Q)}{2}.
\end{equation}
The Jacobian requires further considerations. The derivative of
a radiance in PlanckBT can be formulated as
\begin{equation}
  \frac{\PartD I'}{\PartD x} = \frac{\PartD B^{-1}(I)}{\PartD x} =   
   \frac{\PartD B^{-1}(I)}{\PartD I}\frac{\PartD I}{\PartD x}.
\end{equation}
The term $\PartD I/\PartD x$ is the weighting function for the original
unit, that shall be converted to PlanckBT. The conversion term can be derived
to be
\begin{equation}
  \frac{\PartD B^{-1}}{\PartD I} = \frac{k_B\left[B^{-1}(I)\right]^2}
                     {h\Frq I(1+(c^2I/p_nh\Frq^3))}.
\end{equation}
For Stokes elements following Eq.~\ref{eq:invplanck2} we get
\begin{equation}
  \frac{\PartD Q'}{\PartD x} = \frac{1}{2}\left[
      \left.\frac{\PartD B^{-1}}{\PartD I}\right|_{I+Q}  +
      \left.\frac{\PartD B^{-1}}{\PartD I}\right|_{I-Q}
     \right] \frac{\PartD Q}{\PartD x}.
\end{equation}




\section{Conclusions}
%-----------------------------------------------------------------------------
%
The first version of \ARTS\ can be denoted as a traditional microwave
forward model: 1D and no treatment of scattering. The main novelty of \V1\ was
the introduction of the workspace concept. However, the ambition of easily
extendable software was not fully met by \V1, and the concept was for this
version extended by an agenda mechanism. Our experience so far is that the
desired degree of modularity now has been reached.

The new \ARTS\ version (2.0) is a state-of-the-art radiative transfer model for
the thermal spectral region, as it combines the following features:
\begin{itemize}
\item The model atmosphere can be 1D, 2D or 3D. Tomographic limb sounding
  retrievals require 2D or 3D, and rigorous cloud scattering simulations are
  only possible in 3D.
\item Spherical geoid and surface are throughout default. For 2D and 3D more
  complex topography are also possible. A `flat Earth' is not a viable
  option for limb sounding.
\item Radiative transfer can be made for 1 to 4 Stokes elements. Polarisation
  effects can thus be fully described.
\item Basically no restriction in complexity of surface reflection (but handled
  only in a simplistic, inefficient, manner).
\item For particle single scattering properties, not only the standard
  assumption of spherical or completely randomly oriented particles, but also
  the case of horizontally aligned particles is handled. 
\item Two modules for solving radiative transfer with particle scattering: MC
  and DOIT. Both modules have previously been presented
  \cite{emde:apoli:04,davis05:_monte_carlo_i3etgrs}, have no intrinsic
  approximations, and have been verified by practical retrievals
  \cite{eriksson:first:07,rydberg:nonga:09}.
\item Sensor responses can be incorporated in an efficient manner
  \cite{eriksson:effic:06,buehler:effic:10}.
\end{itemize}
Another way to judge the scientific merits of \ARTS-2.0 is the fact that it has
already been used for a number of scientific publications. Direct usage of 
\ARTS-2.0 includes 
\cite{emde:theef:04,davis05:_cirrus_induc_polar_ghz_aura,hoepfneremde05:_ir_comparison,teichmann06:_understanding_jqsrt,battaglia07:_microw_jqsrt,buehler:aconc:07,davis07:_3d_pol_sim_acp,ekstrom:first:07,eriksson:first:07,pietranera07:_cmb_polarization_mnras,rydberg:predi:07,adams2008,sreerekha2008,Haefele2009,harlow-2009-milli,milz09:_comparison_grl,rydberg:nonga:09,holl-2010-collo}, 
and indirect usage is found in yet more journal articles. 

The main limitations of \ARTS-2.0 are:
\begin{itemize}
\item Physical mechanisms not yet implemented include non-local thermodynamic
  equilibrium and polarised gas absorption.
\item Particle single scattering properties must be calculated externally.
\item Extremely fast calculations (of RTTOV type) are not within the present
  scope of \ARTS. The same applies to calculation of broadband radiative fluxes
  and cooling rates.
\item Weighting functions can be obtained, but so far only for a limited number
  of variables under non-scattering conditions.
\end{itemize}
Some points of general theoretical could be the approach for deriving
analytical expressions for the weighting functions (Sec.~\ref{sec:jacs:atm})
and the conversion of such data to Planck brightness temperatures
(Sec.~\ref{sec:units}).

%The scientific merits of \ARTS\ are estimated in rough terms by the citation
%frequency. The number of citations for the article presenting \V1\
%\cite{buehler:artst:05} is about 60, where about half of the citations refer
%in practise to this new version. The combined number of citations for the DOIT
%and MC modules is about 35. 

The web address for \ARTS\ is \url{www.sat.ltu.se/arts}, where the software can
be downloaded freely and additional documentation is found. Please, note the
``code of conduct'' found on the web site, asking users to cite this and the
relevant module specific articles
\cite[at the time of writing:][]{emde:apoli:04,davis05:_monte_carlo_i3etgrs,eriksson:effic:06,buehler:effic:10}.



\section*{Acknowledgements}

First of all, we thank all others that have contributed to the ARTS
development over the years, particularly 
%
Hermann Berg, 
Mattias Ekstr\"om, 
Axel von Engeln, 
Wolfram Haas,  
Carlos Jim\'enez, 
Viju John,  
Nikolay Koulev,  
Thomas Kuhn,  
Mashrab Kuvatov, 
Christian Melsheimer,  
Mathias Milz, 
Randall Skelton, 
Claas Teichmann,  
and Sreerekha T.R.
%
The second acknowledgement is due to all those in the ARTS user community that
have contributed interesting use cases, applications, and discussions on the
ARTS mailing list (\url{arts-users@www.sat.ltu.se}). Seeing the model being
used is the biggest reward for us who have developed it!

Last but not least, we acknowledge our funding agencies. The ESA study
`Development of a Radiative Transfer Model for Frequencies between 200 and 1000
GHz' (contract 17632/03/NL/FF) was especially valuable. Further, direct or
indirect support has been provided by the Swedish National Space Board (e.g.\
59/07 and 92/08) and by the Swedish Research Council (2007-3720 and 2007-5370),
through different contracts at both the Swedish groups. Development of the
ARTS-MC algorithm was largely funded by the UK Natural Environment Research
Council.



%--- References --------------------------------------------------------------
\bibliography{j_abbr,references}


\begin{figure}
\begin{minipage}[t]{0.35\hsize}
\begin{lstlisting}
Arts2 {
StringCreate(s)
StringSet(s,
   "Hello World")
Print(s)
}
\end{lstlisting}
\end{minipage}
\hspace*{\fill}
\begin{minipage}[t]{0.6\hsize}
\begin{lstlisting}
arts-1.14.122
Executing Arts
{
- StringCreate
- StringSet
- Print
Hello World
}
This run took 0.03s (0.03s CPU time)
Everything seems fine. Goodbye.
\end{lstlisting}
\end{minipage}
\caption{Left: A minimal \ARTS\ controlfile example. Right: \ARTS\ output
  when running this controlfile. } 
\label{fig:hello}
\end{figure}


\begin{figure}
\begin{lstlisting}
*------------------------------------------------------------*
Workspace variable = f_grid
--------------------------------------------------------------
The frequency grid for monochromatic pencil beam calculations.

Usage: Set by the user.
 
Unit:  Hz
--------------------------------------------------------------
Group = Vector
*------------------------------------------------------------*
\end{lstlisting}
\caption{Built-in documentation for variable \texttt{f\_grid}, obtained by
  command `\texttt{arts -d f\_grid}'.}
\label{fig:f_grid}
\end{figure}


\begin{figure}
\begin{lstlisting}
*---------------------------------------------------------*
Workspace method = WriteXML
-----------------------------------------------------------
Writes a workspace variable to an XML file.

This is a supergeneric method. It can write variables 
of any group.

If the filename is omitted, the variable is written
to <basename>.<variable_name>.xml.

Synopsis:

WriteXML( output_file_format, v, filename )

Authors: Oliver Lemke

Variables:

IN    output_file_format (String): Output file format.
GIN   v (Any): Variable to be saved.
GIN   filename (String, Default: ""): Name of the XML file.
*---------------------------------------------------------*
\end{lstlisting}
\caption{Built-in documentation for method \texttt{WriteXML}, obtained by
  command `\texttt{arts -d WriteXML}'.}
\label{fig:WriteXML}
\end{figure}


\begin{figure}
\begin{lstlisting}
*-------------------------------------------------------------------*
Workspace variable = abs_scalar_gas_agenda
---------------------------------------------------------------------

Calculation of scalar gas absorption.

This agenda calculates absorption coefficients for all gas species 
as a function of the given atmospheric state for one point in the 
atmosphere. The result is returned in *abs_scalar_gas*, the 
atmospheric state has to be specified by *rte_pressure*, 
*rte_temperature*, and *rte_vmr_list*.

A mandatory input parameter is f_index, which is used as follows:

1. f_index < 0 : Return absorption for all frequencies (in f_grid).

2. f_index >= 0 : Return absorption for the frequency indicated by
   f_index. 

The methods inside this agenda may require a lot of additional
input variables, such as *f_grid*, *species*, etc.
---------------------------------------------------------------------
Group  = Agenda
Output = abs_scalar_gas
Input  = f_index, rte_pressure, rte_temperature, rte_vmr_list
*-------------------------------------------------------------------*
\end{lstlisting}
\begin{minipage}[t]{0.48\hsize}
\begin{lstlisting}
AgendaSet( abs_scalar_gas_agenda ){
  abs_scalar_gasCalcLBL
}
\end{lstlisting}
\end{minipage}
\hspace*{\fill}
\begin{minipage}[t]{0.48\hsize}
\begin{lstlisting}
AgendaSet( abs_scalar_gas_agenda ){
  abs_scalar_gasExtractFromLookup
}
\end{lstlisting}
\end{minipage}
\caption{Top: Built-in documentation for variable
  \texttt{abs\_scalar\_gas\_agenda}, obtained by command `\texttt{arts -d
    abs\_scalar\_gas\_agenda}'. Bottom left: Controlfile agenda definition for
  line-by-line absorption calculation. Bottom right: Controlfile agenda
  definition to extract absorption from a pre-calculated lookup table.}
\label{fig:agendas}
\end{figure}


\begin{figure}[bt]
  \centering
  \includegraphics[width=0.9\textwidth]{fig_gridbox}
  \caption{A 2D atmospheric ``grid box'', in Cartesian coordinates. Atmospheric
    variables are defined at the corner points, marked with circles. The
    geometry of the grid box is determined by the sum of the geoid radius,
    $r_{[l]}$, and the geometrical altitude (above the geoid), $z_{[k,l]}$,
    where $k$ and $l$ are index for pressure and latitude, respectively. Along
    each pressure surface, the sum $r+z$ is assumed to vary linearly between
    the latitude (and longitude for 3D) grid points. }
  \label{fig:gridbox}
\end{figure}


\begin{figure}[bt]
  \centering
  \includegraphics[width=0.9\textwidth]{fig_ppath}
  \caption{Example of a propagation path. The circles mark the points defining
    the propagation path. The sensor is here found inside the atmosphere and
    the observation direction is downwards, without an interception with the
    surface. A distance criterion has also been applied.}
  \label{fig:ppath}
\end{figure}


\end{document}

