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.
coding_rules.tex in NEMO/trunk/doc/latex/global – NEMO

source: NEMO/trunk/doc/latex/global/coding_rules.tex @ 11543

Last change on this file since 11543 was 11543, checked in by nicolasmartin, 5 years ago

Implementation of convention for labelling references + files renaming
Now each reference is supposed to have the information of the chapter in its name
to identify quickly which file contains the reference (\label{$prefix:$chap_...)

Rename the appendices from 'annex_' to 'apdx_' to conform with the prefix used in labels (apdx:...)
Suppress the letter numbering

File size: 40.5 KB
Line 
1
2\chapter{Coding Rules}
3\label{apdx:CODING}
4
5\chaptertoc
6
7\newpage
8
9A "model life" is more than ten years.
10Its software, composed of a few hundred modules, is used by many people who are scientists or students and
11do not necessarily know every aspect of computing very well.
12Moreover, a well thought-out program is easier to read and understand, less difficult to modify,
13produces fewer bugs and is easier to maintain.
14Therefore, it is essential that the model development follows some rules:
15
16\begin{itemize}
17\item well planned and designed
18\item well written
19\item well documented (both on- and off-line)
20\item maintainable
21\item easily portable
22\item flexible.
23\end{itemize}
24
25To satisfy part of these aims, \NEMO is written with a coding standard which is close to the ECMWF rules,
26named DOCTOR \citep{gibson_rpt86}.
27These rules present some advantages like:
28
29\begin{itemize}
30\item to provide a well presented program
31\item to use rules for variable names which allow recognition of their type   (integer, real, parameter, local or shared variables, etc. ).
32\end{itemize}
33
34This facilitates both the understanding and the debugging of an algorithm.
35
36\section{Introduction}
37
38This document describes conventions used in \NEMO coding and suggested for its development.
39The objectives are to offer a guide to all readers of the \NEMO code, and to facilitate the work of
40all the developers, including the validation of their developments, and
41eventually the implementation of these developments within the \NEMO platform.
42
43A first approach of these rules can be found in the code in \path{./src/OCE/module_example} where
44all the basics coding conventions are illustrated.
45More details can be found below.
46
47This work is based on the coding conventions in use for the Community Climate System Model
48\footnote {\href{http://www.cesm.ucar.edu/working_groups/Software/dev_guide/dev_guide/node7.html}{UCAR conventions}},
49the previous version of this document (``FORTRAN coding standard in the OPA System'') and
50the expertise of the \NEMO System Team.
51After a general overview below, this document will describe:
52
53\begin{itemize}
54\item The style rules, $i.e.$ the syntax, appearance and naming conventions chosen to improve readability of the code;
55\item The content rules, $i.e.$ the conventions to improve the reliability of the different parts of the code;
56\item The package rules to go a step further by improving the reliability of the whole and
57   interfaces between routines and modules.
58\end{itemize}
59
60\section{Overview and general conventions}
61
62\NEMO has 3 major components: ocean dynamics (\path{./src/OCE}), sea-ice (\path{./src/ICE}) and
63marine biogeochemistry (\path{./src/MBG}).
64%, linear-tangent and adjoint of the dynamics ($TAM$) each of them corresponding to a directory.
65In each directory, one will find some FORTRAN files and/or subdirectories, one per functionality of the code:
66\path{./src/OCE/BDY} (boundaries), \path{./src/OCE/DIA} (diagnostics), \path{./src/OCE/DOM} (domain),
67\path{./src/OCE/DYN} (dynamics), \path{./src/OCE/LDF} (lateral diffusion), etc... \\
68All name are chosen to be as self-explanatory as possible, in English, all prefixes are 3 digits. \\
69English is used for all variables names, comments, and documentation. \\
70Physical units are MKS. The only exception to this is the temperature, which is expressed in degrees Celsius,
71except in bulk formulae and part of SI$^3$ sea-ice model where it is in Kelvin.
72See \path{.src/OCE/DOM/phycst.F90} files for conversions.
73
74\section{Architecture}
75
76Within each directory, organisation of files is driven by orthogonality,
77$i.e.$ one functionality of the code is intended to be in one and only one directory, and
78one module and all its related routines are in one file.
79The functional modules are:
80
81\begin{itemize}
82\item \path{SBC}             surface module
83\item \path{IOM}             management of the I/O
84\item \path{NST}             interface to AGRIF (nesting model) for dynamics and biogeochemistry
85\item \path{OBC}, \path{BDY} management of structured and unstructured open boundaries
86\item \path{C1D}             1D (vertical) configuration for dynamics, sea-ice and biogeochemistry
87\item \path{OFF}             off-line module: passive tracer or biogeochemistry alone
88\item \path{...}
89\end{itemize}
90
91For example, the file \textit{domain.F90} contains the module \texttt{domain} and all the subroutines related to
92this module (\texttt{dom\_init, dom\_nam, dom\_ctl}).
93
94\section{Style rules}
95
96\subsection{Argument list format}
97
98Routine argument lists will contain a maximum 5 variables per line,
99whilst continuation lines can be used.
100This applies both to the calling routine and the dummy argument list in the routine being called.
101The purpose is to simplify matching up the arguments between caller and callee.
102
103\begin{forlines}
104SUBROUTINE tra_adv_eiv( kt, pun, pvn, pwn )
105
106      CALL tra_adv_eiv( kt, zun, zvn, zwn )
107\end{forlines}
108
109\subsection{Array syntax}
110
111Except for long loops (see below), array notation should be used if possible.
112To improve readability the array shape must be shown in brackets, $e.g.$:
113
114\begin{forlines}
115onedarraya(:)   = onedarrayb(:) + onedarrayc(:)
116twodarray (:,:) = scalar * anothertwodarray(:,:)
117\end{forlines}
118
119When accessing sections of arrays, for example in finite difference equations,
120do so by using the triplet notation on the full array, $e.g.$:
121
122\begin{forlines}
123twodarray(:,2:len2) =   scalar                      &
124   &                  * ( twodarray2(:,1:len2-1 )   &
125   &                  -   twodarray2(:,2:len2 ) )
126\end{forlines}
127
128For long, complicated loops, explicitly indexed loops should be preferred.
129In general when using this syntax, the order of the loops indices should reflect the following scheme
130(for best usage of data locality):
131
132\begin{forlines}
133DO jk = 1, jpk
134   DO jj = 1, jpj
135      DO ji = 1, jpi
136         threedarray(ji,jj,jk) = ...
137      END DO
138   END DO
139END DO
140\end{forlines}
141
142\subsection{Case}
143
144All FORTRAN keywords are in capital: \forcode{DIMENSION}, \forcode{WRITE}, \forcode{DO}, \forcode{END DO},
145\forcode{NAMELIST}, ... All other parts of the \NEMO code will be written in lower case.
146
147\subsection{Comments}
148
149Comments in the code are useful when reading the code and changing or developing it. \\
150The full documentation and detailed explanations are to be added in the reference manual
151(TeX files, aside from the code itself). \\
152In the code, the comments should explain variable content and describe each computational step. \\
153Comments in the header start with ``!!''.
154For more details on the content of the headers, see Content rules/Headers in this document. \\
155Comments in the code start with ``!''. \\
156All comments are indented (3, 6, or 9 blank spaces). \\
157Short comments may be included on the same line as executable code, and an additional line can be used with
158proper alignment.
159For example:
160
161\begin{forlines}
162zx = zx *zzy   ! Describe what is going on and if it is
163!              ! too long use another ! for proper
164!              ! alignment with automatic indentation
165\end{forlines}
166
167More in-depth comments should be written in the form:
168
169\begin{forlines}
170   !  Check of some namelist values
171\end{forlines}
172
173or
174
175\begin{forlines}
176!
177!     !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
178!     !  Bottom boundary condition on tke
179!     !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
180!
181\end{forlines}
182
183Key features of this style are
184
185\begin{enumerate}
186\item it starts with a "!" in the column required for proper indentation,
187\item the text is offset above and below by a blank line or a content line built for underlying.
188\end{enumerate}
189
190\subsection{Continuation lines}
191
192Continuation lines can be used with precise alignment for readability. For example:
193
194\begin{forlines}
195avmu(ji,jj,jk) =   avmu(ji,jj,jk) * ( un(ji,jj,jk-1) - un(ji,jj,jk) )   &
196   &                              * ( ub(ji,jj,jk-1) - ub(ji,jj,jk) )   &
197   &             / (   fse3uw_n(ji,jj,jk)                               &
198   &                 * fse3uw_b(ji,jj,jk) )
199\end{forlines}
200
201Code lines, which are continuation lines of assignment statements, must begin to the right of the column of
202the assignment operator.
203Due to the possibility of automatic indentation in some editor (emacs for example),
204use a ``\&'' as first character of the continuing lines to maintain the alignment.
205
206\subsection{Declaration of arguments and local variables}
207
208In a routine, input arguments and local variables are declared 1 per line,
209with a comment field on the same line as the declaration.
210Multiple comment lines describing a single variable are acceptable if needed.
211For example:
212
213\begin{forlines}
214INTEGER             ::   kstp   ! ocean time-step index
215\end{forlines}
216
217\subsection{F90 Standard}
218
219\NEMO software adheres to the \fninety language standard and does not rely on any specific language or
220vendor extensions.
221
222\subsection{Free-Form Source}
223
224Free-form source will be used.
225The F90/95 standard allows lines of up to 132 characters, but a self-imposed limit of 80 should enhance readability,
226or print source files with two columns per page.
227Multi-line comments that extend to column 100 are unacceptable.
228
229\subsection{Indentation}
230
231Code as well as comment lines within loops, if-blocks, continuation lines, \forcode{MODULE} or
232\forcode{SUBROUTINE} statements will be indented 3 characters for readability
233(except for \forcode{CONTAINS} that remains at first column).
234
235\begin{forlines}
236MODULE mod1
237   REAL(wp) xx
238CONTAINS
239   SUBROUTINE sub76( px, py, pz, pw, pa,   &
240      &              pb, pc, pd, pe          )
241      <instruction>
242   END SUBROUTINE sub76
243END MODULE mod1
244\end{forlines}
245
246\subsection{Loops}
247
248Loops, if explicit, should be structured with the do-end do construct as opposed to numbered loops.
249Nevertheless non-numeric labels can be used for a big iterative loop of a recursive algorithm.
250In the case of a long loop, a self-descriptive label can be used ($i.e.$ not just a number).
251
252\subsection{Naming Conventions: files}
253
254A file containing a module will have the same name as the module it contains
255(because dependency rules used by "make" programs are based on file names).
256\footnote{
257  For example, if routine A "\forcode{USE}"s module B, then "make" must be told of the dependency relation which
258  requires B to be compiled before A.
259  If one can assume that module B resides in file B.o,
260  building a tool to generate this dependency rule ($e.g.$ A.o: B.o) is quite simple.
261  Put another way, it is difficult (to say nothing of CPU-intensive) to search an entire source tree to
262  find the file in which module B resides for each routine or module which "\forcode{USE}"s B.
263}
264
265\subsection{Naming Conventions: modules}
266
267Use a meaningful English name and the ``3 letters'' naming convention:
268first 3 letters for the code section, and last 3 to describe the module.
269For example, zdftke, where ``zdf'' stands for vertical diffusion, and ``tke'' for turbulent kinetic energy. \\
270Note that by implication multiple modules are not allowed in a single file.
271The use of common blocks is deprecated in \fortran 90 and their use in \NEMO is strongly discouraged.
272Modules are a better way to declare static data.
273Among the advantages of modules is the ability to freely mix data of various types, and
274to limit access to contained variables through the use of the \forcode{ONLY} and \forcode{PRIVATE} attributes.
275
276\subsection{Naming Conventions: variables}
277
278All variable should be named as explicitly as possible in English.
279The naming convention concerns prefix letters of these name, in order to identify the variable type and status. \\
280Never use a \fortran keyword as a routine or variable name. \\
281The table below lists the starting letter(s) to be used for variable naming, depending on their type and status:
282%--------------------------------------------------TABLE--------------------------------------------------
283\begin{table}[htbp]
284  \begin{center}
285    \begin{tabular}{|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|}
286      \hline
287      Type \par / Status                                                                          &
288      integer                                                                                     &
289      real                                                                                        &
290      logical                                                                                     &
291      character                                                                                   &
292      double \par precision                                                                       &
293      complex                                                                                     \\
294      \hline
295      public \par or \par module variable                                                         &
296      \textbf{m n} \par \textit{but not} \par \textbf{nn\_}                                       &
297      \textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_} &
298      \textbf{l} \par \textit{but not} \par \textbf{lp ld ll ln\_}                                &
299      \textbf{c} \par \textit{but not} \par \textbf{cp cd cl cn\_}                                &
300      \textbf{d} \par \textit{but not} \par \textbf{dp dd dl dn\_}                                &
301      \textbf{y} \par \textit{but not} \par \textbf{yp yd yl}                                     \\
302      \hline
303      dummy \par argument                                                                         &
304      \textbf{k} \par \textit{but not} \par \textbf{kf}                                           &
305      \textbf{p} \par \textit{but not} \par \textbf{pp pf}                                        &
306      \textbf{ld}                                                                                 &
307      \textbf{cd}                                                                                 &
308      \textbf{dd}                                                                                 &
309      \textbf{yd}                                                                                 \\
310      \hline
311      local \par variable                                                                         &
312      \textbf{i}                                                                                  &
313      \textbf{z}                                                                                  &
314      \textbf{ll}                                                                                 &
315      \textbf{cl}                                                                                 &
316      \textbf{cd}                                                                                 &
317      \textbf{yl}                                                                                 \\
318      \hline
319      loop \par control                                                                           &
320      \textbf{j} \par \textit{but not} \par \textbf{jp}                                           &
321                                                                                                  &
322                                                                                                  &
323                                                                                                  &
324                                                                                                  &
325                                                                                                  \\
326      \hline
327      parameter                                                                                   &
328      \textbf{jp}                                                                                 &
329      \textbf{pp}                                                                                 &
330      \textbf{lp}                                                                                 &
331      \textbf{cp}                                                                                 &
332      \textbf{dp}                                                                                 &
333      \textbf{yp}                                                                                 \\
334      \hline
335      namelist                                                                                    &
336      \textbf{nn\_}                                                                               &
337      \textbf{rn\_}                                                                               &
338      \textbf{ln\_}                                                                               &
339      \textbf{cn\_}                                                                               &
340      \textbf{dn\_}                                                                               &
341                                                                                                  \\
342      \hline
343      CPP \par macro                                                                              &
344      \textbf{kf}                                                                                 &
345      \textbf{sf}                                                                                 &
346                                                                                                  &
347                                                                                                  &
348                                                                                                  &
349                                                                                                  \\
350      \hline
351    \end{tabular}
352    \label{tab1}
353  \end{center}
354\end{table}
355%--------------------------------------------------------------------------------------------------------------
356
357\subsection{Operators}
358
359Use of the operators \texttt{<, >, <=, >=, ==, /=} is strongly recommended instead of their deprecated counterparts
360(\texttt{.lt., .gt., .le., .ge., .eq., .ne.}).
361The motivation is readability.
362In general use the notation: \\
363$<Blank><Operator><Blank>$
364
365\subsection{Pre processor}
366
367Where the use of a language pre-processor is required, it will be the C pre-processor (cpp). \\
368The cpp key is the main feature used, allowing to ignore some useless parts of the code at compilation step. \\
369The advantage is to reduce the memory use; the drawback is that compilation of this part of the code isn't checked. \\
370The cpp key feature should only be used for a few limited options, if it reduces the memory usage.
371In all cases, a logical variable and a FORTRAN \forcode{IF} should be preferred.
372When using a cpp key \textit{key\_optionname},
373a corresponding logical variable \textit{lk\_optionname} should be declared to
374allow FORTRAN \forcode{IF} tests in the code and
375a FORTRAN module with the same name ($i.e.$ \textit{optionname.F90}) should be defined.
376This module is the only place where a \``\#if defined'' command appears, selecting either the whole FORTRAN code or
377a dummy module.
378For example, the TKE vertical physics, the module name is \textit{zdftke.F90},
379the CPP key is \textit{key\_zdftke} and the associated logical is \textit{lk\_zdftke}.
380
381The following syntax:
382
383\begin{forlines}
384#if defined key_optionname
385!! Part of code conditionally compiled if cpp key key_optionname is active
386#endif
387\end{forlines}
388
389Is to be used rather than the \#ifdef abbreviate form since it may have conflicts with some Unix scripts.
390
391Tests on cpp keys included in \NEMO at compilation step:
392
393\begin{itemize}
394\item
395  The CPP keys used are compared to the previous list of cpp keys
396  (the compilation will stop if trying to specify a non-existing key)
397\item
398  If a change occurs in the CPP keys used for a given experiment, the whole compilation phase is done again.
399\end{itemize}
400
401\section{Content rules}
402
403\subsection{Configurations}
404
405The configuration defines the domain and the grid on which \NEMO is running.
406It may be useful to associate a CPP key and some variables to a given configuration, although
407the part of the code changed under each of those keys should be minimized.
408As an example, the "ORCA2" configuration (global ocean, 2 degrees grid size) is associated with
409the cpp key \texttt{key\_orca2} for which
410
411\begin{forlines}
412cp_cfg = "orca"
413jp_cfg = 2
414\end{forlines}
415
416\subsection{Constants}
417
418Physical constants ($e.g.$ $\pi$, gas constants) must never be hard-wired into the executable portion of a code.
419Instead, a mnemonically named variable or parameter should be set to the appropriate value,
420in the setup routine for the package.
421We realize than many parameterizations rely on empirically derived constants or fudge factors,
422which are not easy to name.
423In these cases it is not forbidden to leave such factors coded as "magic numbers" buried in executable code, but
424comments should be included referring to the source of the empirical formula.
425Hard-coded numbers should never be passed through argument lists.
426
427\subsection{Declaration for variables and constants}
428
429\subsubsection{Rules}
430
431Variables used as constants should be declared with attribute \forcode{PARAMETER} and
432used always without copying to local variables, in order to
433prevent from using different values for the same constant or changing it accidentally.
434
435\begin{itemize}
436\item
437  Usage of the \forcode{DIMENSION} statement or attribute is required in declaration statements
438\item
439  The ``::'' notation is quite useful to show that this program unit declaration part is written in
440  standard FORTRAN syntax, even if there are no attributes to clarify the declaration section.
441  Always use the notation $<$blank$>$::$<$three blanks$>$ to improve readability.
442\item
443  Declare the length of a character variable using the \forcode{CHARACTER} (len=xxx) syntax
444  \footnote {
445    The len specifier is important because it is possible to have several kinds for characters
446    ($e.g.$ Unicode using two bytes per character, or there might be a different kind for Japanese $e.g.$ NEC).
447  }
448\item
449  For all global data (in contrast to module data, that is all data that can be access by other module)
450  must be accompanied with a comment field on the same line
451  \footnote {
452    This allows a easy research of where and how a variable is declared using the unix command:
453    ``grep var *90 | grep !:''.
454  }.
455  For example:
456  \begin{forlines}
457  REAL(wp), DIMENSION(jpi,jpj,jpk) ::  ua   ! i-horizontal velocity (m/s)
458  \end{forlines}
459\end{itemize}
460
461\subsubsection{Implicit None}
462
463All subroutines and functions will include an \forcode{IMPLICIT NONE} statement.
464Thus all variables must be explicitly typed.
465It also allows the compiler to detect typographical errors in variable names.
466For modules, one \forcode{IMPLICIT NONE} statement in the modules definition section is needed.
467This also removes the need to have \forcode{IMPLICIT NONE} statements in
468any routines that are \forcode{CONTAINS}'ed in the module.
469Improper data initialisation is another common source of errors
470\footnote{
471  A variable could contain an initial value you did not expect.
472  This can happen for several reasons, $e.g.$ the variable has never been assigned a value, its value is outdated,
473  memory has been allocated for a pointer but you have forgotten to initialise the variable pointed to.
474}.
475To avoid problems, initialise variables as close as possible to where they are first used.
476
477\subsubsection{Attributes}
478
479\forcode{PRIVATE} / \forcode{PUBLIC}:
480All resources of a module are \forcode{PUBLIC} by default.
481A reason to store multiple routines and their data in a single module is that
482the scope of the data defined in the module can be limited to the routines which are in the same module.
483This is accomplished with the \forcode{PRIVATE} attribute. \\
484\forcode{INTENT}:
485All dummy arguments of a routine must include the \forcode{INTENT} clause in their declaration in order to
486improve control of variables in routine calls.
487
488\subsection{Headers}
489
490Prologues are not used in \NEMO for now, although it may become an interesting tool in combination with
491ProTeX auto documentation script in the future.
492Rules to code the headers and layout of a module or a routine are illustrated in the example module available with
493the code: \path{./src/OCE/module_example}
494
495\subsection{Interface blocks}
496
497Explicit interface blocks are required between routines if optional or keyword arguments are to be used.
498They also allow the compiler to check that the type, shape and number of arguments specified in the \forcode{CALL}
499are the same as those specified in the subprogram itself.
500FORTRAN 95 compilers can automatically provide explicit interface blocks for routines contained in a module.
501
502\subsection{I/O Error Conditions}
503
504I/O statements which need to check an error condition will use the \texttt{iostat=<integer variable>} construct
505instead of the outmoded \texttt{end=} and \forcode{err=}. \\
506Note that a 0 value means success, a positive value means an error has occurred, and
507a negative value means the end of record or end of file was encountered.
508
509\subsection{PRINT - ASCII output files}
510
511Output listing and errors are directed to \texttt{numout} logical unit =6 and
512produces a file called \textit{ocean.output} (use \texttt{ln\_prt} to have one output per process in MPP).
513Logical \texttt{lwp} variable allows for less verbose outputs.
514To output an error from a routine, one can use the following template:
515
516\begin{forlines}
517IF( nstop /= 0 .AND. lwp ) THEN   ! error print
518   WRITE(numout,cform_err)
519   WRITE(numout,*) nstop, ' error have been found'
520ENDIF
521\end{forlines}
522
523\subsection{Precision}
524
525Parameterizations should not rely on vendor-supplied flags to supply a default floating point precision or
526integer size.
527The F95 \forcode{KIND} feature should be used instead.
528In order to improve portability between 32 and 64 bit platforms,
529it is necessary to make use of kinds by using a specific module \path{./src/OCE/par_kind.F90}
530declaring the "kind definitions" to obtain the required numerical precision and range as well as
531the size of \forcode{INTEGER}.
532It should be noted that numerical constants need to have a suffix of \texttt{\_kindvalue} to
533have the according size. \\
534Thus \forcode{wp} being the "working precision" as declared in \path{./src/OCE/par_kind.F90},
535declaring real array \forcode{zpc} will take the form:
536
537\begin{forlines}
538REAL(wp), DIMENSION(jpi,jpj,jpk) ::  zpc      ! power consumption
539\end{forlines}
540
541\subsection{Structures}
542
543The \forcode{TYPE} structure allowing to declare some variables is more often used in \NEMO,
544especially in the modules dealing with reading fields, or interfaces.
545For example:
546
547\begin{forlines}
548! Definition of a tracer as a structure
549TYPE PTRACER
550   CHARACTER(len = 20)  :: sname  ! short name
551   CHARACTER(len = 80 ) :: lname  ! long name
552   CHARACTER(len = 20 ) :: unit   ! unit
553   LOGICAL              :: lini   ! read in a file or not
554   LOGICAL              :: lsav   ! ouput the tracer or not
555END TYPE PTRACER
556
557TYPE(PTRACER) , DIMENSION(jptra) :: tracer
558\end{forlines}
559
560Missing rule on structure name??
561
562\section{Packages coding rules}
563
564\subsection{Bounds checking}
565
566\NEMO is able to run when an array bounds checking option is enabled
567(provided the cpp key \texttt{key\_vectopt\_loop} is not defined). \\
568Thus, constructs of the following form are disallowed:
569
570\begin{forlines}
571REAL(wp) :: arr(1)
572\end{forlines}
573
574where "arr" is an input argument into which the user wishes to index beyond 1.
575Use of the (*) construct in array dimensioning is forbidden also because
576it effectively disables array bounds checking.
577
578\subsection{Communication}
579
580A package should refer only to its own modules and subprograms and to those intrinsic functions included in
581the Fortran standard. \\
582All communication with the package will be through the argument list or namelist input.
583\footnote{
584  The point behind this rule is that packages should not have to know details of
585  the surrounding model data structures, or the names of variables outside of the package.
586  A notable exception to this rule is model resolution parameters.
587  The reason for the exception is to allow compile-time array sizing inside the package.
588  This is often important for efficiency.
589}
590
591\subsection{Error conditions}
592
593When an error condition occurs inside a package, a message describing what went wrong will be printed
594(see PRINT - ASCII output files).
595The name of the routine in which the error occurred must be included.
596It is acceptable to terminate execution within a package, but
597the developer may instead wish to return an error flag through the argument list,
598see \textit{stpctl.F90}.
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 in-lined (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\subsection{Optimisation}
720
721Considering the new computer architecture, optimisation cannot be considered independently from the computer type.
722In \NEMO, portability is a priority, before any too specific optimisation.
723
724Some tools are available to help: for vector computers, \texttt{key\_vectopt\_loop} allows to unroll a loop
725
726\subsection{Package attribute: \forcode{PRIVATE}, \forcode{PUBLIC}, \forcode{USE}, \forcode{ONLY}}
727
728Module variables and routines should be encapsulated by using the \forcode{PRIVATE} attribute.
729What shall be used outside the module can be declared \forcode{PUBLIC} instead.
730Use \forcode{USE} with the \forcode{ONLY} attribute to specify which of the variables, type definitions etc...
731defined in a module are to be made available to the using routine.
732
733\subsection{Parallelism using MPI}
734
735\NEMO is written in order to be able to run on one processor, or on one or more using MPI
736($i.e.$ activating the cpp key $key\_mpp\_mpi$).
737The domain decomposition divides the global domain in cubes (see \NEMO reference manual).
738Whilst coding a new development, the MPI compatibility has to be taken in account
739(see \path{./src/LBC/lib_mpp.F90}) and should be tested.
740By default, the $x$-$z$ part of the decomposition is chosen to be as square as possible.
741However, this may be overriden by specifying the number of sub-domains in latitude and longitude in
742the \texttt{nammpp} section of the namelist file.
743
744\section{Features to be avoided}
745
746The code must follow the current standards of FORTRAN and ANSI C.
747In particular, the code should not produce any WARNING at compiling phase, so that
748users can be easily alerted of potential bugs when some appear in their new developments.
749Below is a list of features to avoid:
750\begin{itemize}
751\item \forcode{COMMON} block
752  (use the declaration part of \forcode{MODULE} instead)
753\item \forcode{EQUIVALENCE}
754  (use \forcode{POINTER} or derived data type instead to form data structure)
755\item Assigned and computed \forcode{GOTO}
756  (use the \forcode{CASE} construct instead)
757\item Arithmetic \forcode{IF} statement
758  (use the block \forcode{IF}, \forcode{ELSE}, \forcode{ELSEIF}, \forcode{ENDIF} or
759  \forcode{SELECT CASE} construct instead)
760\item Labelled \forcode{DO} construct
761  (use unlabelled \forcode{END DO} instead)
762\item \forcode{FORMAT} statement
763  (use character parameters or
764  explicit format- specifiers inside the \forcode{READ} or \forcode{WRITE} statement instead)
765\item \forcode{GOTO} and \forcode{CONTINUE} statements
766  (use \forcode{IF}, \forcode{CASE}, \forcode{DO WHILE}, \forcode{EXIT} or \forcode{CYCLE} statements or
767  a contained ?)
768\item \forcode{PAUSE}
769\item \forcode{ENTRY} statement: a sub-program must only have one entry point.
770\item \forcode{RETURN} is obsolete and so not necessary at the end of program units
771\item \forcode{FUNCTION} statement
772\item Avoid functions with side effects.
773  \footnote{
774    First, the code is easier to understand, if you can rely on
775    the rule that functions don't change their arguments.
776    Second, some compilers generate more efficient code for PURE functions
777    (in FORTRAN 95 there are the attributes PURE and ELEMENTAL), because
778    they can store the arguments in different places.
779    This is especially important on massive parallel and as well on vector machines.
780  }
781\item \forcode{DATA} and \forcode{BLOCK DATA}
782  (use initialisers)
783\end{itemize}
784
785%% Imported from introduction
786%%gm    To be put somewhere else ....
787%%nm    We should consider creating a glossary for all this kind of stuff (terms, acronyms and symbols)
788%%      http://en.wikibooks.org/wiki/LaTeX/Glossary
789%\noindent CPP keys and namelists are used as inputs to the code.
790
791%\noindent \index{CPP keys} CPP keys
792
793%Some CPP keys are implemented in the \fortran code to allow code selection at compiling step.
794%This selection of code at compilation time reduces the reliability of the whole platform since
795%it changes the code from one set of CPP keys to the other.
796%It is used only when the addition/suppression of the part of code highly changes the amount of memory at run time.
797%Usual coding looks like:
798
799%\begin{forlines}
800%#if defined key_option1
801%  ! This part of the \fortran code will be active
802%  ! only if key_option1 is activated at compiling step
803%#endif
804%\end{forlines}
805
806%\noindent \index{Namelist} Namelists
807
808%The namelist allows to input variables (character, logical, real and integer) into the code.
809%There is one namelist file for each component of \NEMO\ (dynamics, sea-ice, biogeochemistry...)
810%containing all the \fortran namelists needed.
811%The implementation in \NEMO\ uses a 2-step process.
812%For each \fortran namelist, two files are read:
813
814%\begin{enumerate}
815%\item
816%  A reference namelist (in \path{./cfgs/SHARED/namelist_ref}) is read first.
817%  This file contains all the namelist variables which are initialised to default values
818%\item
819%  A configuration namelist (in \path{./cfgs/CFG_NAME/EXP00/namelist_cfg}) is read aferwards.
820%  This file contains only the namelist variables which are changed from default values, and overwrites those.
821%\end{enumerate}
822%A template can be found in \path{NEMO/OPA_SRC/module.example}.
823%The effective namelist, taken in account during the run, is stored at execution time in
824%an \texttt{output\_namelist\_dyn} (or \texttt{\_ice} or \texttt{\_top}) file.
825%%gm  end
826
827%%nm: Add some words on the \NEMO\ dependencies
828%The model is implemented in \fninety, with preprocessing (C pre-processor).
829%It runs under UNIX.
830%It is optimized for vector computers and parallelised by domain decomposition with MPI.
831%All input and output is done in NetCDF (Network Common Data Format) with a optional direct access format for output.
832%To ensure the clarity and readability of the code it is necessary to follow coding rules.
833%The coding rules for OPA include conventions for naming variables,
834%with different starting letters for different types of variables (real, integer, parameter\ldots).
835%Those rules are briefly presented in \autoref{apdx:coding} and a more complete document is available .
836
837%The model is organized with a high internal modularity based on physics.
838%For example, each trend (\ie, a term in the RHS of the prognostic equation) for momentum and tracers
839%is computed in a dedicated module.
840%To make it easier for the user to find his way around the code, the module names follow a three-letter rule.
841%For example, \mdl{traldf} is a module related to the TRAcers equation, computing the Lateral DiFfussion.
842%The complete list of module names is presented in \autoref{apdx:coding}.      %====>>>> to be done !
843%Furthermore, modules are organized in a few directories that correspond to their category,
844%as indicated by the first three letters of their name (\autoref{tab:chapters}).
Note: See TracBrowser for help on using the repository browser.