The OUTFILESFLAG control flag is used to activate configurable outputs specified via the 'outputs_balance.txt' input file.

This flag is an updated version of OUTFIELDSFLAG. The specification of the 'outputs_balance.txt' input file has changed since its initial implementation, though the older format of the file is still recognized by OUTFILESFLAG. The flag name was changed to prevent accidentally supplying the current 'outputs_balance.txt' file to older code which supports the former specification of the file. The current code still supports "OUTFIELDSFLAG" as an alias for "OUTFILESFLAG" and will accept both flag names.

Page contents:

1 Configuration
- 1.1 Available options
- 1.2 Behaviour without this option
2 outputs_balance.txt
- 2.1 File format
  - 2.1.1 General structure
  - 2.1.2 Inline comments
  - 2.1.3 Options of the form <option_name>=<value>
- 2.2 Available options
- 2.3 Field names
  - 2.3.1 Permafrost outputs
  - 2.3.2 Fill and spill outputs
- 2.4 File format
- 2.5 Frequency
  - 2.5.1 Note on accumulated outputs
  - 2.5.2 Note on output times
- 2.6 Other Options
  - 2.6.1 "csv" and "txt" format grid order
  - 2.6.2 "csv" and "txt" format leading date column
  - 2.6.3 Store outputs in memory
  - 2.6.4 WATFLOOD "FRAC" weighting
  - 2.6.5 GRU filtering
  - 2.6.6 Accumulation aggregators
  - 2.6.7 Basin-average values "basin_acc"
3 Output file format
- 3.1 Examples
4 Older versions

Configuration

Options with an equal sign (e.g., "pts=<M>") must be provided as a single word in the format "<option_name>=<value>" with no whitespace, such as tabs or spaces, separating the option name, equal sign, and value.

The flag is configured by adding "OUTFILESFLAG" with the "on" or "off" option in the list of control flags in MESH_input_run_options.ini:

##### Control Flags #####
----#
    1 # Number of control flags
OUTFILESFLAG             on

The number of control flags should be updated at the top of this section when adding the flag to existing setups.

Using the older "OUTFIELDSFLAG" flag name is also supported.

Available options

Option	Description	Supported since

Option	Description	Supported since
`0`	Disables the function.	r1401 - OUTFILESFLAG r599 - OUTFIELDSFLAG
`off`	Disables the function.	r1401 - OUTFILESFLAG
`1`	Enables the function.	r1401 - OUTFILESFLAG r599 - OUTFIELDSFLAG
`on`	Enables the function.	r1401 - OUTFILESFLAG

Behaviour without this option

Without activating OUTFILESFLAG or by omitting it from the list of control flags in MESH_input_run_options.ini is equivalent to listing the flag with the "off" option. The function is disabled by default.

`outputs_balance.txt`

The outputs_balance.txt input file contains the listing and configuration of options the model should write if OUTFILESFLAG is enabled. If the file does not exist while the function is enabled, it will stop with an error. If the file exists while the option is disabled, the file is not used.

File format

General structure

The outputs_balance.txt input file is an ASCII/text-based file that contains the list of variables to output, each with a specification that defines the output file format, at what frequency, and other options.

Field names and options should be separated by one or more tabs or spaces:

FIELDNAME option option option

The fields of the file are read in free format, such that spacing between field names and options does not matter.

The following three excerpts are equivalent:

FIELDNAME option option option

Inline comments

Lines are ignored if lead with a comment character of "!" or "#":

!this entry is ignored FIELDNAME option option option
FIELDNAME option option option

Full lines commented using "!" are supported using MESH 1.4.1204 and later. Full lines commented using "#" are supported using MESH 1.4.1254 and later.

Similarly, content following a comment character of "!" or "#" within a line is ignored:

FIELDNAME option option option !this text is ignored
FIELDNAME option option option !option - this option is ignored

Inline comments are supported using MESH 1.4.1204 and later.

Options of the form `<option_name>=<value>`

