New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 2697 for trunk/DOC – NEMO

Changeset 2697 for trunk/DOC


Ignore:
Timestamp:
2011-03-16T15:22:28+01:00 (13 years ago)
Author:
trackstand2
Message:

Coding standards doc updated for dynamic memory developments

Location:
trunk/DOC
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/DOC/NEMO_coding.conv.tex

    r2691 r2697  
    3131 
    3232\title{  
    33 \includegraphics[width=0.3\textwidth]{./TexFiles/FIgures/NEMO_logo_Black.pdf} \\ 
     33\includegraphics[width=0.3\textwidth]{./TexFiles/Figures/NEMO_logo_Black.pdf} \\ 
    3434\vspace{1.0cm} 
    3535\rule{345pt}{1.5pt} \\ 
     
    5454This 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. \\ 
    5555A 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 is 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$) 
     56This 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$) 
    5858After a general overview below, this document will describe : 
    5959\begin{itemize}  
     
    6565%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    6666\section{Overview and general conventions} 
    67 NEMO has different component: 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. 
     67NEMO 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. 
    6868In 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...\\ 
    6969All name are chosen to be as self-explanatory as possible, in English, all prefixes are 3 digits.\\ 
    7070English is used for all variables names, comments, and documentation. \\ 
    71 Physical units are MKS. Only exception for the temperature, which is expressed in degree Celsius, except in bulk formulae and part of LIM sea-ice model where it is in Kelvin. See $DOM/phycst.F90$ files for conversions. 
     71Physical 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. 
    7272%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    7373\section{Architecture} 
    74 Within each directory, organisation of files is driven by ÒorthogonalityÓ\index{orthogonality}, i.e. one functionality of the code is intented to be in one and only one directory, and one module and all its related routines are in one file. 
     74Within 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. 
    7575The functional modules\index{module} are: 
    7676\begin{itemize}  
     
    9090%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    9191\subsection{Argument list format} 
    92 Routines argument lists will contain a maximum 5 variables\index{variable} per line, whilst continuation lines can be used.  
     92Routine argument lists will contain a maximum 5 variables\index{variable} per line, whilst continuation lines can be used.  
    9393This 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.  
    9494 
     
    112112   &                -   twodarray2(:,2:len2 ) )  
    113113\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: (best usage of data locality): 
     114For 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): 
    115115\begin{verbatim} 
    116116DO jk = 1, jpk  
     
    124124%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    125125\subsection{Case} 
    126 All FORTRAN keywords are in capital : \begin {verbatim} DIMENSION, WRITE, DO É END DO, NAMELIST \end{verbatim}  
     126All FORTRAN keywords are in capital : \begin {verbatim} DIMENSION, WRITE, DO, END DO, NAMELIST \end{verbatim}  
    127127All other parts of the NEMO code will be written in lower case.    
    128128 
     
    132132The full documentation and detailed explanations are to be added in the reference manual (TeX files, aside from the code itself). \\ 
    133133In 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 "!".\\ 
     134Comments in the header start with ``!!''. For more details on the content of the headers, see ÒContent rules/HeadersÓ in this document.\\ 
     135Comments in the code start with ``!''.\\ 
    136136All comments are indented (3, 6, or 9 É blank spaces).\\ 
    137137Short comments may be included on the same line as executable code, and an additional line can be used with proper alignment. For example:  
     
    163163   &              * fse3uw_b(ji,jj,jk) ) 
    164164\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.  
     165Code 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.  
    166166%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    167167\subsection{Declaration of arguments and local variables} 
     
    173173%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    174174\subsection{F90 Standard} 
    175 NEMO software adheres to the FORTRAN 95 language standard and does not rely on any specific language or vendor extension. 
     175NEMO software adheres to the FORTRAN 95 language standard and does not rely on any specific language or vendor extensions. 
    176176 
    177177 
    178178%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    179179\subsection{Free-Form Source} 
    180 Free-form source will be used. The F90/95 standard allows 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 would be unacceptable. 
     180Free-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. 
    181181 
    182182%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
     
    195195%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    196196\subsection{Loops} 
    197 Loops, if explicit, should be structured with the do-end do construct as opposed to numbered loops. Nevertheless non-number label can be used for a big iterative loop of recursive algorithm. In case of long loop, a self-descriptive label can be used (i.e. not just a number). 
     197Loops, 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). 
    198198 
    199199%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    200200\subsection{Naming Conventions: files} 
    201 A file containing a module will have the same name as the inside module. 
     201A 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.} 
    202203 
    203204%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    204205\subsection{Naming Conventions: modules} 
    205 Use meaningful English name and the Ò3 lettersÓ naming convention: first 3 metters 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. 
    206 Modules must be called with the same name as the file in which they reside, because dependency rules used by "make" programs are based on file names 
    207 \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.} 
    208  .  
     206Use 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.  
    209207\\ 
    210208Note that by implication multiple modules are not allowed in a single file.  
    211 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 use of the ONLY and PRIVATE attributes.  
     209The 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.  
    212210 
    213211%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    214212\subsection{Naming Conventions: variables} 
    215 All variable should be named as explicit as possible in English. The naming convention concerns prefix letters of these name, in  order to identify the variable type and status.\\ 
     213All 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.\\ 
    216214Never use a FORTRAN keyword as a routine or variable name. \\ 
    217 Table below lists the stating letter(s) to be used for variable naming, depending on their type and status: 
     215The table below lists the starting letter(s) to be used for variable naming, depending on their type and status: 
    218216%--------------------------------------------------TABLE-------------------------------------------------- 
    219217\begin{table}[htbp] 
     
    293291Where the use of a language pre-processor is required, it will be the C pre-processor (cpp).\\ 
    294292The cpp key is the main feature used, allowing to ignore some useless parts of the code at compilation step. \\ 
    295 The advantage is to reduce the memory use; the drawback is that compilation of this part of the code isnÕt checked. \\ 
    296 The cpp key feature should only be used for a few limited options, if is reduces the memory usage. In all cases, a logical variable and a FORTRAN $IF$ should be preferred. 
     293The advantage is to reduce the memory use; the drawback is that compilation of this part of the code isn't checked. \\ 
     294The 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. 
    297295When 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 
    298  to 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$.  
     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$.  
    299297 
    300298The following syntax: 
     
    316314%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    317315\subsection{Configurations} 
    318 The configuration defines the domain and the grid on which NEMO is running. It may be usefull 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  
     316The 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  
    319317\begin{verbatim}  
    320318cp_cfg = "orca" 
     
    332330\begin{itemize} 
    333331\item Usage of the DIMENSION statement or attribute is required in declaration statements 
    334 \item Attribute SAVE is banned. This simplifies the use of AGRIF software. Since all the subroutine are embedded into a module, the variables which value have to be preserved between two calls can be declared in the module interface.  
    335 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.  
     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.  
    336333\item Declare the length of a character variable using the CHARACTER (len=xxx) syntax 
    337 \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). } 
     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). } 
    338335 
    339336\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.  
    340 \footnote {This allows a easy research of where and how a variable is declared using the unix command: Ògrep var *90 |grep !:Ó. } 
     337\footnote {This allows a easy research of where and how a variable is declared using the unix command: ``grep var *90 |grep !:''. } 
    341338\\ 
    342339For example: 
     
    349346 All subroutines and functions will include an IMPLICIT NONE statement.  
    350347Thus all variables must be explicitly typed. It also allows the compiler to detect typographical errors in variable names.  
    351 For modules, one IMPLICIT NONE statement in the modules definition section is needed.  
     348For 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. 
    352349Improper data initialisation is another common source of errors.  
    353350\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.}  
     
    364361\subsection{Headers} 
    365362Prologues are not used in NEMO for now, although it may become an interesting tool in combination with ProTeX auto documentation script in the future.  
    366 Rules to code the headers and layout of a module or a routine are illustrated in the example module available with the code : $NEMO/OPA\_SRC/module\_example$ 
     363Rules 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} 
    367364%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    368365\subsection{Interface blocks} 
     
    385382%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    386383\subsection{Precision} 
    387 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 size of INTEGER. It should be noted that constants need to have attached a \_kindvalue to have the according size. \\ 
    388 Thus wp being the "working precision" as declared in $OPA\_SRC/par\_kind.F90$, declaring real array $zpc$ will take the form: 
     384Parameterizations 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. \\ 
     385Thus $wp$ being the "working precision" as declared in $OPA\_SRC/par\_kind.F90$, declaring real array $zpc$ will take the form: 
    389386\begin{verbatim} 
    390387      REAL(wp), DIMENSION(jpi,jpj,jpk) ::  zpc      ! power consumption 
    391        \end{verbatim} 
     388\end{verbatim} 
    392389%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    393390\subsection{Structures} 
     
    404401 
    405402      TYPE(PTRACER) , DIMENSION(jptra) :: tracer 
    406  \end{verbatim} 
     403\end{verbatim} 
    407404  
    408405 Missing rule on structure name?? 
     
    412409%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    413410\subsection{Bounds checking} 
    414 NEMO is able to run when an array bounds checking option is enabled. \\ 
     411NEMO is able to run when an array bounds checking option is enabled (provided the cpp key $key\_vectopt\_loop$ is not defined). \\ 
    415412Thus, constructs of the  following form are disallowed:  
    416413\begin{verbatim} 
    417414REAL(wp) :: arr(1)  
    418  \end{verbatim} 
     415\end{verbatim} 
    419416where "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. 
    420417%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
     
    429426\subsection{Memory management} 
    430427 
    431 The main action is to identify and declare which arrays are PUBLIC and which are PRIVATE.\\ 
    432 Dynamic memory allocation should be avoided, unless necessary. Indeed, it may be desirable in some occasions. However, this type of memory allocation can reduce performance on some machines, and some debuggers may get confused when trying to diagnose the contents of such variables.  \\ 
    433  
    434 The preferable mechanism for dynamic memory allocation is automatic arrays, as opposed to $ALLOCATABLE$ or $POINTER$ arrays for which memory must be explicitly allocated and de-allocated. 
    435 \footnote {$POINTER$ and $ALLOCATE$ are widely used in AGRIF, and in the routine reading input files.} 
    436 An example of an automatic array is:  
     428The main action is to identify and declare which arrays are PUBLIC and 
     429which are PRIVATE.\\ As of version 3.3.1 of NEMO, the use of static 
     430arrays (size fixed at compile time) has been deprecated.  All module 
     431arrays are now declared ALLOCATABLE and allocated in either the 
     432$<$module\_name$>$\_alloc() or $<$module\_name$>$\_init() 
     433routines. The success or otherwise of each ALLOCATE must be checked 
     434using the $Stat=<integer\ variable>$ optional argument.\\ 
     435 
     436In addition to arrays contained within modules, many routines in NEMO 
     437require local, ``workspace'' arrays to hold the intermediate results 
     438of calculations. In previous versions of NEMO, these arrays were 
     439declared in such a way as to be automatically allocated on the stack 
     440when the routine was called.  An example of an automatic array is: 
    437441\begin{verbatim} 
    438442SUBROUTINE sub(n)  
     
    441445END SUBROUTINE sub  
    442446\end{verbatim} 
    443  
    444 Whereas the same example with $ALLOCATE$ is: 
    445 \begin{verbatim} 
    446 SUBROUTINE sub(n)  
    447    REAL, ALLOCATABLE :: a(:)  
    448    ALLOCATE(a(n))  
     447The downside of this approach is that the program will crash if it 
     448runs out of stack space and the reason for the crash might not be 
     449obvious to the user. 
     450 
     451Therefore, as of version 3.3.1, the use of automatic arrays is 
     452deprecated. Instead, a new module, ``wrk\_nemo,'' has been introduced 
     453which contains 1-,2-,3- and 4-dimensional workspace arrays for use in 
     454subroutines. These workspace arrays should be used in preference to 
     455declaring new, local (allocatable) arrays whenever possible. The only 
     456exceptions to this are when workspace arrays with lower bounds other 
     457than 1 and/or with extent(s) greater than those in the {\it wrk\_nemo} 
     458module are required.\\ 
     459 
     460The 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, 
     462second, third and fourth dimensions, respectively. The 1D arrays are 
     463allocated with extent MAX($jpi\times jpj, jpk\times jpj, jpi\times 
     464jpk$).\\ 
     465 
     466The REAL (KIND=$wp$) workspace arrays in {\it wrk\_nemo} are named 
     467e.g. $wrk\_1d\_1$, $wrk\_4d\_2$ etc. and should be accessed by USE'ing 
     468the {\it wrk\_nemo} module. Since these arrays are available to any 
     469routine, some care must be taken that a given workspace array is not 
     470already 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 
     473checks that the requested arrays are not already in use and then sets 
     474internal flags to show that they are now in use. The {\it 
     475  wrk\_not\_released()} routine un-sets those internal flags. A 
     476subroutine using this functionality for two, 3D workspace arrays named 
     477$zwrk1$ and $zwrk2$ will look something like: 
     478\begin{verbatim} 
     479SUBROUTINE sub() 
     480   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released  
     481   USE wrk_nemo, ONLY: zwrk1 => wrk_3d_5, zwrk2 => wrk_3d_6 
     482   ! 
     483   IF(wrk_in_use(3, 5,6)THEN 
     484      CALL ctl_stop('sub: requested workspace arrays unavailable.') 
     485      RETURN 
     486   END IF 
    449487   ...  
    450    DEALLOCATE(a) ...  
     488   ... 
     489   IF(wrk_not_released(3, 5,6)THEN 
     490      CALL ctl_stop('sub: failed to release workspace arrays.') 
     491   END IF 
     492   ! 
    451493END SUBROUTINE sub  
    452494\end{verbatim} 
     495The first argument to each of the utility routines is the 
     496dimensionality of the required workspace (1--4). Following this there 
     497must be one or more integers identifying which workspaces are to be 
     498used/released. 
     499Note that, in the interests of keeping the code as simple as possible, 
     500there is no use of POINTERs etc. in the {\it wrk\_nemo} 
     501module. Therefore it is the responsibility of the developer to ensure 
     502that the arguments to {\it wrk\_in\_use()} and {\it 
     503  wrk\_not\_released()} match the workspace arrays actually being used 
     504by the subroutine.\\ 
     505 
     506If a workspace array is required that has extent(s) less than those of 
     507the arrays in the {\it wrk\_nemo} module then the advantages of 
     508implicit loops and bounds checking may be retained by defining a 
     509pointer to a sub-array as follows: 
     510\begin{verbatim} 
     511SUBROUTINE sub() 
     512   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released  
     513   USE wrk_nemo, ONLY: wrk_3d_5 
     514   ! 
     515   REAL(wp), DIMENSION(:,:,:), POINTER :: zwrk1 
     516   ! 
     517   IF(wrk_in_use(3, 5)THEN 
     518      CALL ctl_stop('sub: requested workspace arrays unavailable.') 
     519      RETURN 
     520   END IF 
     521   ! 
     522   zwrk1 => wrk_3d_5(1:10,1:10,1:10) 
     523   ...  
     524END SUBROUTINE sub  
     525\end{verbatim} 
     526Here, instead of ``use associating'' the variable $zwrk1$ with the 
     527array $wrk\_3d\_5$ (as in the first example), it is explicitly 
     528declared as a pointer to a 3D array. It is then associated with a 
     529sub-array of $wrk\_3d\_5$ once the call to {\it wrk\_in\_use()} has 
     530completed successfully. Note that in F95 (to which NEMO conforms) it 
     531is not possible for either the upper or lower array bounds of the 
     532pointer object to differ from those of the target array.\\ 
     533 
     534In addition to the REAL (KIND=$wp$) workspace arrays, {\it wrk\_nemo} 
     535also contains 2D integer arrays and 2D REAL arrays with extent ($jpi$, 
     536$jpk$), {\it i.e.} $xz$. The utility routines for the integer 
     537workspaces are {\it iwrk\_in\_use()} and {\it iwrk\_not\_released()} 
     538while those for the $xz$ workspaces are {\it wrk\_in\_use\_xz()} 
     539and {\it wrk\_not\_released\_xz()}. 
     540 
     541Should a call to one of the {\it wrk\_in\_use()} family of utilities 
     542fail, an error message is printed along with a table showing which of 
     543the workspace arrays are currently in use. This should enable the 
     544developer to choose alternatives for use in the subroutine being 
     545worked on.\\ 
     546 
     547When compiling NEMO for production runs, the calls to {\it 
     548  wrk\_in\_use()}/{\it wrk\_not\_released()} can be reduced to stubs 
     549that just return $.$FALSE$.$ by setting the cpp key 
     550{\it key\_no\_workspace\_check}. These stubs may then be inlined (and 
     551thus effectively removed altogether) by setting appropriate compiler 
     552flags (e.g. ``-finline'' for the Intel compiler or ``-Q'' for the IBM 
     553compiler). 
    453554 
    454555 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
     
    464565%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    465566\subsection{Package attribute: $PRIVATE, PUBLIC, USE, ONLY$} 
    466 Modules 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.  
     567Module 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.  
    467568%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    468569\subsection {Parallelism: using MPI} 
    469 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$, and defining the number of subdomains in latitude and longitude. 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 $lib\_mpp.F90$) and should be tested. 
     570NEMO 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. 
    470571 
    471572%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    472573\section{Features to be avoided} 
    473574 
    474 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 user can be easily alerted of potential bugs when some appear in their new developments. ).  
     575The 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. ).  
    475576Below is a list of features to avoid: 
    476577\begin{itemize} 
Note: See TracChangeset for help on using the changeset viewer.