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

MODULE adaptive_inflate_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.3 $
Release Name: $Name: $
Change Date: $Date: 2006/09/11 14:35:32 $
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.

Details on controlling the inflation options are contained in the documentation for the filter. The filter_nml controls what inflation options are used.




OTHER MODULES USED

types_mod
utilities_mod
random_seq_mod
time_manager_mod
ensemble_manager_mod



PUBLIC INTERFACE

use adaptive_inflate_mod, only : update_inflation
 adaptive_inflate_end
 inflate_ens
 output_inflate_diagnostics
 do_obs_inflate
 do_single_ss_inflate
 do_varying_ss_inflate
 adaptive_inflate_init
 adaptive_inflate_type
 get_inflate
 set_inflate
 set_sd
 deterministic_inflate
 do_varying_ss_inflate




PUBLIC COMPONENTS



call update_inflation(inflate_handle,inflate,inflate_sd,prior_mean, prior_var,obs,obs_var,gamma)
 type(adaptive_inflate_type), intent(in)    :: inflate_handle
 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
 

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 inflation on the observation and is the product of the ensemble correlation plus an additional localization factor or group regression factors.

inflate_handle    Handle to object that describes the inflation type and values.
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.


call adaptive_inflate_end(inflate_handle,ens_handle, ss_inflate_index,ss_inflate_index_sd)
 type(adaptive_inflate_type), intent(in)    :: inflate_handle
 type(ensemble_type),         intent(inout) :: ens_handle
 integer,                     intent(in)    :: ss_inflate_index
 integer,                     intent(in)    :: ss_inflate_index_sd
 

Description

Outputs the values of inflation to restart files using the ensemble_manager for state space inflation and file output for observation space inflation. Releases allocated storage in inflate_handle.

inflate_handle    Handle for the details of the inflation being performed.
ens_handle    Handle for ensemble storage that holds values of state space inflation.
ss_inflate_index    Index in ensemble storage copies for state space inflation.
ss_inflate_index_sd    Index in ensemble storage copies for state space inflation standard dev iation.


call inflate_ens(inflate_handle, ens,mean,inflate,var_in)
 type(adaptive_inflate_type),               intent(in)  :: inflate_handle
 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.

inflate_handle    Handle for the details of the inflation being performed.
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(inflate_handle, time)
 type(adaptive_inflate_type), intent(in) :: inflate_handle
 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.

inflate_handle    Handle for the details of the inflation being performed.
time    Time of this diagnostic info.


var = do_obs_inflate(inflate_handle)
 logical,               intent(out) :: do_obs_inflate
 adaptive_inflate_type, intent(in)  :: inflate_handle
 

Description

Returns true if observation space inflation is being done by this handle.

do_obs_inflate    True if obs space inflation is being done by this handle.
inflate_handle    Handle to inflation details.


var = do_varying_ss_inflate(inflate_handle)
 logical,               intent(out) :: do_varying_ss_inflate
 adaptive_inflate_type, intent(in)  :: inflate_handle
 

Description

Returns true if spatially varying state space inflation is being done by this handle.

do_varying_ss_inflate    True if spatially varying state space inflation is being done by this handle.
inflate_handle    Handle to inflation details.


var = do_single_ss_inflate(inflate_handle)
 logical,               intent(out) :: do_single_ss_inflate
 adaptive_inflate_type, intent(in)  :: inflate_handle
 

Description

Returns true if spatially fixed state space inflation is being done by this handle.

do_single_ss_inflate    True if spatially fixed state space inflation is being done by this handle.
inflate_handle    Handle to inflation details.


call adaptive_inflate_init(inflate_handle,inf_flavor,start_from_restart, output_restart,deterministic,in_file_name,out_file_name,diag_file_name,inf_initial, sd_initial,inf_lower_bound,inf_upper_bound,sd_lower_bound,ens_handle,ss_inflate_index,ss_inflate_sd_index)
 type(adaptive_inflate_type), intent(inout) :: inflate_handle
 integer, intent(in)                        :: inf_flavor
 logical, intent(in)                        :: start_from_restart 
 logical, intent(in)                        :: output_restart
 logical, intent(in)                        :: deterministic
 character(len=*), intent(in)               :: in_file_name
 character(len=*), intent(in)               :: out_file_name
 character(len=*), intent(in)               :: diag_file_name
 real(r8), intent(in)                       :: inf_initial
 real(r8), intent(in)                       :: sd_initial
 real(r8), intent(in)                       :: inf_lower_bound
 real(r8), intent(in)                       :: inf_upper_bound
 real(r8), intent(in)                       :: sd_lower_bound
 type(ensemble_type), intent(inout)         :: ens_handle
 integer, intent(in)                        :: ss_inflate_index
 integer, intent(in)                        :: ss_inflate_sd_index
 

