source: CPL/oasis3/trunk/src/mod/oasis3/doc/UG5_Auxiliary_files.tex @ 1677

Last change on this file since 1677 was 1677, checked in by aclsce, 12 years ago

Imported oasis3 (tag ipslcm5a) from cvs server to svn server (igcmg project).

File size: 15.8 KB
2\chapter{OASIS3 auxiliary data files}
5OASIS3 needs auxiliary data files describing coupling and I/O field
6names and units, defining the grids of the models being coupled,
7containing the field coupling restart values or input data values, as
8well as a number of other auxiliary data files used in specific
9transformations. For coupled models distributed in the PRISM Standard
10Running Environment (SCE), all those files are either automatically
11provided or generated.
13\section{Field names and units}
16The text file \texttt{cf\_name\_table.txt}, that can be found in
17directory \texttt{prism/util/running\break/adjunct\_files/oasis3}
18directory, contains a list of CF standard names and associated units
19identified with an index. The appropriate index has to be given by the
20user for each coupling or I/O field as the third entry on the field
21first line (see \ref{subsec_namcouplesecond}). This information will
22be used by OASIS3 for its log messages to {\it cplout} file and by the
23PSMILe to produce CF compliant NetCDF files.
25\section{Grid data files}
28The grids of the models being coupled can be given by the user or
29directly by the model through PSMILe specific calls (see section
30\ref{subsubsec_griddef}) in grid data files. These files can be all
31binary or all NetCDF. In \break {\tt
33Net\-CDF examples can be found.
36arrays containing the grid information are dimensioned {\tt (nx, ny)},
37where {\tt nx} and {\tt ny} are the grid first and second dimension,
38except for Unstructured (U) and Reduced (D) grid, for which the
39arrays are dimensioned {\tt (nbr\_pts,1)}, where {\tt nbr\_pts} is the
40total number of grid points.
44\item {\em grids} or {\em}: contains the component model grid
45  longitudes, latitudes, and local angles (if any)  in single or double precision {\tt
46  REAL} arrays (depending on OASIS3 compilation options). The array names
47  must be composed of a prefix (4 characters), given by the user in
48  the {\it namcouple} on the second line of each field (see section
49  \ref{subsec_namcouplesecond}), and of a suffix (4 characters); this
50  suffix is ``.lon'' or ``.lat'' for respectively the grid point
51  longitudes or latitudes (see {\tt /prism/src/mod/oasis3/src\break/mod\_label.F90}.)
53 If the {\tt SCRIPR/CONSERV} interpolation is used for a grid, the
54 grid data file may contain longitudes and latitudes for model mesh
55 corners as arrays dimensioned {\tt (nx, ny, 4)} or {\tt
56 (nbr\_pts,1, 4)} where {\tt 4} is the number of corners; in this
57 case, it must necessarily be a NetCDF file ({\em
58}). For Logically Rectangular LR grids, the grid
59 corners will be automatically calculated approximately if they are
60 not given in {\em}. The names of the arrays must be
61 composed of the grid prefix and the suffix ``.clo'' or ``.cla'' for
62 respectively the grid corner longitudes or latitudes.
64 If vector fields are defined on a grid which has a local coordinate system not oriented in the usual zonal and meridional directions, the local angle of the grid coordinate system must be given in {\it} file in an array which name must be composed of the grid prefix and the suffix ``.ang''. The angle is defined as the angle between the first component and the zonal direction (which is also the angle between the second component and the meridional direction). In the grid file in {\tt
65/prism/data/toyclim/input\_toyclim\_standard\_standard\_prism\_2-2.tar.gz}, the angles of the {\tt torc} grid are given in array {\tt torc.ang}. If one of the {\tt SCRIPR} interpolations is requested for a vector field, OASIS3 automatically performs the rotation from the local coordinate system to the geographic spherical coordinate system for a source grid, or vice-versa for a target grid.
67 File {\em grids} or {\em} must be present with at least the grid
68 point longitudes and latitudes for all component model.
70\item {\em masks} or {\em}: contains the masks for all
71component model grids in {\tt INTEGER} arrays (0 -not masked- or 1
72-masked- for each grid point). The array names must be composed of the
73grid prefix and the suffix ``.msk''. This file, {\em masks} or {\em
74}, is mandatory.
76\item {\em areas} or {\em}: this file contains mesh surfaces
77for the component model grids in single or double precision {\tt REAL}
78arrays (depending on OASIS3 compilation options). The array names must be
79composed of the grid prefix and the suffix ``.srf''.  The surfaces may
80be given in any units but they must be all the same (in {\tt
81INTERP/GAUSSIAN}, it is assumed that the units are $m^2$ but they are
82used for statistics calculations only.) This file {\em areas} or {\em} is mandatory for {\tt CHECKIN}, {\tt CHECKOUT} or {\tt
84CONSERV}, and used for statistic calculations in {\tt
85INTERP/GAUSSIAN}; it is not required otherwise.
87\item {\em maskr} or {\em}: this file
88  contains Reduced (D) grid mask in {\tt INTEGER} arrays dimensioned
89  {\tt array(nbr\_pts)} where {\tt nbr\_pts} is the total number of the
90  Reduced grid points (0 -not masked- or 1 -masked- for each grid
91  point). This file is required only for grids to which the {\tt
92  REDGLO} or {\tt GLORED} transformation is applied. As mentionned above,
93  these transformations should not be used anymore as interpolations
94  are now available for Reduced grids directly. If used, the mask
95  array name must be ``MSKRDxxx'' where ``xxx'' is half the number of
96  latitude circles of the reduced grid (032 for a T42 for example).
100If the binary format is used, {\em grids}, {\em masks}, {\em areas},
101and {\em maskr} must have the following structure. The array
102name is first written to
103the file to locate a data set corresponding to a given grid.  The
104data set is then written sequentially after its name.  Let us call
105``brick'' the name and its associated data set.  The order in which
106the bricks are written doesn't matter.  All the bricks are written in
107the grid data file in the following way:
110        ...
111        WRITE(LU) array_name
112        WRITE(LU) auxildata
113        ...\end{verbatim} where
115\item {\tt LU} is the associated unit,
116\item {\tt array\_name} is the name of the array (CHARACTER*8),
117\item {\tt auxildata} is the REAL or INTEGER array dimensioned {\tt
118  (nx, ny)} or {\tt (nbr\_pts,1)} containing the grid data.
121%subsection{Grid data files}
123\section{Coupling restart files}
126At the beginning of a coupled run, some coupling fields may have to be
127initially read from their coupling restart file (see section \ref
128{subsubsec_Algoritms}). If needed, these files are also
129automatically  updated by the
130last {\tt prism\_put\_proto} call of the run (see section \ref{prismput}) . To
131force the writing of the field in its coupling restart file, one can
132use the routine {\tt prism\_put\_restart\_proto} (see section \ref{subsec:auxiliary}).
133The name of the coupling restart file is given
134by the 6th character string on the first configuring line for each
135field in the {\em namcouple} (see section
136\ref{subsec_namcouplesecond}). Coupling fields coming from different
137models cannot be in the same
138coupling restart files, but for each model, there can be an arbitrary
139number of fields written in one coupling restart file. Note that in
140the NONE techniques, output files with the same format are also
141created for writing the resulting field after transformation.
143In the coupling restart files, the fields must be single or double
144precision REAL arrays (depending on PSMILe and OASIS3 compilation
145options) and, as the grid data files, must be dimensioned {\tt (nx,
146ny)}, where {\tt nx} and {\tt ny} are the grid first and second
147dimension, except for fields given on Unstructured ('U') and Reduced
148('D’) grid, for which the arrays are dimensioned {\tt (nbr\_pts,1)},
149where {\tt nbr\_pts} is the total number of grid points.  The shape
150and orientation of each restart field (and of the corresponding
151coupling fields exchanged during the simulation) must be coherent with
152the shape of its grid data arrays. The exceptions are for A, B, G,
153L, Z, or Y grids for which the field may be oriented from North to
154South and/or from East to West, in which case, {\tt INVERT}
155transformation will have to be used - see section
158Both binary and NetCDF formats are supported; for NetCDF file the
159suffix .nc is not mandatory. If the coupling restart file
160for the first field is in NetCDF format, OASIS3 will assume that all
161coupling restart files (and output files for {\tt NONE}
162communication techniques) are NetCDF\footnote{Note that even if the grid
163auxiliary data files are in NetCDF format, the restart coupling files
164may be in binary format, or vice-versa.}.
166In the NetCDF restart files, the field arrays must have the source symbolic
167name indicated in the {\em namcouple}
168(see section \ref{subsec_namcouplesecond}).
170In binary restart file, each field is written in the following way:
172        ...
173        WRITE(LU) array_name
174        WRITE(LU) restartdata
175        ...\end{verbatim} where
177\item {\tt LU} is the associated unit,
178\item {\tt array\_name} is the source symbolic name of the field (CHARACTER*8),
179\item {\tt restartdata} is the restart field REAL array dimensioned
180  {\tt (nx, ny)} or {\tt (nbr\_pts,1)}\footnote{If REDGLO is the first
181  transformation applied on a Reduced grid field, the Reduced field
182  must be given is an array {\tt restartdata(nx*ny)} where {\tt nx}
183  and {\tt ny} are the global Gaussian grid dimensions and the Reduced
184  field is completed by trailing zeros.}
187%subsection{Restart data files}
189\section{Input data files}
192Fields with status {\tt INPUT} in the {\em namcouple} will, at
193  runtime, simply be read in from a NetCDF input file by the target
194  model PSMILe below the {\tt prism\_get\_proto} call, at appropriate
195  times corresponding to the input period indicated by the user in the
196  {\it namcouple}.
200The name of the file must be the one given on the field first
201configuring line in the {\em namcouple} (see section
202\ref{subsubsec_secondINPUT}). There must be one input file per {\tt
203INPUT} field, containing a time sequence of the field in a single or
204double precision REAL array (depending on PSMILe compilation options),
205named with the field symbolic name in the {\em namcouple} and
206dimensioned {\tt (nx,ny,time)} or {\tt (nbr\_pts,1,time)}.  The time
207variable as to be an array {\tt time(time)} expressed in
208``seconds since beginning of run''. The ``time'' dimension has to
209be the unlimited dimension.
210For a practical example, see the file in
211{\tt /prism/data/toyclim/input\_toyclim\_standard\_standard\_prism\_2-2.tar.gz}.
213%subsection{Input data files}
215\section{Transformation auxiliary data files}
218Many transformation need auxiliary data files, such as the
219grid-mapping files used for an interpolation. Some of them are created
220automatically by OASIS3, others have to be generated by the user before
221starting the coupled run.
223\subsection{Auxiliary data files for {\tt EXTRAP/NINENN},
225{\tt MOZAIC}, and {\tt SUBGRID}}
227The auxiliary data files containing the weights and addresses used
228in these transformations have a similar structure; their names are
229given in Table \ref{tab.fileana}.
235File name & Description \\
238{\em  nweights }& weights, addresses and iteration number for
239EXTRAP/NINENN interpolation  \\
240any name        & weights and addresses for EXTRAP/WEIGHT extrapolation \\
241{\em  mweights }& weights and addresses for INTERP/SURFMESH interpolation  \\
242{\em  gweights }& weights and addresses for INTERP/GAUSSIAN interpolation  \\
243any name        & weights and addresses for MOZAIC interpolation \\
245any name        & weights and addresses for SUBGRID interpolation \\
249\caption{Analysis auxiliary data files}
253The files {\em nweights}, {\em mweights} and {\em gweights} can be
254created by OASIS3 if their corresponding {\tt \$NIO} = 1 (see {\tt
256\ref{subsec_preproc} and \ref{subsec_interp}).
258The name of the (sub)grid-mapping files for {\tt MOZAIC,
259EXTRAP/WEIGHT} and {\tt SUBGRID} analyses can be chosen by the user
260and have to be indicated in the {\em namcouple} (see respectively
261sections \ref{subsec_preproc} and \ref{subsec_interp} and
262\ref{subsec_cooking}). These files have to be generated by the user before
263starting the coupled run.
267The structure of these files is as follows:
270      ...
271      CHARACTER*8 cladress,clweight
272      INTEGER iadress(jpnb,jpo)
273      REAL weight(jpnb,jpo)
274      OPEN(unit=90, file='at31topa', form='unformatted')
275      WRITE(clweight,'(''WEIGHTS'',I1)') knumb
276      WRITE(cladress,'(''ADRESSE'',I1)') knumb
277      WRITE (90) cladress
278      WRITE (90) iadress
279      WRITE (90) clweight
280      WRITE (90) weight
285\item {\tt jpnb} is the maximum number of neighbors used in the transformation
286({\tt \$NVOISIN} in the {\em namcouple})
287\item {\tt jpo} is the total dimension of the target grid
288\item {\tt at31topa} is the name of the grid-mapping data file ({\tt \$CFILE}
289in  {\em namcouple})
290\item {\tt knumb} is the identificator of the data set ({\tt \$NID} in
291{\em namcouple})
292\item {\tt cladress} is the locator of the address dataset
293\item {\tt clweight} is the locator of the weight dataset
294\item {\tt iadress (i,j)} is the address on the source grid of the $i^e$
295neighbor used for the mapping of the $j^e$ target grid point. The
296address is the index of a grid point within the total number of grid
298\item {\tt weight(i,j)} is the weight affected to the $i^e$
299neighbor used for the transformation of the $j^e$ target grid point
302For file {\em nweights}, there is an additional brick composed of a
303{\tt CHARACTER*8} variable (formed by the characters {\tt INCREME} and
304by the data set identificator) and of an {\tt INTEGER array(N)} which
305is the iteration number within {\tt EXTRAP/NINENN} at which the
306extrapolation of the $n^e$ grid point is effectively performed.
308\subsection{Auxiliary data files for {\tt FILLING}}
310For the FILLING analysis, the global data set used can be
311either interannual monthly, climatological monthly or yearly (see
312\ref{subsec_interp}). The name of the global data file
313can be chosen by the user and has to be indicated in the {\em namcouple}
314have to be given to OASIS through the input file {\em namcouple}. In case of monthly data, the file
315must be written in the following way:
317      ...
318      REAL field_january_year_01(jpi, jpj)
319      ...
320      WRITE(NLU_fil) field_january_year_01
321      WRITE(NLU_fil) field_february_year_01
322      WRITE(NLU_fil) field_march_year_01
323      etc...
324      WRITE(NLU_fil) field_december_year_01
326C if climatology, one stops here
328      WRITE(NLU_fil) field_january_year_02
329      etc...
334\item  {\tt field\_...} is the global dataset
335\item {\tt jpi} and {\tt jpj} are the dimensions of the grid on which FILLING
336is performed
337\item {\tt NLU\_fil} is the logical unit associated to the global data file and is
338defined in the input file {\em namcouple}
340Note that the first month needs not to be a january.
341This is the only file within OASIS in which the fields are not read
342using a locator.
344\subsection{Auxiliary data files for {\tt SCRIPR}}
346The NetCDF files containing the weights and addresses for the {\tt
347  SCRIPR} remappings (see section \ref{subsec_interp})  are
348  automatically generated at runtime by OASIS3. Their structure is
349  described in detail in section 2.2.3 of the SCRIP documentation available
350  in {\tt prism/src/mod/oasis3/doc/SCRIPusers.pdf}.
Note: See TracBrowser for help on using the repository browser.