[Dart-dev]  DART/branches/development/models/template/README: added more details to the 'how to get started' section.
nancy at ucar.edu
nancy at ucar.edu
Wed Dec 5 16:43:50 MST 2012
Date: 2012-12-05 16:43:50 -0700 (Wed, 05 Dec 2012)
added more details to the 'how to get started' section.
this eventually needs to be folded into some other
part of the documentation.
-------------- next part --------------
--- DART/branches/development/models/template/README 2012-12-05 23:10:19 UTC (rev 5940)
+++ DART/branches/development/models/template/README 2012-12-05 23:43:50 UTC (rev 5941)
@@ -118,18 +118,114 @@
experiments. the 'model_mod_check' utility program can be used
during this process to check your implementation.
the general flow is:
- ./model_to_dart - read model data and convert it into a dart state vector file
- ./create_obs_sequence - make a file with a single observation in it
- ./perfect_model_obs - should interpolate a value for the obs
- ./dart_to_model - convert the dart vector back into a model data file
+ 1) ./model_to_dart - read model data and convert it into a dart state vector file
+ 2) ./create_obs_sequence - make a file with a single observation in it
+ 3) ./perfect_model_obs - should interpolate a value for the obs
+ 4) ./dart_to_model - convert the dart vector back into a model data file
- generate an ensemble of states, or set 'start_from_restart' to .false.
- run ./filter with the single observation
- look at the Prior_Diag.nc and Posterior_Diag.nc files
- diff them with ncdiff: ncdiff Posterior_Diag.nc Prior_Diag.nc Innov.nc
- plot it, with ncview if possible: ncview Innov.nc
- the difference between the two is the impact of that single observation
- see if it's at the right location and if the differences seem reasonable
+ 5) generate an ensemble of states, or set 'start_from_restart' to .false.
+ 6) run ./filter with the single observation
+ 7) look at the Prior_Diag.nc and Posterior_Diag.nc files
+ diff them with ncdiff: ncdiff Posterior_Diag.nc Prior_Diag.nc Innov.nc
+ plot it, with ncview if possible: ncview Innov.nc
+ the difference between the two is the impact of that single observation
+ see if it's at the right location and if the differences seem reasonable
+more details on each of these 7 steps follows.
+this program needs to read the output file from the model,
+whatever format that is (many of our supported models use netcdf).
+it needs to create a 1d array of values in whatever order it chooses.
+the model_mod code must be able to take any index into that array
+(say array(25)) and be able to return what location and variable kind
+that corresponds so, so the mapping from 2d or 3d array to this 1d array
+has to be kept track of in the model_mod code so it can be inverted
+you can make a synthetic observation (or a series of them) with this
+interactive program and use them for testing. before running, make sure
+the observation types you want to use are in the input.nml file in the
+&obs_kind_nml section, either in the assimilate or evaluate lists.
+then run the program. give the total number of obs you want to create
+(start with 1). answer 0 to number of data items and 0 to number of
+quality control items. answer 0 when it says enter -1 to quit. you
+will be prompted for an observation number to select what type of
+observation you are going to test.
+give it a location that should be inside your domain, someplace where
+you can compute (by hand) what the correct value should be. when it
+asks for time, give it a time that is the same as the time on your
+when it asks for error variance, at this point it doesn't matter.
+give it something like 10% of the expected data value. later on
+this is going to matter a lot, but for testing the interpolation of
+a single synthetic obs, this will do.
+for an output filename, it suggests 'seq_def.out' but in this case,
+tell it 'obs_seq.in'.
+if you have run the model_to_dart and created a state vector, make sure
+the name matches the input name in the input.nml file, the &perfect_model_obs_nml
+namelist. make sure the input obs_sequence is still set to 'obs_seq.in'.
+run perfect_model_obs. something bad will happen, most likely. fix it.
+eventually it will run and you will get an 'obs_seq.out' file. for these
+tests, make sure &obs_sequence_nml : write_binary_obs_sequence = .false.
+in the input.nml file. the sequence files will be short and in ascii.
+you can check to see what the interpolated value is. if it's right, yay.
+if not, debug the interpolation code in the model_mod.f90 file.
+if you have run perfect_model_obs, you have not changed the dart
+state vector in any way. however, it's a good test to make a copy of
+the model input file, then run 'model_to_dart' and then 'dart_to_model'
+(you may need to set 'is_model_advance_file' to .false. for the
+&dart_to_model_nml namelist) and you should get identical values back
+in the model input file as you started with.
+5) running from a single input state
+in the &filter_nml namelist, set 'start_from_restart' to .false.
+this tells filter that you have not generated N initial conditions,
+that you are only going to supply one and it needs to perturb that
+one to generate an initial ensemble. make sure the 'restart_in_file_name'
+matches the name of the single state vector file you have. you can
+use the 'obs_seq.out' file from the perfect_model run because now
+it has data for that observation. later on you will need to decide
+on how to generate a real set of initial states, and then you will
+set 'start_from_restart' back to .true. and supply N files instead of one.
+you may need to set the &ensemble_manager_nml : perturbation_amplitude
+down to something smaller than 0.2 for these tests - 0.00001 is a good
+first guess for adding small perturbations to a state.
+set the ens_size to something small for testing - between 4 and 10 is
+usually a good range. make sure your observation type is in the
+'assimilate_these_obs_types' list and not in the evaluate list.
+run filter. find bugs and fix them until the output 'obs_seq.final'
+seems to have reasonable values. running filter will generate two
+netcdf diagnostic files: Prior_Diag.nc and Posterior_Diag.nc
+run 'ncdiff Posterior_Diag.nc Prior_Diag.nc differences.nc' and use
+your favorite netcdf plotting tool to see if there are any differences
+between the 2 files. for modules using a regular lat/lon grid 'ncview'
+is a quick and dirty way to scan files. for something on an irregular
+grid a more complicated tool will have to be used. if the files are
+identical the assimilation didn't do anything. check to see if there
+is a non-zero DART quality control value in the obs_seq.final file.
+check to see if there are errors in the dart_log.out file. figure out
+why there's no change. if there is a difference, it should be at
+the location of the observation and extend out from it for a short
+distance. if it isn't in the right location, look at your get_state_meta_data()
+code. if it doesn't have a reasonable value, look at your model_interpolate() code.
+there's lots more to say about this, but this is a quick pointer to
+how to get started.
More information about the Dart-dev