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

MODULE smoother_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.2 $
Release Name: $Name: $
Change Date: $Date: 2006/09/11 14:35:32 $
Change history: see CVS log (cop-out, I know)

OVERVIEW

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

Implements a fixed lag ensemble smoother as part of the filter. For now, this is done inefficiently with a separate call to filter_assim in assim_tools_mod for each lag.




OTHER MODULES USED

types_mod
mpi_utilities_mod
utilities_mod
ensemble_manager_mod
time_manager_mod
assim_model_mod
assim_tools_mod
obs_sequence_mod
adaptive_inflate_mod



PUBLIC INTERFACE

use smoother_mod, only : smoother_read_restart
 advance_smoother
 smoother_generate_copy_meta_data
 smoother_write_restart
 init_smoother
 do_smoothing
 smoother_mean_spread
 smoother_assim
 filter_state_space_diagnostics
 smoother_state_space_diagnostics
 smoother_end
 smoother_inc_lags

NOTES

Optional namelist interface &lim_obs_seq_nml may be read from file input.nml.




PUBLIC COMPONENTS

fill in text here


call smoother_read_restart(ens_handle,ens_size,model_size,time1 ,init_time_days)
 type(ensemble_type), intent(inout) :: ens_handle
 integer, intent(in)                :: ens_size
 integer, intent(in)                :: model_size
 type(time_type), intent(inout)     :: time1
 integer, intent(in)                :: init_time_days
 

Description

Reads in ensemble of states for all lag estimates from a restart file.

ens_handle    Handle of ensemble manager structure of single state; copied into all lags for startup.
ens_size    Size of the ensemble.
model_size    Size of the model state vector.
time1    Overwrite the time in the restart file with this value if init_time_day s is non-negative.
init_time_days    If non-negative, use time1 instead of time in restart file.


call advance_smoother(ens_handle)
 type(ensemble_type), intent(in) :: ens_handle
 

Description

Advances smoother state estimates at all lags forward in time. This entails copying the most recent smoother state, contained in ens_handle, into the lag 1 smoother state and pushing back all other lags by 1 (i.e. lag 1 becomes lag2, etc.).

ens_handle    Ensemble handle with most recent filtered state.


call smoother_generate_copy_meta_data(output_state_ens_mean,out put_state_ens_spread,num_output_state_members)
 logical, intent(in) :: output_state_ens_mean
 logical, intent(in) :: output_state_ens_spread
 integer, intent(in) :: num_output_state_members
 

Description

Initializes the metadata required for the smoother state space diagnostic files.

output_state_ens_mean    True if smoother state space output should include ensemble mean.
output_state_ens_spread    True if smoother state space output should include ensemble spread.
num_output_state_members    Number of copies of smoother state vector that should be in state space diagnostic output.


call smoother_write_restart(start_copy,end_copy)
 integer, intent(in) :: start_copy
 integer, intent(in) :: end_copy
 

Description

Outputs restart files for all lags of smoother state. Integer arguments specify the start and end global indices of a continguous set of copies that contain the ensemble members.

start_copy    Global index of ensemble copy that starts the actual ensemble members for smoother.
end_copy    Global index of ensemble copy that ends the actual ensemble members for smoother.


call init_smoother(ens_handle,POST_INF_COPY,POST_INF_SD_COPY)
 type(ensemble_type), intent(inout) :: ens_handle
 integer, intent(in)                :: POST_INF_COPY
 integer, intent(in)                :: POST_INF_SD_COPY
 

Description

Initializes the storage needed for a smoother. Also initializes an adaptive inflation type that does NO inflation (not currently supported for smoothers).

ens_handle    An ensemble handle for the filter that contains information about ensemble and model size.
POST_INF_COPY    Global index of ensemble copy that holds posterior state space inflation values.
POST_INF_SD_COPY    Global index of ensemble copy that holds posterior inflation standard deviation values.


var = do_smoothing()
 logical, intent(out) :: do_smoothing
 

Description

Returns true if smoothing is to be done, else false.

do_smoothing    Returns true if smoothing is to be done.


