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