From 9f63ff24b680473f5f69cb84e4ea971a0f150fa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Riette?= <sebastien.riette@meteo.fr> Date: Mon, 4 Jul 2022 15:56:30 +0200 Subject: [PATCH] S. Riette 04/07/2022 Plugging doc and cleaning --- docs/Developer.md | 105 +++++++++++++++++++++++++++++++-------------- docs/Integrator.md | 18 ++++---- docs/Offline.md | 11 +++-- docs/PHYEX.md | 2 +- docs/Plugging.md | 73 +++++++++++++++---------------- docs/TODO | 6 +-- 6 files changed, 126 insertions(+), 89 deletions(-) diff --git a/docs/Developer.md b/docs/Developer.md index fe02b73cd..c63d54493 100644 --- a/docs/Developer.md +++ b/docs/Developer.md @@ -5,26 +5,29 @@ This document is intended for developers who want to contribute to the PHYEX package. Developer who is interested in plugging the physics in a new model can refere to the Plugging documentation. The topics covered are as follows: - - [Package organisation](#PACKAGE-ORGANISATION) - - [Code preparation](#CODE-PREPARATION) - - [Coding norms](#CODING-NORMS) - - [Pull requests](#PULL-REQUESTS) -This document is written using the markdown "language". With pandoc, it can be converted to HTML (pandoc \<filename\>.md -o \<filename\>.html) or PDF (pandoc \<filename\>.md -o \<filename\>.pdf). + - [Package organisation](#package-organisation) + - [Code preparation](#code-preparation) + - [Coding norms](#coding-norms) + - [Pull requests](#pull-requests) + +This document is written using the markdown "language". With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf). # PACKAGE ORGANISATION The package contains the folowing directories: - - docs: for documentation - - build: an autonomous build system is included in the package. Its usage is covered in the Offline documentation - - src/common: the main source code which is the basis for all models - - src/\<model\>: the source code specific to one model that must replace source code found in the common directory + + - docs: for documentation + - build: an autonomous build system is included in the package. Its usage is covered in the Offline documentation + - src/common: the main source code which is the basis for all models + - src/\<model\>: the source code specific to one model that must replace source code found in the common directory In addition to this organisation, the package uses git branches. The main branches are as follows: - - main: source code without rewriting for GPU transformation (used for official Meso-NH source code) - - GPU: source code adapted for GPU transformations (used for official AROME source code, starting from the 48t3 cycle) - - arome\_\<commit\>: source code ready for inclusion in the AROME compilation environment (the generation of such a branch is described in [Code preparation](#CODE-PREPARATION)) - - testprogs\_data: modified source code used to generate samples for the test programs (more on this topic in the Offline documentation) + + - main: source code without rewriting for GPU transformation (used for official Meso-NH source code) + - GPU: source code adapted for GPU transformations (used for official AROME source code, starting from the 48t3 cycle) + - arome\_\<commit\>: source code ready for inclusion in the AROME compilation environment (the generation of such a branch is described in [Code preparation](#CODE-PREPARATION)) + - testprogs\_data: modified source code used to generate samples for the test programs (more on this topic in the Offline documentation) # CODE PREPARATION @@ -45,10 +48,11 @@ Installation and usage of the preprocessing tools are described in the PHYEX\_to The fortran file names use a capital F letter (eg: foo.F90) except if working a branch (mesonh\_\<commit\>) or in the folder (src/mesonh) specifci to the Meso-NH model. Names for the module: - - modd\_ for module containing only variable declaration (eg: tuning parameters) - - modi\_ for module containing only interface declaration - - modn\_ for namelist declaration - - mode\_ for module containing executable source code (subroutine or function) + + - modd\_ for module containing only variable declaration (eg: tuning parameters) + - modi\_ for module containing only interface declaration + - modn\_ for namelist declaration + - mode\_ for module containing executable source code (subroutine or function) ## When using mode\_ or modi\_? When writing a new subroutine, should we put it in a module (in a mode\_ file) or should we write the subroutine in a file and write the interface bloc in another file (modi\_ file)? @@ -58,14 +62,16 @@ The idea behind is to break compilation dependency at the parameterisation level ## Norm Several constraints are imposed: - - The code must be written with up to 132 characters per line. - - CODE IS IN CAPITAL LETTERS! comments in small letters - - All variables must be declared: IMPLICIT NONE - - except in rare cases, use automatic arrays, no allocatable - - dimensions of dummy argument arrays are explicit (no (:,:)) - - use parenthesis when manipulating arrays (eg: A(:,:)=B(:,:)+C(:,:) instead of A=B+C) + + - The code must be written with up to 132 characters per line. + - CODE IS IN CAPITAL LETTERS! comments in small letters + - All variables must be declared: IMPLICIT NONE + - except in rare cases, use automatic arrays, no allocatable + - dimensions of dummy argument arrays are explicit (no (:,:)) + - use parenthesis when manipulating arrays (eg: A(:,:)=B(:,:)+C(:,:) instead of A=B+C) The variables are named according to the doctor norm: + |Type / Status | INTEGER | REAL | LOGICAL | CHARACTER | TYPE | |--------------|------------|------------|-------------|----------------|------------------| |Global | N | X | L (not LP) | C | T (not TP,TS,TZ) | @@ -75,20 +81,55 @@ The variables are named according to the doctor norm: Regarding array-syntax, code is written using array-syntax in the main branch and in mesonh specific branches based on the GPU branch, using array-syntax with mnh\_expand directives in the GPU branch, using DO loops in arome specific branches based on the GPU branch. If in doublt, check what is done in other routines in the brach you are working in. Be carrefull when using the mnh\_expand directives, code must respect some constraints: - - parenthesis after array variables are mandatory (no A=B+C, but A(:,:)=B(:,:)+C(:,:)) - - no space between array variables and the opening parenthesis (no A (:)=B (:), but A(:)=B(:)) - - same bounds as declared in the mnh\_expand directive should be used in the array-syntax (A(D%NIB;D%NIE)=...) + + - parenthesis after array variables are mandatory (no A=B+C, but A(:,:)=B(:,:)+C(:,:)) + - no space between array variables and the opening parenthesis (no A (:)=B (:), but A(:)=B(:)) + - same bounds as declared in the mnh\_expand directive should be used in the array-syntax (A(D%NIB;D%NIE)=...) + A tool (verify\_mnh\_expand.py) can help at checking the validity of the written code. For the GPU branch (and branches on GPU, including model specific branches): - - except variables declared with the PARAMETER attribute, no variable from modules can be used in the physics. Varaibles must be put in a type received by interface. - - subroutines or functions must not be called from within a loop on horizontal or vertical dimensions (see below for exception) - - functions returning arrays must be rewritten as subroutine + + - except variables declared with the PARAMETER attribute, no variable from modules can be used in the physics. Varaibles must be put in a type received by interface. + - subroutines or functions must not be called from within a loop on horizontal or vertical dimensions (see below for exception) + - functions returning arrays must be rewritten as subroutine Call to external subroutine in loop on horizontal or vertical dimensions must be suppressed in the GPU version. If possible, the call must be put outside of the loop (acting on the full array as a whole) or the subroutine must be put in the CONTAINS part but, in this case, the included subroutine cannot use local array. There are 3 cases: - - the subroutine does't use local array: subroutine is put in an include file (with the .h extension) and included with the fortran INCLUDE statement. - - the subroutine use local arrays but it is called from only one place in the code: the source code of the subroutine is moved (no INCLUDE) in the CONTAINS part and the array declarations are moved in the main subroutine. - - the subroutine use local arrays and is called from several places: the previous technique is not recommended. The source code is put in an include file (with the .h extension) and an extra argument is provided to the subroutine and is used as a buffer so there is no more need to declare local arrays in the called subroutine. + + - the subroutine does't use local array: subroutine is put in an include file (with the .h extension) and included with the fortran INCLUDE statement. + - the subroutine use local arrays but it is called from only one place in the code: the source code of the subroutine is moved (no INCLUDE) in the CONTAINS part and the array declarations are moved in the main subroutine. + - the subroutine use local arrays and is called from several places: the previous technique is not recommended. The source code is put in an include file (with the .h extension) and an extra argument is provided to the subroutine and is used as a buffer so there is no more need to declare local arrays in the called subroutine. + +## Budgets + +In Meso-NH, the budget can be used in two ways: + + - by giving to the budget machinery the tendency due to a given process + - by giving to the budget machinery the total tendency (S variable) before and after a given process. The budget machanism recomputes by difference the tendency only due to the given process. + +In AROME, we cannot provide the total tendency (S variable) before the process. This total tendency is stored internally by the machinery but cannot be set to a different value before doing a computation. + +The physics package must be usable from AROME and Meso-NH, several examples are given: + +Invalid for AROME: +``` +budget_store_init(tempo_s) +modification of tempo_s +budget_store_end(tempo_s) +``` + +Valid: +``` +budget_store_init(pronostic_s) #useless for AROME, but needed for Meso-NH +modification of pronostic_s +budget_store_end(pronostic_s) +``` + +Valid: +``` +computation of delta tempo_s +budget_store_add(delta tempo_s) +``` # PULL REQUESTS This section deals with the pull request procedure from the developer point of view. The integrator point of view is described in the Intergator documentation. diff --git a/docs/Integrator.md b/docs/Integrator.md index dbdbcebf2..6bceda0be 100644 --- a/docs/Integrator.md +++ b/docs/Integrator.md @@ -4,15 +4,16 @@ This document is intended for integrators who are in charge of assembling contributions received through pull requests. -his document is written using the markdown "language". With pandoc, it can be converted to HTML (pandoc \<filename\>.md -o \<filename\>.html) or PDF (pandoc \<filename\>.md -o \<filename\>.pdf). +This document is written using the markdown "language". With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf). # BRANCHES AND NORMS Regarding array-syntax, the applicalble norm depends on the branch: - - The main branch of PHYEX (and all branches based on main) is written using array-syntax - - The GPU branch is written using array-syntax with mnh\_expand directives - - arome specific branches based on the GPU branch are written using DO loops - - mesonh specific branches based on the GPU branch are written using array-syntax withour mnh\_expand directives + + - The main branch of PHYEX (and all branches based on main) is written using array-syntax + - The GPU branch is written using array-syntax with mnh\_expand directives + - arome specific branches based on the GPU branch are written using DO loops + - mesonh specific branches based on the GPU branch are written using array-syntax withour mnh\_expand directives Pull requests can be received on all these kind of branches and must be merged into the main or the GPU branch with according norm. @@ -21,7 +22,8 @@ Pull requests can be received on all these kind of branches and must be merged i The source code must follow strict mnh\_expand directives (described in the Developer documentation). The script verify\_mnh\_expand.py must be used to give an additional check. In addition to the scientific validation, the folowing tests must give the same results (with bit-reproducibility) in each of the model: - - compilation transforming the mnh\_expand directives in DO loop - - compilation keeping the array-syntax - - execution with a different umber of processors + + - compilation transforming the mnh\_expand directives in DO loop + - compilation keeping the array-syntax + - execution with a different umber of processors diff --git a/docs/Offline.md b/docs/Offline.md index 4ba670b04..0c190f4d9 100644 --- a/docs/Offline.md +++ b/docs/Offline.md @@ -5,12 +5,15 @@ This document is intended for persons who want to use PHYEX in an offline mode. Some offline test programs are provided with the package and a library suitable for use with python is also available. +This document is written using the markdown "language". With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf). + # COMPILATION The build/with\_fcm directory contains a build system. This build system has two dependencies (installation is done automatically by the compilation script): - - [fcm](https://metomi.github.io/fcm/doc/user_guide/) - - [fiat](https://github.com/ecmwf-ifs/fiat) + + - [fcm](https://metomi.github.io/fcm/doc/user_guide/) + - [fiat](https://github.com/ecmwf-ifs/fiat) The script build/with\_fcm/make\_fcm.sh uses a configuration file and build the library and test programs. They can be found in the build/bin sudirectory in the architecture specific directory arch\_\<achitecture name\>. @@ -39,7 +42,7 @@ In addition, these data files can be used through the check\_commit\_testprogs.s # PYTHON BINDING -This section must be written. Key ideas are: +**TODO** This section must be written. Key ideas are: + - ctypesforfortran - example -- diff --git a/docs/PHYEX.md b/docs/PHYEX.md index 965b408e3..24b101e88 100644 --- a/docs/PHYEX.md +++ b/docs/PHYEX.md @@ -10,7 +10,7 @@ More specific documentation can be found: - Offline: how to compile the library and the test programs, how to use the library with python, how to use the test programs - Plugging : how to plug the physics package in a model -This document is written using the markdown "language". With pandoc, it can be converted to HTML (pandoc \<filename\>.md -o \<filename\>.html) or PDF (pandoc \<filename\>.md -o \<filename\>.pdf). +This document is written using the markdown "language". With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf). # HISTORY diff --git a/docs/Plugging.md b/docs/Plugging.md index ca83b6f5f..c863e6a63 100644 --- a/docs/Plugging.md +++ b/docs/Plugging.md @@ -1,40 +1,35 @@ -This document must still be written - -Some elements to include (or not): - -The PHYEX parameterizations can be called from different models (eg. Meso-NH, AROME) and from -a driver (which will be included in this repository). -Moreover, PHYEX parameterizations call externals subroutines, which are dependencies. - -This document aims at listing the interfaces to call the PHYEX parameterizations and the -interfaces of the external modules called by PHYEX. - -PHYEX interfaces: -- lima_adjust -- ice_adjust -- shallow_mf -- turb -- lima, lima_warm, lima_cold et lima_mixed -- rain_ice, rain_ice_old -- ini_... - -Dependencies: -- mode_budget -- mode_msg, modd_io -- modd_precision -- yomhook, parkind1 - -Specificities: -- in AROME, BUDGET_SORE_INIT does nothing: it is impossible to compute a tendencie - from the difference of a temporary variable. - Invalid: - budget_store_init(tempo_s) - modification of tempo_s - budget_store_end(tempo_s) - Valid: - budget_store_init(pronostic_s) #useless but valid - modification of pronostic_s - budget_store_end(pronostic_s) - Also valid: - budget_store_add(delta tempo_s) +# PHYEX plugging documentation + +# ABOUT THIS DOCUMENT + +The PHYEX parameterizations can be called from the Meso-NH and AROME models, from +test programs and from a driver. +This document is intended for developers who want to plug in the physics in a new model or program. + +This document is written using the markdown "language". With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf). + +# INTERFACES + +The folowing routines are identified as the interface of the physics: + + - lima\_adjust + - ice\_adjust + - shallow\_mf + - turb + - lima, lima\_warm, lima\_cold and lima\_mixed + - rain\_ice, rain\_ice\_old + - ini\_\* **TODO: list the different ini subroutine needed** + +This interface is declared in the corresponding modi\_\* files. + +# HOOKS + +The code provided in the common directory is independent, it can be compiled and used without +dependency except the [fiat package](https://github.com/ecmwf-ifs/fiat). +For more interaction with the hosting model, some subroutine can receive a specific implementation. +The following codes already have specific implementations for the Meso-NH and AROME models and are therefore +quite likely to receive a new implementation before plugging into another host model. + + - mode\_budget: to store and/or compute statistics on variable tendencies + - mode\_msg: to print messages and abort on error diff --git a/docs/TODO b/docs/TODO index 61d834181..44845966d 100644 --- a/docs/TODO +++ b/docs/TODO @@ -3,11 +3,7 @@ Une solution serait de créer un module propre à PHYEX qui contiendrait des cl pour la physique. Ce module serait initialisé dans Méso-NH à partir de clés actuellement en dehors de la physique. -Dependencies: - - définir les interfaces propres - - créer des codes pour le driver - - liste dans document Interfaces - - pour AROME placés, en attendant, dans phyex/externals +Documentation: search for the TODO keys in the *.md files of the docs directory Clé de compilation REPRO48 + REPRO55 ajoutées pour permettre de reproduire le cycle 48 MNH-5.5.0, elles: - contournent des corrections de bug -- GitLab