
\levela{WSVs, WSMs, and agendas}
%-------------------------------
\label{sec:agendas}

\starthistory
  020605 & Created by Stefan Buehler.\\
\stophistory

This chapter deals with the main components of ARTS: \emph{Workspace
  variables}\index{workspace variables} (\textindex{WSVs}) and
\emph{workspace methods}\index{workspace methods} (\textindex{WSMs}).
Furthermore, it explains the use of \textindex{agendas}, a special
group of WSVs.

\levelb{Implementation files}
%----------------------------
\label{sec:agendas:files}

The two most important files are:
\begin{itemize}
\item \fileindex{workspace.cc}: Definition and documentation of WSVs.
\item\fileindex{methods.cc}: Definition and documentation of WSMs. The
  implementations of WSMs reside in files named
  \artsstyle{m\_something.cc}.
\end{itemize}
It is very likely that you will have to edit these. Less likely, but
possibly, you also have to edit:
\begin{itemize}
\item \fileindex{groups.cc}: Definition of WSV groups.
\end{itemize}

\vspace{2ex}
When ARTS is built, a number of source code files are generated
automatically. They are listed here in the order in which they are
generated: 
\begin{itemize}
\item \fileindex{auto\_wsv\_groups.h}:\\
  Generated from \artsstyle{groups.cc}.
\item \fileindex{auto\_wsv.h}, \fileindex{auto\_wsv\_pointers.cc}:\\
  Generated from \artsstyle{auto\_wsv\_groups.h} and \artsstyle{workspace.cc}. 
\item \fileindex{auto\_md.h}, \fileindex{auto\_md.cc}:\\
  Generated from \artsstyle{auto\_wsv\_groups.h},
  \artsstyle{auto\_wsv.h}, and \artsstyle{methods.cc}.
\end{itemize}
This is achieved by a set of simple C++ programs:
\begin{itemize}
\item \fileindex{make\_auto\_wsv\_groups\_h.cc}
\item \fileindex{make\_auto\_wsv\_h.cc}
\item \fileindex{make\_auto\_wsv\_pointers\_cc.cc}
\item \fileindex{make\_auto\_md\_h.cc}
\item \fileindex{make\_auto\_md\_cc.cc}
\end{itemize}
The meaning of the names should be self-explanatory. There is one program
for each file to be generated.  The generation of the
\artsstyle{auto\_} files happens automatically when you do a
\artsstyle{make}. Therefore, never edit any of these files.

Finally, there are some files that contain the internal implementation
of WSVs, WSMs, and agendas. These are:
\begin{itemize}
\item \fileindex{wsv\_aux.h}, \fileindex{wsv\_aux.cc},
  \fileindex{workspace\_aux.cc}: Implementation of class
  \typeindex{WsvRecord}, which stores the lookup information for one
  WSV, plus auxiliary stuff for the workspace.
\item \fileindex{methods.h}, \fileindex{methods\_aux.cc}:
  Implementation of class \typeindex{MdRecord}, which stores the
  lookup information for one WSM.
\item \fileindex{agenda.h}, \fileindex{agenda.cc}: Implementation of
  class \typeindex{MRecord}, which stores runtime information for one WSM,
  and class \typeindex{Agenda}, which stores an agenda.
\end{itemize}

\vspace{2ex}
As mentioned above, you will not have to modify any of these files,
they are listed here just for reference. Normally, you only have to
modify \artsstyle{workspace.cc} and \artsstyle{methods.cc}.


\levelb{Workspace Variables or WSVs}
%--------------------------
\label{sec:agendas:wsvs}

All important variables in ARTS are WSVs. This means that they can be
manipulated by a list of WSMs, which is specified in the ARTS
controlfile. There exists a predefined list of possible WSVs. This
list defines the \emph{workspace}. One can think of each WSV as a
`slot' in the workspace: The WSV can be either \emph{set}, or
\emph{unset}. Set means that the WSV has a well-defined content, unset
means that it has no well-defined content. At the start of an ARTS job
all WSVs are unset.

WSVs are defined in the file \fileindex{workspace.cc}. A typical
definition looks like this:

{\small
\begin{verbatim}
  wsv_data.push_back
   (WsvRecord
    ("f_grid",
     "The frequency grid for monochromatic pencil beam\n"
     "calculations.\n"
     "\n"
     "Usage:      Set by the user.\n"
     "\n"
     "Unit:       Hz",
     Vector_ ));
\end{verbatim}}

All WSV definitions have the same three elements:
\begin{enumerate}
\item The \emph{name} of the WSV. It has to be used with exactly the
  same name in the code.
\item The \emph{documentation}. This is normally much longer than in
  the example here. It must fully describe the WSV, its purpose, and
  its normal usage. See file \artsstyle{workspace.cc} for instructions
  how to write the documentation.
\item The \emph{group} to which the WSV belongs. You can think of a
  group as something similar to a C++ data type. The WSV in the
  example belongs to the group \artsstyle{Vector}. The allowed groups
  are defined in file \fileindex{groups.cc}. Note that you have to add
  an underscore to the group name.
  % FIXME: Add reference to list of groups in appendix here, when implemented.
\end{enumerate}

\levelb{Workspace Methods or WSMs}
%--------------------------
\label{sec:agendas:wsms}

WSMs manipulate WSVs to produce other WSVs. There are three kinds of
WSM:
\begin{enumerate}
\item Specific WSM.
\item Generic WSM.
\item Agenda WSM.
\end{enumerate}
As in the case of WSVs, there is a central place in ARTS where
information on the available WSMs is stored. This place is the file
\fileindex{methods.cc}. It contains a record for each WSM, which
schematically looks like this: 

FIXME: Continue here.

\begin{verbatim}

\end{verbatim}

\levelb{Agendas}
%--------------------------
\label{sec:agendas:agendas}



%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "uguide"
%%% End: 

