diag_manager_mod provides a convenient set of interfaces for
writing data to disk. It is built upon the parallel I/O interface
mpp_io.
A single group of calls to the
diag_manager_mod interfaces provides data to disk
at any number of sampling and/or averaging intervals specified at run-time.
Run-time specification of diagnostics are input through the diagnostics table.
Usage of
diag_manager includes the following steps:
1. Create diag_table as described in
diag_table_tk documentation.
2. Call
diag_manager_init to initialize diag_manager_mod
3. Call
register_diag_field to register the field to be outputted.
NOTE ALL fields in diag_table should be registered BEFORE the first send_data call
4. Call
send_data to send data to output fields
5. Call
diag_manager_end to exit diag_manager
New Features of
diag_manager_mod :
1. Ability to output scalars (see
send_data and
register_diag_field)
2. Ability to output time average of fields that have time dependent mask.
3. Give optional warning if
register_diag_field fails due to misspelled module name
or field name.
4. Check if a field is registered twice.
5. Check for duplicate lines in
diag_table.
6.
diag_table can contain fields that are NOT written to any files.
The file name in diag_table of these fields is
null
7. By default, a field is output in its global grid, it is now possible to output a field in
a region specified by user, see
send_data for more details
8. To check if the diag table is set up correctly, user should set
init_verbose=.true. in
diag namelist, then the the content of diag_table is printed in stdout.
9. New optional format of file information in
diag_table
It is possible to have just one file name and reuse it many times. A time string will be suffixed
to the base file name each time a new file is opened. The time string can be any combination from
year to second of current model time. Here is an example of file information:
"file2_yr_dy%1yr%3dy", 5, "days",1,"hours","Time", 10, "days", "1 1 7 0 0 0"
From left to right we have: file name, output frequency, output frequency unit, Format (should always
be 1), time axis unit, time axis name, frequency for creating new file, unit for creating new file,
start time of the new file.
In this example the string
10, "days", "1 1 7 0 0 0" is optional.
Keyword for the time string suffix is
%xyr,%xmo,%xdy,%xhr,%xmi,%xsc where
x is mandatory 1 digit number specifying the width of field used in writing the string
10. New time axis for time averaged fields
users can use a namelist option to handle the time value written to time axis for time averaged fields.
If
mix_snapshot_average_fields=.true. then a time averaged file will have time values
corresponding to ending time_bound e.g. January monthly average is labeled Feb01. Users can have both
snapshot and averaged fields in one file.
If
mix_snapshot_average_fields=.false. The time value written to time axis for time averaged fields is the middle on the averaging time.
For example, January monthly mean will be written at Jan.16 not Feb.01 as before. However, to use this
new feature users should
separate snapshot fields and time averaged fields in
different files
or a fatal error will occur.
The namelist
default value is
mix_snapshot_average_fields=.false.
11 Time average, Max and Min
In addition to time average users can also get Max or Min value during the same interval of time as time
average. For this purpose, in the diag table users must replace
.true. or
.false. by
"max" or
"min".
Currently, Max and Min are not available for regional output.
Features of diag_manager_mod include:
Integrated netCDF capability:
netCDF is a
data format widely used in the climate/weather modeling
community. netCDF is considered the principal medium of data storage
for
diag_manager_mod.
None.
-
send_data
send_data (diag_field_id, field, time, is_in, js_in, ks_in, mask, rmask, ie_in, je_in, ke_in, weight)
-
DESCRIPTION
- send_data is overloaded for fields having zero dimension (scalars) to 3 dimension.
diag_field_id corresponds to the id returned from a previous call to
register_diag_field. The field array is restricted to the computational
range of the array. Optional argument is_in can be used to update
sub-arrays of the entire field. Additionally, an optional logical or real
mask can be used to apply missing values to the array.
If a field is declared to be mask_variant in register_diag_field logical mask
should be mandatory.
For the real mask, the mask is applied if the mask value is less than 0.5.
By default, a field will be written out entirely in its global grid. Users can also specify
region in which the field will be output. The region is specified in diag-table just before
the end of output_field replacing "none". For example:
by default:
"ocean_mod","Vorticity","vorticity","file1","all",.false.,"none",2
for regional output:
"ocean_mod","Vorticity","vorticity_local","file2","all",.false.,"0.5 53.5 -89.5 -28.5 -1 -1",2
the format of region is "xbegin xend ybegin yend zbegin zend". If it is a 2D field use (-1 -1)
for (zbegin zend) as in the example above. For a 3D field use (-1 -1) for (zbegin zend) when you want to
write the whole vertical extent, otherwise specify real coordinates. The units used for region are the
actual units used in grid_spec.nc (for example degrees for lat, lon). Fatal error will occur if region's
boundaries are not found in grid_spec.nc
Special note when using regional output: result files containing regional outputs should be
different from files containing global (default) output. It is FATAL error to have one file
containing both regional and global results. For maximum flexibility and independence from
PE counts one file should contain just one region.
Time averaging is supported in regional output.
Physical fields (written in "physics windows" of atmospheric code) are
currently fully supported for regional outputs.
Note of dimension of field in send_data
Most fields are defined in data_domain but used in compute domain. In send_data users can pass EITHER
field in data domain OR field in compute domain. If data domain is used, users should also pass the
starting and ending indices of compute domain (isc, iec ...). If compute domain is used no indices
are needed. These indices are for determining halo exclusively. If users want to ouput the field
partially they should use regional output as mentioned above.
Weight in Time averaging is now supported, each time level may have a different weight. The default
of weight is 1.
-
INPUT
-
diag_field_id |
[integer]
[integer]
[integer]
[integer] |
field |
[real]
[real, dimension(:)]
[real, dimension(:,:)]
[real, dimension(:,:,:)] |
time |
[time_type]
[time_type]
[time_type]
[time_type] |
-
send_tile_averaged_data
-
DESCRIPTION
- send_tile_averaged_data is overloaded for 3-d and 4-d arrays.
diag_field_id corresponds to the id returned by previous call to
register_diag_field. Logical mask can be used to mask out undefined
and/or unused values. Note that the dimension of output field is
smaller by one than the dimension of the data, since averaging over
tiles (3d dimension) is performed.
-
INPUT
-
diag_field_id |
[integer]
[integer] |
field |
[real, dimension(:,:,:)]
[real, dimension(:,:,:,:)] |
area |
[real, dimension(:,:,:)]
[real, dimension(:,:,:)] |
time |
[time_type, dimension(:,:,:)]
[time_type, dimension(:,:,:)] |
mask |
[logical, dimension(:,:,:)]
[logical, dimension(:,:,:)] |
-
register_diag_field
register_diag_field (module_name,field_name,axes,init_time, & long_name,units,missing_value,range,mask_variant,verbose)
-
DESCRIPTION
- Return field index for subsequent calls to send_data
axes are axis ID returned from diag_axis_init, axes are required
for fields of 1-3 dimension and NOT required for scalars.
for a static scalar (constant) init_time is not needed.
optional mask_variant is for fields that have a time-dependent mask. If mask_variant is
true then mask must be present in argument list of send_data
When optional verbose is true a warning will be given if register_diag_field fails due to misspelled field name or module name. The default verbose is false.
The pair (module_name, fieldname) should be registered only once or a FATAL error will occur
-
INPUT
-
module_name |
[character(len=*)] |
field_name |
[character(len=*)] |
axes |
[integer, dimension(:)] |
init_time |
[time_type] |
long_name |
[character(len=*)] |
units |
[character(len=*)] |
missing_value |
[real] |
range |
[real, dimension(2)] |
mask_variant |
[logical] |
verbose |
[logical] |
-
register_static_field
register_static_field (module_name, field_name, axes, & long_name, units, missing_value, range, require)
-
DESCRIPTION
- Return field index for subsequent call to send_data.
-
INPUT
-
module_name |
[character(len=*)] |
field_name |
[character(len=*)] |
axes |
[integer, dimension(:)] |
long_name |
[character(len=*)] |
units |
[character(len=*)] |
missing_value |
[real] |
range |
[real, dimension(2)] |
-
log_diag_field_info
call log_diag_field_info ( module_name, field_name, axes, long_name, units, missing_value, range, mask_variant, require, dynamic )
-
DESCRIPTION
- If init_verbose namelist parameter is true, adds a line briefly
describing diagnostic field to the log file. Normally users should not call
this subroutine directly, since it is called by register_static_field and register_diag_field
if do_not_log is not set to true. It is used, however, in LM3 to avoid excessive
log due to a number of fields registered for each of the tile types. LM3 code uses
do_not_log parameter in the registration calls, and calls this subroutine to
log field information under generic name.
-
diag_manager_end
call diag_manager_end (time)
-
DESCRIPTION
- Flushes diagnostic buffers where necessary. Close diagnostics files.
A warning will be issued here if a field in diag_table is not registered
-
INPUT
-
-
diag_manager_init
call diag_manager_init ()
-
DESCRIPTION
- Open and read diag_table. Select fields and files for diagnostic output.
-
get_base_time
call get_base_time ()
-
DESCRIPTION
- Return base time for diagnostics (note: base time must be >= model time).
-
get_base_date
call get_base_date (year, month, day, hour, minute, second)
-
DESCRIPTION
- Return date information for diagnostic reference time.
-
need_data
need_data (diag_field_id,next_model_time)
-
DESCRIPTION
- Determine whether data is needed for the current model time step.
Since diagnostic data are buffered, the "next" model time is passed
instead of the current model time. This call can be used to minimize
overhead for complicated diagnostics.
-
INPUT
-
inext_model_time | next_model_time = current model time + model time_step [time_type] |
diag_field_id |
[integer] |
None.
None.
None.
None.