Changeset 11799 for NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/global/coding_rules.tex

Timestamp:

2019-10-25T16:27:34+02:00 (5 years ago)

Author:

mocavero

Message:

Update the branch to v4.0.1 of the trunk

Location:

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc

Files:

• . (modified) (1 prop)
• latex (modified) (1 prop)
• latex/global (modified) (1 prop)
• latex/global/coding_rules.tex (modified) (23 diffs)

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/global/coding_rules.tex

@@ -1 +1 @@
 
 \chapter{Coding Rules}
-\label{apdx:coding}
-
-\minitoc
+\label{apdx:CODING}
+
+\chaptertoc
 
 \newpage
@@ -13 +13 @@
 produces fewer bugs and is easier to maintain.
 Therefore, it is essential that the model development follows some rules:
+
 \begin{itemize}
-   \item well planned and designed
-   \item well written
-   \item well documented (both on- and off-line)
-   \item maintainable
-   \item easily portable
-   \item flexible.
+\item well planned and designed
+\item well written
+\item well documented (both on- and off-line)
+\item maintainable
+\item easily portable
+\item flexible.
 \end{itemize}
 
-To satisfy part of these aims, \NEMO is written with a coding standard which is close to the ECMWF rules,
-named DOCTOR \citep{gibson_rpt86}. 
+To satisfy part of these aims, \NEMO\ is written with a coding standard which is close to the ECMWF rules,
+named DOCTOR \citep{gibson_rpt86}.
 These rules present some advantages like:
+
 \begin{itemize}
-   \item to provide a well presented program
-   \item to use rules for variable names which allow recognition of their type
-   (integer, real, parameter, local or shared variables, etc. ). 
+\item to provide a well presented program
+\item to use rules for variable names which allow recognition of their type   (integer, real, parameter, local or shared variables, etc. ).
 \end{itemize}
 
@@ -35 +36 @@
 \section{Introduction}
 
-This document describes conventions used in \NEMO coding and suggested for its development.
-The objectives are to offer a guide to all readers of the \NEMO code, and to facilitate the work of
+This document describes conventions used in \NEMO\ coding and suggested for its development.
+The objectives are to offer a guide to all readers of the \NEMO\ code, and to facilitate the work of
 all the developers, including the validation of their developments, and
-eventually the implementation of these developments within the \NEMO platform.
+eventually the implementation of these developments within the \NEMO\ platform.
 
 A first approach of these rules can be found in the code in \path{./src/OCE/module_example} where
@@ -45 +46 @@
 
 This work is based on the coding conventions in use for the Community Climate System Model
