User Guide for the MATCH stand alone Module of RODOS-PV 5.0 Lennart Robertson USER GUIDE FOR THE MATCH STAND ALONE MODULE OF RODOS-PV 5.0 1 1 Overview 2 1.1 Resource files 3 1.2 File input and output 3 1.2.1 Fixed data files 3 1.2.2 Log File 4 1.2.3 Input weather data in GRIB format 4 1.2.4 Output data in GRIB format 6 2 Starting the stand-alone module 8 2.1 Before the run 8 2.2 Starting the long range atmospheric dispersion module MATCH 8 2.3 Archived runs 12 3 Initialization Windows for standalone MATCH 15 3.1 Overview 15 3.2 Description 16 3.2.1 Source 1 17 3.2.2 Source 2 (optional) 19 3.2.3 Source 3 (optional) 19 3.2.4 Source 4 (optional) 19 3.2.5 Nuclides (Switch on/off nuclides in the source term(s)) 20 3.2.6 End date of the calculations (Optional) 21 3.2.7 Output Selection 22 3.2.8 Graphics on/off 23 3.2.9 Grid for presentation in RoGIS 24 3.2.10 Path weather data 25 3.2.11 Select subarea in weather data 26 4 Results and Data Output 27 4.1 Output to the Graphics system 27 4.1.1 Possible results 27 4.2 Interface data 29 4.2.1 MATCH - FDMT interface 29 5 Error Correction Procedures 30 5.1 Trouble shouting 31 Document History 33-1 -
1 Overview MATCH (Multi-scale Atmospheric Transport and CHemistry model) is the long-range transport model in the system. The model operates on the European scale and calculates activity and depositions of a selected number of nuclides. A necessary requirement is access to numerical weather prediction (NWP) data e.g. HIRLAM or ALADIN. There are five different installations of MATCH, however, this user guide refers only to the stand alone version MATCH. MATCH, a stand-alone version where the source input is described in a simple fashion by the user, MATCH/LSMC a model chain version where the source input is taken from a local or meso-scale dispersion model. INT-MA-FDM, an interface part to the food chain model (FDMT), where the output from either MATCH or RMATCH are post processed to fit into FDMT. MATCHVIEW is provided in order to redisplay the model results in RoGIS as model results are not stored in the RODOS data base, but in a more obscure packed format (WMO GRIB standard) MATCH is an all purpose model developed with the objective to cover a range of atmospheric transport problems from the meso to the continental scale and for application like accidental releases, acidic deposition and photo-chemical oxidant generation. Accidental releases requires high degree of details in the description of the transport and dispersion. To this end a Lagrangian particle model is used for the initial phase of the release. Of special concern is that MATCH operates on an entirely different model area than most of other application in RODOS. The output from MATCH in terms of activity and deposition are not stored directly into the data base and therefor not directly available for other applications. The module PMatch98 is developed with the purpose to extract MATCH results for any desired area that conforms with standard and the result for a such domain is subsequently archived in the data base. For the same reasons MATCH results can not be redisplayed by just activating the data base. Again a special module, MATCHVIEW, is developed to meet such a requirement. The purpose of MATCH in is RODOS to describe the transport and fallout of radio-nuclides on the European scale. To keep the computation load on a - 2 -
reasonable level as small subset of important nuclides are selected, namely Cs137, I131, Ba140, Xe133 and Kr85. 1.1 Resource files The resource files are used to integrate MATCH in the RODOS system. The following files are of interest to the standalone MATCH. MATCH_define MATCH_assign MATCH_load Definition of the MATCH modules and shared memory Assignment of default values Load instructions 1.2 File input and output File input is in ASCII and in GRIdded Binary (GRIB) format. The latter is the format for input weather data and output from MATCH (see http://www.wmo.ch/web/www/reports/guide-binary.html for details). The input ASCII files are fixed files with setup parameters. 1.2.1 Fixed data files A set of fixed data files for model setup are located in ~/roextern/data/match/scripts. The purpose of each file is described in the table below. NameList General parameter setup Output.dat Description of output parameters Nuclides.dat Description of usable nuclides Ba-140 Parameters for Ba-140 Cs-137 Parameters for Cs-137 I-131 Parameters for I-131 Kr-85 Parameters for Kr-85 Xe-133 Parameters for Xe-133-3 -
Inert ListResults ListDates Parameters for any inert species Help script for listing stored MATCH data Help script for listing stored MATCH data 1.2.2 Log File A log-file is generated with rather extensive output. The file is found in ~/roextern/outall/"user"/"runid/ and named Match.log. 1.2.3 Input weather data in GRIB format The weather data should be always located in the directory ~/romet/provider/eu/yyyymmddhhmm00 During runtime of MATCH weather data are delivered to the directory ~/romess/user/provider/ The system task ronetservice delivers the weather data after MATCH sends a request for a specified releasetime. to ronetservice. Input weather data are supposed to come in the so called GRIB file format and divided into files with weather information for one time-stamp in each file. The data has to be retrieved from a numerical weather prediction model, like HIRLAM, ALADIN etc. The file name is constructed by a prefix and a time-stamp, e.g. DMI9907080012, with format PREFIXyymmddhhll, where yy is the year, mm is the month, dd is the day, hh is the hour, and ll is the forecast length. All dates are in UTC time. An analysis is marked by forecast length zero (ll=00). Obviously can several time-stamps denote the same date. So are e.g. 9907080000 the same date as 9907071806 and 9907071212. Weather data should be available at a minimum of three days backwards, but preferably one or two weeks. Only the latest full forecast is needed (normally a 48 hour forecast). The rest of the forecasted data are all covered by analyses and can be removed. However, MATCH still needs the 3 and 6 hour forecasts that contain precipitation information and for filling the gap between analyses that normally are given for every 6 hour. The content required for each data file is listed below. The numbers are the internal GRIB representation of parameters given by the WMO standard. Single level fields PAR TYPE LEV - 4 -
6 105 0 Geopotential Height of the model surface 1 105 0 Pressure at model surface 11 102 0 Sea surface temperature 11 105 0 Temperature at the surface 11 105 2 Temperature at 2m 51 105 2 Specific Humidity at 2m 33 105 10 U-component of Wind at 10m 34 105 10 V-component of Wind at 10m 91 102 0 Ice Concentration 81 105 0 Land Sea Mask 84 105 0 Albedo 83 102 0 Surface Roughness (dynamic) 83 105 0 Surface Roughness (fixed) 122 105 0 Sensible heat flux 121 105 0 Latent heat flux 128 105 0 Friction velocity 62 105 0 Large Scale Precipitation 63 105 0 Convective Precipitation 67 105 0 Mixing layer depth (optional) Multi layer fields PAR TYPE LEV 33 109 # U-componemt of Wind 34 109 # V-component of Wind 11 109 # Temperature 51 109 # Specific Humidity where # is the model level number. It is important that the layers are true model layers and not standard pressure levels. Not all layers that could be retrieved from any numerical weather prediction model are necessary to include, even though it is desirable. You have to be sure though that at least the lowest 5 km of the atmosphere is covered. Note that numerical weather prediction models normally have pressure as vertical co-ordinate that makes the earth surface as the model "top". - 5 -
1.2.4 Output data in GRIB format The output from the MATCH model is stored in GRIB format in the directory ~/roextern/outall//"user"/"runid"/ The naming of the files are NUCLIDE_match_yyyymmddhhmi00, where yyyy is the year, mm is the month, dd is the day, hh is the hour, and mi is the minute. If every possible parameter is selected for output (see section 3.2.7) the output listed below can be found. The numbers refer to internal GRIB representation of parameters, and are necessary for retrieval. Single level fields PAR TYPE LEV Description 243 105 0 Concentration Mean 243 105 1 Concentration 1 Hour 240 105 0 Dose Mean 251 105 0 Acc. Total Deposition 250 105 0 Acc. Wet Deposition 67 105 0 Boundary layer height 122 105 0 Sensible heat flux 61 105 403 Total Precipitation 111 105 0 Net solar radiation 33 105 10 U-wind at 10m 34 105 10 V-wind at 10m 11 105 2 Temperature at 2m 51 105 2 Specific humidity at 2m 130 105 0 Atmospheric resistance Multi layer fields PAR TYPE LEV Description 243 109 # Concentration 33 109 # U-componemt of Wind 34 109 # V-component of Wind - 6 -
where # is the MATCH model layer that ranges between 1 and 5 where 1 is the layer closest to the earth surface. - 7 -
2 Starting the stand-alone module 2.1 Before the run One has to assure that prognostic weather data for the period requested by the MATCH module are available. You may check for the default path to weather data, see section 3.2.9. Some features of the standalone MATCH that may be of interest. Just a limited number of nuclides could be selected. The simulation starts with the start date of the first source. Default a 48 hour simulation will be performed. A specific stop date may be specified. Model results are not stored in the RODOS database but in a file format GRIB. The module INT-MA-FDMT may be used to transform the MATCH output for storage in the RODOS database. Results may be forwarded to RoGIS graphical system for just on-the-fly inspection of the model run. Reviewing the results are made by MATCHVIEW. 2.2 Starting the long range atmospheric dispersion module MATCH An interactive computation run of the stand-alone version of MATCH is started in the following way: In the Main Dialogue window of RODOS select the button [Interactive]. Then the following window pops up. - 8 -
Click on the button [MATCH] in the Interactive Manager window to start a new run of MATCH. A Start window for the definition of the RunId pops up, the RunId has to be entered by the user. The RunID can be any character string using letters and numbers (maximum 12 characters) and must be different from the RunIDs of previous runs which are still in the data base. By selecting [Initializing] in the window, Initialization windows can be opened which enable the selection of input parameter for MATCH. The windows are described in detail in chapter 3. When returning from the Initialization windows a window Program Initialization appears: - 9 -
Now, three options are available: To apply the selection made in the Initialization windows before click on [Apply] and then [Return]. To make new selections in the Initialization windows click on [unlock buttons] and then [MATCH] again. To start the program with the preset selections click on [Return]. The Initialization windows should be called in any case, as important parameters such as the source strength and duration of release have to be set. If no initialization via the Initialization windows is done, the program run is started with the preset selections (as described in section 3); however, this option is only recommended when runs have been performed in the past and no changes are requested. The program run is started by clicking on [Start] in the Start window. To enable the graphics output of MATCH, the Graphics System of RODOS has to be started before MATCH is started by selecting the button [Graphics] in the Main Dialogue window of RODOS. After the program has been started, a Control & Services window appears. This control window is divided into an upper and lower part. The upper part contains the RunID of the currently selected run as well as four buttons to control the runs. The lower part contains five buttons with which various services can be chosen. Both types of buttons are described in detail in the User Guide for the Graphical System. The only button in the lower part which is of interest for MATCH is the button: - 10 -
[Process Status] Selecting this service opens a window with the list of all modules of the selected run and their actual state. The colour coding of the modules indicates whether the module has not yet started (blue), data is loaded from the database (yellow), the module is calculating (green), the results are archived in the database (red) or the module has finished its work (grey). - 11 -
2.3 Archived runs Archived graphical output of MATCH can be displayed by selecting [File] and further [Display Results] in the menu bar of the Interactive Manager window of RODOS. Thereafter, a windows pops up with the program groups where a run can be selected. In the Program Groups window the requested MATCH button has to be selected. By pressing the button [MATCH], a window pops up with the list of all MATCH runs archived. - 12 -
One run out of the list has to be selected and the button [Apply] has to be pressed. Thereafter, two windows appear: The Control & Services window (see above) and the Application List window. The next step is first to select the run in the Application List window by simply clicking on it (colour does not change), and in second to select the [Graphics] button in the Control & Services window. Thereafter, a window with the list of results archived for this run is displayed. - 13 -
In this window either individual results can be selected by clicking through the context menu up to a result which is marked with a red cross. This can be selected by pressing the [Apply] button. Or it is also possible to select all results by pressing first the [All] button and thereafter the [Apply] button. The [Close] button can be selected if no further result is requested. A second option is to select the program MATCHVIEW to display the graphical results in a continuos loop in the graphics system. The Graphics System of RODOS has to be started beforehand. This module is described in a separate user guide (or chapter). - 14 -
3 Initialization Windows for standalone MATCH 3.1 Overview By selecting [Initializing] in the Start window (see previous Chapter) the Initialization windows can be used to select the requested input and also the output which has to be produced by MATCH. The window hierarchy is shown below (WINDOWS, Options): MATCH stand alone input +- Source 1 +- Position +- Emission +- Start time (Note! This is the start date of the simulation) +- Stop time +- Emission height +- Source 2 (optional) +- Position +- Emission +- Start time +- Stop time +- Emission height +- Source 3 (optional) +- Position +- Emission +- Start time +- Stop time +- Emission height +- Source 4 (optional) +- Position +- Emission +- Start time +- Stop time +- Emission height +- Nuclides (switch on/off nuclides in the source term(s) +- Nuclides +- End date of calculation (optional) +- End date (Note! This is the end date of the simulation) +- Output parameter +- Output selection for graphical display +- Graphics on/off +- Send results to graphics +- Grid for presentation in RoGIS +- West-East extension +- South-North extension +- Path to weather data +- Path +- Generator +- Select subarea in weather data +- Indices of rows and columns omitted - 15 -
3.2 Description By selecting [Initializing] in the Start window (see Chapter 2) and then selecting [MATCH] in the following Program Initialization window the Dataset Selection window comes up. This window switches between modification of either the data from the previous initialization, or the data from another initialization made earlier. After pressing the appropriate button, the Initialization windows are called to define parameter values to be used by the MATCH calculations. In various sub-windows the input parameters requested by MATCH can be filled in. These sub-windows can be accessed by clicking on one of the main topics in the main Initialization Window (MATCH: MATCH stand alone input) which appears. - 16 -
Selecting the button [Close] stores the selection and closes the window, the button [Help] opens a help window including some comments for this main menu. For all windows exist default settings which are activated by having selected [default] in the Option menu of the Interactive Manager window. However, modifications from previous runs will be active independent of the selection temporary and default. This is special to MATCH and does not correspond to the description of these options in the system manual. 3.2.1 Source 1 Choosing [Source 1] brings up the following window in which the mandatory input for one run has to be filled in. The standalone version of MATCH requires at least input for one of the four sources: Input window for Source 1 continued - 17 -
Position: Specify the latitude and longitude of the source point in degrees. Emission: Set a constant source term. Only those nuclides that are switch on will be considered in the calculations. Emission rate is in Bq/s Start time: Set the start date of the source term. Note that this date is also used as start date for the simulation. The meteorological data are requested from for this starting time onwards. The time is UTC and the format is YYYYMMDDHH[.mm] (YYYY = year, MM = month, DD = day, HH = hour, [.mm] = minutes which are optional). Stop time: Set stop date of source emission. Note: The stop date of the simulation is set in [End data of calculation] in the main window. The time is UTC and the format is YYYYMMDDHH[.mm] (YYYY = year, MM = month, DD = day, HH = hour, [.mm] = minutes which are optional). Emission height: Set the emission height in meters. Note! If the date is not set the source is omitted, or if date starts with YYYY i.e. a character text string. Selecting the button [Update] stores the selection and closes this window, [Close] closes the window without storing the selections. The button [Help] opens a help window including some comments for this window. - 18 -
3.2.2 Source 2 (optional) Choosing [Source2 (optional)] in the 'Main Menu'-window brings up a similar window as for source 1. Input for sources 2 to 4 are not mandatory and can differ in their source strength from each other. Sources are treated individually in the calculations but concentrations and doses will be added up in the output. If character strings are in the input windows, the source will not be considered in the dispersion calculation. 3.2.3 Source 3 (optional) 3.2.4 Source 4 (optional) Choosing [Source3 (optional)] in the 'Main Menu'-window brings up a similar window as for source 1. Input for sources 2 to 4 are not mandatory and can differ in their source strength from each other. Sources are treated individually in the calculations but concentrations and doses will be added up in the output. If character strings are in the input windows, the source will not be considered in the dispersion calculation. Choosing [Source4 (optional)] in the 'Main Menu'-window brings up a similar window as for source 1. Input for sources 2 to 4 are not mandatory and can differ in their source strength from each other. Sources are treated individually in the calculations but concentrations and doses will be added up in the output. If character strings are in the input windows, the source will not be considered in the dispersion calculation. - 19 -
3.2.5 Nuclides (Switch on/off nuclides in the source term(s)) Choosing [Nuclides (Switch on/off nuclides in the source term(s))] in the 'Main Menu'-window brings up a selection window where up to five radionuclides can be selected for one run. The button [Inert] refers to an ideal traces and should not be selected if further calculations with a foodchain and dose module will be carried out. Selecting the button [Update] stores the selection and closes this window, [Close] closes the window without storing the selections. The button [Help] opens a help window including some comments for this window. - 20 -
3.2.6 End date of the calculations (Optional) Choosing [End date of the calculations (Optional)] in the 'Main Menu'- window brings up a window where the end date of the calculation can be specified. In the present version, up to 48 hours of prognosis are possible. There are 3 different options: 1. If this window remains empty, calculations will be carried out for a 48 hour prognosis. 2. If a date far in the future is selected, MATCH will carry out calculations as long as weather data are available (Note: not activated!) 3. End date in the same format as the start date defines an end date prior to the maximum of 48 hours possible. The time is UTC and the format is YYYYMMDDHH (YYYY = year, MM = month, DD = day, HH = hour). Selecting the button [Update] stores the selection and closes this window, [Close] closes the window without storing the selections. The button [Help] opens a help window including some comments for this window. - 21 -
3.2.7 Output Selection Choosing [Output Selection] in the 'Main Menu'-window brings up a window where the output can be defined for which calculations are performed and which are displayed in the Graphical System of RODOS. If further calculations with the food chain model FDMT are requested, some selections should always be present to get an impression on the concentrations and potential doses: Instantaneous concentration Dose Total Deposition Wet Deposition Precipitation [Close] exits the window without storing any selections, [Update] confirms any selections, and [Help] brings up a comment window. - 22 -
Graphics on/off Choosing [Graphics on/off] in the 'Main Menu'-window brings up a window where it is possible to activate or deactivate the sending of the results to the Graphics System for displaying. The communication with the graphics is rather slow and therefore is this option available. [Close] exits the window without storing any selections, [Update] confirms any selections, and [Help] brings up a comment window. - 23 -
3.2.8 Grid for presentation in RoGIS Choosing [Grid for presentation in RoGIS] in the 'Main Menu'-window brings up a window where it is possible to define the number of grid cells and the bounding box for displaying in the Graphical System of RODOS. This does neither affect the grid area for the calculation, which is defined by the weather data, nor the area available for postprocessing. The output grid for RoGIS in latitude - longitude coordinates (degrees). Make sure that the source location lies within your grid specified. [Close] exits the window without storing any selections, [Update] confirms any selections, and [Help] brings up a comment window. - 24 -
3.2.9 Path weather data Choosing [Path weather data] in the 'Main Menu'-window opens a window where the user can insert the entry keyword in the file $RODOS_DIR/roenvdir/metlistenv. This keyword consists of the provider name and the string eu. The default provider is dmi. On the basis of this keyword the following attributes of meteorological forecast weather data are specified: Sample_Time[h]: cycle time of the incoming forecast weather data Data_Interval[h]: interval of prognosis data Prognosis_Time: prognosis period of the forecast weather data Time_Zone; e.g. UTC DIR_Pattern, File_Pattern and Data_Directory specify the location of the files. The weather data has to be in WMO GRIB format.. Data are supposed to be found with each time-point in separate files with the following naming: WEATHERDATAPATH/PROVIDERYYMMDDHHLLL with (YY=year, MM=month, DD=day, HH=hour, LLL=forecast length) If the provider name is used for the naming it is a generally applied method writing the provider name in capital letters. The default path and PROVIDER will lead to the following example location / file: romet/dmi/eu/dmi98070603 [Close] exits the window without storing any selections, [Update] confirms any selections, and [Help] brings up a comment window. - 25 -
3.2.10 Select subarea in weather data Choosing [Select subarea in weather data] in the 'Main Menu'-window brings up a window where it is possible to define rows and columns which should be omitted from the weather domain. To cut out a sub-area out of the input weather data, it is necessary to specify how many rows and columns that should be left out. The rows and columns on the north and east boundary, respectively, are set to a negative number if you want to exclude those. A positive number in the latter case will be regarded as the absolute index to be kept. This means that -5 will cut down the area on either east or north boundary with 5 columns or rows, while 5 will cut the are at column or row 5 (apparently a very small area). [Close] exits the window without storing any selections, [Update] confirms any selections, and [Help] brings up a comment window. - 26 -
4 Results and Data Output 4.1 Output to the Graphics system 4.1.1 Possible results Dependent on the selections made in the Initialization windows of MATCH, results will be displayed as maps in the Graphical System of RODOS. The following subgroups are available: Activity concentrations in air Wet and dry deposited activity Dose from cloud passage Dose rate from cloud passage Meteorological parameter such as boundary layer height, heat flux, humidity, precipitation and temperature - 27 -
Default results If the preset selections in the Initialization Window in chapter 3.2.7 are not changed by the user, the following results will be calculated by MATCH and are accessible in the Graphics system: Maps Activity concentrations in air (nuclide dependent) Instantaneous Mean Deposited activity (nuclide dependent) Total Wet Dose from cloud passage (nuclide dependent) Dose rate from cloud passage (nuclide dependent) Meteorological parameter Boundary layer height Heat flux Humidity Precipitation Temperature - 28 -
4.2 Interface data MATCH produces data needed by other modules of RODOS: the Terrestrial Foodchain and Dose Module FDMT These data are stored in files. To generate the necessary shared memory and to store the data in the RODOS data base, the module INT-MA-FDM is required. A description of INT-MA-FDM can be found in a separate chapter of user guide. 4.2.1 MATCH - FDMT interface For estimation of the activity concentrations in feed- and foodstuffs as well as doses without countermeasures, data is being transferred to FDMT via INT-MA-FDM: Mean time-integrated air concentration in each time interval Wet deposited activity External dose from cloud passage Rain intensity In addition, several other model and program steering parameters are included in the interface. As mentioned above, the module INT-MA-FDM is needed for this procedure. - 29 -
5 Error Correction Procedures General error messages Error flag (2): Insufficient space for continuation. The weather data contains too many grid cells, and the arrays in MATCH that holds the data are too short. The solution is to cut down the weather data area, see section 3.2.10 for details. If this is not sufficient the MATCH model has to be recompiled with other settings of NXDIM, NYDIM, NLEVDIM or NCHEMDIM. Consult the system manager. Error flag (3): Insufficient space for puffdata. The MATCH model has to be recompiled with other setting of the NPOINTDIM parameter. Consult the system manager. Error flag (4): Insufficient space for continuation. The MATCH model has to be recompiled with other setting of the NSDIM parameter. Consult the system manager. Error messages from checking input data and model parameters Error flag (10): Missing first set of weather data. Check path to weather data and the period of data that is available, see section 3.2.9 for details. Error flag (11): Missing weather data during runtime. There is a gap in available weather data. Consult the system manager. Error flag (12): Puff data missing Error when running RMATCH. File with puff data missing. Error flag (20): Point source outside model area - 30 -
Error when running standalone MATCH. The model discontinues if the specified source location is outside the model domain. Error flag (21): Date string in error Any of the date specifications is erroneous. Check what you have typed in the graphical user interface of MATCH. Error flag (41): Error in grid specification Error when running PMATCH The dynamic grid specification is not correct. Error flag (44): Area for interpolation outside Match model domain Error when running PMATCH. The area for interpolation is outside the model domain. No meaning to continue. 5.1 Trouble shouting MATCH/LSMC can not find weather data The system program delivers the meteorological data into romess/userid/provider e.g. romess/userid/dmieu and each file is composed by a prefix and a date stamp, e.g. DMI9907070024. Please check, if the data fit to the time you requested. In case of problems, please check also the location of the original data in romet/provider/eu/ Data files have to be present there. The model starts but exits after check of memory requirements The weather data contains too many grid cells, and the arrays in MATCH that holds the data are too short. The solution is to cut down the weather data area, see section 3.2.10 for details. - 31 -
Segmentation fault occurs The compiled MATCH executable is too large for the RAMmemory of your computer. The MATCH model has to be recompiled with other settings of NXDIM, NYDIM, NLEVDIM or NCHEMDIM. Consult the system manager. The results presented in RoGIS looks like strips over the map You have most likely rerun MATCH with some other size of the output grid to RoGIS. Close the graphics and restart the model. The dimension specified in the shared memory transferring data from MATCH to the RoGIS graphics is only set once. Changing the area for the graphics, see section 3.2.8, could therefor lead to strange results. - 32 -
Document History Document Title: User Guide for the MATCH stand alone Module of RODOS-PV 5.0 Version and status: Version 1.1 (draft) Authors/Editors: Lennart Robertson Address: Email: Issued by: W. Raskob File Name: Match_UGui_50e.doc Date of print: April 22, 2003-33 -