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

Last change on this file since 10495 was 10495, checked in by nicolasmartin, 21 months ago

Few editions on main files for the manual and global review of LaTeX file for the coding conventions

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