Jump to DART Documentation Main Index 
Main program for driving ensemble filter assimilations.
filter is a Fortran 90 program, and provides a large number of options for controlling execution behavior and parameter configuration that are driven from its namelist. See the namelist section below for more details. The number of assimilation steps to be done is controlled by the input observation sequence and by the timestepping capabilities of the model being used in the assimilation.
This overview includes these subsections:
See the DART web site for more documentation, including a discussion of the capabilities of the assimilation system, a diagram of the entire execution cycle, the options and features.
The basic execution loop is:
The time of the observations in the input observation sequence file controls the length of execution of filter.
For large, parallel models, the execution loop is usually wrapped in an external script which does these additional steps:
For large models filter is almost always compiled to be a parallel MPI program, and most large models are themselves a parallel program using OpenMP, MPI, or both. MPI programs usually cannot start other MPI programs, so the external script submits both the filter job and the N model advances to a batch system so all run as independent parallel jobs.
The same source code is used for all applications of filter. The code specific to the types of observations and the interface code for the computational model is configured at compile time. The DART directory structure is arranged slightly differently than usual in that the main code is spread across a dozen directories at the top level, e.g. the filter source code is in DART/filter/filter.f90. Each model has a separate directory under DART/models, and under each model is a work directory where the code is compiled and can be run for testing. Generally when a fullsize experiment is done the executables are copied to a different location  e.g. scratch space on a large filesystem  since the data files for 10s to 100s of copies of a model can get very large.
The different types of assimilation algorithms (EAKF, ENKF, Kernel filter, Particle filter, etc.) are determined by the &assim_tools_nml:filter_kind entry, described in assim_tools_mod.html. Despite having 'filter' in the name, they are assimilation algorithms and so are implemented in assim_tools_mod.f90.
Running a successful assimilation takes careful diagnostic work and experiment iterations to find the best settings for your specific case. The basic Kalman filter can be coded in only a handful of lines; the hard work is making the right choices to compensate for sampling errors, model bias, observation error, lack of model divergence, variations in observation density in space and time, random correlations, etc. There are tools built into DART to deal with most of these problems but it takes careful work to apply them correctly.
If you are adding a new model or a new observation type, we suggest you assimilate exactly one observation, with no model advance, with inflation turned off, with a large cutoff, and with the outlier threshold off (see below for how to set these namelist items). Run an assimilation. Look at the obs_seq.final file to see what the forward operator computed. Use ncdiff to difference the Prior and Posterior Diag NetCDF files and look at the changes (the "innovations") in the various model fields. Is it in the right location for that observation? Does it have a reasonable value?
Then assimilate a group of observations and check the results carefully. Run the observation diagnostics and look at the total error and spread. Look carefully at the number of observations being assimilated compared to how many are available. Assimilations that are not working can give good looking statistics if they reject all but the few observations that happen to match the current state. The errors should grow as the model advances and then shrink when new observations are assimilated, so a timeplot of the RMSE should show a sawtooth pattern. The initial error might be large but it should decrease and then reach a roughly stable level. The spread should remain constant, at a value around the expected observation error level. If the spread is too small that is ok for the baseline case; several of the DART facilities described below are intended to compensate for ensemble members getting too close to each other. Once you believe you have a working assimilation case, this will be your baseline case. Then one by one enable or tune each of the items below, checking each time to see what is the effect on the results.
Suggestions for the most common namelist settings and features built into DART for running a successful assimilation include:
In practice, ensemble sizes between 20 and 100 seem to work best. Fewer than 2030 members leads to statistical errors which are too large. More than 100 members takes longer to run with very little return, and eventually the results get worse again. Often the limit on the number of members is based on the size of the model since you have to run N copies of the model each time you move forward in time. If you can, start with 5060 members and then experiment with fewer or more once you have a set of baseline results to compare it with. The namelist setting for ensemble size is &filter_nml :: ens_size
There are two main advantages to using localization. One is it avoids an observation impacting unrelated state variables because of spurious corelations. The other is that especially for large models it improves runtime performance because only points within the localization radius need to be considered. Because of the way the parallelization was implemented in DART, localization was easy to add and using it usually results in a very large performance gain. See here for a discussion of localizationrelated namelist items.
Since the filter is being run with a fixed number of ensembles which is usually small compared to the number of degrees of freedom of the model (i.e. the size of the state vector), the tendency is for all the ensemble members to collapse towards a single solution. Inflation increases the spread of the members in a systematic way to avoid problems of collapse. There are several sophisticated options on inflation, including spatial and temporal adaptive and damping options, which help deal with observations which vary in density over time and location. See here for a discussion of inflationrelated namelist items.
Outlier rejection can be used to avoid bad observations (ones where the value was recorded in error or the processing has an error and a nonphysical value was generated). It also avoids observations which have accurate values but the mean of the ensemble members is so far from the observation value that assimilating it would result in unacceptably large increments that might destablize the model run. If the difference between the observation and the prior ensemble mean is more than N standard deviations from the square root of the sum of the prior ensemble and observation error variance, the observation will be rejected. The namelist setting for the number of standard deviations to include is &filter_nml :: outlier_threshold and we typically suggest starting with a value of 3.0.
For small ensemble sizes a table of expected statistical error distributions can be generated before running DART. Corrections accounting for these errors are applied during the assimilation to increase the ensemble spread which can improve the assimilation results. The namelist item to enable this option is &assim_tools_nml :: sampling_error_correction. Additionally you will need to have a precomputed correction file final_full.X, where X matches your ensemble size, in the run directory. See the description of the namelist item in the &assim_tools_nml namelist, and look here for instructions on where to find (or how to generate) the auxiliary file needed by this code. See Anderson (2011).
Separate scripting can be done to support forecasts starting from the analyzed model states. After filter exits, the models can be run freely (with no assimilated data) further forward in time using one or more of the last updated model states from filter. Since all ensemble members are equally likely a member can be selected at random, or a member close to the mean can be chosen. See the closest_member_tool for one way to select a "close" member. The ensemble mean is available to be used, but since it is a combination of all the member states it may not have selfconsistent features, so using a single member is usually preferred.
Filter can be used to evaluate the accuracy of a single model state based on a set of available observations. Convert the model data into a single DART state vector, and either copy or link it so there appear to be 2 separate ensemble members (which are identical). Set the filter namelist ensemble size to 2 by setting ens_size to 2 in the &filter_nml namelist. Turn off the outlier threshold and both Prior and Posterior inflation by setting outlier_threshold to 1, and both the inf_flavor values to 0 in the same &filter_nml namelist. Set all observation types to be 'evaluateonly' and have no types in the 'assimilate' list by listing all types in the evaluate_these_obs_types list in the &obs_kind_nml section of the namelist, and none in the assimilation list. Run filter as usual, including model advances if needed. Run observation diagnostics on the resulting obs_seq.final file to compute the difference between the observed values and the predicted values from this model state.
To compare results of an experiment with and without assimilating data, do one run assimilating the observations. Then do a second run where all the observation types are moved to the evaluate_these_obs_types list in the &obs_kind_nml section of the namelist. Also turn inflation off by setting both inf_flavor values to 0 in the &filter_nml namelist. The forward operators will still be called, but they will have no impact on the model state. Then the two sets of diagnostic state space netcdf files can be compared to evaluate the impact of assimilating the observations, and the observation diagnostic files can also be compared.
The filter adds a quality control field with metadata 'DART quality control' to the obs_seq.final file. At present, this field can have the following values:
0:  Observation was assimilated successfully 
1:  Observation was evaluated only but not used in the assimilation 
2:  The observation was used but one or more of the posterior forward observation operators failed 
3:  The observation was evaluated only but not used AND one or more of the posterior forward observation operators failed 
4:  One or more prior forward observation operators failed so the observation was not used 
5:  The observation was not used because it was not selected in the namelist to be assimilated or evaluated 
6:  The prior quality control value was too high so the observation was not used. 
7:  Outlier test failed (see below) 
The outlier test computes the difference between the observation value and the prior ensemble mean. It then computes a standard deviation by taking the square root of the sum of the observation error variance and the prior ensemble variance for the observation. If the difference between the ensemble mean and the observation value is more than the specified number of standard deviations, then the observation is not used and the DART quality control field is set to 7.
There are two choices for the basic type of inflation: observation space or state space. Almost all users use state space inflation and the rest of this discussion applies to this type. (If you are interested in observation space inflation, talk to Jeff first.)
State space inflation changes the spread of a set of ensemble members without changing the mean value. The algorithm computes the mean and standard deviation for each variable in the state vector in turn, and then moves the values away from the mean in such a way that the mean remains unchanged. The resulting standard deviation is (generally) larger than before. It can be applied to the Prior state, before observations are assimilated (the most frequently used case), or it can be applied to the Posterior state, after assimilation. See Anderson (2007), Anderson (2009).
Inflation can be a single value applied to all state space variables over all times. It can be a single value per state space variable, constant in time. And finally, it can vary with time, adapting to different densities of observations in time and space. To enable state space inflation, see the inf_flavor namelist options below. To allow the values to adapt through time in each assimilation window see the inf_sd_initial description. See the inf_xxx_from_restart options to set a value in the namelist versus reading in the initial values from a file. There are additional options to damp inflation through time. In regions where the density of observations varies in time the damping slowly lowers the inflation values in the absence of new observations at those locations. In practice with large geophysical models using damped inflation has been a successful strategy. See the section describing inf_damping.
The following namelist items related to inflation are all found in the input.nml file, in the &filter_nml namelist. The detailed descriptions are in the namelist section below. Here we try to give some basic advice about commonly used values and suggestions for where to start. In the namelist each entry has two values. The first is for Prior inflation and the second is for Posterior inflation. If inf_flavor is 0, all other settings for that column are ignored.
0:  No inflation 
1:  Observation space inflation 
2:  Spatiallyvarying state space inflation 
3:  Spatiallyfixed state space inflation 
The suggested procedure for testing inflation options is to start without any (both inf_flavor values set to 0). Then enable Prior state space, spatiallyvarying inflation, with no Posterior inflation (set inf_flavor to [2, 0]). Then try damped inflation (set inf_damping to 0.9 and set inf_sd_initial and inf_sd_lower_bound to 0.6). The inflation values and standard deviation are written out to the Prior_Diag.nc and Posterior_Diag.nc files as the last 2 'copies', so the inflation fields can be plotted (we often use ncview ). Expected inflation values are generally in the 1 to 10 range; if values grow much larger than this it usually indicates a problem with the assimilation.
DART is distributed as a toolkit/library/facility that can be used asis with the existing models and observations, but is also designed so that users can add new models, new observation types and forward operators, and new assimilation algorithms.
The locations in the DART code tree which are intended to be modified by users are:
The detailed execution flow inside the filter program is:
This namelist is read from the file input.nml. Namelists start with an ampersand '&' and terminate with a slash '/'. Character strings that contain a '/' must be enclosed in quotes to prevent them from prematurely terminating the namelist.
&filter_nml async = 0, adv_ens_command = "./advance_model.csh", ens_size = 20, start_from_restart = .false., output_restart = .false., obs_sequence_in_name = "obs_seq.out", obs_sequence_out_name = "obs_seq.final", restart_in_file_name = "filter_ics", restart_out_file_name = "filter_restart", init_time_days = 0, init_time_seconds = 0, first_obs_days = 1, first_obs_seconds = 1, last_obs_days = 1, last_obs_seconds = 1, num_output_state_members = 0, num_output_obs_members = 0, output_interval = 1, num_groups = 1, input_qc_threshold = 3.0, outlier_threshold = 1.0, enable_special_outlier_code = .false., output_forward_op_errors = .false., output_restart_mean = .false., output_timestamps = .false., output_inflation = .true., trace_execution = .false., write_obs_every_cycle = .false. silence = .false., inf_flavor = 0, 0, inf_initial_from_restart = .false., .false., inf_sd_initial_from_restart = .false., .false., inf_output_restart = .false., .false., inf_deterministic = .true., .true., inf_in_file_name = 'not_initialized', 'not_initialized', inf_out_file_name = 'not_initialized', 'not_initialized', inf_diag_file_name = 'not_initialized', 'not_initialized', inf_initial = 1.0, 1.0, inf_sd_initial = 0.0, 0.0, inf_damping = 1.0, 1.0, inf_lower_bound = 1.0, 1.0, inf_upper_bound = 1000000.0, 1000000.0, inf_sd_lower_bound = 0.0, 0.0 /
Particular options to be aware of are: async, ens_size, cutoff (localization radius), inflation flavor, outlier_threshold, restart filenames (including inflation), obs_sequence_in_name, horiz_dist_only, binary or ascii controls for state vector and observation sequence file formats. Some of these important items are located in other namelists, but all are in the same input.nml file.
The inflation control variables are all dimensioned 2, the first value being for the prior inflation and the second being for the posterior inflation.
Item  Type  Description 

