Changes between Version 41 and Version 42 of FpCtbtoOverview

Timestamp:

Dec 5, 2017, 9:22:29 AM (6 years ago)

Author:

dearn

Comment:

--

FpCtbtoOverview

@@ -181 +181 @@
 * The original code included two modules, ''ecmwf_mod.f90'' and ''gfs_mod.f90''. Those have now been erased and the variables brought back to the ''par_mod.f90'' file. This has been done with NILU's agreement.
   
+
+=== Vtables ===
+
+One of the main structural modifications is to modify the routines that read the meteorological input data from the GRIB files so that all the variable references are made to names of the corresponding meteorological fields rather than a combination of GRIB parameter codes. In order to do this, we have borrowed the approach from the NWP model WRF (Weather Research and Forecasting model) whereby a Variable Table (Vtable) provides the mapping between the FLEXPART meteorological field names (e.g.. TT, U, U10, …) and the respective GRIB codes. Vtables for ECMWF and GFS data are provided inside the Vtables directory in the usual options directory. The layout of the Vtables is such as:  
+
+
+{{{
+GRIB1 | Level| flexpart | flexpart | flexpart               |GRIB2|GRIB2|GRIB2|GRIB2|
+Param | Type | Name     | Units    | Description            |Discp|Catgy|Param|Level|
+------+------+----------+----------+------------------------+-----------------------+
+ 130  | 109  | TT       | K        | Temperature            |  0  |  0  |  0  | 105 |
+ 131  | 109  | UU       | m s-1    | U                      |  0  |  2  |  2  | 105 |
+ 132  | 109  | VV       | m s-1    | V                      |  0  |  2  |  3  | 105 |
+ 133  | 109  | QV       | kg kg-1  | Specific humidity      |  0  |  1  |  0  | 105 |
+ 134  | 1    | PS       | Pa       | Surface pressure       |  0  |  3  |  0  |  1  |
+ 135  | 109  | ETADOT   | Pa s-1   | Vertical velocity      |  0  |  2  |  32 | 105 |
+ 141  | 1    | SD       | m        | Snow depth             |  0  |  1  |  11 |  1  |
+ 151  | 1    | MSL      | Pa       | Sea-level Pressure     |  0  |  3  |  0  | 101 |
+ 164  | 1    | TCC      | (0-1)    | Total cloud cover      | 192 | 128 | 164 |  1  |
+ 165  | 1    | U10      | m s-1    | 10m U                  |  0  |  2  |  2  | 103 |
+ 166  | 1    | V10      | m s-1    | 10m V                  |  0  |  2  |  3  | 103 |
+ 167  | 1    | T2       | K        | 2m Temperature         |  0  |  0  |  0  | 103 |
+ 168  | 1    | TD2      | K        | 2m Dewpoint            |  0  |  0  |  6  | 103 |
+
+…
+
+ 172  | 1    | LSM      | 0/1 Flag | Land/Sea flag          |  2  |  0  |  0  |  1  |
+ 246  | 1    | CLWC     | kg kg-1  | Spec. cld liq water    |  0  |  1  |  83 | 103 |
+ 247  | 1    | CIWC     | kg kg-1  | Spec. cld ice water    |  0  |  1  |  84 | 103 |
+201031| 1    | QC       | kg kg-1  | Spec. cld water cont.  |  0  | 201 |  31 | 105 |
+------+------+----------+----------+------------------------+-----------------------+
+
+}}}
+
+
+In order to use the Vtables, the routines that read the meteorological data (gridcheck and readwind) are modified and, the structures like: 
+
+
+{{{
+if(isec1(6).eq.131) uuh(i,j,nlev_ec-k+2)= &!! U VELOCITY
+zsec4(nxfield*(ny-j-1)+i+1)
+}}}
+
+
+Are now modified to simply call the actual variable name: 
+
+
+{{{
+.
+ELSE IF(TRIM(fpname) .EQ. 'UU') THEN
+    iumax=max(iumax,nlev_ec-k+1)
+        DO j=0,nymin1
+            DO i=0,nxfield-1
+                uuh(i,j,nlev_ec-k+2) = zsec4(nxfield*(ny-j-1)+i+1)
+            END DO
+        END DO
+}}}
+
+This has required the generation of an additional library, provided with the code, that handles the conversion from variable names to corresponding GRIB parameters. The library is provided in ''src/gributils/class_vtable_mod.f90'' . This library handles as well the  GRIB2 to GRIB1 conversions of parameters. 
+
+The benefits of this approach are:
+
+* The code itself is more understandable and not dependent on specific GRIB parameter
+values
+* Users can experiment with new sources of met fields by creating a new Vtable, mapping
+to the new GRIB parameters, without the need to modify code
+
+This approach, however, adds a level of indirection to the code (a table lookup) that has been compensated by restructuring the code and rearranging the loops in readwind, leading to even better performance in comparison with the original code. 
+
+From the user perspective, the only difference is that a link to the correct Vtable has to be done in the run directory (where pathnames sits)
+
+The code has been tested against our testing environment showing zero differences for the test cases. 
+
+In order to implement and deploy the Vtable approach, the following main modifications/additions  have been carried out:
+
+* Creation of an independent ''gributils/class_Vtable_mod.f90'' to abstract all the operations of using the Vtables and matching GRIB file parameter codes to the appropriate Vtable entry. Gributils is provided inside ''src/''
+* Modification of the code in the following source files that deal directly with GRIB parameter codes - ''gridcheck_ecmwf.f90'', ''readwind_ecmwf.f90'', ''gridcheck_nests.f90'', and ''readwind_nests.f90'' . These modifications include:
+    *  Added code that initializes a Vtable object
+    *  Added code that used Vtable object routines to determine the fpname (e.g. UU,T2, CONVPREC , etc.) of a GRIB message
+    *  Modified code to look for a specific fpname rather than specific GRIB parameters
+
+=== Testing environment ===
+
+A new and independent top-level directory, ''ctbto-testing-env'' was added to the directory tree.  This directory contains the following: 
+
+ * '''case_data''': this directory includes the different test cases used in the testing environment, with the corresponding tree structure and control data. The cases are organised first according to the meteorological type of data (e.g. ''ecmwf_02hr_1p0deg'') and then, several cases underneath depending on the type of FLEXPART run with this data (eg. ''case_ecmwf_02hr_1p0deg_1species_1emission_bwd'', ''case_ecmwf_02hr_1p0deg_1species_1emission_fwd''). In each of the case directories, the user finds the control output (the output the testing environment will test against), the rundir_template directory (with the right options, pathnames and Vtable) and the par_mod file. 
+ * '''check''': this directory contains all the high level routines to control the tests and includes the files the user should invoke to use the testing environment. The test driver, *check.py* is a Python program that expects an XML file as an argument, then creates a *TestSuite* consisting of all the components needed and performs all the compilations, simulations and testing. XML files for the case data are provided. In addition, ''run_selected_cases.py'' adds the possibility to run multiple cases defined in a text file (-lst) and multi_configtest.py calls in the ''run_selected_cases.py'' but using different makefiles provided as well by the user. How the code is executed is provided through the help function.
+ * '''distrotest''': includes all the routines that prepares all the information and populate the directories to perform the testing
+ * '''doc''': documentation for this environment is in the ''ctbto-testing-env/doc/'' directory, in Markdown format. With appropriate Markdown Extension, pointing the browser to ''ctbto-testing-env/doc/Overview.md'' should provide a usable browsing of the  documentation. 
+ * '''flextest''': lower level components for compiling, running, and evaluating FLEXPART output. These provide low level access routines for running FLEXPART programs, as well as numerous tools for accessing, evaluating and comparing FLEXPART outputs.
+ * '''metfetch''': the testing environment requires to have meteorological data to drive the test cases. metfetch automatically gets the NCEP data and prompts information on restricted ECMWF data. 
+ * '''test''': set of unit tests for the testing environment development
+ * '''utilities''': includes examples of additional output one could obtain from the testing environment.
+ * '''distropath''': link to where the source code to run the testing environment is located. 
+
+Apart from the documentation inside the testing environment itself, an updated version is kept in: 
+​http://borealscicomp.com/CTBTO_FLEXPART/WO17/ctbto_testenv_docs/Overview.md
+
+The testing environment includes control case data using the original NILU code for serial tests but with the modifications in the header . For the MPI control data, the new version with the modifications detailed below, has been used to create it
+
+
+