clNCIBase Class Reference

NCI Base Class - version 1.1. More...

#include <NCIBase.h>

Inheritance diagram for clNCIBase:

clNciGrowth clNCIMort

List of all members.

Protected Types

typedef float(clNCIBase::* Ptr2ShadingEffect )(clTree *)
 Define a type for pointers to functions of the ShadingEffect type.
typedef float(clNCIBase::* Ptr2CalculateNCI )(clTree *, clTreePopulation *, clPlot *)
 Define a type for pointers to functions of the CalculateNCI type.
typedef float(clNCIBase::* Ptr2CrowdingEffect )(const float &, const float &, const int &)
 Define a type for pointers to functions of the CalculateCrowding type.

Protected Member Functions

 clNCIBase ()
 Constructor.
 ~clNCIBase ()
 Destructor.
void DoNCISetup (clTreePopulation *p_oPop, int iNumBehaviorSpecies)
 Declares array memory.
void SetFunctionPointers ()
 Sets the function pointers for Crowding Effect, Shading Effect, and NCI.
float CalculateShadingEffect (clTree *p_oTree)
 Calculates the Shading Effect portion of growth.
float CalculateNoShadingEffect (clTree *p_oTree)
 Negates the Shading Effect.
float CalculateShadingEffectNoExp (clTree *p_oTree)
 Calculates the Shading Effect portion of growth.
float CalculateCrowdingEffect (const float &fDbh, const float &fNCI, const int &iSpecies)
 Calculates the Crowding Effect portion of growth.
float CalculateCrowdingEffectNoExp (const float &fDbh, const float &fNCI, const int &iSpecies)
 Calculates the Crowding Effect portion of growth.
float CalculateCrowdingEffectNoDbh (const float &fDbh, const float &fNCI, const int &iSpecies)
 Calculates the Crowding Effect portion of growth.
float CalculateCrowdingEffectSimple (const float &fDbh, const float &fNCI, const int &iSpecies)
 Calculates the Crowding Effect portion of growth.
float CalculateNoCrowdingEffect (const float &fDbh, const float &fNCI, const int &iSpecies)
 Negates the Crowding Effect.
float CalculateNCI (clTree *p_oTree, clTreePopulation *p_oPop, clPlot *p_oPlot)
 Calculates the NCI value for a tree.
float CalculateNCINoEta (clTree *p_oTree, clTreePopulation *p_oPop, clPlot *p_oPlot)
 Calculates the NCI value for a tree.
float CalculateNCINoDivisor (clTree *p_oTree, clTreePopulation *p_oPop, clPlot *p_oPlot)
 Calculates the NCI value for a tree.
float CalculateNCINoEtaNoDivisor (clTree *p_oTree, clTreePopulation *p_oPop, clPlot *p_oPlot)
 Calculates the NCI value for a tree.
float CalculateNoDamageEffect (clTree *p_oTree)
 Returns 1 when there is no storm effect.
float CalculateDamageEffect (clTree *p_oTree)
 Calculates the storm effect for a tree when storm effect is used.

Protected Attributes

float ** mp_fLambda
 Lamba for NCI.
float * mp_fAlpha
 Neighbor DBH effect.
float * mp_fBeta
 Neighbor distance effect.
float * mp_fCrowdingSlope
 Crowding effect slope.
float * mp_fCrowdingSteepness
 Crowding effect steepness.
float * mp_fMinimumNeighborDBH
 The minimum DBH, in cm, of neighbors to be included in NCI calculations.
float * mp_fXb
 Size effect variance parameter.
float * mp_fMaxPotentialValue
 Maximum value, whatever that may be, in appropriate units.
float * mp_fX0
 Size effect mode parameter.
float * mp_fShadingCoefficient
 Shading coefficient in Shading Effect equation.
float * mp_fShadingExponent
 Shading exponent in Shading Effect equation.
float * mp_fMedDamageEta
 NCI neighbor storm medium damage parameter.
float * mp_fFullDamageEta
 NCI neighbor storm full damage parameter.
float * mp_fGamma
 Size sensitivity to NCI parameter.
float * mp_fMedDamageStormEff
 Damage Effect parameter for target trees with medium damage.
float * mp_fFullDamageStormEff
 Damage Effect parameter for target trees with full damage.