Description

Initializes a descriptor of an inflation.

inflate_handle    Handle for the inflation descriptor being initialized.
inf_flavor    Type of inflation, 1=obs_inflate, 2=varying_ss_inflate, 3=single_ss_inflate.
start_from_restart    True if inflation values to be read from restart file.
output_restart    True if an inflatio restart file is to be output.
deterministic    True if deterministic inflation is to be done.
in_file_name    File name from which to read restart.
out_file_name    File name to which to write restart.
diag_file_name    File name to which to write diagnostic output; obs space inflation only .
inf_initial    Initial value of inflation for start_from_restart=.false.
sd_initial    Initial value of inflation standard deviation for start_from_restart=.false.
inf_lower_bound    Lower bound on inflation value.
inf_upper_bound    Upper bound on inflation value.
sd_lower_bound    Lower bound on inflation standard deviation.
ens_handle    Ensemble handle with storage for state space inflation.
ss_inflate_index    Index op copy in ensemble storage for inflation value.
ss_inflate_sd_index    Index of copy in ensemble storage for inflation standard deviation.


var = get_sd(inflate_handle)
 real(r8), intent(out)                   :: get_sd
 type(adaptive_inflate_type), intent(in) :: inflate_handle
 

Description

Returns value of observation space inflation standard deviation.

get_sd    Returns the value of observation space inflation.
inflate_handle    Handle for inflation descriptor.


var = get_inflate(inflate_handle)
 real(r8), intent(out)                   :: get_inflate
 type(adaptive_inflate_type), intent(in) :: inflate_handle
 

Description

Returns value of observation space inflation.

get_inflate    Returns the value of observation space inflation.
inflate_handle    Handle for inflation descriptor.


call set_inflate(inflate_handle,inflate)
 type(adaptive_inflate_type), intent(inout) :: inflate_handle
 real(r8), intent(in)                       :: inflate
 

Description

Set the value of observation space inflation.

inflate_handle    Handle for inflation descriptor.
inflate    Set observation space inflation to this value.


call set_sd(inflate_handle,sd)
 type(adaptive_inflate_type), intent(inout) :: inflate_handle
 real(r8), intent(in)                       :: sd
 

Description

Set the value of observation space inflation standard deviation.

inflate_handle    Handle for inflation descriptor.
sd    Set observation space inflation standard deviation to this value.


var = deterministic_inflate(inflate_handle)
 logical, intent(out)                    :: deterministic_inflate
 type(adaptive_inflate_type), intent(in) :: inflate_handle
 

Description

Returns true if deterministic inflation is being done.

deterministic_inflate    Returns true if deterministic inflation is being done.
inflate_handle    Handle for inflation descriptor.




type adaptive_inflate_type
   private
   integer :: inflation_flavor, obs_diag_unit
   logical :: start_from_restart, output_restart, deterministic
   character(len = 129) :: in_file_name, out_file_name, diag_file_name
   real(r8) :: inflate, sd, sd_lower_bound, inf_lower_bound, inf_upper_bound
   type(random_seq_type) :: ran_seq
end type ensemble_type

Description

Provides a handle for a descriptor of inflation. Includes type of inflation, values controlling it, input and output file names, an output file descriptor for observation space inflation diagnotics, and a random sequence for doing reproducible non-determinstic inflation.

Component Description
inflation_flavor Type of inflation; 1=obs. space, 2=spatially varying, 3=spatially-fixed.
obs_diag_unit Unit descriptor for output diagnostic file.
start_from_restart True if initial inflation to be read from file.
output_restart True if final inflation values to be written to file.
deterministic True if inflation is to be done be deterministic algorithm.
in_file_name File name containing restart.
out_file_name File to contain output restart.
diag_file_name File to hold observation space diagnostics.
inflate Initial value of inflation for all types; current value for obs. space.
sd Initial value of sd for all types; current value for obs. space.
sd_lower_bound Don't allow standard deviation to get smaller than this.
inf_lower_bound Don't let inflation get smaller than this.
inf_upper_bound Don't let inflation get larger than this.
ran_seq Handle to random number sequence to allow reproducing non-deterministic inflate.



The adaptive_inflate module no longer has a namelist. Control has been moved to filter_nml in filter.



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 Cannot have non-determisitic inflation and inf_lower_bound < 1. Algorithm can't work in this cased.
    adaptive_inflate_init ss_inflate_index = ### and ss_inflate_sd_index = ### must be contiguous. Storage for these two must be contiguous in ensemble_manager.
    adaptive_inflate_end ss_inflate_index = ### and ss_inflate_sd_index = ### must be contiguous. Storage for these two must be contiguous in ensemble_manager.



    KNOWN BUGS




    FUTURE PLANS




    PRIVATE COMPONENTS

    Discussion