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:
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).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.1.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.1.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 NCEPLIBS, NCEPLIBS-external and CMake¶
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.
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 |
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 from the ufs-weather-model directory on hera:
cd modulefiles/hera.intel
module use $(pwd)
module load fv3
cd ../..
Note that loading this module file will also set the CMake environment variables shown in Table 3.3.
EnvironmentVariable |
Description |
Hera Intel Value |
---|---|---|
CMAKE_C_COMPILER |
Name of C compiler |
mpiicc |
CMAKE_CXX_COMPILER |
Name of C++ compiler |
mpiicpc |
CMAKE_Fortran_COMPILER |
Name of Fortran compiler |
mpiifort |
CMAKE_Platform |
String containing platform and compiler name |
hera.intel |
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.1.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 the CCPP_SUITES environment variable¶
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 set to ‘FV3_GFS_v15p2’
in build.sh
.
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 configures the build environment and runs the make
command. This script also checks that all necessary environment variables have been set.
If any of the environment variables have not been set, the build.sh
script will exit with a message similar to:
./build.sh: line 11: CMAKE_Platform: Please set the CMAKE_Platform environment variable, e.g. [macosx.gnu|linux.gnu|linux.intel|hera.intel|...]
The WM can be built by running the following command 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.