2.1. UPP Inputs and Outputs

This section describes the input files used to run the UPP and the resulting output files.

2.1.1. Input Files

The UPP requires the following input files:

  • The model forecast file

  • The itag namelist file

  • The GRIB2 control file (e.g., postxconfig-NT.txt)

  • Additional data files (e.g., lookup tables, coefficient files for satellites)

2.1.1.1. Model Forecast

The UPP ingests FV3 write component files in parallel netCDF format.

The table below is a list of the unified model variables available from the FV3 model core. Whether a specific variable is able to be read by the UPP relies on dependencies such as physics options and choice of model. This table does not include variables that are diagnosed when running the UPP.

UFS Unified Model Variables

2.1.1.2. ITAG

The file called itag is a Fortran namelist file that contains two sections: &model_inputs and &nampgb. It is read in by the upp.x executable from standard input (stdin – unit 5). Most UFS applications generate it automatically based on user-defined application-level options. All UPP namelist choices are described here.

&model_inputs

The &model_inputs section parameterizes choices about the set of model output files that will be used for the UPP.

Description of the &model_inputs namelist section.

Variable Name

Description

Data Type

Default Value

datestr

Time stamp being processed (e.g., 2022-08-02_19:00:00).

character(len=19)

n/a

filename

Name of input dynamics file; name of full 3-D model output file.

character(len=256)

n/a

filenameflat

Input configuration text file defining the requested fields.

character(len=256)

postxconfig-NT.txt

filenameflux

Name of input physics file; name of 2-D model output file with physics and surface fields.

character(len=256)

n/a

grib

Grib type (Note that UPP only supports Grib2 currently)

character(5)

grib2

ioform

Input file format. Choices: binarynemsio or netcdf

character(len=20)

n/a

modelname

Model name used by UPP internally (e.g., FV3R for RRFS, 3DRTMA, HAFS; GFS for GFS and GEFS; RAPR for RAP and HRRR; NMM for NAM)

character(len=4)

n/a

&nampgb

The &nampgb section parameterizes choices concerning the processing done in UPP.

Description of the &nampgb namelist section.

Variable Name

Description

Data Type

Default Value

aqf_on

Turn on Air Quality Forecasting (CMAQ-based)

logical

.false.

d2d_chem

Turn on option to process the 2D aerosol/chemical tracers

logical

.false.

d3d_on

Turn on option to use dynamic 3D fields from GFS

logical

.false.

filenameaer

aerosols file name

character(len=256)

“”

gccpp_on

Turn on option to process the aerosol/chemical tracers related output from UFS-Chem (CCPP-Chem) model

logical

.false.

gocart_on

Turn on option to process the aerosol/chemical tracers related output from GEFS-Aerosols model (GOCART)

logical

.false.

gtg_on

Turn on GTG (Graphical Turbulence Guidance)

logical

.false.

hyb_sigp

Not used

logical

.true.

kpo

The number of pressure levels, if different than standard one specified by SPLDEF described below.

integer

0

kpv

The number of output potential vorticity levels

integer

8

kth

The number of output isentropic levels

integer

6

method_blsn

Turn on blowing snow effect on visibility diagnostic (default=true)

logical

.true.

nasa_on

Turn on option to process the aerosol/chemical tracers related output from UFS-Aerosols model (NASA GOCART)

logical

.false.

numx

The number of i regions in a 2D decomposition; Each i row is distibuted to numx ranks; numx=1 is the special case of a 1D decomposition in Y only.

integer

1

po

List indicating pressure levels in output

real,dimension(70)

0

popascal

Switch to indicate if pressure levels are in pascals (multply by 100 if false)

logical

.false.

pv

List indicating the potential vorticity level output

real,dimension(70)

(/0.5,-0.5,1.0,-1.0,1.5,-1.5,2.0,-2.0,(0.,k=kpv+1,70)/)

rdaod

Turn on the option to process the AOD from the GFS scheme

logical

.false.

slrutah_on

Calculate snow to liquid ratio (SLR) using method from University of Utah.(default=false)

logical

.false.

th

List indicating isentropic level output

real,dimension(70)

(/310.,320.,350.,450.,550.,650.,(0.,k=kth+1,70)/)

vtimeunits

valid time units, default=””, Choices: FMIN

character(len=4)

“”

write_ifi_debug_files

Write debug files for In-Flight Icing (IFI), a restricted option in UPP

logical

.false.

2.1.1.3. Control File

The user interacts with the UPP through the control file to define what fields and levels to output. It is composed of a header and a body. The header specifies the output file information. The body includes which fields and levels to process.

A default control file, postxconfig-NT.txt, is provided and read by the UPP. Users who wish to customize the control file to add or remove fields and/or levels may do so by modifying postcntrl.xml and then remaking the text file as described in the later section: Creating the Flat Text File.