Options with an equal sign (e.g., "pts=<M>") must be provided as a single word in the format "<option_name>=<value>" with no whitespace, such as tabs or spaces, separating the option name, equal sign, and value.

The formatting of the below option will be properly recognized:

FIELDNAME option=value

The formatting of the below options may cause an error or will not configure the option as desired:

FIELDNAME option= value !this is not correct

FIELDNAME option = value !this is not correct

Available options

At a minimum, an output field must be defined with a field name, output file format and output frequency. Optionally, additional options can be specified.

This is the general structure of an output field:

<FIELDNAME> <file_format> <frequency> <other_options>

Field names

Any field name in the global "Variable List" can be specified as a field name. The field name is cAsE-sEnSiTive.

The change list contains notes if a variable name has changed and with what code version. This list will also note if the definition of the variable, for example, its units, has changed.

Permafrost outputs

Permafrost outputs require an HLSS to be enabled as they are derived from the TSOL model variable. Permafrost outputs are described here.

Fill and spill outputs

Fill and spill outputs require the process to be enabled. The fill and spill routine is experiment and is not yet described.

File format

Files can created in multiple output file formats. If the same field is desired in multiple output formats, they can be specified in the same line (with exceptions noted in the table).

Keyword	Format	Notes	Supported since

Keyword	Format	Notes	Supported since
r2c	EnSim Hydrologic (Green Kenue) rectangular cell (r2c) ASCII/text format		r599
seq	Binary sequential (seq) format
binseq	Binary sequential (seq) format
csv	Comma-separated (CSV) format	Outputs are written in the default "`gridorder`" sequence. The columns of the output are ordered from 1 to the maximum number of grid IDs in the domain (`NA`). For subbasin-based setups, ordered from 1 to the maximum number of subbasin IDs in the domain (`NA`).	r838
txt	Space-delimited (txt) format		r838
tsi `<grid_ids>`	Space-delimited text format file with *.ts extension	`<grid_ids>` should be a space-delimited list of grid IDs (`RANK`) within the range from 1 to the maximum number of grids in the domain (`NA`). The columns of the output are in the same order as specified in the list of `<grid_ids>`. The "`tsi`" option cannot be specified in the same line where a "`tsk`" option is already defined. To output both "`tsi`' and "`tsk`" outputs of the same variable, they should be specified as separate lines: `FIELDNAME <frequency> tsi 1 FIELDNAME <frequency> tsk 1`	r700
tsk `<tile_ids>`	Space-delimited text format file with *.ts extension	`<tile_ids>` should be a space-delimited list of tile IDs within the range from 1 to the maximum number of tiles in the domain (`NML`). The columns of the output are in the same order as specified in the list of `<tile_ids>`. The "`tsk`" option cannot be specified in the same line where a "`tsi`" option is already defined. To output both "`tsi`" and "`tsk`" outputs of the same variable, they should be specified as separate lines: `FIELDNAME <frequency> tsi 1 FIELDNAME <frequency> tsk 1`	r1204
`nc`	NetCDF format		r1630
`netcdf`
`nc4`
`r2c_binary`	EnSim Hydrologic (Green Kenue) rectangular cell (r2c) binary format	The text "`_binary`" is appended to the file name to distinguish this from the ASCII/text format of this output, such that the "`r2c_binary`" option will create an output file named '`<FIELDNAME>`_binary.r2c', while the "`r2c`" option will create an output file named '`<FIELDNAME>`.r2c'. Both the "`r2c`" and "`r2c_binary`" options can be specified for the same variable in the same line.	r1724
`r2c_bin`			r1724

Frequency

The frequency option specifies the output interval, after how much simulation time the output is written to file. More than one frequency can be specified per line. The same frequency should not be repeated more than once per line.

Frequency	Description	Reset	Notes	Supported since

Frequency	Description	Reset	Notes	Supported since
`Y`	Yearly output	From the first calendar day of the year		r1254 - universal r599 - variable and file format specific
`M`	Monthly output	From the first day of the month
`S`	Seasonal output (monthly averages)	From the first day of the month
`D`	Daily output	From the first hour of the day		r1254 - universal r662 - variable and file format specific
`H`	Hourly output	From the first model time-step in the hour		r1254 - universal r662 - variable and file format specific
`pts=<M>`	Per specified time-step, where `<M>` defines the interval in minutes	After the specified interval <M> has elapsed since the first model time-step	The "`pts=`" option requires the specification of an accumulation aggregator. If no aggregator is specified, "`AVG`" is assumed by default.	r1640

Note on accumulated outputs

Whether accumulated as an average value or sum over the specified time steps, the model resets the counter at the time of the specified "Reset" column in the above table. This means, the first yearly "Y" output from a run that started September 1 may not compare to values in the record for subsequent years, as those values account for a full calendar year while the first value accounts only for the period elapsed from September 1 to the end of that calendar year. The same can be said for averages of daily "D" outputs when the first day of a run started at 18:00 hours; the first value in the series will only account for hours 18:00 to midnight from the first simulation day while subsequent values would be for full simulation days.

The model does not shift the "Reset" interval to correspond to the first time step in the simulation.

Seasonal "S" outputs are an average of the monthly averages over the entire simulation period. The output will contain only 12 frames, one for each calendar month in the year. The value of the frame corresponds to the average of all monthly averages of that month in the simulation period. For example, in a simulation period that spans 4 complete calendar years from 2002 to 2005, the first frame would be the average of January 2002, January 2003, January 2004, and January 2005 monthly averages, the second frame of February 2002, February 2003, and February 2004. February 2005 monthly averages, and so on.

Note on output times

The hour and minutes in a time label in the outputs correspond to the beginning of the time interval; however, the data is representative of the variable at the end of the time interval. This is done for compatibility with certain data viewers, which label hour 24:00 of the current simulation day as hour 00:00 of the next simulation day, so the date printed to file is consistent with the date shown in visual outputs on the screen. Consequently, hours in these outputs range from 00:00-23:00 instead of from 01:00-24:00.

Likewise, the time-stamp of outputs of higher time intervals may print the first hour, day or month of the interval, though the data is again representative of the variable over the entire course of the interval. For example, yearly output with the date "2002/01/01 00:00" is representative of the full calendar year of data, from the beginning of January 1, 2002, to the end of December 31, 2002. Monthly output with the date "2002/01/01 00:00" is representative of the full month of data, from the beginning of January 1, 2002 to the end of January 31, 2002.

Other Options

"`csv`" and "`txt`" format grid order

The "csv" and "txt" output options support optional keywords to control the order of data written to file. If neither keyword is specified "gridorder" is assumed by default. For subbasin-based setups, the two options are equivalent.

Option	Description	Notes	Supported since

Option	Description	Notes	Supported since
`gridorder` (default)	Values are printed in the same order as the grid ID ranking in the domain, from 1 to the maximum number of grids in the domain (`NA`).	If the "`tsi`" or "`tsk`" option is defined in the same line, these options have no effect and "`gridorder`" is assumed by default.	r838
`shedorder`	Values are printed as the full square grid domain would printed, such as the 2D grid printed for the "`r2c`" output format, as a single line by order of rows.		r838

"`csv`" and "`txt`" format leading date column

The "csv" and "txt" output options support optional keywords to control if the leading date column is printed to the output file. If none of these keywords are specified, the leading date column is printed to the file by default.

Option	Description	Supported since

Option	Description	Supported since
`print_date` (default)	Print the leading date column to the file. The second column in the file contains data.	r838
`printdate`
`no_date`	Suppress printing the leading date column to the file. The first column in the file contains data.

Store outputs in memory

The "in_mem" option can be activated to store outputs in memory. In this case, output is only written to file at the end of the simulation. By default, the option is disabled.

Option	Description	Notes	Supported since

Option	Description	Notes	Supported since
`in_mem`	Store outputs in memory. The outputs are only written to file at the end of the simulation.	Only supported if the simulation start and stop dates are explicitly specified in MESH_input_run_options.ini. This option has no effect with the "`pts=`" option.	r1254