async  integer  Controls method for advancing model:

adv_ens_command  character(len=129)  Command sent to shell if async is 2. 
ens_size  integer  Size of ensemble. 
start_from_restart  logical  True means start from a restart file, false means perturb a single state vector in restart file. 
output_restart  logical  True means output a restart file. 
obs_sequence_in_name  character(len=129)  File name from which to read an observation sequence. 
obs_sequence_out_name  character(len=129)  File name to which to write output observation sequence. 
restart_in_file_name  character(len=129)  File containing state restart vectors. 
restart_out_file_name  character(len=129)  File to which to write restart state vectors. 
init_time_days  integer  If negative, don't use. If nonnegative, override the initial days read from state data restart file. 
init_time_seconds  integer  If negative don't use. If nonnegative, override the initial seconds read from state data restart file. 
first_obs_days  integer  If negative, don't use. If nonnegative, ignore all observations before this time. 
first_obs_seconds  integer  If negative, don't use. If nonnegative, ignore all observations before this time. 
last_obs_days  integer  If negative, don't use. If nonnegative, ignore all observations after this time. 
last_obs_seconds  integer  If negative, don't use. If nonnegative, ignore all observations after this time. 
num_output_state_members  integer  Number of ensemble members to be included in the state diagnostic output. 
num_output_obs_members  integer  Number of ensemble members to be included in the output observation sequence file. 
output_interval  integer  Output state and observation diagnostics every 'N'th assimilation time, N is output_interval. 
num_groups  integer  Number of groups for hierarchical filter. 
outlier_threshold  real(r8)  Reject observation if prior mean is more than this many standard deviations from observation. Negative means no check. 
enable_special_outlier_code  logical  If true call a subroutine which can be customized by the user to do more elaborate outlier thresholding tests. See failed_outlier() near the bottom of filter.f90 for where to add the custom code, and for commented out examples of possible tests. Turning this flag on and off allows comparisons to be made between the default outlier threshold code and any custom settings without having to recompile the code. To change the outlier behavior you will have to add code in DART/filter/filter.f90 and recompile your executables. As distributed, turning this flag on and off will make no difference in the results. 
input_qc_threshold  real(r8)  Reject observation if incoming QC value exceeds this value. Incoming observations usually have a QC value provided with the dataset, e.g. NCEP obs include an incoming data QC. 
output_forward_op_errors  logical  True means output errors from forward observation operators. This is the 'istatus' error return code from the model interpolate routine. An ascii text file prior_forward_op_errors and/or post_forward_op_errors will be created in the current directory. For each ensemble member which returns a nonzero return code, a line will be written to this file. Each line will have three values listed: the observation number, the ensemble member number, and the istatus return code. Be cautious when turning this option on. The number of lines in this file can be up to the number of observations times the number of ensemble members times the number of assimilation cycles performed. This option is generally most useful when run with a small observation sequence file and a small number of ensemble members to diagnose forward operator problems. 
output_restart_mean  logical  True means output a restart file which contains the ensemble mean. The file name will be the value of the namelist item &filter_nml::restart_out_file_name with the string .mean appended. Even if &ensemble_manager_nml::single_restart_file_out is true the mean data will be written to a separate file. 
output_timestamps  logical  True means write timing information to the log before and after the model advance and the observation assimilation phases. 
output_inflation  logical  True means output inflation values in the prior and posterior diagnostic files. False omits them. 
trace_execution  logical  True means output very detailed messages about what routines are being called in the main filter loop. Useful if a job hangs or otherwise doesn't execute as expected. 
write_obs_every_cycle  logical  For debug use; this option can significantly slow the execution of filter. True means to write the entire output observation sequence diagnostic file each time through the main filter loop even though only observations with times up to and including the current model time will have been assimilated. Unassimilated observations have the value 888888.0 (the DART "missing value"). If filter crashes before finishing it may help to see the forward operator values of observations that have been assimilated so far. 
silence  logical  True means output almost no runtime messages. Not recommended for general use, but can speed long runs of the lower order models if the execution time becomes dominated by the volume of output. 
All subsequent variables are arrays of length 2. The first element is for the prior, the second element is for the posterior.  
inf_flavor  integer array dimension(2)  Inflation flavor for [prior, posterior]

