+

VELMA Forest-Burn LSR Disturbance Model

Introduction

VELMA version 2.2.0.0 includes a new disturbance type called "Forest Burn LSR".
Simulation configurations can include parameterizations for this disturbance to mimic the effects of burning on VELMA's core LSR ([L]eaf [S]tem [R]oot) biomass and detritus data pools.

The Forest Burn disturbance does not simulate fire itself. Fire propagation, extent, intensity, etc. are not subjects addressed by the the Forest Burn disturbance. Its sole focus is making changes (reductions and transfers) to the LSR pools at specific times and locations during a VELMA simulation run. Configuring a Forest Burn disturbance for a VELMA simulation presupposes that applicable fire data already exists and is available for use.

Forest Burn disturbance paremeterizations specify when (what steps during a simulation run) and where (which cells of the simulation grid) burning occurs, the fractional reduction the burning incurs upon VELMA's LSR pools, and the fractions of burned matter that are volatilized.
The values necessary to inform a Forest Burn parameterization must be derived from preexisting fire data, either collected from actual fire events or simulated via a fire model/simulation.

The Forest Burn disturbance provides two distinct scheduling strategies for parameterizing when and where burn-reduction of the LSR pools occurs:

Both strategies employ the same paramterization scheme to specify reduction fractions, and the same mechanism to reduce and transfer LSR pool amounts. They only differ in how they allow specifying when and where burn-reduction occurs.

A single simulation configuration may contain multiple Forest Burn disturbance parameterization groups, and each parameterization goup may be either a ForestBurnLsrDisturbanceModel or a HistoricalForestBurnLsrDisturbanceModel. This allows fairly complicated scheduling patterns, but users should strive to use as few disturbance parameterization groups per simulation as possible, to reduce overall simulation configuration complexity.

Forest Burn disturbances cannot apply cell-specific reduction fractions: every cell affected by a given parameterization group is burn-reduced using the same set of reduction fractions. Adding multiple Forest Burn disturbance parameterization groups to a simulation permits different reduction fractions, but is not satisfactory way of achieving fine-grained, per-cell burn-reduction specification. As discussed later in this document, adding more than a few Forest Burn disturbance parameterization groups to a single simulation configuration rapidly becomes problematic. VELMA does not permit users to specify the order in which disturbances are applied within a single simulation step. If two Forest Burn disturbances target the same cell location in the same step, the user cannot determine which occurs first. Also, care must be taken when reviewing reported (some) results because all Forest Burn disturbance write burn-specific results map data to a shared set of .asc files.

Mechanism Overview

A Forest Burn disturbance affects VELMA LSR pools at each eligible cell in the following ways:

ABOVE-GROUND BIOMASS

The Biomass Leaf and Biomass Above-Ground Stem pools amounts are reduced, and the reduction amount is further split into transferred and removed portions based on pool-specific burn and volatilized fraction parameters.
The sequence for each pool is:

  1. pool burned amount = (pool initial amount * pool burn fraction)
  2. pool volatilized amount = (pool burned amount * pool volatilized fraction)
  3. pool transferred amount = (pool burned amount - pool volatilized amount)
  4. pool final amount = (pool initial amount - pool burned amount)

Volatilized amounts are removed from the simulation state.

Transferred amounts are added to pool-specific, corresponding detritus pools:

The transfers from biomass to detritus specified above occur AFTER the detritus reductions specified below.

ABOVE-GROUND DETRITUS

The Detritus Leaf and Detritus Above-Ground Stem pools are reduced, and the entire reduction amount is considered volatilized and is removed (i.e. "lost") from the simulation state.
The sequence for each pool is:

  1. pool burned amount = (pool initial amount * pool burn fraction)
  2. pool volatilized amount = pool burned amount
  3. pool final amount = (pool initial amount - pool burned amount)

BELOW-GROUND BIOMASS

The Biomass Below-Ground Stem and Biomass Root pools are reduced, and the entire reduction amount is transferred to a corresponding detritus pool. The sequence for each pool is:

  1. pool burned amount = (pool initial amount * pool burn fraction)
  2. pool transferred amount = pool burned amount
  3. pool final amount = (pool initial amount - pool burned amount)

Transferred amounts are added to pool-specific, corresponding detritus pools:

(The "root fraction for Layer" is the cover-specific, layer-specific Gale-Grigal root fraction value.)

Scheduling Overview

