\chapter{Propagation paths}
 \label{sec:ppath}


\starthistory
  120202 & Revised and parts moved to \theory\ (Patrick Eriksson).\\
  030310 & First complete version written by Patrick Eriksson.\\
\stophistory


\graphicspath{{Figs/ppath/}}


A propagation path is the name given in ARTS to the way the radiation travels
to reach the sensor for a specified line-of-sight. Propagation paths are
introduced in Section \ref{sec:fm_defs:ppaths} and this section provides
further details. For a general usage of ARTS, it should suffice to read
Section~\ref{sec:ppath:usage}. The remaining sub-sections deal with more
low-level aspects of the calculations, and are of interest only if you want to
understand the finer details of ARTS. The actual equations applied are found in
Chapter~\ref{T-sec:ppaththeory} of \theory.


\section{Practical usage}
%===================
\label{sec:ppath:usage}

The overall calculation approach for finding the propagation path is specified
by \wsaindex{ppath\_agenda}. The standard choice for this agenda is
\wsmindex{ppathStepByStep}, applying \builtindoc{ppath\_step\_agenda}
repeatedly in order to trace the path backwards, starting at the sensor. This
set-up is assumed throughout this chapter. A slighltly different selection of
workspace methods is required for radio link calculations, see further
Section~\ref{sec:rlinks}.

The exact ray tracing algorithm to be applied for the calculation of
propagation path is selected through \wsaindex{ppath\_step\_agenda}
(see further Section~\ref{sec:fm_defs:ppaths}). The fastest calculations are
obtained if refraction is neglected, denoted as geometrical calcutions. The
workspace method to apply if this assumption can be made is
\wsmindex{ppath\_stepGeometric}.

The main consideration for using \builtindoc{ppath\_stepGeometric} is to select
a value for \wsvindex{ppath\_lmax}. This variable controls to some extent the
calculation accuarcy, as described in Section~\ref{sec:fm_defs:accuracy}. This
variable sets the maximum distance between points of the propagation
path. Set this variable to e.g.\ -1 if you don't want to apply such a length
criterion.

A straightforward, but inefficient, treatment of refraction is provided by
\wsmindex{ppath\_stepRefractionBasic}. This method divides the propagation path
into a series of geomtrical ray tracing steps. The size of the ray tracing
steps is selected by \wsvindex{ppath\_lraytrace}. This variable affects only
the ray tracing part, the distance between points of the propagation path
actually returned is controled by \builtindoc{ppath\_lmax} as above. At each
ray tracing step, the refractive index is evaluated according to the
specification of \wsaindex{refr\_index\_air\_agenda}. Several methods to
determine refractive index are available (see Chapter~\ref{sec:rindex}).



\section{Calculation approach}
%===================
\label{sec:ppath:approach}

The propagation paths are calculated in steps, as outlined in
Section~\ref{sec:fm_defs:ppaths}. The path steps are normally from one crossing
of the atmospheric grids to next. To introduce
propagation paths steps was necessary to handle the iterative solution for
scattering inside the cloud box, as made clear from Figure
\ref{T-fig:scattering:average} of \theory.

A full propagation path is stored in the workspace variable \wsvindex{ppath},
that is of the type \builtindoc{Ppath} (see Section \ref{sec:ppath:Ppath}). The
paths are determined by calculating a number of path steps. A path step is the
path from a point to the next crossing of either the pressure, latitude or
longitude grid (Figure~\ref{fig:ppath:ex1}). There is one exception to this
definition of a path step, and that is when there is an intersection with the
surface, which ends the propagation path at that point. The starting point for
the calculation of a path step is normally a grid crossing point, but can also
be an arbitrary point inside the atmosphere, such as the sensor position. The
path steps are stored in the workspace variable \wsvindex{ppath\_step}, that is
of the same type as \builtindoc{ppath}.

\begin{figure}
 \begin{center}
  \includegraphics*[width=0.80\hsize]{ppath_ex1}
  \caption{Tracking of propagation paths. For legend, see 
    Figure \ref{fig:ppath:ex2}. The figure tries to visualize how the
    calculations of propagation paths are performed from one grid cell
    to next. In this example, the calculations start directly at the
    sensor position $(\ast)$ as it placed inside the model
    atmosphere. The circles give the points defining the propagation
    path. Path points are always included at the crossings of the grid
    cell boundaries. Such a point is then used as the starting point
    for the calculations inside the next grid cell. }
  \label{fig:ppath:ex1}  
 \end{center}
\end{figure}
% This figure was produced by the Matlab function mkfigs_ppath

\begin{figure}
 \begin{center}
   \includegraphics*[width=0.98\hsize]{ppath_ex2}
  \caption{As Figure \ref{fig:ppath:ex1}, but with a length criterion 
    for the distance between the points defining the path.
    Note: Tangent points are no longer included automatically.}
  \label{fig:ppath:ex2}  
 \end{center}
