Contents:
Table of Contents |
---|
This page contains a guide for building and using OpenIFS 48r1 at model version 48R1.1.
We describe how to build the model and carry out a few basic tests, how to run an example forecast experiment, for which initial experiment data is made available, and how to visualise the model output by creating plots.
Info |
---|
Worked Example: We explain the model installation and the process of running of a forecast experiment on the ECMWF Atos Sequana XH2000 HPC facility (hpc2020).
It is important to note that the installation process on hpc2020 will not directly translate to alternative systems. To address this we present details about a docker install in the last section of this guide. |
Access requirements
OpenIFS is licensed software and using the model requires your affiliation with an institute that has signed the ECMWF OpenIFS software licence agreement.
In order to access the model sources and other required data packages, you need to have a personal ECMWF account which you can create on the ECMWF web site or by clicking here.
If you are a new model user you should in the first instance contact OpenIFS support (by emailing openifs-support@ecmwf.int) requesting access to OpenIFS by providing the following information: your full name, your affiliation and related institutional email address, and your ECMWF account user name. OpenIFS staff will then activate OpenIFS user policies for your personal ECMWF account. In some cases we may need to request additional verification of your affiliation with your licensed institute prior to giving you access.
Extract the OpenIFS package
Create your local installation of OpenIFS 48R1.1 by downloading and extracting the tarball containing the model source package.
The tarball can be downloaded from this web site: https://sites.ecmwf.int/openifs/openifs-data/src/48r1/openifs-48r1.tar.gz. Please note that access to this web site is restricted to registered OpenIFS users, i.e. your personal ECMWF account must have been added to the OpenIFS user policy.
In the example below we assume that the OpenIFS model shall be installed in the user's HOME
directory, and that the wget
utility is available for convenient download:
Code Block | ||||
---|---|---|---|---|
| ||||
cd $HOME
wget https://sites.ecmwf.int/openifs/openifs-data/src/48r1/openifs-48r1.tar.gz
tar -xvzf openifs-48r1.tar.gz |
Note |
---|
|
Set up the platform configuration file
The OpenIFS model requires a number of Linux environment variables to be set for both installation and runs. These are referred to as global environment variables.
The most important environment variable is OIFS_HOME
, which is required by all scripts used by the model.
OIFS_HOME
describes the location of the OpenIFS model installation and is general the path where the git repository was extracted. For example, if you clone the repository into your $HOME directory then you should set:
Code Block | ||||
---|---|---|---|---|
| ||||
export OIFS_HOME=$HOME/openifs-48r1.1/ |
The other model environment variables are
OIFS_CYCLE
- describes the model cycle (e.g. 48r1) for which this configuration file can be used - this should not be editedOIFS_EXPT
- path to the location of the openifs experiments. Setting this is a convenience for the OpenIFS 3D model but is a requirement for the SCM experimentsOIFS_ARCH
- if available on for a system, this variable describes the location of the arch directory, which provides specific information about the system and compiler, e.g.$OIFS_HOME/arch/ecmwf/hpc2020/gnu
- Such a directory is not always required, i.e., if a system has all the appropriate libraries installed. If this is the case
OIFS_ARCH
can be set to an empty string, i.e.,OIFS_ARCH=""
- Such a directory is not always required, i.e., if a system has all the appropriate libraries installed. If this is the case
OIFS_DATA_DIR
- describes the location of climatological input files that are required to run OpenIFS. These have been installed on the ECMWF hpc2020 in a central and accessible location under/perm/openifs/oifs_data
and the information is organised by model cycle.
Note |
---|
If you do not have access to the ECMWF hpc2020 file system, or if you wish to install the climatological input files in a local directory of your choice, then you can download the required data from this site: https://sites.ecmwf.int/openifs/openifs-data/ifsdata/48r1/ As a minimum you will require the packages Download and extract these files to your chosen location, the filepath of which should then be set to variable |
OIFS_EXEC
- describes the location and file name for the OpenIFS 3D executable, e.g.$OIFS_HOME/build/bin/ifsMASTER.DP
, which is a double-precision executable for the 3D model
All the global environment variables described above, as well as some other variables that are dependent on the above, are defined in the Platform configuration file, which needs to be modified for your local OpenIFS installation.
- This file can be located anywhere on your file system, however the recommended default location
is $OIFS_HOME
. - We provide
$OIFS_HOME/oifs-config.edit_me.sh
, which is a commented template of this configuration file. - You should edit this file and update the path set in variable
OIFS_HOME
with your installation's path.
Once edited the platform configuration file is loaded using the following command:
Code Block | ||||
---|---|---|---|---|
| ||||
source /path/to/file/location/oifs-config.edit_me.sh
# using our installation example:
# source $HOME/openifs-48r1.1/oifs-config.edit_me.sh |
We recommend to include this command in your Linux shell startup configuration (e.g. in .bashrc).
The above command should also be include in any batch job scripts that are intended to run OpenIFS (described in Section 3)
Note |
---|
|
Build OpenIFS
In the next step the model binary executable (and other helper programs) will be built.
OpenIFS build system
In contrast to earlier model versions, the building of OpenIFS 48r1 is no longer based on the FCM configuration manager; instead, the build system for OpenIFS is now based on the same ecbuild / CMake system used for the ECMWF IFS model.
Similar to the IFS, OpenIFS 48r1 also employs a software bundle which, as part of the build process, automatically finds, downloads and installs many of the required software packages, e.g., ecbuild, ecCodes, metkit, etc. Hence, a separate installation of these libraries is no longer required as they have now become part of the OpenIFS distribution.
Starting the build process
The $OIFS_HOME/scripts/build_test/openifs-test.sh
script can be used to build the model and run initial tests.
- The script requires key environment variables, such as $OIFS_HOME, to be assigned. Make sure you have sourced the platform configuration script first.
- The usage of the script is shown with the command:
openifs-test.sh -h
Run the build process and the tests using the following commands (assumes the platform configuration file has been sourced) :
Code Block | ||||
---|---|---|---|---|
| ||||
cd $OIFS_HOME
$OIFS_TEST/openifs-test.sh -cbt |
where
Info |
---|
|
and the command line options are
Info |
---|
|
If everything has worked correctly then all tests should have passed and the script returns the following
Code Block | ||||
---|---|---|---|---|
| ||||
[INFO]: Good news - ctest has passed
openifs is ready for experiment and SCM testing
----------------------------------------------------------------
END ifstest on OpenIFS build |
Set up a forecast experiment
An example forecast experiment has been prepared for OpenIFS 48r1. The experiment ID is ab2a.
Extract the example forecast experiment ab2a.tar.gz
into a folder in a location suitable for model experiments. The global OpenIFS configuration file (oifs-config.edit_me.sh
) sets the variable OIFS_EXPT
which should point to the root directory for your OpenIFS experiments. You should extract ab2a.tar.gz
to this location, and this folder will become your experiment directory.
Info |
---|
The experiment directory would ideally be in a different location from the earlier model installation path |
Example:
On the ECMWF hpc2020 our model has been previously installed to $OIFS_HOME
which is in $HOME/openifs-48r1.1
. For the experiment we extract the ab2a package to $OIFS_EXPT
which is in a different location on the file system. The experiment directory shall therefore be $OIFS_EXPT/ab2a/2016092500
.
Code Block | ||||
---|---|---|---|---|
| ||||
cd $OIFS_EXPT
wget https://sites.ecmwf.int/openifs/openifs-data/case_studies/48r1/karl/ab2a.tar.gz
tar -xvzf ab2a.tar.gz |
Ensure the namelist files for the atmospheric model (fort.4) and for the wave model (wam_namelist) are found in the experiment directory. If they are not already there then you can find them in a subfolder (called ecmwf
) inside the experiment directory.
Code Block | ||||
---|---|---|---|---|
| ||||
cd $OIFS_EXPT/ab2a/2016092500
cp ./ecmwf/fort.4 .
cp ./ecmwf/wam_namelist . |
You will need to copy three further scripts from the OpenIFS package into your experiment directory:
oifs-run:
this is a generic run script which executes the binary model program file.exp-config.h:
this is the experiment configuration file that determines settings for your experiment. It will be read by oifs-run.run
.ecmwf-hpc2020.job:
this is the wrapper script to submit non-interactive jobs on hpc2020
Copy these files from $OIFS_HOME/scripts
into your experiment directory.
Code Block | ||||
---|---|---|---|---|
| ||||
cd $OIFS_EXPT/ab2a/2016092500
cp $OIFS_HOME/scripts/exp_3d/oifs-run .
cp $OIFS_HOME/scripts/exp_3d/exp-config.h .
cp $OIFS_HOME/scripts/exp_3d/run.ecmwf-hpc2020.job . |
Determine experiment parameters
Namelist:
- You can edit the atmospheric model namelist file fort.4. It contains Fortran namelists which control model settings and switches.
- An important switch to edit is in namelist NAMRIP the variable CSTOP. Set this to the desired length of the forecast experiment.
- Experiment ab2a can be run for up to 144 hours (6 days) by setting
CSTOP='h144'
.
Experiment configuration file:
- You can edit the exp-config.h file which determines settings for this experiment.
- The oifs-run script will read the settings from this file.
- Alternatively, the settings can be passed to the oifs-run script via command line parameters, which takes precedence over the exp-config.h settings.
Info |
---|
You should always set up an exp-config.h for each experiment. If no exp-config.h file is found in the experiment directory, and if also no command line parameters are provided when calling oifs-run, then oifs-run will revert to its own default values which are not appropriate. In any case you should either edit the exp-config.h file appropriately or provide the correct command line parameters. |
The exp-config.h file contains the following settings:
Code Block | ||||
---|---|---|---|---|
| ||||
#--- required variables for this experiment:
OIFS_EXPID="ab2a" # your experiment ID
OIFS_RES="255" # the spectral grid resolution (here: T255)
OIFS_GRIDTYPE="l" # the grid type, either 'l' for linear reduced grid, or 'o' for the cubic octahedral grid
OIFS_NPROC=8 # the number of MPI tasks
OIFS_NTHREAD=4 # the number of OpenMP threads
OIFS_PPROC=true # enable postprocessing of model output after the model run
OUTPUT_ROOT=$(pwd) # folder where pproc output is created (only used if OIFS_PPROC=true). In this case an output folder is created in the experiment directory.
LFORCE=true # overwrite existing symbolic links in the experiment directory
LAUNCH="" # the platform specific run command for the MPI environment (e.g. "mpirun", "srun", etc).
#--- optional variables that can be set for this experiment:
#OIFS_NAMELIST='my-fort.4' # custom atmospheric model namelist file
#OIFS_EXEC="<cutome-path>/ifsMASTER.DP" # model exec to be used for this experiment
|
...
title | Order of precedence for how OpenIFS evaluates variables: |
---|
...
Running the experiment
After all optional edits to the namelists (fort.4) and to the experiment configuration file (exp-config.h) have been completed the model run can be started.
Depending on the available hardware experiments can either be run interactively or as a batch job.
Running a batch job
This method is the preferred way to run OpenIFS, as it is more efficient and it allows more flexibility in using the available hardware resources.
...
- In section 3, this script is copied to the experiment directory because it needs to be located here, to run an experiment.
...
Code Block | ||||
---|---|---|---|---|
| ||||
# set OpenIFS platform environment:
PLATFORM_CFG="/path/to/your/config/oifs-config.edit_me.sh" |
- It is important to change
"/path/to/your/config/oifs-config.edit_me.sh"
to the actual path for theoifs-config.edit_me.sh,
e.g.,"$HOME/openifs-48r1.1/oifs-config.edit_me.sh"
- The default resources requested in
run.ecmwf-hpc2020.job
are 8 nodes on the ECMWF hpc2020 machine, with a total of 256 MPI tasks and 4 OpenMP threads. This can be changed as required. - For information, the
LAUNCH
command for batch job submission is set to "srun
" without any further options, because all required parallel environment settings are provided through the SLURM script headers.
- It is important to change
Once you have made the appropriate changes to run.ecmwf-hpc2020.job
, you can submit it and, hence, run the experiment with the following commands
Code Block | ||||
---|---|---|---|---|
| ||||
# run as batch job:
cd $OIFS_EXPT/ab2a/2016092500
sbatch ./run.ecmwf-hpc2020.job |
Info |
---|
The job wrapper script will read the exp-config.h file and adopt the selected values. The exceptions are LAUNCH, which is set to "srun" for batch jobs, and OIFS_NPROC & OIFS_NTHREAD for which values from the batch job headers are used. The job wrapper script modifies the exp-config.h file accordingly prior to calling the oifs-run script. |
Running interactively
On the ECMWF hpc2020, running the model script interactively should be fine for lower grid resolutions up to T255L91.
- In order to run the experiment interactively, execute the oifs-run script from the command line in your terminal.
- If no command line parameters are provided with the oifs-run command, then the values from the exp-config.h will be used.
- In exp-config.h set OIFS_NPROC=8 and OIFS_NTHREAD to 4.
- In exp-config.h the LAUNCH variable should remain empty, i.e. LAUNCH="" and no --runcmd parameter should be provided in the command line.
The oifs-run script will in this case use its default launch parameters: srun -c${OIFS_NPROC} --mem=64GB --time=60
which will work fine with OIFS_NPROC=8 for experiment ab2a.
Code Block | ||||
---|---|---|---|---|
| ||||
# run interactively:
cd $OIFS_EXPT/ab2a/2016092500
./oifs-run |
Postprocessing
If in the exp-config.h file the OIFS_PPROC
variable has been set to true
(or if the --pproc command line parameter was used) then the model output in the experiment directory is further processed after completing the model run.
- In this case the script will generate a folder called
output_YYYMMDD_HHMMSS
, with YYYYMMDD being the current date and HHMMSS the current time. - This avoids accidental modification or overwriting of any previous results when the model experiment is repeated.
- For convenience a symbolic link
output
is set to the most recently generated model output. If the model run is repeated and a newoutput_YYYMMDD_HHMMSS
folder is generated, the symbolic link will be updated to point to the most recent output folder. - The variable
OUTPUT_ROOT
in exp-config.h determines where this ouput folder will be created. The default location is inside the experiment directory, but when assigning another path toOUTPUT_ROOT
this could be created elsewhere.
The postprocessing groups all model output fields and diagnostics into individual GRIB files with ascending forecast time step. Also, a copy of the atmospheric model namelist file fort.4, as well as the ifs.stat and NODE.01_001 log files are moved into the output folder.
This postprocessing is required if the Metview Python script is to be used later to visualise the model output.
Plotting of model output
Here we describe in a brief summary how plots from the model results can be generated. This permits a first-order sanity check whether the model results look sensible.
For this we use the Metview graphics package developed at ECMWF which is used within an example Jupyter Notebook.
Info |
---|
This requires the use of Jupyter Notebooks using a conda environment with Metview and Metview-Python libraries. At ECMWF you can access a Jupyter server on the hpc2020 either via the Linux Virtual Desktop (VDI) environment or via access to the JupytherHub service. |
Step 1: Copy the Metview processing code to your $OIFS_EXPT
location:
Code Block | ||||
---|---|---|---|---|
| ||||
cd $OIFS_EXPT
wget https://sites.ecmwf.int/openifs/openifs-data/case_studies/48r1/karl/mv.tar.gz
tar -xvzf mv.tar.gz
cd mv |
In the following steps we will process the OpenIFS model output into a dataset format that can be easily interpreted by Metview using a simplified plotting procedure.
Step 2: Edit the file process.sh
and change the path variable if required:
- in_dir: This needs to point to the
output
folder where the postprocessed OpenIFS model experiment (from the previous section) is found. Note that absolute file paths are required for this variable! By default this path is linked to theOIFS_EXPT
variable.
Step 3: Execute the script by running the command:
Code Block | ||||
---|---|---|---|---|
| ||||
cd $OIFS_EXPT/mv
./process.sh |
- This data processing may take a couple of minutes to complete.
- Occasionally the message "ERROR: input file does not exist!" may occur which can be safely ignored. This happens when the script attempts to convert model output which was not generated by OpenIFS. The script will not fail but simply carry on looking for the next file.
- After successful completing the conversion process "Done." should appear on the terminal.
- As a result of this processing, regular gridded and compressed GRIB files are generated in
$OIFS_EXPT/mv/data/ab2a
which can be visualised with by running the enclosed Jupyter Notebooksingle.ipynb
Step 4: Now proceed with the following steps to visualise the processed data:
- We describe the process on the example of the ECMWF Linux Virtual Desktop (VDI)
- In the VDI, open a terminal, log into the hpc2020 with command:
ssh hpc-login
- In the terminal start the Jupyter session on an interactive node, using the command:
ecinteractive -j
- After the interactive node has started you will be given a weblink to connect to the Jupyterlab session ("To manually re-attach go to <weblink>").
- Open a web browser (e.g. Chrome) inside the VDI and paste the weblink into the browser's URL address field; this will connect to the Jupyter session.
- In the file explorer, on the left side of the Jupyter window, navigate to the folder
$PERM/mv/ipynb/
and select Notebooksingle.ipynb
- Open this Notebook by double-clicking in the explorer window.
- Once it has opened, run all its cells in sequence (e.g. use the command "Run All Cells" in menu "Run").
- This will generate a series of plots from the model output which are displayed inside the Notebook.
- Optional: After completing the Jupyter session it is good practice to release the reserved interactive node using this command in the terminal window:
ecinteractive -p hpc -k
and confirm cancellation of the job; if this is not done the interactive job will timeout after 12 hours.
Requirements
This section provides further details about software requirements for OpenIFS.
...