[4775] | 1 | \newpage |
---|
| 2 | \chapter{OASIS3-MCT auxiliary data files} |
---|
| 3 | \label{sec_auxiliary} |
---|
| 4 | |
---|
| 5 | In some cases, OASIS3-MCT uses auxiliary data files, e.g. defining the |
---|
| 6 | grids of the models being coupled, containing the field coupling |
---|
| 7 | restart values or input data values, or the remapping weights and |
---|
| 8 | addresses. |
---|
| 9 | |
---|
| 10 | \section{Grid data files} |
---|
| 11 | \label{subsec_griddata} |
---|
| 12 | |
---|
| 13 | With OASIS3-MCT, the grid data files {\em grids.nc, masks.nc} and {\em |
---|
| 14 | areas.nc} are required only for certain operations, i.e. {\em |
---|
| 15 | grids.nc}, and {\em masks.nc} for {\tt SCRIPR} (see section |
---|
| 16 | \ref{subsec_interp}) and {\em masks.nc} and {\em areas.nc} for {\tt |
---|
| 17 | CONSERV} (see section \ref{subsec_cooking}). These NetCDF files can |
---|
| 18 | be created by the user before the run or can be written directly at |
---|
| 19 | run time by the master process of each component model using the grid |
---|
| 20 | data definition routines (see section \ref{subsubsec_griddef}). These |
---|
| 21 | routines can be used by the component models to add grid fields to the |
---|
| 22 | grid files but grid fields are {\bf never} overwritten in the grid |
---|
| 23 | files. |
---|
| 24 | |
---|
| 25 | The arrays containing the grid information are dimensioned {\tt (nx, |
---|
| 26 | ny)}, where {\tt nx} and {\tt ny} are the grid first and second |
---|
| 27 | dimension. Unstructured grids or other grids expressed with 1D |
---|
| 28 | vectors are supported by setting {\tt nx} to the total number of grid |
---|
| 29 | points and {\tt ny} to 1. |
---|
| 30 | |
---|
| 31 | \begin{enumerate} |
---|
| 32 | |
---|
| 33 | \item {\em grids.nc}: contains the model grid longitudes and latitudes |
---|
| 34 | in double precision {\tt REAL} arrays. The array names must be |
---|
| 35 | composed of a prefix (4 characters), given by the user in the {\it |
---|
| 36 | namcouple} on the second line of each field (see section |
---|
| 37 | \ref{subsec_namcouplesecond}), and of a suffix (4 characters); this |
---|
| 38 | suffix is ``.lon'' or ``.lat'' for respectively the grid point |
---|
| 39 | longitudes or latitudes. |
---|
| 40 | |
---|
| 41 | If the {\tt SCRIPR/CONSERV} remapping is used, longitudes and |
---|
| 42 | latitudes for the source and target grid {\bf corners} must also be |
---|
| 43 | available in the {\em grids.nc} file as double precision {\tt |
---|
| 44 | REAL} arrays dimensioned {\tt (nx,ny,4)} or {\tt (nbr\_pts,1,4)} |
---|
| 45 | where {\tt 4} is the number of corners (in the counterclockwize |
---|
| 46 | sense). The names of the arrays must be composed of the grid prefix |
---|
| 47 | and the suffix ``.clo'' or ``.cla'' for respectively the grid corner |
---|
| 48 | longitudes or latitudes. As for the other grid information, the |
---|
| 49 | corners can be provided in {\em grids.nc} before the run by the user |
---|
| 50 | or directly by the model through specific calls (see section |
---|
| 51 | \ref{subsubsec_griddef}). |
---|
| 52 | |
---|
| 53 | % For source grids of Logically Rectangular LR type only, the grid |
---|
| 54 | % corners will however be automatically calculated and stored by |
---|
| 55 | % OASIS if they are not initially available in {\em |
---|
| 56 | % grids.nc}\footnote{Tip: to automatically calculate the corners |
---|
| 57 | % of a Logically Rectangular LR target grid, use the corresponding |
---|
| 58 | % reverse remapping in which the current target grid becomes the |
---|
| 59 | % source grid.}. |
---|
| 60 | |
---|
| 61 | Longitudes must be given in degrees East in the interval -360.0 to |
---|
| 62 | 720.0. Latitudes must be given in degrees North in the interval |
---|
| 63 | -90.0 to 90.0. Note that if some grid points overlap, it is |
---|
| 64 | recommended to define those points with the same number (e.g. 360.0 |
---|
| 65 | for both, not 450.0 for one and 90.0 for the other) to ensure |
---|
| 66 | automatic detection of overlap by OASIS3-MCT. |
---|
| 67 | |
---|
| 68 | The corners of a cell cannot be defined modulo 360 degrees. For |
---|
| 69 | example, a cell located over Greenwich will have to be defined with |
---|
| 70 | corners at -1.0 deg and 1.0 deg but not with corners at 359.0 deg |
---|
| 71 | and 1.0 deg. |
---|
| 72 | |
---|
| 73 | Cells larger than 180.0 degrees in longitude are not supported. |
---|
| 74 | |
---|
| 75 | \item {\em masks.nc}: contains the masks for all component model grids |
---|
| 76 | in {\tt INTEGER} arrays. {\bf Be careful to note the historical |
---|
| 77 | OASIS convention: 0 -not masked i.e. active- or 1 -masked |
---|
| 78 | i.e. not active- for each grid point}. The array names must be |
---|
| 79 | composed of the grid prefix and the suffix ``.msk''. This file, {\em |
---|
| 80 | masks} or {\em masks.nc}, is mandatory. |
---|
| 81 | |
---|
| 82 | \item {\em areas.nc}: this file contains mesh surfaces for the |
---|
| 83 | component model grids in double precision {\tt REAL} arrays. The |
---|
| 84 | array names must be composed of the grid prefix and the suffix |
---|
| 85 | ``.srf''. The surfaces may be given in any units but they must be |
---|
| 86 | all the same. This file {\em areas.nc} is mandatory for {\tt |
---|
| 87 | CONSERV/GLOBAL},{\tt /GLBPOS}, {\tt /BASBAL}, and {\tt /BASPOS}; |
---|
| 88 | it is not required otherwise. |
---|
| 89 | |
---|
| 90 | \end{enumerate} |
---|
| 91 | |
---|
| 92 | \section{Coupling restart files} |
---|
| 93 | \label{subsec_restartdata} |
---|
| 94 | |
---|
| 95 | At the beginning of a coupled run, some coupling fields may have to be |
---|
| 96 | initially read from their coupling restart file on their source grid |
---|
| 97 | (see the LAG concept in section \ref{subsubsec_Algoritms}). When |
---|
| 98 | needed, these files are also automatically updated by the last active |
---|
| 99 | {\tt oasis\_put} or {\tt prism\_put\_proto} call of the run (see |
---|
| 100 | section \ref{prismput}) . |
---|
| 101 | % To force the writing of the field in its coupling restart file, one |
---|
| 102 | % can use the routine {\tt prism\_put\_restart\_proto} (see section |
---|
| 103 | % \ref{subsec:auxiliary}). |
---|
| 104 | {\bf Warning}: the date is not written or read to/from the restart |
---|
| 105 | file; therefore, the user has to make sure that the appropriate |
---|
| 106 | coupling restart file is present in the working directory. The |
---|
| 107 | coupling restart files must follow the NetCDF format. |
---|
| 108 | |
---|
| 109 | % Note that all restart files have to be present in the working |
---|
| 110 | % directory at the %beginning of the |
---|
| 111 | % run even if one model is delayed with respect to the others. |
---|
| 112 | |
---|
| 113 | The name of the coupling restart file is given by the 6th character |
---|
| 114 | string on the first configuring line for each field in the {\it |
---|
| 115 | namcouple} (see section \ref{subsec_namcouplesecond}). Coupling |
---|
| 116 | fields coming from different models cannot be in the same coupling |
---|
| 117 | restart files, but for each model, there can be an arbitrary number of |
---|
| 118 | fields written in one coupling restart file. The only exception is when a coupling field sent by a source component model is associated with more than one target field and model; in that case, if coupling restart files are required, it is mandatory to specify different files for the different fields. |
---|
| 119 | |
---|
| 120 | In the coupling restart files, the fields must be provided on the |
---|
| 121 | source grid in single or double precision REAL arrays and, as the grid |
---|
| 122 | data files, must be dimensioned {\tt (nx, ny)}, where {\tt nx} and |
---|
| 123 | {\tt ny} are the grid first and second dimension (see section |
---|
| 124 | \ref{subsec_griddata} above). The shape and orientation of each |
---|
| 125 | restart field (and of the corresponding coupling fields exchanged |
---|
| 126 | during the simulation) must be coherent with the shape of its grid |
---|
| 127 | data arrays. |
---|
| 128 | |
---|
| 129 | The coupling restart files are also used automatically by OASIS3-MCT |
---|
| 130 | to allow partial LOCTRANS time transformation to be saved at the end |
---|
| 131 | of a run for exact restart at the start of the next run. For that |
---|
| 132 | reason, coupling restart filenames are now required for all {\it |
---|
| 133 | namcouple} transformations that use LOCTRANS (with non INSTANT |
---|
| 134 | values). |
---|
| 135 | |
---|
| 136 | \section{Input data files} |
---|
| 137 | \label{subsec_inputdata} |
---|
| 138 | |
---|
| 139 | Fields with status {\tt INPUT} in the {\it namcouple} will, at |
---|
| 140 | runtime, simply be read in from a NetCDF input file by the target |
---|
| 141 | model below the {\tt oasis\_get} call, at appropriate times |
---|
| 142 | corresponding to the input period indicated by the user in the {\it |
---|
| 143 | namcouple}. |
---|
| 144 | |
---|
| 145 | The name of the file must be the one given on the field first |
---|
| 146 | configuring line in the {\it namcouple} (see section |
---|
| 147 | \ref{subsubsec_secondINPUT}). There must be one input file per {\tt |
---|
| 148 | INPUT} field, containing a time sequence of the field in a single or |
---|
| 149 | double precision REAL array named with the field symbolic name in the |
---|
| 150 | {\it namcouple} and dimensioned {\tt (nx,ny,time)}. The time variable |
---|
| 151 | has to be an array {\tt time(time)} expressed in ``seconds since |
---|
| 152 | beginning of run''. The ``time'' dimension has to be the unlimited |
---|
| 153 | dimension. |
---|
| 154 | % For a practical example, see the file SOALBEDO.nc in {\tt |
---|
| 155 | % oasis3/examples/toyoasis3/data}. |
---|
| 156 | |
---|
| 157 | % subsection{Input data files} |
---|
| 158 | |
---|
| 159 | \section{Transformation auxiliary data files} |
---|
| 160 | \label{subsec_mapdata} |
---|
| 161 | |
---|
| 162 | The mapping files to be used for the MAPPING option must be consistent |
---|
| 163 | with the files generated by the SCRIP library to be used for the {\tt |
---|
| 164 | SCRIPR} transformations (see also section \ref{subsec_interp}). The |
---|
| 165 | files are NetCDF containing the following fields: |
---|
| 166 | \begin{verbatim} |
---|
| 167 | dimensions: |
---|
| 168 | src_grid_size = xxx ; |
---|
| 169 | dst_grid_size = xxx ; |
---|
| 170 | num_links = xxx ; |
---|
| 171 | num_wgts = xxx ; |
---|
| 172 | variables: |
---|
| 173 | int src_address(num_links) |
---|
| 174 | int dst_address(num_links) |
---|
| 175 | double remap_matrix(num_links, num_wgts) |
---|
| 176 | \end{verbatim} |
---|
| 177 | where |
---|
| 178 | \begin{itemize} |
---|
| 179 | \item {\tt src\_grid\_size} is a scalar integer indicating the total number |
---|
| 180 | of points in the source grid. This is typically a large number. |
---|
| 181 | This field is a netCDF dimension. |
---|
| 182 | \item {\tt dst\_grid\_size} is a scalar integer indicating the total number |
---|
| 183 | of points in the target grid. This is typically a large number. |
---|
| 184 | This field is a netCDF dimension. |
---|
| 185 | \item {\tt num\_links} is a scalar integer indicating the total number |
---|
| 186 | of associated grid point pairs in the file. This is typically a |
---|
| 187 | large number. This field is a netCDF dimension. |
---|
| 188 | \item {\tt num\_wgts} is a scalar integer indicating the number of |
---|
| 189 | weights per associated grid point pair (up to 5 are supported, see |
---|
| 190 | section \ref{prismput}). This field is a netCDF dimension. |
---|
| 191 | \item {\tt src\_address} is a one dimensional array of size {\tt |
---|
| 192 | num\_links}. It contains the integer source address associated |
---|
| 193 | with each weight. This field is a netCDF variable. |
---|
| 194 | \item {\tt dst\_address} is a one dimensional array of size {\tt |
---|
| 195 | num\_links}. It contains the integer destination address |
---|
| 196 | associated with each weight. This field is a netCDF variable. |
---|
| 197 | \item {\tt remap\_matrix} is a two dimensional array of size {\tt |
---|
| 198 | (num\_links, num\_wgts)}. It contains the real weight value(s) |
---|
| 199 | associated with the source and destination address. This field is a |
---|
| 200 | netCDF variable. |
---|
| 201 | \end{itemize} |
---|