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

\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 
OASIS3-MCT coupler are used by at least 65 modelling groups all around the
world to couple more than 80 applications on different computing platforms\footnote{A list of
coupled models realised with OASIS3-MCT can be found at https://oasis.cerfacs.fr/en/oasis-coupled-models/}.
OASIS3-MCT 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 regularly reinforced
with additional resources coming from European and national projects.

The current OASIS3-MCT internally uses 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 remapping, as a parallel matrix vector 
multiplication, and parallel distributed exchanges of the coupling
fields, based on pre-computed remapping weights and addresses. 
Its design philosophy, based on flexibility and minimal invasiveness,
is close to the OASIS3-MCT 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 (NCAR CESM).

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 to be linked to the component models, and which main
function is to interpolate and exchange the coupling fields 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 remapping, are performed in parallel on the set of source or
target component processes and all coupling exchanges are now executed
in parallel directly between the component processes via Message Passing Interface
(MPI). OASIS3-MCT also supports file I/O using NetCDF and has python and C language bindings. 

The developments realised in the different versions of OASIS3-MCT are described in Appendix \ref{sec_changes}.
To communicate with another component, or to perform I/O actions, a
component model needs to include few specific calls to OASIS3-MCT Application Programming Interface (API).  The {\it namcouple} configuration file is also largely unchanged, although several options are either added, deprecated, not used
or not supported. 

Results obtained with IS-ENES2 coupling technology benchmarks show that OASIS3-MCT performs as well as, and even better at very high number of cores, than other coupling technologies, at least for up to O(10000) cores. 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 codes, 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, either by following the Short Private Online Course (SPOC, see  https://cerfacs.fr/online-training/) or by going through the tutorial steps. Tutorial sources are available in directory {\tt
  examples/tutorial\_communication} and all explanations are provided in the document
{\tt tutorial\_communication.pdf} therein.

\item Identify the coupling or I/O fields and adapt the codes to
  implement the coupling exchanges with the OASIS3-MCT coupling library based on MPI message passing.
  The OASIS3-MCT coupling library uses NetCDF and therefore can also be used to perform I/O actions
  from/to disk files.  For more detail on how to use the 
  OASIS3-MCT API in the codes, 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}.
  OASIS3-MCT supports different interpolation algorithms as described in
  chapter \ref{sec_transformations}.  Remapping files can be computed
  online using the SCRIP options, or offline using either the SCRIP, ESMF or XIOS (see  {\tt
  examples/regrid\_environment}, section \ref{subsec_regrid}) and read in during the run using the MAPPING
  transformation.

{\bf We strongly recommend to tests off-line the quality of the chosen transformations and remappings} using the environment available in {\tt
  examples/regrid\_environment} and explanations provided in the document {\tt regrid\_environment.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. For details on how to compile and run a coupled model
  with OASIS3-MCT, see section \ref{sec_compilationrunning}. 

\end{enumerate}

If you need extra help, do not hesitate to contact us at
oasishelp(at)cerfacs.fr .

\section{OASIS3-MCT sources}
\label{sec_Obtaining}
OASIS3-MCT sources are available from CERFACS git server. To obtain more detail on downloading
the sources, please fill in the registration form at https://oasis.cerfacs.fr/en/downloads/ .

OASIS3-MCT directory structure is the following one:

\begin{verbatim}
 - oasis3-mct/lib/cbindings        C language bindings source code
                 /mct              Model Coupling Toolkit Coupling Software
                 /psmile           OASIS3-MCT coupling library
                 /scrip            SCRIP interpolation library               

 - oasis3-mct/doc                  OASIS3-MCT User Guide

 - oasis3-mct/util/make_dir        Utilities to compile OASIS3-MCT
                  /load_balancing  Tool for load balancing analysis
                  
 - oasis3-mct/pyoasis                Python wrapper source code

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

Copyright © 2021 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 © 2021, 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.''