WATFLOOD "`FRAC`" weighting

The "apply_frac" option can be used to apply the WATFLOOD "FRAC" weighting to gridded outputs. This multiplies outputs by the inflated or deflated fractional area attributed by the Green Kenue processing to represent subbasin attributes inside the square-grid representation of the domain.

Option	Description	Supported since

Option	Description	Supported since
`apply_frac`	Apply the WATFLOOD "FRAC" weighting to gridded outputs.	r1256
`frac`	Apply the WATFLOOD "FRAC" weighting to gridded outputs.	r1256

GRU filtering

GRU filtering can be used to control the GRUs that actively contribute to the grid-average values written for gridded outputs. Enabling GRU filterting allows writing gridded outputs filtered by specific GRUs.

Option	Description	Notes	Supported since

Option	Description	Notes	Supported since
`gru <gru_id>`	Filter gridded outputs to consider only the GRU specified by `<gru_id>`.	`<gru_id>` must be the ID of only 1 GRU. If multiple GRU IDs are listed, only the first is considered. To filter by multiple GRUs, consider the "`gru_include`" or "`gru_exclude`" options.	r1381
`gru_include <gru_ids>`	Filter gridded outputs to exclude the GRU(s) specified by `<gru_ids>` when aggregating grid-average values.	`<gru_ids>` should be a space delimited list of GRU IDs within the range from 1 to the maximum number of GRUs in the domain (`NTYPE`).
`gru_exclude <gru_ids>`	Filter gridded outputs to include the GRU(s) specified by `<gru_ids>` when aggregating grid-average values.

Accumulation aggregators

Accumulation aggregators control the mechanism by which variable values are accumulated over the output interval. The options are only supported with the "pts=" option. If specified with the other output interval options, these options have no effect.

As with the "pts=" option, only one aggregator can be specified per line. If no aggregator is specified, the "AVG" aggregator is assumed by default.

These options are not case-sensitive.

Option	Description	Supported since

Option	Description	Supported since
`ACC`	Accumulated over the time period.	r1640
`CUM`
`SUM`
`AVG`	Averaged over the time period.
`MAX`	The maximum value in the time period.
`MIN`	The minimum value in the time period.
`VAL`	The instantaneous value at the end of the time period.

The "CUM" and "AVG" options were previously supported for Y, S, M, and D outputs but depreciated with MESH 1.4.1254. The "CUM", "AVG", "MAX", and "MIN" options were previously supported for H outputs for the "r2c" output option, but also depreciated in MESH 1.4.1254. A warning to this effect was added in MESH 1.4.1381. The warning and these options are no longer supported for any frequency interval except with the "pts=" option.

Basin-average values "`basin_acc`"

The "basin_acc" option prints basin-average values instead of the typical grid-point average values for gridded outputs.

Basin-average values are accumulated as a function of the contributing area of the cell following the flow directions defined by RANK/NEXT. These are the same sort of outputs printed to the "basin-average" CSV outputs, except they can be printed for any location within the domain.

The output of basin-average values does not support GRU filtering.

Option	Description	Supported since

Option	Description	Supported since
`basin_acc`	Print basin-accumulated grid values.	r1727

Basin-average outputs may not be representative if the domain contains improperly ordered RANK and NEXT. Warnings are printed at the beginning of a run if this is the case:

WARNING: NEXT might be upstream of RANK (NEXT <= RANK) at RANK 19.

Basin-average values are calculated as follows:

basin_frac = FRAC
basin_val = grid_val
do i = 1, NAA
  ii = NEXT(i)
  if (ii .gt. 0 .and. FRAC(i) .gt. 0.0) then
    basin_frac(ii) = basin_frac(ii) + basin_frac(i)
    basin_val(ii) = basin_val(ii) + basin_val(i)
  end if
end do
where (basin_frac .gt. 0.0)
  basin_val = basin_val/basin_frac
end where

FRAC, NEXT and NAA are fields and attributes read from the basin information file.

Output file format

Output files created by OUTFILESFLAG follow a common structure:

<FIELDNAME>_<FREQ>[_<FN>][_<VN_IG><IG>][_basin_acc][_not][_<VN_GRU><GRU>][_binary].<ext>

Terms denoted within square brackets are only appended depending on the options enabled for the output field.

Term	Description

Term	Description
`<FIELDNAME>`	Name of the output variable, corresponding to its definition in the variable list for that particular version of the code.
`<FREQ>`	Character string denoting the output frequency (the same as the input option, except for "`pts=`" for which the out label is "`PTS-<M>M`", where `<M>` is the frequency specified in minutes from the configuration option).
`<FN>`	Character string that denotes the aggregation function used for the variable. Only printed if the output frequency is specified using the "`pts=`" option.
`<VN_IG>`	Character string that denotes a layer. Only printed if the output field contains layers. MESH 1.4.1381 and later print "`IG`", earlier versions do not use this label.
`<IG>`	Layer number/ID, only printed if the output field contains layers. Printing outputs when the number of soil layers is greater than or equal to 10 is only supported using MESH 1.4.1204 and later.
`<_basin_acc>`	Only appended if the "`basin_acc`" option is enabled for the output field.
"`_not`"	Only appended if the "`gru_exclude`" option is enabled for the output field.
`<VN_GRU>`	Character string that denotes a GRU. Only printed if GRU filtering is enabled for the output field. MESH 1.4.1381 and later print "`GRU`".
`<GRU>`	GRU ID, only printed if GRU filtering is enabled for the output field.
"`_binary`"	Only appended if the output format is specified by the "`r2c_binary`" or "`r2c_bin`" options.

Examples

If the MESH setup contains 3 soil layers, the following output field definition will create output files named: TSOL_H_IG1.r2c, TSOL_H_IG2.r2c, TSOL_H_IG3.r2c

TSOL H r2c

The following output field definition will create two files of the same output field in two difference file formats using the names: TA_D.csv, TA_D.seq

TA D csv seq

The following output field definition will create the following output file name: LQWS_PTS-30M_AVG_GRU4_binary.r2c

LQWSSOL pts=30 AVG r2c_binary gru_include 4

If the domain contains at least 27 grids, the following output field definition will create output files names: ROFTOT_D_basin_acc.ts, QO_H.ts QO_D.ts

ROFTOT D tsi 13 14 27 basin_acc
QO H D tsi 13 14 27

Older versions

The following information is superseded by information in the above sections. These details are provided for reference only.

The following notes apply to older MESH versions. If accommodations for the items that are detailed below appear in an existing outputs_balance.txt file, they can be removed when moving to a more recent code version. In most cases however, these items are simply ignored by newer code if left in the file.

Versions previous to MESH 1.4.1256 applied the WATFLOOD "FRAC" weighting to outputs by default, which can inflate and deflate values when compared to other spatially gridded products. MESH 1.4.1256 and later produce outputs without any weighting applied. The "FRAC" weighting can be optionally applied using the "apply_frac" option for gridded outputs.

MESH 1.4.1254 and later includes optimizations such that all recognized output variables support all of the same options.

Versions previous to MESH 1.4.1254 split the variables supported for hourly output (H) and the other supported output frequencies (Y, S, M, D). In these versions, if the following output variable is supported, it supports only the noted output frequencies:

Field name	Description	Units	Y	S	M	D	H

