doc/README_regression_testing.txt

   1 Regression testing protocol
   2 ===========================
   3
   4 The purpose of regression testing is to make sure that the output of the code
   5 did not change from previous runs on a database of examples and in particular
   6 that bugs that were fixed previously did not reappear (=the code did not regress).
   7
   8 Set a baseline before changing anything. After the change, compare against the baseline.
   9 If the change was supposed to change numbers, verify the science and set up new baseline.
  10 If the change caused rounding error differences only, set up a new baseline.
  11 If there was any change notify other developers in particular Jan.
  12
  13 1. in wrfv2_fire: pull, configure with debug, single processor, compile_fire,
  14    cd test/em_fire, edit namelist.input to set fire_print_file=1 (do NOT commit
  15    such edited file!), wrf.exe >& wrf.log, let run until some wrfrst* files are
  16    produced, ideally 800+ time steps. This will create about 5GB of .txt files.
  17    If the .txt files were not created, make sure all module_fr_sfire_*.F source files
  18    have #define DEBUG_OUT at the beginning (those where this string appears later)
  19
  20 2. to set up a baseline: ./moveto  will create directory ~/tmp/em_fire/<current commit number>
  21    and move the wrf/fire output file there
  22
  23    or
  24
  25 3. to check current commit against baseline: compareto ~/tmp/em_fire/<commit number>
  26
  27 4. Compile with other options (OpenMP, DM, various combinations of number of processes
  28    and threads), run until some wrfrst* files are produced, make sure the results are
  29    the same up to rounding error as in the corresponding wrfrst* files in
  30    the baseline. You can use ncdiff in matlab for that.  The proper path in matlab
  31    is set by starting matlab in test/em_fire or test/em_real, or execute startup.m there.
  32    Note wrf/other/Matlab/netcdf/mexnc must be installed, see README_matlab_netcdf.txt
  33
  34 5. in matlab, type go in the directory with all those *.txt files which should produce
  35    a movie, check for any weirdness and artefacts such as fire propagation stops and
  36    zigzag instabilities of the fireline.
  37
  38 6. in matlab, load LFN from the wrfrst* files and check for any weirdness such as positive
  39    or negative spikes at the boundary. These were past bugs and should not reappear. Some
  40    of these may show up in OpenMP or DM runs only. (But you checked that the parallel
  41    and serial results are the same up to rounding already, right?) Use ncread to load
  42    a single variable from wrfrst* file into matlab.
  43
  44 7. Do not forget to do the same also in em_real with WPS! Some bugs appear only
  45    when running real, not ideal. See README_wps.txt for how to run real. After
  46    running wps.csh once, you can just run wrf.exe the next time (usefulf for mpirun).
  47
  48 In case of any differences find the first commit where the results deviate and either fix or
  49 justify that this is actually correct and establish a new baseline.
  50
  51 Please note in the commit message if the results are to be different because of a change
  52 in science or a bug fix.
  53
  54 To get the current commit number you can use  git log | head -1
  55
  56 The commit number captures the exact state of all files in the project so the
  57 results associated with a commit are reproducible. You can get all files as of a given
  58 commit by git checkout <commit number>
  59
  60 Note that bugs can reappear by changing namelist.input esp. the method parameters at the end.
  61
  62
  63 Jan Mandel, October 6, 2008
  64
  65
  66
  67