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

MODULE adaptive_inflate_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.2 $
Release Name: $Name: post_iceland $
Change Date: $Date: 2006/06/19 23:17:55 $
Change history: see CVS log


OVERVIEW

This module implements a variety of hierarchical Bayesian adaptive inflation algorithms for use with ensemble filters. It can provide constant valued inflation in state or obsevation space, consistent with previous DART releases. It can provide spatially-constant, time-varying spatial adaptive inflation. It can provide spatially-varying, time-varying spatial adaptive inflation and it can provide temporally-varying observation space inflation. Diagnostic output and restart files are available. Several papers on the NCAR/IMAGe/DAReS web page document the algorithms in detail. The DART/tutorial/section12 chapter has more information.

The namelist documentation describes how to use different inflation options.




OTHER MODULES USED

types_mod
utilities_mod
random_seq_mod
time_manager_mod



PUBLIC INTERFACE

use adaptive_inflate_mod, only : update_inflation
 adaptive_inflate_ss_init
 adaptive_inflate_end
 adaptive_inflate_obs_init
 inflate_ens
 output_inflate_diagnostics
 do_obs_inflate
 do_single_ss_inflate
 do_varying_ss_inflate
 ss_inflate
 ss_inflate_sd
 obs_inflate
 obs_inflate_sd
 ss_sd_lower_bound
 ss_inf_upper_bound
 obs_sd_lower_bound
 obs_inf_upper_bound

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




PUBLIC COMPONENTS



call update_inflation(inflate,inflate_sd,prior_mean, prior_var,obs,obs_var,gamma,sd_lower_bound, inf_upper_bound)
 real(r8), intent(inout) :: inflate
 real(r8), intent(inout) :: inflate_sd
 real(r8), intent(in)    :: prior_mean
 real(r8), intent(in)    :: prior_var
 real(r8), intent(in)    :: obs
 real(r8), intent(in)    :: obs_var
 real(r8), intent(in)    :: gamma
 real(r8), intent(in)    :: sd_lower_bound
 real(r8), intent(in)    :: inf_upper_bound
 

Description

Updates the mean and standard deviation of an inflation distribution given the prior values, the prior observation ensemble mean and variance, and the observation and its error variance. The factor gamma is the expected impact (0 to 1) of the state variable corresponding to the infaltion on the observation and is the product of the ensemble correlation plus and additional localization factors or group regression factors.

inflate    Prior mean value of the inflation distribution.
inflate_sd    Prior standard deviation of the inflation distribution.
prior_mean    Mean of the prior observation ensemble.
prior_var    Variance of the prior observation ensemble.
obs    The observed value.
obs_var    Observational error variance.
gamma    Expected impact factor, product of correlation, localization, regression factor.
sd_lower_bound    Lower bound on updated inflation standard deviation.
inf_upper_bound    Upper bound on updated inflation mean.


call adaptive_inflate_ss_init(model_size)
 integer, intent(in) :: model_size
 

Description

Initializes the module if state space inflation is being used. Allocates required storage for the inflation mean and standard deviation, reads restart files, and gets initial values from the namelist as required.

model_size    Size of the model.


call adaptive_inflate_end()
 

Description

Writes required restart files and deallocates storage used for inflation mean and standard deviation.


call adaptive_inflate_obs_init(num_domains,dont_read_restart)
 integer, intent(in) :: num_domains
 logical, intent(in) :: dont_read_restart
 

Description

Reads restarts and intializes inflation values for observation space inflation.

num_domains    Number of domains if parallel assimilation is being done.
dont_read_restart    Don't read in a restart no matter what namelist says.


call inflate_ens(ens,mean,inflate,var_in)
 real(r8), dimension(:), intent(out) :: ens
 real(r8), intent(in)                :: mean
 real(r8), intent(in)                :: inflate
 real(r8), optional, intent(in)      :: var_in
 

Description

Given an ensemble, its mean and the covarance inflation factor, inflates the ensemble.

ens    Values for the ensemble to be inflated
mean    The mean of the ensemble.
inflate    The covariance inflation factor.
var_in    The variance of the ensemble.


call output_inflate_diagnostics(time)
 type(time_type), intent(in) :: time
 

Description

Outputs diagnostic record of inflation for the observation space of spatially constant state space inflation. Spatially varying state space diagnostics are in the Posterior and Prior Diagnostic netcdf files and are written with calls from filter.f90.

time    Time of this diagnostic info.


logical :: do_obs_inflate, do_fixed_ss_inflate, do_varying_ss_inflate

Description

This allows public access to these namelist variables which determine which inflation options are in use. See namelist documentation.



real(r8), allocatable :: ss_inflate(:), ss_inflate_sd(:)

Description

These two arrays are managed by adaptive_inflate_mod and contain the mean and standard deviation of the inflation distributions. If fixed spatial inflation is in use, the size of each is 1. If varying spatial inflation is in use, the size of each is model_size. This direct access is for efficiency and is not a very safe programming practice.



real(r8), allocatable :: obs_inflate(:), obs_inflate_sd(:)

Description

These two arrays are managed by adaptive_inflate_mod and contain the mean and standard deviation of the inflation distributions for observation space inflation. The size of each is the number of parallel domains/regions in use. This direct access is for efficiency and is not a very safe programming practice.



real(r8) :: ss_sd_lower_bound, ss_inf_upper_bound

Description

