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