float * mp_fMaxCrowdingRadius
 Maximum search radius, in meters, in which to look for crowding neighbors.
float m_fDbhDivisor
 The value to divide DBH by in NCI.
short int ** mp_iDamageCodes
 Holds return data codes for the "stm_dmg" tree data member, if used.
short int ** mp_iLightCodes
 Holds return data codes for the "Light" tree data member.
short int * mp_iIndexes
 Speeds access to the arrays.
float m_fMinSaplingHeight
 Minimum sapling height.
short int m_iNumTotalSpecies
 Keep our own copy for the destructor.
short int m_iNumBehSpecies
 Keep our own copy for the destructor.
bool m_bIncludeSnags
 Whether or not to include snags in NCI.
Ptr2ShadingEffectmp_ShadingEffect
 Function pointer array for the appropriate function for calculating Shading Effect.
Ptr2CalculateNCImp_NCI
 Function pointer array for the appropriate function for calculating NCI.
Ptr2CrowdingEffectmp_CrowdingEffect
 Function pointer array for the appropriate function for calculating Crowding Effect.
float(clNCIBase::* DamageEffect )(clTree *)
 Function pointer to the appropriate damage effect calculator.


Detailed Description

NCI Base Class - version 1.1.

This class provides a base class for NCI functionality. Child classes can descend both from this base and from the appropriate behavior base.

The basic pattern for NCI calculations is as follows:

Value = Max Value * Damage Effect * Size Effect * Crowding Effect * Shading Effect

Value is the value being calculated, and Max Value is the maximum possible amount of that value in whatever units are appropriate. Damage Effect, Size Effect, Shading Effect, and Crowding Effect are multipliers bounded between 0 and 1 which act to reduce Max Value.

Size Effect is calculated as:

SE = exp(-0.5(ln(DBH/X0)/Xb)2)

where:

Crowding Effect is calculated as:

CE = exp(-C * DBH γ * NCID)

where:

NCIi is calculated as follows (simplifying the notation):

NCIi = Σ η λk((DBHk/q)α/distanceβ)
where:
NCI ignores neighbors with disturbance and harvest death codes. Natural deaths are NOT ignored, because it presumes that those deaths occurred in the current timestep and they should still be considered as live neighbors.

Shading effect is calculated as follows:

SE = exp(-m * Sn)

where:

Storm Effect is an input parameter. There is one for trees with medium damage and one for trees with full damage. Each is a value between 0 and 1. If the damage counter of the target tree = 0 (tree is undamaged), Storm Effect equals 1.

It is expected that not all terms in the equation will be used for all trees. A user can turn off some of the terms by setting key parameters to 0 or 1. To be efficient, this behavior looks for this and has several alternate function forms to avoid extra math. It calls the correct function form through function pointers. Different species can have different configurations.

There are parameters defined, but this class does not populate the values nor validate them. That is the responsibility of the child class. This class also does not bother checking for valid arrays before trying to access them. This class declares the arrays, NULLs pointers in the constructor, and deletes them in the constructor.

Copyright 2005 Charles D. Canham.

Author:
Lora E. Murphy

Edit history:
-----------------
March 14, 2005 - Created (LEM)
November 17, 2006 - Bug fix in NCI calculation - changing from eta of neighbor species to eta of target species
February 5, 2008 - Allowing a "no competitive effect" option (LEM)
February 8, 2008 - Changed mortality flags from simple booleans to reason codes; now we ignore neighbors that have a disturbance death but not a natural death (LEM)

Member Typedef Documentation

typedef float(clNCIBase::* clNCIBase::Ptr2ShadingEffect)(clTree *) [protected]

Define a type for pointers to functions of the ShadingEffect type.

typedef float(clNCIBase::* clNCIBase::Ptr2CalculateNCI)(clTree *, clTreePopulation *, clPlot *) [protected]

Define a type for pointers to functions of the CalculateNCI type.

typedef float(clNCIBase::* clNCIBase::Ptr2CrowdingEffect)(const float &, const float &, const int &) [protected]

Define a type for pointers to functions of the CalculateCrowding type.


Constructor & Destructor Documentation

clNCIBase::clNCIBase (  )  [protected]

Constructor.

NULLs out pointers. It's OK for this to be protected since it will only be called by children.

clNCIBase::~clNCIBase (  )  [protected]

Destructor.

Deletes all arrays, freeing memory.