This allows public access to these namelist variables. The first sets a hard lower bound on the standard deviation for the state space inflation distribution and the second puts a hard upper bound on the mean. See the namelist documentation for more information.



real(r8) :: obs_sd_lower_bound, obs_inf_upper_bound

Description

This allows public access to these namelist variables. The first sets a hard lower bound on the standard deviation for the observation space inflation distribution and the second puts a hard upper bound on the mean. See the namelist documentation for more information.





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

 namelist / adaptive_inflate_nml / 
 do_obs_inflate,do_varying_ss_inflate,do_single_ss_inflate,
start_from_inflate_restart,output_restart,deterministic_inflate,
inflate_in_file_name,inflate_out_file_name,obs_inf_initial,
obs_inf_sd_initial,obs_sd_lower_bound,obs_inf_upper_bound,
ss_inf_initial,ss_inf_sd_initial,ss_sd_lower_bound,ss_inf_up
 

Discussion

The namelist controls the operation of the various inflation options. The three entries, do_obs_inflate, do_varying_ss_inflate, and do_single_ss_inflate select what type of inflation to do. At most one of these can be true; all false indicates no inflation.

To do traditional, fixed state space inflation, select do_single_ss_inflate, set ss_inf_initial to the desired inflation value and set the ss_inf_sd_initial and ss_sd_lower_bound to negative values.

To do temporally-varying but spatially constant inflation, select do_single_ss_inflate and set ss_inf_initial and ss_inf_sd_initial to the desired initial values. To avoid potential inflation filter divergence, the ss_sd_lower_bound can be set. If ss_inf_sd_initial and ss_sd_lower_bound are set to the same value, the standard deviation will remain fixed at the intial value. To avoid large inflation values, ss_inf_upper_bound can be set to limit the mean inflation values.

To do spatially-varying temorarlly-varying inflation, select do_varying_ss_inflate and set ss_inf_initial and ss_inf_sd_initial to the desired initial values. To avoid potential inflation filter divergence, the ss_sd_lower_bound can be set. If ss_inf_sd_initial and ss_sd_lower_bound are set to the same value, the standard deviation will remain fixed at the intial value. To avoid large inflation values, ss_inf_upper_bound can be set to limit the mean inflation values.

To do temporally-fixed observation space inflation, select do_obs_inflate, set obs_inf_initial to the desired inflation value and set obs_inf_sd_initial and obs_sd_lower_bound to negative values.

To do temporally-varying observation space inflation (this was the adaptive algorithm available in previous DART releases), select do_obs_inflate, and set obs_inf_initial and obs_inf_sd_initial to the desired initial values. To avoid potential inflation filter divergence, the obs_sd_lower_bound can be set. If obs_inf_sd_initial and obs_sd_lower_bound are set to the same value, the standard deviation will remain fixed at the intial value. To avoid large inflation values, obs_inf_upper_bound can be set to limit the mean inflation values.

This namelist is read in a file called input.nml

Contents Type Description
do_obs_inflate logical True to do obs space inflation. Default: .false.
do_varying_ss_inflate logical True to do spatially-varying temporally-varying inflation. Default: .false.
do_single_ss_inflate logical True to do spatially constant temporally-varying state space inflation. Default: .false.
start_from_inflate_restart logical True if initial inflation distributions are to be read from restart file. Default: .false.
output_restart logical True if final inflation distribution values are to be written to restart file. Default: .true.
deterministic_inflate logical True if inflation is to be done by linear inflation. False implies stocahstic inflation. Default: .true.
inflate_in_file_name character(len=129) Inflation restart file name. Default: inflate_ics
inflate_out_file_name character(len=129) Inflation output restart file name. Default: inflate_restart
obs_inf_initial real Initial value of obs space inflation mean if not starting from restart. Default: 1.0
obs_inf_sd_initial real Initial value of obs space inflation standard deviation. 0 or negative gives time constant. Default: 0.0
obs_sd_lower_bound real Hard lower bound on the standard deviation for obs space inflation. Default: 0.0
obs_inf_upper_bound real Hard upper bound on the mean for obs space inflation. Default: 10000000
ss_inf_initial real Initial value of state space inflation mean if not starting from restart. Default: 1.0
ss_inf_sd_initial real Initial value of state space inflation standard deviation. 0 or negative gives time constant. Default: 0.0
ss_sd_lower_bound real Hard lower bound on the standard deviation for state space inflation. Default: 0.0
ss_inf_upper_bound real Hard upper bound on the mean for state space inflation. Default: 10000000
diagnostic_file_name character(len=129) File name of output diagnostic file used for obs space and fixed state space inflation. Default: inflate_diag




FILES




REFERENCES

  • Anderson, Jeffrey L., 2006: An adaptive covariance inflation error correction algorithm for ensemble filters.
  • Anderson, Jeffrey L., 2006: Spatially-varying adaptive covariance inflation in an ensemble filter.

    ERROR CODES and CONDITIONS

    RoutineMessageComment
    adaptive_inflate_init Can only use one type of inflation at a time. No more than one of the do_inflation options can be true.
    adaptive_inflate_ss_init Size of state space restart file is incorrect. Restart file must have single entry for fixed spatial inflation and model_size entries for spatially-varying inflation.
    adaptive_inflate_obs_init Number of domains in restart not same as number of domains. Restart must be same size as number of domains in use.



    KNOWN BUGS




    FUTURE PLANS




    PRIVATE COMPONENTS

    Discussion