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

MODULE smoother_mod

Contact: Jeff Anderson
Revision: $Revision: 2859 $
Source: $URL: http://subversion.ucar.edu/DAReS/DART/trunk/smoother/smoother_mod.html $
Change Date: $Date: 2007-04-12 11:10:54 -0600 (Thu, 12 Apr 2007) $
Change history: try "svn log" or "svn diff"

OVERVIEW

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

To enable the smoother, set the number of lags (num_lags) to something larger than 0 in the smoother_nml section of your input.nml file and run filter as before.

&smoother_nml
   num_lags              = 10,
   start_from_restart    = .false.,
   output_restart        = .true.,
   restart_in_file_name  = "smoother_ics",
   restart_out_file_name = "smoother_restart"  /

In the low order models, 10 is a plausible number.

In addition to generating Prior_Diag.nc and Posterior_Diag.nc files, files of the form Lag_NNNNN_Diag.nc will be generated. Each of these has N fewer timesteps than the lag=0 run, starting at the same time but ending N timesteps sooner. The obs_seq.final file and the Prior_Diag.nc and Posterior_Diag.nc files will be the same as the non-lagged version; the new output will be in each of the Lag_NNNNN_Diag.nc files.

Don't overlook the example below.




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_gen_copy_meta_data
 smoother_write_restart
 init_smoother
 do_smoothing
 smoother_mean_spread
 smoother_assim
 filter_state_space_diagnostics
 smoother_ss_diagnostics
 smoother_end
 smoother_inc_lags

NOTES

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




PUBLIC COMPONENTS

The following routines are public:


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_days 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_gen_copy_meta_data(num_output_state_members, output_inflation)
 integer, intent(in) :: num_output_state_members
 logical, intent(in) :: output_inflation
 

Description

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

num_output_state_members    Number of copies of smoother state vector that should be in state space diagnostic output.
output_inflation    True if smoother state space output should include inflation values.


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, num_output_state_members, output_state_mean_index, output_state_spread_index, output_inflation, temp_ens, 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
 integer, intent(in)                     :: num_output_state_members
 integer, intent(in)                     :: output_state_mean_index
 integer, intent(in)                     :: output_state_spread_index
 logical, intent(in)                     :: output_inflation
 real(r8), intent(out)                   :: temp_ens(model_size)
 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.
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.
output_inflation    True if the inflation values are to be output. Default is .TRUE.
temp_ens    Storage passed in to avoid having to allocate extra space.
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_ss_diagnostics(model_size, num_output_state_members, output_inflation, temp_ens, ENS_MEAN_COPY, ENS_SD_COPY, POST_INF_COPY, POST_INF_SD_COPY)
 integer, intent(in)   :: model_size
 integer, intent(in)   :: num_output_state_members
 logical, intent(in)   :: output_inflation
 real(r8), intent(out) :: temp_ens(model_size)
 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.
num_output_state_members    Number of state copies to be output in the state space diagnostics file.
output_inflation    True if the inflation values are to be output. Default is .TRUE.
temp_ens    Storage passed in to avoid having to allocate extra space.
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.




NAMELIST

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_gen_copy_meta_data output metadata in smoother needs ensemble size < 10000, not ### Can't output more than 9999 copies.



KNOWN BUGS




EXAMPLE

If you have a True_State.nc file and want to use the plot_total_err matlab function to plot the error, you must do the following steps to generate analogs of lagged True_State.nc files to use as a comparison. (The logic is not currently implemented in the matlab scripts to be able to compare netCDF files with unequal time coordinates.)

Make N separate versions of the True_State.nc with the last N timesteps removed. Using the netCDF NCO operator program 'ncks' is one way. If the True_State.nc file has 1000 time steps, then this command removes the last one:

ncks -d time,0,998 True_State.nc True_Lag01.nc

Note that the first time is at index 0, so the last timestep is index 999 in the full file, and 998 in the truncated file. Repeat this step for all N lags. Here are NCO commands to generate 10 truth files for num_lags = 10, 1000 time steps in True_State.nc:

ncks -d time,0,998 True_State.nc True_Lag01.nc
ncks -d time,0,997 True_State.nc True_Lag02.nc
ncks -d time,0,996 True_State.nc True_Lag03.nc
ncks -d time,0,995 True_State.nc True_Lag04.nc
ncks -d time,0,994 True_State.nc True_Lag05.nc
ncks -d time,0,993 True_State.nc True_Lag06.nc
ncks -d time,0,992 True_State.nc True_Lag07.nc
ncks -d time,0,991 True_State.nc True_Lag08.nc
ncks -d time,0,990 True_State.nc True_Lag09.nc
ncks -d time,0,989 True_State.nc True_Lag10.nc

Here is an example matlab session which plots the lag=0 results and then odd numbered lags from 1 to 9. It uses the plot_total_err function from the $DART/matlab directory:

datadir    = '.';
truth_file = fullfile(datadir,'True_State.nc');
diagn_file = fullfile(datadir,'Prior_Diag.nc');
plot_total_err
reply = input('original data.  hit enter to continue ');

truth_file = fullfile(datadir,'True_Lag01.nc');
diagn_file = fullfile(datadir,'Lag_00001_Diag.nc');
plot_total_err
reply = input('Lag 01.  hit enter to continue ');

truth_file = fullfile(datadir,'True_Lag03.nc');
diagn_file = fullfile(datadir,'Lag_00003_Diag.nc');
plot_total_err
reply = input('Lag 03.  hit enter to continue ');

truth_file = fullfile(datadir,'True_Lag05.nc');
diagn_file = fullfile(datadir,'Lag_00005_Diag.nc');
plot_total_err
reply = input('Lag 05.  hit enter to continue ');

truth_file = fullfile(datadir,'True_Lag07.nc');
diagn_file = fullfile(datadir,'Lag_00007_Diag.nc');
plot_total_err
reply = input('Lag 07.  hit enter to continue ');

truth_file = fullfile(datadir,'True_Lag09.nc');
diagn_file = fullfile(datadir,'Lag_00009_Diag.nc');
plot_total_err
reply = input('Lag 09.  hit enter to continue ');




PRIVATE COMPONENTS

Discussion