\end{figure}
% This figure was produced by the Matlab function mkfigs_ppath


Propagation paths are calculated with the internal function
\funcindex{ppath\_calc}. The communication between this method and
\builtindoc{ppath\_step\_agenda} is handled by \builtindoc{ppath\_step}.
That variable is used both as input and output to
\builtindoc{ppath\_step\_agenda}.  The agenda gets back
\builtindoc{ppath\_step} as returned to \funcindex{ppath\_calc} and the
last path point hold by the structure is accordingly the starting
point for the new calculations. If a total propagation path shall be
determined, the agenda is called repeatedly until the starting point
of the propagation path is found. 

The path is determined by starting at the end point and moving
backwards to the starting point. The calculations are initiated by
filling \builtindoc{ppath\_step} with the practical end point of the
path. This is either the position of the sensor (true or
hypothetical), or some point at the top of the atmosphere (determined
by geometrical calculations starting at the sensor).

The agenda performs only calculations to next crossing of a grid, all
other tasks are performed by \funcindex{ppath\_calc}, with one exception.
If there is an intersection with the surface, the calculations stop at
this point. This is flagged by setting the background field of
\builtindoc{ppath\_step}. Beside this, \funcindex{ppath\_calc} checks if
the starting point of the calculations is inside the cloud box or
below the surface level, and check if the last point of the path has
been reached. 

%In many cases the propagation path can/must be considered to consist
%of several parts. One exemple is surface reflection (see
%Figure \ref{fig:fm_defs:surface_refl}). The variable \builtindoc{ppath}
%describes then only a single part of the propagation path.


\section{Spacing of additional path points}
%===================
\label{sec:ppath:lmax}

The strategy when considering \wsvindex{ppath\_lmax} differs somewhat between
the workspace methods. For pure geometrical calculations, the points are spaced
evenly inside the grid box. That is, the points are separated with the same
distance ($\leq$\,\builtindoc{ppath\_lmax}). 

When refraction is considered, the ray tracing moves forward in steps following
\wsvindex{ppath\_lraytrace}. When another step of this size would result in a
distance $>$\,\builtindoc{ppath\_lmax}, the present point is added to
$\leq$\,\builtindoc{ppath\_step}. A consequence of this is that additional
points are likely not evenly spaced. The distance between most points will be
\wsvindex{ppath\_lraytrace} times an integer value, but the distance between
the last additional point and the grid border can be any number
($\leq$\,\builtindoc{ppath\_lmax}). If \builtindoc{ppath\_step} is set to be
negative, no additional points are included, as for geometrical calculations.

As points are always included in the propagation paths at the crossings of the
atmospheric grids, making these grids finer will give shorter path steps.
However, it is neither good practise or efficient to use the atmospheric grids
to control the accuracy of the radiative transfer calculations. An upper limit
on the step length (\builtindoc{ppath\_lmax}) shall be applied for this
purpose.


\section{Tangent points}
%===================
The term ``\textindex{tangent point}'' refers to the point of a limb sounding
path with the lowest altitude. For 1D cases this definition is clear, but for
2D and 3D calculations there are complications. First of all, there are two
different possible definitions: the point having the lowest radius (ie.\
distance to the planets centre) or the point with the lowest altitude (ie.\
vertical distance to the reference ellipsoid). The later is the more important
with respect to optical thickness of the path, but the point of the highest
pressure would be an even more relevant definition in this context. Another
complication is that with refraction there can in principle exist more than one
tangent point.

Up to ARTS-2.0 minimum-radius tangent points were added as extra points to the
propagation paths (a reminiscent from ARTS-1), but this feature has now been
removed following the discussion in the paragraph above. However, many internal
functions make use of the concept of tangent point (as the minimum-radius
one). The altitude-based tangent point for a propagation path can be determined
with the method \wsmindex{TangentPointExtract}.



\section{The propagation path data structure}
%===================
\label{sec:ppath:Ppath}

A propagation path is represented by a structure of type
\typeindex{Ppath}. This structure holds also auxiliary variables to
facilitate the radiative transfer calculations and to speed up the
interpolation. The fields of \builtindoc{Ppath} are as follows:

\begin{description}

  \item[dim] [Index] The atmospheric dimensionality. This field shall always 
     be equal to the workspace variable \builtindoc{atmosphere\_dim}.
     
   \item[np] [Index] Number of positions to define the propagation path through
     the atmosphere. Allowed values are $\geq 1$. The number of rows of
     \shortcode{pos} and \shortcode{los}, and the length of \shortcode{z},
     \shortcode{gp\_p}, \shortcode{gp\_lat} and \shortcode{gp\_lon}, shall be
     equal to \shortcode{np}. The length of \shortcode{l\_step} is
     \shortcode{np} - 1. If \shortcode{np} $\leq$ 1, the observed spectrum is
     identical to the radiative background. For cases where the sensor is
     placed inside the model atmosphere and \shortcode{np} = 1, the stored
     position is identical to the sensor position and that position can be used
     to determinate the radiative background (see below).

   \item[constant] [Numeric] The propagation path constant. It is defined as
     the product: $\Rds n \sin(\ZntAng)$ (see Chapter~\ref{T-sec:ppath:refr1D}
     of \theory), at the position of the sensor. This is a true constant for
     the path just for 1D atmospheres, but can be useful also in other cases.
     For example, it equals the impact parameter normally used to define limb
     radio occultations. This field is initiated -1, to indicate that the
     constant is not yet set.

   \item[background] [String] The radiative background for the propagation
     path. The possible options for this field are 'space', 'surface', 'cloud
     box interior' and 'cloud box level', where the source of radiation
     should be clear the content of the strings.
     
   \item[start\_pos] [Vector] The practical start position of the propagation
     path. This vector equals in general the last row of \shortcode{pos}. The
     exception is radio link calculations where the transmitter is placed above
     the model atmosphere, where this field gives the position of the
     transmitter.

   \item[start\_los] [Vector] Line-of-sight at start point of propagation
     path. Set and used in the same way as \shortcode{start\_pos}.

   \item[start\_lstep] [Numeric] The distance between \shortcode{start\_pos}
     and the last position in \shortcode{pos}. This value is zero, except for a
     transmitter placed above the top-of-the-atmosphere. Hence, this length
     corresponds to propgation if free space (n=1).

   \item[end\_pos] [Vector] The end position of the propagation path. If
     the point is placed inside the atmosphere, this field is redundant as it
     is equal to the first row of \shortcode{pos}, but identifies the sensor
     position for observations from space.

   \item[end\_los] [Vector] The line-of-sight at the end point of the
     propagation path. Provides additional information if the sensor is placed
     above the top-of-the-atmosphere, and gives then the observation direction
     of the sensor.

   \item[end\_lstep] [Numeric] The distance between \shortcode{end\_pos}
     and the first position in \shortcode{pos}. This value is non-zero just if
     the sensor is placed above the top-of-the-atmosphere. Hence, this length
     corresponds to propgation if free space (n=1).

   \item[pos] [Matrix] The position of the propagation path points inside the
     atmosphere. This matrix has \shortcode{np} rows and up to 3 columns. Each
     row holds a position where column 1 is the radius, column 2 the latitude
     and column 3 the longitude (cf. Section \ref{sec:fm_defs:sensorpos}). The
     number of columns for 1D and 2D is 2, while for 3D it is 3. The latitudes
     are stored for 1D cases as these can be of interest for some applications
     and are useful if the propagation path shall be plotted. The latitudes for
     1D give the angular distance to the sensor (see further Section
     \ref{sec:fm_defs:atmdim}). The propagation path is stored in reversed
     order, that is, the position with index 0 is the path point closest to the
     sensor (and equals \shortcode{start\_pos} if it is inside the atmosphere).
%     The full path is stored also for 1D cases with symmetry around a tangent
%     point (in contrast to ARTS-1).
     
   \item[los] [Matrix] The line-of-sight of the propagation path at
     each point. The number of rows of the matrix is \shortcode{np}.
     For 1D and 2D, the matrix has a single column holding the zenith
     angle. For 3D there is an additional column giving the azimuth
     angle. The zenith and azimuth angles are defined in
     Section \ref{sec:fm_defs:los}. If the radiative background is the
     cloud box, the last position (in \shortcode{pos}) and
     line-of-sight give the relevant information needed when
     extracting the radiative background from the cloud box intensity
     field.
     
   \item[r] [Vector] The radius for each path position. The length of this
     vector is accordingly \shortcode{np}. This is a help variable for plotting
     and similar purposes. 
     
   \item[lstep] [Vector] The length along the propagation path
     between the positions in \shortcode{pos}. The first value is the
     length between the first and second point etc. 

   \item[nreal] [Vector] The real part of the refractive index at each path
     position. This index corresponds to the phase velocity.

   \item[ngroup] [Vector] The group index of refraction. This index corresponds
     to the group velocity.

   \item[gp\_p] [ArrayOfGridPos] Index position with respect to the
     pressure grid. The structure for grid positions is described in
     \developer, Section \ref{D-sec:interpolation:gridpos}. 
     
   \item[gp\_lat] [ArrayOfGridPos] As \shortcode{gp\_p} but with
     respect to the latitude grid.

   \item[gp\_lon] [ArrayOfGridPos] As \shortcode{gp\_p} but with
     respect to the longitude grid.     
\end{description}


\section{Further reading}
%===================
The implementation, calculation approaches and the numerical expressions used
are discussed in Chapter~\ref{T-sec:ppaththeory} of \theory.




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

% LocalWords:  ppath cc stepGeometric stepGeometricWithLmax ppathCalc pos los
% LocalWords:  ArrayOfGridPos geom ppc geomppath gridpos fd gridrange Eq Eqs
% LocalWords:  rodgers WGS montenbruck
