grid.tex

\section{Horizontal grids}
\label{HORIZONTAL_GRIDS}

Physical quantities of climate models are typically stored on a horizonal grid.
The maximum number of supported grid cells is 2147483647 (INT\_MAX).
This corresponds to a global regular lon/lat grid with 65455x32727
grid cells and a global resolution of 0.0055 degree.

\subsection{Grid area weights}
\label{GRID_AREA_WEIGHTS}

One single point of a horizontal grid represents the mean of a grid cell.
These grid cells are typically of different sizes, because the grid points are of varying distance.

Area weights are individual weights for each grid cell. 
%They take into account the different grid cell sizes when needed by a {\CDO} operator. 
They are needed to compute the area weighted mean or
variance of a set of grid cells (e.g. \htmlref{fldmean}{fldmean} - the mean value of all grid cells).
In {\CDO} the area weights are derived from the grid cell area.
If the cell area is not available then it will be computed from the geographical coordinates via spherical triangles.
This is only possible if the geographical coordinates of the grid cell corners are available or derivable.
Otherwise {\CDO} gives a warning message and uses constant area weights for all grid cells.

The cell area is read automatically from a NetCDF input file if a variable has the
corresponding ``cell\_measures'' attribute, e.g.:

\begin{lstlisting}[frame=single, backgroundcolor=\color{pcolor1}, basicstyle=\small]
var:cell_measures = "area: cell_area" ;
\end{lstlisting}

If the computed cell area is not desired 
then the {\CDO} operator \htmlref{setgridarea}{setgridarea} can be used to
set or overwrite the grid cell area.

\subsection{Grid description}
\label{GRID_DESCRIPTION}

In the following situations it is necessary to give a description of a horizontal grid:

\begin{itemize}
\item Changing the grid description (operator: \htmlref{setgrid}{setgrid})
\item Horizontal interpolation (all remapping operators)
\item Generating of variables (operator: \htmlref{const}{const}, \htmlref{random}{random})
\end{itemize}

As now described, there are several possibilities to define a horizontal grid.

\subsubsection{Predefined grids}

Predefined grids are available for global regular, gaussian or icosahedral-hexagonal GME grids.
% They have the following predefined grid names: 
%\texttt{r<NX>x<NY>}, \texttt{lon=<LON>/lat=<LAT>}, \texttt{n<N>} and \texttt{gme<NI>}

\subsubsection*{Global regular grid: \texttt{global\_<DXY>}}
    \texttt{global\_<DXY>} defines a global regular lon/lat grid.
    The grid increment \texttt{<DXY>} can be selected at will.
    The longitudes start at \texttt{<DXY>}/2 - 180$^\circ$ and the
    latitudes start at \texttt{<DXY>}/2 - 90$^\circ$.

\subsubsection*{Global regular grid: \texttt{r<NX>x<NY>}}
    \texttt{r<NX>x<NY>} defines a global regular lon/lat grid.
    The number of the longitudes \texttt{<NX>} and the latitudes \texttt{<NY>} can be selected at will.
    The longitudes start at 0$^\circ$ with an increment of (360/\texttt{<NX>})$^\circ$.
    The latitudes go from south to north with an increment of (180/\texttt{<NY>})$^\circ$.

\subsubsection*{One grid point: \texttt{lon=<LON>/lat=<LAT>}}
    \texttt{lon=<LON>/lat=<LAT>} defines a lon/lat grid with only one grid point.

\subsubsection*{Global Gaussian grid: \texttt{n<N>}}
    \texttt{n<N>} defines a global Gaussian grid. \texttt{N} specifies the number of
    latitudes lines between the Pole and the Equator.
    The longitudes start at 0$^\circ$ with an increment of (360/nlon)$^\circ$.
    The gaussian latitudes go from north to south.

%\subsubsection*{Spherical harmonics: t$<$RES$>$spec}
%    t$<$RES$>$spec defines the spectral coefficients of a global gaussian grid.
%    Each valid triangular resolution can be used for $<$RES$>$.

