varinfo.dat

varinfo.dat

The varinfo.dat file specifies many things about the input/output rules for ROMS. Read the comments at the beginning of varinfo.dat for an introduction to the meaning of the various entries Vinfo(1) through Vinfo(7) and scale.

 This file contains all ROMS/TOMS Input/Output variables information. It is used to manage NetCDF files. 
 The following information is needed for any IO variable:
!
       Vinfo(1)      Field variable name.
       Vinfo(2)      Long-name attribute.
       Vinfo(3)      Units attribute.
       Vinfo(4)      Field type attribute.
       Vinfo(5)      Associated time variable name.
       Vinfo(6)      Index variable name used in information arrays.
       Vinfo(7)      Staggered C-grid variable type:
                           'nulvar' => non-grided variable.
                           'p2dvar' => 2D PHI-variable.
                           'r2dvar' => 2D RHO-variable.
                           'u2dvar' => 2D U-variable.
                           'v2dvar' => 2D V-variable.
                           'p3dvar' => 3D PHI-variable.
                           'r3dvar' => 3D RHO-variable.
                           'u3dvar' => 3D U-variable.
                           'v3dvar' => 3D V-variable.
                           'w3dvar' => 3D W-variable.
                           'b3dvar' => 3D BED-sediment.
       scale         Scale to convert data to model input units.
!
   Enclose Vinfo variables with single quotes so this file can be read with a free format statement. The Vinfo(6) variable must be    
   unique and case sensitive. It is checked in "mod_ncparm" to set the appropiate ID index for the information arrays.
   Notice that there is commented information for each variable  including input/output type and internal model units in brackets.     
   There are some variables that are special and require a particular units for input and output. 

Vinfo() entries

Vinfo(1): The principal role of varinfo.dat is to make the connection between the unique index variable name that ROMS uses (Vinfo(6)) and the name of the corresponding variable in the NetCDF file (Vinfo(1)).

Example: The default varinfo.dat uses the name swrad for the solar shortwave radiation flux in the forcing NetCDF file. If you have a forcing NetCDF file that uses a different name, say shortwave, you don’t need to rename the variable in the forcing file. Just change the Vinfo(1) entry in varinfo.dat to shortwave and ROMS will find it.

Vinfo(6): This the only entry in varinfo.dat that you must not change. This is the name by which variables are referred to internally in ROMS.

Vinfo(5): This is the time variable name associated with the data. If your NetCDF file uses a different name from the default you don’t need to rename it in the NetCDF file, just in varinfo.dat.

Example: If your file of shortwave radiation data is a time series defined at times given by variable shortwave_time then change the Vinfo(5) entry to this from the default srf_time.

Note: If the data in your NetCDF file has an attribute of time the entry in Vinfo(5) is ignored, and the time variable indicated in the NetCDF is used instead.

Vinfo(3) and scale: This is possibly the trickiest part of varinfo.dat and a place where one can easily make an error.

Note: For output only variables, the Vinfo(3) units string is used on output to describe the data in an output NetCDF file units attribute.

For variables that are used on input only, such as meteorological data, we have assumed a convention that Vinfo(3) describes the units that you have in your NetCDF file. It does not strictly describe the units ROMS assumes internally (though this is generally true if the scale factor is 1). The scale can be used to make ROMS modify the data during input to be consistent with ROMS internal units without the need to re-create a new forcing file with adjusted units.

Example: ROMS assumes surface air pressure is given in millibars. The COARE bulk formulae in subroutine bulk_flux demand this. If your input file is in Pascals you can convert these using the scale entry. You would change scale from its default of 1.0d0 to 0.01d0 because 1 Pascal = 0.01 millibar. Note that the rule is

ROMS_internal_units = (your_units) x (scale)

Hint: if you google search the string convert pascal to millibar you’ll get the necessary scale factor without overly taxing your brain.

If you change the scale factor in your varinfo.dat, I recommend you change the units string in Vinfo(2) to be consistent with your data file, and insert a comment to remind yourself what you’ve done in using a new scale factor. You can append a comment using a ! after anyentry in varinfo.dat.

Here is a table of common conversions that might be required:

Index     Default NetCDF  Long Name               Units required      Other     Scale
Vinfo(5)  variable name                           Internally by ROMS  units             
!   
!
idPair       Pair         surface air pressure       millibar          Pascal    0.01
!
idTair       Tair         surface air temperature    Celsius           Kelvin    can't do it
!
idQair       Qair         surface air relative       Fraction          Percent   0.01
                          humidity
!
idCfra       cloud        cloud fraction             Fraction          Percent   0.01
!
idSrad       swrad        solar shortwave            Watt/m2 (input)             1.0
                          radiation                  Celsius m/s
!
idrain       rain         rain fall rate             kg/m2/s           m/s       0.001
                                                                                (1/rhow)
!
idsdwf       swflux       surface net freshwater     m/s               cm/day    0.01/86400
                          flux (E-P)
