MODULE obs_kind_mod

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: obs_kind_mod.html 8306 2015-07-31 22:24:33Z nancy $

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

Overview

Introduction

This module provides definitions of specific observation types and generic variable kinds, 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 kinds and types is this: Kinds apply both to observations and to state vector variables. Knowing the KIND_xxx of an observation must be sufficient to compute the correct forward operator. The kinds 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 kinds are associated with an observation type or with a model state variable. An example kind is KIND_U_WIND_COMPONENT. Multiple different specific observation types can be associated with this generic kind, for instance RADIOSONDE_U_WIND_COMPONENT, ACARS_U_WIND_COMPONENT, and SAT_U_WIND_COMPONENT. Generic kinds are defined via an integer parameter statement at the start of this module. As new generic kinds are needed they are added to this list. Generic kind integer parameters are required to start with KIND_ and observation types are NOT allowed to start with KIND_.

Typically kinds are used by model-interface files models/xx/model_mod.f90, observation forward operator files obs_def/obs_def_xx_mod.f90, and observation converter programs observations/xx/xx.f90.

The obs_kind module being described here is created by the program preprocess from two kinds 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 Kinds

To add an additional kind, edit the obs_kind/DEFAULT_obs_kind_mod.F90 file and add a unique number to the list of generic kinds 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_obs_generic. Run the preprocess program to generate the obs_kind/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_obs_kinds, 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 kind, and two logicals indicating whether this observation type is to be assimilated, evaluated only (forward operator is computed but not assimilated), 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 kind 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'  
 /


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=129), dimension(:) Names of observation types to be assimilated.
evaluate_these_obs_types character(len=129), dimension(:) Names of observation types to be evaluated only.

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'  
/
would assimilate temperature and wind observations, but only compute the forward operators for surface pressure obs.

[top]

MODULES USED

utilities_mod

[top]

PUBLIC INTERFACES

use obs_kind_mod, only : max_obs_kinds
 get_num_obs_kinds
 get_num_raw_obs_kinds
 get_obs_kind_name
 get_raw_obs_kind_name
 get_obs_kind_index
 get_raw_obs_kind_index
 assimilate_this_obs_kind
 evaluate_this_obs_kind
 get_obs_kind_var_type
 write_obs_kind
 read_obs_kind
 get_kind_from_menu
 map_def_index
 paramname_length
 GENERIC_KIND_DEFINITIONS
 OBSERVATION_TYPES

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


integer, parameter :: max_obs_kinds

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

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_obs_kinds()
integer :: get_num_obs_kinds

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_obs_kinds' above.

var Integer count of the total number of specific types defined in the obs_kind_mod.f90 file.


var = get_num_raw_obs_kinds()
integer :: get_num_raw_obs_kinds

Returns the number of different generic kinds (e.g. KIND_TEMPERATURE, KIND_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 kinds defined in the obs_kind_mod.f90 file.


var = get_obs_kind_name(obs_kind_ind)
character(len=32)              :: get_obs_kind_name
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_raw_obs_kind_name(obs_kind_ind)
character(len=32)              :: get_raw_obs_kind_name
integer, intent(in)            :: obs_kind_ind

Given an integer index return the string name of the corresponding generic kind (e.g. "KIND_TEMPERATURE", "KIND_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_obs_kind_index(obs_kind_name)
integer                       :: get_obs_kind_index
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_obs_kind_index 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_raw_obs_kind_index(obs_kind_name)
integer                       :: get_raw_obs_kind_index
character(len=32), intent(in) :: obs_kind_name

Given the name of a generic kind (e.g. "KIND_TEMPERATURE", "KIND_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_raw_obs_kind_index 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_obs_kind(obs_kind_ind)
logical              :: assimilate_this_obs_kind
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_obs_kind(obs_kind_ind)
logical              :: evaluate_this_obs_kind
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_obs_kind_var_type(obs_kind_ind)
integer              :: get_obs_kind_var_type
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 kind associated with this type (e.g. KIND_TEMPERATURE, KIND_SPECIFIC_HUMIDITY). The parameter defined by this name is used as an integer index into the obs_type_type table to return the generic kind associated with this type.

var Returns the integer GENERIC kind index associated with this obs type.
obs_kind_ind An integer index into the obs_type_type table.


call write_obs_kind(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_obs_kinds() or the public max_obs_kinds). 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_obs_kind(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_kind_from_menu()
integer              :: get_kind_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_def_index(obs_def_index)
integer              :: map_def_index
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 kinds 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 :: KIND_.....

All generic kinds available are public parameters that begin with KIND_.



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_def_index 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_obs_kind 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_obs_kind 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 kinds. However, the interfaces to the code in this module are still using 'kind' where they should be using 'type'. Either some new distinct terminology for both concepts needs to be invented, or the string 'kind' in all these routines need to be replaced with 'type', and 'raw_kind' with 'kind'. In any case the names of all these routines need to change. 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 KIND_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 2004 - 2013 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: 8306 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/Lanai/obs_kind/obs_kind_mod.html $
Change Date: $Date: 2015-07-31 16:24:33 -0600 (Fri, 31 Jul 2015) $
Change history:  try "svn log" or "svn diff"