DMC -- Jan 2005

Notes on TRANSP regression testing.

Background:  there is a desire to run regression tests before updating the
TRANSP production system, and to expand TRANSP regression testing to cover
a variety of simulations on a number of tokamaks.  Until recently, the only
"standard" regression test cases were old TFTR cases with simplified geometry.
Now there are several cases, and a definite procedure for adding more.

List of regression test cases:  see $CONFIGDIR/regression.dat

Contents as of 1 Feb 2005:
transpgrid.pppl.gov> cat $CONFIGDIR/regression.dat 
TFTR  88  37065Y01  mctest.tmi
D3D   04  118419W04 ectest.tmi
CMOD  05  3018      rftest.tmi
NSTX  04  112989Z08 nstxreg1.tmi
This references three cases.  For example:

The regression test data for TFTR 37065Y01 is in $RESULTDIR/TFTR.88/37065Y01*
and there is also a Ufiles input directory $DATADIR/TFTR/test as referenced
in the regression test case namelist (37065Y01TR.DAT file).  A UREAD script
for standard plots is found at $RESULTDIR/TFTR.88/mctest.tmi ...

To add a regression test case:
  (1) case should normally run without crashing in a few hours at most;
      a copy of the namelist and results should be in "tok.yy" subdirectory
      of $RESULTDIR (as in the example, above).
  (2) input data should be in Ufile form in a subdirectory of
      $DATADIR/<tok> where <tok> is a tokamak id code such as "D3D"
      or "NSTX"; the case's namelist file should reference the Ufile 
      directory, using the INPUTDIR variable, as a relative path to 
      $DATADIR/<tok>.  This is necessary so the procedure for copying 
      regression tests can find the input data.
  (3) a single rplot "UREAD" script or tmi file should be available 
      to produce a "standard" set of plots for the regression test.
      This script should initially answer the rplot prompt

           ; RPLOT:MAIN   ENTER OPTION NUMBER:$

      and, if it runs normally, should produce a series of plots and 
      then exit the program, without invoking any subprocedures.  This
      last restriction is due to the limitations of the scripts for
      copying the regression test cases.
  (4) when (1-3) are satisfied, add a record to $CONFIGDIR/regression.dat,
      in the format "<tok> <yy> <runid> <tmi-filename>"; no comments; there
      must be exactly four blank delimitted fields.

Regression test cases are copied by $TRANSPROOT/bootstrap/entar*.csh; they
are installed in new copies of the code by $TRANSPROOT/bootstrap/install.csh.

The bootstrap/install.csh procedure can be run on an existing developer's
copy of the code -- THIS REPLACES THE SOURCE with the current state of the
repository -- regression test data is added; existing test data is undisturbed
provided the runids are distinct from those used for the regression tests.

To run a single regression test by hand:  use the traditional method, i.e.:

  activate <tok.yy> <old-runid> <new-runid>
  pretr ...
  runtr ...

Automated execution of *all* regression tests:

  run_all_tests [N]

This will launch the first N jobs and queue subsequent jobs so that all 
subsequent jobs execute sequentially.  N=1 is assumed if the argument is 
omitted.  N=0 should not be used unless a TRANSP job is already running
(the enqueue mechanism is a daisy chain off the script at the end of each
completed TRANSP run).

Use 

  rmonitor

to track the progress of runs.

NOTE:  at PPPL, the above procedure is not recommended for shared 
interactive cluster nodes.  So, on the PPPL unix cluster, use:

  run_all_tests qsub

to queue all regression tests as PBS batch jobs.  These will usually run 
simultaneously, as, usually, serial batch compute servers are available.