GEMCLIM config files

There are three configuration files used when running GEMCLIM.

Two of these are read by the executables (entry and/or model):

gemclim_settings.nml

'grid' and 'ptopo' get read by entry and model,
'gement' gets only read by the entry and
'gem_cfgs' (dynamics) and 'physics_cfgs' (physics) get only read by the model.

outcfg.out

The third one is only used in batch mode:

configexp.dot.cfg

gemclim_settings.nml

Information about the variables in the grid, entry and config namelists can be found here and the information about the physics namelist is here.

The following variables should always be set according the values in this list:

namelist 'gem_cfgs':
Init_balgm_L = .false.	No initialization, as it is useless in climate mode.
Schm_hdlast_L = .true.	(Optional/Used for AMIP2) Horizontal diffusion after the physics.
Schm_psadj_L = .true.	Surface pressure adjustment is activated. This means that at every time step, the horizontal integral of pi' at the surface is restored to its previous time step value. In hydrostatic mode, ln(p) and ln(pi_s/z_s) are also corrected. Note that in LAM mode, this parameter should be set to false.
Out3_ndigits = 8	Minimum of digits used to represent output units. Required by the diagnostics scripts.
Out3_unit_S = 'P'	Output names will include current steps rather than current dates and will end with a 'p'. Required by the diagnostics.
Out3_nbitg = 16	Packing factor used for all variables except for those defined in Out_xnbits_s. Please do not use anything smaller as it causes irreparable degradation of the diagnostics.
Clim_climat_L = .true.	You will run in climate mode.
Clim_ininc_L = .true.	To define physics surface forcing increments at the start of an experiment and at 0Z every 15th day of each month following that. These increments are applied by the physics package every day at 12Z in climate mode to simulate the annual cycle evolution of certain variables. Examples of affected variables are the sea surface temperatures and sea ice percentage coverage.
namelist 'physics_cfgs':
MOYHR:	When 'strip_phy=1' this value is used to determine the output interval in 'outcfg.out'. The unit is hours.

Most variables in these namelists have to be set manually. Only a few get set automatically. They are:

The hybrid levels 'hyb', the pressure at the top of the model 'Pres_ptop', and the list of levels at which radiation is performed, 'RADNIVL', are all adjusted according to 'etaname' in 'configexp.dot.cfg'.
'Step_total' is adjusted according to variables in 'configexp.dot.cfg'.
'Step_rsti' is set according to 'climat_rsti'.
'Step_cleanup' is set according to 'climat_cleanup'. After 'Step_cleanup' time steps 'Um_xfer.sh' will be called.
'Mod_runstrt_S' is set according to your 'startdate'.
For LAM 'Pil_jobstrt_S' and 'Pil_jobend_S' are adjusted at each interval.

outcfg.out

You will find information about the structure of this file here.

When 'strip_phy=1;', the file 'outcfg.out' is created automatically for the very first month. For continuing jobs, the first and last output time step of 'steps' will always be updated, and if the saving of an analysis file is required, a few variables will be added automatically.

A list of all model variables available for output can be found at the beginning of each model listing.
Note that this list varies depending on the schemes used!

This physics fields link shows an example of available fields for output when using ISBA.

And here is a list of the most common dynamic fields available for output:

TT	Air temperature	C
UU	u-component of the wind (along the grid x-axis)	knots
VV	v-component of the wind (along the grid y-axis)	knots
UV	Wind modulus	knots
GZ	Geopotential height	dam
HU	Specific humidity	kg/kg
HR	Relative humidity	%
ES	Dew point depression	C
P0	Surface pressure	hPa
PN	Sea level pressure	hPa
ME	Mountain height	m
LA	Geographical latitude	deg
LO	Geographical longitude	deg

configexp.dot.cfg

You will find information about the general variables in this file here.

Two of its variables do get updated each job with the current date:

The experiment name 'exp'

For LAM jobs the name of the pilot file archive 'lam_nest_exp'

And here is the list of special climate variables in GEMCLIM:

The variables written in red have to be initialized to run in climate mode, variables in violet only have to be set when diagnostics are required.

climat=1;

Required for climate-mode GEM/GEMCLIM. Default: climat=0

exp:

Experiment name. The current year and month are added/updated automatically at the start of each new job, depending also on the value of the variable ${interval}: The result is thus expname_YYYYMM resp. expname_YYYYMM-MM.
Note that if ${exp} contains an underscore everything after the last underscore will be replaced by the current date and that the maximum name length is 25 characters including the date.

xfer:

Note! In climate-mode this is the location, including the machine name and directory path, where the post-processing and diagnostics will be done, also known as ${dest_mach}. If the diagnostics are asked for ('diagnos=1;') the resulting files will be archived on ${arch_mach} in ${archdir}, otherwise they stay here. Format: xfer='machine:directory'

