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 time-stepping 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 top level directory has been simplified from previous versions to look like :
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 forecast 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 preassim_mean.nc and postassim_mean.nc (or output_mean.nc) diagnostic 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 timeseries plot of the RMSE should show a sawtooth pattern. The initial error entirely depends on the match between the initial ensemble and the observations and may be large but it should decrease and then reach a roughly stable level. The ensemble spread should ultimately remain relatively steady, at a value around the expected observation error level. Once you believe you have a working assimilation, this will be your baseline case. If the ensemble spread is too small, several of the DART facilities described below are intended to compensate for ensemble members getting too close to each other. 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 20-30 members leads to statistical errors which are too large. More than 100 members takes longer to run with very little benefit, 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 50-60 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 correlations. The other is that, especially for large models, it improves run-time 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 localization-related namelist items.
Since the filter is run with a number of members which is usually small compared to the number of degrees of freedom of the model (i.e. the size of the state vector or the number of EOFs needed to characterize the variability), the model uncertainty is under-represented. Other sources of error and uncertainty are not represented at all. These factors lead to the ensemble being 'over-confident', or having too little spread. More observations leads to more over-confidence. This characteristic can worsen with time, leading to ensemble collapse to a single solution. Inflation increases the spread of the members in a systematic way to overcome this problem. 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 inflation-related 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 non-physical 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 the precomputed correction file sampling_error_correction_table.nc, 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 self-consistent 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. Either copy or link the model state file 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 'evaluate-only' 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.
In pre-Manhattan DART, there were two choices for the basic type of inflation: observation-space or state-space. Observation-space inflation is no longer supported. (If you are interested in observation-space inflation, talk to Jeff first.) The rest of this discussion applies to state-space inflation.
State-space inflation changes the spread of an ensemble
without changing the ensemble mean. The algorithm computes the ensemble mean
and standard deviation for each variable in the state vector
in turn, and then moves the member's values away from the mean in such a
way that the mean remains unchanged. The resulting standard deviation
is 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 values can vary in space and time, depending on the specified namelist values. Even though we talk about a single inflation value, the inflation has a gaussian distribution with a mean and standard deviation. We use the mean value when we inflate, and the standard deviation indicates how sure of the value we are. Larger standard deviation values mean "less sure" and the inflation value can increase more quickly with time. Smaller values mean "more sure" and the time evolution will be slower since we are more confident that the mean (inflation value) is correct.
The standard deviation of inflation allows inflation values to increase with time, if required by increasing density or frequency of observations, but it does not provide a mechanism to reduce the inflation when the frequency or density of observations declines. So there is also an option to damp inflation through time. In practice with large geophysical models using damped inflation has been a successful strategy.
The following namelist items which control inflation are found in the input.nml file, in the &filter_nml namelist. The detailed descriptions are in the namelist page. Here we try to give some basic advice about commonly used values and suggestions for where to start. Spatial variation is controlled by inf_flavor, which also controls whether there's any inflation, inf_initial_from_restart, and inf_initial, as described below. Time variation is controlled by inf_sd_initial_from_restart, inf_sd_initial, inf_sd_lower_bound, inf_damping, inf_lower_bound and inf_upper_bound.
In the namelist each entry has two values. The first is for Prior inflation and the second is for Posterior inflation.
0: | No inflation (Prior and/or Posterior) and all other inflation variables are ignored |
[1: | Deprecated: Observation space inflation] |
2: | Spatially-varying state space inflation (gaussian) |
3: | Spatially-uniform state space inflation (gaussian) |
4: | Relaxation To Prior Spread (Posterior inflation only) |
5: | Enhanced Spatially-varying state space inflation (inverse gamma) |
The suggested procedure for testing inflation options is to start without any (both inf_flavor values set to 0 and inf_damping > 0.). Then enable Prior state space, spatially-varying 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 files with _{prior,post}inf_{mean,sd} in their names. These NetCDF files can be viewed with common tools (we often use ncview ). Expected inflation values are generally in the 1 to 30 range; if values grow much larger than this it usually indicates a problem with the assimilation.
It is possible to set inflation values in an existing netCDF file by using one of the standard NCO utilities like "ncap2" on a copy of a restart file. Inflation mean and sd values look exactly like restart values, arranged by variable type like T, U, V, etc.
Here's an example of using ncap2 to set the T,U and V inf values:
ncap2 -s 'T=1.0;U=1.0;V=1.0' wrfinput_d01 input_priorinf_mean.nc ncap2 -s 'T=0.6;U=0.6;V=0.6' wrfinput_d01 input_priorinf_sd.nc -or- ncap2 -s 'T(:,:,:)=1.0;U(:,:,:)=1.0;V(:,:,:)=1.0' wrfinput_d01 input_priorinf_mean.nc ncap2 -s 'T(:,:,:)=0.6;U(:,:,:)=0.6;V(:,:,:)=0.6' wrfinput_d01 input_priorinf_sd.nc
Some versions of the NCO utilities change the full 3D arrays into a single scalar. If that's your result (check your output with ncdump -h) use the alternate syntax or a more recent version of the NCO tools.
DART is distributed as a toolkit/library/facility that can be used as-is 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 Manhattan release of DART includes state space output expanded from the previous two stages (Prior and Posterior) to up to four (input, preassim, postassim, and output). This makes it possible to examine the states with and without either kind of inflation, as described below. In addition, the state space vectors are each written to a separate NetCDF file: ${stage}_mean.nc, ${stage}_sd.nc, ${stage}_member_####.nc . The detailed execution flow inside the filter program is:
See the filter namelist page for a detailed description of all &filter_nml variables. This namelist is read from the file input.nml.
mpi_utilities_mod filter_mod
Note that filter_mod.f90 uses many more modules.
See Detailed Program Flow for a short description of DART's new 'stages'. In addition, the Manhattan release simplifies some namelists by replacing many user-settable file names with hardwired filenames. Files can then be renamed in the run scripts to suit the user's needs.
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, 2, 3. | Observation Inflation is no longer supported (i.e flavor 1). |
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 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