doc/README.io_config

   1 Run time control of IO stream variable sets
   2
   3 For WRF releases prior to V3.2, state variables were associated with I/O
   4 streams at compile time via their entries in the Registry.  That will
   5 still work, and should still be considered the primary method for defining
   6 stream variable sets in WRF. This new capability allows users to add or
   7 exclude state variables from a history or input stream at run-time without
   8 recompiling.  Also, this can be done on a per-domain basis as well.
   9
  10 Here's a quick sketch of how it is used:
  11
  12 a) There are two new namelist variables in the time_control section
  13 of the namelist.input file.  The first is iofields_filename. This is a
  14 character variable, settable separately for each domain and defaulting
  15 to "NONE_SPECIFIED".  This is where a user can list the names of text
  16 files containing lists of variables to added/removed from history and
  17 input streams for that domain.  As with other namelist variables that
  18 have max_domains in their rconfig definitions, each domain does have
  19 to have an entry in the namelist.input file. You can set each entry to
  20 the name of separate definitions file for each domain, or some or all
  21 of them can be the name of the same file.
  22
  23 The second namelist variable is a logical, ignore_iofields_warning,
  24 which tells the program what to do if it encounters an error in these
  25 user-specified files.  The default value, .TRUE., is to print a warning
  26 message but continue the run.  If set to .FALSE., the program will
  27 abort if there are errors in these user-specified files.
  28
  29 b) The user-specified files, named as settings to the iofields_filename
  30    in the namelist.input file.  The files contain lines associating
  31    variables with streams.  Each line has the form:
  32
  33   op:streamtype:streamid:variables
  34
  35     op:          either + (plus) or - (minus) for adding or removing
  36                  a variable
  37     streamtype:  either i (input) or h (history) indicating which type
  38                  of stream is being affected
  39     streamid:    an integer between 0 and the number of streams (0
  40                  represents main input or history)
  41     variables:   comma separated list of variables
  42
  43 Example.  The line:
  44
  45     +:i:5:u,v,w
  46
  47 will add the U, V, and W variables to auxinput5.  Note for this example,
  48 these are 2 time-level variables so that, as with Registry-defined
  49 stream-associations, the designations apply to variables representing
  50 the highest numbered time level (U_2). See the file test/em_real/sample.txt
  51
  52 These lines cannot be longer than 256 characters, but you can associate
  53 long lists of variables using multiple lines with the same op, streamtype,
  54 and streamid. You can have comments in these files by putting # on the
  55 line, causing the entire line to be a comment (even characters before
  56 the #).
  57
  58 An implementation note: the mechanism is not very efficient at this
  59 point. Each variable listed involves a search through all the state
  60 variables in the grid.  That is still relatively quick - even a very
  61 long list shouldn't take more than a couple seconds -- and the lists are
  62 processed only once when a grid is allocated.  Even so, super-long lists
  63 of these run-time stream associations are mildly discouraged. In other
  64 words, use this as a mechanism to tweak the Registry I/O definitions or to
  65 get domain by domain specific behavior, but don't use it as a substitute
  66 for defining I/O definitions with state variables in the Registry.
  67