\subsubsection*{Global icosahedral-hexagonal GME grid: \texttt{gme<NI>}}
    \texttt{gme<NI>} defines a global icosahedral-hexagonal GME grid.
    \texttt{NI} specifies the number of intervals on a main triangle side.

\subsubsection{Grids from data files}

You can use the grid description from an other datafile.
The format of the datafile and the grid of the data field must be supported by {\CDO} .
Use the operator '\htmlref{sinfo}{sinfo}' to get short informations about your variables and the grids.
If there are more then one grid in the datafile the grid description of the first variable will be used.

\subsubsection{SCRIP grids}

SCRIP (Spherical Coordinate Remapping and Interpolation Package) uses
a common grid description for curvilinear and unstructured grids.
For more information about the convention see \cite{SCRIP}.
This grid description is stored in NetCDF. Therefor it is only
available if {\CDO} was compiled with NetCDF support!

\vspace{2mm}

%\begin{minipage}[t]{\textwidth}
SCRIP grid description example of a curvilinear MPIOM \cite{MPIOM} GROB3 grid (only the NetCDF header):
\begin{lstlisting}[frame=single, backgroundcolor=\color{pcolor1}, basicstyle=\footnotesize]
    netcdf grob3s {
    dimensions:
            grid_size = 12120 ;
            grid_xsize = 120 ;
            grid_ysize = 101 ;
            grid_corners = 4 ;
            grid_rank = 2 ;
    variables:
            int grid_dims(grid_rank) ;
            float grid_center_lat(grid_ysize, grid_xsize) ;
                    grid_center_lat:units = "degrees" ;
                    grid_center_lat:bounds = "grid_corner_lat" ;
            float grid_center_lon(grid_ysize, grid_xsize) ;
                    grid_center_lon:units = "degrees" ;
                    grid_center_lon:bounds = "grid_corner_lon" ;
            int grid_imask(grid_ysize, grid_xsize) ;
                    grid_imask:units = "unitless" ;
                    grid_imask:coordinates = "grid_center_lon grid_center_lat" ;
            float grid_corner_lat(grid_ysize, grid_xsize, grid_corners) ;
                    grid_corner_lat:units = "degrees" ;
            float grid_corner_lon(grid_ysize, grid_xsize, grid_corners) ;
                    grid_corner_lon:units = "degrees" ;

    // global attributes:
                    :title = "grob3s" ;
    }
\end{lstlisting}
%\end{minipage}

% \subsubsection{PINGO grids}

% PINGO uses a very simple grid description in ASCII format
% to describe regular longitude/latitude or global gaussian grids.
% All PINGO grid description files are supported by {\CDO}. 
% For more information about this format see \cite{PINGO}.

% \vspace{2mm}

% %\begin{minipage}[t]{\textwidth}
% PINGO grid description example of a T21 gaussian grid:
% \begin{lstlisting}[frame=single, backgroundcolor=\color{pcolor1}, basicstyle=\footnotesize]
%     Grid Description File
%     (Comments start at non digit characters and end at end of line)
%     First part: The dimensions.
%     64 32 = Number of longitudes and latitudes
%     Second part: The listed longitudes.
%     2 means equidistant longitudes
%     0.000000 5.625000 = Most western and second most western longitude
%     Third part: The listed latitudes.
%     32 means all 32 latitudes are given in the following list:
%      85.761  80.269  74.745  69.213  63.679  58.143  52.607  47.070
%      41.532  35.995  30.458  24.920  19.382  13.844   8.307   2.769
%      -2.769  -8.307 -13.844 -19.382 -24.920 -30.458 -35.995 -41.532
%     -47.070 -52.607 -58.143 -63.679 -69.213 -74.745 -80.269 -85.761
% \end{lstlisting}
% %\end{minipage}

\subsubsection{CDO grids}

All supported grids can also be described with the {\CDO} grid description.
%The {\CDO} grid description is an ASCII formatted file.
%It is a common grid description for all available grids.
The following keywords can be used to describe a grid:

\vspace{3mm}
\begin{tabular}[b]{lll}
Keyword           & Datatype     & Description \\ \hline
\textbf{gridtype}     & STRING       & Type of the grid (gaussian, lonlat, curvilinear, unstructured). \\
\textbf{gridsize}     & INTEGER      & Size of the grid. \\
\textbf{xsize}        & INTEGER      & Size in x direction (number of longitudes). \\
\textbf{ysize}        & INTEGER      & Size in y direction (number of latitudes). \\
\textbf{xvals}        & FLOAT ARRAY  & X values of the grid cell center. \\
\textbf{yvals}        & FLOAT ARRAY  & Y values of the grid cell center.\\
\textbf{nvertex}      & INTEGER      & Number of the vertices for all grid cells. \\
\textbf{xbounds}      & FLOAT ARRAY  & X bounds of each gridbox. \\
\textbf{ybounds}      & FLOAT ARRAY  & Y bounds of each gridbox. \\
\textbf{xfirst, xinc} & FLOAT, FLOAT & Macros to define xvals with a constant increment, \\
                         &                         & xfirst is the x value of the first grid cell center. \\
\textbf{yfirst, yinc} & FLOAT, FLOAT & Macros to define yvals with a constant increment, \\
                         &                         & yfirst is the y value of the first grid cell center. \\
%xname        & STRING       & name of the x axis \\
%xlongname    & STRING       & longname of the x axis \\
\textbf{xunits}       & STRING       & units of the x axis \\
%yname        & STRING       & name of the y axis \\
%ylongname    & STRING       & longname of the y axis \\
\textbf{yunits}       & STRING       & units of the y axis \\
\end{tabular}

\vspace{4mm}

Which keywords are necessary depends on the gridtype.
The following table gives an overview of the default values or the size
with respect to the different grid types.

%\vspace{2mm}
%\begin{tabular}[b]{|c|c|c|c|c|c|c|c|c|}
%\hline
%gridtype    & gridsize     & xsize & ysize & xvals    & yvals    & nvertex & xbounds     & ybounds \\
%\hline
%\hline
%gaussian    & xsize*ysize  & nlon  & nlat  & xsize    & ysize    & 2       & 2*xsize     & 2*ysize \\
%\hline
%lonlat      & xsize*ysize  & nlon  & nlat  & xsize    & ysize    & 2       & 2*xsize     & 2*ysize \\
%\hline 
%curvilinear & xsize*ysize  & nlon  & nlat  & gridsize & gridsize & 4       & 4*gridsize  & 4*gridsize \\
%\hline
%cell        & ncell        &       &       & gridsize & gridsize & nv      & nv*gridsize & nv*gridsize \\
%\hline
%\end{tabular}
%\vspace{2mm}

\vspace{2mm}
\hspace{2cm}
\begin{tabular}[c]{|>{\columncolor{pcolor1}}l|c|c|c|c|c|}
\hline
\rowcolor{pcolor1}
\cellcolor{pcolor2}
gridtype   & lonlat      & gaussian    & projection &curvilinear & unstructured \\
\hline
gridsize   & xsize*ysize & xsize*ysize & xsize*ysize & xsize*ysize & \textbf{ncell} \\
\hline
xsize      & \textbf{nlon} & \textbf{nlon} & \textbf{nx} & \textbf{nlon} & gridsize \\
\hline
ysize      & \textbf{nlat} & \textbf{nlat} & \textbf{ny} &  \textbf{nlat} & gridsize \\
\hline
xvals      & xsize & xsize & xsize &  gridsize & gridsize \\
\hline
yvals      & ysize & ysize & ysize &  gridsize & gridsize \\
\hline
nvertex    & 2 & 2 & 2 &  4 & \textbf{nv} \\
\hline
xbounds    & 2*xsize & 2*xsize & 2*xsize &  4*gridsize & nv*gridsize \\
\hline
ybounds    & 2*ysize & 2*ysize & 2*xsize &  4*gridsize & nv*gridsize \\
\hline
xunits    & degrees & degrees & m &  degrees & degrees \\
\hline
 yunits    & degrees & degrees & m &  degrees & degrees \\