inf_initial_from_restart  logical array dimension(2)  If true, get initial mean values for inflation from restart file. If false, use the corresponding namelist value inf_initial. 
inf_sd_initial_from_restart  logical array dimension(2)  If true, get initial standard deviation values for inflation from restart file. If false, use the corresponding namelist value inf_sd_initial. 
inf_deterministic  logical array dimension(2)  True means deterministic inflation, false means stochastic. 
inf_output_restart  logical array dimension(2)  Output an inflation restart file if true. 
inf_in_file_name  character(len=129) dimension(2)  Filename to read inflation restart values from. 
inf_out_file_name  character(len=129) dimension(2)  Filename to write inflation restart values into. 
inf_diag_file_name  character(len=129) dimension(2)  Filename to write output diagnostics for observation space inflation into. 
inf_initial  real(r8) dimension(2)  Initial value of inflation if not read from restart file. 
inf_sd_initial  real(r8) dimension(2)  Initial value of inflation standard deviation if not read from restart file. If negative, do not update the inflation values, so they are timeconstant. If positive, the inflation values will adapt through time, so they are timevarying. 
inf_damping  real(r8) dimension(2)  Damping factor for inflation mean values. The difference between the current inflation value and 1.0 is multiplied by this factor before the next assimilation cycle. The value should be between 0.0 and 1.0. Setting a value of 0.0 is full damping, which in fact turns all inflation off by fixing the inflation value at 1.0. A value of 1.0 turns inflation damping off leaving the original inflation value unchanged. 
inf_lower_bound  real(r8) dimension(2)  Lower bound for inflation value. 
inf_upper_bound  real(r8) dimension(2)  Upper bound for inflation value. 
inf_sd_lower_bound  real(r8) dimension(2)  Lower bound for inflation standard deviation. If using a negative value for sd_initial this should also be negative to preserve the setting. 
The following table contains the deprecated or obsolete namelist variables. If only deprecated, the values will have no effect. If obsolete, it is a FATAL ERROR to have these in the namelist.
Contents  Type  Description 