outrep:

Set this variable to a directory on ${mach} which is NOT under your ${EXECDIR}. Because if you continue your run the old ${EXECDIR} will be erased after the next job has been launched.

absaddres:

Location of executables. Must be on launching machine.

mach:

Name of the machine where the model is to be run.

startdate:

Day and time when the run starts: 'startdate="YYYY MM DD HH";' This date must match the validity date of the u-wind in the analysis file.

enddate:

Day and time when the run should finish: 'enddate="YYYY MM DD HH";'

interval:

Duration of one model job in months. Every interval, a new model job will be started with a call to Um_launch. There are usually several jobs in a particular experimental run. On 'marvin' keep this value set to '1'. Default: interval=1

climat_1diagpermonth:

Has only an effect if interval > 1. If climat_1diagpermonth=1, the diagnostics will be done for each single month instead of for interval months.

climat_rsti:

Days per model subjobs (clones). Since the time a model subjob can run is limited, more than one might have to be submitted per interval. Step_rsti in gemclim_settings.nml will be set automatically according to this value. If climat_rsti is not specified, Step_rsti will not be changed.

climat_cleanup:

Transfer interval in units of days. The default outcfg.out asks for a large volume of output files which may cause quota problems. To avoid this you can start the post-processing / file transfer before the model subjob is finished. climat_cleanup is the number of days after which the post-processing will be started. Step_cleanup in gemclim_settings.nml will be set automatically according to this value. If climat_cleanup is not specified, Step_cleanup will not be changed.

climat_job_size:

Sets the cpu time for several post-processing jobs. Possible values: small (default), i.e. 240x120 AMIP2 uniform grid; medium: i.e. 330x250 SGMIP grid; big: i.e. 720x360 mesoglobal grid.

cpu times for post processing and diagnostics using 8 cpu's on AIX:

	post processing	diagnostics
small	1800 s	3600 s * interval
medium	2400 s	7200 s * interval
big	3600 s	10800 s * interval

The maximum cpu time is restricted to 10800 seconds.

For any other machine:
post processing: cpu time from AIX times 8
diagnostics: 28800 s

The cpu times can be changed in the script 'Climat_post_processing'.

climat_rm_ptend:

If this parameter is set to 1 and Climat_mdpr_clean is called, it removes the 3D physics tendencies samples from the individual pr-files archives but only after their diagnostics have been calculated. Only UU, VV, WW, TT, HU, HR, GZ, T5, and T9 are kept. Default: climat_rm_ptend=0

step_total:

Number of time steps per model subjob. Calculated automatically.

deltat:

Size of the time step in seconds. Must be the same value as Cstv_dt_8 in gemclim_settings.nml, but is an integer.

etaname:

This variable sets the models vertical configuration: 1) The hybrid level distribution, 2) the pressure of the top model level. It also determines 3) the output pressure levels in outcfg.out and 4) the levels for which radiation is done (i.e. P_rad_nivl in gemclim_settings.nml). All of these etaname variables are set by the script Climat_eta2preshyb, i.e. with etaname=lh53t10; you define 53 hybrid levels with a top at 10 hPa. At the moment the following options are defined: lh28t10, lh40t2, lh42t1, lh50t5, lh50t5b, lh53t10, lh53t10b, lh60t2, lh60t2b, lh70tp1, lh80tp1, lh58tp10. The default is lh40t2. To use a new vertical configuration, simply add it to your copy of the script Climat_eta2preshyb.

strip_phy:

When strip_phy=1, the Climat_strip_phy script will be called to do the first part of the post-processing and the dm-, dp- and pm- output files will be reorganized in just two files per time step, md- and pr-, standing for model level data and pressure level data. All of the multi-level pm- variables will be interpolated to pressure levels and written to the pr- files. If you want to run the full diagnostics you have to set "strip_phy=1"

diagnos:

When diagnos=1, Climat_lancer_diag will be called to perform standard diagnostics, i.e. monthly means, variances, time series, etc.. If you want to run the full diagnostics you have to set "diagnos=1".

climat_masks:

The diagnostics need the non-filtered topography (ME) and the land-sea mask (MG) at the model's resolution. These two fields are usually saved in the md-sample files. Otherwise, they have to be in ~/gem/ls-masks under the names me_${climat_masks} and mg_${climat_masks}, respectively. Furthermore, if splitout or window are set, these files have to have the suffixes: _hi and _lo, meaning there will then be two me- and two mg-files.

zoncal:

When zoncal=1 and diagnos=1, zonal averages will be calculated as well. This parameter has no effect if the model is run in LAM mode.

climat_pp_cpus:

Number of cpu's used for post processing and diagnostics. On multi-node computers, current suggested values are 8 under AIX and 4 under Linux. For workstations, a value of 1 is recommended.