\hline
%xname      &  &  &  &  \\
%\hline
%xlongname  &  &  &  &  \\
%\hline
%xunits     &  &  &  &  \\
%\hline
%yname      &  &  &  &  \\
%\hline
%ylongname  &  &  &  &  \\
%\hline
%yunits     &  &  &  &  \\
%\hline
\end{tabular}

\vspace{3mm}

The keywords nvertex, xbounds and ybounds are optional if area weights are not needed.
The grid cell corners xbounds and ybounds have to rotate counterclockwise.

\vspace{2mm}

%\begin{minipage}[t]{\textwidth}
{\CDO} grid description example of a T21 gaussian grid:
\begin{lstlisting}[frame=single, backgroundcolor=\color{pcolor1}, basicstyle=\footnotesize]
    gridtype = gaussian
    xsize    = 64
    ysize    = 32
    xfirst   =  0
    xinc     = 5.625
    yvals    = 85.76  80.27  74.75  69.21  63.68  58.14  52.61  47.07
               41.53  36.00  30.46  24.92  19.38  13.84   8.31   2.77
               -2.77  -8.31 -13.84 -19.38 -24.92 -30.46 -36.00 -41.53
              -47.07 -52.61 -58.14 -63.68 -69.21 -74.75 -80.27 -85.76
\end{lstlisting}
%\end{minipage}

\vspace{2mm}

%\begin{minipage}[t]{\textwidth}
{\CDO} grid description example of a global regular grid with 60x30 points:
\begin{lstlisting}[frame=single, backgroundcolor=\color{pcolor1}, basicstyle=\footnotesize]
    gridtype = lonlat
    xsize    =   60
    ysize    =   30
    xfirst   = -177
    xinc     =    6
    yfirst   =  -87
    yinc     =    6
\end{lstlisting}
%\end{minipage}

% \vspace{2mm}

% For a lon/lat grid with a rotated pole, the north pole must be defined.
% As far as you define the keywords xnpole/ynpole all coordinate values
% are for the rotated system.

\vspace{2mm}

%\begin{minipage}[t]{\textwidth}
{\CDO} grid description example of a regional rotated lon/lat grid:
\begin{lstlisting}[frame=single, backgroundcolor=\color{pcolor1}, basicstyle=\footnotesize]
   gridtype = projection
   xsize    = 81
   ysize    = 91
   xunits   = "degrees"
   yunits   = "degrees"
   xfirst   =  -19.5
   xinc     =    0.5
   yfirst   =  -25.0
   yinc     =    0.5
   grid_mapping_name = rotated_latitude_longitude
   grid_north_pole_longitude = -170
   grid_north_pole_latitude = 32.5
\end{lstlisting}
%\end{minipage}

Example {\CDO} descriptions of a curvilinear and an unstructured grid can be found
in \htmlref{Appendix C}{appendixgrid}.

%#define  GRID_GENERIC             1
%#define  GRID_GAUSSIAN            2
%#define  GRID_GAUSSIAN_REDUCED    3
%#define  GRID_LONLAT              4
%#define  GRID_SPECTRAL            5
%#define  GRID_FOURIER             6
%#define  GRID_TRIANGULAR          7
%#define  GRID_TRAJECTORY          8
%#define  GRID_CELL                9
%#define  GRID_CURVILINEAR        10

%gaussian   curv cell
%regular    curv cell
%triangular      cell

%regular (regelmaessig)
%square (quadratisches) grid is a grid formed by tiling the plane regularly with squares
%A triangular grid, also called an isometric grid (Gardner 1986, pp. 209-210), is a grid fo
%rmed by tiling the plane regularly with equilateral triangles. 

%quadrilateral (vierseitige)

%rectangular (rechteckig)
%  gaussian
%  regular lon/lat

%nonrectangular

%  triangular
%  hexagonal (GME)
%  curvilinear (krummlinig)
%  generic

% retilinear (geradlinig)