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

MODULE assim_tools_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.5 $
Release Name: $Name: pre_hawaii $
Change Date: $Date: 2004/12/22 20:48:12 $
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
obs_sequence_mod
obs_def_mod
cov_cutoff_mod
obs_model_mod
reg_factor_mod
location_mod
time_manager_mod
ensemble_manager_mod



PUBLIC INTERFACE

use assim_tools_mod, only : assim_tools_init
 obs_increment
 update_from_obs_inc
 look_for_bias
 filter_assim
 async_assim_region
 assim_tools_end




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_in, ens_size, obs, obs_var, obs_inc)
real(r8), intent(in), dimension(ens_size)  :: ens_in 
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 

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. Obs_increment also implements the adaptive systematic error correction algorithm using observation space covariance inflation. A number of options for this algorithm are selected through namelist parameters.

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.


call update_from_obs_inc(obs, obs_inc, state, ens_size, 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(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.
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.


call filter_assim(ens_handle, ens_obs, compute_obs_in, ens_size, model_size, num_obs_in_set, num_groups, seq, keys, confidence_slope, cutoff, save_reg_series, reg_series_unit, obs_seq_in_name)
 type(ensemble_type), intent(in)                           :: ens_handle
 real(r8), dimension(ens_size, num_obs_in_set), intent(in) :: ens_obs
 logical, dimension(num_obs_in_set), intent(in)            :: compute_obs_in
 integer, intent(in)                                       :: ens_size
 integer, intent(in)                                       :: model_size
 integer, intent(in)                                       :: num_obs_in_set
 integer, intent(in)                                       :: num_groups
 type(obs_sequence_type), intent(inout)                    :: seq 
 integer, dimension(num_obs_in_set), intent(in)            :: keys
 real(r8), intent(in)                                      :: confidence_slope
 real(r8), intent(in)                                      :: cutoff
 logical, intent(in)                                       :: save_reg_series
 integer, intent(in)                                       :: reg_series_unit
 character(len=*), intent(in)                              :: obs_seq_in_name
 

Description

Entry subroutine to do an assimilation for a given observation set. Calls are made to internal subroutine filter_assim_region to do actual assimilation for each domain as requested by the num_domains namelist parameter. This public subroutine can either call filer_assim_region directly or create appropriate files for each domain and use the shell to execute programs to do the regions (controlled by do_parallel option in namelist). The current parallel assimilation algorithm does not recompute any observations but simply updates the prior distribution each time another observation is assimilated. For single domain use, the compute_obs_in logical array indicates if there are state variables that cannot (or should not) be recomputed during the sequential assimilation. Support for the reg_series output is very limited with this release and is confined to low-order models.

ens_handle    Identifies ensemble (see ensemble_manager_mod)
ens_obs    Ensemble prior values for observations
compute_obs_in    True if corresponding observation can be recomputed here
ens_size    Ensemble size
model_size    Model state vector length
num_obs_in_set    Number of observations to be assimilated
num_groups    Number of groups for filter
seq    Observation sequence
keys    Indices of the current observations in seq
confidence_slope    Adaptive bias correction (see obs_increment)
cutoff    Localization factor (see update_from_obs_inc)
save_reg_series    True to save regression stats (low-order only)
reg_series_unit    Open to regression stats file if needed
obs_seq_in_name    Obs sequence is written here if shell driven multiple domains


call async_assim_region(in_file_name,out_file_name)
 character(len=*), intent(in) :: in_file_name
 character(len=*), intent(in) :: out_file_name
 

Description

This is a subroutine designed to allow calls to filter_assim_region to be handled by separate processes through the shell. Instead of having a direct call from filter_assim, filter_assim writes out all the arguments for filter_assim_region for a given region to a file. The shell then starts a program, assim_region, which calls async_assim_region with the appropriate file names. The arguments are obtained by the file by async_assim_region and then a call is made to subroutine filter_assim_region. At completion, the output arguments are written to out_file_name.

in_file_name    File where input required for filter_assim_region is found
out_file_name    File where output from filter_assim_region is to be put


call assim_tools_end()
 

Description

Called to terminate use of assim_tools_mod. Writes out the assim_tools restart file. This file contains the observation space covariance inflation parameter and the standard deviation of the covariance inflation.





NAMELIST

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

namelist / assim_tools_nml /  &
filter_kind, sort_obs_inc, cov_inflate, cov_inflate_sd, sd_lower_bound, &
deterministic_cov_inflate, start_from_assim_restart, assim_restart_in_file_name, &
assim_restart_out_file_name, do_parallel, num_domains, parallel_command

Discussion

This namelist is read in a file called input.nml

Contents Type Description
filter_kind integer Selects the variant of filter to be used. 1=EAKF, 2=ENKF, 3=Kernel filter, 4=particle filter.
sort_obs_inc logical If true, the final increments from obs_increment are sorted so that the mean increment value is as small as possible. This minimizes regression errors when non-deterministic filter or error correction algorithms are applied. Default is false.
cov_inflate real(r8) Initial mean value of the observation space covariance inflation factor. If start_from_assim_restart is true, this is overwritten by the value in the file. If the value is less than 0, no observation space covariance inflation is applied. Defalut value is -1 (no inflation).
cov_inflate_sd real(r8) Initial value of the standard deviation of the observation space covariance inflation factor. If start_from_assim_restart is true, this is overwritten by the second value in the restart file. If this value is less than 0.0, the mean value stays constant in time. If the value is greater than the sd_lower_bound (see below), an adjustment of this value takes place at each assimilation step. Default value is 0.05.
sd_lower_bound real(r8) Smallest value allowed for cov_inflate_sd during a run (it can be set to values smaller than cov_inflate_sd initially). Once cov_inflate_sd is reduced to this value, the systematic error correction algorithm will keep the cov_inflate_sd fixed at this value. Default value is 0.05.
deterministic_cov_inflate logical Selects manner in which uncertainty is added to prior obs space distribution for obs space covariance inflation. If this is true, ensemble members are just moved out by increasing the distance between each ensemble member and the mean by this factor. If false, a random draw from a gaussian is added to each ensemble member. Default is true.
start_from_assim_restart logical If true, values of cov_inflate and cov_inflate_sd are read from a file. Default is false.
assim_restart_in_file_name character(len=129) Name of file from which to read in cov_inflate and cov_inflate_sd override values. Default is assim_tools_ics.
assim_restart_out_file_name character(len=129) Name of file to which to write cov_inflate and cov_inflate_sd final values for possible restart. Default is assim_tols_restart.
do_parallel integer Execution control: 0 = single executable; 2 = parallel_command; 3 = use filter_server Default: 0
num_domains integer Use this many subdomains; assimilate each independently Default: 1
parallel_command character(len=129) Command to be executed for option 2 Default: ./assim_filter.csh



FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
assim_tools_init do parallel option # not supported Only 0, 2, 3 currently supported.
obs_increment Illegal value of filter_kind in assim_tools namelist [1-4 OK] Only 1-4 currently supported.
obs_increment_eakf Both obs_var and prior_var are zero. This is inconsistent Product of two delta functions doesn't work.
filter_assim Use less than 10000 domains. Need to modify code for more than 10000 domains.
filter_assim Did not find observation copy with metadata "observation" In obs_sequence file, need to find copy that is observations.
filter_assim Having more domains than state variables does not make sense It doesn't.



KNOWN BUGS

The current version of the systematic error correction algorithm does not work in a logical fashion with the parallel region assimilation feature.




FUTURE PLANS

Discussion