formats.tex 9.6 KB
Newer Older
Uwe Schulzweida's avatar
Uwe Schulzweida committed
1
2
%Every input and output file is a collection of 2D or 3D variables
%over an unlimited number of time steps.
Uwe Schulzweida's avatar
Uwe Schulzweida committed
3

Uwe Schulzweida's avatar
Uwe Schulzweida committed
4
\section{GRIB}
5

Uwe Schulzweida's avatar
Uwe Schulzweida committed
6
GRIB \cite{GRIB} (GRIdded Binary) is a standard format designed by the
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
World Meteorological Organization (WMO) to support the efficient 
transmission and storage of gridded meteorological data.

A GRIB record consists of a series of header sections, followed by
a bitstream of packed data representing one horizontal grid of data
values. The header sections are intended to fully describe the data
included in the bitstream, specifying information such as the
parameter, units, and precision of the data, the grid system and
level type on which the data is provided, and the date and time
for which the data are valid.

Non-numeric descriptors are enumerated in tables, such that a 1-byte
code in a header section refers to a unique description.
The WMO provides a standard set of enumerated parameter names and
level types, but the standard also allows for the definition
of locally used parameters and geometries. Any activity
that generates and distributes GRIB records must also make
their locally defined GRIB tables available to users.

Uwe Schulzweida's avatar
Uwe Schulzweida committed
26
27
28
{\CDI} does not support the full GRIB standard. The following
data representation and level types are implemented: \\

Uwe Schulzweida's avatar
Uwe Schulzweida committed
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
\begin{tabular}{|r|r|l|l|}
\hline
\rowcolor[gray]{.9}
GRIB1  & GRIB2 & & \\
\rowcolor[gray]{.9}
 grid type &  template & GRIB\_API name & description \\
     0  & 3.0 & regular\_ll & Regular longitude/latitude grid \\
     3  & -- & lambert & Lambert conformal grid \\
     4  & 3.40 & regular\_gg & Regular Gaussian longitude/latitude grid \\
     4  & 3.40 & reduced\_gg & Reduced Gaussian longitude/latitude grid \\
   10  & 3.1 & rotated\_ll & Rotated  longitude/latitude grid \\
   50  & 3.50 & sh & Spherical harmonic coefficients \\
 192  & 3.100 & -- & Icosahedral-hexagonal GME grid \\
  --   & 3.101 & -- & General unstructured grid \\
\hline
Uwe Schulzweida's avatar
Uwe Schulzweida committed
44
45
46
\end{tabular}


Uwe Schulzweida's avatar
Uwe Schulzweida committed
47
48
49
50
51
52
\begin{tabular}{|r|r|l|l|}
\hline
\rowcolor[gray]{.9}
GRIB1  & GRIB2 & & \\
\rowcolor[gray]{.9}
 level type &  level type & GRIB\_API name & description \\
Uwe Schulzweida's avatar
Uwe Schulzweida committed
53
     1  &    1 & surface                        & Surface level \\
Uwe Schulzweida's avatar
Uwe Schulzweida committed
54
55
56
     2  &    2 & cloudBase                    & Cloud base level \\
     3  &    3 & cloudTop                     & Level of cloud tops \\
     4  &    4 & isothermZero               & Level of 0$^{\circ}$ C isotherm \\
Uwe Schulzweida's avatar
Uwe Schulzweida committed
57
58
59
60
61
62
63
64
65
66
67
68
     8  &    8 & nominalTop                 & Norminal top of atmosphere \\
     9  &    9 & seaBottom                   & Sea bottom \\
   10  &  10 & entireAtmosphere        & Entire atmosphere \\
   99  & --  & --                                & Isobaric level in Pa \\
 100  & 100 & isobaricInhPa              & Isobaric level in hPa \\
 102  & 101 & meanSea                     & Mean sea level \\
 103  & 102 & heightAboveSea          & Altitude above mean sea level \\
 105  & 103 & heightAboveGround    & Height level above ground \\
 107  & 104 & sigma                          & Sigma level \\
 109  & 105 & hybrid                         & Hybrid level      \\
 110  & 105 & hybridLayer                 & Layer between two hybrid levels   \\
 111  & 106 & depthBelowLand          & Depth below land surface    \\
Uwe Schulzweida's avatar
Uwe Schulzweida committed
69
 112  & 106 & depthBelowLandLayer & Layer between two depths below land surface   \\   
Uwe Schulzweida's avatar
Uwe Schulzweida committed
70
 113  & 107 & theta                           & Isentropic (theta) level \\
71
   --  & 114 & --                               & Snow level \\
Uwe Schulzweida's avatar
Uwe Schulzweida committed
72
 160  & 160 & depthBelowSea            & Depth below sea level    \\
