Forecast YAML
The structured YAML to run a forecast is described below. It is enforced via JSON Schema.
In this block, there are entries that define where the forecast will run (run_directory:), what will run (executable:), the data files that should be staged (cycle_dependent: and static:), and blocks that correspond to the configuration files required by the forecast model (fd_ufs:, field_table:, namelist:, etc.). Each of the configuration file blocks will allow the user to set a template file as input, or to define a configuration file in its native key/value pair format with an option to update the values (update_values:) contained in the original input file (base_file:).
The configuration files required by the UFS Weather Model are documented here.
The forecast: block
This section describes the specifics of the FV3 atmosphere forecast component.
forecast:
cycle_dependent:
INPUT/gfs_data.nc: /path/to/gfs_data.nc
INPUT/sfc_data.nc: /path/to/sfc_data.nc
INPUT/gfs_ctrl.nc: /path/to/gfs_ctrl.nc
diag_table: /path/to/diag_table/template/file
domain: regional
executable: fv3.exe
fd_ufs:
base_file: /path/to/base/fd_ufs.yaml
field_table:
base_file: /path/to/field_table.yaml
update_values:
liq_wat:
longname: cloud water mixing ratio
units: kg/kg
profile_type:
name: fixed
surface_value: 2.0
length: 12
model_configure:
base_file: /path/to/base/model_configure
update_values:
write_dopost: .false.
namelist:
base_file: /path/to/base/input.nml
update_values:
fv_core_nml:
k_split: 2
n_split: 6
run_dir: /path/to/forecast/run/directory/{yyyymmddhh}
static:
fv3.exe: /path/to/executable/ufs_model
INPUT/grid_spec.nc: /path/to/grid_spec.nc
...
data_table: /path/to/data_table
eta_micro_lookup.data: /path/to/noahmptable.dat
noahmptable.tbl: /path/to/noahmptable.tbl
ufs_configure: /path/to/template/ufs.configure
Updating Values
Many of the blocks describe configuration files needed by the UFS Weather Model, i.e. namelist:, fd_ufs:, model_configure:. The base_file: entry in a given block is required to initially stage the file; it can then be modified via an update_values: block.
To ensure the correct values are updated, the hierarchy of entries in the base file must be mirrored under the update_values: block. Multiple entries within a block may be updated and they need not follow the same order as those in the base file. For example, the base file named people.yaml may contain:
person:
age: 19
address:
city: Boston
number: 12
state: MA
street: Acorn St
name: Jane
Then the entries in the update_values: YAML block would override this base file with the entries:
base_file: people.yaml
update_values:
person:
address:
street: Main St
number: 99
The contents of the staged people.yaml that results:
person:
age: 19
address:
city: Boston
number: 99
state: MA
street: Main St
name: Jane
UW YAML Keys
cycle_dependent:
This block contains a set of files to stage in the run directory: File names as they appear in the run directory are keys and their source paths are the values. Source paths can be provided as a single string path, or a list of paths to be staged in a common directory under their original names.
Warning
The current version does not support adding cycle information to the content of the files, and this information must be hard-coded in the YAML file.
diag_table:
The path to the input Jinja2 template for the diag_table file.
The diag_table is described here.
domain:
A switch to differentiate between a global or regional configuration. Accepted values are global and regional.
executable:
The path to the compiled executable.
fd_ufs:
This block requires a base_file: entry that contains the path to the YAML file. An optional update_values: block may be provided to update any values contained in the base file. Please see the Updating Values section for providing information in these entries.
The fd_ufs.yaml file is a structured YAML used by the FV3 weather model. The tested version can be found in the ufs-weather-model repository. The naming convention for the dictionary entries are documented here.
field_table:
The block requires a base_file: entry that contains the path to the YAML file. An optional update_values: block may be provided to update any values contained in the base file. Please see the Updating Values section for providing information in these entries.
If a predefined field table (i.e., not a configurable YAML) is to be used, include it in the static: block.
The documentation for the field_table file is here. Information on how to structure the UW YAML for configuring a field_table is in the Defining a field_table Section.
length:
The length of the forecast in hours.
model_configure:
The block requires a base_file: entry that contains the path to the YAML file. An optional update_values: block may be provided to update any values contained in the base file. Please see the Updating Values section for providing information in these entries.
The documentation for the model_configure file is here.
namelist:
The block requires a base_file: entry that contains the path to the namelist file. An optional update_values: block may be provided to update any values contained in the base file. Please see the Updating Values section for providing information in these entries.
The documentation for the FV3 namelist, input.nml is here.
run_dir:
The path where the forecast input data will be staged and output data will appear after a successful forecast.
static:
This block contains a set of files to stage in the run directory: file names as they appear in the run directory are keys and their source paths are the values. Source paths can be provided as a single string path, or a list of paths to be staged in a common directory under their original names.
ufs_configure:
The path to the input Jinja2 template for the ufs.configure file.
The documentation for the ufs.configure file is here.
The platform: block
This block describes necessary facts about the computational platform.
platform:
mpicmd: srun # required
scheduler: slurm
mpicmd:
The MPI command used to run the model executable. Typical options are srun, mpirun, mpiexec, etc. System administrators should be able to advise the appropriate choice, if needed.
scheduler:
The name of the batch system. Supported options are lfs, pbs, and slurm.
The preprocessing: block
preprocessing:
lateral_boundary_conditions:
interval_hours: 3 # optional, default
offset: 0 # optional, default
output_file_path: # required
lateral_boundary_conditions:
The optional block describes how the lateral boundary conditions have been prepared for a limited-area configuration of the model forecast. It is required for a limited-area forecast. The following entries in its subtree are used for the forecast:
interval_hours:
The integer number of hours setting how frequently the lateral boundary conditions will be used in the model forecast.
offset:
The integer number of hours setting how many hours earlier the external model used for boundary conditions started compared to the desired forecast cycle.
output_file_path:
The path to the lateral boundary conditions files prepared for the forecast. It accepts the integer forecast_hour as a Python template, e.g., /path/to/srw.t00z.gfs_bndy.tile7.f{forecast_hour:03d}.nc.
The user: block
user:
account: my_account # optional
account:
The user account associated with the batch system.