Module diag_table

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.

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
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.
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`

 "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

`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]