Member Function Documentation

void clNCIBase::DoNCISetup ( clTreePopulation p_oPop,
int  iNumBehaviorSpecies 
) [protected]

Declares array memory.

Obviously, call this before reading any parameters into the arrays.

Parameters:
iNumBehaviorSpecies Number of species to which the behavior is applied.
p_oPop Tree population, for getting seedling height

void clNCIBase::SetFunctionPointers (  )  [protected]

Sets the function pointers for Crowding Effect, Shading Effect, and NCI.

This function analyzes the parameters to discern the user's intentions, then for each species selects the simplest function form that provides what they need.

For Crowding Effect:

For Shading Effect:

For NCI: Storm damage is used if any storm damage value is not 1. Otherwise, it is not used.

  • If storm damage is used and the DBH divisor != 1, NCI = CalculateNCI().
  • If storm damage is used and the DBH divisor = 1, NCI = CalculateNCINoDivisor().
  • If storm damage is not used and the DBH divisor != 1, NCI = CalculateNCINoEta().
  • If storm damage is not used and the DBH divisor = 1, NCI = CalculateNCINoEtaNoDivisor().

    For Storm Effect: If any storm damage value is not 1, CalculateStormEffect() is used. Otherwise, it is CalculateNoStormEffect().

All parameter values should be filled before calling this function. So, by extension, DeclareArrays() should also have been called.

float clNCIBase::CalculateShadingEffect ( clTree p_oTree  )  [protected]

Calculates the Shading Effect portion of growth.

This version calculates the full equation with all terms, viz:

SE = exp(-m * Sn)
where:
  • SE = Shading Effect
  • m = shading coefficient
  • S = amount of shade cast by neighbors, as placed in the "Light" data member
  • n = shading exponent

Parameters:
p_oTree Tree for which to calculate the shading effect.
Returns:
Shading Effect, not guaranteed to be between 0 and 1.

float clNCIBase::CalculateNoShadingEffect ( clTree p_oTree  )  [inline, protected]

Negates the Shading Effect.

Use this version if the user has indicated that the Shading Effect is not to be used - i.e. m = 0.

Parameters:
p_oTree Tree for which to calculate the shading effect.
Returns:
1, to remove Shading Effect from growth.

float clNCIBase::CalculateShadingEffectNoExp ( clTree p_oTree  )  [protected]

Calculates the Shading Effect portion of growth.

This version is used when the user has set n = 1, allowing us to skip a calculation. This version returns:

SE = exp(-m * S)
where:
  • SE = Shading Effect
  • m = shading coefficient
  • S = amount of shade cast by neighbors, as placed in the "Light" data member

Parameters:
p_oTree Tree for which to calculate the shading effect.
Returns:
Shading Effect, not guaranteed to be between 0 and 1.

float clNCIBase::CalculateCrowdingEffect ( const float &  fDbh,
const float &  fNCI,
const int &  iSpecies 
) [protected]

Calculates the Crowding Effect portion of growth.

This uses the full equation:

CE = exp(-C * DBHγ * NCID)
where:
  • CE = crowding effect
  • C is the NCI slope parameter
  • D is the NCI steepness parameter
  • DBH is of the target tree, in meters
  • γ is the size sensitivity to NCI parameter
  • NCI is this tree’s NCI value

Parameters:
fDbh DBH of the tree for which to calculate the Crowding Effect.
fNCI Tree's NCI.
iSpecies Tree's species.
Returns:
Crowding Effect, not guaranteed to be between 0 and 1.

float clNCIBase::CalculateCrowdingEffectNoExp ( const float &  fDbh,
const float &  fNCI,
const int &  iSpecies 
) [protected]

Calculates the Crowding Effect portion of growth.

This form is used if the user sets D = 1, which cancels out a power term:

CE = exp(-C * DBHγ * NCI)
where:
  • CE = crowding effect
  • C is the NCI slope parameter
  • DBH is of the target tree, in meters
  • γ is the size sensitivity to NCI parameter
  • NCI is this tree’s NCI value

Parameters:
fDbh DBH of the tree for which to calculate the Crowding Effect.
fNCI Tree's NCI
iSpecies Tree's species.
Returns:
Crowding Effect, not guaranteed to be between 0 and 1.

