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

MODULE obs_def_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.7 $
Release Name: $Name: pre_iceland $
Change Date: $Date: 2005/10/17 19:47:35 $
Change history: see CVS log

OVERVIEW

Provides an abstraction of the definition of an observation. An observation sequence at a higher level is composed of observation definitions associated with observed values. For now, the basic operations required to implement an observation definition are an ability to compute a forward operator given the model state vector, the ability to read/write the observation definition from/to a file, and a capability to do a standard input driven interactive definition of the observation definition.

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_def module being described here is created by the program preprocess.f90 from two kinds of input files. First, a DEFAULT obs_def module (normally called DEFAULT_obs_def_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 this directory. If no special obs_def files are included in the preprocessor namelist, a minimal obs_def_mod.f90 is created which can only support identity forward observation operators.





OTHER MODULES USED

types_mod
utilities_mod
location_mod (depends on model choice)
time_manager_mod
assim_model_mod
obs_kind_mod
Other speical obs_def_kind modules as required



PUBLIC INTERFACE

use obs_def_mod, only : obs_def_type
 init_obs_def
 get_obs_def_location
 get_obs_kind
 get_obs_def_time
 get_obs_def_error_variance
 set_obs_def_location
 set_obs_def_kind
 set_obs_def_time
 set_obs_def_error_variance
 set_obs_def_key
 interactive_obs_def
 write_obs_def
 read_obs_def
 get_expected_obs_from_def
 destroy_obs_def
 copy_obs_def
 assignment(=)
 get_obs_name




PUBLIC COMPONENTS





type obs_def_type
   private
   type(location_type)  :: location
   integer              :: kind
   type(time_type)      :: time
   real(r8)             :: error_variance
   integer              :: key
end type obs_def_type

Description

Models all that is known about an observation except for actual values. Includes a location, kind, time and error variance.

Component Description
location Location of the observation.
kind The kind of the observation.
time Time of the observation.
error_variance Error variance of the observation.
key Unique identifier for observations of a particular kind.



call init_obs_def(obs_def, location, kind, time, error_variance)
 type(obs_def_type),  intent(out) :: obs_def
 type(location_type), intent(in)  :: location
 integer,             intent(in)  :: kind
 type(time_type),     intent(in)  :: time
 real(r8),            intent(in)  :: error_variance
 

Description

Creates an obs_def type with location, kind, time and error_variance specified.

obs_def    The obs_def that is created
location    Location for this obs_def
kind    Observation kind for obs_def
time    Time for obs_def
error_variance    Error variance of this observation




call copy_obs_def(obs_def1,obs_def2)
 type(obs_def_type), intent(out) :: obs_def1
 type(obs_def_type), intent(in)  :: obs_def2
 

Description

Copies obs_def2 to obs_def1, overloaded as assignment (=).

obs_def1    obs_def to be copied into
obs_def2    obs_def to be copied from




var = get_obs_def_error_variance(obs_def)
 real(r8)                       :: get_obs_def_error_variance
 type(obs_def_type), intent(in) :: obs_def
 

Description

Returns error variance from an obs_def.

get_obs_def_error_variance    Error variance from an obs_def
obs_def    An obs_def


var = get_obs_def_location(obs_def)
 type(location_type), intent(out) :: get_obs_def_location
 type(obs_def_type), intent(in)   :: obs_def
 

Description

Returns the location from an obs_def.

get_obs_def_location    Returns location from an obs_def
obs_def    An obs_def


var = get_obs_kind(obs_def)
 integer,            intent(out) :: var
 type(obs_def_type),  intent(in) :: obs_def
 

Description

Returns an observation kind from an observation definition.

var    Returns the obs_kind from an obs_def
obs_def    An obs_def


var = get_obs_def_time(obs_def)
 type(time_type)                :: get_obs_def_time
 type(obs_def_type), intent(in) :: obs_def
 

Description

Returns time from an obs_def.

get_obs_def_time    Returns time from an obs_def
obs_def    An obs_def




obs_name = get_obs_name(obs_kind_ind)
 character(len = 32)            :: get_obs_name
 type(obs_def_type), intent(in) :: obs_def
 

Description

Given the integer index associated with an observation type, returns the observation name. See obs_kind for more detail.

get_obs_name    Returns name from an obs kind
obs_kind_ind    An obs kind




call set_obs_def_location(obs_def, location)
 type(obs_def_type),  intent(inout) :: obs_def
 type(location_type), intent(in)    :: location
 

Description

Set the location in an obs_def.

obs_def    An obs_def
location    A location




call set_obs_def_error_variance(obs_def, error_variance)
 type(obs_def_type), intent(inout) :: obs_def
 real(r8), intent(in)              :: error_variance
 

Description

Set error variance for an obs_def.

obs_def    An obs_def
error_variance    Error variance




call set_obs_def_key(obs_def, key)
 type(obs_def_type), intent(inout) :: obs_def
 integer,            intent(in)    :: key
 

Description

Set the key for an obs_def.

obs_def    An obs_def
key    Unique identifier for this observation




call set_obs_def_kind(obs_def, kind)
 type(obs_def_type), intent(inout) :: obs_def
 integer,            intent(in)    :: kind
 

Description

Set the kind of observation in an observation definition.

obs_def    An obs_def
kind    An integer pertaining to a particular kind of observation.




call set_obs_def_time(obs_def, time)
 type(obs_def_type), intent(inout) :: obs_def
 type(time_type), intent(in)       :: time
 

Description

Sets time for an obs_def.

obs_def    An obs_def
time    Time to set




call get_expected_obs_from_def(key, obs_def, obs_kind_ind, state, obs_val, istatus, assimilate_this_ob, evaluate_this_ob)
 integer,            intent(in)  :: key
 type(obs_def_type), intent(in)  :: obs_def
 integer,            intent(in)  :: obs_kind_ind
 real(r8),           intent(in)  :: state(:)
 real(r8),           intent(out) :: obs_val
 integer,            intent(out) :: istatus
 logical,            intent(out) :: assimilate_this_ob
 logical,            intent(out) :: evaluate_this_ob
 

Description

Compute the observation (forward) operator for a particular obs definition.

key    descriptor for observation type
obs_def    The input obs_def.
obs_kind_ind    The obs kind
state    Model state vector
istatus    Returned integer describing problems with applying forward operator
assimilate_this_ob    Indicates whether to assimilate this obs or not
evaluate_this_ob    Indicates whether to evaluate this obs or not




call read_obs_def(ifile, obs_def, key, [,fform])
 integer,                    intent(in)    :: ifile
 type(obs_def_type),         intent(inout) :: obs_def
 integer,                    intent(in)    :: key
 character(len=*), optional, intent(in)    :: fform
 

Description

Reads an obs_def from file open on channel ifile. Uses format specified in fform or FORMATTED if fform is not present.

ifile    File unit open to output file
obs_def    Observation definition to be read
key    descriptor of xxxx ... unused?
fform    File format specifier: FORMATTED or UNFORMATTED; default FORMATTED


call interactive_obs_def(obs_def)
 type(obs_def_type), intent(inout) :: obs_def
 

Description

Creates an obs_def via input from standard in.

obs_def    An obs_def


call write_obs_def(ifile,obs_def [,fform])
 integer,                    intent(in) :: ifile
 type(obs_def_type),         intent(in) :: obs_def
 character(len=*), optional, intent(in) :: fform
 

Description

Writes an obs_def to file open on channel ifile. Uses format specified in fform or FORMATTED if fform is not present.

ifile    File unit open to output file
obs_def    Observation definition to be written
fform    File format specifier: FORMATTED or UNFORMATTED; default FORMATTED


call destroy_obs_def(obs_def)
 type(obs_def_type), intent(inout) :: obs_def
 

Description

Releases all storage associated with an obs_def and its subcomponents.

obs_def    An obs_def to be released.




FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
get_expected_obs_from_def Attempt to evaluate undefined obs_kind_type An observation kind integer index for which no forward operator has been defined is an error.
read_obs_def Expected header "obdef" in input file The format of the input file is not consistent.
read_obs_def Expected kind header "kind " in input file The format of the input file is not consistent.
read_obs_def Attempt to read for undefined obs_kind type Reading for an observation kind integer index for which no forward operator has been defined is an error.
write_obs_def Attempt to write for undefined obs_kind type Writing for an observation kind integer index for which no forward operator has been defined is an error.
interactive_obs_def Attempt to interactively create undefined obs_kind type Creating an observation kind integer index for which no forward operator has been defined is an error.



KNOWN BUGS




FUTURE PLANS