MODULE obs_kind_mod

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: obs_kind_mod.html 11832 2017-07-18 19:29:35Z nancy@ucar.edu $

NAMELIST / MODULES / INTERFACES / FILES / REFERENCES / ERRORS / PLANS / TERMS OF USE

Overview

Introduction

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 QTY_xxx of an observation must be sufficient to compute the correct forward operator. The quantities also must be able to identify the different variables in the state vector. 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.

Examples and Use

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.

When making code changes remember to edit only the template file (normally DEFAULT_obs_kind_mod.F90) and not the obs_kind_mod.f90 file directly. All of the build scripts in DART remove the existing obs_kind and obs_def modules and regenerate them using the preprocess program and any direct changes will be lost.

Adding Additional Quantities

To add an additional quantity, edit the assimilation_code/modules/observations/DEFAULT_obs_kind_mod.F90 file and add a unique number to the list of generic quantities at the top of the file. Then find the obs_kind_names initializer statements in the initialize_module() subroutine, and add an entry with the same index to define the string associated with the parameter. The names must be identical. If the number is larger than the current maximum, increase the value of max_defined_quantities. Run the preprocess program to generate the assimilation_code/modules/observations/obs_kind_mod.f90 file which will then be used by the rest of the DART system.

Implementation Details

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 obsesrvation 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_kind_type maps generic quantity parameters to the equivalent string names.


[top]

NAMELIST

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'
/
would assimilate temperature and wind observations, but only compute the forward operators for surface pressure obs. Radiance observations have precomputed values for each ensemble member in the input observation sequence file which would be used instead of calling the forward operator code.

[top]

MODULES USED

utilities_mod

[top]

PUBLIC INTERFACES

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
 paramname_length
 GENERIC_QTY_DEFINITIONS
 OBSERVATION_TYPES

A note about documentation style. Optional arguments are enclosed in brackets [like this].


integer, parameter :: max_defined_types_of_obs

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. (Note that in spite of the name, this is the number of specific types, e.g. RADIOSONDE_TEMPERATURE, AIRCRAFT_SPECIFIC_HUMIDITY) and not the number of generic quantities.

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_kind_ind)
character(len=32)              :: get_name_for_type_of_obs
integer, intent(in)            :: obs_kind_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_kind_ind An integer index into the obs_type_type table.


var = get_name_for_quantity(obs_kind_ind)
character(len=32)              :: get_name_for_quantity
integer, intent(in)            :: obs_kind_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_kind_type table.
obs_kind_ind An integer index into the obs_kind_type table.


var = get_index_for_type_of_obs(obs_kind_name)
integer                       :: get_index_for_type_of_obs
character(len=32), intent(in) :: obs_kind_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_kind_name.
obs_kind_name Name of specific observation type found in obs_type_type table.


var = get_index_for_quantity(obs_kind_name)
integer                       :: get_index_for_quantity
character(len=32), intent(in) :: obs_kind_name

Given the name of a generic quantity (e.g. "QTY_TEMPERATURE", "QTY_SPECIFIC_HUMIDITY"), returns the index of the entry in the obs_kind_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_kind_type table entry with name string corresponding to obs_kind_name.
obs_kind_name Name of generic kind found in obs_kind_type table.


var = assimilate_this_type_of_obs(obs_kind_ind)
logical              :: assimilate_this_type_of_obs
integer, intent(in)  :: obs_kind_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_kind_ind An integer index into the obs_type_type table.


var = evaluate_this_type_of_obs(obs_kind_ind)
logical              :: evaluate_this_type_of_obs
integer, intent(in)  :: obs_kind_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_kind_ind An integer index into the obs_type_type table.


var = get_quantity_for_type_of_obs(obs_kind_ind)
integer              :: get_quantity_for_type_of_obs
integer, intent(in)  :: obs_kind_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_kind_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 :: paramname_length

The current Fortran standards define the maximum length of a Fortran parameter to be 32 chars long. This named parameter can be used anyplace the string name length of a parameter is needed. All the specific types and generic quantities in DART are defined both as an integer parameter number for efficiency, and as a string variable when a descriptive or human-readable name is needed. The length of these names cannot exceed this parameter-name limit.



integer, parameter :: QTY_.....

All generic quantities available are public parameters that begin with QTY_.



integer, parameter :: SAMPLE_OBS_TYPE

A list of all observation types that are available is provided as a set of integer parameter statements. The F90 identifiers are the same as the string names that are associated with this identifier in the obs_type_type table.


[top]

FILES


[top]

REFERENCES


[top]

ERROR CODES and CONDITIONS

RoutineMessageComment
initialize_module ______ from obs_kind_nml is not a legal observation kind An observation type name that is not in the obs_type_type table has been specified to be assimilated or evaluted.
initialize_module Illegal to evaluate and assimilate the same kind ______ The same observation type name has been specified in both namelist entries.
map_type_of_obs_table Couldnt find obs_def_index __ in obs_kind map. An attempt to use an observation type that was NOT in the obs_sequence header.
read_type_of_obs_table Didnt find obs_kind_definition string An obs_sequence file that was expected to contain an obs_kind_definition list in its header did not.
read_type_of_obs_table didnt find observation kind _____ in obs_kind_mod list An observation type specified by name in an observation sequence file header was NOT found in the obs_type_type table.

[top]

FUTURE PLANS

The terminology has evolved since the initial version of this code was developed, but since the names are part of the public interfaces they have remained constant and are now confusing. The current system makes a definite distinction between specific observation types versus generic state variable and observation quantities. However, the interfaces to the code in this module are still using 'kind' where they should be using 'type'. As a byproduct of the interface name confusion there is additional confusion inside other parts of the DART code where 'kind' is used for local variable names where it really is a 'type'.

As noted in the Overview, the real distinction is that knowing the QTY_xxx of an observation should be enough to compute the correct forward operator. The kinds also should be sufficient to identify the different variables in the state vector. The types are observation-platform dependent and allow users to select to assimilate and evaluate these as they choose.


[top]

Terms of Use

DART software - Copyright UCAR. This open source software is provided by UCAR, "as is", without charge, subject to all terms of use at http://www.image.ucar.edu/DAReS/DART/DART_download

Contact: DART core group
Revision: $Revision: 11832 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/Manhattan/assimilation_code/modules/observations/obs_kind_mod.html $
Change Date: $Date: 2017-07-18 13:29:35 -0600 (Tue, 18 Jul 2017) $
Change history:  try "svn log" or "svn diff"