Note

The control file names postxconfig-NT.txt and postcntrl.xml are generic names and are different depending on the application used. Control files for various operational models are located in the UPP/parm directory.

2.1.1.3.1. Selecting Which Variables the UPP Outputs

To output a field, the body of the control file needs to contain an entry for the appropriate variable. If an entry for a particular field is not yet available in the control file, it may be added to the control file with the appropriate entries for that field. For variables found on vertical levels (e.g., isobaric or height levels), the desired levels to be output must be listed (see next section: Controlling which levels the UPP outputs). A list of available GRIB2 fields that can be output by UPP can be found in the table GRIB2 Fields Produced by UPP. Please note that some fields are dependent on model, physics, and other fields.

2.1.1.3.2. Controlling which levels the UPP outputs

The <level> tag in the postcntrl.xml file is used to list the desired levels for output. The following levels are currently available for output:

  • For isobaric output, 46 levels are possible, from 2 to 1000 hPa (2, 5, 7, 10, 20, 30, 50, 70 mb and then every 25 mb from 75 to 1000 mb). The complete list of levels is specified in sorc/ncep_post.fd/CTLBLK.f.

    • Modify specification of variable LSMDEF to change the number of pressure levels: LSMDEF=47

    • Modify specification of SPLDEF array to change the values of pressure levels: (/200.,500.,700.,1000.,2000.,3000.,5000.,7000.,7500.,10000.,12500.,15000.,17500.,20000., …/)

  • For model-level output, all model levels are possible, from the highest to the lowest.

  • When using the Noah LSM, the soil layers are 0-10 cm, 10-40 cm, 40-100 cm, and 100-200 cm.

  • When using the RUC LSM, the soil levels are 0 cm, 1 cm, 4 cm, 10 cm, 30 cm, 60 cm, 100 cm, 160 cm, and 300 cm. (For the old RUC LSM, there are only 6 layers, and if using this, you will need to change NSOIL for “RUC LSM” from 9 to 6 in the sorc/ncep_post.fd/WRFPOST.f routine.)

  • When using Pliem-Xiu LSM, there are two layers: 0-1 cm, 1-100 cm

  • For low, mid, and high cloud layers, the layers are \(\geq\)642 hPa, \(\geq\)350 hPa, and <350 hPa, respectively.

  • For PBL layer averages, the levels correspond to 6 layers with a thickness of 30 hPa each.

  • For flight level, the levels are 30 m, 50 m, 80 m, 100 m, 305 m, 457 m, 610 m, 914 m, 1524 m, 1829 m, 2134 m, 2743 m, 3658 m, 4572 m, 6000 m, 7010 m.

  • For AGL radar reflectivity, the levels are 4000 and 1000 m.

  • For surface or shelter-level output, the <level> is not necessary.

2.1.1.3.3. Creating the Flat Text File

If the control file requires any modifications, a preprocessing step will be required by the user to convert the modified XML file parm/postcntrl.xml to a flat text file parm/postxconfig-NT.txt. The user will first need to edit the postcntrl.xml file to declare which fields are to be output from the UPP.

In order to ensure that the user-edited XML files are error free, XML stylesheets (parm/EMC_POST_CTRL_Schema.xsd and EMC_POST_Avblflds_Schema.xsd) can be used to validate both the postcntrl.xml and post_avblflds.xml files respectively. Confirmation of validation will be given (e.g., postcntrl.xml validates) or otherwise return errors if it does not match the schema. This step is optional, but acts as a safeguard to avoid run-time failures with the UPP. To run the validation:

xmllint --noout --schema EMC_POST_CTRL_Schema.xsd postcntrl.xml
xmllint --noout --schema EMC_POST_Avblflds_Schema.xsd post_avblflds.xml

Once the XMLs are validated, the user will need to generate the flat file. The command below will run the Perl program parm/PostXMLPreprocessor.pl to generate the post flat file:

/usr/bin/perl PostXMLPreprocessor.pl your_user_defined_xml post_avblflds.xml your_user_defined_flat

where your_user_defined_xml is your modified XML and your_user_defined_flat is the output text file.

2.1.2. Output Files

Upon a successful run, upp.x will generate GRIB2 output files in the post processor working directory. These files will include all fields that were requested in the control file.

When running UPP standalone, the following GRIB2 output files will be generated:

GFS Model: GFSPRS.HHH
LAM (Limited Area Model): NATLEV.HHH and PRSLEV.HHH

When executed with the provided run script, UPP provides log files in the post-processor working directory named upp.fHHH.out, where HHH is the forecast hour. These log files may be consulted for further runtime information in the event of an error.