clDisturbance Class Reference

Disturbance - Version 1.0. More...

#include <Disturbance.h>

Inheritance diagram for clDisturbance:

clBehaviorBase clWorkerBase

List of all members.

Public Types

enum  cutType { partial, gap, clear }
 Types of harvest cuts. More...
enum  amtType { percentBA, absBA, percentDen, absDen }
 How amount to cut is defined. More...

Public Member Functions

 clDisturbance (clSimManager *p_oSimManager)
 Constructor.
 ~clDisturbance ()
 Destructor.
void Action ()
 Performs the harvest or mortality episode for a timestep.
void SetNameData (char *cNameString)
 Captures the parameter file behavior string passed to this behavior.

Static Public Member Functions

static int GetNumberOfCutRanges ()
 Gets the number of total allowed cut ranges.

Protected Member Functions

void ResetResultsGrid ()
 Resets all the values in the Harvest Results or Episodic Mortality Results grid.
void GetData (xercesc::DOMDocument *p_oDoc)
 Performs setup.
void ReadHarvestParameterFileData (xercesc::DOMDocument *p_oDoc)
 Reads harvest data from the parameter file.
void ReadMortEpParameterFileData (xercesc::DOMDocument *p_oDoc)
 Reads episodic mortality data from the parameter file.
void SetupGrids ()
 Sets up the harvest or mortality episode grids and gets all the return codes.
void ValidatePackages ()
 Makes sure that the data in the event harvest packages makes sense.
void CutTrees (clPackage *p_oMasterPackage)
 Performs the tree cutting for a master cut package.
int AssembleCutArea (clPackage *p_oMasterPackage, const int &iNumXCells, const int &iNumYCells, stcGridList *&p_cutArea, float *p_fLoDbh, float *p_fHiDbh, float *p_fAmountToRemove, bool *p_bSpeciesCut)
 Finds all the grid cells affected by a given cut.
void GetBasalArea (stcGridList *p_cutArea, const short int &iSpecies, float *p_fTotalBasalArea, float *p_fLoDbh, float *p_fHiDbh)
 Gets the basal area in a cut area for a single species.
clTreeGetTallestTreeInCutArea (stcGridList *&p_cutArea, const short int &iSpecies)
 Finds the tallest tree of a species within a cut area.
clTreeGetNextTreeInCutArea (stcGridList *&p_cutArea, const short int &iSpecies)
 Gets the next tallest tree of a species within a cut area.
void SetCutFlags (stcGridList *p_cutArea, const int &iCutType)
 Sets the Harvest Type data member of the Harvest Results grid.

Protected Attributes

clTreePopulationmp_oPop
 Stashed pointer to tree population.
clGridBasemp_oMasterCutsGrid
 MASTER CUTS GRID.
clGridBasemp_oCutEventsGrid
 CUT EVENTS GRID.
clGridBasemp_oResultsGrid
 RESULTS GRID.
short int m_iMasterTimestepCode
 timestep data member code in "harvestmastercuts" grid
short int m_iMasterIDCode
 id data member code in "harvestmastercuts" grid
short int * mp_iSpeciesCodes
 species data member code in "harvestmastercuts" grid.
short int m_iCutTypeCode
 cuttype data member code in "harvestmastercuts" grid
short int m_iAmountTypeCode
 amttype data member code in "harvestmastercuts" grid
short int * mp_iRangeMinCodes
 rangeminx data member codes in "harvestmastercuts" grid.
short int * mp_iRangeMaxCodes
 rangemaxx data member codes in "harvestmastercuts" grid.
short int * mp_iRangeAmountCodes
 rangeamtx data member codes in "harvestmastercuts" grid.
short int m_iCutTimestepCode
 timestep data member code in "harvestcutevents" grid
short int m_iCutIDCode
 id data member code in "harvestcutevents" grid
short int m_iHarvestTypeCode
 Harvest Type data member code in "Harvest Results" grid.
short int ** mp_iDenCutCodes
 Cut Density data member codes in "Harvest Results" grid.
short int ** mp_iBaCutCodes
 Cut Basal Area data member codes in "Harvest Results" grid.
short int m_iReasonCode
 Reason code to pass to the tree population when trees are killed.
bool m_bIsHarvest
 What kind of behavior this is.

Static Protected Attributes

static short int m_iNumAllowedCutRanges
 Number of cut ranges allowed.

Classes

struct  stcGridList
 Holds a linked list of grid cells. More...


Detailed Description

Disturbance - Version 1.0.

This class allows for highly specific disturbance events. Two kinds of disturbance can be performed: harvest or episodic mortality (disease, insect outbreaks, etc). They work the exact same way, differing only in the reason code passed to the tree population when killing the tree.

Harvest/mortality episodes can be defined on a grid cell level for each timestep for each species. If more than one event is defined for a species for a single grid cell and timestep, the user takes a chance on what happens. Cells with common disturbance criteria are grouped by the user into groups which will be evaluated together.

If the disturbance is harvest, there are three kinds of harvests that can be performed: gap cut, partial cut, and clear cut. Partial cuts may remove only a portion of the trees, but otherwise, there is no difference in how the trees are removed for each cut type. The type of cut is recorded for the benefit of other behaviors for whom this might be important. The user can define different ranges of dbh values to cut, and each can have a portion of the trees removed, as defined by percentage of basal area, percentage of density, absolute amount of basal area (in square meters per hectare), or absolute amount of density (in stems per hectare). For gap cut and clear cut, for all species affected, all trees are removed. Any attempt to define cut ranges etc. for gap and clear cuts will cause an error to be thrown (the cut ranges could be ignored but throwing an error alerts the user in case they didn't know, so they could amend the parameter file to get what they meant to get).

Episodic mortality events are processed like harvest partial cuts.

The disturbance event data is stored in a grid. Each cut event, defined as the killing to be done for one species for one timestep for one grid cell, is stored in a grid package. These packages are sorted in timestep order. Each timestep, all the cut events that are defined for that timestep are executed, then those packages are removed.

Seedlings are always ignored by this behavior.

This behavior can be called from the parameter file by either "harvest" or "episodic mortality". The namestring is "harvest".

Copyright 2003 Charles D. Canham.

Author:
Lora E. Murphy

Edit history:
-----------------
April 28, 2004 - Submitted as beta (LEM)
May 5, 2004 - Transformed from harvest-only to disturbance
April 13, 2005 - Explicitly removed snags from all disturbance calcs (LEM)
April 20, 2005 - Changed the name of TimestepCleanup to ResetResultsGrid and changed the way it's called to make sure harvest results are preserved for as long as possible (LEM)

Member Enumeration Documentation

Types of harvest cuts.

These are listed in increasing order of severity (that's important!)

Enumerator:
partial  Partial cut.
gap  Gap cut.
clear  Clear cut.

How amount to cut is defined.

Enumerator:
percentBA  As a percentage of total basal area in cut range.
absBA  As an amount of BA in sq m in that cut range.
percentDen  As a percentage of total density in that cut range.
absDen  As a total number of trees in that cut range.


Constructor & Destructor Documentation

clDisturbance::clDisturbance ( clSimManager p_oSimManager  ) 

Constructor.

Parameters:
p_oSimManager Sim Manager object.

clDisturbance::~clDisturbance (  ) 

Destructor.


Member Function Documentation

void clDisturbance::Action (  )  [virtual]

Performs the harvest or mortality episode for a timestep.

This goes through the master package lists in either the harvestmastercuts or mortepisodemastercuts grid and calls CutTrees() for each one that is for this timestep.

Reimplemented from clBehaviorBase.

static int clDisturbance::GetNumberOfCutRanges (  )  [inline, static]

Gets the number of total allowed cut ranges.

Returns:
Number of total allowed cut ranges.

void clDisturbance::SetNameData ( char *  cNameString  )  [virtual]

Captures the parameter file behavior string passed to this behavior.

This is overridden from clBehaviorBase so we can capture the namestring passed. Since this class can create multiple kinds of behaviors that function differently, this will capture what kind of behavior this is supposed to be.

Parameters:
cNameString Behavior's parameter file names.
Exceptions:
modelErr if the name is not recognized.

Reimplemented from clBehaviorBase.

void clDisturbance::ResetResultsGrid (  )  [protected]

Resets all the values in the Harvest Results or Episodic Mortality Results grid.

If Harvest, Harvest Type becomes -1; all others are 0.

void clDisturbance::GetData ( xercesc::DOMDocument *  p_oDoc  )  [protected, virtual]

Performs setup.

First, SetUpGrids() is called to create our grids. Then, if this is harvest, ReadHarvestParameterFileData() is called; if episodic mortality, ReadEpMortParameterFileData() is called. Then ValidatePackages() is called to validate data from the parameter file.

Parameters:
p_oDoc DOM tree of parsed input file.

Implements clWorkerBase.

void clDisturbance::ReadHarvestParameterFileData ( xercesc::DOMDocument *  p_oDoc  )  [protected]

Reads harvest data from the parameter file.

It doesn't perform validation other than basic data types - more in-depth logical validation is left to ValidatePackages().

Parameters:
p_oDoc DOM tree of parsed input file.

void clDisturbance::ReadMortEpParameterFileData ( xercesc::DOMDocument *  p_oDoc  )  [protected]

Reads episodic mortality data from the parameter file.

It doesn't perform validation other than basic data types - more in-depth logical validation is left to ValidatePackages().

Parameters:
p_oDoc DOM tree of parsed input file.

void clDisturbance::SetupGrids (  )  [protected]

Sets up the harvest or mortality episode grids and gets all the return codes.

void clDisturbance::ValidatePackages (  )  [protected]

Makes sure that the data in the event harvest packages makes sense.

For each cut event (each package) - this checks the following:

  • No negative values in cut ranges
  • Cut ranges do not overlap
  • Cut amounts expressed in percentages do not have values over 100
  • There are no cut ranges defined for gap and clear cuts

For harvest gap and clear cuts, this will set up one cut range so the cut happens correctly. The cut range will cover dbhs from 0 to 3000, removing 100% of density.

void clDisturbance::CutTrees ( clPackage p_oMasterPackage  )  [protected]

Performs the tree cutting for a master cut package.

It starts by getting a linked list of cells to cut and their tallest trees of a given species, then selects trees to cut according to the cut type.

Parameters:
p_oMasterPackage The master package to cut

int clDisturbance::AssembleCutArea ( clPackage p_oMasterPackage,
const int &  iNumXCells,
const int &  iNumYCells,
stcGridList *&  p_cutArea,
float *  p_fLoDbh,
float *  p_fHiDbh,
float *  p_fAmountToRemove,
bool *  p_bSpeciesCut 
) [protected]

Finds all the grid cells affected by a given cut.

The cut in question is found in one master cut package. The grid cells are identified by matching ID numbers on packages in the "harvestcutevents" / "mortepisodecutevents" grid. The cut area cells are assembled into a linked list. All packages which went into the linked list are then deleted. This also extracts the cut range data and cut amount data.

Parameters:
p_oMasterPackage The master package for which the cut area list is being assembled. (This package will be deleted.)
iNumXCells Number of X cells in mp_oCutEventsGrid.
iNumYCells Number of Y cells in mp_oCutEventsGrid.
p_cutArea Pointer in which to start the linked list.
p_fLoDbh Array (sized m_iNumAllowedCutRanges) into which to put the low dbhs of the package's cut ranges.
p_fHiDbh Array (sized m_iNumAllowedCutRanges) into which to put the high dbhs of the package's cut ranges.
p_fAmountToRemove Array (sized m_iNumAllowedCutRanges) into which to put the amount of basal area to remove for each of the package's cut ranges.
p_bSpeciesCut Array of all species for whether or not a species is affected by this cut.
Returns:
The number of the cells in the cut area.

void clDisturbance::GetBasalArea ( stcGridList p_cutArea,
const short int &  iSpecies,
float *  p_fTotalBasalArea,
float *  p_fLoDbh,
float *  p_fHiDbh 
) [protected]

Gets the basal area in a cut area for a single species.

The cut area is defined by a linked list of grid cells. This gets the basal area in each cut range and puts it in an array whose pointer was passed.

Parameters:
p_cutArea Pointer to the linked list.
iSpecies Species of tree for which to calculate basal area.
p_fTotalBasalArea Array (size m_iNumAllowedCutRanges) in which to put the total basal area calculation.
p_fLoDbh Array (size m_iNumAllowedCutRanges) of lower-limit dbhs for the cut ranges that have been defined.
p_fHiDbh Array (size m_iNumAllowedCutRanges) of upper-limit dbhs for the cut ranges that have been defined.

clTree* clDisturbance::GetTallestTreeInCutArea ( stcGridList *&  p_cutArea,
const short int &  iSpecies 
) [protected]

Finds the tallest tree of a species within a cut area.

The cut area is defined by a linked list of grid cells. This assumes that the tallest tree pointers for each grid cell in the linked list is not populated. This will populate and sort them. Which means that the pointer p_cutArea could be changed.

Parameters:
p_cutArea Pointer to the linked list.
iSpecies Species of tree to populate.
Returns:
Tallest tree in the area, or NULL if there are no trees of the desired species.

clTree* clDisturbance::GetNextTreeInCutArea ( stcGridList *&  p_cutArea,
const short int &  iSpecies 
) [protected]

Gets the next tallest tree of a species within a cut area.

The cut area is defined by a linked list of grid cells. This assumes that the pointers to the tallest trees for each grid cell are populated, and that the current tallest tree is no longer wanted (although if it is to be killed it hasn't been killed yet). The current tallest tree could still be alive; but it will be ignored for further consideration.

Parameters:
p_cutArea Pointer to the linked list.
iSpecies Species being cut.
Returns:
Next tallest tree in the area, or NULL if there are no trees of the desired species.

void clDisturbance::SetCutFlags ( stcGridList p_cutArea,
const int &  iCutType 
) [protected]

Sets the Harvest Type data member of the Harvest Results grid.

For each grid cell in the cut area, this makes sure that the data member is set to the most severe cut type that occurred in a timestep.

Parameters:
p_cutArea Pointer to the linked list of the cut area.
iCutType Most severe cut type from this cut area.


Member Data Documentation

Stashed pointer to tree population.

MASTER CUTS GRID.

If this behavior is harvesting, the grid is called "harvestmastercuts"; if it is episodic mortality, the grid is called "mortepisodemastercuts". The grid has a single cell. This is where the cut events are defined.

Each cut event is one package and is applied to a list of species. It has a timestep, cut amount, cut type, and number of cut ranges defined. It also has a unique ID number. The grid cells to which it is applied are in either the "harvestcutevents" or "mortepisodecutevents" grid, depending on what this behavior is.

Species are treated individually. A cut event removing 20% of three species removes 20% of each species individually; one that removes 5 sq.m/ha of basal area removes 5 from each species.

For the cut ranges, four dbh ranges can be defined to which the cuts will be applied. The ranges are ordered as 1 is the smallest minimum dbh. Ranges cannot overlap.

The packages are in timestep order, earliest first.

It is possible that a grid map will have been read in for this grid; it will be ignored, and any grid created with such a map will be overwritten.

Data members - all for packages:
Data member name Data type Description
id int ID number of cut
timestep int Timestep at which to apply the cut
cuttype int Matches a value of the enum "cutType"
amttype int Matches a value of the enum "amtType". Not used if episodic mortality
species(x) bool One of each of these for each species. If true, this species is being cut.
rangeamt(x) float Range amount to cut. There are one of each of the following for m_iNumAllowedCutRanges, where x is the index, starting at 0 (thus "rangemin0" and "rangeamt2"). Units depend on amttype and are either percentage of basal area, percentage of density, absolute amount of basal area (in square meters per hectare), or absolute amount of density (in stems per hectare)
rangemin(x) float Range minimum dbh value. There are one of each of the following for m_iNumAllowedCutRanges, where x is the index, starting at 0.
rangemax(x) float Range maximum dbh value. There are one of each of the following for m_iNumAllowedCutRanges, where x is the index, starting at 0.

CUT EVENTS GRID.

If this behavior is harvesting, the grid is called "harvestcutevents"; if it is episodic mortality, the grid is called "mortepisodecutevents". The grid has a cell resolution that matches the tree population. This is where data about cutting events is stored.

The need to cut a grid cell is signaled by the presence of a package. The package has an ID number which matches a package in either the "harvestmastercuts" or "mortepisodemastercuts" grid, which contains the information about how the cut is actually to be performed. Packages are in timestep order, earliest first.

It is possible that a grid map will have been read in for this grid; it will be ignored, and any grid created with such a map will be overwritten.

Data members - all for packages:

Data member nameData typeDescription
id int ID number matching master package in "harvestmastercuts"
timestep int Timestep at which to apply the cut

RESULTS GRID.

If this behavior is harvesting, the grid is called "Harvest Results"; if it is episodic mortality, the grid is called "Mortality Episode Results". The grid has a cell resolution matching that of "harvestcutevents/ mortepisodecutevents". This is where data on actual cut/kill results is stored. The data is stored raw - no conversion to per-hectare amounts.

It is possible that a grid map will have been read in for this grid; it will be ignored, and any grid created with such a map will be overwritten.
Data member name Data type Description
Harvest Type int Type of harvest that occurred in the current timestep - -1 if none has occurred. This data member is not registered if this grid is "Mortality Episode Results".
Cut Density_x_sp int Number of trees cut in the current timestep. There are one of each of the following for m_iNumAllowedCutRanges times number of species, where x is the cut range index, starting at 0, and sp is the species number.
Cut Basal Area_x_sp float Total basal area cut in the current timestep. There are one of each of the following for m_iNumAllowedCutRanges times number of species, where x is the cut range index, starting at 0, and sp is the species number.

short int clDisturbance::m_iMasterTimestepCode [protected]

timestep data member code in "harvestmastercuts" grid

short int clDisturbance::m_iMasterIDCode [protected]

id data member code in "harvestmastercuts" grid

short int* clDisturbance::mp_iSpeciesCodes [protected]

species data member code in "harvestmastercuts" grid.

Array size is number species. Array index matches species number

short int clDisturbance::m_iCutTypeCode [protected]

cuttype data member code in "harvestmastercuts" grid

short int clDisturbance::m_iAmountTypeCode [protected]

amttype data member code in "harvestmastercuts" grid

short int* clDisturbance::mp_iRangeMinCodes [protected]

rangeminx data member codes in "harvestmastercuts" grid.

Array size is number cut ranges

short int* clDisturbance::mp_iRangeMaxCodes [protected]

rangemaxx data member codes in "harvestmastercuts" grid.

Array size is number cut ranges

short int* clDisturbance::mp_iRangeAmountCodes [protected]

rangeamtx data member codes in "harvestmastercuts" grid.

Array size is number cut ranges

short int clDisturbance::m_iCutTimestepCode [protected]

timestep data member code in "harvestcutevents" grid

short int clDisturbance::m_iCutIDCode [protected]

id data member code in "harvestcutevents" grid

short int clDisturbance::m_iHarvestTypeCode [protected]

Harvest Type data member code in "Harvest Results" grid.

short int** clDisturbance::mp_iDenCutCodes [protected]

Cut Density data member codes in "Harvest Results" grid.

Array size is number of cut ranges by number of species

short int** clDisturbance::mp_iBaCutCodes [protected]

Cut Basal Area data member codes in "Harvest Results" grid.

Array size is number cut ranges by number of species

short int clDisturbance::m_iNumAllowedCutRanges [static, protected]

Number of cut ranges allowed.

short int clDisturbance::m_iReasonCode [protected]

Reason code to pass to the tree population when trees are killed.

bool clDisturbance::m_bIsHarvest [protected]

What kind of behavior this is.

If true, it's a harvest. If false, it's episodic mortality.


The documentation for this class was generated from the following file:

Generated on Wed Oct 28 13:58:45 2009 for SORTIE Core C++ Documentation by  doxygen 1.5.6