output_state_ens_mean  obsolete  The ensemble mean is now always in the state diagnostic output. 
output_state_ens_spread  obsolete  The ensemble spread is now always in the state diagnostic output. 
output_obs_ens_mean  obsolete  The ensemble mean is now always in the output observation sequence file. 
output_obs_ens_spread  obsolete  The ensemble spread is now always in the output observation sequence file. 
inf_start_from_restart  obsolete  The mean and standard deviation now have separate namelist controls. 
types_mod obs_sequence_mod obs_def_mod time_manager_mod utilities_mod assim_model_mod assim_tools_mod obs_model_mod ensemble_manager_mod adaptive_inflate_mod mpi_utilities_mod smoother_mod
Routine  Message  Comment 

filter_main  ens_size in namelist is ###: Must be > 1  Ensemble size must be at least 2. 
filter_main  inf_flavor= ### Must be 0, 1, 2, 3.  Only inflation options 0 to 3 are supported. 
filter_main  Posterior observation space inflation (type 1) not supported.  Posterior observation space inflation doesn't work. 
filter_main  Number of processes > model size.  Number of processes can't exceed model size for now. 
filter_generate_copy_meta_data  output metadata in filter needs state ensemble size < 10000, not ###.  Only up to 10000 ensemble members with state output for now. 
filter_generate_copy_meta_data  output metadata in filter needs obs ensemble size < 10000, not ###.  Only up to 10000 ensemble members with obs space output for now. 
filter_setup_obs_sequence  input obs_seq file has ### qc fields; must be < 2.  Only 0 or 1 qc fields in input obs sequence for now. 
get_obs_copy_index  Did not find observation copy with metadata observation.  Only 0 or 1 qc fields in input obs sequence for now. 
none
Many. New assimilation algorithms, support for new observation types, support for additional models, better performance on higher numbers of MPI tasks... The list is long. Send email to dart@ucar.edu if you are interested in additional functionality in DART.
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: 12164 $ 
Source:  $URL: https://svndaresdart.cgd.ucar.edu/DART/releases/classic/filter/filter.html $ 
Change Date:  $Date: 20171201 16:13:10 0700 (Fri, 01 Dec 2017) $ 
Change History:  try "svn log" or "svn diff" 