SORTIE Core C++ Documentation
Protected Types | Protected Member Functions | Protected Attributes | List of all members
clNCIBase Class Reference

NCI Base Class - version 1.1. More...

#include <NCIBase.h>

Inheritance diagram for clNCIBase:
clNCIGrowth clNCIMort

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:
--------------—
October 20, 2011 - Wiped the slate clean for SORTIE 7.0 (LEM)

Member Typedef Documentation

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.

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

Define a type for pointers to functions of the ShadingEffect 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

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
fDbhDBH of the tree for which to calculate the Crowding Effect.
fNCITree's NCI.
iSpeciesTree'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
fDbhDBH of the tree for which to calculate the Crowding Effect.
fNCITree's NCI.
iSpeciesTree'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
fDbhDBH of the tree for which to calculate the Crowding Effect.
fNCITree's NCI
iSpeciesTree'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
fDbhDBH of the tree for which to calculate the Crowding Effect.
fNCITree's NCI.
iSpeciesTree'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_oTreeTree 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_oTreeTree for which to calculate NCI.
p_oPopTree population object.
p_oPlotPlot 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_oTreeTree for which to calculate NCI.
p_oPopTree population object.
p_oPlotPlot 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_oTreeTree for which to calculate NCI.
p_oPopTree population object.
p_oPlotPlot 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_oTreeTree for which to calculate NCI.
p_oPopTree population object.
p_oPlotPlot object.
Returns
NCI value.
float clNCIBase::CalculateNoCrowdingEffect ( const float &  fDbh,
const float &  fNCI,
const int &  iSpecies 
)
inlineprotected

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
fDbhDBH of the tree for which to calculate the Crowding Effect.
fNCITree's NCI.
iSpeciesTree's species.
Returns
1, to remove Crowding Effect from growth.
float clNCIBase::CalculateNoDamageEffect ( clTree p_oTree)
inlineprotected

Returns 1 when there is no storm effect.

Parameters
p_oTreeTree for which to calculate the storm effect.
Returns
1.
float clNCIBase::CalculateNoShadingEffect ( clTree p_oTree)
inlineprotected

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_oTreeTree 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_oTreeTree 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_oTreeTree 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
iNumBehaviorSpeciesNumber of species to which the behavior is applied.
p_oPopTree 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.

bool clNCIBase::m_bIncludeSnags
protected

Whether or not to include snags in NCI.

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 to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

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 to which this behavior applies. This array is accessed by using the index returned for mp_iIndexes[species number].

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: