5. Running UPP Stand-Alone

A script for running the UPP package is included in the /scripts directory:
  • run_upp

Before running the script, perform the following instructions:

  1. cd to your DOMAINPATH directory. This is the top working directory for the run.

  2. Make a directory to put the UPP results in.

    mkdir postprd
  3. Make a directory for staging a copy of the desired control file.

    mkdir parm
  4. Optional: If desired, edit the control XML file(s) in /UPP/parm to reflect the fields and levels you want UPP to output. It is recommended that you make copies of the original beforehand.

    GFS XMLs: postcntrl_gfs_f00.xml (0-hour lead time) and postcntrl_gfs.xml (all other lead times)
    LAM (Limited Area Model) XML: fv3lam.xml

    Re-make the flat text file(s) following the steps in the “Control File: Creating the Flat Text File” section.

  5. Copy the flat text file(s) to the /parm directory in your DOMAINPATH. These are the files that UPP reads directly.

    GFS text files: postxconfig-NT-GFS-F00.txt (0-hour lead time) and postxconfig-NT-GFS.txt (all other lead times).
    LAM text file: postxconfig-NT-fv3lam.txt
  6. Copy the /scripts/run_upp script to the /postprd directory.

  7. Edit the run script as outlined in the “Run Script Overview” section. Once these directories are set up and the edits outlined below are complete, the script can be run interactively from the /postprd directory by simply typing the script name on the command line.

5.1. Run Script Overview


It is recommended that the user refer to the run_upp script while reading this overview. All user modified variables are contained at the top of the run_upp script in the user-edit section, along with a brief description. Descriptions below follow the run_upp script.

  1. Set up basic path variables

    TOP_DIR: Top level directory for building and running UPP
    DOMAINPATH: Working directory for this run
    UNIPOST_HOME: Location of the UPP directory
    POSTEXEC: Location of the UPP executable
    modelDataPath: Location of the model output data files to be processed
    txtCntrlFile: Name and location of the flat text file that lists desired fields for output.


    For FV3, the scripts are configured such that UPP expects the flat text file to be in /parm, and the postprocessor working directory to be called /postprd, all under DOMAINPATH. This setup is for user convenience to have a script ready to run, paths may be modified but be sure to check the run script to make sure settings are correct.

  2. Specify dynamic core being run

    model: What model is used (“GFS” or “LAM” - Limited Area Model)
  3. Specify the format for the input model files and output UPP files

    inFormat: Format of the model data (“binarynemsiompiio”: GFS only or “netcdf”: GFS/LAM)
    outFormat: Format of output from UPP (“grib2”)
  4. Specify the forecast cycles to be post-processed

    startdate: Forecast start date (YYYYMMDDHH)
    fhr: First forecast hour to be post-processed
    lastfhr: Last forecast hour to be post-processed
    incrementhr: Increment (in hours) between forecast files
    Do not set to 0 or the script will loop continuously
  5. Set/uncomment the run command for your system. (i.e. mpirun, etc).

    RUN_COMMAND: System run commands
    - The default execution command in the distributed scripts is for a single processor:
    ./upp.x > upp.${fhr}.out 2>&1
    - To run UPP using mpi (dmpar compilation), the command line should be:
    >> LINUX-MPI systems: mpirun -np N upp.x > outpost 2>&1
    (Note: On some systems a host file also needs to be specified: -machinefile "host")
    >> IBM: mpirun.lsf upp.x < itag > outpost
    >> SGI MPT: mpiexec_mpt upp.x < itag > outpost
  6. Set naming convention for prefix and extension of output file name
    • comsp is the initial string of the output file name. By default it is not set and the prefix of the output file will be the string set in the XML file DATSET parameter. If set it will concatenate the setting to the front of the string specified in the XML file DATSET parameter.

    • tmmark is used for the file extension (in run_upp, tmmark=tm00; if not set, it is set to .GrbF)

Upon a successful run, UPP will generate output files for each forecast hour in the /postprd directory.

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 run-time information in the event of an error.


FV3 output is on a Guassian grid. To interpolate to a lat/lon or other projection, use wgrib2 (see Examples-of-wgrib2 section).