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

MODULE assim_tools_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.12 $
Release Name: $Name: $
Change Date: $Date: 2006/09/11 14:35:32 $
Change history: see CVS log


OVERVIEW

This module provides subroutines that implement the 'parallel' versions of 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. The parallel implementation that allows each observation to update all state variables that are close to it at the same time is described in Anderson (2007).



OTHER MODULES USED

types_mod
utilities_mod
sort_mod
random_seq_mod
obs_sequence_mod
obs_def_mod
cov_cutoff_mod
reg_factor_mod
location_mod (model dependent choice)
ensemble_manager_mod
mpi_utilities_mod
adaptive_inflate_mod
time_manager_mod
assim_model_mod



PUBLIC INTERFACE

use assim_tools_mod, only : filter_assim

Optional namelist interface &assim_tools_nml may be read from file input.nml.




PUBLIC COMPONENTS



call filter_assim(ens_handle,obs_ens_handle,obs_seq,keys,ens_si ze,num_groups,obs_val_index,inflate,ENS_MEAN_COPY,ENS_SD_COPY,ENS_INF_COPY,ENS_ INF_SD_COPY,OBS_KEY_COPY,OBS_GLOBAL_QC_COPY,OBS_PRIOR_MEAN_START,OBS_PRIOR_MEAN _END,OBS_PRIOR_VAR_START,OBS_PRIOR_VAR_END,inflate_only)
 type(ensemble_type), intent(inout)         :: ens_handle
 type(ensemble_type), intent(inout)         :: obs_ens_handle
 type(obs_sequence_type), intent(in)        :: obs_seq
 integer, dimension(:), intent(in)          :: keys
 integer, intent(in)                        :: ens_size
 integer, intent(in)                        :: num_groups
 integer, intent(in)                        :: obs_val_index
 type(adaptive_inflate_type), intent(inout) :: inflate
 integer, intent(in)                        :: ENS_MEAN_COPY
 integer, intent(in)                        :: ENS_SD_COPY
 integer, intent(in)                        :: ENS_INF_COPY
 integer, intent(in)                        :: OBS_KEY_COPY
 integer, intent(in)                        :: OBS_GLOBAL_QC_COPY
 
 integer, intent(in)                        :: OBS_PRIOR_MEAN_STA
 RT
 integer, intent(in)                        :: OBS_PRIOR_MEAN_END
 
 integer, intent(in)                        :: OBS_PRIOR_VAR_STAR
 T
 integer, intent(in)                        :: OBS_PRIOR_VAR_END<
 /em>
 logical, intent(in)                        :: inflate_only
 

Description

Does assimilation and inflation for a set of observations that is identified by having integer indices listed in keys. Only the inflation is updated if inflation_only is true, otherwise the state is also updated.

ens_handle    Contains state variable ensemble data and description.
obs_ens_handle    Contains observation prior variable ensemble and description.
obs_seq    Contains the observation sequence including observed values and error v ariances.
keys    A list of integer indices of observations in obs_seq that are to be use d at this time.
ens_size    Number of ensemble members in state and observation prior ensembles.
num_groups    Number of groups being used in assimilation.
obs_val_index    Integer index of copy in obs_seq that contains the observed value from instrument.
inflate    Contains inflation values and all information about inflation to be use d.
ENS_MEAN_COPY    Index of copy containing ensemble mean in ens_handle.
ENS_SD_COPY    Index of copy containing ensemble standard deviation in ens_handle.
ENS_INF_COPY    Index of copy containing state space inflation in ens_handle.
ENS_INF_SD_COPY    Index of copy containing state space inflation standard deviation in en s_handle.
OBS_KEY_COPY    Index of copy containing unique key for observation in obs_ens_handle.< /TD>
OBS_GLOBAL_QC_COPY    Index of copy containing global quality control value in obs_ens_handle .
OBS_PRIOR_MEAN_START    Index of copy containing first group's prior mean in obs_ens_handle.
OBS_PRIOR_MEAN_END    Index of copy containing last group's prior mean in obs_ens_handle.< /TD>
OBS_PRIOR_VAR_START    Index of copy containing first group's ensemble variance in obs_ens_han dle.
OBS_PRIOR_VAR_END    Index of copy containing last group's ensemble variance in obs_ens_hand le.
inflate_only    True if only inflation is to be updated, and not state.


call filter_assim(ens_handle, ens_obs, compute_obs_in, ens_size, model_size, num_obs_in_set, num_groups, seq, keys, 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)                                      :: 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 filter_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
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




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, cutoff, sort_obs_inc, &
spread_restoration, sampling_error_correction, adaptive_localization_threshold

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. Default: 1.
cutoff real(r8) Cutoff controls a distance dependent weight that modulates the impact of an observation on a state variable. The units depend both on the location module being used and on the covariance cutoff module options selected. Default is 0.2.
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: false.
spread_restoration logical True turns on algorithm to restore amount of spread that would be expected to be lost if underlying obs/state variable correlation were really 0. Default: false
sampling_error_correction logical True uses special input files generated by correl_error.f90 in system_simulation to reduce errors in the regression step. Special input files corresponding with the ensemble size being used are required. This option is not yet fully supported. Contact the DART developers group if you have questions. Default: false
adaptive_localization_threshold integer Used to reduce the impact of observations in densely observed regions. If the number of observations close to a given observation is greater than the threshold number, the cutoff radius for localization is adjusted to try to make the number of observations close to the given observation be the threshold number. This should be dependent on the location module and is tuned for a three_dimensional spherical implementation for numerical weather prediction models at present. Default: -1



FILES




REFERENCES

Anderson, Jeffrey L. "A Local Least Squares Framework for Ensemble Filtering" April 2003, MWR 131, pp 634-642

ERROR CODES and CONDITIONS

RoutineMessageComment
assim_tools_init cant combine spread_restoration and filter_kind ### Spread restoration only compatible with filter_kind 1
obs_increment Illegal value of filter_kind in assim_tools namelist [1-4 OK] Only 1-6 currently supported.
obs_increment_eakf
obs_increment_ran_kf
obs_increment_det_kf
Both obs_var and prior_var are zero. This is inconsistent Product of two delta functions doesn't work.
get_correction_from_file Use less than 10000 ensemble File only works up to 9999 members.
get_correction_from_file Correction file ______ does not exist. Couldn't find the correction file in the working directory.



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




PRIVATE COMPONENTS

Discussion