Commit 6b717d9e authored by Uwe Schulzweida's avatar Uwe Schulzweida
Browse files

Docu update

parent 2b5347b2
......@@ -45,6 +45,7 @@ doc/tex/f_vlist.tex -text
doc/tex/f_vlist_var.tex -text
doc/tex/f_zaxis.tex -text
doc/tex/formats.tex -text
doc/tex/grid.tex -text
doc/tex/intro.tex -text
doc/tex/makedoc -text
doc/tex/makehtml -text
......@@ -52,8 +53,10 @@ doc/tex/makepdf_c -text
doc/tex/makepdf_f -text
doc/tex/makeps_c -text
doc/tex/makeps_f -text
doc/tex/taxis.tex -text
doc/tex/test.tex -text
doc/tex/usage.tex -text
doc/tex/zaxis.tex -text
examples/Makefile.am -text
examples/Makefile.in -text
examples/cdi_copy.c -text
......
......@@ -2,103 +2,11 @@
\chapter{\label{appendixa}Examples}
\section{Write a dataset}
\begin{lstlisting}[frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
#include <stdio.h>
#include "cdi.h"
#define NLON 12 /* Number of longitudes */
#define NLAT 6 /* Number of latitudes */
#define NLEV 5 /* Number of levels */
#define NTIME 3 /* Number of time steps */
int main(void)
{
int gridID, zaxisID1, zaxisID2, taxisID;
int vlistID, varID1, varID2, streamID, tsID;
int i, nmiss = 0;
double lons[NLON] = {0, 30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 330};
double lats[NLAT] = {-75, -45, -15, 15, 45, 75};
double levs[NLEV] = {101300, 92500, 85000, 50000, 20000};
double var1[NLON*NLAT];
double var2[NLON*NLAT*NLEV];
/* Create a regular lon/lat grid */
gridID = gridCreate(GRID_LONLAT, NLON*NLAT);
gridDefXsize(gridID, NLON);
gridDefYsize(gridID, NLAT);
gridDefXvals(gridID, lons);
gridDefYvals(gridID, lats);
/* Create a surface level Z-axis */
zaxisID1 = zaxisCreate(ZAXIS_SURFACE, 1);
/* Create a pressure level Z-axis */
zaxisID2 = zaxisCreate(ZAXIS_PRESSURE, NLEV);
zaxisDefLevels(zaxisID2, levs);
/* Create a variable list */
vlistID = vlistCreate();
/* Define the variables */
varID1 = vlistDefVar(vlistID, gridID, zaxisID1, TIME_VARIABLE);
varID2 = vlistDefVar(vlistID, gridID, zaxisID2, TIME_VARIABLE);
/* Define the variable names */
vlistDefVarName(vlistID, varID1, "varname1");
vlistDefVarName(vlistID, varID2, "varname2");
/* Create a Time axis */
taxisID = taxisCreate(TAXIS_ABSOLUTE);
/* Assign the Time axis to the variable list */
vlistDefTaxis(vlistID, taxisID);
/* Create a dataset in netCDF format */
streamID = streamOpenWrite("example.nc", FILETYPE_NC);
if ( streamID < 0 )
{
fprintf(stderr, "%s\n", cdiStringError(streamID));
return(1);
}
/* Assign the variable list to the dataset */
streamDefVlist(streamID, vlistID);
/* Loop over the number of time steps */
for ( tsID = 0; tsID < NTIME; tsID++ )
{
/* Set the verification date to 1985-01-01 + tsID */
taxisDefVdate(taxisID, 19850101+tsID);
/* Set the verification time to 12:00 */
taxisDefVtime(taxisID, 1200);
/* Define the time step */
streamDefTimestep(streamID, tsID);
/* Init var1 and var2 */
for ( i = 0; i < NLON*NLAT; i++ ) var1[i] = 1;
for ( i = 0; i < NLON*NLAT*NLEV; i++ ) var2[i] = 2;
/* Write var1 and var2 */
streamWriteVar(streamID, varID1, var1, nmiss);
streamWriteVar(streamID, varID2, var2, nmiss);
}
/* Close the output stream */
streamClose(streamID);
/* Destroy the objects */
vlistDestroy(vlistID);
taxisDestroy(taxisID);
zaxisDestroy(zaxisID1);
zaxisDestroy(zaxisID2);
gridDestroy(gridID);
\section{Write a dataset}
return 0;
}
\end{lstlisting}
\lstinputlisting[language=C, frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
{../../examples/cdi_write.c}
\subsection{Result}
......@@ -140,139 +48,11 @@ data:
\section{Read a dataset}
\begin{lstlisting}[frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
#include <stdio.h>
#include "cdi.h"
#define NLON 12 /* Number of longitudes */
#define NLAT 6 /* Number of latitudes */
#define NLEV 5 /* Number of levels */
#define NTIME 3 /* Number of time steps */
int main(void)
{
int taxisID, vlistID, varID1, varID2, streamID, tsID;
int nmiss, vdate, vtime;
double var1[NLON*NLAT];
double var2[NLON*NLAT*NLEV];
/* Open the dataset */
streamID = streamOpenRead("example.nc");
if ( streamID < 0 )
{
fprintf(stderr, "%s\n", cdiStringError(streamID));
return(1);
}
/* Get the variable list of the dataset */
vlistID = streamInqVlist(streamID);
/* Set the variable IDs */
varID1 = 0;
varID2 = 1;
/* Get the Time axis form the variable list */
taxisID = vlistInqTaxis(vlistID);
/* Loop over the number of time steps */
for ( tsID = 0; tsID < NTIME; tsID++ )
{
/* Inquire the time step */
streamInqTimestep(streamID, tsID);
/* Get the verification date and time */
vdate = taxisInqVdate(taxisID);
vtime = taxisInqVtime(taxisID);
/* Read var1 and var2*/
streamReadVar(streamID, varID1, var1, &nmiss);
streamReadVar(streamID, varID2, var2, &nmiss);
}
/* Close the input stream */
streamClose(streamID);
return 0;
}
\end{lstlisting}
\lstinputlisting[language=C, frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
{../../examples/cdi_read.c}
\section{Copy a dataset}
\begin{lstlisting}[frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
#include <stdio.h>
#include "cdi.h"
#define NLON 12 /* Number of longitudes */
#define NLAT 6 /* Number of latitudes */
#define NLEV 5 /* Number of levels */
#define NTIME 3 /* Number of time steps */
int main(void)
{
int taxisID, vlistID1, vlistID2, varID1, varID2, streamID1, streamID2, tsID;
int nmiss, vdate, vtime;
double var1[NLON*NLAT];
double var2[NLON*NLAT*NLEV];
/* Open the input dataset */
streamID1 = streamOpenRead("example.nc");
if ( streamID1 < 0 )
{
fprintf(stderr, "%s\n", cdiStringError(streamID1));
return(1);
}
/* Get the variable list of the dataset */
vlistID1 = streamInqVlist(streamID1);
/* Set the variable IDs */
varID1 = 0;
varID2 = 1;
/* Get the Time axis form the variable list */
taxisID = vlistInqTaxis(vlistID1);
/* Open the output dataset (GRIB format) */
streamID2 = streamOpenWrite("example.grb", FILETYPE_GRB);
if ( streamID2 < 0 )
{
fprintf(stderr, "%s\n", cdiStringError(streamID2));
return(1);
}
vlistID2 = vlistDuplicate(vlistID1);
streamDefVlist(streamID2, vlistID2);
/* Loop over the number of time steps */
for ( tsID = 0; tsID < NTIME; tsID++ )
{
/* Inquire the input time step */
streamInqTimestep(streamID1, tsID);
/* Get the verification date and time */
vdate = taxisInqVdate(taxisID);
vtime = taxisInqVtime(taxisID);
/* Define the output time step */
streamDefTimestep(streamID2, tsID);
/* Read var1 and var2 */
streamReadVar(streamID1, varID1, var1, &nmiss);
streamReadVar(streamID1, varID2, var2, &nmiss);
/* Write var1 and var2 */
streamWriteVar(streamID2, varID1, var1, nmiss);
streamWriteVar(streamID2, varID2, var2, nmiss);
}
/* Close the streams */
streamClose(streamID1);
streamClose(streamID2);
return 0;
}
\end{lstlisting}
\lstinputlisting[language=C, frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
{../../examples/cdi_copy.c}
......@@ -17,7 +17,8 @@ The function {\tt gridCreate} creates a horizontal Grid.
\item[{\tt gridtype}]
The type of the grid, one of the set of predefined CDI grid types.
The valid CDI grid types are {\tt GRID\_GENERIC}, {\tt GRID\_GAUSSIAN},
{\tt GRID\_LONLAT}, {\tt GRID\_SPECTRAL}, {\tt GRID\_CURVILINEAR} and {\tt GRID\_CELL}.
{\tt GRID\_LONLAT}, {\tt GRID\_SPECTRAL}, {\tt GRID\_GME},
{\tt GRID\_CURVILINEAR} and {\tt GRID\_CELL}.
\item[{\tt size}]
Number of gridpoints.
......@@ -33,7 +34,8 @@ Number of gridpoints.
Here is an example using {\tt gridCreate} to create a regular lon/lat Grid:
\begin{lstlisting}[backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
\begin{lstlisting}[language=C, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
#include "cdi.h"
...
#define NLON 12
......@@ -122,7 +124,8 @@ Grid ID, from a previous call to {\htmlref{\tt gridCreate}{gridCreate}}
{\tt gridInqType} returns the type of the grid,
one of the set of predefined CDI grid types.
The valid CDI grid types are {\tt GRID\_GENERIC}, {\tt GRID\_GAUSSIAN},
{\tt GRID\_LONLAT}, {\tt GRID\_SPECTRAL}, {\tt GRID\_CURVILINEAR} and {\tt GRID\_CELL}.
{\tt GRID\_LONLAT}, {\tt GRID\_SPECTRAL}, {\tt GRID\_GME}, {\tt GRID\_CURVILINEAR}
and {\tt GRID\_CELL}.
......
......@@ -51,7 +51,8 @@ Library not available
Here is an example using {\tt streamOpenWrite} to create a new netCDF file
named {\tt foo.nc} for writing:
\begin{lstlisting}[backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
\begin{lstlisting}[language=C, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
#include "cdi.h"
...
int streamID;
......@@ -110,7 +111,8 @@ Library not available
Here is an example using {\tt streamOpenRead} to open an existing netCDF
file named {\tt foo.nc} for reading:
\begin{lstlisting}[backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
\begin{lstlisting}[language=C, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
#include "cdi.h"
...
int streamID;
......
......@@ -15,8 +15,8 @@ The function {\tt taxisCreate} creates a Time axis.
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\tt taxistype\ }
\item[{\tt taxistype}]
The type of the time axis, one of the set of predefined CDI time types.
The valid CDI time types are {\tt TAXIS\_ABSOLUTE} and {\tt TAXIS\_RELATIVE}.
The type of the Time axis, one of the set of predefined CDI time axis types.
The valid CDI time axis types are {\tt TAXIS\_ABSOLUTE} and {\tt TAXIS\_RELATIVE}.
\end{deflist}
\end{minipage}
......
......@@ -16,8 +16,8 @@ The function {\tt zaxisCreate} creates a vertical Z-axis.
\begin{deflist}{\tt zaxistype\ }
\item[{\tt zaxistype}]
The type of the Z-axis, one of the set of predefined CDI Z-axis types.
The valid CDI Z-axis types are {\tt ZAXIS\_SURFACE}, {\tt ZAXIS\_HYBRID},
{\tt ZAXIS\_HYBRID\_HALF}, {\tt ZAXIS\_PRESSURE}, {\tt ZAXIS\_HEIGHT},
The valid CDI Z-axis types are {\tt ZAXIS\_GENERIC}, {\tt ZAXIS\_SURFACE},
{\tt ZAXIS\_HYBRID}, {\tt ZAXIS\_PRESSURE}, {\tt ZAXIS\_HEIGHT},
{\tt ZAXIS\_DEPTH\_BELOW\_SEA} and {\tt ZAXIS\_DEPTH\_BELOW\_LAND}.
\item[{\tt size}]
Number of levels
......@@ -34,7 +34,8 @@ Number of levels
Here is an example using {\tt zaxisCreate} to create a pressure level Z-axis:
\begin{lstlisting}[backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
\begin{lstlisting}[language=C, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
#include "cdi.h"
...
#define NLEV 5
......@@ -90,8 +91,8 @@ Z-axis ID, from a previous call to {\htmlref{\tt zaxisCreate}{zaxisCreate}}
{\tt zaxisInqType} returns the type of the Z-axis,
one of the set of predefined CDI Z-axis types.
The valid CDI Z-axis types are {\tt ZAXIS\_SURFACE}, {\tt ZAXIS\_HYBRID},
{\tt ZAXIS\_HYBRID\_HALF}, {\tt ZAXIS\_PRESSURE}, {\tt ZAXIS\_HEIGHT},
The valid CDI Z-axis types are {\tt ZAXIS\_GENERIC}, {\tt ZAXIS\_SURFACE},
{\tt ZAXIS\_HYBRID}, {\tt ZAXIS\_PRESSURE}, {\tt ZAXIS\_HEIGHT},
{\tt ZAXIS\_DEPTH\_BELOW\_SEA} and {\tt ZAXIS\_DEPTH\_BELOW\_LAND}.
......
......@@ -28,6 +28,7 @@
\usepackage{array,colortbl} % color table
\usepackage{listings}
%\lstloadlanguages{[ANSI]C,[77]Fortran}
\usepackage{color}
\definecolor{zebg}{rgb}{1,1,.8} %elfenbeinfarbig
......@@ -121,7 +122,7 @@
\end{picture}
\begin{flushright}
\large\bf{Climate Data Interface \\ Version 0.9.7 \\ May 2006}
\large\bf{Climate Data Interface \\ Version 1.0.0 \\ June 2006}
\end{flushright}
\vfill
......@@ -171,18 +172,24 @@
\input{c_vlist_var}
\chapter{Grids}
\chapter{Grid}
\input{grid}
\input{c_grid}
\chapter{Z-axis}
\input{zaxis}
\input{c_zaxis}
\chapter{T-axis}
\input{taxis}
\input{c_taxis}
......
......@@ -121,7 +121,7 @@
\end{picture}
\begin{flushright}
\large\bf{Climate Data Interface \\ Version 0.9.7 \\ May 2006}
\large\bf{Climate Data Interface \\ Version 1.0.0 \\ June 2006}
\end{flushright}
\vfill
......@@ -171,18 +171,24 @@
\input{f_vlist_var}
\chapter{Grids}
\chapter{Grid}
\input{grid}
\input{f_grid}
\chapter{Z-axis}
\input{zaxis}
\input{f_zaxis}
\chapter{T-axis}
\input{taxis}
\input{f_taxis}
......
......@@ -2,108 +2,11 @@
\chapter{\label{appendixa}Examples}
\section{Write a dataset}
\begin{lstlisting}[frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
PROGRAM CDIWRITE
IMPLICIT NONE
INCLUDE 'cdi.inc'
INTEGER NLON, NLAT, NLEV, NTIME
PARAMETER (NLON = 12) ! Number of longitudes
PARAMETER (NLAT = 6) ! Number of latitudes
PARAMETER (NLEV = 5) ! Number of levels
PARAMETER (NTIME = 3) ! Number of time steps
INTEGER gridID, zaxisID1, zaxisID2, taxisID
INTEGER vlistID, varID1, varID2, streamID, tsID
INTEGER i, nmiss, status
REAL*8 lons(NLON), lats(NLAT), levs(NLEV)
REAL*8 var1(NLON*NLAT), var2(NLON*NLAT*NLEV)
DATA lons /0, 30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 330/
DATA lats /-75, -45, -15, 15, 45, 75/
DATA levs /101300, 92500, 85000, 50000, 20000/
nmiss = 0
! Create a regular lon/lat grid
gridID = gridCreate(GRID_LONLAT, NLON*NLAT)
CALL gridDefXsize(gridID, NLON)
CALL gridDefYsize(gridID, NLAT)
CALL gridDefXvals(gridID, lons)
CALL gridDefYvals(gridID, lats)
! Create a surface level Z-axis
zaxisID1 = zaxisCreate(ZAXIS_SURFACE, 1)
! Create a pressure level Z-axis
zaxisID2 = zaxisCreate(ZAXIS_PRESSURE, NLEV)
CALL zaxisDefLevels(zaxisID2, levs)
! Create a variable list
vlistID = vlistCreate()
! Define the variables
varID1 = vlistDefVar(vlistID, gridID, zaxisID1, TIME_VARIABLE)
varID2 = vlistDefVar(vlistID, gridID, zaxisID2, TIME_VARIABLE)
! Define the variable names
CALL vlistDefVarName(vlistID, varID1, "varname1")
CALL vlistDefVarName(vlistID, varID2, "varname2")
! Create a Time axis
taxisID = taxisCreate(TAXIS_ABSOLUTE)
! Assign the Time axis to the variable list
CALL vlistDefTaxis(vlistID, taxisID)
! Create a dataset in netCDF format
streamID = streamOpenWrite("example.nc", FILETYPE_NC)
IF ( streamID < 0 ) THEN
WRITE(0,*) cdiStringError(streamID)
STOP
END IF
! Assign the variable list to the dataset
CALL streamDefVlist(streamID, vlistID)
! Loop over the number of time steps
DO tsID = 0, NTIME-1
! Set the verification date to 1985-01-01 + tsID
CALL taxisDefVdate(taxisID, 19850101+tsID)
! Set the verification time to 12:00
CALL taxisDefVtime(taxisID, 1200)
! Define the time step
status = streamDefTimestep(streamID, tsID)
! Init var1 and var2
DO i = 1, NLON*NLAT
var1(i) = 1
END DO
DO i = 1, NLON*NLAT*NLEV
var2(i) = 2
END DO
! Write var1 and var2
CALL streamWriteVar(streamID, varID1, var1, nmiss)
CALL streamWriteVar(streamID, varID2, var2, nmiss)
END DO
! Close the output stream
CALL streamClose(streamID)
\section{Write a dataset}
! Destroy the objects
CALL vlistDestroy(vlistID)
CALL taxisDestroy(taxisID)
CALL zaxisDestroy(zaxisID1)
CALL zaxisDestroy(zaxisID2)
CALL gridDestroy(gridID)
END
\end{lstlisting}
\lstinputlisting[language=Fortran, frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
{../../examples/cdi_write_f.f}
\subsection{Result}
......@@ -145,134 +48,11 @@ data:
\section{Read a dataset}
\begin{lstlisting}[frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
PROGRAM CDIREAD
IMPLICIT NONE
INCLUDE 'cdi.inc'
INTEGER NLON, NLAT, NLEV, NTIME
PARAMETER (NLON = 12) ! Number of longitudes
PARAMETER (NLAT = 6) ! Number of latitudes
PARAMETER (NLEV = 5) ! Number of levels
PARAMETER (NTIME = 3) ! Number of time steps
INTEGER gridID, zaxisID1, zaxisID2, taxisID
INTEGER vlistID, varID1, varID2, streamID, tsID
INTEGER nmiss, status, vdate, vtime
REAL*8 var1(NLON*NLAT), var2(NLON*NLAT*NLEV)
! Open the dataset
streamID = streamOpenRead("example.nc")
IF ( streamID < 0 ) THEN
WRITE(0,*) cdiStringError(streamID)
STOP
END IF
! Get the variable list of the dataset
vlistID = streamInqVlist(streamID)
! Set the variable IDs
varID1 = 0
varID2 = 1
! Get the Time axis form the variable list
taxisID = vlistInqTaxis(vlistID)
! Loop over the number of time steps
DO tsID = 0, NTIME-1
! Inquire the time step
status = streamInqTimestep(streamID, tsID)
! Get the verification date and time
vdate = taxisInqVdate(taxisID)
vtime = taxisInqVtime(taxisID)
! Read var1 and var2
CALL streamReadVar(streamID, varID1, var1, nmiss)
CALL streamReadVar(streamID, varID2, var2, nmiss)
END DO
! Close the input stream
CALL streamClose(streamID)
END
\end{lstlisting}
\lstinputlisting[language=Fortran, frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
{../../examples/cdi_read_f.f}
\section{Copy a dataset}
\begin{lstlisting}[frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
PROGRAM CDICOPY
IMPLICIT NONE
INCLUDE 'cdi.inc'
INTEGER NLON, NLAT, NLEV, NTIME
PARAMETER (NLON = 12) ! Number of longitudes
PARAMETER (NLAT = 6) ! Number of latitudes
PARAMETER (NLEV = 5) ! Number of levels
PARAMETER (NTIME = 3) ! Number of time steps
INTEGER gridID, zaxisID1, zaxisID2, taxisID, tsID
INTEGER vlistID1, vlistID2, varID1, varID2, streamID1, streamID2
INTEGER i, nmiss, status, vdate, vtime
REAL*8 var1(NLON*NLAT), var2(NLON*NLAT*NLEV)
! Open the input dataset
streamID1 = streamOpenRead("example.nc")
IF ( streamID1 < 0 ) THEN
WRITE(0,*) cdiStringError(streamID1)
STOP
END IF
! Get the variable list of the dataset
vlistID1 = streamInqVlist(streamID1)
! Set the variable IDs
varID1 = 0
varID2 = 1
! Get the Time axis form the variable list
taxisID = vlistInqTaxis(vlistID1)
! Open the output dataset (GRIB format)
streamID2 = streamOpenWrite("example.grb", FILETYPE_GRB)
IF ( streamID2 < 0 ) THEN