call smoother_mean_spread(ens_size,ENS_MEAN_COPY,ENS_SD_COPY, output_state_ens_mean,output_state_ens_spread)
 integer, intent(in) :: ens_size
 integer, intent(in) :: ENS_MEAN_COPY
 integer, intent(in) :: ENS_SD_COPY
 logical, intent(in) :: output_state_ens_mean
 logical, intent(in) :: output_state_ens_spread
 

Description

Computes the ensemble mean (and spread if required) of all state variables for all lagged ensembles. Spread is only computed if it is required for output.

ens_size    Size of ensemble.
ENS_MEAN_COPY    Global index of copy that stores ensemble mean.
ENS_SD_COPY    Global index of copy that stores ensemble spread.
output_state_ens_mean    True if the ensemble mean is to be output to state diagnostic file.
output_state_ens_spread    True if ensemble spread is to be output to state diagnostic file.


call smoother_assim(obs_ens_handle,seq,keys,ens_size,num_groups ,obs_val_index,ENS_MEAN_COPY,ENS_SD_COPY,PRIOR_INF_COPY,PRIOR_INF_SD_COPY, OBS_KEY_COPY,OBS_GLOBAL_QC_COPY,OBS_PRIOR_MEAN_START,OBS_PRIOR_MEAN_END, OBS_PRIOR_VAR_START,OBS_PRIOR_VAR_END)
 type(ensemble_type), intent(inout)  :: obs_ens_handle
 type(obs_sequence_type), intent(in) :: seq
 integer, dimension(:), intent(in)   :: keys
 integer, intent(in)                 :: ens_size
 integer, intent(in)                 :: num_groups
 integer, intent(in)                 :: obs_val_index
 integer, intent(in)                 :: ENS_MEAN_COPY
 integer, intent(in)                 :: ENS_SD_COPY
 integer, intent(in)                 :: PRIOR_INF_COPY
 integer, intent(in)                 :: PRIOR_INF_SD_COPY
 integer, intent(in)                 :: OBS_KEY_COPY
 integer, intent(in)                 :: OBS_GLOBAL_QC_COPY
 integer, intent(in)                 :: OBS_PRIOR_MEAN_START
 integer, intent(in)                 :: OBS_PRIOR_MEAN_END
 integer, intent(in)                 :: OBS_PRIOR_VAR_START
 integer, intent(in)                 :: OBS_PRIOR_VAR_END
 

Description

Does assimilation of a set of observations for each smoother lag.

obs_ens_handle    Handle for ensemble manager holding prior estimates of observations.
seq    Observation sequence being assimilated.
keys    A one dimensional array containing indices in seq of observations to as similate at current time.
ens_size    Ensemble size.
num_groups    Number of groups in filter.
obs_val_index    Integer index of copy of data in seq that contains the observed value from instruments.
ENS_MEAN_COPY    Global index in smoother's state ensemble that holds ensemble mean.
ENS_SD_COPY    Global index in smoother's state ensemble that holds ensemble standard deviation.
PRIOR_INF_COPY    Global index in obs_ens_handle that holds inflation values (not used for smoother).
PRIOR_INF_SD_COPY    Global index in obs_ens_handle that holds inflation sd values (not used for smoother).
OBS_KEY_COPY    Global index in obs_ens_handle that holds the key for the observation.
OBS_GLOBAL_QC_COPY    Global index in obs_ens_handle that holds the quality control value.
OBS_PRIOR_MEAN_START    Global index in obs_ens_handle that holds the first group's prior mean.
OBS_PRIOR_MEAN_END    Global index in obs_ens_handle that holds the last group's prior mean.
OBS_PRIOR_VAR_START    Global index in obs_ens_handle that holds the first group's prior variance.
OBS_PRIOR_VAR_END    Global index in obs_ens_handle that holds the last group's prior variance.


