Skip to content

Getting Started

ceceliadid edited this page Mar 8, 2020 · 125 revisions

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 is expected to be available in early 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.

image_2002_wm_support_forum

1 Download the Model Source Code

Check git configuration

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.

Where to download/install

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.

Clone the ufs-weather-model repositories

You can now clone the ufs-weather-model repository. You will be using a tag called ufs-v1.0.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.0.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.

2 Compile the Model

Prerequisite libraries

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.

Compiling

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.

3 Download a Test Case

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, will retrieve input files for you.

4 Run the Test Case

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.

Systems with 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 modufile 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'.

Systems without Job Schedulers

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

Where to Find Outputs

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.

5 Check Your Results

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.0.0. Your results may look different if you are using a different branch or tag.

2M Air Temperature Total Precipitation
Clone this wiki locally