!
idUsms       sustr        surface u-momentum         N/m2 (input)      dyne/cm2  0.1
                          stress                     m2/s2

Input and output variables

Some variables described in varinfo.dat are both input and output variables. The model state variables zeta, temp, salt, u, v…etc. are obviously in this category. Certain surface flux variables can be either input forcing data, or output results computed internally.

Example: In some ROMS configurations, such as #define BULK_FLUX, surface u-stress, sustr, is an output having been computed internally. It is written to the output NetCDF file if Hout(idUsms) = T in the roms.in file.

In other configurations sustr is an input, and drives the surface momentum input directly.

The scale factor is only used on input. It is ignored on output. Output data are always written in default ROMS internal units with a few exceptions: namely, heat fluxes and surface and bottom stresses. The output scale factors applied can be seen in the source code (e.g. wrt_his.F). This re-scaling is made to give geophysically meaningful units of Watt/m2 for heat, and N/m2 (or Pa) for stresses.

We will add more documentation on the default internal units, and the distinction between input and output varibales, in the next model release.

CAUTION: You must be very careful here if you start tinkering with varinfo.dat entries for mixed I/O variables.

Example: If you intend surface wind stress tau, sustr, as an input but have a data file in dynes/cm2 (= 0.1 N/m2 or Pa), you need to convert these to ROMS internal units of kinematic stress tau/rho0 (like u*2) of m2/s2. The scale factor is 0.1/1025 = 9.8x10-5 where the numerator 0.1 converts dynes/cm2 to Pa and the reference density of seawater is 1025 kg/m3.

The conversion of momentum (in Pa) and heat flux (in Watts/m2) to kinematic units (of m2/s2 and degC m/s, respectively) is why the report of min/max values sent to stdout shows different values to those you have in your input NetCDF file. You should always carefully inspect the range of data values read when working with a new model set-up or new forcing netCDF files to make sure the data you are reading are what you expect. In the next version of the model will will clarify these procedures by documenting within varinfo.dat the default input and output units, and the internal units.

If you intend sustr to be an output you should keep the units string Vinfo(3) as newton meter-2 because this string will be the units attribute in the output NetCDF file. The scale value is irrelevant because it will not be applied on output. You can’t use it to alter the units of the output.

If you specify sustr as input and output (which you can do: ROMS will read forcing sustr from a forcing NetCDF file and write sustr to history, averages, stations file etc.) even if you do a scale factor conversion you’d better keep the Vinfo(3) units as Newton meter-2 so that the output files have the correct metadata in the NetCDF attributes.

Surface fluxes of tracers are always output in units of tracer_units m/s. This is true also for the surface salt flux. It is not converted to an equivalent freshwater flux. The variable swflux is an input variable only. You can do the conversion yourself if you wish using a suitable surface salinity value. We do not do this conversion within ROMS because in order to perform a tracer budget analysis you would want fluxes in tracer units.

However, if you are using the BULK_FLUXES option, you can have the computed evaporation rate (in kg m/s) saved to the output file, and perform a freshwater budget calculation accordingly.

We don’t recommend mixing the units of state variables on input and output. A user could give an initial condition file with sea level zeta in centimeters by setting the scale to 0.01. The output history, averages, restart etc. files will nevertheless be written with zeta in units of meters. So you would want the Vinfo(3) string to reflect this. The risk here is that if you subsequently restart the model from one of these files, you would need to remember to re-set the scale for zeta in varinfo.dat.

Note also that in if you specify stresses or heat fluxes through analytical.F that they must be converted to kinematic units within analytical.F, i.e. stress in Pa must be divided by rho0, and heat fluxes by rho0*cp.

A nifty varinfo.dat trick

Vinfo(1) does not have to be unique. You can direct more than one variable index name (Vinfo(6)) to read the data from the same NetCDF variable in the input files. The scale entry let’s you apply different scaling to each.

Example: Suppose you wish to specify a constant value for the open boundary values for biological tracers. Rather than make a NetCDF file with data for all of NO3_west, NH4_west, phyt_west etc you could make a NetCDF file with a single variable named, say ones_west, which is filled with nothing but 1.0 for all time, s_rho and eta_rho.

In varinfo.dat, there must still be one entry for each unique index but you can have each entry point to the same ONES_west data. Assign the value you want for each variable in the scale entry. This scale will be multiplied by the 1.0 on input to set the open boundary values.

 'ONES_west'
  'ammonium western boundary condition'
  'millimole_nitrogen meter-3'
  'NH4_east, scalar, series'
  'NH4_time'
  'idTbry(iwest,iNH4_)'
  'nulvar'
  0.1d0          ! make all values equal to 0.1 millimole meter-3
!
 'ONES_west'
  'phytoplankton western boundary condition'
  'millimole_nitrogen meter-3'
  'phyt_west, scalar, series'
  'phyt_time'
  'idTbry(iwest,iPhyt)'
  'nulvar'
  0.08d0        ! make all values equal to 0.08 millimole meter-3