clStorm Class Reference

Storms version 1.0. More...

#include <Storm.h>

Inheritance diagram for clStorm:

clBehaviorBase clWorkerBase List of all members.

Public Member Functions

 clStorm (clSimManager *p_oSimManager)
 Constructor.
 ~clStorm ()
 Destructor.
void GetData (xercesc::DOMDocument *p_oDoc)
 Does behavior setup.
void TimestepCleanup ()
 Resets all values in the "Storm Damage" grid to 0.
void Action ()
 Performs the storm calculations.

Protected Types

 mapped
 Susceptibility is entered via a map.
 uniform
 Susceptibility is uniform across the plot.
 deterministic
 Deterministic damage index calculations.
 stochastic
 Stochastic damage index calculations.
 lognormal
 Lognormal distribution.
 normal
 Normal distribution.
 negative_binomial
 Negative binomial distribution.
enum  susceptibility { mapped, uniform }
 Enum for describing the damage pattern. More...
enum  stochasticity { deterministic, stochastic }
 Enum for stochasticity. More...
enum  distribution_func { lognormal, normal, negative_binomial }
 Enum for listing probability distribution functions. More...

Protected Member Functions

void DoGridSetup ()
 Does the grid setup for the behavior.
void CalculateStormProbabilities ()
 Calculates the annual probability of a storm of each severity class.
void ApplyDamage (int iSeverityClass)
 Applies the damage for a storm of a given return interval.
void ReadParFile (xercesc::DOMDocument *p_oDoc)
 Reads in parameters from the parameter file.
void SetStochFuncPointer ()
 Sets the function pointer for a stochastic damage pattern.
void AdjustTimeSinceLastStormCounter (bool bStormThisTimestep)
 Adjusts the time-since-last-storm counter held in the "stormtime" data member of the "Storm Damage" grid.
float NormalDraw (const float &fMean)
 Performs a random draw on a normal distribution.
float LognormalDraw (const float &fMean)
 Performs a random draw on a lognormal distribution.
float NegBinomialDraw (const float &fMean)
 Performs a random draw on a negative binomial distribution.

Protected Attributes

clGridBasemp_oStormGrid
 Storms grid This grid is named "Storm Damage" and it contains the severity of all storms that happened in the previous timestep.
clGridBasemp_oSusceptibilityMap
 Storm susceptibility map This grid is named "Storm Susceptibility".
float(clStorm::* RandomDraw )(const float &fNumber)
 Function pointer for the appropriate RandomDraw function.
float * mp_fStormProbabilities
 Timestep probability of the occurence of a storm of each return interval.
float mp_fStdDev
 Standard deviation for normal or lognormal probability distribution functions.
float mp_fClump
 Clumping parameter for negative binomial probability distribution function.
int m_iNumSeverityClasses
 The total number of storm return intervals.
int m_iDmgIndexCode
 Return code for the "dmg_index" data member of the "Storm Damage" grid.
int m_iStormTimeCode
 Return code for the "stormtime" data member of the "Storm Damage" grid.
int m_iSusceptIndexCode
 Return code for the "index" data member of the "Storm Susceptibility" grid.
enum clStorm::susceptibility m_iSusceptibility
 Enum for describing the damage pattern.Variable holding the susceptibility pattern value.
enum clStorm::stochasticity m_iStochasticity
 Enum for stochasticity.Variable holding the stochasticity.
enum clStorm::distribution_func m_iDistribution
 Enum for listing probability distribution functions.What probability distribution function to use if the value in m_iDamagePattern is "stochastic".

Friends

class clTestStorm
 This is for testing purposes - whenever there's a heavy stochastic component to the operation of a behavior the only effective testing happens when the testing class can get in and rig events to happen.

Detailed Description

Storms version 1.0.

The storm damage calculator’s function is to assess whether or not one or more storms has occurred, and if so, what the damage pattern and amount of damage were. It creates a map of storm damage across the plot, with each location getting a damage index between 0 (no damage) and 1 (most damage).

Deciding when storms occur
The 0 – 1 interval of storm severity values is subdivided into ten storm severity classes. Each class is assigned a return interval in the parameter file by the user. Taking the reciprocal of the return interval gives us the annual probability of each type of storm.

To decide whether a given storm occurs, a random number is compared to the annual probability. Each storm severity class is decided individually. For multi-year timesteps, there is one random “coin flip” per year per severity class. This allows multiple storms to occur in the same timestep. For multi-year timesteps, multiple storms of the same severity class can occur, up to one per year. Storm damage for multiple storms is additive, up to a max damage index of 1.

Calculating damage when storms occur
The amount of damage caused by a timestep's storms is stored in the grid named "Storm Damage". Each cell in the grid contains a value between 0 (no damage) and 1 (total damage). In addition, a counter is set containing the number of years since the last storm.