float clNCIBase::CalculateCrowdingEffectNoDbh ( const float &  fDbh,
const float &  fNCI,
const int &  iSpecies 
) [protected]

Calculates the Crowding Effect portion of growth.

This form is used if the user sets γ in the Crowding Effect equation to 0, eliminating the DBH term:

CE = exp(-C * NCID)
where:
  • CE = crowding effect
  • C is the NCI slope parameter
  • D is the NCI steepness parameter
  • NCI is this tree’s NCI value

Parameters:
fDbh DBH of the tree for which to calculate the Crowding Effect.
fNCI Tree's NCI.
iSpecies Tree's species.
Returns:
Crowding Effect, not guaranteed to be between 0 and 1.

float clNCIBase::CalculateCrowdingEffectSimple ( const float &  fDbh,
const float &  fNCI,
const int &  iSpecies 
) [protected]

Calculates the Crowding Effect portion of growth.

This form is used if the user wants the simplest crowding effect. In this, the user sets γ in the Crowding Effect equation to 0, eliminating the DBH term, and d = 1, eliminating the exponent:

CE = exp(-C * NCI)
where:
  • CE = crowding effect
  • C is the NCI slope parameter
  • NCI is this tree’s NCI value

Parameters:
fDbh DBH of the tree for which to calculate the Crowding Effect.
fNCI Tree's NCI.
iSpecies Tree's species.
Returns:
Crowding Effect, between 0 and 1.

float clNCIBase::CalculateNoCrowdingEffect ( const float &  fDbh,
const float &  fNCI,
const int &  iSpecies 
) [inline, protected]

Negates the Crowding Effect.

Use this version if the user has indicated that the Shading Effect is not to be used - i.e. C = 0 or radius = 0.

Parameters:
fDbh DBH of the tree for which to calculate the Crowding Effect.
fNCI Tree's NCI.
iSpecies Tree's species.
Returns:
1, to remove Crowding Effect from growth.

float clNCIBase::CalculateNCI ( clTree p_oTree,
clTreePopulation p_oPop,
clPlot p_oPlot 
) [protected]

Calculates the NCI value for a tree.

This is the full form:

NCIi = Σ ηkλk((DBHk/q)α/distanceβ)
This makes allowances for the possibility that not all species and types will necessarily have storm damage applied to them.
Parameters:
p_oTree Tree for which to calculate NCI.
p_oPop Tree population object.
p_oPlot Plot object.
Returns:
NCI value.

float clNCIBase::CalculateNCINoEta ( clTree p_oTree,
clTreePopulation p_oPop,
clPlot p_oPlot 
) [protected]

Calculates the NCI value for a tree.

This form is used when the user is not using storm damage but is using the DBH divisor term:

NCIi = Σ λk((DBHk/q)α/distanceβ)
Parameters:
p_oTree Tree for which to calculate NCI.
p_oPop Tree population object.
p_oPlot Plot object.
Returns:
NCI value.

float clNCIBase::CalculateNCINoDivisor ( clTree p_oTree,
clTreePopulation p_oPop,
clPlot p_oPlot 
) [protected]

Calculates the NCI value for a tree.

This form is used when the user is using storm damage but has set the DBH divisor term to 1:

NCIi = Σ ηkλk(DBHkα/distanceβ)
This makes allowances for the possibility that not all species and types will necessarily have storm damage applied to them.
Parameters:
p_oTree Tree for which to calculate NCI.
p_oPop Tree population object.
p_oPlot Plot object.
Returns:
NCI value.

float clNCIBase::CalculateNCINoEtaNoDivisor ( clTree p_oTree,
clTreePopulation p_oPop,
clPlot p_oPlot 
) [protected]

Calculates the NCI value for a tree.

This form is used when the user is not using either storm damage or the DBH divisor:

NCIi = Σ λk(DBHkα/distanceβ)
Parameters:
p_oTree Tree for which to calculate NCI.
p_oPop Tree population object.
p_oPlot Plot object.
Returns:
NCI value.

float clNCIBase::CalculateNoDamageEffect ( clTree p_oTree  )  [inline, protected]

Returns 1 when there is no storm effect.

Parameters:
p_oTree Tree for which to calculate the storm effect.
Returns:
1.

float clNCIBase::CalculateDamageEffect ( clTree p_oTree  )  [protected]

Calculates the storm effect for a tree when storm effect is used.

