4. Inputs and Outputs

This chapter describes the input and output files needed for executing the model in the various supported configurations.

4.1. Input files

There are three types of files needed to execute a run: static datasets (fix files containing climatological information), files that depend on grid resolution, initial and boundary conditions, and model configuration files (such as namelists).

4.1.1. Static datasets (i.e., fix files)

The static input files for global configurations are listed and described in Table 4.1. Similar files are used for a regional grid but are grid specific and generated by pre-processing utilities.

Table 4.1 Fix files containing climatological information

Filename

Description

aerosol.dat

External aerosols data file

CFSR.SEAICE.1982.2012.monthly.clim.grb

CFS reanalysis of monthly sea ice climatology

co2historicaldata_YYYY.txt

Monthly CO2 in PPMV data for year YYYY

global_albedo4.1x1.grb

Four albedo fields for seasonal mean climatology: 2 for strong zenith angle dependent (visible and near IR) and 2 for weak zenith angle dependent

global_glacier.2x2.grb

Glacier points, permanent/extreme features

global_h2oprdlos.f77

Coefficients for the parameterization of photochemical production and loss of water (H2O)

global_maxice.2x2.grb

Maximum ice extent, permanent/extreme features

global_mxsnoalb.uariz.t126.384.190.rg.grb

Climatological maximum snow albedo

global_o3prdlos.f77

Monthly mean ozone coefficients

global_shdmax.0.144x0.144.grb

Climatological maximum vegetation cover

global_shdmin.0.144x0.144.grb

Climatological minimum vegetation cover

global_slope.1x1.grb

Climatological slope type

global_snoclim.1.875.grb

Climatological snow depth

global_snowfree_albedo.bosu.t126.384.190.rg.grb

Climatological snowfree albedo

global_soilmgldas.t126.384.190.grb

Climatological soil moisture

global_soiltype.statsgo.t126.384.190.rg.grb

Soil type from the STATSGO dataset

global_tg3clim.2.6x1.5.grb

Climatological deep soil temperature

global_vegfrac.0.144.decpercent.grb

Climatological vegetation fraction

global_vegtype.igbp.t126.384.190.rg.grb

Climatological vegetation type

global_zorclim.1x1.grb

Climatological surface roughness

RTGSST.1982.2012.monthly.clim.grb

Monthly, climatological, real-time global sea surface temperature

seaice_newland.grb

High resolution land mask

sfc_emissivity_idx.txt

External surface emissivity data table

solarconstant_noaa_an.txt

External solar constant data table

4.1.2. Grid description and initial condition files

The input files containing grid information and the initial conditions for global configurations are listed and described in Table 4.2. The input files for a limited area model (LAM) configuration including grid information and initial and lateral boundary conditions are listed and described in Table 4.3. Note that the regional grid is referred to as Tile 7 here, and are generated by several pre-processing utilities.

Table 4.2 Input files containing grid information and initial conditions for global configurations

Filename

Description

Date-dependent

Cxx_grid.tile[1-6].nc

Cxx grid information for tiles 1-6, where ‘xx’ is the grid number

gfs_ctrl.nc

NCEP NGGPS tracers, ak, and bk

gfs_data.tile[1-6].nc

Initial condition fields (ps, u, v, u, z, t, q, O3). May include spfo3, spfo, spf02 if multiple gases are used

oro_data.tile[1-6].nc

Model terrain (topographic/orographic information) for grid tiles 1-6

sfc_ctrl.nc

Control parameters for surface input: forecast hour, date, number of soil levels

sfc_data.tile[1-6].nc

Surface properties for grid tiles 1-6

Table 4.3 Regional input files containing grid information and initial and lateral boundary conditions for regional configurations

Filename

Description

Date-dependent

Cxx_grid.tile7.nc

Cxx grid information for tile 7, where ‘xx’ is the grid number

gfs_ctrl.nc

NCEP NGGPS tracers, ak, and bk

gfs_bndy.tile7.HHH.nc

Lateral boundary conditions at hour HHH

gfs_data.tile7.nc

Initial condition fields (ps, u, v, u, z, t, q, O3). May include spfo3, spfo, spf02 if multiple gases are used

oro_data.tile7.nc

Model terrain (topographic/orographic information) for grid tile 7

sfc_ctrl.nc

