Main RC file

From tm5
Jump to: navigation, search

To describe the main rc file, with which you will principally interface with the model, we use the template for the full chemistry version that ships with TM5. You can get a copy:

svn export https://svn.knmi.nl/svn/TM5/base/trunk/rc/tm5_template_chem.rc tm5.rc

The sections specifics to restart options, output options and pre- and post-processing have their own page: Restart options, Output options, and Post-processing.

Contents

General settings

The top part of the file has some general settings:

 1  !=====================================================================!
 2  ! Run main specifications
 3  !=====================================================================!
 4  ! id
 5  my.basename     : tm5v4
 6   
 7  ! timing
 8  timerange.start : 2006-01-01 00:00:00
 9  timerange.end   : 2006-02-01 00:00:00
10  jobstep.length  : month
11   
12  ! autorun
13  submit.auto     : False
14   
15  ! main directories
16  my.project.dir  : ${my.scratch}/TM5
17  my.run.dir      : ${my.project.dir}/benchmark
18   
19  ! dir of standard input files (read in model init)
20  inputdir        : ${my.data.dir}

line 5: this id is used as basename for the executable, runtime rc files, job script (hence log files too), and the ${my.basename}__sources.tar archive.

line 8-9: date and time of the start and end of the simulation.

line 10: length of a chunk. Runs are stopped and restarted after each chunk period, until the end of the simulation is reached. Either a number, which specifies the number of days, or 'month', for one month. If set to 'inf', it never stops. This is the default.

line 13: set this key to True, if you want the pycasso script to automatically submit (run) the executable after compilation. This is equivalent to using the '-s' or '--submit' option at the command line. The job is then started in the background, foreground or managed by a job scheduler, according to ${submit.to}, which is defined in expert.rc file. Note options passed at the command line always take precedence.

line 16-17: these to key define where the code is build and compile, and where it is run. The code is build and compiled in :

<my.project.dir>/build/

