Getting Started
This page will help you to setup and run a basic test case using the ufs-weather-model, which is used in multiple UFS applications.
If you would like to engage in development or run a full set of regression tests, you will need to refer to the UFS Weather Model User's Guide.
This weather model repository does not include a workflow, pre-processing (preparation of inputs), or post-processing. Such workflows are available through the application-level repositories in this ufs-community organization, such as the UFS Medium-Range Weather Application. Inclusion of workflows makes the model configuration much easier to modify. If you would like to change the resolution, physics package, initial conditions, output frequency, or other aspects of the model, it is recommended that you use an application. The UFS Medium-Range Weather Application 1.1 was released in September 2020.
If you encounter problems, please check the ufs-weather-model issues page. You can also submit a question to the UFS Weather Model Support Forum.
The model source code is hosted here on GitHub. Check that git is installed on your machine and that you can reach GitHub. See Set Up Git and Creating a GitHub Account for Development Work for more details.
All files need to be visible to the compute nodes on your machine. Please go to the appropriate working directory for your system and project.
% cd <working_directory>
Note that working directories are often non-backed up file systems. If you are making changes to the source code it's important to push to GitHub regularly.
You can now clone the ufs-weather-model repository.
You will be using a tag called ufs-v1.1.0 on a branch called release/public-v1:
% 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
This tag has been tested with the example used in this section. If you would like to work with the head of the development branch, which has the very latest code changes, you can replace the tag in the checkout command with develop. This code may not be fully tested or work with this example. To get the latest changes on the release/public-v1 branch, replace the tag with this branch name.
The above commands do not require a GitHub account, but it is strongly recommended that you have one so you can version control your own modifications. A GitHub account is required if you wish to contribute code back to the ufs-weather-model repository.
Compiling the model will take place within the ufs-weather-model directory you just created.
The UFS Weather Model requires a number of other libraries for it to compile. If you are working on a pre-configured platform, the prerequisite libraries have been built and are available. If you are NOT working on a pre-configured platform, then you will need to build the necessary libraries.
The starting point for downloading and building prerequisite libraries is the NCEPLIBS-external wiki page. The tag for NCEPLIBS and NCEPLIBS-external should match the tag of the weather model.
For some platforms, the instructions on the NCEPLIBS-external wiki page and README files extend through compilation of the Weather Model.
If that's not the case for your platform, see the UFS Weather Model User's Guide section called "Building and Running the UFS Weather Model" for instructions on how to compile the model. You will need to first set paths to the prerequisite libraries so that the compiler can find them. Note that if you are on a pre-configured platform, you can use modulefiles to do this, but if you are not, you will need to set the paths manually. The User's Guide section has instructions for both.
A prepared case can be downloaded from the NOAA Environmental Modeling Center ftp server. Download and untar the prepared case in your working directory.
https://ftp.emc.ncep.noaa.gov/EIB/UFS/simple-test-case.tar.gz
Executing the following commands will untar the test case into a directory named 'simple-test-case'.
% cd <working_directory>
% wget https://ftp.emc.ncep.noaa.gov/EIB/UFS/simple-test-case.tar.gz
% tar -zxf simple-test-case.tar.gz
This test case will run a global C96 grid configuration for a 24 hour forecast period.
Note that downloading this test case is not necessary when running an application that includes the Common Infrastructure for Modeling Earth (CIME) workflow. For example, the Medium-Range Weather Application, which uses CIME, can download input files for you.
First, copy the ufs_weather_model into your run directory. If you followed the instructions in the Download a Test Case section, then your run directory is <working_directory>/simple-test-case.
% cd <run_directory>
% cp <working_directory>/ufs-weather-model/ufs_weather_model .
If your computing system includes a job scheduler, such as Portable Batch System (PBS), Slurm Workload Manager (Slurm), or Platform Load Sharing Facility (LSF) then follow instructions for Systems with Job Schedulers. If your system does not include a job scheduler then follow instructions for Systems without Job Schedulers.
If your system includes a job scheduler then run the prepared global C96 test on 8 mpi tasks via submission to the job scheduler.
If you are not already set up for this, you can download an appropriate template file based on your job scheduler.
| Job Scheduler | Template |
|---|---|
| PBS | % wget https://raw.githubusercontent.com/wiki/ufs-community/ufs-weather-model/tools/ufs_simple_test_case.qsub.template |
| Slurm | % wget https://raw.githubusercontent.com/wiki/ufs-community/ufs-weather-model/tools/ufs_simple_test_case.sbatch.template |
| LSF | % wget https://raw.githubusercontent.com/wiki/ufs-community/ufs-weather-model/tools/ufs_simple_test_case.bsub.template |
You will need to edit placeholders in the template file.
| Placeholder | Description |
|---|---|
| __ACCOUNT__ | Project or group identifier |
| __QUEUE_OR_QOS__ | Queue or Quality of Service (e.g. regular, debug) |
| __PATH_TO_MODULEFILE__ | Path to modulefile |
| __MODULEFILE__ | Modulefile used to setup run (often the modulefile used when compiling ) |
| __MPIEXEC__ | Program executing MPI processes (e.g. mpiexec, mpiexec_mpt, mpirun, aprun) |
Once this is done you can submit the job. The instructions for each type of job scheduler are below.
| Job Scheduler | Template |
|---|---|
| PBS | % qsub ufs_simple_test_case.qsub.template |
| Slurm | % sbatch ufs_simple_test_case.sbatch.template |
| LSF | % bsub ufs_simple_test_case.bsub.template |
Standard output and standard error will be directed to a file name 'out'.
If your system does not include a job scheduler then run the global C96 test configuration on 8 processors using the appropriate MPI program (e.g. mpiexec, mpiexec_mpt, mpirun, aprun).
% mpiexec -np 8 ./ufs_weather_model
If the run is successful you'll find output files named dynf***.nc (dynamics variables) and phyf***.nc (physics variables) through 024h in the run directory.
There are several NetCDF visualization tools, such as Ncview, NCL, Ferret, and Panoply.
We have provided a NCL script that plots 2m Temperature (tmp2m) and Total Precipitation (tprcp) at 24h. You can download it locally at: https://raw.githubusercontent.com/wiki/ufs-community/ufs-weather-model/tools/plot_ufs_phyf.ncl
To use NCL, load the following modulefiles:
| System | Modules |
|---|---|
| Cheyenne | module load intel/18.0.5 ncl/6.6.2 |
| Stampede2 | module load ncl_ncarg/6.3.0 |
| Hera | module load ncl/6.5.0 |
Execute the following commands to get and run the script.
% cd <run_directory>
% wget https://raw.githubusercontent.com/wiki/ufs-community/ufs-weather-model/tools/plot_ufs_phyf.ncl
% ncl plot_ufs_phyf.ncl
For reference and comparison, two example plots are below. They are consistent with the tag ufs-v1.1.0. Your results may look different if you are using a different branch or tag.
 |
 |