73
74
75
76
77
78
 162  & 162 & --                               & Lake or River Bottom \\
 163  & 163 & --                               & Bottom Of Sediment Layer  \\
 164  & 164 & --                               & Bottom Of Thermally Active Sediment Layer  \\
 165  & 165 & --                               & Bottom Of Sediment Layer Penetrated By \\ 
         &        &                                    & Thermal Wave  \\
 166  & 166 & --                               & Mixing Layer  \\
Uwe Schulzweida's avatar
Uwe Schulzweida committed
79
\hline
Uwe Schulzweida's avatar
Uwe Schulzweida committed
80
81
\end{tabular}

Uwe Schulzweida's avatar
Uwe Schulzweida committed
82
\subsection{GRIB edition 1}
Uwe Schulzweida's avatar
Uwe Schulzweida committed
83

Uwe Schulzweida's avatar
Uwe Schulzweida committed
84
85
86
87
88
89
90
91
92
93
94
95
96
97
GRIB1 is implemented in {\CDI} as an internal library and enabled per default.
The internal GRIB1 library is called CGRIBEX. This is lightweight
version of the ECMWF GRIBEX library. CGRIBEX is written in ANSI C with a portable Fortran interface. 
The configure option {\tt --disable-cgribex} will disable the encoding/decoding of GRIB1 records with CGRIBEX.

\subsection{GRIB edition 2}

GRIB2 is available in {\CDI} via the ECMWF GRIB\_API \cite{GRIBAPI}.
GRIB\_API is an external library and not part of {\CDI}. To use GRIB2 with
{\CDI} the GRIB\_API library must be installed before the configuration
of the {\CDI} library. Use the configure option {\tt --with-grib\_api} to
enable GRIB2 support. 

The GRIB\_API library is also used to encode/decode GRIB1 records if the support for the CGRIBEX library is disabled.
Uwe Schulzweida's avatar
Uwe Schulzweida committed
98
This feature is not tested regulary and the status is experimental!
99

Uwe Schulzweida's avatar
Uwe Schulzweida committed
100
\section{NetCDF}
Uwe Schulzweida's avatar
Uwe Schulzweida committed
101

Uwe Schulzweida's avatar
Uwe Schulzweida committed
102
NetCDF \cite{NetCDF} (Network Common Data Form) is an interface for array-oriented data
103
104
105
106
access and a library that provides an implementation of the interface.
The netCDF library also defines a machine-independent format for 
representing scientific data. Together, the interface, library, and 
format support the creation, access, and sharing of scientific data.
107

