ICON Training - Hands-on Session
Optional Exercise 1: Tracer Advection#
The Jablonowski-Williamson (JW) test case provides a set of four predefined tracer initial conditions which can be activated or deactivated via namelist (see the figure on the right). Here, you will learn how to enable and control the transport of passive tracers in an idealized test. See the Tutorial book, Sections 4.2.2 and 3.6.5, for details on the configuration of the tracer transport for standard NWP runs.
For simplicity, we make use of the following scripts and namelists from the previous JW exercises:
the master namelist file (icon_master.namelist)
the model namelist file for the nested setup (NAMELIST_NWP)
the ICON batch job (icon.sbatch)
- set some environment variables for this exercise
- copy the reference scripts icon_master.namelist, NAMELIST_NWP, icon.sbatch
# base directory for ICON sources and binary:
export ICONDIR=/pool/data/ICON/ICON_training/icon/
# directory with input grids:
export GRIDDIR=/pool/data/ICON/ICON_training/exercise_idealized/grids/
# absolute path to directory with plenty of space:
export SCRATCHDIR=/scratch/${USER::1}/$USER
export EXPDIR=$SCRATCHDIR/exercise_idealized/exp_JW_R02B04_adv
if [ ! -d $EXPDIR ]; then
mkdir -p $EXPDIR
fi
# visualization settings
export SCRIPTDIR=$HOME/icon-training-scripts/exercise_idealized/plot_scripts
# copy prepared Namelists and batch script
cp /pool/data/ICON/ICON_training/exercise_idealized/NAMELIST_NWP $EXPDIR/
cp /pool/data/ICON/ICON_training/exercise_idealized/icon_master.namelist $EXPDIR/
cp /pool/data/ICON/ICON_training/exercise_idealized/icon.sbatch $EXPDIR/
# grid files: link to experiment directory
ln -sf ${GRIDDIR}/icon_grid_00*.nc ${EXPDIR}/.
In the above settings we used the scratch partition of the file system, with a quota of 15 TiB (see /sw/bin/lfsquota.sh -u $USER).
#
In the namelist file NAMELIST_NWP we have omitted the namelists run_nml, nh_testcase_nml and the output namelists output_nml, as we are going to recreate them for a setup with tracers.
- Enable the transport module by activating the main switch
ltransport (run_nml) - Select the tracers number $1$ and $4$ (or all, if you like) from the set of pre-defined tracer distributions depicted in the figure above.
A specific tracer is selected by adding the respective tracer number (1,2,3, or 4) to the namelist variable
tracer_inidist_list (nh_testcase_nml). - Set the total number of tracer fields
ntracer (run_nml)accordingly. - Enable (uncomment) the namelist
transport_nml, which specifies details of the applied numerical transport schemes and limiters.
cat >> $EXPDIR/NAMELIST_NWP << EOF
! run_nml: general switches ---------------------------------------------------
&run_nml
ltestcase = .TRUE. ! idealized testcase runs
num_lev = 40,40,40 ! number of full levels (atm.) for each domain
lvert_nest = .FALSE. ! vertical nesting
dtime = 1440. ! timestep in seconds
ldynamics = .TRUE. ! compute adiabatic dynamic tendencies
ltransport = ?????????? ! main switch for large-scale tracer transport
ntracer = ?????????? ! number of advected tracers
iforcing = 0 ! pure dynamics (no physics forcing)
msg_level = 10 ! controls how much printout is written during runtime
ltimer = .FALSE. ! timer for monitoring the runtime of specific routines
output = "nml" ! main switch for enabling/disabling components of the model output
/
! nh_testcase_nml: idealized testcase specification --------------------------
&nh_testcase_nml
nh_test_name = "jabw" ! testcase selection
jw_up = 1.0 ! amplitude of u-perturbation [m/s]
tracer_inidist_list = ?????????? ! choosing from a list of predefined tracer distributions
/
! transport_nml: tracer transport ---------------------------------------------
!&transport_nml
! ivadv_tracer = 3, 3, 3, 3 ! tracer specific method to compute vertical advection
! ihadv_tracer = 2, 2, 2, 2 ! tracer specific method to compute horizontal advection
! itype_hlimit = 0, 0, 0, 0 ! type of limiter for horizontal transport
! itype_vlimit = 0, 0, 0, 0 ! type of limiter for horizontal transport
! beta_fct = 1.005 ! factor of allowed over-/undershooting in monotonous limiter
!/
EOF
- Add the selected tracers to the list of pressure level and model level output fields in the namelist
output_nml
qx, where x is a number indicating the position of the tracer within the ICON-internal 4D tracer memory.
For this testcase, tracer 1 is named q1, and so on.
These default names can be overwritten with the namelist variable tracer_names (transport_nml). See Section 4.2.2 of the tutorial for details.
cat >> $EXPDIR/NAMELIST_NWP << EOF
! output_nml: specifies an output stream --------------------------------------
! model level output on native (triangular) grid
&output_nml
filetype = 4 ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_bounds = 0., 10000000., 86400. ! output: start, end, increment
steps_per_file = 30 ! number of output steps in one output file
mode = 1 ! 1: forecast mode (relative t-axis), 2: climate mode (absolute t-axis)
include_last = .TRUE. ! flag whether to include the last time step
output_filename = 'exp3_JW' ! file name base
output_grid = .TRUE. ! flag whether grid information is added to output.
!
ml_varlist = 'u', 'v', 'w', 'temp', 'pres','topography_c', 'pres_sfc', 'vor', 'div', ?????????
/
! output_nml: specifies an output stream --------------------------------------
! pressure level output on native grid
&output_nml
filetype = 4 ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_bounds = 0., 10000000., 86400. ! output: start, end, increment
steps_per_file = 30 ! number of output steps in one output file
mode = 1 ! 1: forecast mode (relative t-axis), 2: climate mode (absolute t-axis)
include_last = .TRUE. ! flag whether to include the last time step
output_filename = 'exp3_JW' ! file name base
output_grid = .TRUE. ! flag whether grid information is added to output.
remap = 0 ! no remapping (native grid)
!
pl_varlist = 'temp', 'vor', 'div', ?????????
p_levels = 50000.,60000.,70000.,85000.,92500. ! pressure levels in Pa
/
! output_nml: specifies an output stream --------------------------------------
! model level output on regular lat/lon grid
&output_nml
filetype = 4 ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_bounds = 0., 10000000., 86400. ! output: start, end, increment
steps_per_file = 30 ! number of output steps in one output file
mode = 1 ! 1: forecast mode (relative t-axis), 2: climate mode (absolute t-axis)
include_last = .TRUE. ! flag whether to include the last time step
output_filename = 'exp3_JW_lonlat' ! file name base
output_grid = .TRUE. ! flag whether grid information is added to output.
remap = 1 ! remap to regular lat/lon grid
reg_lat_def = -90.,1.0,90. ! start, increment, end latitude in degrees
reg_lon_def = 0.,1.0,359.0 ! start, increment, end longitude in degrees
!
ml_varlist = 'u', 'v', 'w', 'temp', 'pres','topography_c', 'pres_sfc', 'vor', 'div', ??????????
/
EOF
Solution
&run_nml ltransport = .TRUE. ! main switch for large-scale tracer transport ntracer = 4 ! number of advected tracers
! nh_testcase_nml: idealized testcase specification ————————– &nh_testcase_nml nh_test_name = “jabw” ! testcase selection jw_up = 1.0 ! amplitude of u-perturbation [m/s] tracer_inidist_list = 1, 2, 3, 4 ! choosing from a list of predefined tracer distributions /
! transport_nml: tracer transport ——————————————— &transport_nml tracer_names = ‘q1’,’q2’,’q3’,’q4’ ivadv_tracer = 3, 3, 3, 3 ! tracer specific method to compute vertical advection ihadv_tracer = 2, 2, 2, 2 ! tracer specific method to compute horizontal advection itype_hlimit = 4, 0, 0, 0 ! type of limiter for horizontal transport itype_vlimit = 3, 0, 0, 0 ! type of limiter for horizontal transport beta_fct = 1.005 ! factor of allowed over-/undershooting in monotonous limiter /
&output_nml 1 ml_varlist = ‘u’, ‘v’, ‘w’, ‘temp’, ‘pres’,’topography_c’, ‘pres_sfc’, ‘vor’, ‘div’, ‘q1’, ‘q2’, ‘q3’, ‘q4’
&output_nml 2 pl_varlist = ‘temp’, ‘vor’, ‘div’, ‘q1’, ‘q2’, ‘q3’, ‘q4’
&output_nml 3 ml_varlist = ‘u’, ‘v’, ‘w’, ‘temp’, ‘pres’,’topography_c’, ‘pres_sfc’, ‘vor’, ‘div’, ‘q1’, ‘q2’, ‘q3’, ‘q4’
Running the ICON model#
sbatch.
cd $EXPDIR && sbatch --account=$SLURM_JOB_ACCOUNT icon.sbatch
Check the job status using the Slurm command squeue
Visualizaton#
ncview, as it is useful to scan through different levels and time steps. To do so, please log in with your account $USER@levante.dkrz.de using your SSH client (e.g. PuTTY). After login, first load the ncview module: module load ncview.
- Open the global domain output
$EXPDIR/exp3_JW_lonlat_DOM01_ML_0001.nc - Have a look at tracer number $4$. Initially it is constant ($=1$) everywhere. Ideally, an initially constant tracer should stay constant for all times, no matter how complicated the flow.
- Does ICON preserve a constant tracer in a run without nest?
- Does ICON preserve a constant tracer in a run with nest? Note: If a constant tracer is preserved in a two-way nested run, it is automatically preserved in a global run without nest (hence, a two-way nested run is sufficient to answer these questions).
- Have a look at tracer number $1$. The initial tracer values are in the range $0 \leq q1 \leq 0.98$. How do the global minimum and maximum values change as a function of time? Are they preserved?
Solution
Answer:Yes, the ICON transport is constancy preserving for the global domain as well as for nested domain(s). The given run is a two-way nested run, as can be inferred from the namelist variable lfeedback=.TRUE. (grid_nml). Hence the given run is sufficient to answer this question.
No, the global maximum and minimum values of q1 are not preserved over time. In particular the global minimum value falls below zero. The transport scheme is creating spurious undershoots (and overshoots) in the advected field.
- Have a look at tracer number 1. You will notice that spurious negative values emerge after some time.
- Activate an appropriate filter/limiter such that the transport scheme for tracer 1 becomes at least positive definite (i.e. $q(t)\geq 0 \,\, \forall\, t$). See the Tutorial book, Section 3.6.5, for additional help.
- Repeat the run to confirm that your settings are valid and document your settings below.
Your answer:
itype_hlimit = …
type_vlimit = …
Solution
Possible answer:
itype_hlimit = 4, 0, 0, 0
type_vlimit = 3, 0, 0, 0
Congratulations! You have successfully completed optional Exercise 1.
Further Reading and Resources#
ICON Tutorial, Ch. 4: https://www.dwd.de/DE/leistungen/nwv_icon_tutorial/nwv_icon_tutorial.html
A new draft version of the ICON Tutorial is available here: https://icon-training-2025-scripts-rendering-cc74a6.gitlab-pages.dkrz.de/index.html. It is currently being finalized and will be published soon.
Author info: Deutscher Wetterdienst (DWD) 2025 :: icon@dwd.de. For a full list of contributors, see CONTRIBUTING in the root directory. License info: see LICENSE file.