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

MODULE assim_tools_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.2 $
Change Date: $Date: 2004/04/26 20:18:23 $
Change history: see CVS log

OVERVIEW

This module provides subroutines that implement the sequential scalar filter algorithms. These include the standard sequential filter as described in Anderson (2003) along with systematic correction algorithms for both mean and spread. In addition, algorithms to do a variety of flavors of filters including the EAKF, ENKF, particle filter, and kernel filters are included.




OTHER MODULES USED

types_mod
utilities_mod
sort_mod
random_seq_mod



PUBLIC INTERFACE

use assim_tools_mod, only : assim_tools_init &
 obs_increment &
 update_from_obs_inc
 look_for_bias




PUBLIC COMPONENTS


call assim_tools_init( )

Description

Initialization routine for assim_tools. This must be called before other public interfaces can be used.


call obs_increment( ens, ens_size, obs, obs_var, obs_inc, slope, a, [,bias_ratio_out] )
real(r8), intent(in), dimension(ens_size) :: ens 
integer, intent(in)                       :: ens_size 
real(r8), intent(in)                      ::  obs 
real(r8), intent(in)                      ::  obs_var 
real(r8), intent(out), dimension(ens_size) ::  obs_inc 
real(r8), intent(in)                      ::  slope 
real(r8), intent(out)                      ::  a 
real(r8), OPTIONAL, intent(out)           ::  bias_ratio_out 

Description

Does a scalar update of a prior ensemble in observation space and computes the increments for each prior ensemble member. Four different ensemble filter algorithms are selectable through a namelist arguement. The EAKF variant also includes a capability to do an empirical systematic error correction.

ens     The prior ensemble expected values for this observation.
ens_size Size of the prior ensemble.
obs The observed value (from the instrument).
obs_var The observational error variance (from the observing system).
obs_inc The increments computed for the prior ensemble.
slope Parameter that controls the strength of the systematic error correction. Values range from small positive (strong corrections) to 1.0 (weak corrections). A value of 0 indicates that no correction is to be done.
a Ratio of updated ensemble standard deviation to prior standard deviation from EAKF. This is used in the heuristic prior variance reduction correction in update_from_obs_inc.
bias_ratio_out Optional ratio of difference between ensemble mean and observation and expected value. Can be used to assess systematic error.


call update_from_obs_inc(obs, obs_inc, state, ens_size, a, state_inc, reg_coef, [,correl_out] )
real(r8), intent(in), dimension(ens_size)  :: obs 
real(r8), intent(in), dimension(ens_size)  :: obs_inc 
real(r8), intent(in), dimension(ens_size)  :: state 
integer, intent(in)                        :: ens_size 
real(r8), intent(in)                       ::  a 
real(r8), intent(out), dimension(ens_size) :: state_inc 
real(r8), intent(out)                      ::  reg_coef 
real(r8), OPTIONAL, intent(out)            ::  correl_out 

Description

Given the prior joint distribution of an observation and a state variable along with computed increments for the observation ensemble members, uses a linear regression to compute increments for the state variable ensemble. An optional algorithm to do prior corrections of spread reduction is also available for use with the EAKF variant of the filter. The increments and the regression coefficient are returned and optionally the correlation between the state and observation priors.

obs     The prior ensemble expected values for this observation.
obs_inc     The observation increments for the ensemble computed by obs_increment.
state     The prior ensemble values for a state variable.
ens_size Size of the ensemble.
a Ratio of updated ensemble standard deviation to prior standard deviation from EAKF. This is used in the heuristic prior variance reduction correction in update_from_obs_inc.
state_inc The increments computed for the state variable ensemble.
reg_coef The regression coefficient between the observation and state variable ensembles.
correl_out Optional sample correlation between state and prior.


call look_for_bias(ens, n, obs, obs_var, var_ratio)
real(r8), intent(in), dimension(n)         :: ens 
integer, intent(in)                        :: n 
real(r8), intent(in),                      :: obs 
real(r8), intent(in), dimension(ens_size)  :: obs_var 
real(r8), intent(out)                       ::  var_ratio 

Description

Given a prior ensemble estimate, an observation, and the observational error variance, computes the ratio of the square of ratio of the difference between the ensemble mean and the observation to the expected value of this difference.

ens     The prior ensemble expected values for this observation.
n Size of the ensemble.
obs     The observed value.
obs_var     The observational error variance.
var_ratio Ratio of square of difference between ensemble mean prior and observed value to the expected variance of this quantity.




NAMELIST

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

namelist / assim_tools_nml /  &
    prior_spread_correction, filter_kind, slope_threshold

Discussion

This namelist is read in a file called input.nml

Contents Type Description
prior_spread_correction logical True if prior spread reduction correction algorithm is to be used. Default is false.
filter_kind integer Selects the variant of filter to be used. 1=EAKF, 2=ENKF, 3=Kernel filter, 4 = particle filter.
slope_threshold real(r8) Threshold value of variance ratio at which systematic error correction begins to be applied if slope is not 0.



FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
obs_increment Illegal value of filter_kind in assim_tools namelist [1-4 OK] Only 4 variants currently supported.
obs_increment_particle Confidence slope bias correction is not implemented Can't use bias correction with particle filter at present.
obs_increment_enkf Confidence slope bias correction is not implemented Can't use bias correction with ENKF at present.
obs_increment_kernel Confidence slope bias correction is not implemented Can't use bias correction with kernel filter at present.
update_from_obs_inc The prior_spread_correction algorithm only works with EAKF filters. Do not select prior_spread_correction = .true. with other filters. Prior spread correction only works with EAKF.



KNOWN BUGS




FUTURE PLANS

Discussion