As stated in the introduction, the Forest Burn disturbance provides two different ways to parameterize scheduling, but both ways require specifying when (simulation steps) and where (cell locations within the simulation's delineated watershed) burn-reduction activity will occur. During a simulation run, VELMA keeps track of where and when burn-reduction should occur, and applies the burn-reduction mechanism to each specified cell location at each specified simulation step, as one of the last actions performed for the step. (I.e. after water balance, water transfer, and Plant-Soil interactions have occurred.)

A simulation that configures disturbance parameter groups so that two or more disturbances occur at the same simulation step cannot specify the order in which the disturbances are applied for that step. The order in which VELMA applies any disturbances specified (Harvest, Fertilize, Burn, etc.) is arbitrary and depends upon factors within VELMA's initialization mechanisms.

Note: there are a couple of caveats to the cannot-specify-order rule:

  1. Water Drain disturbances are applied during a given simulation step at a point completely apart from any other disturbances.
    (And, multiple Water Drain disturbances still cannot be explicitly ordered relative to each other.)
  2. Disturbances that provide pool initialization functions may be parameterized to occur at the start, rather than the end of the simulation step.
    (Again, however, they cannot be explicitly ordered relative to other disturbances.)

However, neither of the above caveats apply for Forest Burn Disturbances.

The details of how to specify exactly which simulation steps and cell locations are affected by a Forest Burn disturbance are given in the next of this document.

Adding a Forest Burn Disturbance to a Simulation Configuration

Preliminary Considerations

Fire Data

Before adding a Forest Burn disturbance to a VELMA simulation configuration, you must have data from a fire. The fire data may be from any source: an actual event, a hypothetical event, or output from a fire simulation, but it should be relevant for your VELMA simulation site, and must provide you with enough information for you to decide:

Deciding Which Scheduling Type to Use

Once you have determined "when", "where" information from fire data, you can decide which Forest Burn disturbance to use.
The ForestBurnLsrDisturbanceModel is typically simpler to configure than the HistoricalForestBurnLsrDisturbanceModel, and should be the default selection. However, if your fire data presents you with many, smaller, disjoint areas, affected by burning, the latter option may result in a clearer configuration.

Adding the Disturbance to the Configuration

Begin with either a pre-existing VELMA simulation configuration loaded into JVelma, or by create a new configuration from within JVelma (via the Edit -> "Create a New, Empty Configuration" menu item).

Next, click the Edit -> "Disturbances" -> "Add Disturbance" menu item. This will open the "Specify Disturbance Model Type and Name" popup dialog box.

In the dialog box, set the Disturbance Type by selecting either ForestBurnLsrDisturbanceModel or HistoricalForestBurnLsrDisturbanceModel from the drop-down list.

Enter a name in the disturbance in the "Disturbance Name" text field. The name should be composed only of alpha-numeric characters and (optionally) underscore or dash characters. Do not use whitespace (blank or tab) or punctuation characters (e.g. comma, colon, or semicolon). The name must be unique from the names of any other disturbances already added to the simulation configuration.

Click the dialog box's [ OK ] button to confirm and add a parameterization group for the type of Forest Burn disturbance you selected. JVelma then shifts display focus to the "All Parameters" tab, and filters the rows of the parameters table to those specific to your newly-added disturbance.

Common Parameters

Regardless of the scheduling type of Forest Burn disturbance added, the following parameters always occur as part of the parameterization group.

Parameters That Can (Should!) Be Left Alone

The modelClass parameter is set by JVelma when you add the contaminant to the simulation configuration. Do Not Change this parameter's value. Ever.

Paremeters That Specify Burn Effects

The following parameters determine the fractions that a Forest Burn disturbance employs to calculate the amounts of biomass or detritus burned at a given cell location and simulation step.

biomassAgStemNburnFraction
biomassAgStemNvolatilizedFraction
biomassBgStemNburnFraction
biomassLeafNburnFraction
biomassLeafNvolatilizedFraction
biomassRootNburnFraction
detritusAgStemNburnFraction
detritusLeafNburnFraction

All of the above parameters must be provided decimal values in the range [0.0, 1.0]. Their names start with the pool name they are for, and end in ...burnFraction or ...volatilizedFraction, depending upon whether they represent the fraction of existing amount burned, or the fraction of the burned amount volatilized. See the Mechanism Overview section of this document for details of the burn-reduction calculations.

The initializeAgeModification parameter specifies what happens to a cell's age value after burn reduction occurs at the cell's location. The parameter's value indicates the number of integer years to add to, subtract from, or set for the cell's age.

Examples:

initializeAgeModification Meaning
0 Set the cell's age to 0.
+0 Add 0 to the cell's age (i.e. do not change the cells age at all).
+5 Add 5 years to the cell's age.
-7 Subtract 7 years from the cell's age. Cell's resulting age will be 0 if original value is less than 7.
9 Set the cell's age to 9.

Parameters That Control Results Reporting

When the enableAutomaticSpatialReporting is set True, the Forest Burn disturbance will write .asc map files to the simulation's specified Results folder. Maps are written for each simulation step in which burn-reductions occur, and provide cell-specific data about burn amounts. Setting this parameter False suppresses writing the output maps. Set the Results Reported section later in this document for additional details.

WARNING: Any and all burn disturbances configured within the same simulation configuration write to the same set of .asc output files.
When two or more burn disturbances write data to an .asc output file on the same day, succesive burn disturbances overwrite prior burn disturbance values in burn-specific maps. Keep this in mind if you must schedule two or more burn disturbances to occur at the same step and location.

When the trimOutputToWatershedBoundary parameter is True, output maps written are the size (ncols and nrows) of the bounding rectangle of the simulation's delineated watershed. When set to False, output maps dimensions match the simulation's DEM map. This parameter is ignored when enableAutomaticSpatialReporting is set False.

Parameters Specific to ForestBurnLsrDisturbanceModel

Burn-reduction affects cell locations only when and where all of the values specified in the following parameters are true.

Parameters That Specify When Map-Based Burning Occurs

The ageThreshold selects cell locations for burn-reduction based on the cell-specific age (in years) value that VELMA tracks for each cell in the simulation's delineated watershed. The parameter accepts either a single integer, or a comma-delimited sequence of dash-separated min-max integer range pairs.

Examples:

ageThreshold Meaning
0 All otherwise-eligible cell location remains eligible (because any cell has age zero more).
60 Only otherwise-eligible cell locations with age >= 60 remain eligible.
60-60 Only otherwise-eligible cell locations with age == 60 remain eligible.
10-50 Only otherwise-eligible cell locations with age in the range [10, 50] remain eligible.
10-50, 75-100 Otherwise-eligible cell locations with age in the range [10, 50] or [75, 100] remain eligible.

The next three parameters all accept either a single integer value, or a comma-separate list of integer values and/or integer range pairs.

The initializeActiveLoops parameter specifies the simulation loop index numbers during which burn-reduction can occur. A valid loop index is an integer between 1 and the number of loops (numberOfLoops parameter) specified for the simulation. Values outside the valid range are ignored.

Examples: (assuming numberOfLoops is set to 10)

initializeActiveLoops Meaning
3 Burn reduction can only occur during loop 3.
3, 5, 9 Burn reduction can only occur during loops 3, 5, and 9.
3-9 Burn reduction can only occur during loops 3 through 9.
1, 4-6, 10 Burn reduction can only occur during loops 1, 4 through 6, and 10.

The initializeActiveYears parameter specifies the years of the simulation run when burn-reduction can occur. Valid values for this parameter must be fully-specified year integers (e.g. 1992 not 92) that are within the range specified by the simulation's start and end year ([syear, eyear]) parameter values. Values outside the valid range are ignored.

Examples: (assuming [syear, eyear] are set to [1990, 2005])

initializeActiveYears Meaning
1990 Burn reduction can only occur during simulation year 1990.
1990, 1995 Burn reduction can only occur during simulation years 1990 and 1995.
1990-1995 Burn reduction can only occur during simulation years 1990 through 1995.
1990, 2000-2004, 2005 Burn reduction can only occur during simulation years 1990, 2000 through 2004, and 2005.

The initializeActiveJdays parameter specifies the Julian days of each simulation year when burn-reduction can occur. Valid values for this parameter must be integers between 1 and 366 (366 is used to indicate the "extra" day of a leap year). Values outside the valid range are ignored.

Examples:

initializeActiveJdays Meaning
60 Burn reduction can only occur on the 60th day of a year.
1, 90, 180 Burn reduction can only occur on Julian days 1, 90, and 180 of a year.
1, 365-366 Burn reduction can only occur on the first and last days of non-leap years, and the last two days of leap years.
1-366 Burn reduction can occur on every day of a year.

Keep in mind the effect of leap years when translating calendar dates to Julian days. For example: "the 60th day of the year" maps to either the last day of February or the first day of March.

Parameters That Specify Where Map-Based Burning Occurs

The initializeCoverIds specifies a comma-separated sequence of integer cover ID values. Only valid cover IDs specified in this list are eligible for burn-reduction. Valid cover IDs must correspond to integer values present within the cover map specified by the simulation's coverSpeciesIndexMapFileName, and by a uniqueId parameter in one of the simulations CoverSpecies parameter groups. Valid cover IDs must also be present at cell locations within the delineated watershed, i.e. even if a cover ID exists in the cover map and for a CoverSpecies, it isn't valid for a burn disturbance unless some cells within the watershed are of that cover type.

The filterMapFullName allows users to specify Grid ASCII .asc map file containing (integer) filter ID values.
If the value of this parameter is not a fully-qualified path and file name, VELMA will prefix the specified input data location root and name to this parameter's value to create a fully-qualified name. (I.e. partially-specified file names are assumed to be relative to the simulation's input data location.)
If the value of this parameter is left blank, filtering by it is deactivated (and this is the default behavior). When specified the filter map provides a second layer of arbitrary ID values used in conjunction with the initializeFilterIds parameter. The .asc map file specified must match the header information of the simulation's specified DEM grid.

