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 @ 11433

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

Pre-implementation of new cover page and new headings style for reference manuals

Cover page

The layout of the frontpage has been completely redesigned,
a coloured banner has been added to emphasize the title and easily identify each manual
between them.
The chosen color for each document (blue for NEMO, gray for SI3 and green for TOP) will be
used throughout the manual for the links and in the chapter headings.
The list of authors (writers/editors/reviewers) for the version of the manual is given next to
the abstract, which is now included in the frontpage.
A link to an existing ORCID profile for the author precedes its name.
Few settings have been added to each definitions.tex in order to adjust the rendering of the cover page (vertical spaces above and below the title, a subtitle, the width for authors list and
abstract section)

Headings

  • header: chapter number and title for even pages, same infos for section otherwise
  • footer: name of the manual and page numbering with the total number of pages (reverse order between odd/even pages)

For the chapter heading, a new style 'Bjornstrup' from fncychap package is now use.

Abstract

Split the section in two paragraphs for all manuals

  1. Common description with almost the same sentences only customized by the general infos of the model
  2. Specific part for the characteristics of the model

Troubleshooting

As announced, I have introduced some icons from academicons and fontawesome packages.
It required to switch from pdflatex to xelatex for the compilation and it prevents from now
the building of the whole document.
Also the PDF generated does not look nice due to the font

Work in progress...

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