6. Code repositories and directory structure

This chapter describes the code repositories that comprise the MRW App, without describing, in detail, any of the components.

6.1. Hierarchical Repository Structure

The umbrella repository for the MRW Application is named ufs-mrweather-app and is available on GitHub at https://github.com/ufs-community/ufs-mrweather-app. An umbrella repository is a repository that includes links, called externals, to additional repositories. The MRW App includes the checkout_externals tools along with a configuration file called Externals.cfg, which describes the external repositories associated with the MRW App umbrella repository (see Table 6.1).

Table 6.1 List of top-level repositories included in the MRW App

Repository Description	Authoritative repository URL
Umbrella repository for the MRW App	https://github.com/ufs-community/ufs-mrweather-app
Umbrella repository for the UFS Weather Model	https://github.com/ufs-community/ufs-weather-model
Repository for the global workflow	https://github.com/NOAA-EMC/global-workflow
Repository for UFS utilities, (e.g., pre-processing, chgres_cube)	https://github.com/ufs-community/UFS_UTILS
Repository for the Unified Post Processor (UPP)	https://github.com/NOAA-EMC/UPP

The UFS Weather Model is itself an umbrella repository and contains a number of sub-repositories used by the model as documented here.

Note that the prerequisite libraries (including NCEP Libraries and external libraries) are not included in the UFS MRW Application repository. The `spack-stack <https://github.com/NOAA-EMC/spack-stack>`__ repository assembles these prerequisite libraries. The spack-stack has already been built on preconfigured (Level 1) platforms. However, it must be built on other systems. Chapter %s contains details on installing the spack-stack.

6.2. Directory Structure

The directory structure on disk for users of the MRW App depends on whether one is using a pre-configured platform. Users working on pre-configured platforms will only have the files associated with the ufs-mrweather-app in their disk space. The directory structure is set in configuration file Externals.cfg, which is in the top directory where the umbrella repository has been cloned.

The directory structures for the standalone UFS Weather Model and the UFS Weather Model included with the MRW App are equal in that they contain subdirectories for FMS, FV3, NEMS and stochastic_physics. However, in the MRW App, subdirectories are located under src/model. The MRW App also includes directories for CIME, such as the src/model/FV3/cime and src/model/NEMS/cime directories.

Users working outside of preconfigured platforms will have additional files on disk associated with the libraries, pre- and post-processing. The resulting directory structure is determined by the path settings in the NCEPLIBS .gitmodules file.

The ufs-mrweather-app umbrella repository structure is determined by the local_path settings contained within the Externals.cfg file. After manage_externals/checkout_externals is run (Step 3.3), the specific GitHub repositories described in Table 6.1 are cloned into the target subdirectories shown below. Directories that will be created as part of the build process appear in parentheses and will not be visible until after the build is complete. Some directories have been removed for brevity.

ufs-mrweather-app
├── (bin)
├── (build)
├── docs
│     └── UsersGuide
├── (include)
├── (lib)
├── manage_externals
├── global-workflow
│     ├── docs
│     │     └── UsersGuide
│     ├── (fix)
│     ├── jobs
│     ├── modulefiles
│     ├── scripts
│     ├── tests
│     │     └── baseline_configs
│     └── ush
│          ├── Python
│          ├── rocoto
│          ├── templates
│          └── wrappers
├── (share)
├── plotting_scripts
└── src
     ├── UPP
     │     ├── parm
     │     └── sorc
     │          └── ncep_post.fd
     ├── UFS_UTILS
     │     ├── sorc
     │     │    ├── chgres_cube.fd
     │     │    ├── fre-nctools.fd
     |     │    ├── grid_tools.fd
     │     │    ├── orog_mask_tools.fd
     │     │    └── sfc_climo_gen.fd
     │     └── ush
     └── ufs_weather_model
          └── FV3
               ├── atmos_cubed_sphere
               └── ccpp

6.2.1. Global Workflow Sub-Directories

A number of sub-directories are created under the global-workflow directory when the global workflow is cloned (see directory diagram above). Table 6.2 describes the contents of these sub-directories.

Table 6.2 Sub-directories of the global workflow

Directory Name	Description
docs	User’s Guide Documentation
jobs	J-job scripts launched by Rocoto
modulefiles	Files used to load modules needed for building and running the workflow
scripts	Run scripts launched by the J-jobs
tests	Baseline experiment configuration
ush	Utility scripts used by the workflow

6.3. Experiment Directory Structure

When the user generates an experiment (Step 4.4), a user-defined experimental directory (EXPTDIR) is created based on information specified in the config.sh file. Table 6.3 shows the contents of the experiment directory before running the experiment workflow.

Table 6.3 Files and sub-directory initially created in the experimental directory

File Name	Description
config.sh	User-specified configuration file, see Section %s
data_table	Cycle-independent input file (empty)
field_table	Tracers in the forecast model
FV3LAM_wflow.xml	Rocoto XML file to run the workflow
input.nml	Namelist for the UFS Weather model
launch_FV3LAM_wflow.sh	Symlink to the shell script of ufs-srweather-app/regional_workflow/ush/launch_FV3LAM_wflow.sh that can be used to (re)launch the Rocoto workflow. Each time this script is called, it appends to a log file named log.launch_FV3LAM_wflow.
log.generate_FV3LAM_wflow	Log of the output from the experiment generation script generate_FV3LAM_wflow.sh
nems.configure	See NEMS configuration file
suite_{CCPP}.xml	CCPP suite definition file used by the forecast model
var_defns.sh	Shell script defining the experiment parameters. It contains all of the primary parameters specified in the default and user-specified configuration files plus many secondary parameters that are derived from the primary ones by the experiment generation script. This file is sourced by various other scripts in order to make all the experiment variables available to these scripts.
YYYYMMDDHH	Cycle directory (empty)

Table 6.4 Description of the fix directories

Directory Name	Description
fix_am	Directory containing the global fix (time-independent) data files. The experiment generation script copies these files from a machine-dependent system directory.
fix_lam	Directory containing the regional fix (time-independent) data files that describe the regional grid, orography, and various surface climatology fields as well as symlinks to pre-generated files.

Table 6.5 New directories and files created when the workflow is launched

Directory/File Name	Description
YYYYMMDDHH	This is a “cycle directory” that is updated when the first cycle-specific workflow tasks (get_extrn_ics and get_extrn_lbcs) are run. These tasks are launched simultaneously for each cycle in the experiment. Cycle directories are created to contain cycle-specific files for each cycle that the experiment runs. If DATE_FIRST_CYCL and DATE_LAST_CYCL are different, and/or if CYCL_HRS contains more than one element in the config.sh file, more than one cycle directory will be created under the experiment directory.
grid	Directory generated by the make_grid task to store grid files for the experiment
log	Contains log files generated by the overall workflow and by its various tasks. Look in these files to trace why a task may have failed.
orog	Directory generated by the make_orog task containing the orography files for the experiment
sfc_climo	Directory generated by the make_sfc_climo task containing the surface climatology files for the experiment
FV3LAM_wflow.db FV3LAM_wflow_lock.db	Database files that are generated when Rocoto is called (by the launch script) to launch the workflow.
log.launch_FV3LAM_wflow	The launch_FV3LAM_wflow.sh script appends its output to this log file each time it is called. Take a look at the last 30–50 lines of this file to check the status of the workflow.

The output files for an experiment are described in Section 7.2. The workflow tasks are described in Section %s.