The initializeFilterIds specifies a sequence of comma-separated filter ID values. Only valid filter IDs specified in this list (AND in the cover IDS list) are eligible for burn-reduction. Valid filter IDs must correspond to integer values present within the Grid ASCII .asc map file specified by filterMapFullName. If filterMapFullName is left blank, filtering is deactivated, and this parameter is ignored.

Parameters Specific to HistoricalForestBurnLsrDisturbanceModel

With the exception of initializeActiveLoops, the HistoricalForestBurnLsrDisturbanceModel does not have parameters that specify when and where burn-reduction occurs. Instead, it requires the user to specify when-and-where information in a .csv file, and contains parameters to specify that file, and how it should be loaded.

The initializeActiveLoops parameter specifies the simulation loop index numbers during which burn-reduction can occur. A valid loop index is an integer between 1 and the number of loops (numberOfLoops parameter) specified for the simulation.
This parameter is common to both Forest Burn disturbance scheduling styles -- see its description in the ForestBurnLsrDisturbanceModel section above for details and examples of its use.

The initializeHistoricalData parameter specifies the path and name of the .csv file containing the when-and-where burn-reduction occurs. If the value of this parameter is not a fully-qualified path and file name, VELMA will prefix the specified input data location root and name to this parameter's value to create a fully-qualified name. (I.e. partially-specified file names are assumed to be relative to the simulation's input data location.)
The contents and format required for the .csv file are described in the next section of this document.