call filter_state_space_diagnostics(out_unit,ens_handle, model_size,output_state_ens_mean,output_state_ens_spread,num_output_state_members, output_state_mean_index,output_state_spread_index,ENS_MEAN_COPY,ENS_SD_COPY,inflate, INF_COPY,INF_SD_COPY)
 type(netcdf_file_type), intent(inout)   :: out_unit
 type(ensemble_type), intent(inout)      :: ens_handle
 integer, intent(in)                     :: model_size
 logical, intent(in)                     :: output_state_ens_mean 
 logical, intent(in)                     :: output_state_ens_spread
 integer, intent(in)                     :: num_output_state_members
 integer, intent(in)                     :: output_state_mean_index
 integer, intent(in)                     :: output_state_spread_index
 integer, intent(in)                     :: ENS_MEAN_COPY
 integer, intent(in)                     :: ENS_SD_COPY
 type(adaptive_inflate_type), intent(in) :: inflate
 integer, intent(in)                     :: INF_COPY
 integer, intent(in)                     :: INF_SD_COPY
 

Description

Writes state space diagnostic values including ensemble members, mean and spread, and inflation mean and spread to a netcdf file.

out_unit    Descriptor for the netcdf file being written.
ens_handle    Ensemble handle whose state space values are to be written.
model_size    Size of the model state vector.
output_state_ens_mean    True if the ensemble mean values are to be output.
output_state_ens_spread    True if the ensemble spread values are to be output.
num_output_state_members    Number of individual state members to be output.
output_state_mean_index    Index in netcdf file for ensemble mean.
output_state_spread_index    Index in netcdf file for ensemble spread.
ENS_MEAN_COPY    Global index in ens_handle for ensemble mean.
ENS_SD_COPY    Global index in ens_handle for ensemble spread.
inflate    Contains description and values of state space inflation.
INF_COPY    Global index in ens_handle of inflation values.
INF_SD_COPY    Global index in ens_handle of inflation standard deviation values.


call smoother_state_space_diagnostics(model_size, output_state_ens_mean,output_state_ens_spread,num_output_state_members, ENS_MEAN_COPY,ENS_SD_COPY,POST_INF_COPY,POST_INF_SD_COPY)
 integer, intent(in) :: model_size
 logical, intent(in) :: output_state_ens_mean
 logical, intent(in) :: output_state_ens_spread
 integer, intent(in) :: num_output_state_members
 integer, intent(in) :: ENS_MEAN_COPY
 integer, intent(in) :: ENS_SD_COPY
 integer, intent(in) :: POST_INF_COPY
 integer, intent(in) :: POST_INF_SD_COPY
 

Description

Outputs state space diagnostics files for all smoother lags.

model_size    Size of the model state vector.
output_state_ens_mean    True if the ensemble mean is to be output in state space diagnostics file.
output_state_ens_spread    True if the ensemble spread is to be output in the state space diagnostics file.
num_output_state_members    Number of state copies to be output in the state space diagnostics file.
ENS_MEAN_COPY    Global index of the ensemble mean in the lag smoother ensemble handles.
ENS_SD_COPY    Global index of the ensemble spread in the lag smoother ensemble handles.
POST_INF_COPY    Global index of the inflation value in the lag smoother ensemble handles (not currently used).
POST_INF_SD_COPY    Global index of the inflation spread in the lag smoother ensemble handles (not currently used).


call smoother_end()
 

Description

Releases storage allocated for smoother.


call smoother_inc_lags()
 

Description

Increments the number of lags that are in use for smoother. Used when a smoother is being started up and there have not been enough times to propagate the state to all requested lags.




We adhere to the F90 standard of starting a namelist with an ampersand '&' and terminating with a slash '/'.

 namelist / smoother_nml / 
 num_lags,start_from_restart,output_restart,restart_in_file_name,
restart_out_file_name


 

Discussion

This namelist is read in a file called input.nml

Contents Type Description
num_lags integer Number of smoother lags; < 1 means no smoother. Default: 0
start_from_restart logical True if smoother states are to come from restart file. False if they are to be spun up from scratch. Default: .false.
output_restart logical True if restart file is to be written, else false. Default:.false.
restart_in_file_name character(len=129) File name from which to read restarts, lag extensions get added. Default: smoother_ics
restart_out_file_name character(len=129) File name to which to write smoother restarts, lag extensions get added. Default: smoother_restart




FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
smoother_generate_copy_meta_data output metadata in smoother needs ensemble size < 10000, not ### Can't output more than 9999 copies.



KNOWN BUGS




FUTURE PLANS




PRIVATE COMPONENTS

Discussion