\newpage
\chapter{OASIS3-MCT auxiliary data files}
\label{sec_auxiliary}

OASIS3-MCT uses auxiliary data files, e.g. defining the
grids of the models being coupled, containing the field coupling
restart values or input data values, or the remapping weights and
addresses.

\section{Grid data files}
\label{subsec_griddata}

With OASIS3-MCT, the grid data files {\em grids.nc, masks.nc} and {\em
  areas.nc} are required only for certain operations, i.e.  {\em
  grids.nc}, and {\em masks.nc} for {\tt SCRIPR} (see section
\ref{subsec_interp}), {\em areas.nc} for conservative remapping
for which the normalisation by the true area of the cells is 
applied, i.e. DESTARTR, DESTNNTR, FRACARTR, or FRACNNTR (see section
\ref{subsec_interp})
and {\em masks.nc} and {\em areas.nc} for {\tt
  CONSERV} (see section \ref{subsec_cooking}). These NetCDF files can
be created by the user before the run or can be written directly at
run time by the processes of each component model using the grid
data definition routines (see section \ref{subsubsec_griddef}).  These
routines can be used by the component models to add grid fields to the
grid files but grid fields are {\bf never} overwritten in the grid
files.

The arrays containing the grid information are dimensioned {\tt (nx,
  ny)}, where {\tt nx} and {\tt ny} are the grid first and second
dimension.  Unstructured grids or other grids expressed with 1D
vectors are supported by setting {\tt nx} to the total number of grid
points and {\tt ny} to 1.

\begin{enumerate}

\item {\em grids.nc}: contains the model grid longitudes and latitudes
  in double precision {\tt REAL} arrays. The array names must be
  composed of a prefix (4 characters), given by the user in the {\it
    namcouple} on the second line of each field (see section
  \ref{subsec_namcouplesecond}), and of a suffix,``.lon'' or ``.lat'', for respectively the grid point
  longitudes or latitudes.

  If the {\tt SCRIPR/CONSERV} remapping is specified, longitudes and
  latitudes for the source and target grid {\bf corners} must also be
  available in the {\em grids.nc} file as double precision {\tt
    REAL} arrays dimensioned {\tt (nx,ny,nc)} or {\tt (nbr\_pts,1,nc)}
  where {\tt nc} is is the maximum number of corners 
  (in the counterclockwize sense, starting by any corner) over all cells; 
  nc can be any number. For cells that do not have the maximum 
  number of distinct corners, we recommend to repeat the last corner 
  as many times as needed to describe nc corners.
  The names of the arrays must be composed of the grid prefix
  and the suffix ``.clo'' or ``.cla'' for respectively the grid corner
  longitudes or latitudes.  As for the other grid information, the
  corners can be provided in {\em grids.nc} before the run by the user
  or directly by the component code through specific calls (see section
  \ref{subsubsec_griddef}).

  % For source grids of Logically Rectangular LR type only, the grid
  % corners will however be automatically calculated and stored by
  % OASIS if they are not initially available in {\em
  %   grids.nc}\footnote{Tip: to automatically calculate the corners
  %   of a Logically Rectangular LR target grid, use the corresponding
  %   reverse remapping in which the current target grid becomes the
  %   source grid.}.
 
  Longitudes must be given in degrees East in the interval -360.0 to
  720.0. Latitudes must be given in degrees North in the interval
  -90.0 to 90.0. Note that if some grid points overlap, it is
  recommended to define those points with the same number (e.g. 360.0
  for both, not 450.0 for one and 90.0 for the other) to ensure
  automatic detection of overlap by OASIS3-MCT.
 
  The corners of a cell cannot be defined modulo 360 degrees. For
  example, a cell located over Greenwich will have to be defined with
  corners at -1.0 deg and 1.0 deg but not with corners at 359.0 deg
  and 1.0 deg.
 
  Cells larger than 180.0 degrees in longitude are not supported.
  
  Longitudes and latitudes of grid points or corners can be defined through the {\tt oasis\_write\_grid} or {\tt oasis\_write\_corner} API routines respectively,  see section \ref{subsubsec_griddef}.
 
\item {\em masks.nc}: contains the masks for all component model grids
  in {\tt INTEGER} arrays. {\bf Be careful to use the historical
    OASIS convention: 0 = not masked i.e. active, 1 = masked
    i.e. not active, for each grid point}. The array names must be
  composed of the grid prefix and the suffix ``.msk''. Mask can be defined through the {\tt oasis\_write\_mask} API routine, see section \ref{subsubsec_griddef}.
  
 File {\em masks.nc} may also contain the grid cell fractions that defines the active (i.e. not masked) part of the cells.  Fractions should be consistent with the mask field. The fraction field is only used in the global {\tt CONSERV} operations. If both a mask and fractions are defined for a grid, they must be consistent; OASIS3-MCT will abort if they are not coherent or if both are missing.  Note that by OASIS conventions for the mask, a gridcell with mask=0 (active) should have a fractions greater than 0 and a gridcell with mask=1 (inactive) should have a fractions equal to 0.   The fraction array name must be composed of the grid prefix and the suffix ``.frc''. Fractions can be defined through the {\tt oasis\_write\_frac} API routine, see section \ref{subsubsec_griddef}.
  
 File {\em masks.nc} is mandatory.