Control parameters for surface input: forecast hour, date, number of soil levels

sfc_data.tile7.nc

Surface properties for grid tile 7

4.1.3. Model configuration files

The configuration files used by the UFS Weather Model are listed here and described below:

  • diag_table

  • field_table

  • model_configure

  • nems.configure

  • suite_[suite_name].xml (used only at build time)

While the input.nml file is also a configuration file used by the UFS Weather Model, it is described in Section 4.1.4. The run-time configuration of model output fields is controlled by the combination of diag_table and model_configure, and is described in detail in Section 4.2.

4.1.3.1. diag_table file

There are three sections in file diag_table: Header (Global), File, and Field. These are described below.

Header Description

The Header section must reside in the first two lines of the diag_table file and contain the title and date of the experiment (see example below). The title must be a Fortran character string. The base date is the reference time used for the time units, and must be greater than or equal to the model start time. The base date consists of six space-separated integers in the following format: year month day hour minute second. Here is an example:

20161003.00Z.C96.64bit.non-mono
2016 10 03 00 0 0

File Description

The File Description lines are used to specify the name of the file(s) to which the output will be written. They contain one or more sets of six required and five optional fields (optional fields are denoted by square brackets [ ]). The lines containing File Descriptions can be intermixed with the lines containing Field Descriptions as long as files are defined before fields that are to be written to them. File entries have the following format:

"file_name", output_freq, "output_freq_units", file_format, "time_axis_units", "time_axis_name"
[, new_file_freq, "new_file_freq_units"[, "start_time"[, file_duration, "file_duration_units"]]]

These file line entries are described in Table 4.4.

Table 4.4 Description of the six required and five optional fields used to define output file sampling rates.

File Entry

Variable Type

Description

file_name

CHARACTER(len=128)

Output file name without the trailing “.nc”

output_freq

INTEGER

The period between records in the file_name:
> 0 output frequency in output_freq_units.
= 0 output frequency every time step (output_freq_units is ignored)
=-1 output at end of run only (output_freq_units is ignored)

output_freq_units

CHARACTER(len=10)

The units in which output_freq is given. Valid values are “years”, “months”, “days”, “minutes”, “hours”, or “seconds”.

file_format

INTEGER

Currently only the netCDF file format is supported. = 1 netCDF

time_axis_units

CHARACTER(len=10)

The units to use for the time-axis in the file. Valid values are “years”, “months”, “days”, “minutes”, “hours”, or “seconds”.

time_axis_name

CHARACTER(len=128)

Axis name for the output file time axis. The character string must contain the string ‘time’. (mixed upper and lowercase allowed.)

new_file_freq

INTEGER, OPTIONAL

Frequency for closing the existing file, and creating a new file in new_file_freq_units.

new_file_freq_units

CHARACTER(len=10), OPTIONAL

Time units for creating a new file: either years, months, days, minutes, hours, or seconds. NOTE: If the new_file_freq field is present, then this field must also be present.

start_time

CHARACTER(len=25), OPTIONAL

Time to start the file for the first time. The format of this string is the same as the global date. NOTE: The new_file_freq and the new_file_freq_units fields must be present to use this field.

file_duration

INTEGER, OPTIONAL

How long file should receive data after start time in file_duration_units. This optional field can only be used if the start_time field is present. If this field is absent, then the file duration will be equal to the frequency for creating new files. NOTE: The file_duration_units field must also be present if this field is present.

file_duration_units

CHARACTER(len=10), OPTIONAL

File duration units. Can be either years, months, days, minutes, hours, or seconds. NOTE: If the file_duration field is present, then this field must also be present.

Field Description

The field section of the diag_table specifies the fields to be output at run time. Only fields registered with register_diag_field(), which is an API in the FMS diag_manager routine, can be used in the diag_table.

Registration of diagnostic fields is done using the following syntax

diag_id = register_diag_field(module_name, diag_name, axes, ...)

in file FV3/atmos_cubed_sphere/tools/fv_diagnostics.F90. As an example, the sea level pressure is registered as:

id_slp = register_diag_field (trim(field), 'slp', axes(1:2), &   Time, 'sea-level pressure', 'mb', missing_value=missing_value, range=slprange )

All data written out by diag_manager is controlled via the diag_table. A line in the field section of the diag_table file contains eight variables with the following format:

"module_name", "field_name", "output_name", "file_name", "time_sampling", "reduction_method", "regional_section", packing

These field section entries are described in Table 4.5.

Table 4.5 Description of the eight variables used to define the fields written to the output files.

Field Entry

Variable Type

Description

module_name

CHARACTER(len=128)

Module that contains the field_name variable. (e.g. dynamic, gfs_phys, gfs_sfc)

field_name

CHARACTER(len=128)

The name of the variable as registered in the model.

output_name

CHARACTER(len=128)

Name of the field as written in file_name.

file_name

CHARACTER(len=128)

Name of the file where the field is to be written.

time_sampling

CHARACTER(len=50)

Currently not used. Please use the string “all”.

reduction_method

CHARACTER(len=50)

The data reduction method to perform prior to writing data to disk. Current supported option is .false.. See FMS/diag_manager/diag_table.F90 for more information.

regional_section

CHARACTER(len=50)

Bounds of the regional section to capture. Current supported option is “none”. See FMS/diag_manager/diag_table.F90 for more information.

packing

INTEGER

Fortran number KIND of the data written. Valid values: 1=double precision, 2=float, 4=packed 16-bit integers, 8=packed 1-byte (not tested).

Comments can be added to the diag_table using the hash symbol (#).

A brief example of the diag_table is shown below. “...” denote where lines have been removed.

 20161003.00Z.C96.64bit.non-mono
 2016 10 03 00 0 0

 "grid_spec",     -1,  "months",   1, "days",  "time"
 "atmos_4xdaily",  6,  "hours",    1, "days",  "time"
 "atmos_static"   -1,  "hours",    1, "hours", "time"
 "fv3_history",    0,  "hours",    1, "hours", "time"
 "fv3_history2d",  0,  "hours",    1, "hours", "time"

 #
 #=======================
 # ATMOSPHERE DIAGNOSTICS
 #=======================
 ###
 # grid_spec
 ###
  "dynamics", "grid_lon",  "grid_lon",  "grid_spec", "all", .false.,  "none", 2,
  "dynamics", "grid_lat",  "grid_lat",  "grid_spec", "all", .false.,  "none", 2,
  "dynamics", "grid_lont", "grid_lont", "grid_spec", "all", .false.,  "none", 2,
  "dynamics", "grid_latt", "grid_latt", "grid_spec", "all", .false.,  "none", 2,
  "dynamics", "area",      "area",      "grid_spec", "all", .false.,  "none", 2,
 ###
 # 4x daily output
 ###
  "dynamics",  "slp",       "slp",      "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "vort850",   "vort850",  "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "vort200",   "vort200",  "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "us",        "us",       "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "u1000",     "u1000",    "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "u850",      "u850",     "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "u700",      "u700",     "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "u500",      "u500",     "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "u200",      "u200",     "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "u100",      "u100",     "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "u50",       "u50",      "atmos_4xdaily", "all", .false.,  "none", 2
  "dynamics",  "u10",       "u10",      "atmos_4xdaily", "all", .false.,  "none", 2

 ...
 ###
 # gfs static data
 ###
  "dynamics",  "pk",        "pk",       "atmos_static",  "all", .false.,  "none", 2
  "dynamics",  "bk",        "bk",       "atmos_static",  "all", .false.,  "none", 2
  "dynamics",  "hyam",     "hyam",      "atmos_static",  "all", .false.,  "none", 2
  "dynamics",  "hybm",     "hybm",       "atmos_static",  "all", .false.,  "none", 2
  "dynamics",  "zsurf",    "zsurf",      "atmos_static",  "all", .false.,  "none", 2
 ###
 # FV3 variables needed for NGGPS evaluation
 ###
 "gfs_dyn",    "ucomp",      "ugrd",     "fv3_history",    "all",  .false.,  "none",  2
 "gfs_dyn",    "vcomp",      "vgrd",     "fv3_history",    "all",  .false.,  "none",  2
 "gfs_dyn",    "sphum",      "spfh",     "fv3_history",    "all",  .false.,  "none",  2
 "gfs_dyn",    "temp",       "tmp",      "fv3_history",    "all",  .false.,  "none",  2
 ...
 "gfs_phys",  "ALBDO_ave",    "albdo_ave", "fv3_history2d", "all", .false., "none",  2
 "gfs_phys",  "cnvprcp_ave",  "cprat_ave", "fv3_history2d", "all", .false., "none",  2
 "gfs_phys",  "cnvprcpb_ave", "cpratb_ave","fv3_history2d", "all", .false., "none",  2
 "gfs_phys",  "totprcp_ave",  "prate_ave", "fv3_history2d", "all", .false., "none",  2
 ...
 "gfs_sfc",   "crain",   "crain",    "fv3_history2d",  "all",  .false.,  "none",  2
 "gfs_sfc",   "tprcp",   "tprcp",    "fv3_history2d",  "all",  .false.,  "none",  2
 "gfs_sfc",   "hgtsfc",  "orog",     "fv3_history2d",  "all",  .false.,  "none",  2
 "gfs_sfc",   "weasd",   "weasd",    "fv3_history2d",  "all",  .false.,  "none",  2
 "gfs_sfc",   "f10m",    "f10m",     "fv3_history2d",  "all",  .false.,  "none",  2
...

More information on the content of this file can be found in FMS/diag_manager/diag_table.F90.

Note

None of the lines in the diag_table can span multiple lines.

4.1.3.2. field_table file

The FMS field and tracer managers are used to manage tracers and specify tracer options. All tracers advected by the model must be registered in an ASCII table called field_table. The field table consists of entries in the following format:

The first line of an entry should consist of three quoted strings:
  • The first quoted string will tell the field manager what type of field it is. The string “TRACER” is used to declare a field entry.

  • The second quoted string will tell the field manager which model the field is being applied to. The supported type at present is “atmos_mod” for the atmosphere model.

  • The third quoted string should be a unique tracer name that the model will recognize.

The second and following lines are called methods. These lines can consist of two or three quoted strings. The first string will be an identifier that the querying module will ask for. The second string will be a name that the querying module can use to set up values for the module. The third string, if present, can supply parameters to the calling module that can be parsed and used to further modify values.

An entry is ended with a forward slash (/) as the final character in a row. Comments can be inserted in the field table by having a hash symbol (#) as the first character in the line.

Below is an example of a field table entry for the tracer called “sphum”:

# added by FRE: sphum must be present in atmos
# specific humidity for moist runs
 "TRACER", "atmos_mod", "sphum"
           "longname",     "specific humidity"
           "units",        "kg/kg"
           "profile_type", "fixed", "surface_value=3.e-6" /

In this case, methods applied to this tracer include setting the long name to “specific humidity”, the units to “kg/kg”. Finally a field named “profile_type” will be given a child field called “fixed”, and that field will be given a field called “surface_value” with a real value of 3.E-6. The “profile_type” options are listed in Table 4.6. If the profile type is “fixed” then the tracer field values are set equal to the surface value. If the profile type is “profile” then the top/bottom of model and surface values are read and an exponential profile is calculated, with the profile being dependent on the number of levels in the component model.

Table 4.6 Tracer profile setup from FMS/tracer_manager/tracer_manager.F90.

Method Type

Method Name

Method Control

profile_type

fixed

surface_value = X

profile_type

profile

surface_value = X, top_value = Y (atmosphere)

For the case of

"profile_type","profile","surface_value = 1e-12, top_value = 1e-15"

in a 15 layer model this would return values of surf_value = 1e-12 and multiplier = 0.6309573, i.e 1e-15 = 1e-12*(0.6309573^15).

A method is a way to allow a component module to alter the parameters it needs for various tracers. In essence, this is a way to modify a default value. A namelist can supply default parameters for all tracers and a method, as supplied through the field table, will allow the user to modify the default parameters on an individual tracer basis. The lines in this file can be coded quite flexibly. Due to this flexibility, a number of restrictions are required. See FMS/field_manager/field_manager.F90 for more information.

4.1.3.3. model_configure file

This file contains settings and configurations for the NUOPC/ESMF main component, including the simulation start time, the processor layout/configuration, and the I/O selections. Table 4.7 shows the following parameters that can be set in model_configure at run-time.

Table 4.7 Parameters that can be set in model_configure at run-time.

Parameter

Meaning

Type

Default Value

print_esmf

flag for ESMF PET files

logical

.true.

PE_MEMBER01

total number of tasks for ensemble number 1

integer

150 (for c96 with quilt)

start_year

start year of model integration

integer

2019

start_month

start month of model integration

integer

09

start_day

start day of model integration

integer

12

start_hour

start hour of model integration

integer

00

start_minute

start minute of model integration

integer

0

start_second

start second of model integration

integer

0

nhours_fcst

total forecast length

integer

48

dt_atmos

atmosphere time step in second

integer

1800 (for C96)

output_1st_tstep_rst

output first time step history file after restart

logical

.false.

memuse_verbose

flag for printing out memory usage

logical

.false.

atmos_nthreads

number of threads for atmosphere

integer

4

restart_interval

frequency to output restart file

integer

0 (write restart file at the end of integration)

quilting

flag to turn on quilt

logical

.true.

write_groups

total number of groups

integer

2

write_tasks_per_group

total number of write tasks in each write group

integer

6

output_history

flag to output history files

logical

.true.

num_files

number of output files

integer

2

filename_base

file name base for the output files

character(255)

‘atm’ ‘sfc’

output_grid

output grid

character(255)

gaussian_grid

output_file

output file format

character(255)

nemsio

imo

i-dimension for output grid

integer

384

jmo

j-dimension for output grid

integer

190

nfhout

history file output frequency

integer

3

nfhmax_hf

forecast length of high history file

integer

0 (0:no high frequency output)

nfhout_hf

high history file output frequency

integer

1

nsout

output frequency of number of time step

integer

-1 (negative: turn off the option, 1: output history file at every time step)

Table 4.8 shows the following parameters in model_configure that are not usually changed.

Table 4.8 Parameters that are not usually changed in model_configure at run-time.

Parameter

Meaning

Type

Default Value

total_member

total number of ensemble member

integer

1

RUN_CONTINUE

Flag for more than one NEMS run

logical

.false.

ENS_SPS

flag for the ensemble stochastic coupling flag

logical

.false.

calendar

type of calendar year

character(*)

‘gregorian’

fhrot

forecast hour at restart for nems/earth grid component clock in coupled model

integer

0

cpl

flag for coupling with MOM6/CICE5

logical

.false.

write_dopost

flag to do post on write grid component

logical

.false.

ideflate

lossless compression level

integer

1 (0:no compression, range 1-9)

nbits

lossy compression level

integer

14 (0: lossless, range 1-32)

write_nemsioflip

flag to flip the vertical level for nemsio file

logical

.true.

write_fsyncflag

flag to check if a file is synced to disk

logical

.true.

iau_offset

IAU offset lengdth

integer

0

4.1.3.4. nems.configure file

This file contains information about the various NEMS components and their run sequence. In the current release, this is an atmosphere-only model, so this file is simple and does not need to be changed. A sample of the file contents is below:

EARTH_component_list: ATM
ATM_model:            fv3
runSeq::
  ATM
::

4.1.3.5. The SDF (Suite Definition File) file

There are two SDFs currently supported for the UFS Medium Range Weather App configuration: suite_FV3_GFS_v15p2.xml and suite_FV3_GFS_v16beta.xml.

There are two SDFs currently supported for the UFS Short Range Weather App configuration: suite_FV3_GFS_v15p2.xml and suite_FV3_RRFS_v1alpha.xml.

Detailed descriptions of the supported suites can be found with the CCPP v5.0.0 Scientific Documentation.

4.1.4. Namelist file input.nml

The atmosphere model reads many parameters from a Fortran namelist file, named input.nml. This file contains several Fortran namelist records, some of which are always required, others of which are only used when selected physics options are chosen.

The following link provides an in depth description of the namelist settings:

https://dtcenter.ucar.edu/GMTB/v5.0.0/sci_doc/

The following link describes the various physics-related namelist records:

https://dtcenter.ucar.edu/GMTB/v5.0.0/sci_doc/CCPPsuite_nml_desp.html

The following link describes the stochastic physics namelist records:

https://stochastic-physics.readthedocs.io/en/ufs-v1.1.0/namelist_options.html

The following link describes some of the other namelist records (dynamics, grid, etc):

https://noaa-emc.github.io/FV3_Dycore_ufs-v1.1.0/html/index.html

The namelist section &interpolator_nml is not used in this release, and any modifications to it will have no effect on the model results.

4.1.4.1. fms_io_nml

The namelist section &fms_io_nml of input.nml contains variables that control reading and writing of restart data in netCDF format. There is a global switch to turn on/off the netCDF restart options in all of the modules that read or write these files. The two namelist variables that control the netCDF restart options are fms_netcdf_override and fms_netcdf_restart. The default values of both flags are .true., so by default, the behavior of the entire model is to use netCDF IO mode. To turn off netCDF restart, simply set fms_netcdf_restart to .false.. The namelist variables used in &fms_io_nml are described in Table 4.9.

Table 4.9 Description of the &fms_io_nml namelist section.

Variable Name

Description

Data Type

Default Value

fms_netcdf_override

If true, fms_netcdf_restart overrides the individual do_netcdf_restart value. If false, individual module settings has a precedence over the global setting, therefore fms_netcdf_restart is ignored.

logical

.true.

fms_netcdf_restart

If true, all modules using restart files will operate under netCDF mode. If false, all modules using restart files will operate under binary mode. This flag is effective only when fms_netcdf_override is .true. When fms_netcdf_override is .false., individual module setting takes over.

logical

.true.

threading_read

Can be ‘single’ or ‘multi’

character(len=32)

‘multi’

format

Format of restart data. Only netCDF format is supported in fms_io.

character(len=32)

‘netcdf’

read_all_pe

Reading can be done either by all PEs (default) or by only the root PE.

logical

.true.

iospec_ieee32

If set, call mpp_open single 32-bit ieee file for reading.

character(len=64)

‘-N ieee_32’

max_files_w

Maximum number of write files

integer

40

max_files_r

Maximum number of read files

integer

40

time_stamp_restart

If true, time_stamp will be added to the restart file name as a prefix.

logical

.true.

print_chksum

If true, print out chksum of fields that are read and written through save_restart/restore_state.

logical

.false.

show_open_namelist_file_warning

Flag to warn that open_namelist_file should not be called when INTERNAL_FILE_NML is defined.

logical

.false.

debug_mask_list

Set debug_mask_list to true to print out mask_list reading from mask_table.

logical

.false.

checksum_required

If true, compare checksums stored in the attribute of a field against the checksum after reading in the data.

logical

.true.

This release of the UFS Weather Model sets the following variables in the &fms_io_nml namelist:

&fms_io_nml
  checksum_required = .false.
  max_files_r = 100
  max_files_w = 100
/

4.1.4.2. namsfc

The namelist section &namsfc contains the filenames of the static datasets (i.e., fix files). Table 4.1 contains a brief description of the climatological information in these files. The variables used in &namsfc to set the filenames are described in Table 4.10.

Table 4.10 List of common variables in the *namsfc namelist section used to set the filenames of static datasets.*

Variable Name

File contains

Data Type

Default Value

fnglac

Climatological glacier data

character*500

‘global_glacier.2x2.grb’

fnmxic

Climatological maximum ice extent

character*500

‘global_maxice.2x2.grb’

fntsfc

Climatological surface temperature

character*500

‘global_sstclim.2x2.grb’

fnsnoc

Climatological snow depth

character*500

‘global_snoclim.1.875.grb’

fnzorc

Climatological surface roughness

character*500

‘global_zorclim.1x1.grb’

fnalbc

Climatological snowfree albedo

character*500

‘global_albedo4.1x1.grb’

fnalbc2

Four albedo fields for seasonal mean climatology

character*500

‘global_albedo4.1x1.grb’

fnaisc

Climatological sea ice

character*500

‘global_iceclim.2x2.grb’

fntg3c

Climatological deep soil temperature

character*500

‘global_tg3clim.2.6x1.5.grb’

fnvegc

Climatological vegetation cover

character*500

‘global_vegfrac.1x1.grb’

fnvetc

Climatological vegetation type

character*500

‘global_vegtype.1x1.grb’

fnsotc

Climatological soil type

character*500

‘global_soiltype.1x1.grb’

fnsmcc

Climatological soil moisture

character*500

‘global_soilmcpc.1x1.grb’

fnmskh

High resolution land mask field

character*500

‘global_slmask.t126.grb’

fnvmnc

Climatological minimum vegetation cover

character*500

‘global_shdmin.0.144x0.144.grb’

fnvmxc

Climatological maximum vegetation cover

character*500

‘global_shdmax.0.144x0.144.grb’

fnslpc

Climatological slope type

character*500

‘global_slope.1x1.grb’

fnabsc

Climatological maximum snow albedo

character*500

‘global_snoalb.1x1.grb’

A sample subset of this namelist is shown below:

&namsfc
  FNGLAC   = 'global_glacier.2x2.grb'
  FNMXIC   = 'global_maxice.2x2.grb'
  FNTSFC   = 'RTGSST.1982.2012.monthly.clim.grb'
  FNSNOC   = 'global_snoclim.1.875.grb'
  FNZORC   = 'igbp'
  FNALBC   = 'global_snowfree_albedo.bosu.t126.384.190.rg.grb'
  FNALBC2  = 'global_albedo4.1x1.grb'
  FNAISC   = 'CFSR.SEAICE.1982.2012.monthly.clim.grb'
  FNTG3C   = 'global_tg3clim.2.6x1.5.grb'
  FNVEGC   = 'global_vegfrac.0.144.decpercent.grb'
  FNVETC   = 'global_vegtype.igbp.t126.384.190.rg.grb'
  FNSOTC   = 'global_soiltype.statsgo.t126.384.190.rg.grb'
  FNSMCC   = 'global_soilmgldas.t126.384.190.grb'
  FNMSKH   = 'seaice_newland.grb'
  FNVMNC   = 'global_shdmin.0.144x0.144.grb'
  FNVMXC   = 'global_shdmax.0.144x0.144.grb'
  FNSLPC   = 'global_slope.1x1.grb'
  FNABSC   = 'global_mxsnoalb.uariz.t126.384.190.rg.grb'
/

Additional variables for the &namsfc namelist can be found in the FV3/ccpp/physics/physics/sfcsub.F file.

4.1.4.3. atmos_model_nml

The namelist section &atmos_model_nml contains information used by the atmosphere model. The variables used in &atmos_model_nml are described in Table 4.11.

Table 4.11 List of common variables in the *atmos_model_nml namelist section.

Variable Name

Description

Data Type

Default Value

blocksize

Number of columns in each block sent to the physics. OpenMP threading is done over the number of blocks. For best performance this number should divide the number of grid cells per processor: ((npx-1)*(npy-1)/(layout\_x)*(layout\_y)). A description of these variables is provided here.

integer

1

chksum_debug

If true, compute checksums for all variables passed into the GFS physics, before and after each physics timestep. This is very useful for reproducibility checking.

logical

.false.

dycore_only

If true, only the dynamical core (and not the GFS physics) is executed when running the model, essentially running the model as a solo dynamical core.

logical

.false.

debug

If true, turn on additional diagnostics for the atmospheric model.

logical

.false.

sync

If true, initialize timing identifiers.

logical

.false.

fdiag

Array with dimension maxhr = 4096 listing the diagnostic output times (in hours) for the GFS physics. This can either be a list of times after initialization, or an interval if only the first entry is nonzero. The default setting of 0 will result in no outputs.

real

fhmax

The maximal forecast time for output.

real

384.0

fhmaxhf

The maximal forecast hour for high frequency output.

real

120.0

fhout

Output frequency during forecast time from 0 to fhmax, or from fhmaxhf to fhmax if fhmaxf>0.

real

3.0

fhouthf

The high frequency output frequency during the forecast time from 0 to fhmaxhf hour.

real

1.0

ccpp_suite

Name of the CCPP physics suite

character(len=256)

FV3_GFS_v15p2, set in build.sh

avg_max_length

Forecast interval (in seconds) determining when the maximum values of diagnostic fields in FV3 dynamics are computed.

real

A sample of this namelist is shown below:

&atmos_model_nml
  blocksize = 32
  chksum_debug = .false.
  dycore_only = .false.
  fdiag = 1
  fhmax = 384
  fhout = 3
  fhmaxhf = 120
  fhouthf = 1
  ccpp_suite = 'FV3_GFS_v16beta'
/

The namelist section relating to the FMS diagnostic manager &diag_manager_nml is described in Section 4.3.1.

4.2. Output files

The output files generated when running fv3.exe are defined in the diag_tabl file. For the default global configuration, the following files are output (six files of each kind, corresponding to the six tiles of the model grid):

  • atmos_4xdaily.tile[1-6].nc

  • atmos_static.tile[1-6].nc

  • sfcfHHH.nc

  • atmfHHH.nc

  • grid_spec.tile[1-6].nc

Note that the sfcf* and atmf* files are not output on the 6 tiles, but instead as a single global gaussian grid file. The specifications of the output files (format, projection, etc) may be overridden in the model_configure input file, see Section 4.1.3.3.

The regional configuration will generate similar output files, but the tile[1-6] is not included in the filename.

Two files (model_configure and diag_table) control the output that is generated by the UFS Weather Model. The output files that contain the model variables are written to a file as shown in the figure below. The format of these output files is selected in model_configure as NetCDF or nemsio. The information in these files may be remapped, augmented with derived variables, and converted to GRIB2 by the Unified Post Processor (UPP). Model variables are listed in the diag_table in two groupings, fv3_history and fv3_history2d, as described in Section 4.1.3.1. The names of the files that contain these model variables are specified in the model_configure file. When quilting is set to .true. for the write component, the variables listed in the groups fv3_history and fv3_history2d are converted into the two output files named in the model_configure file, e.g. atmfHHH. and sfcfHHH.. The bases of the file names (atm and sfc) are specified in the model_configure file, and HHH refers to the forecast hour.

_images/fv3IO.png

Standard output files are logfHHH (one per forecast hour), and out and err as specified by the job submission. ESMF may also produce log files (controlled by variable print_esmf in the model_configure file), called PETnnn.ESMF_LogFile (one per MPI task).

Additional output files include: nemsusage.xml, a timing log file; time_stamp.out, contains the model init time; RESTART/*nc, files needed for restart runs.

4.3. Additional Information about the FMS Diagnostic Manager

The UFS Weather Model output is managed through the FMS (Flexible Modeling System) diagnostic manager (FMS/diag_manager) and is configured using the diag_table file. Data can be written at any number of sampling and/or averaging intervals specified at run-time. More information about the FMS diagnostic manager can be found at: https://data1.gfdl.noaa.gov/summer-school/Lectures/July16/03_Seth1_DiagManager.pdf

4.3.1. Diagnostic Manager namelist

The diag_manager_nml namelist contains values to control the behavior of the diagnostic manager. Some of the more common namelist options are described in Table 4.12. See FMS/diag_manager/diag_manager.F90 for the complete list.

Table 4.12 Namelist variables used to control the behavior of the diagnostic manager.

Namelist variable

Type

Description

Default value

max_files

INTEGER

Maximum number of files allowed in diag_table

31

max_output_fields

INTEGER

Maximum number of output fields allowed in diag_table

300

max_input_fields

INTEGER

Maximum number of registered fields allowed

300

prepend_date

LOGICAL

Prepend the file start date to the output file. .TRUE. is only supported if the diag_manager_init routine is called with the optional time_init parameter.

.TRUE.

do_diag_field_log

LOGICAL

Write out all registered fields to a log file

.FALSE.

use_cmor

LOGICAL

Override the missing_value to the CMOR value of -1.0e20

.FALSE.

issue_oor_warnings

LOGICAL

Issue a warning if a value passed to diag_manager is outside the given range

.TRUE.

oor_warnings_fatal

LOGICAL

Treat out-of-range errors as FATAL

.FALSE.

debug_diag_manager

LOGICAL

Check if the diag table is set up correctly

.FALSE.

This release of the UFS Weather Model uses the following namelist:

&diag_manager_nml
  prepend_date = .false.
/

4.4. Additional Information about the Write Component

The UFS Weather Model is built using the Earth System Modeling Framework (ESMF). As part of this framework, the output history files written by the model use an ESMF component, referred to as the write component. This model component is configured with settings in the model_configure file, as described in Section 4.1.3.3. By using the ESMF capabilities, the write component can generate output files in several different formats and several different map projections. For example, a Gaussian global grid in NEMSIO format, or a native grid in NetCDF format. The write component also runs on independent MPI tasks, and so the computational tasks can continue while the write component completes its work asynchronously. The configuration of write component tasks, balanced with compute tasks, is part of the tuning for each specific application of the model (HPC, write frequency, i/o speed, model domain, etc). For the global grid, if the write component is not selected (quilting=.false.), the FV3 code will write tiled output in the native projection in NetCDF format. The regional grid requires the use of the write component.