OpenIFS includes a number of idealised configurations. In this article we explain how to:

  • setup and run a shallow-water model
  • set idealized (e.g. Rossby-Haurwitz wave) or real single level field.
  • enable semi-Lagrangian or Euler timestepping

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

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 (N2DINI=42 does not work).

Although there is mention of NCONF=202 (the Vorticity Equation configuration) in the code, this does not work.

Warning: code changes required for OpenIFS 38r1

OpenIFS 38r1 (all versions) require code changes in order to be able to run with N2DINI=3 (initialized with real fields). Please see Code Changes below.

On this page...

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 requires the vorticity, divergence, ln(Ps) (contains the geopotential of the free surface) and orography when starting from real fields.

The Euler advection scheme can only be run on a regular Gaussian grid (see below for example) whereas the semi-Lagrangian advection is normally run on the reduced Gaussian grid.

T255 shallow-water test case

A test for the shallow-water model at spectral horizontal resolution T255 is available from the OpenIFS ftp site to try. Note: Only licensed institutes are provided with the userid/password to access the OpenIFS ftp site.

ftp ftp.ecmwf.int
cd case_studies/shallow_water
get t255_swtest.tar.gz

This example comes with initial files, namelist and job script. The namelist is configured to run the semi-Lagrangian advection. A few lines in the job script may need altering for your local setup.

Creating initial fields from existing GRIB files

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.

Extract starting files from existing experiment 
#  Extract a single level (level 1) for the shallow water model
#  and change the experiment id in the file.

expid="epc8"
newid="sw01"

grib_copy -w level=1,shortName=vo ICMSH${expid}INIT tmp
grib_set -s experimentVersionNumber="$newid" -w experimentVersionNumber="$expid" tmp vo.grb

grib_copy -w level=1,shortName=d  ICMSH${expid}INIT tmp
grib_set -s experimentVersionNumber="$newid" -w experimentVersionNumber="$expid" tmp d.grb

grib_copy -w shortName=z   ICMSH${expid}INIT z.grb

#  Combine the 3 files to form the spectral initial file
cat vo.grb d.grb z.grb  >  ICMSH${newid}INIT

#  Create gridpoint file (stl1 is used in this example)
grib_copy -w shortName=stl1 ICMGG${expid}INIT gg.grb
grib_set -s experimentVersionNumber=${newid} -w experimentVersionNumber=${expid} gg.grb ICMGG${newid}INIT

For idealized configurations the field in the initial data file is used correctly set the grid. The actual values are overwritten by the model code to set the idealized start. Hence stl1 is used in this example to for the initial gridpoint file because its values will be overwritten and not used to initialize the model fields.


If you have access to the MARS archive at ECMWF then an example of how to retrieve single level fields for use with the SW model is:

The following MARS request will retrieve ERA-Interim (T255) 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.

Change the model level if required.

Retrieve spectral fields from MARS for shallow-water model 
retrieve,
  class=ei,
  type=an,
  stream=oper,
  date=20100212,
  time=12,
  step=0,
  expver=1,
  param=VOR/D/Z,
  levelist=1,
  levtype=ml,
  target="sh_ml"
Retrieve gridpoint field from MARS for shallow-water model 
 retrieve,
  class=ei,
  type=an,
  stream=oper,
  date=20091227,
  time=12,
  step=0,
  expver=1,
  param=139,
  levelist=off,
  levtype=sfc,
  target="sfc_gg"

and then set the appropriate ICMSH and ICMGG file names and experiment number as shown in the previous example.

Namelists

It is extremely important to correctly set the NAMELIST to configure the shallow-water model.

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

semi-Lagrangian advection namelist (43r3) 
!  Shallow-water model with semi-Lagrangian advection.
!  The variables below must be set in order to correctly configure
!  the shallow-water model.
!  Other variables (if present) can be left as-is.

For namelist : NAMDYN
 HDIRVOR=1.e15,        ! horizontal diffusion parameters
 HDIRDIV=1.e15,        ! see code for further description
 HDIRSP=1.e15,
 LHDIFFM=true,
 NDIFFACT=6,
 LSETTLS=true,         ! ensure SL scheme is enabled
 LSETTLST=true,
 SITR=350.,            ! reference temperature
 REFGEO=78452.0,       ! reference geopotential for shallow-water model

