INTERFACE / PUBLIC COMPONENTS / NAMELIST / FILES / REFERENCES / ERRORS / BUGS / PLANS /

MODULE obs_kind_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.1 $
Release Name: $Name: iceland $
Change Date: $Date: 2005/10/28 17:12:41 $
Change history: see CVS log

OVERVIEW

Provides definitions of observation types and generic variable kinds and tools for determining how to use observations available in an observation sequence file. Generic kinds can be associated with an observation type or with a model state variable. An example is U_WIND_COMPONENT. State variables in a model can be associated with this generic kind. Similarly, many different observation types can be associated with this generic kind, for instance RADIOSONDE_U_WIND_COMPONENT and ACARS_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 can be added to this list. Generic kind integer parameters are required to start with KIND_ and observation types are NOT allowed to start with KIND_.

Beginning with the I-release of DART, a more flexible. powerful (and complicated) mechanism for incorporating new types of observations is part of DART. The obs_kind module being described here is created by the program preprocess.f90 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_reanalyis_bufr_mod.f90) which are also 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.

The obs_kind module contains a table, the obs_kind_info table, that defines the details of each observation type that has been created by the preprocess program. Each table entry contains the integer index of the observation type which is associated with an integer parameter declaration. Also associated with each table entry are the name of the observation type ( this string is identical to the F90 identifier associated with the integer index via the parameter statement), the integer index of the associated 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. These logicals can be set via the namelist and have defaults values that cause an observation type to be ignored.





OTHER MODULES USED

utilities_mod



PUBLIC INTERFACE

use obs_def_mod, only : max_obs_kinds
 get_obs_kind_name
 assimilate_this_obs_kind
 evaluate_this_obs_kind
 get_obs_kind_var_type
 get_obs_kind_index
 write_obs_kind
 read_obs_kind
 get_kind_from_menu
 map_def_index
 GENERIC_KIND_DEFINITIONS
 OBSERVATION_TYPES




PUBLIC COMPONENTS



var = get_obs_kind_name(obs_kind_ind)
 character(len=32), intent(out) :: get_obs_kind_name
 integer, intent(in)            :: obs_kind_ind
 

Description

Given an integer index into the obs_kind_info table (the index is defined in the integer, parameter statement for the observation types that is created by the preprocess program (see DEFAULT_obs_kind_mod.html), returns the associated string name. This string is the same as the F90 identifier associated with the integer index.

get_obs_kind_name    Name string associated with this entry in the obs_kind_info table.
obs_kind_ind    An integer index into the obs_kind_info table.


var = assimilate_this_obs_kind(obs_kind_ind)
 logical, intent(out) :: assimilate_this_obs_kind
 integer, intent(in)  :: obs_kind_ind
 

Description

Given an integer index into the obs_kind_info table (the index is defined in the integer, parameter statement for the observation types that is created by the preprocess program (see DEFAULT_obs_kind_mod.html), returns true if this observation type is to be assimilated, otherwise false.

assimilate_this_obs_kind    Returns true if this entry in the obs_kind_info table is to be assimila ted.
obs_kind_ind    An integer index into the obs_kind_info table.


var = evaluate_this_obs_kind(obs_kind_ind)
 logical, intent(out) :: evaluate_this_obs_kind
 integer, intent(in)  :: obs_kind_ind
 

Description

Given an integer index into the obs_kind_info table (the index is defined in the integer, parameter statement for the observation types that is created by the preprocess program (see DEFAULT_obs_kind_mod.html), returns true if this observation type is to be evaluated, otherwise false.

evaluate_this_obs_kind    Returns true if this entry in the obs_kind_info table is to be evaluated.
obs_kind_ind    An integer index into the obs_kind_info table.


var = get_obs_kind_var_type(obs_kind_ind)
 integer, intent(out) :: get_obs_kind_var_type
 integer, intent(in)  :: obs_kind_ind
 

Description

Given an integer index into the obs_kind_info table (the index is defined in the integer, parameter statement for the observation types that is created by the preprocess program (see DEFAULT_obs_kind_mod.html), returns the integer index of the GENERIC KIND that is associated with this observation type.

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


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

Description

Given the name of an observation type, returns the index of the entry in the obs_kind_info 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_kind_info table entry with name string corre sponding to obs_kind_name.
obs_kind_name    Name of observation type to be found in obs_kind_info table.


call write_obs_kind(ifile,fform)
 integer, intent(in)                    :: ifile
 character(len=*), optional, intent(in) :: fform
 

Description

Writes out information about all defined observation types from the obs_kind_info 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.

ifile    Unit number of output observation sequence file being written.
fform    Optional format for file. Default is ascii.


call read_obs_kind(ifile,pre_I_format,fform)
 integer, intent(in)                    :: ifile
 logical, intent(in)                    :: pre_I_format
 character(len=*), optional, intent(in) :: fform
 

Description

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_kind_info 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_kind_info table (integer index 1 in the file corresponds to the first table entry, etc.)

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.
fform    Optional format for file. Default is ascii.


var = get_kind_from_menu()
 integer, intent(out) :: get_kind_from_menu
 

Description

Interactive input of observation type from the obs_kind info.

get_kind_from_menu    Integer index of observation type.


var = map_def_index(obs_def_index)
 integer, intent(out) :: map_def_index
 integer, intent(in)  :: obs_def_index
 

Description

Maps from the integer observation type index in the header block of an input observation sequence file into the corresponding entry in the obs_kind_info table. This allows observation sequences that were created with different obs_kind_mod.f90 versions to be used with the current obs_kind_mod.

map_def_index    Index of this observation type in obs_kind_info table.
obs_def_index    Index of observation type from input observation sequence file.


integer, parameter :: max_obs_kinds

Description

The total number of available observation types in the obs_kind_info table. This value is added by the preprocess program.



integer, parameter :: KIND_.....

Description

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



integer, parameter :: SAMPLE_OBS_TYPE

Description

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_kind_info table.





We adhere to the F90 standard of starting a namelist with an ampersand '&' and terminating with a slash '/'.

 namelist / obs_kind_nml / 
 assimilate_these_obs_types,evaluate_these_obs_types



 

Discussion

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_kind_info table is eligble. 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 evluate_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.

This namelist is read in a file called input.nml

Contents Type Description
assimilate_these_obs_types character(len=129) Name of observation type to be assimilated only. Default: null
evaluate_these_obs_types character(len=129) Name of observation type to be evaluated only. Default: null




FILES




REFERENCES


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_kind_info 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_kind_info table.



KNOWN BUGS




FUTURE PLANS