3. Building and Running the UFS Weather Model

3.1. Prerequisite Libraries

The UFS Weather Model requires a number of libraries for it to compile. There are two categories of libraries that are needed:

1. Bundled libraries (NCEPLIBS). These are libraries developed for use with NOAA weather models. Most have an NCEPLIBS prefix in the repository, e.g. NCEPLIBS-bacio. Select tools from the UFS Utilities repository (UFS-UTILS) are also included in this category. A list of the bundled libraries tested with this WM release is in the top-level README of the NCEPLIBS repository (be sure to look at the tag in that repository that matches the tag on this WM release).

2. Third-party libraries (NCEPLIBS-external). These are libraries that were developed external to the UFS Weather Model. They are general software packages that are also used by other models in the community. Building these is optional, since existing builds of these libraries can be pointed to instead. A list of the external libraries tested with this WM release is in the top-level README of the NCEPLIBS-external repository. Again, be sure to look at the tag in that repository that matches the tag on this WM release.

Note

The libraries in NCEPLIBS-external must be built before the libraries in NCEPLIBS.

See this wiki link for an explanation of which platforms and compilers are supported. This will help to determine if you need to build NCEPLIBS and NCEPLIBS-external or are working on a system that is already pre-configured. On pre-configured platforms, the libraries are already available.

If you do have to build the libraries, it is a good idea to check the platform- and compiler-specific README files in the doc/ directory of the NCEPLIBS-external repository as a first step, to see if your system or one similar to it is included. These files have detailed instructions for building NCEPLIBS-external, NCEPLIBS, and the UFS Weather Model. They may be all the documentation you need. Be sure to use the tag that corresponds to this version of the WM, and define a WORK directory path before you get started.

If your platform is not included in these platform- and compiler-specific README files, there is a more generic set of instructions in the README file at the top level of the NCEPLIBS-external repository, and at the top level of the NCEPLIBS repository. It may still be a good idea to look at some of the platform- and compiler-specific README files as a guide. Again, be sure to use the tag that corresponds to this version of the WM.

The top-level README in the NCEPLIBS-external repository includes a troubleshooting section that may be helpful.

You can also get expert help through a user support forum set up specifically for issues related to build dependencies.

3.2. Downloading the Weather Model Code

To clone the ufs-weather-model repository for this v1.0.0 release, execute the following commands:

git clone https://github.com/ufs-community/ufs-weather-model.git ufs-weather-model
cd ufs-weather-model
git checkout ufs-v1.0.0
git submodule update --init --recursive

Compiling the model will take place within the ufs-weather-model directory you just created.

3.3. Building the Weather Model

3.3.1. Setting environment variables for paths to NCEPLIBS and NCEPLIBS-external

You will need to make sure that the WM has the paths to the libraries that it requires. In order to do that, these environment variables need to be set, as shown in Table 3.1 and Table 3.2 for the bash shell.

Table 3.1 Bundled libraries (NCEPLIBS) required for the Weather Model

NCEP Library	Environment Variables
nemsio	export NEMSIO_INC=<path_to_nemsio_include_dir>
	export NEMSIO_LIB=<path_to_nemsio_lib_dir>/libnemsio<version>.a
bacio	export BACIO_LIB4=<path_to_bacio_lib_dir>/libbacio<version>.a
splib	export SP_LIBd=<path_to_sp_lib_dir>/libsp<version>_d.a
w3emc	export W3EMC_LIBd=<path_to_w3emc_lib_dir>/libw3emc<version>_d.a
w3nco	export W3NCO_LIBd=<path_to_w3nco_lib_dir>/libw3nco<version>_d.a

Table 3.2 Third-party libraries (NCEPLIBS-external) required for the Weather Model

Library	Environment Variables
NetCDF	export NETCDF=<path_to_netcdf_install_dir>
ESMF	export ESMFMKFILE=<path_to_esmfmk_file>/esmf.mk

The following are a few different ways to set the required environment variables to the correct values. If you are running on one of the pre-configured platforms, you can set them using modulefiles. Modulefiles for all supported platforms are located in modulefiles/<platform>/fv3. To load the modules, for example on hera, run:

cd modulefiles/hera.intel
module use $(pwd)
module load fv3
cd ../..

If you are not running on one of the pre-configured platforms, you will need to set the environment variables in a different way.

If you used one of the platform- and compiler-specific README files in the doc/ directory of NCEPLIBS-external to build the prerequisite libraries, there is a script in the NCEPLIBS-ufs-v1.0.0/bin directory called setenv_nceplibs.sh that will set the NCEPLIBS-external variables for you.

Of course, you can also set the values of these variables yourself if you know where the paths are on your system.

3.3.2. Setting other environment variables

You will also need to set the CMAKE_Platform environment variable. See the README files in the doc/ directories of the NCEPLIBS-external repository for recognized values.

The default value is:

export CMAKE_Platform=linux.<compiler>

Where <compiler> is either Intel or GNU. You may also wish to set the following environment variables:

• CMAKE_Platform: if not set the default is linux.${COMPILER}

• CMAKE_C_COMPILER: if not set the default is mpicc

• CMAKE_CXX_COMPILER: if not set the default is mpicxx

• CMAKE_Fortran_COMPILER: if not set the default is mpif90

In order to have one or more CCPP physics suites available at runtime, you need to select those suites at build time by setting the CCPP_SUITES environment variable. Multiple suites can be set, as shown below in an example for the bash shell:

export CCPP_SUITES=’FV3_GFS_v15p2,FV3_GFS_v16beta’

If CCPP_SUITES is not set, the default is ‘FV3_GFS_v15p2’.

3.3.3. Building the model

The UFS Weather Model uses the cmake build system. There is a build script called build.sh in the top-level directory of the WM repository that ensures all necessary variables are actually set.

After setting all the environment variables, you can build the model by running the following from the ufs-weather-model directory:

./build.sh

Once build.sh is finished, you should see the executable, named ufs_weather_model, in the top-level directory.

Expert help is available through a user support forum set up specifically for issues related to the Weather Model.

3.4. Running the model

The UFS Weather Model wiki includes a simple test case that illustrates how the model can be run.