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

input.nml
inflate_ics: Default name for file containing initial values of inflation mean and standard deviation.
inflate_restart: Default name for file that outputs final values of inflation mean and standard deviation.
inflate_diag: 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, 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

Routine Message Comment

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

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.

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.

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

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

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

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

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.

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

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

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

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

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.

Routine	Message	Comment
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.