Configuring a Cell-Specific Burn Disturbance

Overview

In VELMA, burn disturbances provide a way to mimic the effects of burning biomass and detritus at specific times and locations during a simulation run.
VELMA has several different burn disturbance models: this document focuses on the Cell-Specific Burn Disturbance Model, which provides a high degree of specificity for where, when, and how individual cells are affected by burn effects during a simulation run. It is the most configurable burn disturbance available in VELMA, but it can also require the most detailed effort to parameterize.

The Cell-Specific Burn Disturbance Model allows you to select the burn, volatilized, and below-ground-damage fraction modes it will use. These fraction modes are the same for each and every cell the disturbance burns, but their parameterization values may be specified on a per-cell, per-date basis. For example, if you chose DIRECT_VALUE for the burn fraction mode, the burn fraction is "calculated" to be simply whatever fractional value you specify (within the range [0.0, 1.0]), but you may specify distinct values for every cell, and for every year,jday that cell will burn. You may also specify a default value, used when there is no cell- or date- specific value.
(Since specifying specific values significantly complicates the driver data you must provide, try and set the your default value(s) for whatever configuration applies to the majority of cells and dates your burn applies to.)

Requirements

One comma-separated values (.csv) driver data file containing location, date, and (optionally) cell-specific bg-damage, burn, and volatilized parameters for the cells when burns will occur during the simulation run. The formatting details of the .csv file are described later in this document.

Adding and Configuring the Disturbance

In JVelma add a CellSpecificBurnDisturbanceModel parameterization group to your VELMA simulation configuration:

Click the Edit --> Disturbances --> Add a Disturbance menu item.
(This opens the "Specify Disturbance Model Type and Name" dialog window.)
Select the CellSpecificBurnDisturbanceModel item from the dialog window's "Disturbance Type" drop-down list.
Type a name into the "Disturbance Name" text field.
The name will become the parameterization group's Item-level identifier.
It can be any name that follows the rules and that is meaningful to you.
Click OK to accept your selections, close the dialog window, and add the parameterization group.

When the parameterization group is added, JVelma shifts the GUI to display the "All Parameters" tab, with column filtering set to show only the newly added group.
The group's parameters initially have these default values:

Group	Item	Parameter	Value
disturbance	csb_disturbance	cellDataFileName
disturbance	csb_disturbance	enableAutomaticSpatialReporting	`false`
disturbance	csb_disturbance	enableFullDataBuffer	`true`
disturbance	csb_disturbance	initializeActiveLoops	`1`
disturbance	csb_disturbance	initializeAgeModification	`+0`
disturbance	csb_disturbance	modelClass	`CellSpecificBurnDisturbanceModel`
disturbance	csb_disturbance	setBgDamageFractionMode	`DIRECT_VALUE`
disturbance	csb_disturbance	setBurnFractionMode	`DIRECT_VALUE`
disturbance	csb_disturbance	setDefaultBgDamageFractionParameters	`0.0`
disturbance	csb_disturbance	setDefaultBurnFractionParameters	`0.0`
disturbance	csb_disturbance	setDefaultVolatilizedFractionParameters	`0.0`
disturbance	csb_disturbance	setVolatilizedFractionMode	`DIRECT_VALUE`
disturbance	csb_disturbance	trimToWatershedBoundary	`false`

Notes:

The initializeActiveLoops parameter's value may initially be empty (blank).
If it is blank, set it to 1. (unless you have a different, valid value planned).
The blank value is an artifact of support for a legacy disturbance parameterization that should not be propagated to new simulation configurations.
The cellDataFileName parameter's value will initially be empty (blank).
You must provide the name of a valid driver data file for this parameter: it is an error to leave it blank.
In the table above, the rows are ordered by Parameter name.
In JVelma's "All Parameters Tab", clicking the "Parameter" column in the GUI's table orders the rows by that column.
The Item name "csb_disturbance" below is merely an example name.

Parameter Details

(Parameters appear in a different order here than they do in the table above.)

cellDataFileName
The name of the comma-separated value (.csv) driver data file for this burn disturbance. If the name is not a fully-qualified path + name, its location is assumed to be relative to inputDataLocationRootName/inputDataLocationDirName location specified in the simulation configuration. Content and formatting details for this file are described later in this document.

