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

PROGRAM smoother

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.1 $
Release Name: $Name: post_iceland $
Change Date: $Date: 2006/06/15 22:52:26 $
Change history: see CVS log

OVERVIEW

Main program for driving smoother calculations using ensemble filter update algorithms available in DART. This program provides a number of options that are driven from its namelist. The namelist options are nearly identical to the filter namelist options. Additional namelist parameters have been added to handle features specific to the smoother, specifically the restart capabilities for the smoother. The number of assimilation steps to be done are controlled by the input observation sequence and by the time-stepping capabilities of the model being used in the assimilation. This documentation was created for the I-release of DART.

Quality control flags for observations are set in smoother. The quality control flags work in a manner identical to filter. If forward observation operators cannot be computed for any ensemble member, the quality control flag for the observation is incremented by 1000 for the prior and 100000 for a violation when computing posterior diagnostics.

The smoother also performs an outlier test on observations which set the quality control flags (see outlier_threshold in namelist). Once again, this feature is identical to the filter.

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




OTHER MODULES USED (note: the key difference with the filter is assim_tools_smoother_mod is used - assim_tools_smoother_mod contains alterations to subroutines filter_assim_region, filter_assim and asyn_assim_region which allow the smoother to run)

types_mod
obs_sequence_mod
obs_def_mod
time_manager_mod
utilities_mod
assim_model_mod
random_seq_mod
assim_tools_smoother_mod
obs_model_mod
ensemble_manager



NAMELIST

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

namelist / smoother_nml /  &
      async, adv_ens_command, ens_size, cov_inflate, 
      start_from_smoother_restart, output_smoother_restart,
      smoother_restart_in_base, smoother_restart_out_base,
      start_from_restart, restart_in_file_name,
      obs_sequence_in_name, obs_sequence_out_name,  
      init_time_days, init_time_seconds, 
      output_state_ens_mean, output_state_ens_spread, 
      output_obs_ens_mean,   output_obs_ens_spread, 
      num_output_state_members, num_output_obs_members, 
      output_interval,  num_groups, outlier_threshold, lag 

Discussion

This namelist is read in a file called input.nml

Contents Type Description
async integer Controls whether models are advanced via a subroutine call or by writing initial condition files for ensemble members to disk and having shellscript advance the model.
0 = advance by subroutine. Default
1 = shell advance using shell script piped to filter.
2 = advance by F90 calls to shell to advance model.
3 = model advanced when signalled by a signal file, which is is written out by filter (used for running filter on a compute node separate from the model advances).
ens_size integer Number of ensemble members to be integrated. Default is 20.
cov_inflate real(r8) Covariance inflation factor applied to prior estimate before each assimilation step. Default is 1.0 (no inflation).
start_from_smoother_restart logical Should initial ensemble states come from (a) restart file(s). Default is .false. Please note that if this option is .false., the restart is then controlled by the logical start_from_restart. If start_from_restart is true, then we start from a filtered state in filename restart_in_file_name, otherwise, a cold initialization is used in the same manner as filter.
output_smoother_restart logical Controls whether restart files for the lagged smoother states are created or not. Note that one restart file for each lag from 0 to lag is created when this logical is .true.
smoother_restart_in_base character(len=129) The character `tag' associated with the smoother restart files. Suppose the character specified is `s'. If one is running at lag = 5 smoother, then the program requires restart files s000 (lag 0), s001, s002, s003, s004 and s005 to be available. If not present, program failure will occur.
smoother_restart_out_base character(len=129) The character `tag' associated with the smoother restart files that one wants to output. Suppose the character specified is `s'. If one is running at lag = 5 smoother, then the program will output restart files s000 (lag 0), s001, s002, s003, s004 and s005 to be available for the subsequent run of the smoother.
start_from_restart logical First of all, this logical is only of consequence if start_from_smoother_restart = .false.. When this is the case, the smoother starts without any previously saved lagged smoother states. When start_from_smoother_restart = .false., the lagged states are just set to the filtered state initially. Once the smoother runs for sufficiently long, valid smoother states are generated. Now, when start_from_smoother_restart = .false., start_from_restart controls *which* filtered state we start from. If start_from_restart = .true. we start by loading up the initial conditions in filename restart_in_file_name, otherwise we start from a cold initialization as in the filter program.
restart_in_file_name character(len=129) If start_from_restart = .true. *and* start_from_smoother_restart = .false. we start from the filter initial conditions specified by this filename. File name (root) for a file(s) containing restart state for all ensemble members. Multiple files have extensions ".####", where #### is a 4 digit number representing the ensemble member. Default is 'filter_ics'.
obs_sequence_in_name character(len=129) File name that contains an observation sequence file. Default is 'obs_seq.out'.
obs_sequence_out_name character(len=129) Uknown purpose. Ask JLA. Default is 'obs_seq.final'.
init_time_days integer Initial time of model (time is in days and seconds; see time_manager. If init_time_days and init_time_seconds are less than 0, the initial time comes from the time in the restart file. Default value is 0.
init_time_seconds integer Initial time of model in seconds. Default is 0.
output_state_ens_mean logical Output ensemble mean in state diagnostic files.
output_state_ens_spread logical Output ensemble spread in state diagnostic files.
output_obs_ens_mean logical Output ensemble mean in observation output file.
output_obs_ens_spread logical Output ensemble spread in observation output file.
num_output_state_members integer This number of ensemble members is output to the state diagnostics file. If this is less than the total number of ensemble members the first subset is output. Default is 0.
num_output_obs_members integer This number of ensemble members is output to the observation output file. If this is less than the total number of ensemble members the first subset is output. Default is 0.
output_interval integer The frequency with which output state diagnostics are written. Units are in assimilation times. Default value is 1 meaning output is written at every observation time.
num_groups integer Number of groups for hierarchical group filter. Should be a divisor of the ensemble size. Default is 1.
outlier_threshold real(r8) Discard all observations where the prior ensemble mean and the observation value differ by more than this many of the expected standard deviations. A quality control flag value is incremented by 100 if this check is violated for the prior ensemble mean and by 400 it this check is violated for the posterior ensemble mean. Negative value means no quality control of this kind is performed. Default value is -1.0
lag integer Integer indicating up to how many lags one wants to compute. Default value is 0 (no lag calculations). Lag can not exceed 1000.



FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
filter_generate_copy_meta_data output metadata in filter needs ensemble size < 10000 Ensemble sizes greater than require modifications to output ensemble code.
filter_get_obs_info Did not find observation copy with metadata "observations" None of the copies of data in the obs_seq file is an "observation"



KNOWN BUGS




FUTURE PLANS

Possibilities: add in parallel capability. As it stands, the smoother is not compatible with the parallel option.

Discussion

Please see a brief write up written by Shree Khare briefly explaining how the smoother output is formatted and its meaning. There is text and figures contained in the files smootherdatadartexplain.ps (or pdf) and smootherdatadart.ps (or pdf) can be found in the ~/DART/smoother directory.