This page describes the required steps to use OpenIFS/AC "v2ac-rc" on the ECMWF HPCF.

OpenIFS/AC compared to the standard OpenIFS model

OpenIFS/AC consists of the standard OpenIFS model and the additional composition software package. Both components together are referred to as OpenIFS/AC (with AC standing for "atmospheric composition"). 

The standard OpenIFS model is described in detail in the OpenIFS User Guide. The user guide introduces the model's components and supported model grids. It informs about additional required software packages and how to build the OpenIFS model. It further describes how to carry out an acceptance test after a successful model build in order to verify the model's functionality.

Additional model sources

In the standard OpenIFS model the source code for atmospheric composition (atmospheric chemistry and aerosol code) has been replaced by dummy routines. The additional model sources for OpenIFS/AC replace these dummy routines and substitute the full composition source code. It is therefore necessary to rebuild the model executable after adding the additional model source code. This process is described further below.

Additional data packages

In order to run OpenIFS with atmospheric composition a substantial number of additional input data files are required. These provide initial conditions for the chemical and aerosol fields as well as additional boundary conditions for the model, mostly in the form of emission fluxes for a number of chemical tracers. These emissions are released mostly at the model surface, however they can also be associated with emission heights (e.g. for engine emissions from global air traffic). Further information is required for the physical removal of tracers through either wet scavenging or dry deposition, the latter of which is related to the surface vegetation type as used by the land surface scheme. 

The additional data packages required for atmospheric composition modelling need to be prepared for the model at the desired grid resolution. While the standard OpenIFS model can be used with a wide range of model grids, the prepared chemical input data is only available for few selected grid resolutions and for specific time periods. If the model is to be used for other time periods or at different horizontal or vertical grid resolutions then the additional data packages need first to be generated for this purpose. 

Obtaining and compiling the code

This section contains information about where the source code package for OpenIFS/AC can be obtained and how the sources should be installed.

Working with the ftp server

You need to connect to the ECMWF ftp server to download the source package for OpenIFS/AC.  If your institution has signed the OpenIFS license agreement then you can request the ftp password by emailing openifs-support@ecmwf.int.

You can either convert your existing OpenIFS installation or create a new installation for OpenIFS/AC.  We recommend the latter and in this case you will also need the sources for the OpenIFS model (oifs43r3v2) which can be found on the ftp server. 

Connecting to the ECMWF ftp server and how to obtain OpenIFS 43r3 sources is described here in the OpenIFS User Guide.

ftp ftp.ecmwf.int
username: openifs
password:  
cd src/openifs-ac
get openifs-ac.43r3.v1.tgz
bye

Installing the OpenIFS-AC sources

In order to convert the standard OpenIFS model to OpenIFS/AC the additional software package for composition needs to be installed into an existing OpenIFS installation:

• change into your $OIFS_HOME directory where OpenIFS is installed:  cd $OIFS_HOME
• in this directory extract the downloaded source package:   tar xvzf openifs-ac.43r3.v1.tgz
  Note that this unpacking will not only add new files into $OIFS_HOME but it will also overwrite some of the existing files with new version required for OpenIFS/AC

If both the standard (meteorological) model and the atmospheric composition model are to be used at the same time, it is recommended to create a new directory for the OpenIFS/AC installation and to unpack the standard OpenIFS model sources into this directory (for instance, if the standard OpenIFS model is installed into directory 'oifs43r3', the new destination for the model sources could be extracted into directory 'openifs-ac').

Once the standard OpenIFS model code is unpacked, unpack package  openifs-ac.43r3.v1.tgz  into $OIFS_HOME, overwriting any pre-existing files from the standard model installation.

Environment settings

In order to build OpenIFS/AC the standard environment settings for oifs43r3v2 can be used with the application of two changes:

• change OIFS_HOME to point to the installation of openifs-ac (and not to the standard oifs43r3 installation)
• change OIFS_DATA_DIR to a bespoke path as the additional data packages will be added to the climate data files; we describe below what date needs to be moved to this directory
• before compiling the model sources edit $OIFS_HOME/make/oifs.fcm to enable chemistry (which is by default disabled)