This retrieves the tree's damage and determines whether the tree is undamaged (damage value of 0), medium damaged (1000 < value < 2000), or fully damaged (value > 2000). It then retrieves the appropriate value from the appropriate array and returns it.

Parameters:
p_oTree Tree for which to calculate the storm effect.
Returns:
The storm effect, between 0 and 1


Member Data Documentation

float** clNCIBase::mp_fLambda [protected]

Lamba for NCI.

Array assumed to be sized number of behavior species by number of total species. This array is accessed by using the species number as an array index.

float* clNCIBase::mp_fAlpha [protected]

Neighbor DBH effect.

α variable in Crowding Effect equation above. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

float* clNCIBase::mp_fBeta [protected]

Neighbor distance effect.

β variable in Crowding Effect equation above. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

float* clNCIBase::mp_fCrowdingSlope [protected]

Crowding effect slope.

C in Crowding Effect equation above. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

Crowding effect steepness.

D in Crowding Effect equation above. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

The minimum DBH, in cm, of neighbors to be included in NCI calculations.

Array assumed to be sized total number of species.

float* clNCIBase::mp_fXb [protected]

Size effect variance parameter.

Xb in Size Effect equation above. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

Maximum value, whatever that may be, in appropriate units.

Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

float* clNCIBase::mp_fX0 [protected]

Size effect mode parameter.

X0 in Size Effect equation above. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

Shading coefficient in Shading Effect equation.

The user can set this to 0 to turn off Shading Effect. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

float* clNCIBase::mp_fShadingExponent [protected]

Shading exponent in Shading Effect equation.

Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

float* clNCIBase::mp_fMedDamageEta [protected]

NCI neighbor storm medium damage parameter.

ηk in NCI equation above. This is omitted or set to 1 if not used. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

float* clNCIBase::mp_fFullDamageEta [protected]

NCI neighbor storm full damage parameter.

ηk in NCI equation above. This is omitted or set to 1 if not used. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

float* clNCIBase::mp_fGamma [protected]

Size sensitivity to NCI parameter.

γ in Crowding Effect equation above. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

Damage Effect parameter for target trees with medium damage.

This is omitted or set to 1 if not used. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

Damage Effect parameter for target trees with full damage.

This is omitted or set to 1 if not used. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

Maximum search radius, in meters, in which to look for crowding neighbors.

For calculating the Crowding Effect. Array assumed to be sized number of species to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

float clNCIBase::m_fDbhDivisor [protected]

The value to divide DBH by in NCI.

q in the NCI equation above. May be set to 1.

short int** clNCIBase::mp_iDamageCodes [protected]

Holds return data codes for the "stm_dmg" tree data member, if used.

Array size is assumed to be number of total species by 2 (saplings and adults). The "stm_dmg" tree member is only used if the species uses storm damage.

short int** clNCIBase::mp_iLightCodes [protected]

Holds return data codes for the "Light" tree data member.

Array size is assumed to be number of species to which this behavior applies by 2 (saplings and adults). The "Light" tree member is only used if the species uses the Shading Effect (i.e. mp_fShadingCoefficient != 0).

short int* clNCIBase::mp_iIndexes [protected]

Speeds access to the arrays.

Array size is assumed to be number of species.

float clNCIBase::m_fMinSaplingHeight [protected]

Minimum sapling height.

For doing neighbor searches.

short int clNCIBase::m_iNumTotalSpecies [protected]

Keep our own copy for the destructor.

This is the total number of tree species.

short int clNCIBase::m_iNumBehSpecies [protected]

Keep our own copy for the destructor.

This is the number of tree species applied to this behavior.

bool clNCIBase::m_bIncludeSnags [protected]

Whether or not to include snags in NCI.

Function pointer array for the appropriate function for calculating Shading Effect.

Array size is number of species to which this behavior applies.

Function pointer array for the appropriate function for calculating NCI.

Array size is number of species to which this behavior applies.

Function pointer array for the appropriate function for calculating Crowding Effect.

Array size is number of species to which this behavior applies.

float(clNCIBase::* clNCIBase::DamageEffect)(clTree *) [protected]

Function pointer to the appropriate damage effect calculator.

Only one is needed, because there cannot be variability between species.


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

Generated on Tue Apr 19 13:56:14 2011 for SORTIE Core C++ Documentation by  doxygen 1.5.6