There are four damage patterns, and the value in the "Storm Damage" cells is calculated differently for each:

  1. Varying spatial distribution, deterministic. In this pattern, a static storm vulnerability map is supplied for the plot in the parameter file. The map is a set of values from 0 (no susceptibility) on up. The susceptibility value at a location is multiplied by the damage index of any storm that hits to arrive at a final damage index for that location.
  2. Varying spatial distribution, stochastic. In this pattern, a static storm vulnerability map is supplied for the plot in the parameter file. The map is a set of values from 0 (no susceptibility) to 1 (maximum susceptibility). The damage index of a storm is determined as for the “Uniform stochastic” method. Then the susceptibility value at a location is multiplied by this damage index to arrive at a final damage index for that location.
  3. Uniform deterministic. All plot locations receive the storm’s designated damage index.
  4. Uniform stochastic. The storm’s designated severity is used as the mean in a probability distribution function to arrive at a final damage index.

This behavior's call string and name string are both "storm".

Copyright 2004 Charles D. Canham

Author:
Lora E. Murphy
Edit history:
-----------------
September 9, 2004 - Created (LEM)
February 17, 2006 - Added time-since-last-storm counter (LEM)


Member Enumeration Documentation

enum clStorm::distribution_func [protected]

Enum for listing probability distribution functions.

Poisson is not included because it creates integers only - not appropriate.

Enumerator:
lognormal  Lognormal distribution.
normal  Normal distribution.
negative_binomial  Negative binomial distribution.

enum clStorm::stochasticity [protected]

Enum for stochasticity.

Enumerator:
deterministic  Deterministic damage index calculations.
stochastic  Stochastic damage index calculations.

enum clStorm::susceptibility [protected]

Enum for describing the damage pattern.

This controls the method used to calculate final damage indexes.

Enumerator:
mapped  Susceptibility is entered via a map.
uniform  Susceptibility is uniform across the plot.


Constructor & Destructor Documentation

clStorm::clStorm ( clSimManager p_oSimManager  ) 

Constructor.

Parameters:
p_oSimManager Sim Manager object.

clStorm::~clStorm (  ) 

Destructor.

Frees memory.


Member Function Documentation

void clStorm::Action (  )  [virtual]

Performs the storm calculations.

It loops through all of the storm severity classes and, for each class and for each year per timestep, uses a random number against the values in mp_fStormProbabilities to determine if a storm of a given severity has occurred. If a storm happens, ApplyDamage() is called.

Reimplemented from clBehaviorBase.

void clStorm::AdjustTimeSinceLastStormCounter ( bool  bStormThisTimestep  )  [protected]

Adjusts the time-since-last-storm counter held in the "stormtime" data member of the "Storm Damage" grid.

If there was no storm this timestep, it adds the number of years per timestep to the value. If there was a storm, it sets the value to 0.

void clStorm::ApplyDamage ( int  iSeverityClass  )  [protected]

Applies the damage for a storm of a given return interval.

The storm's mean severity is calculated by taking a random draw on its severity interval. The damage is applied according to one of the following scenarios:

Parameters:
iSeverityClass Index of the severity class, up to m_iNumSeverityClasses. This is NOT the actual number of years in the return interval. This is not validated to ensure that it is a proper array index before being used as such.

void clStorm::CalculateStormProbabilities (  )  [protected]

Calculates the annual probability of a storm of each severity class.

The probability of a storm of a given return interval is calculated as 1/length of the return interval. The return interval values should already be in mp_fStormProbabilities, put there by ReadParFile().

void clStorm::DoGridSetup (  )  [protected]

Does the grid setup for the behavior.

Steps:

  1. Check to see if m_iSusceptibility is "mapped". If it is, get the "Storm Susceptibility" grid and verify that it has been created.
  2. Check for the existence of the "Storm Damage" grid. If it has been created in the parameter file, make sure the grid cell resolution matches "Storm Susceptibility", if that grid exists.
  3. If "Storm Damage" was not created in the parameter file, create it with "Storm Susceptibility"'s grid cell resolution if that grid exists, or the default grid cell resolution if it doesn't.
  4. Call TimestepCleanup() to make sure that all values in "Storm Damage" are 0.

Exceptions:
modelErr if:
  • The damage pattern as read from the parameter file is "mapped" but there is no map in the parameter file for the grid "Storm Susceptibility"
  • Either grid is in the parameter file but not set up correctly
  • There is grid cell resolution data in the parameter file for both "Storm Damage" and "Storm Susceptibility" and they do not match

void clStorm::GetData ( xercesc::DOMDocument *  p_oDoc  )  [virtual]

Does behavior setup.

It does the following:

  1. Calls ReadParFile() to read parameter file values
  2. Calls DoGridSetup() to set up the grids
  3. Calls CalculateStormProbabilities() to calculate the annual storm probabilities
  4. Calls SetStochFuncPointer() to set the stochastic function pointer, if appropriate