For namelist: NAMCT0
 NFPOS=0,              ! disable fullpos post-processing
 N2DINI=1,             ! 2D initialisation switch
 LTWOTL=true,          ! enable two-time level SL scheme
 LSLPHY=false,         ! turn off Sl physics option
 LSPRT=false,          ! turn off 'virtual temperature' as spectral variable
 NFRHIS=10,            ! frequency of results output
 NUNDEFLD=0,            ! make sure uninitialised variables are all set to zero

For namelist: NAMARG
 NCONF=201,            ! select shallow-water configuration
 LSLAG=true,           ! enable SL scheme
 UTSTEP=1800.0,         ! model timestep (resolution dependent)

For namelist: NAMPAR0
 NPROC=1,              ! only use 1 MPI process in 2-D.
 NPRGPEW=1,            ! required for 2-D configurations

For namelist: NAEPHY
 LEPHYS=false,           ! turn off ECMWF Physics package (master switch)
 LERADI=false,           ! turn off radiation scheme

For namelist: NAMDYNA
 LGRADSP=.false.,        ! disable de-aliasing the pressure gradient term
 LRFRIC=false,         ! turn off Rayleigh friction
semi-Lagrangian advection namelist (40r1) 
!  Shallow-water model with semi-Lagrangian advection.
!  The variables below must be set in order to correctly configure
!  the shallow-water model.
!  Other variables (if present) can be left as-is.

For namelist : NAMDYN
 HDIRVOR=1.e15,        ! horizontal diffusion parameters
 HDIRDIV=1.e15,        ! see code for further description
 HDIRSP=1.e15,
 LHDIFFM=true,
 NDIFFACT=6,
 TSTEP=1800.0,         ! model timestep (resolution dependent)
 LSETTLS=true,         ! ensure SL scheme is enabled
 LSETTLST=true,
 SITR=350.,            ! reference temperature
 REFGEO=78452.0,       ! reference geopotential for SW model

For namelist: NAMCT0
 LRFRIC=false,         ! turn of Rayleigh friction
 LFPOS=false,          ! disable fullpos post-processing
 N2DINI=1,             ! 2D initialisation switch
 NCONF=201,            ! select shallow-water configuration
 LTWOTL=true,          ! enable two-time level SL scheme
 LSLAG=true,           ! enable SL scheme
 LSLPHY=false,         ! turn off Sl physics option
 LSPRT=false,          ! turn off 'virtual temperature' as spectral variable
 NFRHIS=10,            ! frequency of results output

For namelist: NAEPHY
 LEPHYS=false,           ! turn off ECMWF Physics package (master switch)
 LERADI=false,           ! turn off radiation scheme

For namelist: NAMDYNA
 LGRADSP=.false.,        ! disable de-aliasing the pressure gradient term

For namelist: NAMDIM
  NUNDEFLD=0,            ! make sure uninitialised variables are all set to zero
Euler advection namelist 
!  Shallow-water model with Euler advection.
!  The variables below must be set in order to correctly configure
!  the shallow-water model.
!  Other variables (if present) can be left as-is.

For namelist: NAMDYN
 TSTEP=300.0,               ! reduce timestep for Euler stepping
 REPS1=0.01,                ! turn on Asselin time-filtering coefficient
 REPS2=0.01,
 LHDIFFM=.false.,           !  horizontal diffusion on / off
 LSETTLS=.false.,           ! extrapolations in SL scheme
 LSETTLST=.false.,          ! ditto

For namelist: NAMCT0
 NCONF=201,                 ! model configuration: 201 = shallow-water (see yomct0.F90)
 LSLAG=.false.,             ! turn off semi-lagrangian scheme
 LTWOTL=.false.,            ! disable two-time-level SL scheme.
 LRFRIC=.false.,            ! turn off Rayleigh friction
 LSLPHY=.false.,            ! turn off split time-step physics
 LVERTFE=.false.,           ! turn off vertical finite element scheme
 N2DINI=1,                  ! initialise  1 = Haurwitz wave, 2 = real fields
 LSPRT=.false.,             ! if T temperature is 'virtual temperature'
 LFPOS=false,               ! turn off fullpos diagnostics, does not work with SW
 N3DINI=0,                  ! no 3D initialisation
 NSTOP=600,                 ! no. of steps to run
 NFRHIS=10,                 ! frequency of results output

For namelist: NAEPHY
 LEPHYS=false,           ! turn off ECMWF Physics package (master switch)
 LERADI=false,           ! turn off radiation scheme

