\chapter{Batch calculations}
 \label{sec:batch}

% Document history, format:
%  \starthistory
%    date1 & text .... \\
%    date2 & text .... \\
%    ....
%  \stophistory

\starthistory
  090330 & Description of \builtindoc{ybatch\_start} added by Stefan Buehler.\\
  070726 & Copy-edited by Stefan Buehler.\\
  070618 & Updated by Oliver Lemke.\\
  040916 & Created by Patrick Eriksson.\\
\stophistory

Quite often one wants to repeat a large number of calculations with
only a few variables changed. Examples of such cases are to perform 1D
calculations for a number of atmospheric states taken from some
atmospheric model, generate a set of spectra to create a training
database for regression based inversions or perform a numeric
inversion error analysis. For such calculations it is inefficient to
perform the calculations by calling ARTS repeatedly. For example, as
data must be imported for each call even if the data are identical
between the cases. Cases such as the ones described above are here
denoted commonly as batch calculations.

\section{Batch calculations of measurement vector y}

Batch calculations of measurement vectors are done by the WSM
\wsmindex{ybatchCalc}, which takes three inputs, the indices  
\wsvindex{ybatch\_start} and \wsvindex{ybatch\_n}, and the agenda
\wsaindex{ybatch\_calc\_agenda}.

The method \builtindoc{ybatchCalc} will do \builtindoc{ybatch\_n}
calculations, starting at index \builtindoc{ybatch\_start}. It will run
the agenda \builtindoc{ybatch\_calc\_agenda} for each case
individually. The agenda gets an input \wsvindex{ybatch\_index}, which
it should use to extract the right input data from one or more arrays
or matrices of input. Execution of \builtindoc{ybatch\_calc\_agenda}
must result in a new spectrum vector, \builtindoc{y}, most likely by a
call of \builtindoc{yCalc}.

The WSV \builtindoc{ybatch\_start} is set to a default of 0 in
\shortcode{general.arts}, so you do not have to set this variable
unless you want to start somewhere in the middle of your batch input
data. 

The next section gives some examples of what could be put inside
the \builtindoc{ybatch\_calc\_agenda}.

\section{Control file examples}
%
The WSV \wsmindex{Extract} can be used to extract an element from an
Array, a row from a \builtindoc{Matrix}, a
\builtindoc{Matrix} from a \builtindoc{Tensor3}, and so on. The
selection is always done on the first dimension. So, for a
\builtindoc{Tensor3} as input, it copies the page with the given index
from the input \builtindoc{Tensor3} variable to the output
\builtindoc{Matrix}.

The idea here is to store the batch cases in tensors or arrays with
one dimension extra compared to corresponding workspace variables. For
example, a set of \builtindoc{t\_field} (which is of type
\builtindoc{Tensor3}) is stored as \builtindoc{Tensor4}.

If the dimension is the same for all batch cases, tensors are
appropriate. If the dimensions vary (for example you have a different
number of vertical levels for each case), then arrays are appropriate.

In the following 1D example, five atmospheric scenarios
have been put into the three first loaded files, and a random vector
of zenith angles is found in the last file. The batch calculations
are then performed as:

\begin{code}
ReadXML( tensor4_1, "batch_t_field.xml" )
ReadXML( tensor4_2, "batch_z_field.xml" )
ReadXML( tensor5_1, "batch_vmr_field.xml" )
ReadXML( tensor3_1, "batch_za.xml" )
IndexSet( ybatch_n, 5 )

AgendaSet ( ybatch_calc_agenda ){
  Print( ybatch_index, 0 )
  Extract( t_field,    tensor4_1, ybatch_index )
  Extract( z_field,    tensor4_2, ybatch_index )
  Extract( vmr_field,  tensor5_1, ybatch_index )
  Extract( sensor_los, tensor3_1, ybatch_index )

  yCalc
}

ybatchCalc

WriteXML( "ascii", ybatch )
\end{code}

If you then want to repeat the calculations, for example with another
propagation path step length (e.g. 25\,km), it is sufficient to add
the lines:

\begin{code}
AgendaSet( ppath_step_agenda ){
   ppath_stepGeometric( ppath_step, atmosphere_dim, lat_grid,
                        lon_grid,z_field, refellipsoid, z_surface,
                        25e3 )
}

ybatchCalc

WriteXML( "ascii", ybatch, "ybatch_run2.xml" )
\end{code}

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