Uwe Schulzweida's avatar
Uwe Schulzweida committed
108
109
110
{\CDI} only supports the classic data model of netCDF and arrays up to 4 dimensions.
These dimensions should only be used by the horizontal and vertical grid and the time.
The netCDF attributes should follow the
111
112
\href{http://ftp.unidata.ucar.edu/software/netcdf/docs/conventions.html}
     {GDT, COARDS or CF Conventions}.
Uwe Schulzweida's avatar
Uwe Schulzweida committed
113

Uwe Schulzweida's avatar
Uwe Schulzweida committed
114
115
NetCDF is an external library and not part of {\CDI}. To use netCDF with
{\CDI} the netCDF library must be installed before the configuration
Uwe Schulzweida's avatar
Uwe Schulzweida committed
116
117
of the {\CDI} library. Use the configure option {\tt --with-netcdf} to
enable netCDF support (see \htmlref{Build}{build}).
118

119
%\subsection{ncdap}
120
121


Uwe Schulzweida's avatar
Uwe Schulzweida committed
122
123
\section{SERVICE}

Uwe Schulzweida's avatar
Uwe Schulzweida committed
124
SERVICE is the binary exchange format of the atmospheric general circulation model ECHAM \cite{ECHAM}.
125
It has a header section with 8 integer values followed by the data section.
Uwe Schulzweida's avatar
Uwe Schulzweida committed
126
127
128
129
The header and the data section have the standard Fortran blocking for binary data records.
A SERVICE record can have an accuracy of 4 or 8 bytes and the byteorder can be little or big endian.
In {\CDI} the accuracy of the header and data section must be the same.
The following Fortran code example can be used to read a SERVICE record with an accuracy of 4 bytes:
130

Uwe Schulzweida's avatar
Uwe Schulzweida committed
131
\begin{lstlisting}[language=Fortran, backgroundcolor=\color{pyellow}, basicstyle=\small, columns=flexible]
132
   INTEGER*4 icode,ilevel,idate,itime,nlon,nlat,idispo1,idispo2
133
   REAL*4 field(mlon,mlat)
134
135
      ...
   READ(unit) icode,ilevel,idate,itime,nlon,nlat,idispo1,idispo2
136
137
138
139
140
141
142
143
144
145
146
147
   READ(unit) ((field(ilon,ilat), ilon=1,nlon), ilat=1,nlat)
\end{lstlisting}

The constants {\tt mlon} and {\tt mlat} must be greater or equal than {\tt nlon} and {\tt nlat}.
The meaning of the variables are:

\vspace*{3mm}
\hspace*{8mm}\begin{minipage}{10cm}
\begin{deflist}{{\tt idispo2 \ \ }}
\item[{\tt icode}]    The code number
\item[{\tt ilevel}]   The level
\item[{\tt idate}]    The date as YYYYMMDD
Uwe Schulzweida's avatar
Uwe Schulzweida committed
148
\item[{\tt itime}]    The time as hhmmss
149
150
\item[{\tt nlon}]     The number of longitudes
\item[{\tt nlat}]     The number of latitides
Uwe Schulzweida's avatar
Uwe Schulzweida committed
151
152
\item[{\tt idispo1}]  For the users disposal (Not used in {\CDI})
\item[{\tt idispo2}]  For the users disposal (Not used in {\CDI})
153
154
\end{deflist}
\end{minipage}
Uwe Schulzweida's avatar
Uwe Schulzweida committed
155
\vspace*{3mm}
156

Uwe Schulzweida's avatar
Uwe Schulzweida committed
157
158
SERVICE is implemented in {\CDI} as an internal library and enabled per default.
The configure option {\tt --disable-service} will disable the support for the SERVICE format.
159

Uwe Schulzweida's avatar
Uwe Schulzweida committed
160
161
\section{EXTRA}

Uwe Schulzweida's avatar
Uwe Schulzweida committed
162
163
164
165
166
167
EXTRA is the standard binary output format of the ocean model MPIOM \cite{MPIOM}.
It has a header section with 4 integer values followed by the data section. 
The header and the data section have the standard Fortran blocking for binary data records.
An EXTRA record can have an accuracy of 4 or 8 bytes and the byteorder can be little or big endian.
In {\CDI} the accuracy of the header and data section must be the same.
The following Fortran code example can be used to read an EXTRA record with an accuracy of 4 bytes:
168

Uwe Schulzweida's avatar
Uwe Schulzweida committed
169
\begin{lstlisting}[language=Fortran, backgroundcolor=\color{pyellow}, basicstyle=\small, columns=flexible]
170
   INTEGER*4 idate,icode,ilevel,nsize
171
   REAL*4 field(msize)
172
173
      ...
   READ(unit) idate,icode,ilevel,nsize
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
   READ(unit) (field(isize),isize=1,nsize)
\end{lstlisting}

The constant {\tt msize} must be greater or equal than {\tt nsize}.
The meaning of the variables are:

\vspace*{3mm}
\hspace*{8mm}\begin{minipage}{10cm}
\begin{deflist}{{\tt idispo2 \ \ }}
\item[{\tt idate}]    The date as YYYYMMDD
\item[{\tt icode}]    The code number
\item[{\tt ilevel}]   The level
\item[{\tt nsize}]    The size of the field
\end{deflist}
\end{minipage}
Uwe Schulzweida's avatar
Uwe Schulzweida committed
189
190
191
192
\vspace*{3mm}

EXTRA is implemented in {\CDI} as an internal library and enabled per default.
The configure option {\tt --disable-extra} will disable the support for the EXTRA format.
193
194


Uwe Schulzweida's avatar
Uwe Schulzweida committed
195
\section{IEG}
196

Uwe Schulzweida's avatar
Uwe Schulzweida committed
197
IEG is the standard binary output format of the regional model REMO \cite{REMO}.
Uwe Schulzweida's avatar
Uwe Schulzweida committed
198
It is simple an unpacked GRIB edition 1 format. The product and grid
Uwe Schulzweida's avatar
Uwe Schulzweida committed
199
description sections are coded with 4 byte integer values and the
200
data section can have 4 or 8 byte IEEE floating point values.
201
The header and the data section have the standard Fortran blocking
Uwe Schulzweida's avatar
Uwe Schulzweida committed
202
203
204
for binary data records. The IEG format has a fixed size of 100 for the
vertical coordinate table. That means it is not possible to store more
than 50 model levels with this format.
Uwe Schulzweida's avatar
Uwe Schulzweida committed
205
{\CDI} supports only data on Gaussian and LonLat grids for the IEG format.
Uwe Schulzweida's avatar
Uwe Schulzweida committed
206
207
208

IEG is implemented in {\CDI} as an internal library and enabled per default.
The configure option {\tt --disable-ieg} will disable the support for the IEG format.