-\footnote {\href{http://www.cesm.ucar.edu/working_groups/Software/dev_guide/dev_guide/node7.html}{UCAR conventions}}, 
+\footnote {\href{http://www.cesm.ucar.edu/working_groups/Software/dev_guide/dev_guide/node7.html}{UCAR conventions}},
 the previous version of this document (``FORTRAN coding standard in the OPA System'') and
-the expertise of the \NEMO System Team.
+the expertise of the \NEMO\ System Team.
 After a general overview below, this document will describe:
 
 \begin{itemize}
-   \item The style rules, $i.e.$ the syntax, appearance and naming conventions chosen to improve readability of the code;
-   \item The content rules, $i.e.$ the conventions to improve the reliability of the different parts of the code;
-   \item The package rules to go a step further by improving the reliability of the whole and
+\item The style rules, $i.e.$ the syntax, appearance and naming conventions chosen to improve readability of the code;
+\item The content rules, $i.e.$ the conventions to improve the reliability of the different parts of the code;
+\item The package rules to go a step further by improving the reliability of the whole and
    interfaces between routines and modules.
 \end{itemize}
@@ -59 +60 @@
 \section{Overview and general conventions}
 
-\NEMO has 3 major components: ocean dynamics (\path{./src/OCE}), sea-ice (\path{./src/ICE}) and
+\NEMO\ has 3 major components: ocean dynamics (\path{./src/OCE}), sea-ice (\path{./src/ICE}) and
 marine biogeochemistry (\path{./src/MBG}).
 %, linear-tangent and adjoint of the dynamics ($TAM$) each of them corresponding to a directory.
@@ -79 +80 @@
 
 \begin{itemize}
-   \item \path{SBC}             surface module
-   \item \path{IOM}             management of the I/O
-   \item \path{NST}             interface to AGRIF (nesting model) for dynamics and biogeochemistry
-   \item \path{OBC}, \path{BDY} management of structured and unstructured open boundaries 
-   \item \path{C1D}             1D (vertical) configuration for dynamics, sea-ice and biogeochemistry
-   \item \path{OFF}             off-line module: passive tracer or biogeochemistry alone
-   \item \path{...}
+\item \path{SBC}             surface module
+\item \path{IOM}             management of the I/O
+\item \path{NST}             interface to AGRIF (nesting model) for dynamics and biogeochemistry
+\item \path{OBC}, \path{BDY} management of structured and unstructured open boundaries
+\item \path{C1D}             1D (vertical) configuration for dynamics, sea-ice and biogeochemistry
+\item \path{OFF}             off-line module: passive tracer or biogeochemistry alone
+\item \path{...}
 \end{itemize}
 
@@ -142 +143 @@
 
 All FORTRAN keywords are in capital: \forcode{DIMENSION}, \forcode{WRITE}, \forcode{DO}, \forcode{END DO},
-\forcode{NAMELIST}, ... All other parts of the \NEMO code will be written in lower case.
+\forcode{NAMELIST}, ... All other parts of the \NEMO\ code will be written in lower case.
 
 \subsection{Comments}
@@ -216 +217 @@
 \subsection{F90 Standard}
 
-\NEMO software adheres to the \fninety language standard and does not rely on any specific language or
+\NEMO\ software adheres to the \fninety language standard and does not rely on any specific language or
 vendor extensions.
 
@@ -268 +269 @@
 For example, zdftke, where ``zdf'' stands for vertical diffusion, and ``tke'' for turbulent kinetic energy. \\
 Note that by implication multiple modules are not allowed in a single file.
-The use of common blocks is deprecated in \fortran 90 and their use in \NEMO is strongly discouraged.
+The use of common blocks is deprecated in \fortran 90 and their use in \NEMO\ is strongly discouraged.
 Modules are a better way to declare static data.
 Among the advantages of modules is the ability to freely mix data of various types, and
@@ -292 +293 @@
       complex                                                                                     \\
       \hline
-      public \par or \par module variable                                                         & 
-      \textbf{m n} \par \textit{but not} \par \textbf{nn\_}                                       & 
+      public \par or \par module variable                                                         &
+      \textbf{m n} \par \textit{but not} \par \textbf{nn\_}                                       &
       \textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_} &
       \textbf{l} \par \textit{but not} \par \textbf{lp ld ll ln\_}                                &
@@ -301 +302 @@
       \hline
       dummy \par argument                                                                         &
-      \textbf{k} \par \textit{but not} \par \textbf{kf}                                           & 
-      \textbf{p} \par \textit{but not} \par \textbf{pp pf}                                        & 
+      \textbf{k} \par \textit{but not} \par \textbf{kf}                                           &
+      \textbf{p} \par \textit{but not} \par \textbf{pp pf}                                        &
       \textbf{ld}                                                                                 &
       \textbf{cd}                                                                                 &
@@ -309 +310 @@
       \hline
       local \par variable                                                                         &
-      \textbf{i}                                                                                  & 
+      \textbf{i}                                                                                  &
       \textbf{z}                                                                                  &
       \textbf{ll}                                                                                 &
@@ -333 +334 @@
       \hline
       namelist                                                                                    &
-      \textbf{nn\_}                                                                               & 
+      \textbf{nn\_}                                                                               &
       \textbf{rn\_}                                                                               &
       \textbf{ln\_}                                                                               &
@@ -388 +389 @@
 Is to be used rather than the \#ifdef abbreviate form since it may have conflicts with some Unix scripts.
 
-Tests on cpp keys included in \NEMO at compilation step:
+Tests on cpp keys included in \NEMO\ at compilation step:
 
 \begin{itemize}
@@ -402 +403 @@
 \subsection{Configurations}
 
-The configuration defines the domain and the grid on which \NEMO is running.
+The configuration defines the domain and the grid on which \NEMO\ is running.
 It may be useful to associate a CPP key and some variables to a given configuration, although
 the part of the code changed under each of those keys should be minimized.
@@ -487 +488 @@
 \subsection{Headers}
 
-Prologues are not used in \NEMO for now, although it may become an interesting tool in combination with
+Prologues are not used in \NEMO\ for now, although it may become an interesting tool in combination with
 ProTeX auto documentation script in the future.
 Rules to code the headers and layout of a module or a routine are illustrated in the example module available with
@@ -563 +564 @@
 \subsection{Bounds checking}
 
-\NEMO is able to run when an array bounds checking option is enabled
+\NEMO\ is able to run when an array bounds checking option is enabled
 (provided the cpp key \texttt{key\_vectopt\_loop} is not defined). \\
 Thus, constructs of the following form are disallowed:
@@ -606 +607 @@
 the \texttt{stat=<integer\ variable>} optional argument. \\
 
-In addition to arrays contained within modules, many routines in \NEMO require local, ``workspace'' arrays to
+In addition to arrays contained within modules, many routines in \NEMO\ require local, ``workspace'' arrays to
 hold the intermediate results of calculations.
 In previous versions of \NEMO, these arrays were declared in such a way as to be automatically allocated on
@@ -697 +698 @@
 It is then associated with a sub-array of \texttt{wrk\_3d\_5} once the call to
 \texttt{wrk\_in\_use()} has completed successfully.
-Note that in F95 (to which \NEMO conforms) it is not possible for either the upper or lower array bounds of
+Note that in F95 (to which \NEMO\ conforms) it is not possible for either the upper or lower array bounds of
 the pointer object to differ from those of the target array. \\
 
@@ -710 +711 @@
 This should enable the developer to choose alternatives for use in the subroutine being worked on. \\
 
-When compiling \NEMO for production runs,
+When compiling \NEMO\ for production runs,
 the calls to {\texttt{wrk\_in\_use()} / \texttt{wrk\_not\_released()} can be reduced to stubs that just
 return \forcode{.false.} by setting the cpp key \texttt{key\_no\_workspace\_check}.
@@ -732 +733 @@
 \subsection{Parallelism using MPI}
 
-\NEMO is written in order to be able to run on one processor, or on one or more using MPI
+\NEMO\ is written in order to be able to run on one processor, or on one or more using MPI
 ($i.e.$ activating the cpp key $key\_mpp\_mpi$).
-The domain decomposition divides the global domain in cubes (see \NEMO reference manual).
+The domain decomposition divides the global domain in cubes (see \NEMO\ reference manual).
 Whilst coding a new development, the MPI compatibility has to be taken in account
 (see \path{./src/LBC/lib_mpp.F90}) and should be tested.
@@ -748 +749 @@
 Below is a list of features to avoid:
 \begin{itemize}
-\item
-  \forcode{COMMON} block
+\item \forcode{COMMON} block
   (use the declaration part of \forcode{MODULE} instead)
-\item
-  \forcode{EQUIVALENCE}
+\item \forcode{EQUIVALENCE}
   (use \forcode{POINTER} or derived data type instead to form data structure)
-\item
-  Assigned and computed \forcode{GOTO}
+\item Assigned and computed \forcode{GOTO}
   (use the \forcode{CASE} construct instead)
-\item
-  Arithmetic \forcode{IF} statement
+\item Arithmetic \forcode{IF} statement
   (use the block \forcode{IF}, \forcode{ELSE}, \forcode{ELSEIF}, \forcode{ENDIF} or
   \forcode{SELECT CASE} construct instead)
-\item
-  Labelled \forcode{DO} construct
+\item Labelled \forcode{DO} construct
   (use unlabelled \forcode{END DO} instead)
-\item
-  \forcode{FORMAT} statement
+\item \forcode{FORMAT} statement
   (use character parameters or
   explicit format- specifiers inside the \forcode{READ} or \forcode{WRITE} statement instead)
-\item
-  \forcode{GOTO} and \forcode{CONTINUE} statements
+\item \forcode{GOTO} and \forcode{CONTINUE} statements
   (use \forcode{IF}, \forcode{CASE}, \forcode{DO WHILE}, \forcode{EXIT} or \forcode{CYCLE} statements or
   a contained ?)
-\item
-  \forcode{PAUSE}
-\item
-  \forcode{ENTRY} statement: a sub-program must only have one entry point.
-\item
-  \forcode{RETURN} is obsolete and so not necessary at the end of program units
-\item
-  \forcode{FUNCTION} statement
-\item
-  Avoid functions with side effects.
+\item \forcode{PAUSE}
+\item \forcode{ENTRY} statement: a sub-program must only have one entry point.
+\item \forcode{RETURN} is obsolete and so not necessary at the end of program units
+\item \forcode{FUNCTION} statement
+\item Avoid functions with side effects.
   \footnote{
     First, the code is easier to understand, if you can rely on
@@ -790 +779 @@
     This is especially important on massive parallel and as well on vector machines.
   }
-\item
-  \forcode{DATA} and \forcode{BLOCK DATA}
+\item \forcode{DATA} and \forcode{BLOCK DATA}
   (use initialisers)
 \end{itemize}
 
+%% Imported from introduction
+%%gm    To be put somewhere else ....
+%%nm    We should consider creating a glossary for all this kind of stuff (terms, acronyms and symbols)
+%%      http://en.wikibooks.org/wiki/LaTeX/Glossary
+%\noindent CPP keys and namelists are used as inputs to the code.
+
+%\noindent \index{CPP keys} CPP keys
+
+%Some CPP keys are implemented in the \fortran code to allow code selection at compiling step.
+%This selection of code at compilation time reduces the reliability of the whole platform since
+%it changes the code from one set of CPP keys to the other.
+%It is used only when the addition/suppression of the part of code highly changes the amount of memory at run time.
+%Usual coding looks like:
+
+%\begin{forlines}
+%#if defined key_option1
+%  ! This part of the \fortran code will be active
+%  ! only if key_option1 is activated at compiling step
+%#endif
+%\end{forlines}
+
+%\noindent \index{Namelist} Namelists
+
+%The namelist allows to input variables (character, logical, real and integer) into the code.
+%There is one namelist file for each component of \NEMO\ (dynamics, sea-ice, biogeochemistry...)
+%containing all the \fortran namelists needed.
+%The implementation in \NEMO\ uses a 2-step process.
+%For each \fortran namelist, two files are read:
+
+%\begin{enumerate}
+%\item
+%  A reference namelist (in \path{./cfgs/SHARED/namelist_ref}) is read first.
+%  This file contains all the namelist variables which are initialised to default values
+%\item
+%  A configuration namelist (in \path{./cfgs/CFG_NAME/EXP00/namelist_cfg}) is read aferwards.
+%  This file contains only the namelist variables which are changed from default values, and overwrites those.
+%\end{enumerate}
+%A template can be found in \path{NEMO/OPA_SRC/module.example}.
+%The effective namelist, taken in account during the run, is stored at execution time in
+%an \texttt{output\_namelist\_dyn} (or \texttt{\_ice} or \texttt{\_top}) file.
+%%gm  end
+
+%%nm: Add some words on the \NEMO\ dependencies
+%The model is implemented in \fninety, with preprocessing (C pre-processor).
+%It runs under UNIX.
+%It is optimized for vector computers and parallelised by domain decomposition with MPI.
+%All input and output is done in NetCDF (Network Common Data Format) with a optional direct access format for output.
+%To ensure the clarity and readability of the code it is necessary to follow coding rules.
+%The coding rules for OPA include conventions for naming variables,
+%with different starting letters for different types of variables (real, integer, parameter\ldots).
+%Those rules are briefly presented in \autoref{apdx:coding} and a more complete document is available .
+
+%The model is organized with a high internal modularity based on physics.
+%For example, each trend (\ie, a term in the RHS of the prognostic equation) for momentum and tracers
+%is computed in a dedicated module.
+%To make it easier for the user to find his way around the code, the module names follow a three-letter rule.
+%For example, \mdl{traldf} is a module related to the TRAcers equation, computing the Lateral DiFfussion.
+%The complete list of module names is presented in \autoref{apdx:coding}.      %====>>>> to be done !
+%Furthermore, modules are organized in a few directories that correspond to their category,
+%as indicated by the first three letters of their name (\autoref{tab:chapters}).