\item {\em areas.nc}: this file contains mesh surfaces for the
  component model grids in double precision {\tt REAL} arrays. The
  array names must be composed of the grid prefix and the suffix
  ``.srf''.  The surfaces may be given in any units but they must be
  the same on the source and target sides; furthermore they must be in square radians if the True Area (TR) correction is activated, see section \ref{subsec_interp}.

  Surfaces can be defined through the {\tt oasis\_write\_area} API routine, see section \ref{subsubsec_griddef}.
  
  This file {\em areas.nc} is mandatory for the global {\tt
    CONSERV} post-processing operation;
  it is not required otherwise.

\end{enumerate}

\section{Coupling restart files}
\label{subsec_restartdata}

At the beginning of a coupled run, some coupling fields may have to be
initially read from their coupling restart file on their source grid
(see the LAG concept in section \ref{subsec_lag}). When
needed, these files are also automatically updated by the last active
{\tt oasis\_put} or {\tt prism\_put\_proto} call of the run (see
section \ref{prismput}) .
% To force the writing of the field in its coupling restart file, one
% can use the routine {\tt prism\_put\_restart\_proto} (see section
% \ref{subsec:auxiliary}).
{\bf Warning}: the date is not written or read to/from the restart
file; therefore, the user has to make sure that the appropriate
coupling restart file is present in the working directory. The
coupling restart files must follow the NetCDF format.

% Note that all restart files have to be present in the working
% directory at the %beginning of the
% run even if one model is delayed with respect to the others.

The name of the coupling restart file is given by the 6th character
string on the first configuring line for each field in the {\it
  namcouple} (see section \ref{subsec_namcouplesecond}). Coupling
fields coming from different models cannot be in the same coupling
restart files, but for each model, there can be an arbitrary number of
fields written in one coupling restart file. One 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. 

The coupling restart files are also used automatically by OASIS3-MCT
to allow partial LOCTRANS time transformation to be saved at the end
of a run for exact restart at the start of the next run. When LOCTRANS
transformations are specified, the initial coupling restart file
should not contain any LOCTRANS restart fields. For the following
runs, it is mandatory that the coupling restart file contains LOCTRANS
restart fields coherent with the current namcouple entries. For
example, it will not be possible to restart a run with a multiple
field entry in the namcouple with a coupling restart file created by a 
run not activating this multiple file option.


In the coupling restart files, the fields must be provided on the
source grid in single or double precision REAL arrays and, as the grid
data files, must be dimensioned {\tt (nx, ny)}, where {\tt nx} and
{\tt ny} are the grid first and second dimension (see section
\ref{subsec_griddata} above).  The shape and orientation of each
restart field (and of the corresponding coupling fields exchanged
during the simulation) must be coherent with the shape of its grid
data arrays.

\section{Input data files}
\label{subsec_inputdata}

Fields with status {\tt INPUT} in the {\it namcouple} will, at
runtime, simply be read in from a NetCDF input file by the target
model below the {\tt oasis\_get} call, at appropriate times
corresponding to the input period indicated by the user in the {\it
  namcouple}.

The name of the file must be the one given on the field first
configuring line in the {\it namcouple} (see section
\ref{subsubsec_secondINPUT}). There must be one input file per {\tt
  INPUT} field, containing a time sequence of the field in a single or
double precision REAL array named with the same field symbolic name as in the
{\it namcouple} and dimensioned {\tt (nx,ny,time)}.  The time variable
has to be an array {\tt time(time)} expressed in ``seconds since
beginning of run''. The ``time'' dimension has to be the unlimited
dimension.
% For a practical example, see the file SOALBEDO.nc in {\tt
%   oasis3/examples/toyoasis3/data}.

% subsection{Input data files}

\section{Transformation auxiliary data files}
\label{subsec_mapdata}

The mapping files to be used for the MAPPING option must be consistent
with the files generated by the SCRIP library to be used for the {\tt
  SCRIPR} transformations (see also section \ref{subsec_interp}). The
files are NetCDF containing the following fields:
\begin{verbatim}
dimensions:
      src_grid_size = xxx ;
      dst_grid_size = xxx ;
      num_links = xxx ;
      num_wgts = xxx ;
variables:
      int src_address(num_links) 
      int dst_address(num_links) 
      double remap_matrix(num_links, num_wgts) 
\end{verbatim}
where
\begin{itemize}
\item {\tt src\_grid\_size} is a scalar integer indicating the total number
  of points in the source grid.  
  This field is a netCDF dimension.
\item {\tt dst\_grid\_size} is a scalar integer indicating the total number
  of points in the target grid.  
  This field is a netCDF dimension.
\item {\tt num\_links} is a scalar integer indicating the total number
  of associated source and target grid point pairs in the file.  This field is a netCDF dimension.
\item {\tt num\_wgts} is a scalar integer indicating the number of
  weights per associated grid point pair (up to 5 are supported, see
  sections \ref{prismput} and \ref{subsec_interp} for BICUBIC and CONSERV/SECOND).
  This field is a netCDF dimension.
\item {\tt src\_address} is a one dimensional array of size {\tt
    num\_links}.  It contains the integer source address associated
  with each weight.  This field is a netCDF variable.
\item {\tt dst\_address} is a one dimensional array of size {\tt
    num\_links}.  It contains the integer destination address
  associated with each weight.  This field is a netCDF variable.
\item {\tt remap\_matrix} is a two dimensional array of size {\tt
    (num\_links, num\_wgts)}.  It contains the real weight value(s)
  associated with the source and destination address.  For each link, 
  up to 5 weights are supported, see sections \ref{prismput} and \ref{subsec_interp} 
  especially for BICUBIC and CONSERV/SECOND. This field is a
  netCDF variable.
\end{itemize}
