This module provides definitions of specific observation types and generic variable quantities, routines for mapping between integer identifiers and string names, routines for reading and writing this information, and routines for determining whether and how to process observations from an observation sequence file.
The distinction between quantities and types is this: Quantities apply both to observations and to state vector
variables. Knowing the type of an observation must be sufficient to compute the correct forward operator. The quantity
associated with an observation must be sufficient to identify which variable in the state vector should be used to
compute the expected value. Types only apply to observations, and are usually observation-platform dependent. Making
distinctions between different observation sources by using different types allows users to selectively assimilate,
evaluate, or ignore them.
Generic quantities are associated with an observation type or with a model state variable. An example quantity is
QTY_U_WIND_COMPONENT. Multiple different specific observation types can be associated with this generic quantity,
for instance RADIOSONDE_U_WIND_COMPONENT, ACARS_U_WIND_COMPONENT, and SAT_U_WIND_COMPONENT. Generic
quantities are defined via an integer parameter statement at the start of this module. As new generic quantities are
needed they are added to this list. Generic quantity integer parameters are required to start with QTY_ and
observation types are NOT allowed to start with QTY_.
Typically quantities are used by model-interface files models/xx/model_mod.f90, observation forward operator files
observations/forward_operators/obs_def_xx_mod.f90, and observation converter programs
observations/obs_converters/xx/xx.f90.
The obs_kind module being described here is created by the program preprocess from two categories of input files.
First, a DEFAULT obs_kind module (normally called DEFAULT_obs_kind_mod.F90 and documented in this directory) is used
as a template into which the preprocessor incorporates information from zero or more special obs_def modules (such as
obs_def_1d_state_mod.f90 or obs_def_reanalysis_bufr_mod.f90) which are documented in the obs_def directory. If
no special obs_def files are included in the preprocessor namelist, a minimal obs_kind_mod.f90 is created which can
only support identity forward observation operators.
All of the build scripts in DART remove the existing obs_kind_mod.f90 file and regenerate it using the
preprocess program. Do not add new quantities to obs_kind_mod.f90, because these changes will not be kept when
you run quickbuild.sh.
New quantities should be added to a quantity file, for example a new ocean quantity should be added to
ocean_quantities_mod.f90. The quantity files are in assimilation_code/modules/observations/.
Every line in a quantity file between the start and end markers must be a comment or a quantity definition (QTY_string).
Multiple name-value pairs can be specified for a quantity but are not required. For example, temperature may be defined:
! QTY_TEMPERATURE units="K" minval=0.0. Comments are allowed between quantity definitions or on the same line as the
definition. The code snippet below shows acceptable formats for quantity definitions
! BEGIN DART PREPROCESS QUANTITY DEFINITIONS ! ! Formats accepted: ! ! QTY_string ! QTY_string name=value ! QTY_string name=value name2=value2 ! ! QTY_string ! comments ! ! ! comment ! ! END DART PREPROCESS QUANTITY DEFINITIONS
The obs_kind module contains an automatically-generated list of integer parameters, derived from the obs_def files, an
integer parameter max_defined_types_of_obs, and an automatically-generated list of initializers for the
obs_type_type derived type that defines the details of each observation type that has been created by the preprocess
program. Each entry contains the integer index of the observation type, the string name of the observation type (which
is identical to the F90 identifier), the integer index of the associated generic quantities, and three logicals
indicating whether this observation type is to be assimilated, evaluated only (forward operator is computed but not
assimilated), assimilated but has externally computed forward operator values in the input observation sequence file, or
ignored entirely. The logicals initially default to .false. and are set to .true. via the &obs_kind_nml namelist. A
second derived type obs_qty_type maps the integer parameter for a quantity to the quantity name (a string), and
stores any additional pair-value metadata for that quantity.
This namelist is read from the file input.nml. Namelists start with an ampersand '&' and terminate with a slash '/'.
Character strings that contain a '/' must be enclosed in quotes to prevent them from prematurely terminating the
namelist.
&obs_kind_nml assimilate_these_obs_types = 'null', evaluate_these_obs_types = 'null' use_precomputed_FOs_these_obs_types = 'null' /
Controls what observation types are to be assimilated, evaluated, or ignored. For each entry, a list of observation type names can be specified. Any name in the obs_type_type table is eligible. Specifying a name that is not in the table results in an error. Specifying the same name for both namelist entries also results in an error. Observation types specified in the list for assimilate_these_obs_types are assimilated. Those in the evaluate_these_obs_types list have their forward operators computed and included in diagnostic files but are not assimilated. An observation type that is specified in neither list is ignored. Identity observations, however, are always assimilated if present in the obs_seq.out file.
| Item | Type | Description |
|---|---|---|
| assimilate_these_obs_types | character(len=31), dimension(:) | Names of observation types to be assimilated. |
| evaluate_these_obs_types | character(len=31), dimension(:) | Names of observation types to be evaluated only. |
| use_precomputed_FOs_these_obs_types | character(len=31), dimension(:) | If the forward operator values have been precomputed outside of filter, for example for radiances or other compute intensive computations, the ensemble of forward operator values can be stored in the observation sequence file. For any type listed here, the forward operator interpolation code will not be called and the values in the file will be used instead. |
For example:
&obs_kind_nml
assimilate_these_obs_types = 'RADIOSONDE_TEMPERATURE',
'RADIOSONDE_U_WIND_COMPONENT',
'RADIOSONDE_V_WIND_COMPONENT',
evaluate_these_obs_types = 'RADIOSONDE_SURFACE_PRESSURE',
use_precomputed_FOs_these_obs_types = 'RADIANCE'
/
utilities_mod
| use obs_def_mod, only : | max_defined_types_of_obs |
| get_num_types_of_obs | |
| get_num_quantities | |
| get_name_for_type_of_obs | |
| get_name_for_quantity | |
| get_index_for_type_of_obs | |
| get_index_for_quantity | |
| assimilate_this_type_of_obs | |
| evaluate_this_type_of_obs | |
| get_quantity_for_type_of_obs | |
| write_type_of_obs_table | |
| read_type_of_obs_table | |
| get_type_of_obs_from_menu | |
| map_type_of_obs_table | |
| GENERIC_QTY_DEFINITIONS | |
| OBSERVATION_TYPES |
A note about documentation style. Optional arguments are enclosed in brackets [like this].
The total number of available observation types in the obs_type_type table. This value is added by the preprocess
program and depends on which obs_def_xxx_mod.f90 files are listed in the
&preprocess_nml namelist.
There is also a function interface which is an alternate method to get this value. In some cases the code requires a parameter value known at compile time (for declaring a fixed length array, for example). For an array allocated at run time the size can be returned by the function interface.
var = get_num_types_of_obs()
integer :: get_num_types_of_obs
Returns the number of different specific observation types (e.g. RADIOSONDE_TEMPERATURE, AIRCRAFT_SPECIFIC_HUMIDITY) defined in the obs_kind_mod.f90 file. This file is generated by the preprocess program. This is the same value as the public 'max_defined_types_of_obs' above.
var |
Integer count of the total number of specific types defined in the obs_kind_mod.f90 file. |
var = get_num_quantities()
integer :: get_num_quantities
Returns the number of different generic quantities (e.g. QTY_TEMPERATURE, QTY_SPECIFIC_HUMIDITY) defined in the obs_kind_mod.f90 file. This file is generated by the preprocess program.
var |
Integer count of the total number of generic quantities defined in the obs_kind_mod.f90 file. |
var = get_name_for_type_of_obs(obs_type_ind)
character(len=32) :: get_name_for_type_of_obs integer, intent(in) :: obs_type_ind
Given an integer index return the string name of the corresponding specific observation type (e.g. "RADIOSONDE_TEMPERATURE", "AIRCRAFT_SPECIFIC_HUMIDITY"). This string is the same as the F90 identifier associated with the integer index.
var |
Name string associated with this entry in the obs_type_type table. |
obs_type_ind |
An integer index into the obs_type_type table. |
var = get_name_for_quantity(obs_qty_ind)
character(len=32) :: get_name_for_quantity integer, intent(in) :: obs_qty_ind
Given an integer index return the string name of the corresponding generic quantity (e.g. "QTY_TEMPERATURE", "QTY_SPECIFIC_HUMIDITY"). This string is the same as the F90 identifier associated with the integer index.
var |
Name string associated with this entry in the obs_qty_type table. |
obs_qty_ind |
An integer index into the obs_qty_type table. |
var = get_index_for_type_of_obs(obs_type_name)
integer :: get_index_for_type_of_obs character(len=*), intent(in) :: obs_type_name
Given the name of a specific observation type (e.g. "RADIOSONDE_TEMPERATURE", "AIRCRAFT_SPECIFIC_HUMIDITY"), returns the index of the entry in the obs_type_type table with this name. If the name is not found in the table, a -1 is returned. The integer returned for a successful search is the value of the integer parameter with the same identifier as the name string.
get_index_for_type_of_obs |
Integer index into the obs_type_type table entry with name string corresponding to obs_type_name. |
obs_type_name |
Name of specific observation type found in obs_type_type table. |
var = get_index_for_quantity(obs_qty_name)
integer :: get_index_for_quantity character(len=32), intent(in) :: obs_qty_name
Given the name of a generic quantity (e.g. "QTY_TEMPERATURE", "QTY_SPECIFIC_HUMIDITY"), returns the index of the entry in the obs_qty_type table with this name. If the name is not found in the table, a -1 is returned. The integer returned for a successful search is the value of the integer parameter with the same identifier as the name string.
get_index_for_quantity |
Integer index into the obs_qty_type table entry with name string corresponding to obs_qty_name. |
obs_qty_name |
Name of generic kind found in obs_qty_type table. |
var = assimilate_this_type_of_obs(obs_type_ind)
logical :: assimilate_this_type_of_obs integer, intent(in) :: obs_type_ind
Given the integer index associated with a specific observation type (e.g. RADIOSONDE_TEMPERATURE, AIRCRAFT_SPECIFIC_HUMIDITY), return true if this observation type is to be assimilated, otherwise false. The parameter defined by this name is used as an integer index into the obs_type_type table to return the status of this type.
var |
Returns true if this entry in the obs_type_type table is to be assimilated. |
obs_type_ind |
An integer index into the obs_type_type table. |
var = evaluate_this_type_of_obs(obs_type_ind)
logical :: evaluate_this_type_of_obs integer, intent(in) :: obs_type_ind
Given the integer index associated with a specific observation type (e.g. RADIOSONDE_TEMPERATURE, AIRCRAFT_SPECIFIC_HUMIDITY), return true if this observation type is to be evaluated only, otherwise false. The parameter defined by this name is used as an integer index into the obs_type_type table to return the status of this type.
var |
Returns true if this entry in the obs_type_type table is to be evaluated. |
obs_type_ind |
An integer index into the obs_type_type table. |
var = get_quantity_for_type_of_obs(obs_type_ind)
integer :: get_quantity_for_type_of_obs integer, intent(in) :: obs_type_ind
Given the integer index associated with a specific observation type (e.g. RADIOSONDE_TEMPERATURE, AIRCRAFT_SPECIFIC_HUMIDITY), return the generic quantity associated with this type (e.g. QTY_TEMPERATURE, QTY_SPECIFIC_HUMIDITY). The parameter defined by this name is used as an integer index into the obs_type_type table to return the generic quantity associated with this type.
var |
Returns the integer GENERIC quantity index associated with this obs type. |
obs_type_ind |
An integer index into the obs_type_type table. |
call write_type_of_obs_table(ifile [, fform, use_list])
integer, intent(in) :: ifile character(len=*), optional, intent(in) :: fform integer, optional, intent(in) :: use_list(:)
Writes out information about all defined observation types from the obs_type_type table. For each entry in the table, the integer index of the observation type and the associated string are written. These appear in the header of an obs_sequence file. If given, the use_list(:) must be the same length as the max_obs_specific count. If greater than 0, the corresponding index will be written out; if 0 this entry is skipped. This allows a table of contents to be written which only includes those types actually being used.
ifile |
Unit number of output observation sequence file being written. |
| fform | Optional format for file. Default is FORMATTED. |
| use_list(:) | Optional integer array the same length as the number of specific types (from get_num_types_of_obs() or the public max_defined_types_of_obs). If value is larger than 0, the corresponding type information will be written out. If 0, it will be skipped. If this argument is not specified, all values will be written. |
call read_type_of_obs_table(ifile, pre_I_format [, fform])
integer, intent(in) :: ifile logical, intent(in) :: pre_I_format !(deprecated) character(len=*), optional, intent(in) :: fform
Reads the mapping between integer indices and observation type names from the header of an observation sequence file and prepares mapping to convert these to values defined in the obs_type_type table. If pre_I_format is true, there is no header in the observation sequence file and it is assumed that the integer indices for observation types in the file correspond to the storage order of the obs_type_type table (integer index 1 in the file corresponds to the first table entry, etc.) Support for pre_I_format is deprecated and may be dropped in future releases of DART.
ifile |
Unit number of output observation sequence file being written. |
pre_I_format |
True if the file being read has no obs type definition header (deprecated). |
| fform | Optional format for file. Default is FORMATTED. |
var = get_type_of_obs_from_menu()
integer :: get_type_of_obs_from_menu
Interactive input of observation type. Prompts user with list of available types and validates entry before returning.
var |
Integer index of observation type. |
var = map_type_of_obs_table(obs_def_index)
integer :: map_type_of_obs_table integer, intent(in) :: obs_def_index
Maps from the integer observation type index in the header block of an input observation sequence file into the corresponding entry in the obs_type_type table. This allows observation sequences that were created with different obs_kind_mod.f90 versions to be used with the current obs_kind_mod.
var |
Index of this observation type in obs_type_type table. |
obs_def_index |
Index of observation type from input observation sequence file. |
integer, parameter :: QTY_.....QTY_.- &obs_kind_nml in input.nml
- Files containing input or output observation sequences.
- none