For namelist: NAMDYNA
 LGRADSP=.false.,        ! disable de-aliasing the pressure gradient term

For namelist: NAMDIM
  NUNDEFLD=0,            ! make sure uninitialised variables are all set to zero


Also, add a blank namelist to fort.4 for the idealized cases. Some configurations selected using N2DINI will expect to find a namelist NAMSWE.

&NAMSWE
/


Gotchas

There are a number of issues that can cause the model to fail. Please make sure:

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 uses a different set of subroutines for output and does not go through the usual code path for 3D forecasts (if NCONF=1).

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, only ICMSH output files are generated. 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:

Metview GRIB filter icon example for plotting spectral data
READ,
    DATA       = 'ICMSHepc9+000594',
    INTERPOLATION = LINEAR FIT,
    GRID       = 5/5,
    GAUSSIAN   = REGULAR

For more information about Metview please see Using Metview with OpenIFS or contact openifs-support@ecmwf.int.

Code changes

if running OpenIFS 38r1 (all versions), code changes are required before using the shallow water option initialized with real fields (N2DINI=3 & NCONF=201).

Changes are required because the shallow-water code uses older code for reading GRIB data that was omitted from OpenIFS before the shallow-water option was made available.

Required steps to enable shallow-water code option

  • Download the OpenIFS 38r1 shallow-water replacement source tarball: openifs38r1_sw_newsrc.tgz
    (this file is also available on the OpenIFS ftp site)

  • Make a backup copy of the OpenIFS source code  in the directory where the OpenIFS model files were unpacked:

    cp -r src src.orig

  • Delete some files that will be replaced:

    rm src/openifs/dummy/decops2.f90
rm src/openifs/dummy/gribex.f90
rm src/openifs/emos/pbio/emosnum.F
rm src/openifs/emos/pbio/fortint.h
rm -r src/openifs/emos/gribex		# delete entire 'gribex' director

  • Unpack the tarfile downloaded above. This will create a new directory 'src/openifs/emos/gribex'.
    Make sure the tarfile is in the top level directory that contains 'src':

    # Make sure openifs38r1_sw_newsrc.tgz is in the directory that contains 'src.
tar xzvf openifs38r1_sw_newsrc.tgz

    Verify that 'src/openifs/emos/gribex' exists and contains source code.

  • To compile the code if using GNU/gfortran, it may be necessary to enable the use of cray pointers.
    Edit 'make/oifs.cfg' and change:

    oifs.prop{fc}       = $OIFS_FC

    to:

    oifs.prop{fc}       = $OIFS_FC -fcray-pointer

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 setups are mainly done under the routines called su0yoma and su0yomb (all setup routines start with '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 the 2D configurations calling spc2.


with thanks to Nils Wedi and Sylvie Malardel, ECMWF.





3 Comments

  1. Zhenqian Wang

    Hi ,

    I'm wondering whether if i can creating initial file(ICMSH${expid}INIT) from existing NetCDF files?

    I would like to design some sensitivity experiments, so i wont to create the initial file by NetCDF, i have tried to convert the *.nc to *.grb and replace the variables in existing initial file, but it didn't work, could some one tell me how to do it?

    Best regards,

    Zhenqian


    wangzhenqian@wangzhenqiandeMacBook-Pro 19900101 % cdo replace ICMSHECE3INIT T255_no_TP300_mulc9.8_chname.grb 123 

    cdo    replace (Warning): Variable Z not found!

    cdo    replace: Processed 3642358 values from 42 variables over 2 timesteps [0.03s 9640KB].

    1. Marcus Koehler

      Dear Zhenqian Wang,

      Is your question in connection with a shallow water experiment or does it relate to anything written on this confluence page?

      If you have a generic question then I recommend that you post it in an appropriate OpenIFS user forum section please.  When it is visible in the user forum then other OpenIFS users can find your question and they can try to help you.  

      Once you have posted your query in the forum I will delete it here, because comments added to a confluence page should be specifically about its content.

      Many thanks, Marcus

      1. Zhenqian Wang

        Dear @Marcus Koehler,

        Thank you for your kind tips.  As following, I guess the author may know how to made the initiation files. I will move it to the forum.

        Best regards,

        Zhenqian

        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 requires the vorticity, divergence, ln(Ps) (contains the geopotential of the free surface) and orography when starting from real fields.