PUBLIC INTERFACE ~ PUBLIC ROUTINES ~ ERROR MESSAGES

Module diag_table_mod

Contact:  Seth Underwood
Reviewers: 
Change History: WebCVS Log


OVERVIEW

diag_table_mod is a set of subroutines use to parse out the data from a diag_table. This module will also setup the arrays required to store the information by counting the number of input fields, output files, and files.

diag_table_mod parses the diag_table file, and sets up the required arrays to hold the information needed for the diag_manager_mod to correctly write out the model history files. The diagnostics table allows users to specify sampling rates and the choice of fields at run time. The diag_table file consists of comma-separated ASCII values. The diag_table essentially has three sections: Global, File, and Field sections. The Global section must be the first two lines of the file, whereas the File and Field sections can be inter mixed to allow the file to be organized as desired. Comments can be added to the diag_table file by using the hash symbol (#) as the first character in the line. All errors in the diag_table will throw a FATAL error. A simple utility diag_table_chkhas been added to the FRE tools suite to check a diag_table for errors. A brief usage statement can be obtained by running diag_table_chk --help, and a man page like description can views by running perldoc diag_table_chk. Below is a description of the three sections.
  1. Global Section: The first two lines of the diag_table must contain the title and the base date of the experiment respectively. 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 integer in the following format.
    year month day hour minute second
  2. File Section: File lines contain 6 required and 5 optional fields (optional fields are surrounded with square brackets ([]). File lines can be intermixed with the field lines, but the file must be defined before any fields that are to be written to the file. File lines 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"]]]
    with the following descriptions.
    CHARACTER(len=128) :: file_name
    Output file name without the trailing ".nc". A single file description can produce multiple files using special time string suffix keywords. This time string will append the time strings to the base file name each time a new file is opened. They syntax for the time string suffix keywords are %#tt Where # is a mandatory single digit number specifying the width of the field, and tt can be as follows:
    1. yr – Years
    2. mo – Months
    3. dy – Days
    4. hr – Hours
    5. mi – Minutes
    6. sc – Seconds
    Thus, a file name of file2_yr_dy%1yr%3dy will have a base file name of file2_yr_dy_1_001 if the file is created on year 1 day 1 of the model run. NOTE: The time suffix keywords must be used if the optional fields new_file_freq and new_file_freq_units are used, otherwise a FATAL error will occur.
    INTEGER :: output_freq
    How often to write fields to file.
    1. > 0 – Output frequency in output_freq_units.
    2. = 0 – Output frequency every time set. (output_freq_units is ignored.)
    3. =-1 – Output at end of run only. (output_freq_units is ignored.)
    CHARACTER(len=10) :: output_freq_units
    Time units for output. Can be either years, months, days, minutes, hours, or seconds.
    INTEGER :: file_format
    Output file format. Currently only the netCDF file format is supported.
    1. = 1 – netCDF
    CHARACTER(len=10) :: time_axis_units
    Time units for the output file time axis. Can be either years, months, days, minutes, hours, or seconds.
    CHARACTER(len=128) :: time_axis_name
    Axis name for the output file time axis. The character sting must contain the string 'time'. (mixed upper and lowercase allowed.)
    INTEGER, OPTIONAL :: new_file_freq
    Frequency for closing the existing file, and creating a new file in new_file_freq_units.
    CHARACTER(len=10), OPTIONAL :: new_file_freq_units
    Time units for creating a new file. Can be either years, months, days, minutes, hours, or seconds. NOTE: If the new_file_freq field is present, then this field must also be present.
    CHARACTER(len=25), OPTIONAL :: start_time
    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.
    INTEGER, OPTIONAL :: file_duration
    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.
    CHARACTER(len=10), OPTIONAL :: file_duration_units
    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.
  3. Field Section: Field lines contain 8 fields. Field lines can be intermixed with file lines, but the file must be defined before any fields that are to be written to the file. Fields line can contain fields that are not written to any files. The file name for these fields is null. Field lines have the following format:
     "module_name", "field_name", "output_name", "file_name", "time_sampling", "reduction_method", "regional_section", packing
    with the following descriptions.
    CHARACTER(len=128) :: module_name
    Module that contains the field_name variable. (e.g. atmos_mod, land_mod)
    CHARACTER(len=128) :: field_name
    Module variable name that has data to be written to file.
    CHARACTER(len=128) :: output_name
    Name of the field as written in file_name.
    CHARACTER(len=128) :: file_name
    Name of the file where the field is to be written. NOTE: The file file_name must be defined first.
    CHARACTER(len=50) :: time_sampling
    Currently not used. Please use the string "all".
    CHARACTER(len=50) :: reduction_method
    The data reduction method to perform prior to writing data to disk. Valid options are (redundant names are separated with commas):
    .TRUE., average
    Average from the last time written to the current time.
    .FALSE., none
    No reduction performed. Write current time step value only.
    min
    Minimum value from last write to current time.
    max
    Maximum value from last write to current time.
    diurnal##
    ## diurnal averages
    CHARACTER(len=50) :: regional_section
    Bounds of the regional section to capture. A value of none indicates a global region. The regional section has the following format:
    lat_min, lat_max, lon_min, lon_max, vert_min, vert_max
    Use vert_min = -1 and vert_max = -1 to get the entire vertical axis. NOTE: Currently, the defined region MUST be confined to a single tile.
    INTEGER :: packing
    Fortran number KIND of the data written. Valid values:
    1. = 1 – double precision
    2. = 2 – float
    3. = 4 – packed 16-bit integers
    4. = 8 – packed 1-byte (not tested).

Sample diag_table

  1.  "diag manager test"
     1999 1 1 0 0 0
    
     #output files
     10_days,               10, "days", 1, "hours", "Time"
     "file1_hr%hr3",         5, "days", 1, "hours", "Time", 15, "days"
     "file2_yr_dy%yr1%dy3",  5, "days", 1, "hours", "Time", 10, "days", "1 1 7 0 0 0"
     "file3_yr_dy%yr1%dy3",  5, "days", 1, "hours", "Time", 20, "days", "1 1 7 0 0 0", 5, "years"
    
     #output variables
     "ice_mod", "ice", "ice", "10_days", "all", .false., "none", 2
    
     # temp_local file and fields.
     temp_local, 1, "days", 1, "hours", "Time"
     "ocean_mod", "temp", "temp", "temp_local", "all", .FALSE., "5 259.5 -59.5 59.5 1 1", 2

Useful Additional Utility

A simple utility has been created to help discover


OTHER MODULES USED

      mpp_io_mod
mpp_mod
fms_mod
time_manager_mod
constants_mod
diag_data_mod
diag_util_mod

PUBLIC INTERFACE

parse_diag_table:
Parse the diag_table in preparation for diagnostic output.


PUBLIC ROUTINES

  1. parse_diag_table

    SUBROUTINE parse_diag_table (diag_subset, istat, err_msg)
    DESCRIPTION
    parse_diag_table is the public interface to parse the diag_table, and setup the arrays needed to store the requested diagnostics from the diag_table. parse_diag_table will return a non-zero istat if a problem parsing the diag_table. NOT YET IMPLEMENTED: parse_diag_table will parse through the diag_table twice. The first pass, will be to get a good "guess" of array sizes. These arrays, that will hold the requested diagnostic fields and files, will then be allocated to the size of the "guess" plus a slight increase.


    INPUT
    diag_subset    Diagnostic sampling subset.
       [INTEGER, OPTIONAL]

    OUTPUT
    iunit    Status of parsing the diag_table. A non-zero status indicates a problem parsing the table.
       [INTEGER, OPTIONAL]
    err_msg    Error message corresponding to the istat return value.
       [CHARACTER(len=*), OPTIONAL]


ERROR MESSAGES

FATAL in parse_diag_table
diag_table file does not exist.
FATAL in parse_diag_table
Error reading the global descriptor from the diagnostic table.
FATAL in parse_diag_table
Error reading the base date from the diagnostic table.
FATAL in parse_diag_table
The base_year/month/day can not equal zero
WARNING in parse_diag_table
Problem reading diag_table, line numbers in errors may be incorrect.
FATAL in parse_diag_table
Problem reading the diag_table (line: <line_number>)
FATAL in parse_diag_table
Incorrect file description FORMAT in diag_table. (line: <line_number>)
FATAL in parse_diag_table
Invalid file FORMAT for file description in the diag_table. (line: <line_number>)
FATAL in parse_diag_table
Invalid time axis units in diag_table. (line: <line_number>)
FATAL in parse_diag_table
Invalid output frequency units in diag_table. (line: <line_number>)
FATAL in parse_diag_table
Invalid NEW file frequency units in diag_table. (line: <line_number>)
FATAL in parse_diag_table
Invalid file duration units in diag_table. (line: <line_number>)
FATAL in parse_diag_table
Invalid start time in the file description in diag_table. (line: <line_number>)
FATAL in parse_diag_table
Field description FORMAT is incorrect in diag_table. (line: <line_number>)
FATAL in parse_diag_table
Packing is out of range for the field description in diag_table. (line: <line_number>)
FATAL in parse_diag_table
Error in regional output description for field description in diag_table. (line: <line_number>)


top