It is recommend for the first two changes to use a custom configuration script to set the environment variables.

Alternatively the settings can be enabled when running the prep scripts that come with OpenIFS/AC:  For the t21 acceptance tests, the environment variables and paths are set within the oifs-config.<platform>.sh which needs to be edited in the  platform  subdirectory. This is described below.

Obtaining additional data packages

• Create a new directory (here we name this directory /data/openifs-ac) which will contain additional data that is required for atmospheric composition modelling and it will also contain the new OIFS_DATA_DIR.  

• Download the four additional data tgz archives that are required for OpenIFS chemistry experiments into /data/openifs-ac :
  ${datapath}=/nm6/oifs/

  cd /data/openifs-ac
  module load ecfs
  ecp ec:${datapath}/oifs-ac-43r3-chem.tgz .  
  ecp ec:${datapath}/oifs-ac-43r3-xtra.tgz .
  ecp ec:${datapath}/oifs-ac-43r3-initcond.tgz .
  ecp ec:${datapath}/ICMCL-2010.tgz .

• Unpack oifs-ac-43r3-chem.tgz and oifs-ac-43r3-xtra.tgz into /data/openifs-ac. This will result in the following directory structure inside /data/openifs-ac : 

• set the new environment variable for your OpenIFS/AC installation:   export OIFS_DATA_DIR=/data/openifs-ac/43r3

The following two tgz archives can be unpacked to any location, however in this example the files we will also extract them into /data/openifs-ac:

• Unpack oifs-ac-43r3-initcond.tgz into /data/openifs-ac which results in a directory /data/openifs-ac/INITIAL-CONDITIONS. The files therein are initial data files for the first day of month for all 12 months of 2010.
• Unpack ICMCL-2010.tgz into /data/openifs-ac which results in a directory /data/openifs-ac/ICMCL. This directory contains monthly files with surface boundary conditions (e.g. SSTs, soil temps, albedos, LAI etc).
• From you conventional OpenIFS installation's OIFS_DATA_DIR copy the directories ifsdata and rtables to /data/openifs-ac/43r3 as they are also needed here.
• Further, create a directory /data/openifs-ac/43r3/wam which needs to contain wave model initial data for 2010-01-01.  (presently files are copied over from cca:/lus/snx11062/scratch/ms/nl/nm6/ECE-DATA/OPENIFS/43r3)

Building the model

On the ECMWF Bull Atos Sequana HPC it is possible to compile the model using a login node. However, in order to complete the acceptance testing with chemistry an interactive node should be requested.

% ecinteractive -c 12 -m 32GB -t 06:00:00

If you have a configuration script that sets the appropriate environment for OpenIFS you should run this first before building the model executables. 

In your command line you should type   export OIFS_CHEM=enable   to overwrite the default setting in oifs.fcm (or alternatively you can edit the variable in file oifs.fcm)

Further you should make a choice whether you want to build with XIOS server support, in that case set appropriate environment variables. Otherwise set   export OIFS_XIOS=disable   to disable XIOS. 

Then compile the model using fcm (here with verbose output and with 12 parallel child processes):

cd $OIFS_HOME/make
fcm make -v -j 16 -f oifs.fcm

Only proceed further after the code has compiled and all the executables were built without errors.

Run the acceptance tests

The model package offers various tests to check the basic functionality of the model and to verify that all paths to the data directories are correct and accessible.

Overview

The acceptance tests are run on a T21 full Gaussian grid and are designed to require a minimum of computational resources. Several different tests are being offered which activate different pathways in the model source code. It is highly recommended to carry out these brief tests to verify that the model is working normally prior to using the model for forecast experiments.

The tests are located in $OIFS_HOME/t21test and t21test_xios_t255ac.

Running the tests for the first time requires editing the wrapper scripts job.sh and setup-exp.sh by setting the path to the appropriate master.exe and by changing RUNCMD to to something appropriate for the platform.

t21test:  This directory contains the original acceptance test which is provided with OpenIFS.  It should work in the same way for OpenIFS/AC as described in the OpenIFS User Guide.

t21test_xios:  This directory contains an OpenIFS acceptance test which makes use of the XIOS server – we do not describe this here.

t21test_xios_t255ac:  This directory contains the new tests for OpenIFS/AC. The test consists of a short 1-day run to demonstrate the working of OpenIFS/AC. It has a very limited set of options. Note that you cannot increase the runtime of the experiment because the provided ICMCL file does not contain data for an extended model run. The three acceptance tests in this directory make use of the additional compositon (AC) code and it is possible to run this test (a) without AC as in t21test, (b) with additional AC included, and (c) for both of the previous tests additionally XIOS server output can be selected.

Step-by-step

Here we describe the required steps to carry out the tests.

t21test:  

./job.sh -n 12 -t 2 -m ../make/gnu-opt-chem-fftw/oifs/bin/master.exe

If the oifs_run script (or the oiac_run script) is used without the --nomove option it produces an error at the end of the acceptance test, stating the ICMGGepc8+* files cannot be found. This refers to the copying of model output to output1 and the postprocessing and is therefore not relevant to the model functionality.

t21test_xios_t255ac:

First run the standard t21test for experiment epc8.  This test runs in directory $SCRATCH/43r3/epc8/ and hence the -x parameter needs to be given the absolute full path to the master.exe binary.
In setup-exp.sh change the value for RUN_NUMBER otherwise any pre-existing model output from this test will be overwritten. 

./setup-exp.sh -n 16 -t 2 -x /home/damk/oifs/model/openifs-ac/make/gnu-opt-chem-fftw/oifs/bin/master.exe

Now repeat the test with chemistry for experiment oiac. This test runs in directory $SCRATCH/43r3/oiac/. 

./setup-exp.sh -c -n 16 -t 2 -x /home/damk/oifs/model/openifs-ac/make/gnu-opt-chem-fftw/oifs/bin/master.exe

This test runs with a 30 min time step and due to the computational requirements for the added chemistry it will take much longer to complete.

Steps to carry out an experiment

Preparing an experiment

The experiment controls are in $OIFS_HOME/AC-experiments/

Here are the following scripts:

• prep-ic-icmcl-compo.sh  script to generate initial conditions for chemical fields for the selected run time. Begin and end date need to be given as an argument.
• config.h  settings for model installation, paths, and experiment configuration
• oifs-run.sh  script controls the workflow for the experiment: reads experiment config, sets up run directories (in $SCRATCH), loads platform configuration, edits namelists, links to initial conditions and executes OIFS_RUNCMD
• run-cca.job  wrapper script for oifs-run.sh, required settings for batch scheduler

In $OIFS_HOME/AC-experiments/platform:

• it is necessary to create a machine config file:  oifs-config.damk.sh  (we can re-use the one used in t21test_xios_t255ac)

Create a wrapper script to submit the batch job; in the platform directory the following templates exist:

• ecmwf-cca.job.tmpl    –    run oifs without XIOS   (try this first!)   this is virtually the same as $OIFS_HOME/AC-experiments/run-cca.job
• ecmwf-cca+xios.job.tmpl    –    run oifs with XIOS     this is virtually the same as $OIFS_HOME/AC-experiments/run-cca+xios.job
• ecmwf-cca-workflow.sh    –    workflow for a run with a series of restarts

Forecast without restarts

We begin with a batch job to run OpenIFS/AC without restarts and without XIOS.  For this purpose we modify run-cca.job:

• in run-cca.job delete the accounting PBS header line:   #PBS -l EC_billing_account=nlchekli

Edit the following lines in file config.h:

