Difference between revisions of "The run.def Input File"

Latest revision as of 17:43, 18 October 2024

The run.def input file and its format

some general comments and disambiguation to start with

This pages specifically focuses on the run.def file used by the model with the lon-lat (LMDZ) dynamical core. There is also a run.def when running with the DYNAMICO dynamical core, which can be quite different.

In addition, the example discussed below is for the Generic physics package, but most of what is mentioned here is relevant for the other (Mars, Venus, Titan) physics packages.

the run.def file

The run.def file is a text file that is read at run time by the GCM (and must thus be present in the same directory as the executable). It contains the values of various parameters that the user can specify (as "key = value", where "key" is a predefined keyword and "value" may be a real, an integer, a string or a logical) and modify depending on the specific simulation that is intended, e.g. the line:

planet_type = generic

means that when the GCM will run, it will set parameter planet_type (which identifies the physics package that is used) to generic. If using a different physics package, like the Mars one then planet_type should be adapted accordingly.

Any line starting with # is a comment, e.g.

# Number of days to run model for

The order in which parameters are given in the run.def file is not important, except if a parameter value is given more than once (not recommended!), then it is the last occurrence that prevails.

Worth knowing about: if a given "key" is not present in the file, then a default value (hard coded in the code) will be used for the related parameter.

*.def files included in run.def

The run.def file can include other files (based on the same format, lines containing "key = value" or comments) using the INCLUDEDEF keyword, e.g.:

INCLUDEDEF=callphys.def

This is a convenient way to separate related sets of parameters in separate files; common practice is to put dynamics related parameters in run.def and physics related parameters in callphys.def

Reference def files

Reference *.def files are provided in the LMDZ.GENERIC/deftank directory

Outputted used_*def files

When the GCM run finishes, for each of the input def files *.def, an ASCII output file used_*.def is generated (in practice these would be used_run.def and used_callphys.def). These files contain, along the same format as the *.def input files, the "key = value" that were used, along with comments about whether "value" was read in the input def file or if the code default was used (i.e. the sought "keyword" was not present in the input def files).

Example of run.def file

#
#----------------------------------------------------------------------- 
# Run control parameters:                                         
#------------------------

# planet type
planet_type = generic # for pluto & exoplanets
planet_type = mars    # for mars
planet_type = venus   # for venus

# Number of days to run model for 
     nday=1

# ndynstep (overrides nday): number of dynamical steps to run for
#     ndynstep=20

# Number of dynamical steps per day (must be a multiple of iperiod)
 day_step = 480

# Apply a Matsuno step every iperiod dynamical step
  iperiod=5

# Control output information in the dynamics every iconser dynamical steps
  iconser=120

# Apply dissipation every idissip dynamical steps
  idissip=5

# dissipation operator to use (star or non-star)
 lstardis=.true.

# use hybrid vertical coordinate (else will use sigma levels)
 hybrid=.true.

# iterate lateral dissipation operator gradiv nitergdiv times
nitergdiv=1

# iterate lateral dissipation operator nxgradrot nitergrot times
nitergrot=2

# iterate lateral dissipation operator divgrad niterh times
   niterh=2

# time scale (s) for shortest wavelengths for u,v (gradiv)
 tetagdiv= 3000.

# time scale (s) for shortest wavelengths for u,v (nxgradrot)
 tetagrot=9000.

# time scale (s) for shortest wavelengths for h (divgrad)
 tetatemp=9000.

# multiplicative constants for dissipation with altitude:
# coefficient for middle atmosphere (~20-70km)
dissip_fac_mid = 2
# coefficient for upper atmosphere (~100km+)
dissip_fac_up = 10

# coefficient for gamdissip                                            
  coefdis=0.

# time marching scheme (Matsuno if purmats is true, else Matsuno-Leapfrog)
  purmats=.false.

# run with (true) or without (false) physics
   physic=.true.

# call physics every iphysiq dynamical steps
  iphysiq=10

# Use a regular grid
  grireg=.true.

# Output in diagfi file every ecritphy dynamical steps
 ecritphy=120

# longitude (degrees) of zoom center
   clon=63.

# latitude (degrees) of zoom center
   clat=0.

# enhancement factor of zoom, along longitudes
  grossismx=1.

# enhancement factor of zoom, along latitudes
 grossismy=1.

#  Use an hyperbolic function f(y) if .true., else use a sine
  fxyhypb=.false.

# extention along longitudes of zoom region (fraction of global domain)
   dzoomx= 0.

# extention along latitudes of zoom region (fraction of global domain)
   dzoomy=0.

# zoom stiffness along longitudes
    taux=2.

# zoom stiffness along latitudes
    tauy=2.

#  Function  f(y) as y = Sin(latitude) if = .true. ,  else  y = latitude
  ysinus= .false.

# Use a sponge layer
  callsponge  = .true.
 
# Sponge layer extends over topmost nsponge layers
  nsponge = 3

# Sponge:  relaxed towards teta=teta_ave
#        and mode0(u=v=0), mode1(u=u_ave,v=0), mode2(u=u_ave,v=v_ave)
  mode_sponge= 2

# Sponge layer time scale (s):  tetasponge
  tetasponge = 50000

# some definitions for the physics, in file 'callphys.def'
INCLUDEDEF=callphys.def

Notes:

• Lines beginning with a hashtag are comments
• values associated to keywords may be logicals, integers, reals or even strings
• The parsing is case-sensitive : "thisparameter=" and "ThisParameter=" are identified as two distinct keywords
• The order in which the parameters are given in the file does not matter (except if a parameter is specified multiple times, clearly a bad idea, and then the last occurrence will prevail).
• Accessing a parameter and its value from run.def in the Fortran code is done using the getin_p routine, e.g.:

       call getin_p("keyword",val)

will look for the line with "keyword = " in file run.def and extract trailing value which will be use to set the value of the val variable in the code.

Examples run.def for DYNAMICO

• run.def for Held&Suarez test case
• run.def for generic-DYNAMICO
• run.def for Venus-DYNAMICO
• run.def for Mars-DYNAMICO
• run.def for DYNAMICO-giant
• run.def for Pluto-DYNAMICO