New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
NEMO_coding_conv.tex in NEMO/trunk/doc/latex/NEMO/main – NEMO

source: NEMO/trunk/doc/latex/NEMO/main/NEMO_coding_conv.tex @ 10405

Last change on this file since 10405 was 9388, checked in by nicolasmartin, 6 years ago

Global reorganisation of DOC directory: implementation and configuration of syntax highlighting with 'minted' LaTeX package
New macros have been created to insert different source codes (fortran, xml, c and shell-session) in the document.
Pygments Python package is now required to compile the documentation.

File size: 32.9 KB
Line 
1\documentclass[a4paper]{article}
2\usepackage{type1cm} 
3\usepackage{times} 
4\usepackage{color} 
5\usepackage{rotating} 
6\usepackage{color} 
7\usepackage{framed} 
8\usepackage{makeidx} 
9\graphicspath{{figures/}}
10
11%%%%%%%
12\pagestyle{empty} 
13\setlength{\leftmargin}{1 cm} 
14\setlength{\rightmargin}{1 cm} 
15\setlength{\oddsidemargin}{0 cm} 
16\setlength{\evensidemargin}{0 cm} 
17\setlength{\topmargin}{-1cm} 
18\setlength{\textwidth}{16 cm} 
19\setlength{\textheight}{25cm} 
20
21%%%%%%%%%essai plus jolis from NEMO book
22\usepackage{fancyhdr}
23
24\pagestyle{fancy}
25%\usepackage[colorlinks=true]{hyperref} %%create link
26 
27\makeindex %% run first makeindex NEMO_coding.conv.idx NEMO_coding.conv.ist
28     
29\begin{document}
30
31
32\title{ 
33\includegraphics[width=0.3\textwidth]{NEMO_logo_Black} \\
34\vspace{1.0cm}
35\rule{345pt}{1.5pt} \\
36\vspace{0.45cm}
37 {\Huge NEMO coding conventions} 
38\rule{345pt}{1.5pt} \\ 
39{\small  -- version 3 --}   }
40%\title{NEMO coding conventions}
41\author{NEMO System Team }
42\date{March 2011}
43
44
45\maketitle
46
47\newpage
48
49\tableofcontents   
50         
51\newpage
52%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
53\section{Introduction}
54This document describes conventions\index{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. \\
55A first approach of these rules can be found in the code in $NEMO/OPA\_SRC/module\_example$ where all the basics coding conventions are illustrated. More details can be found below.\\
56This work is based on the coding conventions in use for the Community Climate System Model, \footnote { http://www.cesm.ucar.edu/working\_groups/Software/dev\_guide/dev\_guide/node7.html }
57 the previous version of this document (``FORTRAN coding standard in the OPA System'') and the expertise of the NEMO System Team which can be contacted for further information ($nemo\_st@locean-ipsl.upmc.fr$)
58After a general overview below, this document will describe :
59\begin{itemize} 
60\item The style rules, i.e. the syntax, appearance and naming conventions chosen to improve readability of the code;
61\item The content rules, i.e. the conventions to improve the reliability of the different parts of the code;
62\item The package rules to go a step further by improving the reliability of the whole and interfaces between routines and modules.
63\end{itemize}
64
65%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
66\section{Overview and general conventions}
67NEMO has several different components: ocean dynamics ($OPA\_SRC$), sea-ice ($LIM\_SRC$), ocean biogeochemistry\- ($TOP\_SRC$), linear-tangent and adjoint of the dynamics ($TAM$)É each of them corresponding to a directory.
68In each directory, one will find some FORTRAN files and/or subdirectories, one per functionality of the code: $BDY$ (boundaries), $DIA$ (diagnostics), $DOM$ (domain), $DYN$ (dynamics), $LDF$ (lateral diffusion), etc...\\
69All name are chosen to be as self-explanatory as possible, in English, all prefixes are 3 digits.\\
70English is used for all variables names, comments, and documentation. \\
71Physical units are MKS. The only exception to this is the temperature, which is expressed in degrees Celsius, except in bulk formulae and part of LIM sea-ice model where it is in Kelvin. See $DOM/phycst.F90$ files for conversions.
72%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
73\section{Architecture}
74Within each directory, organisation of files is driven by ÒorthogonalityÓ\index{orthogonality}, i.e. one functionality of the code is intended to be in one and only one directory, and one module and all its related routines are in one file.
75The functional modules\index{module} are:
76\begin{itemize} 
77\item SBC      surface module
78\item IOM      management of the I/O
79\item NST      interface to AGRIF (nesting model) for dynamics and biogeochemistry
80\item OBC, BDY management of structured and unstructured open boundaries
81\item C1D      1D (vertical) configuration for dynamics, sea-ice and biogeochemistry
82\item OFF      off-line module: passive tracer or biogeochemistry alone
83\item CFG      tutorial and reference configurations
84\item DOC      documentation
85\end{itemize}
86
87For example, the file $domain.F90$ contains the module $domain$ and all the subroutines related to this module ($ dom\_init, dom\_nam, dom\_ctl$).
88%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
89\section{Style rules}
90%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
91\subsection{Argument list format}
92Routine argument lists will contain a maximum 5 variables\index{variable} per line, whilst continuation lines can be used.
93This applies both to the calling routine and the dummy argument list in the routine being called. The purpose is to simplify matching up the arguments between caller and callee.
94
95\begin{verbatim}
96SUBROUTINE tra_adv_eiv( kt, pun, pvn, pwn )
97
98      CALL tra_adv_eiv( kt, zun, zvn, zwn )
99\end{verbatim}
100
101%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
102\subsection{Array syntax}
103Except for long loops (see below), array notation should be used if possible. To improve readability the array shape must be shown in brackets, e.g.:
104\begin{verbatim}
105onedarraya(:) = onedarrayb(:) + onedarrayc(:)
106twodarray (:,:) = scalar * anothertwodarray(:,:)
107\end{verbatim}
108When accessing sections of arrays, for example in finite difference equations, do so by using the triplet notation on the full array, e.g.:
109\begin{verbatim}
110twodarray(:,2:len2) = scalar                      & 
111   &                * ( twodarray2(:,1:len2-1 )   & 
112   &                -   twodarray2(:,2:len2 ) )
113\end{verbatim}   
114For long, complicated loops, explicitly indexed loops should be preferred. In general when using this syntax, the order of the loops indices should reflect the following scheme (for best usage of data locality):
115\begin{verbatim}
116DO jk = 1, jpk
117   DO jj = 1, jpj
118      DO ji = 1, jpi
119         array(ji,jj,jk) = ...
120      END DO
121   END DO
122END DO
123\end{verbatim}
124%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
125\subsection{Case}
126All FORTRAN keywords are in capital : \begin {verbatim} DIMENSION, WRITE, DO, END DO, NAMELIST \end{verbatim} 
127All other parts of the NEMO code will be written in lower case.   
128
129%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
130\subsection{Comments}
131Comments in the code are useful when reading the code and changing or developing it. \\
132The full documentation and detailed explanations are to be added in the reference manual (TeX files, aside from the code itself). \\
133In the code, the comments should explain variable content and describe each computational step.\\
134Comments in the header start with ``!!''. For more details on the content of the headers, see ÒContent rules/HeadersÓ in this document.\\
135Comments in the code start with ``!''.\\
136All comments are indented (3, 6, or 9 É blank spaces).\\
137Short comments may be included on the same line as executable code, and an additional line can be used with proper alignment. For example:
138\begin{verbatim}
139      zx = zx *zzy   ! Describe what is going on and if it is
140      !              ! too long use another Ô!Õ for proper
141      !              ! alignment with automatic indentation
142\end{verbatim}     
143More in-depth comments should be written in the form:
144\begin{verbatim}
145!   Check of some namelist values
146\end{verbatim}         
147or
148\begin{verbatim}   
149!
150!         !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
151!         !  Bottom boundary condition on tke
152!         !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
153!
154\end{verbatim}   
155Key features of this style are 1) it starts with a "!" in the column required for proper indentation, 2) the text is offset above and below by a blank line or a content line built for underlying.
156%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
157\subsection{Continuation lines}
158Continuation lines can be used with precise alignment for readability. For example:
159\begin{verbatim}   
160avmu(ji,jj,jk) = avmu(ji,jj,jk) * ( un(ji,jj,jk-1) - un(ji,jj,jk) )   &
161   &                            * ( ub(ji,jj,jk-1) - ub(ji,jj,jk) )   &
162   &           / (  fse3uw_n(ji,jj,jk)         &
163   &              * fse3uw_b(ji,jj,jk) )
164\end{verbatim}   
165Code lines, which are continuation lines of assignment statements, must begin to the right of the column of the assignment operator. Due to the possibility of automatic indentation in some editor (emacs for example), use a ``\&'' as first character of the continuing lines to maintain the alignment.
166%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
167\subsection{Declaration of arguments and local variables}
168
169In a routine, input arguments and local variables are declared 1 per line, with a comment field on the same line as the declaration. Multiple comment lines describing a single variable are acceptable if needed. For example:
170\begin{verbatim} 
171INTEGER             ::   kstp   ! ocean time-step index
172\end{verbatim}
173%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
174\subsection{F90 Standard}
175NEMO software adheres to the FORTRAN 95 language standard and does not rely on any specific language or vendor extensions.
176
177
178%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
179\subsection{Free-Form Source}
180Free-form source will be used. The F90/95 standard allows lines of up to 132 characters, but a self-imposed limit of 80 should enhance readability, or print source files with two columns per page. Multi-line comments that extend to column 100 are unacceptable.
181
182%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
183\subsection{Indentation}
184Code as well as comment lines within loops, if-blocks, continuation lines, MODULE or SUBROUTINE statements will be indented 3 characters for readability. (except for CONTAINS that remains at first column)
185\begin{verbatim} 
186MODULE mod1
187   REAL(wp) xx
188CONTAINS
189   SUBROUTINE sub76( px, py, pz, pw, pa,   & 
190      &              pb, pc, pd, pe      )
191      <instruction>
192   END SUBROUTINE sub76
193END MODULE mod1
194\end{verbatim}
195%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
196\subsection{Loops}
197Loops, if explicit, should be structured with the do-end do construct as opposed to numbered loops. Nevertheless non-numeric labels can be used for a big iterative loop of a recursive algorithm. In the case of a long loop, a self-descriptive label can be used (i.e. not just a number).
198
199%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
200\subsection{Naming Conventions: files}
201A file containing a module will have the same name as the module it contains (because dependency rules used by "make" programs are based on file names).
202\footnote{For example, if routine A "USE"s module B, then "make" must be told of the dependency relation which requires B to be compiled before A. If one can assume that module B resides in file B.o, building a tool to generate this dependency rule (e.g. A.o: B.o) is quite simple. Put another way, it is difficult (to say nothing of CPU-intensive) to search an entire source tree to find the file in which module B resides for each routine or module which "USE"s B.}
203
204%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
205\subsection{Naming Conventions: modules}
206Use a meaningful English name and the ``3 letters'' naming convention: first 3 letters for the code section, and last 3 to describe the module. For example, zdftke, where ``zdf'' stands for vertical diffusion, and ``tke'' for turbulent kinetic energy.
207\\
208Note that by implication multiple modules are not allowed in a single file.
209The 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 to limit access to contained variables through the use of the ONLY and PRIVATE attributes.
210
211%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
212\subsection{Naming Conventions: variables}
213All variable should be named as explicitly as possible in English. The naming convention concerns prefix letters of these name, in  order to identify the variable type and status.\\
214Never use a FORTRAN keyword as a routine or variable name. \\
215The table below lists the starting letter(s) to be used for variable naming, depending on their type and status:
216%--------------------------------------------------TABLE--------------------------------------------------
217\begin{table}[htbp]
218\begin{center}
219\begin{tabular}{|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|}
220\hline  Type \par / Status &   integer&   real&   logical &   character&   double \par precision&   complex \\ 
221\hline
222public  \par or  \par module variable& 
223\textbf{m n} \par \textit{but not } \par \textbf{nn\_}& 
224\textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_}& 
225\textbf{l} \par \textit{but not} \par \textbf{lp ld ll ln\_}& 
226\textbf{c} \par \textit{but not} \par \textbf{cp cd cl cn\_}& 
227\textbf{d} \par \textit{but not} \par \textbf{dp dd dl dn\_}& 
228\textbf{y} \par \textit{but not} \par \textbf{yp yd yl} \\
229\hline
230dummy \par argument& 
231\textbf{k} \par \textit{but not} \par \textbf{kf}& 
232\textbf{p} \par \textit{but not}  \par \textbf{pp pf}& 
233\textbf{ld}& 
234\textbf{cd}& 
235\textbf{dd}& 
236\textbf{yd} \\
237\hline
238local \par variable& 
239\textbf{i}& 
240\textbf{z}& 
241\textbf{ll}& 
242\textbf{cl}& 
243\textbf{cd}& 
244\textbf{yl} \\
245\hline
246loop \par control& 
247\textbf{j} \par \textit{but not } \par \textbf{jp}& 
248& 
249& 
250& 
251& 
252 \\
253\hline
254parameter& 
255\textbf{jp}& 
256\textbf{pp}& 
257\textbf{lp}& 
258\textbf{cp}& 
259\textbf{dp}& 
260\textbf{yp} \\
261\hline
262
263namelist&
264\textbf{nn\_}& 
265\textbf{rn\_}& 
266\textbf{ln\_}& 
267\textbf{cn\_}& 
268\textbf{dn\_}& 
269\\
270\hline
271CPP \par macro& 
272\textbf{kf}& 
273\textbf{sf} \par & 
274& 
275& 
276& 
277 \\
278\hline
279\end{tabular}
280\label{tab1}
281\end{center}
282\end{table}
283%--------------------------------------------------------------------------------------------------------------
284
285%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
286\subsection{Operators}
287Use of the operators $<, >, <=, >=, ==, /= $ is strongly recommended instead of their deprecated counterparts, $lt., .gt., .le., .ge., .eq., and .ne. $ The motivation is readability. In general use the notation: \\
288$<Blank><Operator><Blank>$
289%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
290\subsection{Pre processor}
291Where the use of a language pre-processor is required, it will be the C pre-processor (cpp).\\
292The cpp key is the main feature used, allowing to ignore some useless parts of the code at compilation step. \\
293The advantage is to reduce the memory use; the drawback is that compilation of this part of the code isn't checked. \\
294The cpp key feature should only be used for a few limited options, if it reduces the memory usage. In all cases, a logical variable and a FORTRAN $IF$ should be preferred.
295When using a cpp key $key\_optionname$, a corresponding logical variable $lk\_optionname$ should be declared to allow FORTRAN $IF$ tests in the code and  a FORTRAN module with the same name (i.e. $optionname.F90$) should
296 be defined. This module is the only place where a ``\#if defined'' command appears, selecting either the whole FORTRAN code or a dummy module. For example, the TKE vertical physics, the module name is $zdftke.F90$, the CPP key is $key\_zdftke$ and the associated logical is $lk\_zdftke$.
297
298The following syntax:
299\begin{verbatim} 
300#if defined key_optionname
301!! Part of code conditionally compiled if cpp key key_optionname is active
302#endif
303\end{verbatim} 
304Is to be used rather than the \#ifdef abbreviate form since it may have conflicts with some Unix scripts.
305
306Tests on cpp keys included in NEMO at compilation step:
307\begin{itemize}
308\item The CPP keys used are compared to the previous list of cpp keys (the compilation will stop if trying to specify a Ònon-existing keyÓ)
309\item If a change occurs in the CPP keys used for a given experiment, the whole compilation phase is done again.
310\end{itemize}
311%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
312\section{Content rules}
313
314%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
315\subsection{Configurations}
316The 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. As an example, the "ORCA2" configuration (global ocean, 2 degrees grid size) is associated with the cpp key $key\_orca2$ for which
317\begin{verbatim} 
318cp_cfg = "orca"
319jp_cfg = 2
320\end{verbatim} 
321%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
322\subsection{Constants}
323Physical constants (e.g. pi, gas constants) must never be hardwired into the executable portion of a code. Instead, a mnemonically named variable or parameter should be set to the appropriate value, in the setup routine for the package\index{package}. We realize than many parameterizations rely on empirically derived constants or fudge factors, which are not easy to name. In these cases it is not forbidden to leave such factors coded as "magic numbers" buried in executable code, but comments should be included referring to the source of the empirical formula. Hard-coded numbers should never be passed through argument lists.
324
325%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
326\subsection{Declaration for variables and constants}
327
328\subsubsection{Rules :}
329Variables used as constants should be declared with attribute PARAMETER and used always without copying to local variables, inorder to prevent from using different values for the same constant or changing it accidentally.
330\begin{itemize}
331\item Usage of the DIMENSION statement or attribute is required in declaration statements
332\item The ``::'' notation is quite useful to show that this program unit declaration part is  written in standard FORTRAN syntax, even if there are no attributes to clarify the  declaration section. Always use the notation $<$blank$>$::$<$three blanks$>$ to improve readability.
333\item Declare the length of a character variable using the CHARACTER (len=xxx) syntax
334\footnote { The len specifier is important because it is possible to have several kinds for characters  (e.g. Unicode using two bytes per character, or there might be a different kind for Japanese e.g. NEC). }
335
336\item For all global data (in contrast to module data, that is all data that can be access by other module) must be accompanied with a comment field  on the same line.
337\footnote {This allows a easy research of where and how a variable is declared using the unix command: ``grep var *90 |grep !:''. }
338\\
339For example:
340\begin{verbatim}
341REAL(wp), DIMENSION(jpi,jpj,jpk) ::  ua  &  !: i-horizontal velocity (m/s)
342\end{verbatim}
343\end{itemize}
344
345\subsubsection{Implicit None:}
346 All subroutines and functions will include an IMPLICIT NONE statement.
347Thus all variables must be explicitly typed. It also allows the compiler to detect typographical errors in variable names.
348For modules, one IMPLICIT NONE statement in the modules definition section is needed. This also removes the need to have IMPLICIT NONE statements in any routines that are CONTAIN'd in the module.
349Improper data initialisation is another common source of errors.
350\footnote{A variable could contain an initial value you did not expect. This can happen for several reasons, e.g. the variable has never been assigned a value, its value is outdated, memory has been allocated for a pointer but you have forgotten to initialise the variable pointed to.} 
351To avoid problems, initialise variables as close as possible to where they are first used.
352
353\subsubsection{Attributes:}
354$PRIVATE / PUBLIC$ :
355All resources of a module are $PUBLIC$ by default.
356A reason to store multiple routines and their data in a single module is that the scope of the data defined in the module can be limited to the routines which are in the same module. This is accomplished with the $PRIVATE$ attribute.\\
357$INTENT$ :
358All dummy arguments of a routine must include the $INTENT$ clause in their declaration in order to improve control of variables in routine calls.
359
360%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
361\subsection{Headers}
362Prologues are not used in NEMO for now, although it may become an interesting tool in combination with ProTeX auto documentation script in the future.
363Rules to code the headers and layout of a module or a routine are illustrated in the example module available with the code : {\it NEMO/OPA\_SRC/module\_example}
364%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
365\subsection{Interface blocks}
366Explicit interface blocks are required between routines if optional or keyword arguments are to be used. They also allow the compiler to check that the type, shape and number of arguments specified in the CALL are the same as those specified in the subprogram itself. FORTRAN 95 compilers can automatically provide explicit interface blocks  for routines contained in a module.
367%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
368\subsection{I/O Error Conditions}
369I/O statements which need to check an error condition will use the $iostat=<integer variable>$ construct instead of the outmoded end= and err=. \\
370Note that a 0 value means success, a positive value means an error has occurred, and a negative value means the end of record or end of file was encountered.
371 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
372\subsection{PRINT - ASCII output files}
373Output listing and errors are directed to $numout$ logical unit =6 and produces a file called $ocean.output$  (use ln\_prt to have one output per process in  MPP). Logical $lwp$ variable allows for less verbose outputs.
374To output an error from a routine, one can use the following template:
375\begin{verbatim}
376      IF( nstop /= 0 .AND. lwp ) THEN   ! error print
377         WRITE(numout,cform_err)
378         WRITE(numout,*) nstop, ' error have been found'
379      ENDIF
380\end{verbatim}
381
382%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
383\subsection{Precision}
384Parameterizations should not rely on vendor-supplied flags to supply a default floating point precision or integer size. The F95$ KIND$ feature should be used instead. In order to improve portability between 32 and 64 bit platforms, it is necessary to make use of kinds by using a specific module ($OPA\_SRC/par\_kind.F90$)  declaring the "kind definitions" to obtain the required numerical precision and range as well as the size of INTEGER. It should be noted that numerical constants need to have a suffix of \_$kindvalue$ to have the according size. \\
385Thus $wp$ being the "working precision" as declared in $OPA\_SRC/par\_kind.F90$, declaring real array $zpc$ will take the form:
386\begin{verbatim}
387      REAL(wp), DIMENSION(jpi,jpj,jpk) ::  zpc      ! power consumption
388\end{verbatim}
389%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
390\subsection{Structures}
391The TYPE structure allowing to declare some variables is more often used in NEMO, especially in the modules dealing with reading fields, or interfaces.For example
392\begin{verbatim}
393 ! Definition of a tracer as a structure
394      TYPE PTRACER
395         CHARACTER(len = 20)  :: sname  !: short name
396         CHARACTER(len = 80 ) :: lname  !: long name
397         CHARACTER(len = 20 ) :: unit   !: unit
398         LOGICAL              :: lini   !: read in a file or not
399         LOGICAL              :: lsav   !: ouput the tracer or not
400      END TYPE PTRACER
401
402      TYPE(PTRACER) , DIMENSION(jptra) :: tracer
403\end{verbatim}
404 
405 Missing rule on structure name??
406 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
407\section{Packages coding rules}
408 
409%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
410\subsection{Bounds checking}
411NEMO is able to run when an array bounds checking option is enabled (provided the cpp key $key\_vectopt\_loop$ is not defined). \\
412Thus, constructs of the  following form are disallowed:
413\begin{verbatim}
414REAL(wp) :: arr(1)
415\end{verbatim}
416where "arr" is an input argument into which the user wishes to index beyond 1. Use of the (*) construct in array dimensioning  is forbidden also because it effectively disables array bounds checking.
417%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
418\subsection{Communication}
419A package should refer only to its own modules and subprograms and to those intrinsic functions included in the Fortran standard.\\
420All communication with the package will be through the argument list or namelist input.
421\footnote { The point behind this rule is that packages should not have to know details of the surrounding model data structures, or the names of variables outside of the package. A notable exception to this rule is model resolution parameters. The reason for the exception is to allow compile-time array sizing inside the package. This is often important for efficiency.}
422%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
423\subsection{Error conditions}
424When an error condition occurs inside a package, a message describing what went wrong will be printed (see PRINT - ASCII output files). The name of the routine in which the error occurred must be included. It is acceptable to terminate execution within a package, but the developer may instead wish to return an error flag through the argument list, see $stpctl.F90$.
425%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
426\subsection{Memory management}
427
428The main action is to identify and declare which arrays are PUBLIC and
429which are PRIVATE.\\ As of version 3.3.1 of NEMO, the use of static
430arrays (size fixed at compile time) has been deprecated.  All module
431arrays are now declared ALLOCATABLE and allocated in either the
432$<$module\_name$>$\_alloc() or $<$module\_name$>$\_init()
433routines. The success or otherwise of each ALLOCATE must be checked
434using the $Stat=<integer\ variable>$ optional argument.\\
435
436In addition to arrays contained within modules, many routines in NEMO
437require local, ``workspace'' arrays to hold the intermediate results
438of calculations. In previous versions of NEMO, these arrays were
439declared in such a way as to be automatically allocated on the stack
440when the routine was called.  An example of an automatic array is:
441\begin{verbatim}
442SUBROUTINE sub(n)
443   REAL :: a(n)
444   ...
445END SUBROUTINE sub
446\end{verbatim}
447The downside of this approach is that the program will crash if it
448runs out of stack space and the reason for the crash might not be
449obvious to the user.
450
451Therefore, as of version 3.3.1, the use of automatic arrays is
452deprecated. Instead, a new module, ``wrk\_nemo,'' has been introduced
453which contains 1-,2-,3- and 4-dimensional workspace arrays for use in
454subroutines. These workspace arrays should be used in preference to
455declaring new, local (allocatable) arrays whenever possible. The only
456exceptions to this are when workspace arrays with lower bounds other
457than 1 and/or with extent(s) greater than those in the {\it wrk\_nemo}
458module are required.\\
459
460The 2D, 3D and 4D workspace arrays in {\it wrk\_nemo} have extents
461$jpi$, $jpj$, $jpk$ and $jpts$ ($x$, $y$, $z$ and tracers) in the first,
462second, third and fourth dimensions, respectively. The 1D arrays are
463allocated with extent MAX($jpi\times jpj, jpk\times jpj, jpi\times
464jpk$).\\
465
466The REAL (KIND=$wp$) workspace arrays in {\it wrk\_nemo} are named
467e.g. $wrk\_1d\_1$, $wrk\_4d\_2$ etc. and should be accessed by USE'ing
468the {\it wrk\_nemo} module. Since these arrays are available to any
469routine, some care must be taken that a given workspace array is not
470already being used somewhere up the call stack. To help with this,
471{\it wrk\_nemo} also contains some utility routines; {\it
472  wrk\_in\_use()} and {\it wrk\_not\_released()}. The former first
473checks that the requested arrays are not already in use and then sets
474internal flags to show that they are now in use. The {\it
475  wrk\_not\_released()} routine un-sets those internal flags. A
476subroutine using this functionality for two, 3D workspace arrays named
477$zwrk1$ and $zwrk2$ will look something like:
478\begin{verbatim}
479SUBROUTINE sub()
480   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released
481   USE wrk_nemo, ONLY: zwrk1 => wrk_3d_5, zwrk2 => wrk_3d_6
482   !
483   IF(wrk_in_use(3, 5,6)THEN
484      CALL ctl_stop('sub: requested workspace arrays unavailable.')
485      RETURN
486   END IF
487   ...
488   ...
489   IF(wrk_not_released(3, 5,6)THEN
490      CALL ctl_stop('sub: failed to release workspace arrays.')
491   END IF
492   !
493END SUBROUTINE sub
494\end{verbatim}
495The first argument to each of the utility routines is the
496dimensionality of the required workspace (1--4). Following this there
497must be one or more integers identifying which workspaces are to be
498used/released.
499Note that, in the interests of keeping the code as simple as possible,
500there is no use of POINTERs etc. in the {\it wrk\_nemo}
501module. Therefore it is the responsibility of the developer to ensure
502that the arguments to {\it wrk\_in\_use()} and {\it
503  wrk\_not\_released()} match the workspace arrays actually being used
504by the subroutine.\\
505
506If a workspace array is required that has extent(s) less than those of
507the arrays in the {\it wrk\_nemo} module then the advantages of
508implicit loops and bounds checking may be retained by defining a
509pointer to a sub-array as follows:
510\begin{verbatim}
511SUBROUTINE sub()
512   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released
513   USE wrk_nemo, ONLY: wrk_3d_5
514   !
515   REAL(wp), DIMENSION(:,:,:), POINTER :: zwrk1
516   !
517   IF(wrk_in_use(3, 5)THEN
518      CALL ctl_stop('sub: requested workspace arrays unavailable.')
519      RETURN
520   END IF
521   !
522   zwrk1 => wrk_3d_5(1:10,1:10,1:10)
523   ...
524END SUBROUTINE sub
525\end{verbatim}
526Here, instead of ``use associating'' the variable $zwrk1$ with the
527array $wrk\_3d\_5$ (as in the first example), it is explicitly
528declared as a pointer to a 3D array. It is then associated with a
529sub-array of $wrk\_3d\_5$ once the call to {\it wrk\_in\_use()} has
530completed successfully. Note that in F95 (to which NEMO conforms) it
531is not possible for either the upper or lower array bounds of the
532pointer object to differ from those of the target array.\\
533
534In addition to the REAL (KIND=$wp$) workspace arrays, {\it wrk\_nemo}
535also contains 2D integer arrays and 2D REAL arrays with extent ($jpi$,
536$jpk$), {\it i.e.} $xz$. The utility routines for the integer
537workspaces are {\it iwrk\_in\_use()} and {\it iwrk\_not\_released()}
538while those for the $xz$ workspaces are {\it wrk\_in\_use\_xz()}
539and {\it wrk\_not\_released\_xz()}.
540
541Should a call to one of the {\it wrk\_in\_use()} family of utilities
542fail, an error message is printed along with a table showing which of
543the workspace arrays are currently in use. This should enable the
544developer to choose alternatives for use in the subroutine being
545worked on.\\
546
547When compiling NEMO for production runs, the calls to {\it
548  wrk\_in\_use()}/{\it wrk\_not\_released()} can be reduced to stubs
549that just return $.$FALSE$.$ by setting the cpp key
550{\it key\_no\_workspace\_check}. These stubs may then be inlined (and
551thus effectively removed altogether) by setting appropriate compiler
552flags (e.g. ``-finline'' for the Intel compiler or ``-Q'' for the IBM
553compiler).
554
555 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
556\subsection{Optimisation}
557
558Considering the new computer architecture, optimisation cannot be considered independently from the computer type.
559In NEMO, portability is a priority, before any too specific optimisation.
560Some tools are available to help: \\
561For vector computers:
562\begin{itemize} 
563\item  using $key\_vectopt\_loop$ allows to unroll a loop
564\end{itemize}
565%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
566\subsection{Package attribute: $PRIVATE, PUBLIC, USE, ONLY$}
567Module variables and routines should be encapsulated by using the PRIVATE attribute. What shall be used outside the module can be declared PUBLIC instead. Use USE with the ONLY attribute to specify which of the variables, type definitions etc. defined in a module are to be made available to the using routine.
568%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
569\subsection {Parallelism: using MPI}
570NEMO 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). Whilst coding a new development, the MPI compatibility has to be taken in account (see $LBC/lib\_mpp.F90$) and should be tested. By default, the $x$-$z$ part of the decomposition is chosen to be as square as possible. However, this may be overriden by specifying the number of subdomains in latitude and longitude in the nammpp section of the namelist file.
571
572%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
573\section{Features to be avoided}
574
575The code must follow the current standards of FORTRAN and ANSI C.  In particular, the code should not produce any WARNING at compiling phase, so that users can be easily alerted of potential bugs when some appear in their new developments. ).
576Below is a list of features to avoid:
577\begin{itemize}
578\item COMMON blocks (use the declaration part of MODULEs instead)
579\item EQUIVALENCE (use POINTERs or derived data types instead to form data structures)
580\item Assigned and computed GOTOs (use the CASE construct instead)
581\item Arithmetic IF statements ( use the block IF, ELSE, ELSEIF, ENDIF or SELECT CASE construct instead)
582\item Labeled DO constructs  (use unlabeled END DO instead)
583\item FORMAT statements (use character parameters or explicit format- specifiers inside the READ or WRITE statement instead)
584\item GOTO and CONTINUE statement (use IF, CASE, DO WHILE, EXIT or CYCLE statements or a contained
585\item PAUSE
586\item ENTRY statements: a subprogram must only have one entry point.
587\item RETURN Ð it is obsolete and so not necessary at the end of program units
588\item STATEMENT FUNCTION
589 \item Avoid functions with side effects.
590\footnote{ First, the code is easier to understand, if you can rely on the rule that functions don't change their arguments, second, some compilers generate more efficient code for PURE (in FORTRAN 95 there are the attributes PURE and ELEMENTAL) functions, because they can store the arguments in different places. This is especially important on massive parallel and as well on vector machines. }
591\item DATA and BLOCK DATA - (use initialisers)
592\end{itemize}
593
594%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
595
596% \printindex
597% \input NEMO_coding.conv.ind
598
599\end{document}
Note: See TracBrowser for help on using the repository browser.