source: CPL/oasis3-mct/branches/OASIS3-MCT_2.0_branch/doc/UG0_Stepbystep_overview.tex @ 4775

\newpage
\chapter{Introduction}
\label{sec_step}

In 1991, CERFACS started the development of
a software interface to couple existing ocean and atmosphere numerical General
Circulation Models. Today, different versions of the 
OASIS coupler are used by about 35 modelling groups in Europe, Australia, Asia and
North America on the different computing platforms \citep{valcke8}\footnote{The list of
coupled models realized with OASIS can be found at https://verc.enes.org/oasis/oasis-dedicated-user-support-1/some-current-users}.
OASIS sustained development is ensured by a collaboration
between CERFACS and the Centre National de la Recherche Scientifique
(CNRS) and its maintainance and user support is presently reinforced
with additional resources coming from the IS-ENES2 project funded by the EU.

The current OASIS3-MCT is interfaced with MCT, the Model
Coupling Toolkit\footnote{www.mcs.anl.gov/research/projects/mct/} \citep{mct_larson} \newline \citep{mct_jacob}, developed by the Argonne National Laboratory in the USA. MCT implements fully parallel regridding, as a parallel matrix vector 
multiplication, and parallel distributed exchanges of the coupling
fields, based on pre-computed regridding weights and addresses. 
Its design philosophy, based on flexibility and minimal invasiveness,
is close to the OASIS approach. 
MCT has proven parallel performance and is, most notably, the
underlying coupling software used in National Center for Atmospheric
Research Community Earth System Model 1 (NCAR CESM1).

OASIS3-MCT is a portable set of Fortran 77, Fortran 90 and C routines. Low-intrusiveness, portability and flexibility are OASIS3-MCT key design concepts. After compilation OASIS3-MCT is a coupling library that needs to be linked to the component models, and which main function is to interpolate and exchange the coupling fields between them to form a coupled system.  OASIS3-MCT supports  coupling of 2D logically-rectangular fields but 3D fields and 1D fields expressed on unstructured grids are also supported using a one dimension degeneration of the structures. Thanks to MCT, all transformations, including regridding, are executed in parallel on the set of source or target component processes and all couplings are now executed in parallel directly between the components via Message Passing Interface
(MPI). OASIS3-MCT also supports file I/O using netcdf.  

In spite of the significant changes in underlying implementation, usage of OASIS3-MCT in the codes has largely remained unchanged with respect to OASIS3.3.
To communicate with another model, or to perform I/O actions, a component model needs to include few specific calls to the OASIS3-MCT coupling library, which Application Programmig Interface (API) used in component models is unchanged.  The use 
statement has been updated and now requires a single ``use\ mod\_prism'' or ``use mod\_oasis'' statement instead of the various use statements required in prior
OASIS3 versions.  The {\it namcouple} configuration file is also largely unchanged
relative to OASIS3, although several options are either not used
or not supported.  There is a new transformation in {\it namcouple}
i.e. {\tt MAPPING} which allows a user to specify a mapping
file generated externally.  The changes between OASIS3.3 and OASIS3-MCT are lilsted in appendix \ref{sec_changes}.
 
First tests done with up to
8000 cores on the Bullx Curie machine at the TGCC are very encouraging
and it is therefore very likely that OASIS3-MCT will provide an efficient and
easy-to-use coupling solution for many climate modelling groups in the few years to come. 

%See appendix \ref{sec_changes} for a more detailed list of changes in this %version.

\section{Step-by-step use of OASIS3-MCT}

To use OASIS3-MCT for coupling models (and/or perform I/O
actions), one has to follow these steps:
\begin{enumerate}
\item Obtain OASIS3-MCT source code (see chapter \ref{sec_Obtaining}).
\item Get familiar with OASIS3-MCT by going through the tutorial steps. The tutorial sources are given in directory {\tt
  examples/tutorial} and all explanations are provided in the document {\tt tutorial\_oasis3-mct.pdf} therein. 

\item Identify the coupling or I/O fields and adapt the component
  models to allow their exchange with the OASIS3-MCT coupling library based on MPI1 message passing.
  The OASIS3-MCT coupling library uses NetCDF and therefore can be used to perform I/O actions
  from/to disk files.  For more detail on how to interface a model
  with OASIS3-MCT, see chapter \ref{sec_modelinterfacing}.

\item Define all coupling and I/O parameters and the transformations
  required to adapt each coupling field from the source model grid to
  the target model grid; on this basis, prepare OASIS3-MCT configuring file 
  {\it namcouple} (see chapter \ref{sec_namcouple}). 
  OASIS3-MCT supports different interpolation algorithms as described in
  chapter \ref{sec_transformations}.  Regridding files can be computed
  online using the SCRIP options or offline and read using the MAPPING
  transformation.

{\bf We strongly recommend to tests off-line the quality of the chosen transformations and regriddings} using the environment available in {\tt
  examples/test\_interpolation} and explanations provided in the document {\tt test\_interpolation\_oasis3-mct.pdf} therein. 

\item Generate required auxiliary data files (see chapter
  \ref{sec_auxiliary}).
\item Compile OASIS3-MCT, the component models and start the coupled
  experiment. Details on how to compile and run a coupled model with OASIS3-MCT can be found in section \ref{sec_compilationrunning}. 

\end{enumerate}

If you need extra help, do not hesitate to contact us (see contact
details on the back of the cover page).

\section{OASIS3-MCT sources}
\label{sec_Obtaining}
OASIS3-MCT sources are available from CERFACS SVN server. To obtain more detail on downloading
the sources, please fill in the registration form at
https://verc.enes.org/oasis/download/oasis-registration-form .

OASIS3-MCT directory structure is the following one:

\begin{verbatim}
 - oasis3-mct/lib/psmile         OASIS3-MCT coupling library
                 /scrip          SCRIP interpolation library
                 /mct            Model Coupling Toolkit Coupling Software
                  
 - oasis3-mct/doc                OASIS3-MCT User Guide

 - oasis3-mct/util/make_dir      Utilities to compile OASIS3-MCT

 - oasis3-mct/examples           Environment to run the tutorial and
                                 test_interpolation toy coupled models. 
\end{verbatim}
\newpage
\section{Licenses and Copyrights}
 
\subsection{OASIS3-MCT license and copyright statement}

Copyright © 2013 Centre Europ\'een de Recherche et Formation
Avanc\'ee en Calcul Scientifique (CERFACS).  

This software and ancillary information called OASIS3-MCT is free
software.  CERFACS has rights to use, reproduce, and distribute
OASIS3-MCT. The public may copy, distribute, use, prepare derivative works and
publicly display OASIS3-MCT under the terms of the Lesser GNU General
Public License (LGPL) as published by the Free Software Foundation,
provided that this notice and any statement of authorship are
reproduced on all copies. If OASIS3-MCT is modified to produce derivative
works, such modified software should be clearly marked, so as not to
confuse it with the OASIS3-MCT version available from CERFACS.

The developers of the OASIS3-MCT software are researchers attempting to
build a modular and user-friendly coupler accessible to the climate
modelling community. Although we use the tool ourselves and have made
every effort to ensure its accuracy, we can not make any
guarantees. We provide the software to you for free. In return,
you--the user--assume full responsibility for use of the software. The
OASIS3-MCT software comes without any warranties (implied or expressed) and
is not guaranteed to work for you or on your computer. Specifically,
CERFACS and the various individuals involved in development and
maintenance of the OASIS3-MCT software are not responsible for any damage
that may result from correct or incorrect use of this software.

\subsection{MCT copyright statement}
\label{sec_MCT}

                            Modeling Coupling Toolkit (MCT) Software

Copyright © 2011, UChicago Argonne, LLC as Operator of Argonne National Laboratory. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
\begin{enumerate}
\item Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
\item Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
\item The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the UChicago Argonne, LLC, as Operator of Argonne National Laboratory." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

This software was authored by:
\begin{itemize}
\item Argonne National Laboratory Climate Modeling Group, Mathematics and Computer Science Division, Argonne National Laboratory, Argonne IL 60439
\item Robert Jacob, tel: (630) 252-2983, E-mail: jacob@mcs.anl.gov
\item Jay Larson, E-mail: larson@mcs.anl.gov
\item Everest Ong
\item Ray Loy
\end{itemize}

\item WARRANTY DISCLAIMER. THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE COPYRIGHT HOLDER, THE UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, AND THEIR EMPLOYEES: (1) DISCLAIM ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NON-IN- FRINGEMENT, (2) DO NOT ASSUME ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR USEFULNESS OF THE SOFTWARE, (3) DO NOT REPRESENT THAT USE OF THE SOFTWARE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS, (4) DO NOT WARRANT THAT THE SOFTWARE WILL FUNCTION UNINTERRUPTED, THAT IT IS ERROR-FREE OR THAT ANY ERRORS WILL BE CORRECTED. 

\item LIMITATION OF LIABILITY. IN NO EVENT WILL THE COPYRIGHT HOLDER, THE UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, OR THEIR EMPLOYEES: BE LIABLE FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL OR PUNITIVE DAMAGES OF ANY KIND OR NATURE, INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS OR LOSS OF DATA, FOR ANY REASON WHATSOEVER, WHETHER SUCH LIABILITY IS ASSERTED ON THE BASIS OF CONTRACT, TORT (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR OTHERWISE, EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGES.

\end{enumerate}

\subsection{The SCRIP 1.4 license copyright statement}
\label{sec_SCRIP}

The SCRIP 1.4 copyright statement reads as follows:

``Copyright © 1997, 1998 the Regents of the University of California.
This software and ancillary information (herein called SOFTWARE)
called SCRIP is made available under the terms described here. The
SOFTWARE has been approved for release with associated LA-CC Number
98-45. Unless otherwise indicated, this SOFTWARE has been authored by
an employee or employees of the University of California, operator of
Los Alamos National Laboratory under Contract No. W-7405-ENG-36 with
the United States Department of Energy. The United States Government
has rights to use, reproduce, and distribute this SOFTWARE. The public
may copy, distribute, prepare derivative works and publicly display
this SOFTWARE without charge, provided that this Notice and any
statement of authorship are reproduced on all copies. Neither the
Government nor the University makes any warranty, express or implied,
or assumes any liability or responsibility for the use of this
SOFTWARE. If SOFTWARE is modified to produce derivative works, such
modified SOFTWARE should be clearly marked, so as not to confuse it
with the version available from Los Alamos National Laboratory.''