Field name	Description	Units
`PREC`	Precipitation (liquid and frozen)	mm
`EVAP`	Evapotranspiration	mm
`ROF`	Total runoff (includes: overland flow, sub-surface flow/interflow, and baseflow)	mm
`RCAN`	Rain intercepted by the canopy	mm
`SNCAN`	Snow intercepted by the canopy	mm
`PNDW`	Water ponded at the surface of the soil	mm
`SNO`	Snowpack above the soil	mm
`WSNO`	Water contained in the snowpack	mm
`LQWS`	Liquid water stored in the soil (for all soil layers)	mm
`FRWS`	Frozen water stored in the soil (for all soil layers)	mm
`STG`	Total water stored in the system	mm
`GFLX`	Heat conduction between the soil layers (all layers)	W m**-2
`HFS`	Total sensible heat flux over the surface of the soil	W m**-2
`QEVP`	Total latent heat flux over the surface of the soil	W m**-2
`TBAR`	Average temperature of the soil (all layers)	K
`THLQ`	Volumetric liquid water content of the soil (all layers)	m3 m-3
`THIC`	Volumetric frozen water content of the soil (all layers)	m3 m-3
`FSDOWN`	Total incoming shortwave radiation	W m**-2
`FSVH`	Visible shortwave radiation	W m**-2
`FSIH`	Near-infrared shortwave radiation	W m**-2
`FDL`	Incoming longwave radiation	W m**-2
`UL`	Average wind velocity	m s**-1
`TA`	Air temperature	K
`QA`	Specific humidity	kg kg**-1
`PRES`	Surface air pressure	Pa
`PRE`	Surface precipitation rate	mm s**-1
`WR_RUNOFF`	Runoff (includes: overland flow and sub-surface flow/interflow)	mm
`WR_RECHARGE`	Baseflow	mm

The above table contains variables names, descriptions and units used in older versions of the code. These names may be different in the current variable list. Further, name changes or if the definition of the variable, for example, its units, has since changed, it will be noted on the variable list update page.

WR_RUNOFF and WR_RECHARGE are outputted as depths in (mm) not rates (mm/s). If these are used to force the model in routing mode only (e.g. RUNMODE nolss runrte), the time step has to be set to 1 hour as they are hourly depths.

Versions previous to MESH 1.4.1254 require the first line in the file to specify the output folder and the second line in the file to define the number of fields in the file:

'Out_Fields/'
    1 # Number of variables for output
FIELDNAME1 <options>

MESH 1.4.1254 and later will write outputs to the default output folder specified in MESH_input_run_options.ini and scan the file for all recognized output fields. If the configuration file is of the older format, where the first two lines specify the output folder and number of fields in the file respectively, the lines will be read but those specifications will be ignored.

MESH 1.4.1254 and later support the specification of multiple general file formats per line. Versions previous to MESH 1.4.1254 only support one file format per line. If more than one format is listed in a line, only the last-most in the list is used to specify the output file format:

FIELDNAME txt !the output file format is r2c

FIELDNAME txt seq !the output file format is seq

Versions after MESH 1.3.700 scan all words following the field name looking for valid options. MESH 1.3.662 through MESH 1.3.700 require a number that specifies how many options to read following the field name:

FIELDNAME 6 option1 option2 option3 option4 option5 option6

MESH User Support

OUTFILESFLAG

Configuration

Available options

Behaviour without this option

`outputs_balance.txt`

File format

General structure

Inline comments

Options of the form `<option_name>=<value>`

Available options

Field names

Permafrost outputs

Fill and spill outputs

File format

Frequency

Note on accumulated outputs

Note on output times

Other Options

"`csv`" and "`txt`" format grid order

"`csv`" and "`txt`" format leading date column

Store outputs in memory

WATFLOOD "`FRAC`" weighting

GRU filtering

Accumulation aggregators

Basin-average values "`basin_acc`"

Output file format

Examples

Older versions

Related content

OUTFILESFLAG

Configuration

Available options

Behaviour without this option

outputs_balance.txt

File format

General structure

Inline comments

Options of the form <option_name>=<value>

Available options

Field names

Permafrost outputs

Fill and spill outputs

File format

Frequency

Note on accumulated outputs

Note on output times

Other Options

"csv" and "txt" format grid order

"csv" and "txt" format leading date column

Store outputs in memory

WATFLOOD "FRAC" weighting

GRU filtering

Accumulation aggregators

Basin-average values "basin_acc"

Output file format

Examples

Older versions

Related content

`outputs_balance.txt`

Options of the form `<option_name>=<value>`

"`csv`" and "`txt`" format grid order

"`csv`" and "`txt`" format leading date column

WATFLOOD "`FRAC`" weighting

Basin-average values "`basin_acc`"