clStorm Class Reference

Storms version 3.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 Action ()
 Performs the storm calculations.

Protected Types

enum  susceptibility { mapped, uniform }
 Enum for describing the damage pattern. More...
enum  stochasticity { deterministic, stochastic }
 Enum for stochasticity. More...
enum  distribution_func { lognormal, normal }
 Enum for listing probability distribution functions. More...

Protected Member Functions

void DoGridSetup ()
 Does the grid setup fo the behavior.
void CalculateStormProbabilities ()
 Calculates the annual probability of a storm of each severity class.
void ApplyDamage (float fMeanSeverity)
 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 DoSeverityAverages ()
 Calculates mean storm severity for each cell.
void AdjustTimeSinceLastStormCounter (bool bStormThisTimestep)
 Adjusts the time-since-last-storm counter held in the "stormtime" data member of the "Storm Damage" grid.
void PackageCleanup ()
 Resets all values in the "Storm Damage" grid to 0.
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.

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".
struct clStorm::stcStormsmp_stormsList
 Structure for holding scheduled storm events.
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 m_fSSTPeriod
 SST periodicity (Sr).
float m_fSineD
 Sine function d.
float m_fSineF
 Sine function f.
float m_fSineG
 Sine function g.
float m_fTrendSlopeM
 Trend function slope (m).
float m_fTrendInterceptI
 Trend function intercept (i).
int m_iNumSeverityClasses
 The total number of storm return intervals.
int m_i1DmgIndexCode
 Return code for the "1dmg_index" data member of the "Storm Damage" grid.
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.
int m_iNumScheduledStorms
 How many scheduled storms are in mp_stormsList.
enum clStorm::susceptibility m_iSusceptibility
 Enum for describing the damage pattern.
enum clStorm::stochasticity m_iStochasticity
 Enum for stochasticity.
enum clStorm::distribution_func m_iDistribution
 Enum for listing probability distribution functions.

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.

Classes

struct  stcStorms
 Structure for holding scheduled storm events. More...


Detailed Description

Storms version 3.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. Each storm event creates a separate record in the storm damage grid. Storm severity is bounded between 0 and 1.

The frequency of storms can optionally be cyclical (sinusoidal), with an optional overall trend. The actual probability of any storm that uses a cyclical storm regime is:

P'(Fi) = P(Fi) * ([d*sin(pi(x-g)/(2f))] + [mx + i])
where:

Storm events can also be specifically scheduled. In this case, they will occur in addition to any background storms. The user supplies a minimum and a maximum value for the storm intensity and a timestep.

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 can contain 0 or more packages. 0 packages indicates no storm occurred. There is one package for each storm that occurred that timestep, with a single 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


Edit history:
-----------------
September 9, 2004 - Created (LEM)
February 17, 2006 - Added time-since-last-storm counter (LEM)
March 5, 2007 - Removed negative binomial distribution since it made no sense (LEM)
March 6, 2007 - Added storm cyclicity and made version 2.0 (LEM)
May 29, 2007 - Changed damage from additive to separate packages and made version 2.1 (LEM)
December 7, 2007 - Added storm scheduling and made version 3.0 (LEM)

Author:
Lora E. Murphy

Member Enumeration Documentation

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.

enum clStorm::stochasticity [protected]

Enum for stochasticity.

Enumerator:
deterministic  Deterministic damage index calculations.

stochastic  Stochastic damage index calculations.

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.


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

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::DoGridSetup (  )  [protected]

Does the grid setup fo 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::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::ApplyDamage ( float  fMeanSeverity  )  [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:

  • If the storm stochasticity is deterministic and the susceptibility is uniform, the value of the storm damage index is added to each cell of the "Storm Damage" grid (up to a max of 1).
  • If the storm stochasticity is stochastic and the susceptibility is uniform, for each cell in the "Storm Damage" grid, the value of the storm damage index is fed as the mean to the appropriate random draw function in the math library to get a new storm damage index; then this value is added to the cell (up to a max of 1).
  • If the storm stochasticity is deterministic and the susceptibility is mapped, the storm damage index is multiplied by the appropriate cell value in the "Storm Susceptibility" grid and added to the cell of the "Storm Damage" grid (up to a max of 1).
  • If the storm stochasticity is stochastic and the susceptibility is mapped, for each cell in the "Storm Damage" grid, the value of the storm damage index is fed as the mean to the appropriate random draw function in the math library to get a new storm damage index. This index is multiplied by the appropriate cell value in the "Storm Susceptibility" grid and added to the cell of the "Storm Damage" grid (up to a max of 1).
Parameters:
fMeanSeverity The mean severity to use for this storm.

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

void clStorm::DoSeverityAverages (  )  [protected]

Calculates mean storm severity for each cell.

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::PackageCleanup (  )  [protected]

Resets all values in the "Storm Damage" grid to 0.

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.

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.


Friends And Related Function Documentation

friend class clTestStorm [friend]

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.


Member Data Documentation

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; one called "dmg_index", which is the mean of all storm severities for that grid cell, and one called "stormtime", which contains the time since the last storm, in years. For "stormtime", 0 means a storm occurred in the current timestep. It also can contain 1 or more packages, each with a float data member called "1dmg_index", which contains the damage index as a value from 0 (no damage) to 1 (total damage).

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

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.

Structure for holding scheduled storm events.

List of scheduled storms - NULL if no storms

float(clStorm::* clStorm::RandomDraw)(const float &fNumber) [protected]

Function pointer for the appropriate RandomDraw function.

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

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

SST periodicity (Sr).

float clStorm::m_fSineD [protected]

Sine function d.

float clStorm::m_fSineF [protected]

Sine function f.

float clStorm::m_fSineG [protected]

Sine function g.

float clStorm::m_fTrendSlopeM [protected]

Trend function slope (m).

float clStorm::m_fTrendInterceptI [protected]

Trend function intercept (i).

The total number of storm return intervals.

Hardcoded.

int clStorm::m_i1DmgIndexCode [protected]

Return code for the "1dmg_index" data member of the "Storm Damage" grid.

int clStorm::m_iDmgIndexCode [protected]

Return code for the "dmg_index" data member of the "Storm Damage" grid.

int clStorm::m_iStormTimeCode [protected]

Return code for the "stormtime" data member of the "Storm Damage" grid.

Return code for the "index" data member of the "Storm Susceptibility" grid.

How many scheduled storms are in mp_stormsList.

Enum for describing the damage pattern.

This controls the method used to calculate final damage indexes. Variable holding the susceptibility pattern value. 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.

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 for listing probability distribution functions.

Poisson is not included because it creates integers only - not appropriate. What probability distribution function to use if the value in m_iDamagePattern is "stochastic". Value comes from the parameter file.


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

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