Contact: | Jeff Anderson |
Reviewers: | |
Revision: | $Revision: 1.1 $ |
Release Name: | $Name: post_iceland $ |
Change Date: | $Date: 2006/06/15 22:42:05 $ |
Change history: | see CVS log |
types_mod utilities_mod sort_mod random_seq_mod obs_sequence_mod obs_def_mod cov_cutoff_mod obs_model_mod reg_factor_mod location_mod (model dependent choice) ensemble_manager_mod
use assim_tools_smoother_mod, only : | assim_tools_init |
obs_increment (Now Private) | |
update_from_obs_inc (Now Private) | |
filter_assim | |
async_assim_region |
Optional namelist interface &assim_tools_smoother_nml may be read from file input.nml.
Initialization routine for assim_tools. This must be called before other public interfaces can be used.
real(r8), intent(in), dimension(ens_size) :: ens_in integer, intent(in) :: ens_size real(r8), intent(in) :: obs real(r8), intent(in) :: obs_var real(r8), intent(out), dimension(ens_size) :: obs_inc
Does a scalar update of a prior ensemble in observation space and computes the increments for each prior ensemble member. Four different ensemble filter algorithms are selectable through a namelist arguement. The EAKF variant also includes a capability to do an empirical systematic error correction. Obs_increment also implements the adaptive systematic error correction algorithm using observation space covariance inflation. A number of options for this algorithm are selected through namelist parameters.
ens_in | The prior ensemble expected values for this observation. |
ens_size | Size of the prior ensemble. |
obs | The observed value (from the instrument). |
obs_var | The observational error variance (from the observing system). |
obs_inc | The increments computed for the prior ensemble. |
real(r8), intent(in), dimension(ens_size) :: obs real(r8), intent(in), dimension(ens_size) :: obs_inc real(r8), intent(in), dimension(ens_size) :: state integer, intent(in) :: ens_size real(r8), intent(out), dimension(ens_size) :: state_inc real(r8), intent(out) :: reg_coef real(r8), OPTIONAL, intent(out) :: correl_out
Given the prior joint distribution of an observation and a state variable along with computed increments for the observation ensemble members, uses a linear regression to compute increments for the state variable ensemble. An optional algorithm to do prior corrections of spread reduction is also available for use with the EAKF variant of the filter. The increments and the regression coefficient are returned and optionally the correlation between the state and observation priors.
obs | The prior ensemble expected values for this observation. |
obs_inc | The observation increments for the ensemble computed by obs_increment. |
state | The prior ensemble values for a state variable. |
ens_size | Size of the ensemble. |
state_inc | The increments computed for the state variable ensemble. |
reg_coef | The regression coefficient between the observation and state variable ensembles. |
correl_out | Optional sample correlation between state and prior. |
type(ensemble_type), intent(in) :: ens_handle real(r8), dimension(ens_size, num_obs_in_set), intent(in) :: ens_obs logical, dimension(num_obs_in_set), intent(in) :: compute_obs_in integer, intent(in) :: ens_size integer, intent(in) :: model_size integer, intent(in) :: num_obs_in_set integer, intent(in) :: num_groups type(obs_sequence_type), intent(inout) :: seq integer, dimension(num_obs_in_set), intent(in) :: keys real(r8), intent(in) :: cutoff logical, intent(in) :: save_reg_series integer, intent(in) :: reg_series_unit character(len=*), intent(in) :: obs_seq_in_name integer, intent(in) :: lag
Entry subroutine to do an assimilation for a given observation set. Calls are made to internal subroutine filter_assim_region to do actual assimilation for each domain as requested by the num_domains namelist parameter. This public subroutine can either call filter_assim_region directly or create appropriate files for each domain and use the shell to execute programs to do the regions (controlled by do_parallel option in namelist). The current parallel assimilation algorithm does not recompute any observations but simply updates the prior distribution each time another observation is assimilated. For single domain use, the compute_obs_in logical array indicates if there are state variables that cannot (or should not) be recomputed during the sequential assimilation. Support for the reg_series output is very limited with this release and is confined to low-order models. Note that modifications have been made to update an array of ensemble handles for a given lag to implement the smoother.
ens_handle | Identifies ensemble (see ensemble_manager_mod) |
ens_obs | Ensemble prior values for observations |
compute_obs_in | True if corresponding observation can be recomputed here |
ens_size | Ensemble size |
model_size | Model state vector length |
num_obs_in_set | Number of observations to be assimilated |
num_groups | Number of groups for filter |
seq | Observation sequence |
keys | Indices of the current observations in seq |
cutoff | Localization factor (see update_from_obs_inc) |
save_reg_series | True to save regression stats (low-order only) |
reg_series_unit | Open to regression stats file if needed |
obs_seq_in_name | Obs sequence is written here if shell driven multiple domains |
character(len=*), intent(in) :: in_file_name character(len=*), intent(in) :: out_file_name integer, intent(in) :: lag
This is a subroutine designed to allow calls to filter_assim_region to be handled by separate processes through the shell. Instead of having a direct call from filter_assim, filter_assim writes out all the arguments for filter_assim_region for a given region to a file. The shell then starts a program, assim_region, which calls async_assim_region with the appropriate file names. The arguments are obtained by the file by async_assim_region and then a call is made to subroutine filter_assim_region. At completion, the output arguments are written to out_file_name. Note slight modification has been made to implement the smoother.
in_file_name | File where input required for filter_assim_region is found |
out_file_name | File where output from filter_assim_region is to be put |
We adhere to the F90 standard of starting a namelist with an ampersand '&' and terminating with a slash '/'.
namelist / assim_tools_smoother_nml / & filter_kind, cutoff, sort_obs_inc, & cov_inflate, cov_inflate_sd, sd_lower_bound, deterministic_cov_inflate, & start_from_assim_restart, assim_restart_in_file_name, assim_restart_out_file_name, & do_parallel, num_domains, parallel_command, & spread_restoration, cov_inflate_upper_bound, internal_outlier_threshold
This namelist is read in a file called input.nml
Contents | Type | Description |
---|---|---|
filter_kind | integer | Selects the variant of filter to be used. 1=EAKF, 2=ENKF, 3=Kernel filter, 4=particle filter. Default: 1. |
cutoff | real(r8) | Cutoff controls a distance dependent weight that modulates the impact of an observation on a state variable. The units depend both on the location module being used and on the covariance cutoff module options selected. Default is 0.2. |
sort_obs_inc | logical | If true, the final increments from obs_increment are sorted so that the mean increment value is as small as possible. This minimizes regression errors when non-deterministic filter or error correction algorithms are applied. Default: false. |
cov_inflate | real(r8) | Value of the deterministic, state space covariance inflation. Default: -1.0 |
cov_inflate_sd | real(r8) | Value of adaptive covariance inflate standard deviation. Default: 0.05. |
sd_lower_bound | real(r8) | Lower bound of adaptive inflation standard deviation. Default: 0.05. |
deterministic_cov_inflate | logical | If true, use determinstic spatial covariance inflation. Default: .true. |
start_from_assim_restart | logical | If true, start from assim_restart. Default: .false. |
assim_restart_in_file_name | character(len=129) | File name for assim restart. Default: 'assim_tools_ics' |
assim_restart_out_file_name | character(len=129) | File name for assim restart output file. Default: 'assim_tools_restart' |
do_parallel | integer | Execution control: 0 = single executable; 2 = parallel_command; 3 = use filter_server Default: 0 |
num_domains | integer | Use this many subdomains; assimilate each independently Default: 1 |
parallel_command | character(len=129) | Command to be executed for option 2. Default: ./assim_filter.csh |
spread_restoration | logical | True turns on algorithm to restore amount of spread that would be expected to be lost if underlying obs/state variable correlation were really 0. Default: false |
internal_outlier_threshold | real | Like the global outlier threshold in the filter, except it is applied during the sequential update phase. If the difference between the prior ensemble mean and the observed value is more than this many standard deviations of the expected value, the observation is not used. It will still appear in the diagnostic output since this is generated in the filter before the sequential phase begins. Default: -1.0 |
Routine | Message | Comment |
---|---|---|
assim_tools_init | do parallel option # not supported | Only the following are currently supported: 0; assimilation not parallel 2; assimilation parallel, use parallel_command from namelist 3; assimilation parallel, separate script runs assimilation |
obs_increment | Illegal value of filter_kind in assim_tools namelist [1-4 OK] | Only 1-4 currently supported. |
obs_increment_eakf obs_increment_ran_kf obs_increment_det_kf |
Both obs_var and prior_var are zero. This is inconsistent | Product of two delta functions doesn't work. |
filter_assim | Use less than 10000 domains. | Need to modify code for more than 10000 domains. |
filter_assim | Did not find observation copy with metadata "observation" | In obs_sequence file, need to find copy that is observations. |
filter_assim | Having more domains than state variables does not make sense | It doesn't. |
The current version of the systematic error correction algorithm does not work in a logical fashion with the parallel region assimilation feature.
type location_type private real(r8) :: x end type location_type