MODULE adaptive_inflate_mod

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: adaptive_inflate_mod.html 6380 2013-08-05 23:47:11Z nancy $

INTERFACES / NAMELIST / FILES / REFERENCES / ERRORS / PLANS / PRIVATE COMPONENTS / TERMS OF USE

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 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.

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.

[top]

OTHER MODULES USED

types_mod
utilities_mod
random_seq_mod
time_manager_mod
ensemble_manager_mod
[top]

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.

[top]

NAMELIST

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

[top]

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.

[top]

REFERENCES

[top]

ERROR CODES and CONDITIONS

RoutineMessageComment
adaptive_inflate_init Cannot have non-deterministic inflation and inf_lower_bound < 1. Algorithm can't work in this case.
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

none at this time

[top]

FUTURE PLANS

none at this time

[top]

PRIVATE COMPONENTS

no discussion

[top]

Terms of Use

DART software - Copyright 2004 - 2013 UCAR.
This open source software is provided by UCAR, "as is",
without charge, subject to all terms of use at
http://www.image.ucar.edu/DAReS/DART/DART_download

Contact: DART core group
Revision: $Revision: 6380 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/classic/adaptive_inflate/adaptive_inflate_mod.html $
Change Date: $Date: 2013-08-05 17:47:11 -0600 (Mon, 05 Aug 2013) $
Change history:  try "svn log" or "svn diff"