climat_diag_cpus:

If climat_pp_cpus is greater than 1, the diagnostics are to be performed on an multi-node computer and they will run in parallel OpenMP mode, using cpus distributed over four different parts of the diagnostics:

a)	1-5	cpu's to calculate the time series	default 4
b)	1-5	cpu's to calculate means and variances of 3D fields	default 2
c)	1-2	cpu's to calculate covariances of certain fields	default 1
d)	1	cpu to calculate means and variances of 2D fields	default 1

The number of cpu's used per part a) - d) of the diagnostics can be set with climat_diag_cpus: climat_diag_cpus="a b c d".

fularch, arch_mach,
archdir:

When fularch=oui (and ${diagnos}=1 and ${strip_phy}=1), the md-, pr-files, the diagnostics, and a restart file will be archived on ${arch_mach} (default 'pollux') in the directory ${archdir} (default '.'). If you want to run the full diagnostics you set these three parameters to avoid an overflow in your post-processing directory.

save_restart:

When save_restart=1 the restart files will be archived on ${arch_mach} in the directory ${archdir} even if ${diagnos}=0 and/or ${strip_phy}=0.

clean:

When clean=1, original files will be erased after having been archived.

gaussout:

When gaussout != 0, defines the number of grids points in the x- and y-direction for the interpolation of any global grid to a gaussian grid. The first three decimals account for the x- and the last three decimals for the y-direction. I.e. if gaussout="240120"; the grid will be interpolated to a gaussian 240x120 grid.
The default value is 0, but setting gaussout=1 requests interpolation to 192x96 gaussian grids.

rotate

When rotate != 0, vector components are rotated to geographical references so that (UU,VV) is the actual geographically oriented vector wind at the model grid points rather than the model wind. The same holds for the other vectors in the output samples. With this approach no interpolation is required to produce the full set of climate-mode diagnostics. The rotate and gaussout options are mutually exclusive, but the user must define one of them if strip_phy is requested. In addition, rotate is automatically set for all of the limited-area type of output grids such as LAM model output and for hi-resolution windows when either of splitout or window are non zero.
Again, the default value is 0.

splitout:

Only used with global variable resolution grids. In that case, when splitout=1, the high-resolution core area will be saved in files with the suffix _hi. Vector components will be rotated in that area. Meanwhile, the global grid data will be either interpolated to uniform gaussian grids according to ${gaussout} or rotated according to ${rotate}, and saved in another set of files with suffix _lo.

window:

Similar to splitout but for any model grid configuration. Cuts out a window and treats it as high resolution area. The full grid is still treated following the values of the ${rotate} (i.e. rotated vectors) and ${gaussout} (interpolated gaussian grids). Usage: window="lon1 lon2 lat1 lat2", where lon1, lon2 and lat1, lat2 are the left, right and lower, upper grid indices, respectively.

climat_llwindow:

Extracts any region with 'r.diag llagg'. All md- and pr-files for this region are saved and archived in an extra file called 'gemclimdm_${exp}_ll${suffix}.ca'. The diagnostics for this region are not called. Example: climat_llwindow="=-lon #lon =-lat #lat =-kind 1 L =-i lat_grid_size_in_degrees =-j lon_grid_size_in_degrees =-b lat_southwest_corner =-c lon_southwest_corner ". The parameters are the ones used by 'r.diag llagg'. See 'r.diag llagg' for more information.

list_mach:

All of the listings for one job will be archived and packed in a zip-file at the end of a job. By default they will be archived on ${arch_mach} in ${archdir}/${exp}_listings.zip. But you can also archive them on another machine by specifying list_mach to the machine name on which you want the listings to be saved. They will than be archived on ${list_mach} in ${HOME}/listings/${list_mach}/${exp}_listings.zip. If your ${arch_mach} is 'cfs' you will have to set 'list_mach' to another machine.

save_anal:

It is possible to save analysis files during the run. Usage: save_anal="year month increment"; an analysis file will be saved at the end of month in year and then every 'increment' months. If no 'increment' is specified an analysis file will only be saved once. If save_anal is set, 'Climat_prepare_job' sets 'anal_step' to the time step an analysis file will be saved; Climat_save_analysis saves the analysis file and puts it on 'arch_mach' in 'arch_dir'.
Analysis files always get saved on the full model gird (also in LAM mode!)

update_ghg:

If 'update_ghg=1' the values for the GHG's (CO2, N2O, CH4, CFC11, CFC12) will be updated in 'gemclim_settings.nml' according to table $gemclim/dfiles/greenhouse_gases.dat. The default is 0.
Note! This feature is only meaningful when RADIA='cccmarad' in 'gemclim_settings.nml'.

Author: Katja Winger
Last update: June 2008