enableFullDataBuffer
When this parameter is set true the burn disturbance loads the entire cell driver data file into memory at the start of the simulation. When it is set false, the burn disturbance loads one year's worth of driver data at the start of each simulation year. Loading all the at once is a bit faster, but if your driver data file is large, it can cause the simulation to run out of memory. For large simulations with large driver data files, set this parameter false.

initializeActiveLoops
The comma-separated list of loop index numbers (range [1, nth-Loop]) in which the disturbance occurs. Entries in the list may be either single loop numbers or start-end (dash-separated) ranges. A valid loop index number is any positive whole number between 1 and the number of loops specified for the simulation run. For example, in a simulation run for 10 loops, the parameter value 1, 3-5, 10 would trigger the disturbance in loops 1, 3-through-5 (inclusive) and 10.

initializeAgeModification
Specifies the number of years to subtract or add to the age of the cover in affected cells when the disturbance occurs.

To set the cell's cover age to a specific number of years, specify a number, n, without any sign prefix.
To add n years to a cell's cover age, prefix a plus (+) sign to the number n.
To subtract n years to a cell's cover age, prefix a minus (-) sign to the number n.
Subtraction halts at zero (e.g. a cover age of 7, given -10 as the modifier will result in 0, not -3 as the modified age).

This parameter's default value is +0 (current cover age + 0), i.e. the distubance makes no change to the cover's age.
Be careful of the difference between +0 ("add zero to current cover age") and 0 (set the current cover age to zero).

enableAutomaticSpatialReporting
Burn disturbances can write serveral spatial data map (.asc) files each time a burn occurs. Set this parameter false to prevent writing the maps (to improve running time and reduce disk space required for results), or true to write the maps.

trimToWatershedBoundary
When set true, dimensions of any .asc output files are set to the bounding box of the current watershed.
When set false, dimensions of any .asc output files match the dimensions of the original DEM grid.
This parameter's default value is false (i.e. output to the full DEM grid dimensions).
When the enableAutomaticSpatialReporting parameter is set false, this parameter is ignored.
If you are running your simulation configuration under VelmaParalellCmdLine with a large number of sub reaches, or a very large DEM file, either set enableAutomaticSpatialReporting to false, or set this parameter's value to true, in order to reduce the amount of disk space used by .asc files output by this disturbance.

setBurnFractionMode
Specifies how the value of the burn fraction for this disturbance is calculated, and (implicitly) how many values must be provided for the calculation.
This parameter must be set to one of the following "Mode Name" values:

Mode Name	How the Burn Fraction is computed ...
`DIRECT_VALUE`	As the (single) burn fraction parameter specified by the user.
`SATURATION_BASED`	As an exponential function of the (single) burn fraction parameter and cell first-layer saturation value.
`FUEL_DYNAMIC`	As an exponential function of the (three) burn parameters and cell AgFuel value.

Default behavior is DIRECT_VALUE.
This parameter MUST be specified completely, exactly and is case-sensitive.
(e.g. do NOT set the value to "DIRECT", "DIRECT-VALUE", or "Direct-Value" when you mean "DIRECT_VALUE").
Do NOT leave this parameter blank.

setDefaultBurnFractionParameters
Specifies the default parameter values used to compute the burn fraction.
The burn fraction itself determines how much above-ground biomass and detritus is removed due to burning.
This parameter specifies the (one or more) parameter values used to compute that burn fraction.
Exactly how many values, and how they are used depends on what the setBurnFractionMode parameter's value is:

Mode Name	Required Parameters (in order)	Fraction Equation
`DIRECT_VALUE`	`F`	`F`
`SATURATION_BASED`	`K`	`exp(-K * saturationFraction)`
`FUEL_DYNAMIC`	`N`, `D`, `E`	`N / 1 + D * exp(-E * agFuel)`

Values for setDefaultBurnFractionParameters corresponding to a specific setBurnFractionMode value MUST appear in the order specified above.
This parameter's value(s) are used only when no cell-specific values are specified for an applicable cell.
Do NOT leave this parameter blank.

setVolatilizedFractionMode
Specifies how the value of the volatilized fraction for this disturbance is calculated, and (implicitly) how many values must be provided for the calculation.
This parameter must be set to one of the following "Mode Name" values:

Mode Name	How the Volatilization Fraction is computed ...
`DIRECT_VALUE`	As the (single) volitilized fraction parameter specified by the user.
`FUEL_DYNAMIC`	As an exponential function of the (three) burn parameters and cell AgFuel value.

setDefaultVolatilizedFractionParameters
Specifies the default parameter values used to compute the volatilized fraction.
The volatilized fraction itself determines how much of a cell's burned matter is "lost" via volatilization, and how much becomes detritus.
This parameter specifies the (one or more) parameter values used to compute that volatilized fraction.
Exactly how many values, and how they are used depends on what the setVolatilizedFractionMode parameter's value is:

Mode Name	Required Parameters (in order)	Fraction Equation
`DIRECT_VALUE`	`F`	`F`
`FUEL_DYNAMIC`	`N`, `D`, `E`	`N / 1 + D * exp(-E * agFuel)`

Values for setDefaultVolatilizedFractionParameters corresponding to a specific setVolatilizedFractionMode value MUST appear in the order specified above.
This parameter's value(s) are used only when no cell-specific values are specified for an applicable cell.
Do NOT leave this parameter blank.

setBgDamageFractionMode
Specifies how the value of the below-ground ("bg") damage fraction is calculated, and (implicitly) how many values must be provided for the calculation.
This parameter must be set to one of the following "Mode Name" values:

Mode Name	The bg Damage Fraction is computed ...
`DIRECT_VALUE`	The (single) bg damage fraction parameter is directly used as the bg damage fraction.
`FUEL_DYNAMIC`	As an exponential function of the (three) burn parameters and cell AgFuel value.

setDefaultBgDamageFractionParameters
Specifies the default parameter values used to compute the below-ground ("bg") damage fraction.
The bg damage fraction itself determines how much of a cells bg biomass is transferred to bg detritus.
This parameter specifies the (one or more) parameter values used to compute that bg fraction. Exactly how many values, and how they are used depends on what the setBgDamageFractionMode parameter's value is:

Mode Name	Required Parameters (in order)	Fraction Equation
`DIRECT_VALUE`	`F`	`F`
`FUEL_DYNAMIC`	`N`, `D`, `E`	`N / 1 + D * exp(-E * agFuel)`

modelClass
This parameter's value is the actual Java class name of this disturbance model.
It should be set to the correct value by default -- leave this parameter alone.

Driver Data File Format

Format Summary

A Cell-Specific Burn Disturbance Model's driver data file specifies which cells are affected, when those cells are affected, and (optionally) specific details of how a cell is affected at a given simulation step.

The file must contain rows of comma-separated values.
Unlike some VELMA input files, a Cell-Specific Burn Disturbance driver data file CANNOT contain a header text row.
All rows in the file must have the following format:

iCell [year jDayRange gCount [p0ID p0Count p0_0 .. p0_n] .. [pnID pnCount pn_0 .. pn_n]] .. [year ..]

Where:

Field	Parses to ..	Description / Notes
iCell	Integer	The linear index of a cell in the current simulation's watershed delineation.
year	Integer	A "full" year value (e.g. for year 1998 specify, `1998` NOT `98`).
jDayRange	IntegerRange	An Julian Day value (e.g. `31`) or range-pair (e.g. `90-180`).
gCount	Integer	The number of parameter groups associated with the prior iCell, year, jDayRange triplet.
pID	String	parameter group ID
pCount	Integer	The number of parameter fields
p_0 .. p_n	Double	Exactly pCount number of fields, each of which must parse to a Double value.
[ .. etc ]

Notes:

Each row MUST start with a valid iCell value.
Each row MUST contain at least one sequence of [year, jDayRange, gCount] values.
Each [year, jDayRange, gCount] sequence can contain one or move "parameter groups" (as specified by a gCount value > 0).
Fields that parse to Integer must be numeric, integer values (e.g. 1 is OK, but 1.0 is NOT ok).
Fields that parse to Double must be numeric, floating point values.
An IntegerRange can either be a single positive Integer value, or a pair of positive Integer values separated by a dash. No whitespace is allowed between the dash and the numbers.
Julian Day values must be within the Integer range of [1, 366]. Specifying the jdayRange as 1-366 (i.e. "every day of the year") is acceptable even for years that are not leap years.

A "parameter group" (not the same thing as a disturbance "parameterization group" -- the naming similarity is unfortunate) consists of 2 or more fields that provide the parameter values for one of the following aspect's of the disturbance.
A parameter group's first field is always its group identifier ("pID").

pID	pCount is Tied to Mode ...	Parameters Affect ...
1	setBurnFractionMode	How the burn fraction is computed, and thus, how much above-ground biomass and detritus are burned.
2	setVolatilizedFractionMode	How the volatilized fraction is computed, and thus, the distribution of the burned amount between volatilized and ash components.
3	setBgDamageFractionMode	How the below-ground damage fraction is computed, and thus, how much below-ground biomass is damaged (i.e. transferred to detritus).

Its second field is always the number of parameter fields in the group ("pCount"), not including the pID and pCount fields.
The number of parameter fields a parameter group must have (i.e. its pCount field's value) depends upon the value of the Mode disturbance parameter it is tied to (as listed in the table above).

Example Formats

All Cells Default
If your simulation can use the same burn, volatilized, and bgDamage fractions at every cell, the contents of the driver data file are greatly simplified. Suppose your simulation needs to burn 3 cell locations (1001, 1010, 1011) in 2 different years: (1989, 1993), during the first week of November (305-311) in each year. The disturbance's setDefault[...]FractionParameters allow you set burn, volatilized, and bgDamage fraction equation parameters that are appliable whenever cell-specific values aren't provided in the driver data file. Since all your cells need the same parameter values, you can rely on the Default(s) and skip including any of these parameter values in the file.
For this example, your file format would look like this:

                1001,1989,305-311,0,1993,305-311,0
1010,1989,305-311,0,1993,305-311,0
 1011,1989,305-311,0,1993,305-311,0

The ",0" values above are the gCount values, and they indicate that there are no parameterization groups associated with the cells and dates where and when burning occurs. Instead, the burn disturbance will use the setDefault[...]FractionParameters for parameter values to compute the burn, volatilized, and bgDamage fractions.

All Cells Need Specific Parameters for All Fractions
This is the opposite of the "All Default" example. Suppose your simulation must burn the same 3 cell locations (1001, 1010, 1011) at the same dates, but now every cell has its own distinct parameter values for its burn, volatilized, and bgDamage fraction equation parameters. Also suppose that your disturbance has its mode parameter values set as: setBurnFractionMode=SATURATION_BASED, setBgDamageFractionMode=FUEL_DYNAMIC, and setBgDamageFractionMode=DIRECT_VALUE. For this example your file format might look like this:

1001, 1989,305-311, 1,1,0.50, 2,3,0.10,0.25,1.20, 3,1,0.63, 1993,305-311, 1,1,0.33, 2,3,0.15,0.30,1.11, 3,1,0.24
1010, 1989,305-311, 1,1,0.33, 2,3,0.08,0.35,1.15, 3,1,0.45, 1993,305-311, 1,1,0.40, 2,3,0.27,0.30,1.50, 3,1,0.30
1011, 1989,305-311, 1,1,0.70, 2,3,0.20,0.15,1.00, 3,1,0.60, 1993,305-311, 1,1,0.42, 2,3,0.08,0.30,0.85, 3,1,0.55

(Note: the extra whitespace in the example text above is only for readability in this example: do not include extra whitespace in actual driver data files.)
Here is the first line of the driver data above, with explicit labeling applied to the parameterization groups' fields of the first year,day entry:

1001, 1989,305-311, 1,1,0.50, 2,3,0.10,0.25,1.20, 3,1,0.63, (... etc ...)
              | | |     | | |    |    |     | | |
              | | |     | | |    |    |     | | bgDamageFractionParemeter value F (for DIRECT_VALUE mode)
              | | |     | | |    |    |     | bgDamageFractionParameter pCount
              | | |     | | |    |    |     bgDamageFractionParameter pID
              | | |     | | |    |    |
              | | |     | | |    |    volatilizationFractionParameter value E (for FUEL_DYNAMIC mode)
              | | |     | | |    volatilizationFractionParameter value D (for FUEL_DYNAMIC mode))
              | | |     | | volatilizationFractionParameter value N (for FUEL_DYNAMIC mode))
              | | |     | volatilizationFractionParameter pCount 
              | | |     volatilizationFractionParameter pID
              | | |
              | | burnFractionParameter value K (for SATURATION_BASED mode)
              | burnFractionParameter pCount
              burnFractionParameter pID

Additional Information

Disturbance Name Rules

The name you provide for a disturbance parameterization group must follow these rules:

Must begin with a letter
After the first letter, must consist entirely of letter, digit, dash ("-"), and underscore characters ("_").
No other characters are allowed.
Do NOT include whitespace or other punctuation characters (e.g. ":") in Disturbance Names.
Must be unique to a given disturbance parameterization group.

Submit a Suggestion