Main rc file

!!!! Work in progress, this is the TM5-zoom version, still needs update specific to TM5-MP !!!!!

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 tm5.rc

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

General settings

The top part of the file has some general settings:

  1  !=====================================================================!
  2  ! Run main specifications
  3  !=====================================================================!
  4  ! id
  5  my.basename     : expid
  7  ! timing
  8  timerange.start : 2006-01-01 00:00:00
  9  timerange.end   : 2006-02-01 00:00:00
 10  jobstep.length  : month
 12  ! autorun
 13     : False
 15  ! main directories
 16  my.project.dir  : ${my.scratch}/TM5-RUNS/
 17      : ${my.project.dir}/rundir
 18  my.meteo.dir    : ${my.scratch}/TM5_METEO_NC/
 20  ! dir of standard input files (read in model init)
 21  inputdir        : ${}

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 ${}, 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 :

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

Output/restart/archive directories (see below) can also be set below ${my.project.dir} or ${}.
Following these suggestions, the ${my.project.dir} fully becomes a project or experiment 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 18: this is the location of the met fields at runtime.

line 21: indicates the directory with some of the input data (photolysis data, aerosols input, land-sea mask, leaf area index, ...). Here it is set to ${}, which is set in the machine.rc file, where it point to the default archive that you have downloaded (see User Manual).


The second part of the file deals with your environment:

 21  !=====================================================================!
 22  ! Environment (compiler, libraries, job manager, //, ...)
 23  !=====================================================================!
 24 : optim-fast optim-strict
 26  my.queue.account         : 
 27  my.queue.memoryload      : 
 28  my.machine.rc            : 
 30  #include base/${my.branch}/rc/${my.machine.rc}
 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
  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.

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.source.proj : proj/output proj/budget10 proj/cb05

 60  !=====================================================================!
 61  ! C-preprocessors: DF, TMM, TM5
 62  !=====================================================================!
 63  #if &quot;${par.mpi}&quot; in [&quot;T&quot;,&quot;True&quot;] :
 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
 69  ! macro's for meteo input:
 70  #if &quot;${my.meteo.format}&quot; == &quot;tm5-nc&quot;
 71  my.tmm.define  :  with_tmm_tm5 with_udunits
 72  #else
 73  my.tmm.define  :  with_tmm_tm5
 74  #endif
 76  my.without    :  
 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
 84  my.tm5.define : ${my.without} ${my.def_advec} ${my.defs_misc} ${my.defs_proj} ${my.defs_emis}

line 50: this key lists the directories, from which the source code is gathered. The base dir being already included, you really need to indicate the directories in proj/. Some of the project simply adds extra functionality to the program. Here it is mainly extra output (proj/output) and a different-from-the-base definition of the regions where the budgets are computed (proj/budget/lat10). The main project (here proj/cb05) define the tracer(s) and their sources and sinks.

IMPORTANT: the order of the list matters, since files with the same name are overwritten.

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 may be 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:

  • my.df.define : for scientific Data Format libraries (hdf, netcdf, grib)
  • my.tmm.define : for reading and processing TM5 Meteo
  • my.tm5.define : everything else for TM5 model (mainly tuning processes)

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 time series output and will have to set:

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:

  • Advection
    • slopes : use slopes advection
    • secmom : use second moments advection; requires 'slopes'
  • Convection levels
    • without_lmax_conv : convective fields not on limited number of layers
  • Miscellaneous
    • with_budgets : to produce budget output files
    • with_pycasso : extensions for use with pycasso scripting
  • Special libraries
    • with_lapack : to use LAPACK lib for linar algebra, and speed up convection
  • Chemistry
    *with_cariolle : to use Cariolle parameterization of stratospheric O3
    *with_m7 : to use m7 aerosols model
    *with_optics : m7 flag - aerosol feedback on photolysis
    *with_pm : m7 flag - Calculate PM2.5/PM10 output
    *with_online_bvoc : to use MEGAN for biogenic emissions
    *with_online_nox : ??
    *with_ch4_emis : to switch on CH4 emissions
    *without_o3_nudging : to switch off O3 nudging
    **with_tracerorder : to force tracer distribution over processors. Required when chem/base/ is used.


 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               : ${}/output

h2. Meteorological fields
  96 !=====================================================================!
  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
 106 #include base/${my.branch}/rc/pycasso-meteo-tm5.rc   


 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
 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.