It is suggested (but you don't have to) to start my.run.dir with ${my.project.dir}, so you end up with the following tree :

  <my.project.dir>/build
                  /<rundir>

Output/restart/archive directories (see below) can also be set below ${my.project.dir} or ${my.run.dir}. Following these suggestions, the ${my.project.dir} fully becomes a project top directory, and not just the parent of the build dir.

Finally, note the use of the ${my.scratch} variable (defined in machine.rc).

line 20: indicates the directory with some of the input data (photolysis data, aerosols input, land-sea mask, leaf area index, ...). Here it is set to ${my.data.dir}, which is set in the machine.rc file.


Environment

The second part of the file deals with your environment:

21  !=====================================================================!
22  ! Environment (compiler, libraries, job manager, //, ...)
23  !=====================================================================!
24  my.build.configure.flags : optim-fast optim-strict
25   
26  my.queue.account         : 
27  my.queue.memoryload      : 
28  my.machine.rc            : 
29   
30  #include base/${my.branch}/rc/${my.machine.rc}
31   
32  par.mpi       : T
33  par.ntask     : 12
34  par.nx        : 1
35  par.ny        : 12
36  par.openmp    : F
37  par.nthread   : 1

line 24: list of generic compiler options. Once your machine/compiler rc files are set up, these options will trigger the appropriate ones for your compiler. 'Optim-vfast' (aggressive optimization) , 'Optim-fast' (commonly used optimization), 'Optim-none' (no optimization), 'Optim-strict', 'check-all' (for set of runtime checking) and 'debug' should be available.

line 26-27: these are left empty, because they are specific to your environment. The list of keys may differ, depending mainly on your job scheduler implementation.

line 28: basename of your machine.rc file.

line 30: includes the settings from your machine.rc file, where compiler and path to the libraries are defined.

line 32-33: MPI settings. Set par.mpi to T to use MPI, and specify the number of processors with par.ntask.

line 34-35: dummy keys in TM5.

line 36-37: OpenMP settings. Set par.openmp to T to use it, and specify the number of processors with par.nthread.


Grid and levels

 38 !=====================================================================!
 39 ! Grids & Levels
 40 !=====================================================================!
 41 my.levs                     :  tropo34
 42 ! regions name
 43 my.region1                  :  glb300x200
 44 ...
 45 ! regions meteo grid
 46 my.region1m                 :  glb100x100

line 41: defines the number of model level. If you choose all, then all levels of the original met fields are used. But you can use a combination of these levels to reduced their number. Are available: tropo25, tropo34, ml40.

line 43: provides the region name. It provide the name of the region file with all the definition of the region.

line 46: the name of the meteo grid. Basically the resolution of the met fields. If it differs from the region name, regridding of the meteo to the run resolution is done on the fly.

In this section, zoom regions can also be set. See Zoom Regions for details.


Source code

The source code is gathered from several directories. A set of cpp pre-processor flags is used to remove unneeded files and code snippets. The relevant keys are in the following two sections of the rc file:

47  !=====================================================================!
48  ! Source code
49  !=====================================================================!
50  my.branch      : trunk
51   
52  ! intermediate keys
53  my.source.LEVS : proj/levels/${my.eclevs}/${my.branch} proj/levels/${my.eclevs}/tropo34/${my.branch}/ 
54  my.source.PROJ : proj/chem/base/${my.branch}
55  my.source.OUT  : proj/user_output/${my.branch} proj/budget/lat10xml/${my.branch}
56  my.source.BASE : base/${my.branch}
57   
58  my.source.dirs : ${my.source.BASE} ${my.source.LEVS} ${my.source.OUT} ${my.source.PROJ}
59   
60  !=====================================================================!
61  ! C-preprocessors: DF, TMM, TM5
62  !=====================================================================!
63  #if "${par.mpi}" in ["T","True"] :
64  my.df.define   :  with_hdf4 with_hdf5_par with_netcdf4_par
65  #else
66  my.df.define   :  with_hdf4 with_hdf5 with_netcdf4
67  #endif
68   
69  ! macro's for meteo input:
70  #if "${my.meteo.format}" == "tm5-nc"
71  my.tmm.define  :  with_tmm_tm5 with_udunits
72  #else
73  my.tmm.define  :  with_tmm_tm5
74  #endif
75   
76  my.without    :  
77   
78  ! standard chemistry uses:
79  my.def_advec  : slopes
80  my.defs_emis  : with_ch4_emis
81  my.defs_proj  : with_tracerorder with_m7 with_optics
82  my.defs_misc  : with_pycasso with_budgets
83   
84  my.tm5.define : ${my.without} ${my.def_advec} ${my.defs_misc} ${my.defs_proj} ${my.defs_emis}

line 50: this intermediate key is convenient to quickly switch branch. You could do without it, but then you must replace all references to it (${my.branch}) in the rc file and in the included rc files. Here it is set to trunk, but you could use a release (e.g. release/4.0) or a branch (e.g. branch/my_branch_name).

line 53-58: these keys list the directories, from which the source code is gathered. Only my.source.dirs is mandatory. Here it adds up the four previous convenient lines.

line 56: The code requires a base that has all the meteo and transport codes, the main program and control flow. The directory is set in my.source.BASE. Note that if you examine the code layout, you will see that the subdirectory src of the key value is used to find source code.

line 53: Also required by the base code is the coding of the model levels description. It depends on the type and year of the meteo. This dependence is in the ${my.eclevs}, which is automatically set in the meteo rc file. The levels description also depends on the my.levs key set above. This is not automatic. If you use all the levels from the meteo, then just use:

my.source.LEVS : proj/levels/${my.eclevs}/${my.branch}

If you use a reduced number of levels, for example tropo34, then add a second directory:

proj/levels/${my.eclevs}/tropo34/${my.branch} 

line 54: to define the tracer(s) and their sources and sinks, you just add a project. You must have one. Here we used proj/chem/base/trunk.

line 55: some of the project simply adds functionalities to the program. Here it is mainly extra output (proj/user_output/) and a different-from-the-base definition of the regions where the budgets are computed (proj/budget/lat10xml). You can leave this key empty.

line 58: the final list of directories to search for source code.

IMPORTANT: the order of the list matters, since files with the same name are overwritten. So always put the base source first.

IMPORTANT: if you change the list, recompile the entire code with the -n option (n is for new, and is like clean in may other programs). The files from the new project directories are probably older than the current object files, and then 'make' will not recompile.


line 61: TM5 requires that you define 3 sets of C preprocessor (cpp) flags in the following keys:

line 63-67: these line automatically switches between libraries with and without parallel I/O enabled, if you are using MPI or not. If you do not have netcdf4 (and its required hdf5) installed with parallel I/O enabled, replace these 5 lines with:

my.df.define   :  with_hdf4 with_hdf5 with_netcdf4 

Note that you cannot use restart and time series output. You will have to set:

istart        : 31
restart.write : F
output.pdump  : F

Another possible scenario is that you do not have netcdf4 (and the underlying hdf5). Then use:

my.df.define   :  with_hdf4  with_netcdf 

Again you will not be able to use restart and time series output.


line 69-74: with these lines, TM5 automatically switch between netcdf and hdf format for dealing with TM met field. If you are pre-processing ECMWF original meteo with TM5, you will have to add the with_grib flag, since original data from IFS are in GRIB format, and the with_tmm_ecmwf:

with_tmm_ecmwf with_grib

line 76: this line is not strictly needed, unless you use tags (see Using tags). But it is still convenient to isolate one group of flags available for my.tm5.define: those that turns off some of the processes. These flags start with without_. Possible values are:

without_advection       without_convection
without_diffusion       without_dry_deposition
without_wet_deposition  without_chemistry
without_emission        without_sedimentation
without_boundary        without_photolysis

Be careful when using them. See Issues with the without_* cpp flags.

line 79-82: these are also intermediate keys for my.tm5.define. They are set to one or more of this list:


Tuning

84  !=====================================================================!
85  ! Model tuning
86  !=====================================================================!
87  ! model timestep
88  time.ntimestep              : 3600
89  time.ndyn_max               : 3600
90  ! processes
91  proces.advection.reduced    : T
92  proces.wet_removal.cp_scale : 0.5
93  ! read/write diffusion coefficients
94  diffusion.write             : F
95  diffusion.dir               : ${my.run.dir}/output

Meteorological fields

 96 !=====================================================================!
 97 ! METEO SETTINGS
 98 !=====================================================================!
 99 my.meteo.class        : ei
100 my.meteo.resol        : glb100x100
101 my.meteo.format       : tm5-hdf
102 time.fc               : F
103 time.fc.day0          : 
104 my.tmm.setup.apply    : T
105  
106 #include base/${my.branch}/rc/pycasso-meteo-tm5.rc    

Extra

107 !=====================================================================!
108 ! Extra ressources
109 !=====================================================================!
110 #include base/${my.branch}/rc/pycasso-tm5-expert.rc
111 #include base/${my.branch}/rc/chem.input.rc


At the end of the template, you will find the following lines:

113 !=====================================================================!
114 ! Miscelleaneous (do not modify, unless you know what you're doing!)  !
115 !=====================================================================!
116 output.types            : timing settings
117  
118 jobstep                 : 0
119 jobstep.timerange.start : ${timerange.start}
120 jobstep.timerange.end   : ${timerange.end}
121 prev.output.dir         : 

line 116: This key is use to create specific output directory if needed for settings (grids) and timing (profiling) output. These directories are defined with the timing.output.subdir and settings.output.subdir keys (see Output options). You don't need change this line. line 118: step/leg/chunk number. Leave it to zero. line 119-120: time range of the current step (chunk). Filled automatically by submit scripts. Do not modify. line 121: directory for restart to read for this step. Filled automatically by submit scripts. Do not modify.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox