[Dart-dev] [5941] DART/branches/development/models/template/README: added more details to the 'how to get started' section.

Wed Dec 5 16:43:50 MST 2012

Revision: 5941
Author:   nancy
Date:     2012-12-05 16:43:50 -0700 (Wed, 05 Dec 2012)
Log Message:
-----------
added more details to the 'how to get started' section.
this eventually needs to be folded into some other
part of the documentation.

Modified Paths:
--------------
    DART/branches/development/models/template/README

-------------- next part --------------
Modified: DART/branches/development/models/template/README
===================================================================

--- 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.
+
+1) model_to_dart
+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
+on demand.
+
+2) create_obs_sequence
+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
+model data.
+
+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'.
+
+3) perfect_model_obs
+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.
+
+4) dart_to_model
+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.
+
+6) filter
+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
+
+7) diagnostics
+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.
+
