MODULE adaptive_inflate_mod

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 observation space, consistent with previous DART releases. It can provide spatially-constant, time-varying adaptive inflation. It can provide spatially-varying, time-varying adaptive inflation and it can provide temporally-varying observation space inflation. And finally, it can provide adaptive damped inflation, which decreases inflation through time when observation density varies. Diagnostic output and restart files are available. Several papers on the NSF NCAR DART website 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.

Inflation flavor 3 (spatially-constant state space) reads and writes a restart file that is the full size of the state vector, however it takes the first value in the array and replicates that throughout the array. This allows one to switch between flavors 2 and 3. Going from inflation flavor 3 to 2 the initial value for all items in the state vector will be a constant value and will then start to adapt. Going from inflation flavor 2 to 3 whatever value is in the array at index 1 will be replicated and used for the entire rest of the state vector items.

Other modules used

types_mod
utilities_mod
random_seq_mod
time_manager_mod
ensemble_manager_mod

Public interfaces

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
	set_sd
	deterministic_inflate

A note about documentation style. Optional arguments are enclosed in brackets [like this].

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

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_sd_index)

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_sd_index

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_sd_index`	Index in ensemble storage copies for state space inflation standard deviation.

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

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

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

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

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

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, mean_from_restart, sd_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, label)

type(adaptive_inflate_type), intent(inout) :: inflate_handle
integer, intent(in)                        :: inf_flavor
logical, intent(in)                        :: mean_from_restart
logical, intent(in)                        :: sd_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
character(len=*), intent(in)               :: label

Initializes a descriptor of an inflation object.

`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.
`mean_from_restart`	True if inflation mean values to be read from restart file.
`sd_from_restart`	True if inflation standard deviation values to be read from restart file.
`output_restart`	True if an inflation 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.
`label`	Character label to be used in diagnostic output (e.g. ‘Prior’, ‘Posterior’).

var = get_sd(inflate_handle)

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

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

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

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

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

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
   integer :: obs_diag_unit
   logical :: start_from_restart
   logical :: output_restart
   logical :: deterministic
   character(len = 129) :: in_file_name
   character(len = 129) :: out_file_name
   character(len = 129) :: diag_file_name
   real(r8) :: inflate
   real(r8) :: sd
   real(r8) :: sd_lower_bound
   real(r8) :: inf_lower_bound
   real(r8) :: inf_upper_bound
   type(random_seq_type) :: ran_seq
end type adaptive_inflate_type

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. There are 2 instances of this type, one for Prior and one for Posterior inflation.

Component	Description
inflation_flavor	Type of inflation; 0=none, 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.

Namelist

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

Files

Three files are opened from this module, but all names are passed in from the filter_nml now, and there are 2 values for each name: one for the prior and one for the posterior inflation.

inf_in_file_name Mean and standard deviation values read in restart file format.
inf_out_file_name Mean and standard deviation values written in restart file format.
inf_diag_file_name Contains diagnostic history of inflation values for obs space and spatially-fixed state space inflation. Diagnostics for spatially-varying state space inflation are extra fields on the Posterior and Prior diagnostic netcdf files created in filter.f90.

References

Anderson, J. L., 2007: An adaptive covariance inflation error correction algorithm for ensemble filters. Tellus A, 59, 210-224. doi: 10.1111/j.1600-0870.2006.00216.x
Anderson, J. L., 2009: Spatially and temporally varying adaptive covariance inflation for ensemble filters. Tellus A, 61, 72-83. doi: 10.1111/j.1600-0870.2008.00361.x

Private components

no discussion