clNCIBase Class Reference

NCI Base Class - version 1.0. 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 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.0.

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λk((DBHk/q)α/distanceβ)
where:

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)


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

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::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::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::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::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

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::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::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::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::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::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::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.

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.


Member Data Documentation

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.

float clNCIBase::m_fDbhDivisor [protected]
 

The value to divide DBH by in NCI.

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

float clNCIBase::m_fMinSaplingHeight [protected]
 

Minimum sapling height.

For doing neighbor searches.

short int clNCIBase::m_iNumBehSpecies [protected]
 

Keep our own copy for the destructor.

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

short int clNCIBase::m_iNumTotalSpecies [protected]
 

Keep our own copy for the destructor.

This is the total number of tree species.

Ptr2CrowdingEffect* clNCIBase::mp_CrowdingEffect [protected]
 

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

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

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].

float* clNCIBase::mp_fCrowdingSteepness [protected]
 

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].

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. If used, there has to be a value for all species, even if they don't use this behavior, since they will be neighbors. This array is accessed by using the species number as an array index.

float* clNCIBase::mp_fFullDamageStormEff [protected]
 

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].

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].

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_fMaxCrowdingRadius [protected]
 

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::mp_fMaxPotentialValue [protected]
 

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_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. If used, there has to be a value for all species, even if they don't use this behavior, since they will be neighbors. This array is accessed by using the species number as an array index.

float* clNCIBase::mp_fMedDamageStormEff [protected]
 

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].

float* clNCIBase::mp_fMinimumNeighborDBH [protected]
 

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_fShadingCoefficient [protected]
 

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_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].

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].

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_iIndexes [protected]
 

Speeds access to the arrays.

Array size is assumed to be number of species.

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).

Ptr2CalculateNCI* clNCIBase::mp_NCI [protected]
 

Function pointer array for the appropriate function for calculating NCI.

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

Ptr2ShadingEffect* clNCIBase::mp_ShadingEffect [protected]
 

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

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


The documentation for this class was generated from the following file:
Generated on Mon Mar 27 12:51:17 2006 for SORTIE Core C++ Documentation by  doxygen 1.4.6-NO