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

PROGRAM filter

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.13 $
Release Name: $Name: $
Change Date: $Date: 2006/09/11 14:35:32 $
Change history: see CVS log

OVERVIEW

Main program for driving ensemble filter assimilations. This program provides a number of options that are driven from its namelist. 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 J-release of DART.

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 is okay; 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.

The filter also can perform an outlier threshold test on observations. If the prior ensemble mean differs from the observed value by more than a specified number of standard deviations, it is not used and the DART quality control field is set to 7.

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




OTHER MODULES USED

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



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

 namelist / filter_nml / 
 async,adv_ens_command,ens_size,start_from_restart,output_restart,obs_sequence_i
 n_name,obs_sequence_out_name,restart_in_file_name,restart_out_file_name,init_ti
 me_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, inf_flavor, inf_start_from_restart, inf_output_restart,
inf_deterministic, inf_in_file_name, inf_out_file_name, inf_diag_file_name,
inf_initial, inf_sd_initial, inf_lower_bound, inf_upper_bound, inf_sd_lower_bound
 

Discussion

Controls various aspects of filter. The inflation control variables are all dimensioned 2, the first value being for the prior inflation and the second being for the posterior inflation.

This namelist is read in a file called input.nml

Contents Type Description
async integer Controls method for advancing model: 0 is subroutine call, 2 is shell command. Default: 0
adv_ens_command character(len Command sent to shell if async is 2. Default: .
ens_size integer Size of ensemble. Default: 20
start_from_restart logical True means start from a restart file, false means perturb a single state vector in restart file. Default: .false.
output_restart logical True means output a restart file. Default: .false.
obs_sequence_in_name character(len=129) File name from which to read an observation sequence. Default: obs_seq.out
obs_sequence_out_name character(len=129) File name to which to write output observation sequence. Default: obs_seq.final
restart_in_file_name character(len=129) File containing state restart vectors. Default: filter_ics
restart_out_file_name character(len=129) File to which to write restart state vectors. Default: filter_restart
init_time_days integer If negative, don't use. If non-negative, override the initial days read from state restart. Default: 0
init_time_seconds integer If negative don't use. If non-negative, override the initial seconds read from state restart. Default: 0
output_state_ens_mean logical True mean include ensemble mean in state diagnostic output. Default: .true.
output_state_ens_spread logical True means include ensemble spread in state diagnostic output. Default: .true.
output_obs_ens_mean logical True means include ensemble mean in output observation sequence file. Default: .true.
output_obs_ens_spread logical True means include ensemble spread in output observation sequence file. Default: .true.
num_output_state_members integer Number of ensemble members to be included in the state diagnostic output. Default: 0
num_output_obs_members integer Number of ensemble members to be included in the observation sequence file. Default: 0
output_interval integer Output state and observation diagnostics every nth assimilation time, n is output_interval. Default: 1
num_groups integer Number of groups for hierarchical filter. Default: 1
outlier_threshold real(r8) Reject observation if prior mean is more than this many sd's from observation. Negative means no check. Default: -1.0_r8
inf_flavor integer 0=none, 1=obs_space, 2 = varying state space, 3 = fixed state_space. Default: 0
inf_start_from_restart logical If true, get initial values for inflation from restart file. Default: .false.
inf_output_restart logical Output an inflation restart file if true. Default: .false.
inf_deterministic logical True means determinstic inflation, false means stochastic. Default: .true.
inf_in_file_name character(len=129) Name from which to read inflation restart. Default: not_initialized
inf_out_file_name character(len=129) File to which to write inflation restart file. Default: not_initialized
inf_diag_file_name character(len=129) File to which to write output diagnostics for observation space inflation. Default: not_initialized
inf_initial real(r8) Initial value of inflation if not read from restart file. Default: 1.0_r8
inf_sd_initial real(r8) Initial value of inflation standard deviation if not read from restart file. Default: 0.0_r8
inf_lower_bound real(r8) Lower bound for inflation value. Default: 1.0_r8
inf_upper_bound real(r8) Upper bound on inflation value. Default: 1000000.0_r8
inf_sd_lower_bound real(r8) Lower bound for inflation standard deviation. Default: 0.0_r8




FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
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.



KNOWN BUGS




FUTURE PLANS

Further development to better support observations that can only be computed once is needed.

Discussion