Submitting a Run

In this chapter we provide detailed information on how to run the regional EMEP/MSC-W model for two different types of simulations, namely:

Base run
This is the default set up for yearly transport model calculations in \(50\times 50 km^2\) grid.
Scenario run
A run with reduced emissions from a particular country or several countries is called a “Scenario run”. It is the basic type of run for the source-receptor calculations.

Details about the submission of these different types of runs are given below. We suggest that users test the “Base run” first, which can be done without significant changes in the code itself. One can also use the outputs of such a run in the future as a reference run for the other simulations.

Base run

This is an example of a minimum modrun.sh script to run the model.

Listing 3 Minimum modrun.sh example.
#!/bin/bash
	    
# Minimalistic script for run the EMEP/MSC-W model

# Link the input data
inputdir=.
ln -s $inputdir/input/* .   # Other input files

# Run the model
mpirun $inputdir/code/Unimod

# Clean the links to the input data
find . -type l -delete

This bash shell script is designed so that users can easily adapt it to fit their needs. It contain the minimum information required to run the EMEP/MSC-W model. The script should be self-explanatory. It assumes one directory for input data other than meteorology data. The metdata for the year, and for January \(1^{st}\) the following year (365 +1 files) is linked directly in the config_emep.nml file. You need to set the right paths for the input directories. All the input files in the input directories are linked to the directory you are working from.

config_emep.nml

The model has a namelist system. It is possible to set different constants and flags for running the model. The constants and flags itself is defined in ModelConstants_ml.f90, while they are set in the namelist file under ModelConstants_config parameter. Some of these are briefly explained in ch-inputfiles. Model gets information about running for special cases from this file. The datasets provided are for the EMEP grid EECCA.

The different parameters for the model run are set in the config_emep.nml file. In the very beginning of this, the section INPUT_PARA has all these variables including the link to the meteorology data. The trendyear can be set to change the boundary emissions for earlier and future years, see the modules BoundaryConditions_ml.f90 and GlobalBCs_ml.f90 to understand better what the trendyear setting does. The default setting is the meteorological year you are running for, in this case 2014. The runlabel1 option sets the name of the different output NetCDF files, see ch-output. The startdate and enddate parameters are set for the time period you want the model to run (YYYY,MM,DD), and you need meteorology data for the period, as shown in Listing 4.

Listing 4 Basic namelist example.
&INPUT_PARA
  GRID      = 'EECCA',
  iyr_trend = 2014,
  runlabel1 = 'Base',
  runlabel2 = 'Opensource_Setup_2016',
  startdate = 2014,01,01,000000,
  enddate   = 2014,01,10,000000,
&end
&Machine_config
  DataPath(1) = '../input', ! define 'DataDir' keyword
&end
&ModelConstants_config
  meteo                 = '../meteoYYYY/meteoYYYYMMDD.nc',
  DegreeDayFactorsFile  = 'MetDir/DegreeDayFactors.nc',
  !------------------------------
[...]
  !------------------------------
  EmisDir               = 'DataDir/EECCA',
  emis_inputlist(1)%name= 'EmisDir/gridPOLL', ! ASCII
[...]
  ! --------Sub domain x0   x1  y0   y1
  RUNDOMAIN =  36, 100, 50, 150   ! EECCA sub-domain
&end

In Listing 4, the model is run for the period 1 January to 10 Januray 2014 and the trend year used is 2014. Output files will be stored with the name ‘Base’ and the meteorological correspond to the ‘EECCA’ grid.

It is possible to run the model on a smaller domain than the full regional model domain, as defined by indexes \(x\) and \(y\). For the ‘EECCA’ gtid \(x=1,\ldots,132; y=1,\ldots,159\). To set a smaller domain, use RUNDOMAIN variable in the ModelConstants_config namelist to idicate the sub-domain indexes. In Listing 4, RUNDOMAIN defines a subdomain with \(x=36,\ldots,100; y=50,\ldots,150\).

To run the model, the correct path to the EMEP/MSC-W model code has to be set (mpirun path_to_the_modelcode/Unimod).

It is recommended to submit the script as a batch job. Please check the submission routine on the computer system you are running on. In the newer model versions (since 4.0) the number of nodes is set automatically from what is asked for when submitting a job. The approximate time and CPU usage is described in sec-compinf.

When the job is no longer running or in the queue, it is either finished or has crashed for some reason. If the model run crashed, an error message will give information on what was missing or wrong in the routine. If the run was successful, a message

++++++++++++++++++++++++++++++++++++++++++++++++
programme is finished

will be stated at the end of the log file, before printing the Timing.out file.

The model results will be written to this same directory. Please make sure there is enough disk place for the model results. For more information about the model result output files, see ch-output.

If for some reason the model crashed, please check both the log and the error file for any clue of the crash. After fixing the problem the job can be submitted again. If the model has crashed, then the links to the input data are not removed.

The script can also be submitted interactively, and either have the output written to the screen or to named error and output log files. The variables wanted in the output are specified in the OutputConcs_config, OutputDep_config and in the OutputMisc_config parameters respectively for surface concentrations, depositions and some miscellaneous outputs.

Nesting

The boundary conditions needed for EMEP MSC-W model is provided with the input data. The model can read Boundary conditions data from other models as well. These data has to be in NetCDF format. The boundary conditions needed for EMEP MSC-W model is provided with the input data. The model can read Boundary conditions data from other models as well. These data has to be in NetCDF format.

Different Nesting modes are:

  • read the external BC data only,
  • produce EMEP BC data from the simulation,
  • read the external BC data and produce EMEP BC data,
  • using the default EMEP BC data from the input data directory and write out EMEP BC at the end of the simulation,
  • read the external BC data only in the beginning of the simulation,
  • read external BC at the beginning of the simulation and write out EMEP BC at the end of the simulation.

These options are controlled by the MODE_READ and MODE_SAVE variables in Nest_config namelist, in config_emep.nml file. The mode options are:

MODE_READ
‘NONE’
do nothing (default).
‘START’
read at the start of run.
‘FORECAST’
read at the start of run, if the files are found.
‘NHOUR’
read at given NHOURREAD hourly intervals. NHOURREAD is set in Nest_config and should be an integer fraction of 24.
MODE_SAVE
‘NONE’
do nothing (default).
‘END’
write at end of run.
‘FORECAST’
write every OUTDATE(1:FORECAST_NDUMP). OUTDATE and FORECAST_NDUMP are set in Nest_config.
‘NHOUR’
write at given NHOURSAVE hourly intervals. NHOURSAVE is set in Nest_config and should be an integer fraction of 24.

If BC data are read at NHOURREAD intervals from the file defined by template_read_BC in Nest_config. The IC data (entire 3D domain) will be set at start of run from the file defined by template_read_3D in Nest_config.

Write BCs from EMEP MSC-W model

Listing 5 shows an example to write every 3 hours into daily Nest/BC files. Output file name is defined by template_write (‘BC_YYYYMMDD.nc’), where ‘YYYYMMDD’ is replaced by corresponding date.

All advected model variables will be written out for the sub-domain defined by out_DOMAIN (\(x=60,\ldots,107; y=11,\ldots,58\)). If no out_DOMAIN is given, the model inner domain will be written out.

Listing 5 Write BCs configuration example.
&Nest_config
  MODE_READ        = 'NONE',          ! do not read external BC
  MODE_SAVE        = 'NHOUR',         ! write BCs
  NHOURSAVE        = 3,               !  every 3 hours
  template_write   = 'BC_YYYYMMDD.nc' !  to your (daily) BC output file
                                      !  (8 records per file)
  !-------- Sub domain for write modes
  out_DOMAIN       = 60,107,11,58,    ! istart,iend,jstart,jend
&end

Read BCs from EMEP MSC-W model

Listing 6 shows an example to read every 3 hours from the Nest/BC files created previously by running Listing 5. Please note that the model sub-domain for a nested run is set by RUNDOMAIN, as shown in Listing 4.

Listing 6 Read BCs configuration example.
&Nest_config
  MODE_READ        = 'NHOUR',         ! read external BC
  NHOURREAD        = 3,               !   every 3 hours
  template_read_BC = 'BC_YYYYMMDD.nc' !   your (daily) BC input file
  MODE_SAVE        = 'NONE',          ! do not write BCs
&end

Read external BCs

Reading BCs from a different model is more involved than the previous example. The vertical axis and variables in the file need to be mapped to the corresponding model variables.

Listing 7 shows an example to read every 3 hours from an external BC file. The model will read 3 variables from MyBC.nc: O3, NO, and NO2. The maping between the MyBC.nc variables and the corresponding model variables is defined in the ExternalBICs_bc namelist.

Listing 7 External BCs configuration example.
&Nest_config
  MODE_READ        = 'NHOUR',         ! read external BC
  NHOURREAD        = 3,               !   every 3 hours
  template_read_BC = 'MyBC.nc'        !   from your BC input file
  MODE_SAVE        = 'NONE',          ! do not write BCs
&end
&ExternalBICs_config
  USE_EXTERNAL_BIC = T,
  EXTERNAL_BIC_NAME= 'MyBICScenario', ! variable mapping, see ExternalBICs_bc
  TOP_BC           = T,               ! use top BC also from your BC file
  filename_eta     = 'filename.zaxis',! text file containing the
                                      !   description of your BC file
&end
&ExternalBICs_bc
  description='MyBICScenario','Version name',3,  ! name,version,size
  map_bc=! emep,external,frac,wanted,found,IXADV,
    'O3' ,'O3_VMR_inst' ,1.0,T,F,-1,
    'NO' ,'NO_VMR_inst' ,1.0,T,F,-1,
    'NO2','NO2_VMR_inst',1.0,T,F,-1,
&end

Vertical coordinate

In ordet the determine the vertical levels on the external BC file (‘MyBC.nc’ in Listing 7), the following checks will take place in the following order:

  1. \(\eta\) (eta) coordinate:
    If the variable \(hyam\) (hybrid a coefficient at layer midpoint) is found, \(\eta\) is calculated from \(hyam\) and \(hyam\) variables on the file.
  2. \(\sigma\) (sigma) coordinate:
    If the vertical level is indexed by variable k.
  3. \(\eta\) coordinate:
    If the file defined by variable filename_eta exist (‘filename.zaxis’ in Listing 7), \(\eta\) is derived from vct and vctsize variables on the file.
  4. pressure coordinate:
    If the vertical level is indexed by variable lev.

Independent of the coordinates of the BC file, the BC levels will be interpolated into EMEP model levels. If the BC file level structure is not recognized, and there is no filename_eta provided, the model will write an error message and stop execution.

An example of the filename_eta for EMEP model levels is given below. Here the vct variable describes the model level boundaries in hybrid eta coordinate:

Listing 8 filename_eta for EMEP model levels.
zaxistype = hybrid
size      : 20
name      : k
longname  : vertical sigma coordinates
units     : sigma_level
levels    : 0.0200 0.0600 0.1000 0.1425 0.1950 0.2635 0.3470
        0.4365 0.5215 0.5990 0.6695 0.7330 0.7895 0.8390
        0.8815 0.9170 0.9455 0.9670 0.9820 0.9940
vctsize   = 42
vct       =
        10000. 09600. 09200. 08800. 08350. 07750. 06980.
        06080. 05190. 04380. 03640. 02970. 02370. 01840.
        01380. 00990. 00670. 00420. 00240. 00120. 00000.
        0.0000 0.0400 0.0800 0.1200 0.1650 0.2250 0.3020
        0.3920 0.4810 0.5620 0.6360 0.7030 0.7630 0.8160
        0.8620 0.9010 0.9330 0.9580 0.9760 0.9880 1.0000

vct is the vertical coordinate table describing the hybrid a and b paramters at the layer interfaces in \(\eta\) coordinate system (\(hyai\) and \(hybi\)). They must respect the following constraints:

  • \(hyai_1=0\) and \(hybi_1=1\);
  • \(hyai_0=P_t\) and \(hybi_0=0\).
  • \(P_t\) is the pressure at top of the model domain.

In this file, the first 21 values in vct represent \(hyai\) and the remaining 21 represent \(hybi\) values in hPa.

Variable mapping

The variables to be used from the external boundary condition data are given in the ExternalBICS_bc namelist in the config_emep.nml file. In Listing 7, map_bc maps 3 variables in the ‘MyBC.nc’ file to 3 model variables (O3, NO, and NO2). On each line of map_bc contains the 6 elements:

  1. Variable name in EMEP MSC-W model, e.g. ‘O3’.
  2. Variable name in the External BC data file, e.g. ‘O3_VMR_inst’.
  3. External BC component to EMEP component fraction, e.g. 1.0.
  4. Is this component wanted or not, set to T or .true. to read the variable.
  5. Was the BC variable found on the file, will be set by the model on run time.
  6. Index of the advected model variable, will be set by the model on run time.

The fraction is helpful, when one has to map a variable that is explicitly not in the model but a fraction of that variable can be mapped to a matching variable in the model.

Unit conversions are delegated to the Units_ml.f90 module. The supported units are: \(\mu g/m^3\), \(\mu g(S)/m^3\), \(\mu g(N)/m^3\), \(\mu g(C)/m^3\), ppb, mixing ratio (mol/mol) and mass mixing ratio (kg/kg).

If the BC data has different units, either convert them into one of the above mentioned units in pre-processing or add the respective conversion factor in the module Units_ml.f90.

Source Receptor (SR) Runs

The EMEP/MSC-W model can be used to test the impact of reduced emission of one or more pollutants from a particular country or a number of countries. Such runs are called “Scenario runs”. They are the basic runs for source-receptor calculations.

Emission factors for reduced emissions of pollutants from different sectors and countries can be defined in the input file called femis.dat, which can be found in the downloaded input data directory, see section sec-femis.

Listing 9 femis.dat for a base run.
Name  7  sox  nox  co   voc  nh3  pm25   pmco
27    0  1.0  1.0  1.0  1.0  1.0  1.0    1.0

This base run example means that there are (1.0), no emission reductions of SOx, NOx, CO, VOC, NH3, PM2.5 and PMco from all sectors in the UK.

  • The first column of the second line represents the country code. (27 is the code for UK.) The codes for all countries can be found in Fortran module Country_ml.f90. Please note that the country code must be the same as in the emission files for the given country. Some countries and areas are divided into sub-areas in the emission files. In this case, one line for each sub-area has to be included into the femis.dat file. Countries and areas where emissions are given for sub-areas include the Russian Federation, Germany and all sea areas.
  • The second column of the second line represents the sector and “0” means all sectors. Here one can write the appropriate sector code if the emission is reduced only from a specific sector. The description of each sector can also be found in the Fortran module EmisDef_ml.f90.
  • The columns under the pollutant names show the emission factors for the given pollutants. For example, 0.7 would mean 70% of the original emission, thus 30% reduction.
  • The number (“7”) following the first text (“Name”) in the first line gives the number of pollutants treated in the file.

An example of femis.dat file describing 50% reduced emission of SOx from sector 10 (the emission from agriculture) in the UK is shown in Listing 10.

Listing 10 femis.dat for 50% SOx reduction from sector 10 over UK.
Name  7  sox  nox  co   voc  nh3  pm25   pmco
27   10  0.5  1.0  1.0  1.0  1.0  1.0    1.0

For a scenario run femis.dat file should be edited manually depending on the level of reduction one would like to test with any pollutant from any sector and/or any country. Several lines can be written in the file.