Parameters:
p_oDoc DOM tree of parsed input file.

Implements clWorkerBase.

float clStorm::LognormalDraw ( const float &  fMean  )  [inline, protected]

Performs a random draw on a lognormal distribution.

The standard deviation is mp_fStdDev.

Parameters:
fMean Mean of the lognormal distribution.
Returns:
Random number between 0 and 1.

float clStorm::NegBinomialDraw ( const float &  fMean  )  [inline, protected]

Performs a random draw on a negative binomial distribution.

The clumping parameter is mp_fClump.

Parameters:
fMean Mean of the negative binomial distribution.
Returns:
Random number between 0 and 1.

float clStorm::NormalDraw ( const float &  fMean  )  [inline, protected]

Performs a random draw on a normal distribution.

The standard deviation is mp_fStdDev.

Parameters:
fMean Mean of the normal distribution.
Returns:
Random number between 0 and 1.

void clStorm::ReadParFile ( xercesc::DOMDocument *  p_oDoc  )  [protected]

Reads in parameters from the parameter file.

Exceptions:
modelErr if:
  • Any return interval is not greater than 0.
  • The susceptibility value is not recognized.
  • The stochasticity value is not recognized.
  • The stochasticity is "stochastic" and there is no value for probability distribution function, or that value is not recognized.
  • The stochasticity is "stochastic", the probability distribution function is "normal" or "lognormal", and there is no value for standard deviation.
  • The stochasticity is "stochastic", the probability distribution function is "negative_binomial", and there is no value for the clumping parameter.
Parameters:
p_oDoc DOM tree of parsed input file.

void clStorm::SetStochFuncPointer (  )  [protected]

Sets the function pointer for a stochastic damage pattern.

If m_iDamagePattern is not "stochastic", nothing happens. If it is, this sets the value for clStorm::*RandomDraw depending on the value in m_iDistribution.


Member Data Documentation

enum clStorm::distribution_func clStorm::m_iDistribution [protected]

Enum for listing probability distribution functions.What probability distribution function to use if the value in m_iDamagePattern is "stochastic".

Poisson is not included because it creates integers only - not appropriate. Value comes from the parameter file.

int clStorm::m_iNumSeverityClasses [protected]

The total number of storm return intervals.

Hardcoded.

enum clStorm::stochasticity clStorm::m_iStochasticity [protected]

Enum for stochasticity.Variable holding the stochasticity.

Value comes from the parameter file. This controls how the damage pattern is applied - whether the same damage index is applied to all cells or whether it is randomized for each.

enum clStorm::susceptibility clStorm::m_iSusceptibility [protected]

Enum for describing the damage pattern.Variable holding the susceptibility pattern value.

This controls the method used to calculate final damage indexes. Value comes from parameter file. If the susceptibility is uniform, all locations have a susceptibility index of 1. If it is mapped, the "Storm Susceptibility" grid holds each location's susceptibility between 0 and 1.

float clStorm::mp_fClump [protected]

Clumping parameter for negative binomial probability distribution function.

This is only used if m_iStochasticity = stochastic and m_iDistribution = negative_binomial. Value comes from the parameter file.

float clStorm::mp_fStdDev [protected]

Standard deviation for normal or lognormal probability distribution functions.

This is only used if m_iStochasticity = stochastic and m_iDistribution = lognormal or normal. Value comes from the parameter file.

float* clStorm::mp_fStormProbabilities [protected]

Timestep probability of the occurence of a storm of each return interval.

Array size is m_iNumSeverityClasses. These values are calculated in CalculateStormProbabilities().

clGridBase* clStorm::mp_oStormGrid [protected]

Storms grid This grid is named "Storm Damage" and it contains the severity of all storms that happened in the previous timestep.

It is of user-settable resolution. It contains two float data members: the first is "dmg_index", which contains the damage index as a value from 0 (no damage) to 1 (total damage). The second is "stormtime", which contains the time since the last storm, in years. 0 means a storm occurred in the current timestep.

If there is a map for the "Storm Susceptibility" grid, and no other grid resolution information for this grid, then this grid will use the resolution of "Storm Susceptibility".

clGridBase* clStorm::mp_oSusceptibilityMap [protected]

Storm susceptibility map This grid is named "Storm Susceptibility".

It has one float data member called "index". The value in "index" is a value from 0 (no storm susceptibility) to 1 (total storm susceptibility).

If the susceptibility = the enum value "mapped", then a grid map for this grid is expected in the parameter file. The values it contains will not be changed throughout the run. The grid resolution must match that of "Storm Damage" grid.

If the damage pattern is something other than "mapped", then this pointer is left as NULL and the grid is not initialized or used.


The documentation for this class was generated from the following file:
Generated on Wed Nov 29 08:42:24 2006 for SORTIE Core C++ Documentation by  doxygen 1.4.7