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

Data Types
type	field_description_type
	Private type to hold field information for the diag table. More...

type	file_description_type
	Private type to hold file information for the diag table. More...

Functions/Subroutines
pure integer function	find_unit_ivalue (unit_string)
	Return the integer value for the given time unit. More...

pure character(len=128) function	fix_file_name (file_name_string)
	Fixes the file name for use with diagnostic file and field initializations. More...

subroutine	initialize_output_arrays ()
	Allocate the file, in and out field arrays after reading the `diag_table` file. (CURRENTLY EMPTY)

pure logical function	is_a_file (line)
	Determines if a line from the diag_table file is a file. More...

subroutine, public	parse_diag_table (diag_subset, istat, err_msg)
	Parse the `diag_table` in preparation for diagnostic output. More...

type(field_description_type) function	parse_field_line (line, istat, err_msg)
	Parse a field description line from the `diag_table` file. More...

type(file_description_type) function	parse_file_line (line, istat, err_msg)
	`parse_file_line` parses a file description line from the `diag_table` file, and returns a `TYPE(file_description_type)`. The calling function, would then need to call the `init_file` to initialize the diagnostic output file. More...

Variables
character(len= *), parameter	unallowed_all = UNALLOWED_QTE//","

character(len= *), parameter	unallowed_qte = "'"//'"'

Detailed Description

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.

Author: Seth Underwood

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:
- yr Years
- mo Months
- dy Days
- hr Hours
- mi Minutes
- 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.
- > 0 <EN > Output frequency in output_freq_units.
- = 0 <EN > Output frequency every time set. (output_freq_units is ignored.)
- =-1 <EN > 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 <EN > 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. 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, avg, mean

Average from the last time written to the current time.

.FALSE., none

No reduction performed. Write current time step value only.

rms

Calculate the root mean square from the last time written to the current time.

pow##

Calculate the mean of the power ## from the last time written to the current time.

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 <EN > double precision
- = 2 <EN > float
= 4 <EN > packed 16-bit integers
- = 8 <EN > 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

Data Type Documentation

◆ diag_table_mod::field_description_type

type diag_table_mod::field_description_type

Private type to hold field information for the diag table.

Definition at line 267 of file diag_table.F90.

Collaboration diagram for field_description_type:

[legend]

Private Attributes
character(len=128)	field_name

character(len=128)	file_name

character(len=128)	module_name

character(len=128)	output_name

integer	pack

type(coord_type)	regional_coords

character(len=50)	spatial_ops

character(len=50)	time_method

character(len=50)	time_sampling

◆ diag_table_mod::file_description_type

type diag_table_mod::file_description_type

Private type to hold file information for the diag table.

Definition at line 278 of file diag_table.F90.

Collaboration diagram for file_description_type:

[legend]

Private Attributes
integer	file_duration

character(len=10)	file_duration_units

integer	file_format

character(len=fms_file_len)	file_name

character(len=10)	filename_time_bounds

integer	ifile_duration_units

integer	inew_file_freq_units

integer	ioutput_freq_units

integer	itime_units

character(len=128)	long_name

integer	new_file_freq

character(len=10)	new_file_freq_units

integer	output_freq

character(len=10)	output_freq_units

type(time_type)	start_time

character(len=25)	start_time_s

character(len=10)	time_units

Function/Subroutine Documentation

◆ find_unit_ivalue()

pure integer function diag_table_mod::find_unit_ivalue ( character(len=*), intent(in) unit_string )

private

Return the integer value for the given time unit.

Returns: Integer find_unit_ivalue

Returns the corresponding integer value for the given time unit.

seconds = 1
minutes = 2
hours = 3
days = 4
months = 5
years = 6
unknown = -1

Parameters

[in] unit_string Input string, containing the unit.

Definition at line 816 of file diag_table.F90.

◆ fix_file_name()

pure character(len=128) function diag_table_mod::fix_file_name ( character(len=*), intent(in) file_name_string )

private

Fixes the file name for use with diagnostic file and field initializations.

Returns: Character(len=128) fix_file_name

Parameters

[in] file_name_string String containing the file name from the diag_table.

Definition at line 780 of file diag_table.F90.

◆ is_a_file()

pure logical function diag_table_mod::is_a_file ( character(len=*), intent(in) line )

private

Determines if a line from the diag_table file is a file.

Returns: Logical is_a_file

is_a_file checks a diag_table line to determine if the line describes a file. If the line describes a file, the is_a_file will return .TRUE.. Otherwise, it will return .FALSE.

Parameters

[in] line String containing the diag_table line.

Definition at line 749 of file diag_table.F90.

◆ parse_diag_table()

subroutine, public diag_table_mod::parse_diag_table	(	integer, intent(in), optional	diag_subset,
		integer, intent(out), optional, target	istat,
		character(len=*), intent(out), optional	err_msg
	)

Parse the diag_table in preparation for diagnostic output.

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.

Parameters

[in]	diag_subset	Diagnostic sampling subset.
[out]	istat	Status of parsing the `diag_table`. A non-zero status indicates a problem parsing the table.
[out]	err_msg	Error message corresponding to the `istat` return value.

Definition at line 318 of file diag_table.F90.

◆ parse_field_line()

type(field_description_type) function diag_table_mod::parse_field_line	(	character(len=*), intent(in)	line,
		integer, intent(out), optional, target	istat,
		character(len=*), intent(out), optional	err_msg
	)

private

Parse a field description line from the diag_table file.

Returns: field_description_type parse_field_line

parse_field_line parses a field description line from the diag_table file, and returns a TYPE(field_description_type). The calling function, would then need to call the init_input_field and init_output_field to initialize the diagnostic output field.

Parameters

[in]	line	Line to parse from the `diag_table` file.
[out]	istat	Return state of the function. A value of 0 indicates success. A positive value indicates a `FATAL` error occurred, and a negative value indicates a `WARNING` should be issued.
[out]	err_msg	Error string to include in the `FATAL` or `WARNING` message.

Definition at line 660 of file diag_table.F90.

◆ parse_file_line()

type(file_description_type) function diag_table_mod::parse_file_line	(	character(len=*), intent(in)	line,
		integer, intent(out), optional, target	istat,
		character(len=*), intent(out), optional	err_msg
	)

private

parse_file_line parses a file description line from the diag_table file, and returns a TYPE(file_description_type). The calling function, would then need to call the init_file to initialize the diagnostic output file.

Returns: file_description_type parse_file_line

Parameters

[in]	line	Line to parse from the `diag_table` file.
[out]	istat	Return state of the function. A value of 0 indicates success. A positive value indicates a `FATAL` error occurred, and a negative value indicates a `WARNING` should be issued.
[out]	err_msg	Error string to include in the `FATAL` or `WARNING` message.

Definition at line 491 of file diag_table.F90.

Data Types

Functions/Subroutines

Variables

Detailed Description

Sample diag_table

Data Type Documentation

◆ diag_table_mod::field_description_type

Private Attributes

◆ diag_table_mod::file_description_type

Private Attributes

Function/Subroutine Documentation

◆ find_unit_ivalue()

◆ fix_file_name()

◆ is_a_file()

◆ parse_diag_table()

◆ parse_field_line()

◆ parse_file_line()

Sample `diag_table`