• PLATFORM='damk' or 'atos-intel'  (depending on Cray or Atos)
• OIFS_DATA_DIR= (set to your oifs data dir)
• ICMCLDIR= (set to where ICMCL directory has previously been extracted to
• OIFS_INIDATA_DIR= path_to_.../INITIAL_CONDITIONS/T255L91-tm5-none
• MET_IC_DIR= path_to_...ICMCL/aabg/2010010100

Prepare initial conditions for chemistry:

• the following script requires the substring and the grib_get commands:  On the Cray load modules sms and eccodes   (not clear for Atos?)
• run script prep-ic-icmcl-compo.sh 2010-01-01 2010-01-03  (if startdate and enddate are not given 2010-01-01 + 2 days fclength is used as default)
  (this command takes a few minutes to complete, check $PROGDIR as this presumes the location of timeint.exe)
• during the above process an experiment directory is created:  $SCRATCH/43r3/experiments/{expid}/chem_ic/  with default expid=abcd  (contains about 1.7 GB data)

Following these steps:

• submit job:  qsub ./run-cca.job

Forecast with restarts

unclear how to do that

README

                       ━━━━━━━━━━━━━━━━━━━━━━━━━
                        ATMOSPHERIC COMPOSITION
                       ━━━━━━━━━━━━━━━━━━━━━━━━━

Table of Contents
─────────────────

1. Test data
.. 1. Datasets for OIFS/AC
.. 2. Overview table of provided Initial Conditions

2. t21test_xios_t255ac
.. 1. Presentation
.. 2. How to run
.. 3. Tested configurations
.. 4. Output and diagnostics

3. AC-experiments
.. 1. Overview
.. 2. Main scripts
..... 1. Pre-processing
..... 2. OIFS run
.. 3. Configuration
.. 4. Examples
..... 1. Example 1 - A simple run
..... 2. Example 2 - Longer experiment with stop-and-restart
..... 3. Example 3 - Using a workflow script
..... 4. About performance - Long pre-processing
.. 5. Creating ICs at the end of run
..... 1. Example - A series of daily runs

4. Output

5. Using the workflow without restart

                       ━━━━━━━━━━━━━━━━━━━━━━━━━

There are two of directories for the Atmospheric Composition work. The
/t21test_xios_t255ac/ is just a test run with almost no options that you
can set. In /AC-experiments/ you can configure your experiment in
greater detail. In all cases, you need to install some additional data
for the AC work.


1 Test data
═══════════

1.1 Datasets for OIFS/AC
────────────────────────

  • You can fetch the main data dedicated to AC configurations from ECFS:
    ┌────
    │ ec:/nm6/oifs/oifs-ac-43r3-chem.tgz
    │ ec:/nm6/oifs/oifs-ac-43r3-xtra.tgz
    └────
    This will unpack to three directories: 43r3/chemistry, 43r3/climate.v015,
    and '43r3/xdata'. The second one adds input to the standard
    'ifsdata_cy43r3_climate.v015_255l.tgz'

  • Unpack them in the same directory where you unpack the default
    OpenIFS data, which should then contain:
    ┌────
    │ 43r3/chemistry      # AC specific
    │ 43r3/xdata          # AC specific
    │ 43r3/rtables        # Standard dataset for OIFS-43r3
    │ 43r3/climate.v015   # Standard dataset for OIFS-43r3 + AC specifics
    │ 43r3/ifsdata        # Standard dataset for OIFS-43r3
    │ 43r3/wam            # Standard dataset for OIFS-43r3
    └────

  • A set of initial conditions is available:
    ┌────
    │ ec:/nm6/oifs/oifs-ac-43r3-initcond.tgz
    └────
    Unpack into a directory: INITIAL-CONDITIONS

  • A set of ICMCL climatology for the years 2010 on the TL255L90 grid (kindly
    prepared by ECMWF) and few days of 2013 on TL255L60 is also needed:
    ┌────
    │ ec:/nm6/oifs/ICMCL-2010.tgz
    └────
    Unpack into a directory: ICMCL


1.2 Overview table of provided Initial Conditions
─────────────────────────────────────────────────
 
  The tested and supported configurations are:
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                           RESOL  LEVELS  LCHEM  CHEM_SCHEME  LAERO  AERO_SCHEME  START_DATE
  ───────────────────────────────────────────────────────────────────────────────────────────
   T255L60-bascoetm5-aer     255      60  true   bascoetm5    true   aer          2013-07-01
   T255L60-tm5-aer           255      60  true   tm5          true   aer          2013-07-01
  ───────────────────────────────────────────────────────────────────────────────────────────
   T255L91-tm5-aer           255      91  true   tm5          true   aer          2010-01-01
   T255L91-tm5-none          255      91  true   tm5          false  -            2010-01-01
   T255L91-bascoetm5-aer     255      91  true   bascoetm5    true   aer          2010-01-01
   T255L91-bascoetm5-none    255      91  true   bascoetm5    false  -            2010-01-01
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


2 t21test_xios_t255ac
═════════════════════

2.1 Presentation
────────────────

  • This is as close as possible to /t21test/, so they could eventually
    be combined if desired.
  • Short 1-day run to demonstrate the OIFS-AC. It has a very limited
    set of options. Note that you cannot increase the runtime of the
    'oiac' experiment because the provided ICMCL file (albedos/LAIs
    climatology) is for 2013-07-01 to 2013-07-03 only.
  • The /setup-exp.sh/ script sets the experiment up and run it.
    • Check the "Set platform and read its configuration" section, where
      the RUNDIR is defined and the OIFS env variables (same as for
      compilation) are retrieved.
    • You need a wrapper to run it on your HPC (see examples in the
      platform subdir)
    • XIOS and Chemistry are optional and can be switched on at the
      command line. For more details, read script header:
      ┌────
      │ setup-exp.sh -h
      └────
  • Possible experiments are:
    • 'epc8' on the TF21 grid (same as in t21test dir)
    • 'oiac' on the TL255 grid, which uses a modified CB05 chemistry
      scheme (referred to as TM5) and the AER aerosol scheme on 60
      levels. You can switch on the BASCOE chemistry scheme by editing
      the CHEM_SCHEME variable in the /setup-exp.sh/.


2.2 How to run
──────────────

  • create a wrapper job script that you will submit to your job
    manager. The job script must set OMP_NUM_THREADS, NPROC, and
    OIFS_RUNCMD (which probably differs if you are using XIOS or not),
    and call /setup-exp.sh/. See examples in:
    ┌────
    │   runtime/platform/*job.tmpl
    └────
  • create a platform configuration file in:
    ┌────
    │   runtime/platform/oifs-config.${platform}.sh
    └────
  • set the platform variable in /setup-exp.sh/ (line 89)
  • submit


2.3 Tested configurations
─────────────────────────

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                   cca-cray  
  ────────────────────────────
   t21             ok        
   t21 + xios      ok        
   tm5/aer         ok        
   tm5/aer + xios  ok        
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━


2.4 Output and diagnostics
──────────────────────────

  Diagnostics - At the end of 'oiac' experiment, a couple of budgets are
  gathered. These can be compared with previously run results, which are
  included in the 'ctrl' directory. For example, if you expect the exact
  same result, you could:
  ┌────
  │ EXPID=oiac; RUNDIR=${SCRATCH}/${OIFS_CYCLE}/${EXPID} ;  RUN_NUMBER=3  #checkoifs
  │ fref1=${OIFS_HOME}/t21test_xios_ac/ctrl/massdia_chem__oiac_2013070100.txt
  │ fref2=${OIFS_HOME}/t21test_xios_ac/ctrl/ozonbud_chem__oiac_2013070100.txt
  │ fnew1=${RUNDIR}/output${RUN_NUMBER}/massdia_chem_oiac.txt
  │ fnew2=${RUNDIR}/output${RUN_NUMBER}/ozonbud_chem_oiac.txt
  │ diff $fref1 $fnew1
  │ diff $fref2 $fnew2
  └────

  Output:
  • ${RUNDIR}/output${RUN_NUMBER} : contains log, chem diagnostics, and
    GG+SH grib files if not using XIOS.
  • ${RUNDIR}/xios_output : has netcdf files if using XIOS.

  For pointers to handle the output on the reduced Gaussian grid, see
  the Output section below.


3 AC-experiments
════════════════

3.1 Overview
────────────

  In the AC-experiments directory, you will find:
  • low level scripts, in the /scripts/ subdirectory. Several of them
    provides a set of functions, like a library.
  • two main level scripts, one for pre-processing and one for running
    OIFS
  • one high level workflow script, which is mainly an example, known to
    work at ECMWF.

  Here's an overview:
  ┌────
  │ AC-experiments
  │       ├── config.h                      # Config file
  │       ├── ctrl
  │       │   ├── context_ifs.xml           # xios resource
  │       │   ├── ifs_xml                   # xios resource
  │       │   ├── iodef.xml                 # xios resource
  │       │   ├── namelist.ifs.sh           # script to generate OIFS namelist
  │       │   └── Table                     # dir with AC tracers definition tables
  │       │
  │       ├── oifs-run.sh                   # Main script to setup rundir and launch OIFS executable
  │       ├── prep-ic-icmcl-compo.sh        # Main script to gather IC/ICML/ICMCL-COMPO
  │       │
  │       ├── platform
  │       │   ├── ecmwf-cca.job.tmpl        # job template to run without xios (PBSpro, qsub)
  │       │   ├── ecmwf-cca+xios.job.tmpl   # job template to run with xios    (PBSpro, qsub)
  │       │   ├── ecmwf-cca-workflow.sh     # Example workflow script for run with series of restarts
  │       │   ├── knmi-rhino.job.tmpl       # job template to run without xios (SLURM)
  │       │   ├── oifs-config.ecmwf-cca.sh  # platform environment (ECMWF)
  │       │   └── oifs-config.knmi-rhino.sh # platform environment (KNMI)
  │       │
  │       └── scripts                       # Set of low levels scripts
  │           ├── add_nrt_fire_chem
  │           ├── gaussgr
  │           ├── get_alb_lai_intLimits
  │           ├── get_tablecol
  │           ├── grib_def.h
  │           ├── lib_general.sh            # lib of utilities
  │           ├── lib_chem_setup.sh         # lib of functions to create the AC namelists
  │           ├── lib_icmcl_clima           # lib of functions to create ICMCL files
  │           ├── lib_icmcl_compo           # lib of functions to create ICMCL-COMPO files
  │           └── lib_initcond.sh           # lib of functions to create Initial Conditions (IC) files
  └────


3.2 Main scripts
────────────────

  There are two main scripts to setup and run an experiment. Although
  experiments are configured by editing /config.h/, few script arguments
  and options allow for a flexible workflow.


3.2.1 Pre-processing
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  The /prep-ic-icmcl-compo.sh/ script prepares the Initial Conditions,
  the climatology, and the atmospheric composition fluxes before you run
  OIFS. The main purpose is to create or copy three sets of files (IC,
  ICMCL and ICMCL-COMPO) needed to run an experiment. Paths to find
  those files are set in the /config.h/. See the section DATASETS in
  that file for details. Note that it is possible to use different data
  than those provide to test OpenIFS/AC but keep in mind this requires
  access to MARS archives at ECMWF.
  ┌────
  │  Usage:
  │         prep-ic-icmcl-compo.sh  START_DATE  END_DATE
  │
  │  Setup or create in $AC_IC_DIR:
  │
  │    - Initial Conditions for START_DATE (if not continuing/restarting a run)
  │         ICs are looked for in $OIFS_INIDATA_DIR. If not found, they are created.
  │
  │    - ICMCL climatology file for START_DATE to END_DATE.
  │         If $ICMCLDIR dir is set (in config.h), the ICMCL file is linked
  │         from $ICMCLDIR/ICMCL-yyyymm0100
  │         (Note: can contain data for dates before or after those required)
  │
  │    - ICMCL-COMPO (Emissions and Depositions) for START_DATE to END_DATE.
  │         ICMCL-COMPO are looked for in $OIFS_INIDATA_DIR. If not found, it is created.
  │
  │         (If \$AC_IC_DIR/ICMCL-INIT-COMPO-... exists, it will not be
  │         created again. This allows for faster re-run when developing.)
  │
  │  START_DATE, END_DATE:
  │    - Must be in a format understood by 'date -d' (eg 2010-12-15)
  │
  └────

  Note that:

  • If prepared beforehand, ICMCL and ICMCL-COMPO can contain data for dates
    before or after those requested, but filename formats expected BY THIS
    SCRIPT are:
    = ICMCL       : ICMCL-yyyymm0100
    = ICMCL-COMPO : ICMCL-INIT-COMPO or ICMCL-INIT-COMPO-START_DATE-END_DATE (with dates in YYYYMMDDhh)

  • $OIFS_INIDATA_DIR, $ICMCLDIR and $AC_IC_DIR are set in /config.h/


3.2.2 OIFS run
╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  The /oifs-run.sh/ script reads the experiment setup (config.h), sets a
  rundir up (if not already done) and launch the OIFS executable to
  start or continue the experiment.

  You will need a wrapper around /oifs-run.sh/ to define
  OMP_NUM_THREADS, OIFS_NPROC, and OIFS_RUNCMD, and sent it to your HPC
  compute nodes. Some example wrappers, working with and without XIOS:
  • AC-experiments/platform/ecmwf-cca.job.tmpl
  • AC-experiments/platform/ecmwf-cca+xios.job.tmpl


3.3 Configuration
─────────────────

  There is a lot of comments in the /config.h/ to explain what the
  different entries are. A few words about the main AC keys:

  To activate chemistry, set:
  • LCHEM=true
  • choose chemistry scheme (tm5 or bascoetm5) and corresponding table
    version:
    • CHEM_SCHEME = tm5 or bascoetm5
    • CHEM_VER = ver15 or ver2f

  And to activate aerosols:
  • LAERO=true
  • if not, LCHEM_AEROI (use MACC to get aerosol scattering/absorption)
    must be set to false
  • choose aerosol scheme and corresponding table version:
    • AERO_SCHEME = aer
    • AERO_VER = ver1


3.4 Examples
────────────

3.4.1 Example 1 - A simple run
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  • Configure your experiment by editing /config.h/. To run a 10-day
    experiment day, use:
    ┌────
    │ run_start_date="2010-01-01"
    │ run_end_date="2010-01-11"
    └────
    The restart frequency should be longer than the run, eg:
    ┌────
    │ rst_freq="1 month"
    └────

  • Create or gather ICs:
    ┌────
    │ prep-ic-icmcl-compo.sh  2010-01-01  2010-01-11
    └────
    It is recommended to run it on a compute node, if the ICMCL-COMPO
    has to be created.

  • Then submit a job to launch an oifs executable.
    ┌────
    │ {qsub, sbatch,...} wrapper.sh
    └────


3.4.2 Example 2 - Longer experiment with stop-and-restart
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  • Define your experiment by editing /config.h/. To run a 2-month
    experiment with a stop-and-restart after the 1st month (ie 2
    legs/chunks of 1 month), just set:
    ┌────
    │ run_start_date="2010-01-01"
    │ run_end_date="${run_start_date} + 2 months"
    │ rst_freq="1 month"
    │ USE_RESTART=true
    └────

  • Create or gather ICs for every leg:
    ┌────
    │ prep-ic-icmcl-compo.sh  2010-01-01 2010-02-01
    │ prep-ic-icmcl-compo.sh  2010-02-01 2010-03-01
    └────
    These can be run in parallel. But if ICMCLDIR is not provided, then
    ICMCL climatology needs to be created, and you have to wait that the
    first job is finished before starting the others (which can then run
    in parallel).

  • Submit your wrapper-around-oifs-run once:
    ┌────
    │ {qsub, sbatch} wrapper.sh
    └────
    Wait until it is finished, then resubmit it again to simulate the
    second month. No need to edit your /config.h/, it will pickup where
    it stopped.


3.4.3 Example 3 - Using a workflow script
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  The 4 jobs in the previous example, can be all triggered automatically
  and in a timely fashion with a single script. The
  /platform/ecmwf-cca-workflow.sh/ provides an example that works on
  cca@ECMWF.

  • Define a 2-month experiment with a stop-and-restart after the 1st
    month:
    ┌────
    │ run_start_date="2010-01-01"
    │ run_end_date="${run_start_date} + 2 months"
    │ rst_freq="1 month"
    └────

  • Create and queue jobs with correct dependencies:
    ┌────
    │ ./workflow-cca.sh
    └────


3.4.4 About performance - Long pre-processing
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  ICMCL-COMPO could be prepared for the entire run at once. In the
  example 2 above, it would be done with:
  ┌────
  │ prep-ic-icmcl-compo.sh 2010-01-01 2010-03-01
  └────
  Then you simulate the two legs one after the other, like above. There
  is no advantage in doing that. Indeed, the creation of the ICMCL-COMPO
  can be quite expensive (~15 min for two days!). Better to limit it to
  monthly or daily files that can be stitched together afterwards if needed.


3.5 Creating ICs at the end of run
──────────────────────────────────

  When setting LAC4IC=true, an AC-for-IC grib file is created at the end
  of a run. It is a snapshot of all AC tracers, which can be used by the
  pre-processing script to create Initial Conditions. The main
  requirement is:
  • no netCDF output (LXIOS=false)

  With the AC-for-IC file, you can create IC for a new experiment, which
  will continue from the previous experiment as far as AC tracers are
  concerned. The meteo fields to complete the IC can come from an
  archived experiment or a set of standard meteo IC. This workflow is
  desirable when you want to reinitialize your integration with an
  updated weather forecast (which does not provide AC tracers) for
  example.


3.5.1 Example - A series of daily runs
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  • Configure your 1st day experiment:
    ┌────
    │ run_start_date="2010-01-01"
    │ run_end_date="2010-01-02"
    └────
    With a restart frequency equal or longer than the run, you can
    switch off the creation of restart:
    ┌────
    │ rst_freq="1 month"
    │ USE_RESTART=false
    └────
    • Create ICs
      ┌────
      │ prep-ic-icmcl-compo.sh  2010-01-01  2010-01-02
      └────
    • Then submit a job to launch oifs executable
      ┌────
      │ {qsub, sbatch} wrapper.sh
      └────

      This will create an extra file we will use in the next day
      experiment:
      ┌────
      │ AUXFILE=${RUNDIR}/output/001/ICMUA${EXP}.ac_rst
      └────

  • Configure your next day experiment, with a new name (or after
    removing the previous rundir - after moving away the AUXFILE!):
    ┌────
    │ EXP=bcde
    │ run_start_date="2010-01-02"
    │ run_end_date="2010-01-03"
    └────
    In the /config.h/, be sure to:
     - set OIFS_INIDATA_DIR to nothing, or comment it.
     - set the variable AC_IC_ONCE to the AUXFILE from the previous exp.
     - set the MET_IC_DIR or modify the "variables to retrieve METEO initial
       conditions from an archived experiment" section as you see fit.

    • Create ICs
      ┌────
      │ prep-ic-icmcl-compo.sh  2010-01-02  2010-01-03
      └────
    • Then submit a job to launch oifs executable
      ┌────
      │ {qsub, sbatch} wrapper.sh
      └────
      This will create an extra file for another run:
      ┌────
      │ AUXFILE=${RUNDIR}/output/001/ICMUA${EXP}.ac_rst
      └────

  • Etc.


4 Output
════════

  Output data are on the reduced grid - which is an unstructured grid in the
  netcdf files. To go further, you may want to remap the output.  This can be
  achieved with /cdo/. The procedure is slightly different for grib and netCDF
  files. Check the scripts in the /postproc/ directory for examples dealing
  with grib files. For netCDF files, you must set a grid (grid descriptions
  are available in the /ctrl/ directory) before remapping:
  ┌────
  │ cdo -L setgridtype,regular -setgrid,${OIFS_HOME}/t21test_xios_ac/ctrl/TL255-griddes.txt \
  │      AMIP_6h_reduced_ml.nc oiac_6h_reduced_ml.nc
  └────

  Note that available UV-processor output is an experimental product, which is
  currently not filled (just zeroes). It concerns two variables: uvp2drad
  (gribcode 210055) and toaer340 (gribcode 210056)