The enableFullDataBuffer parameter specifies how the HistoricalForestBurnLsrDisturbanceModel loads the .csv file data. When set to True, VELMA will read the entire contents of the .csv data file into memory once, at the start of the simulation run. No additional data-reads from the file are performed during the simulation run. This reduces the simulation running time, but increases the memory used by the simulator during the entire simulation run.
When set to False, VELMA reads the .csv data file multiple times, at the start of each simulation year, and stores only the current year's data into memory. This increases simulation running time, but decreases the memory used by the simulator during the entire simulation run.

Note: unless your .csv data file is quite small (e.g. less than 500 rows of data), or you are absolutely certain you will not incur and out-of-memory error, set this parameter's value to False.

Historical Data File Format Details

The file specified by the initializeHistoricalData parameter must contain comma-separated-values data. The file must contain one row of data for each cell were burn-reduction should occur. Each row in the file must contain a cell id (linear index number), followed by a sequence of year and Julian day-or-range paired values. Rows are not required to all have the same number of year and Julian day paired values, but each row must start with a valid cell id, followed by at least one year value and one Julian day-or-range value. This permits each cell to potentially have its own, unique "burn schedule".

Note: the file should not contain a header row.

The format of a row in the data file is:

cellID,Year,JdayOrRange[,Year,JdayOrRange ...]

Note: whitespace on either side of the commas separating the data value is strongly discouraged.
Note: rows in the file must not end in a comma.

The cellID must be an integer, and its value must be the linear index of a cell that is within the simulation's delineated watershed.

Year values must be full-year integers: e.g. 1995 not 95.

JulianDayOrRange values must be either a single integer value (a Julian Day) or two integer values separated by a dash (-) character (a Julian Range).

Example File Contents:

1070,1995,60,1995,120
1300,1995,60,1995,90-220,1996,120
2105,2000,210-214

The 3 rows of csv data above specify three cell locations and when burn-reduction occurs for each of the three.

Results Reported for Forest Burn Disturbances

Daily Results

The effects of Forest Burn disturbances are reflected in the values of the various BIOMASS and DETRITUS results columns of the DailyResults.csv file, and the files that are derived from it (i.e. AnnualResults.csv, and Combined_DailyResults.csv).

The DailyResults.csv file also records burn-reduction amounts in the values of the cover-specific "Disturbance_N_Removed" columns:

_Disturbance_N_Removed(gN)_Cover_Total
_Disturbance_N_Removed(gN/m2)_Cover_Average
_Disturbance_N_Removed(gN/m2)_Delineated_Average
_Disturbance_N_Removed_Cell_Count_Cover_Total

Where is the uniqueName of a CoverSpecies parameterized for your simulation.

However, be aware that these columns record any disturbance-related reductions. If, for example, your simulation configuration has parameterized both a Harvest disturbance and a Forest Burn disturbance, the reductions for both will appear in these columns. You must note the simulation timing information (in the Loop, Step, Year, and Jday columns) and know when your disturbances will occur to determine which values represent which disturbances.

Cell Data Writers

Cell Data Writer files written for simulation configurations that include Forest Burn disturbances report burn amount in the following columns:

Burned_Biomass_Leaf_C
Burned_Biomass_Ag_Stem_C
Burned_Detritus_Leaf_C
Burned_Detritus_Ag_Stem_C
Burned_Ash_Amount_N
Burned_AG_Total_N
Burned_Volatilized_Amount_N

Note: Forest Burn disturbances always set the Burned_Ash_Amount_N map containing only zeroes: this data column for Forest Burn results.
Forest Burn is required by VELMA implementation details to write the Burned_Ash_Amount_N data column, but the file contents are for a different type of disturbance.

Cell Data Writer files also record burn-reduction amounts in the values of the "Disturbanc_N_Removed" columns:

Disturbance_N_Removed_Layer1
Disturbance_N_Removed_Layer2
Disturbance_N_Removed_Layer3
Disturbance_N_Removed_Layer4

However, be aware that these columns record any disturbance-related reductions. If, for example, your simulation configuration has parameterized both a Harvest disturbance and a Forest Burn disturbance, the reductions for both will appear in these columns. You must note the simulation timing information (in the Loop, Step, Year, and Jday columns) and know when your disturbances will occur to determine which values represent which disturbances.

Spatial Data Results

When one or more Forest Burn parameter groups set enableAutomaticSpatialReporting as True, the VELMA simulator writes a collection of spatial data .asc map files for each day that any burn-reduction occurs.

Be aware that any and all burn disturbances configured within the same simulation configuration write to the same set of .asc output files.
When two or more burn disturbances write data to an .asc output file on the same day, succesive burn disturbances overwrite prior burn disturbance values in burn-specific maps. Keep this in mind if you must schedule two or more burn disturbances to occur at the same step and location.

The files are written to top-level results location directory specified by the simulation configuration, and have the following filename format:

Spatial_BURNED__ALL___.asc

Where:

Example: The filename Spatial_BURNED_BIOMASS_AG_STEM_C_ALL_1_2003_181.asc has:

The data types reported are:

data units Description
AG_TOTAL_N grams (Nitrogen) Total Above-Ground amount burned from cell (BIOMASS and DETRITUS pools).
ASH_AMOUNT_N grams (Nitrogen) Unused! (You may ignore this map file.)
BIOMASS_AG_STEM_C grams (Carbon) Amount burned from BIOMASS_AG_STEM pool.
BIOMASS_LEAF_C grams (Carbon) Amount burned from BIOMASS_LEAF pool.
DETRITUS_AG_STEM_C grams (Carbon) Amount burned from DETRITUS_AG_STEM pool.
DETRITUS_LEAF_C grams (Carbon) Amount burned from DETRITUS_LEAF pool.

Note: Forest Burn disturbances write an ASH_AMOUNT_N map containing only zeroes: ignore this map file when reviewing Forest Burn results.
Forest Burn is required by VELMA implementation details to write the ASH_AMOUNT_N file, but the file contents are for a different type of disturbance.

All the Spatial_BURNED_ files that VELMA writes will have the same dimensions as the DEM grid specified for the simulation configuration, unless the trimOutputToWatershedBoundary parameter is set True.