OpenIFS includes a number of idealised configurations. In this article we explain how to:
- setup and run a shallow-water model
- idealized (e.g. Rossby-Haurwitz wave) or real single level field.
- semi-Lagrangian or Euler timestepping
creating the initial fields
Configuration
The shallow-water (SW) configuration is one of several that exist in OpenIFS (and IFS). The configuration is set by the variable NCONF in namelist NAMCT0 (see yomct0.F90). The normal 3D primitive equation configuration uses NCONF=1.
For the 2D SW configuration, NCONF=201, and NCONF=202 is the vorticity equation model.
The 2D SW model can be initialised in various idealized states or from a single level real field. This initialisation is controlled by another variable, N2DINI in the namelist NAMCT0. As these idealized configurations are primarily research tools, they may vary from one major model release to another and not all options found in the code are guaranteed to work.
N2DINI = 1 in NAMCT0 will initialise the Rossby-Haurwitz wave case (Williamson et al, J. Comput. Phys., 1992).
N2DINI = 3 in NAMCT0 will initialise the SW model with real fields read from GRIB.
The reader is invited to look in suspecb.F90 to see what other initialisation options as possible.
Getting data
The SW model still needs the ICMSH (spectral fields) and ICMGG (gridpoint) files to correctly start. In the idealized case, these are read solely to set the model's spectral and gridpoint resolution and the model will overwrite the initial state read from file (see the code in suspecb.F90).
The model will require the vorticity, divergence, ln(Ps) (contains the geopotential of the free surface) and orography.
The Euler advection scheme can only be run on a regular Gaussian grid however (see below for example).
A test for the shallow-water model at spectral horizontal resolution T255 is available from the OpenIFS ftp site to try.
ftp ftp.ecmwf.int cd case_studies/shallow_water get t255_swtest.tar.gz
This example comes with initial files, namelist and job. The namelist is configured to run the semi-Lagrangian advection.
The GRIB files from an existing experiment can also be used to create initial files for the shallow-water model. In the following example, the initial files from the T21 test case distributed with the OpenIFS tarfile are used.
Note that the initial fields themselves are not used with the idealized configurations. The initial files are there to correctly set the grid, hence stl1 is used in this example to get the initial gridpoint file.
If you have access to the MARS archive at ECMWF then an example of how to retrieve single level fields is:
The following MARS request will retrieve ERA-Interim vorticity, divergence and geopotential fields together with a gridpoint field that can be used to create the initial ICMSH and ICMGG files in a similar way to the above method.
Namelists
It is extremely important to correctly set the NAMELIST to configure the shallow-water model correctly. Two examples are given here, one for semi-Lagrangian advection, the other for Euler advection. Euler advection must use a regular gaussian grid. It will not work with a reduced grid. The users is free to alter some parameters such as the timestep, filtering etc.
The examples below show the variables to change from normal forecast settings.
If using the Euler method, make sure a smaller suitable choice of timestep compared to the semi-Lagrangian setup is used. Also, ensure the Asselin time-filter is on.
Gotchas
GRIB_GRIBEX_MODE_ON
The model will fail unless the environment variable:
export GRIB_GRIBEX_MODE_ON=1
is set in the job script. This is because the shallow-water code does not go through the usual code path (if NCONF=1) and uses a older code to output.
Otherwise the model will crash at the first output attempt. Users will usually see a failure from the grib_api library (typically grib_set_real8_array).
Make sure FULLPOS is off
Related to the above, the shallow-water model does not use the FULLPOS part of the model for output (namelist NAMFPC) normally used when NCONF=1 (3D primitive equation model).
Make sure FULLPOS is off by setting:
&NAMCT0 LFPOS=false,
in the fort.4 namelist file.
Undefined fields initialized to zero
Make sure that all variables in the model are initialized to zero. The SW model can output fields that are not used.
To do this set the namelist variable:
&NAMDIM NUNDEFLD=0,
Plotting
The shallow-water model outputs fields only in spectral space. To plot the fields they will first need converting to gridpoint form.
The figure at the top of this page was generated using 'Metview'. The 'GRIB Filter' icon was used:
READ,
DATA = 'ICMSHepc9+000594',
INTERPOLATION = LINEAR FIT,
GRID = 5/5,
GAUSSIAN = REGULAR
For more information about Metview please contact openifs-support@ecmwf.int
Code notes
Other switches related to the shallow-water model setup are used internally: LR2D & LRSHW.
The IFS starts with a huge amount of setup. The setup are mainly done under the routines called su0yoma and su0yomb (all setup routines starts by su). They are themselves called by the first layer of the model cnt0. Then, the following layers cnt1, cnt2, cnt3 are called and finally, we reach cnt4 which contains the time loop. The routine which does one time step is called stepo (there are many different way of calling it as you could see in the routine cnt4).
A time step starts in spectral space (all prognostic fields are in spectral space).
A standard time step (corresponding to time t) goes as: the spectral fields (which are at time t) are transformed to GP space (Legendre inverse transform. followed by Fourier inverse transform.). Then the grid point computations start. At the end of the GP computation, the prognostic fields for next time step t+dt contain the explicit guess + half of the semi-implicit (SI) correction. This guess is transformed back to spectral space where we solve the SI problem to compute the other half of the SI correction. End of time step is reached. At the beginning of next time step, the new spectral fields will then be the new fields for the new time t.
In the routine suspecb, you can choose between idealized cases or read one level of a grib file (N2DINI is the key for this choice). suspecb is called at cnt3 level - the first part of the GP computations are done from a routine called CPG2 which is a very simplified version of the 3D GP computation, the other (lagged, mostly SL computation) are done in CPG2_LAG Both cpg2 and cpg2_lag are called by the driver routine gp_model which is also the driver routine of the 3D GP computation. - the spectral computation are done under spc.
with thanks to Nils Wedi and Sylvie Malardel, ECMWF.