| Index | Rundeck: E6TomaF40 | Created: Fri May 17 03:30:39 EDT 2024 |
SUBDD.f
Summary: subdd_mod and subroutines in this file provide functionality
facilitating the output of model diagnostics at sub-daily
frequencies. The model currently writes the diagnostics
to disk in "raw" form; the scaleacc utility must be used
to extract groups of outputs (see "Terminology" below for the
definition of "group"). Model diagnostics not defined on the
model's horizontal grid are not supported. Currently, only the
atmospheric model can use this package.
Author : M. Kelley
Version: 1.0
Usage:
Two interfaces are available, for
I. outputs whose groupings and other metadata are defined
during model initialization
II. outputs whose registration is deferred until the stage
of model execution at which the first time-slice of the
output data is saved/accumulated.
The type II interface is intended for outputs that do not
naturally fall into one of the pre-existing categories of
type I, and for which the creation of a new category
would yield little or no long-term benefit. For example,
special (temporary) diagnostics to investigate parameterization-
specific factors determining the behavior of a particular model
component are easily introduced as type II, as the deferred
registration permits a more compact coding footprint than I.
For standard fields (e.g. SLP, SAT, precipitation), type I
is easier to use over time, via its single set of rundeck
parameters. Automatic vertical regridding of outputs to
constant-pressure levels is currently only possible via I
(will be added to II soon).
Requests for type I outputs are made through rundeck
strings SUBDD, SUBDD1, ..., following the traditional
subdaily diagnostics framework. However, the parsing
of the requests has been extended to allow optional
specification of the output frequency Nsubdd for individual
fields using the syntax varname:NN where integer NN is the
value of Nsubdd to be in effect for varname. Requests for
which NN is not specified will default to the global Nsubdd.
By default, outputs are time-averaged over each time interval;
instantaneous output can be requested by appending a trailing
"i" (e.g. varname:i or varname:NNi). For a time-averaged
quantity, the number of timesteps per output file (Nday*days_per_file)
must be divisible by its Nsubdd.
To predefine a new output field, two steps are sufficient when
it is appropriate to place that field in a pre-existing output
category (see Terminology for the definition of "category"):
(1) Specify metadata for that field in the declaration
procedure for the pre-existing category. This is
done by setting the elements of the info_type structure.
(2) In the model component in which the output field is
available, add a section to a "select case"
block corresponding to the pre-existing category.
These blocks pass gridded arrays to the inc_subdd
procedure, which copies the contents of the arrays
into a master database of all outputs (incrementing
accumulated quantities when appropriate). See the
next paragraph for an example of such a block.
To define a new category, it is necessary to
(1) Create a new procedure to define the metadata
for its output fields, and invoke the procedure
in the appropriate section of parse_subdd (where
the calls to ijh_defs et al. are made).
(2) In the part(s) of the model in which outputs in this
category are to be collected, add a do-loop and
select-case block like the following for category
'xyz' (there are many examples to clone):
integer ngroups, grpids(subdd_ngroups)
type(subdd_type), pointer :: subdd
! find groups belonging to category 'xyz'
call find_groups('xyz',grpids,ngroups)
do igrp=1,ngroups ! loop over groups in this category
subdd => subdd_groups(grpids(igrp)) ! for brevity
do k=1,subdd%ndiags ! loop over diags in this group
select case (subdd%name(k))
case ('some_var') ! array already available
call inc_subdd(subdd,k,some_array)
case ('complicated_var') ! need to compute output
temp_array = (....)
call inc_subdd(subdd,k,temp_array)
end select
end do
end do
Type II outputs are declared/saved/accumulated as follows:
call inc_subdd(
'some_var', ! name of this field
real*8 some_array, ! data to be saved/accumulated
integer Nsubdd, ! output frequency for this field
logical instant, ! T for snapshots, F for averages
optional units='xxxx', ! units specification
optional long_name='xxxx' ! description
)
The metadata and control parameters are only examined during
the FIRST call to inc_subdd for a given output field. No coding
is in place yet to check whether they were changed afterward.
Arrays or rank 2 and 3 are accepted. In the latter case, the
size of this extra dimension can be automatically determined,
but if it does not correspond to the 3rd index of the array it is
necessary to specify (via optional argument jdim) which of the
dimensions is the 2nd horizontal dimension. Optional arguments
dim3name and coordvalues can be used to name this extra dimension
in output files and provide a coordinate axis if appropriate.
call inc_subdd(
'some_var',
......
jdim=3, ! only needed if extra dim is the first
dim3name='zzz', ! name instead of size_some_var
coordvalues=zzz ! 1D array of length size(dim3)
)
The extra dimension need not be "vertical"; in some circumstances
it may be useful to bundle collections of 2D fields into 3D output
arrays.
Currently, each type II output variable constitues a separate
group (of size 1) and hence will be placed in its own output
file by scaleacc. Another consequence of this arrangement
is that the checkpointing of model state will write a
array having the name 'some_var' if the above example were present
in the code, so a name collision will occur if 'some_var' is already
the checkpoint-file name of a model array. Please choose your output
names keeping this in mind (i.e. 't', 'q', 'p', 'u', 'v' will not
work, sorry) until I resolve the issue. This is not an issue for
type I outputs.
If snapshots are to be written, inc_subdd can still be called
every timestep; it will simply return immediately during the
intervening timesteps. In case you wish to avoid calculating
some expensive diagnostic every timestep, keep in mind that
snapshots are taken when mod(itime+1,Nsubdd)==0.
Terminology:
Categories occupy the middle position of a 3-level taxonomy
based on string identifiers (names).
(a) shape: a name for the grid on which a field is
defined. Currently recognized names:
i. aijh horizontal grid only
ii. aijph horizontal grid + constant-pressure levels
iii. aijlh horizontal grid + model levels
iv. gijlh horizontal grid + soil levels
(b) category: the name given to a collection of outputs
of a particular shape, e.g. those from a single model
component. The identifier must be unique globally, i.e.
two categories having different shapes must have different
category names.
(c) group: an instance of a given category for
a particular output frequency and sampling type
(e.g. instantaneous versus time-averaged). A group
may contain multiple output fields. The names of
groups are generated by combining the names of
their parent categories with their sampling information.
The hierarchy is stored in flattened form, i.e. as a list of groups
having shape and category attributes. Each group is placed into
a separate output file by the scaleacc procedure.
Other notes:
- Arrays passed to inc_subdd must be horizontally dimensioned to
include the 1-row "halo".
- To define a time-averaged type-I field as a ratio of sums,
set the dname element of the info_type structure to the
sname of the field serving as the denominator. For
example: if there is a cloud fraction output named 'cldf',
and one wishes to weight a water content diagnostic by
cloud fraction, one can set dname='cldf' along with the
other metadata for water content. The call to inc_subdd()
for water content would then pass an array equal to in-cloud
water content multiplied by cloud fraction. It is the
responsibility of the user to request that 'cldf' be
output, and at the same time frequency as water content;
execution will stop if dname is set but the corresponding
field does not exist in the numerator''s group.
Modules:
Global Subroutines:
- def_rsf_subdd_acc
- defmeta_subdd
- get_subdd_strings
- get_subdd_timeunitstr
- get_subdd_vinterp_coeffs
- get_subdd_vinterp_coeffs1
- ijh_defs
- ijlh_defs
- ijph_defs
- next
- next
- next
- parse_subdd
- parse_subdd parse sub daily diag requests
and declare subdaily diag metadata and allocate space
for requested outputs
- prep_subdd_acc
- read_subdd_rsf
- read_subdd_rsf1
- reset_cached_subdd
- reset_cached_subdd resets cached_subdd accumulations
- rsf_equals_db_int
- set_subdd_period
- set_subdd_period get index of the current subdd accumulation period
- set_subdd_period1
- set_subdd_period get index of the current subdd accumulation period
- write_subdd_accdata
- write_subdd_accfile
- writemeta_subdd
- xintrp
Depends on the following files:
Used by the following files: