Harvest Interface - Version 1.1. More...

#include <HarvestInterface.h>

Inheritance diagram for clHarvestInterface:

Public Member Functions
	clHarvestInterface (clSimManager *p_oSimManager)
	Constructor. More...

	~clHarvestInterface ()
	Destructor. More...

void	Action ()
	Performs the harvest. More...

void	GetData (xercesc::DOMDocument *p_oDoc)
	Performs setup. More...

void	SetNameData (std::string sNameString)
	Captures the namestring passed to this behavior. More...

void	RegisterTreeDataMembers ()
	Registers any new data members requested by the user. More...

Public Member Functions inherited from clBehaviorBase
virtual float	GetBehaviorVersion ()
	Gets the behavior version number. More...

	clBehaviorBase (clSimManager *p_oSimManager)
	Constructor. More...

virtual	~clBehaviorBase ()
	Destructor. More...

virtual short int	ValidateVersionNumber (float fTestVersion)
	Makes sure that the version number of a file passed is between the minimum and current version numbers. More...

virtual void	SetSpeciesTypeCombos (short int iNumCombos, stcSpeciesTypeCombo *p_whatCombos)
	Sets the species/type combos for a behavior. More...

virtual short int	GetNewTreeInts ()
	Gets the number of new tree integer data members this behavior wants to register. More...

virtual short int	GetNewTreeFloats ()
	Gets the number of new tree float data members this behavior wants to register. More...

virtual short int	GetNewTreeChars ()
	Gets the number of new tree character data members this behavior wants to register. More...

virtual short int	GetNewTreeBools ()
	Gets the number of new tree bool data members this behavior wants to register. More...

virtual short int	GetNumSpeciesTypeCombos ()
	Gets the number of species/type combos to which this behavior applies. More...

virtual short int	GetNumBehaviorSpecies ()
	Gets the number of unique tree species to which this behavior applies. More...

struct stcSpeciesTypeCombo	GetSpeciesTypeCombo (short int iIndex)
	Gets one of this behavior's type/species combos. More...

virtual short int	GetBehaviorSpecies (short int iIndex)
	Gets one of the behavior's species. More...

short int	GetBehaviorListNumber ()
	Gets the behavior list number for this behavior, which differentiates between multiple copies of the behavior in the behavior list. More...

void	SetBehaviorListNumber (short int iNumber)
	Sets the behavior list number for this behavior, which differentiates between multiple copies of the behavior in the behavior list. More...

std::string	FormatSpeciesTypeQueryString ()
	Formats the string for species/types query. More...

virtual DOMElement *	GetParentParametersElement (xercesc::DOMDocument *p_oDoc)
	This will get the correct set of parameters for this behavior based on the behavior list position number. More...

Public Member Functions inherited from clWorkerBase
	clWorkerBase (clSimManager *p_oSimManager)
	Constructor. More...

virtual	~clWorkerBase ()
	Destructor. More...

std::string	GetName ()
	Gets the object's namestring. More...

clSimManager *	GetSimManager ()

void	DoObjectSetup (xercesc::DOMDocument *p_oDoc, fileType iFileType)
	Triggers the setup process. More...

virtual void	TimestepCleanup ()
	Performs any necessary cleanup operations at the end of a timestep. More...

virtual void	EndOfRunCleanup ()
	Performs any necessary cleanup operations at the end of a run. More...

Protected Types
enum	member_type { notassigned, isfloat, isint, ischar, isbool }
	Enum for types of tree data members. More...

Protected Member Functions
void	ResetResultsGrid ()
	Resets all the values in the Harvest Results grid. More...

void	SetupResultsGrid ()
	Sets up the "Harvest Results grid" and gets all the return codes. More...

Protected Member Functions inherited from clWorkerBase
void	AssembleFileCode (int iFileType, int iFileVersion, char *cCode)
	Creates the proper identifying filecode for an XML file. More...

Protected Attributes
enum clHarvestInterface::member_type *	mp_iMemberType
	Array for holding tree data member types. More...

std::string *	mp_sNewTreeDataMembers
	Array of labels for any new tree data members that this interface is to create. More...

std::string *	mp_sFileColumns
	Array of columns in the files. More...

std::string	m_sExecutable
	Path to user executable. More...

std::string	m_sInputFile
	Path and filename of the input file to the harvest executable that this behavior will prepare. More...

std::string	m_sTreesToCutFile
	Path and filename of the file of the trees to cut that is created by the harvest executable. More...

std::string	m_sTreesToUpdateFile
	Path and filename of the file of the trees to update that is created by the harvest executable - empty string if not needed. More...

std::string	m_sBatchFileIn
	Path and filename of the batch parameters input file that this will read - empty string if not needed. More...

std::string	m_sBatchParamsOut
	Path and filename of the parameters output file that this will write in the event of a batch - empty string if not needed. More...

std::string	m_sArguments
	Argument string to pass to the user executable - empty string if not needed. More...

bool **	mp_bAppliesToTrees
	Which trees this behavior is applied to. More...

int *	mp_iColumnTranslation
	Initial values for the new float data members (if any). More...

bool *	mp_bUserDefinedColumn
	Which of the file columns are user-defined new tree data members. More...

int	m_iNextTimestepToHarvest
	The next timestep a harvest will be performed. More...

int	m_iPeriod
	How often, in timesteps, harvests occur. More...

int	m_iNumFileColumns
	Number of columns in the text files. More...

int	m_iNumSpecies
	Total number of species, for the destructor. More...

short int	m_iNumAllowedCutRanges
	Number of cut ranges allowed in "Harvest Results" grid - this comes from the class clDisturbance. More...

deadCode	m_iReasonCode
	Reason code to pass to the tree population when trees are killed. More...

short int	m_iHarvestTypeCode
	Harvest Type data member code in "Harvest Results" grid. More...

short int **	mp_iDenCutCodes
	Cut Density data member codes in "Harvest Results" grid. More...

short int **	mp_iBaCutCodes
	Cut Basal Area data member codes in "Harvest Results" grid. More...

clGrid *	mp_oResultsGrid
	Harvest results grid, with same format as in clDisturbance. More...

Protected Attributes inherited from clBehaviorBase
short int	m_iNumSpeciesTypeCombos
	How many type/species combos a behavior will act on. More...

short int	m_iNumBehaviorSpecies
	How many distinct species are in the combo list - important for filling species-specific values from parameter file. More...

short int *	mp_iWhatSpecies
	List of distinct species - for filling species-specific values from parameter file. More...

stcSpeciesTypeCombo *	mp_whatSpeciesTypeCombos
	Array of species/type combos that the behavior will act on. More...

short int	m_iNewTreeInts
	The number of new tree integer data members this behavior wants to add. More...

short int	m_iNewTreeFloats
	The number of new tree float data members this behavior wants to add. More...

short int	m_iNewTreeChars
	The number of new tree character data members this behavior wants to add. More...

short int	m_iNewTreeBools
	The number of new tree boolean data members this behavior wants to add. More...

short int	m_iBehaviorListNumber
	The number of this behavior in the behavior list, to differentiate between possible multiple copies of this behavior. More...

float	m_fVersionNumber
	Version number - this will be rounded to 2 digits after the decimal place. More...

std::string	m_sXMLRoot
	XML root that encloses the parameters for this behavior. More...

float	m_fMinimumVersionNumber
	Minimum version number - this behavior will run parameter data for a file marked between this number and the current version number, inclusive. More...

Protected Attributes inherited from clWorkerBase
std::string	m_sNameString
	If a behavior has registered a command line command with the sim manager, this allows it to be called. More...

clSimManager *	mp_oSimManager
	Pointer to the simulation manager object. More...

int *	mp_iAllowedFileTypes
	List of the input file types this object can handle. More...

int	m_iNumAllowedTypes
	Number of input file types this object can handle. More...

Detailed Description

Harvest Interface - Version 1.1.

This behavior serves as an interface between SORTIE and a user-written executable for harvesting. (Although code that did something besides harvesting is certainly possible for the creative programmer as well.)

This behavior executes on a user-defined cycle. When it executes, it gathers all eligible trees and writes them to a text file. It then calls the user executable. It expects the executable to create a file (with a pre-arranged name) with the list of trees to cut.

The user may also ask for new tree data members to be added on the executable's behalf. If this is the case, the user executable can also write a file of trees to to update with new values for those data members. The new data members (which are all floats), and their initial values, are passed in on the behavior's parameter file call string as follows: "HarvestInterface (name1) (name2)" etc. The initial values will always be 0. (We cannot do otherwise - a SORTIE run is constantly creating new trees, but we don't know which ones they are; so this behavior will never know (outside of initial conditions) which trees are new and which have a legitimately set value of 0.)

The file SORTIE writes for the user executable is tab-delimited text and has the following format: Line 1, two columns: Current timestep, total number of timesteps Line 2, column names, 6+n columns: "X", "Y", "Species", "Type", "Diam", "Height", [any additional variables that the user wishes]. Subsequent lines, 6+n columns, one line per tree: X, Y, species number, type number, DBH/diam10, height, [any additional variables that the user wishes, including new variables they have defined]. The "Diam" value is diameter at 10 cm if the tree type is seedling, and DBH in all other cases.

The file format of the user response files is identical to that of the SORTIE file, with the same columns in the same order. Each timestep, all these files are overwritten. Any other files in the working directory are ignored. (Incidentally, the timestep line in the response file will be ignored by SORTIE, so technically it doesn't have to be anything in particular.)

The list of harvested trees will be used to update the "Harvest Results" grid. This grid is the same as that produced by the clDisturbance class; however, if clDisturbance is also trying to use this grid in the same run, they will not play nicely together and will probably overwrite each other's results (at best). For each harvested species, this grid contains members called "Cut Density_0_x" and "Cut Basal Area_0_x" where x is the species number. These are raw density/BA values for each grid cell (8 m x 8 m) and are not converted to per ha amounts. The grid also contains a data member called "Harvest Type" that equals -1 if there was no harvesting in a grid cell this timestep, or 0 (partial cut) if there were harvested trees.

The user executable runs once per timestep. It does not stay running. So it must do any necessary initialization and setup each time. The executable can be written in any language, and can do anything it wishes. The only two requirements is that it be a standalone executable, and that it produce the file of trees to harvest that SORTIE expects.

If the user executable wants input parameters through SORTIE, it can have this behavior pass them as a string argument when the executable is launched. If it uses a file for input parameters, and SORTIE is running in batch mode, the user can specify a file with parameters for each run, one set per line; this behavior will extract the line corresponding to the batch number and write it to a specified file before calling the user executable.

The name string for this behavior is "HarvestInterface"; the parameter file call string is as described above.

Author: Lora E. Murphy

Edit history:
--------------—
October 20, 2011 - Wiped the slate clean for SORTIE 7.0 (LEM)

Member Enumeration Documentation

◆ member_type

enum clHarvestInterface::member_type

protected

Enum for types of tree data members.

Enumerator
notassigned	Not assigned a type.
isfloat	Float data member.
isint	Int data member.
ischar	Char data member.
isbool	Bool data member.

Constructor & Destructor Documentation

◆ clHarvestInterface()

clHarvestInterface::clHarvestInterface ( clSimManager * p_oSimManager )

Constructor.

Parameters

p_oSimManager Sim Manager object.

◆ ~clHarvestInterface()

clHarvestInterface::~clHarvestInterface ( )

Destructor.

Member Function Documentation

◆ Action()

void clHarvestInterface::Action ( )

virtual

Performs the harvest.

The timestep is compared to m_iNextTimestepToHarvest. If they are not equal, the behavior exits. If they are equal, then:

m_iNextTimestepToHarvest is incremented with the value in m_iPeriodicity
All trees to which this behavior applies are collected and written to an input file for the harvesting program
The harvesting program is called, passing the parameters and the input file of trees
The harvest (and possibly update) output file(s) are read into memory
All trees to which this behavior applies are compared to the harvest (and output) list(s) and if they're on it (by way of type, species, X, Y, and diameter being equal) they are killed (or updated).

Reimplemented from clBehaviorBase.

◆ GetData()

void clHarvestInterface::GetData ( xercesc::DOMDocument * p_oDoc )

virtual

Performs setup.

This reads from the parameter file. It verifies the working directory and its contents. If this is a batch run and the user has asked for the batch parameter file splitting, it writes this run's parameters.

Parameters

p_oDoc DOM tree of parsed input file.

Exceptions

modelErr

if:

The user executable is missing
Tree data members requested in the harvest file do not exist (data members that already exist, not those being created by this interface)
Number of timesteps between calls to the user executable is negative
Set of batch parameters too short for the number of requested runs

Implements clWorkerBase.

◆ RegisterTreeDataMembers()

void clHarvestInterface::RegisterTreeDataMembers ( )

virtual

Registers any new data members requested by the user.

Reimplemented from clBehaviorBase.

◆ ResetResultsGrid()

void clHarvestInterface::ResetResultsGrid ( )

protected

Resets all the values in the Harvest Results grid.

Harvest Type becomes -1; all others are 0.

◆ SetNameData()

void clHarvestInterface::SetNameData ( std::string sNameString )

virtual

Captures the namestring passed to this behavior.

This parses out any tree data members that may be riding along on the string.

Parameters

sNameString Behavior's namestring.

Reimplemented from clBehaviorBase.

◆ SetupResultsGrid()

void clHarvestInterface::SetupResultsGrid ( )

protected

Sets up the "Harvest Results grid" and gets all the return codes.

Member Data Documentation

◆ m_iHarvestTypeCode

short int clHarvestInterface::m_iHarvestTypeCode

protected

Harvest Type data member code in "Harvest Results" grid.

◆ m_iNextTimestepToHarvest

int clHarvestInterface::m_iNextTimestepToHarvest

protected

The next timestep a harvest will be performed.

◆ m_iNumAllowedCutRanges

short int clHarvestInterface::m_iNumAllowedCutRanges

protected

Number of cut ranges allowed in "Harvest Results" grid - this comes from the class clDisturbance.

◆ m_iNumFileColumns

int clHarvestInterface::m_iNumFileColumns

protected

Number of columns in the text files.

◆ m_iNumSpecies

int clHarvestInterface::m_iNumSpecies

protected

Total number of species, for the destructor.

◆ m_iPeriod

int clHarvestInterface::m_iPeriod

protected

How often, in timesteps, harvests occur.

◆ m_iReasonCode

deadCode clHarvestInterface::m_iReasonCode

protected

Reason code to pass to the tree population when trees are killed.

◆ m_sArguments

std::string clHarvestInterface::m_sArguments

protected

Argument string to pass to the user executable - empty string if not needed.

◆ m_sBatchFileIn

std::string clHarvestInterface::m_sBatchFileIn

protected

Path and filename of the batch parameters input file that this will read - empty string if not needed.

◆ m_sBatchParamsOut

std::string clHarvestInterface::m_sBatchParamsOut

protected

Path and filename of the parameters output file that this will write in the event of a batch - empty string if not needed.

◆ m_sExecutable

std::string clHarvestInterface::m_sExecutable

protected

Path to user executable.

◆ m_sInputFile

std::string clHarvestInterface::m_sInputFile

protected

Path and filename of the input file to the harvest executable that this behavior will prepare.

◆ m_sTreesToCutFile

std::string clHarvestInterface::m_sTreesToCutFile

protected

Path and filename of the file of the trees to cut that is created by the harvest executable.

◆ m_sTreesToUpdateFile

std::string clHarvestInterface::m_sTreesToUpdateFile

protected

Path and filename of the file of the trees to update that is created by the harvest executable - empty string if not needed.

◆ mp_bAppliesToTrees

bool** clHarvestInterface::mp_bAppliesToTrees

protected

Which trees this behavior is applied to.

The first index is number of species, the second is number of types.

◆ mp_bUserDefinedColumn

bool* clHarvestInterface::mp_bUserDefinedColumn

protected

Which of the file columns are user-defined new tree data members.

Array size is m_iNumFileColumns.

◆ mp_iBaCutCodes

short int** clHarvestInterface::mp_iBaCutCodes

protected

Cut Basal Area data member codes in "Harvest Results" grid.

Array size is number of cut ranges by number of species

◆ mp_iColumnTranslation

int* clHarvestInterface::mp_iColumnTranslation

protected

Initial values for the new float data members (if any).

Array size is m_iNewTreeFloats. Translation array between file columns and user-defined data members. Array size is m_iNumFileColumns. For each column, the value is the matching array index in mp_cNewTreeDataMembers, or -1 if the column is not a new user-defined tree data member.

◆ mp_iDenCutCodes

short int** clHarvestInterface::mp_iDenCutCodes

protected

Cut Density data member codes in "Harvest Results" grid.

Array size is number of cut ranges by number of species

◆ mp_iMemberType

enum clHarvestInterface::member_type * clHarvestInterface::mp_iMemberType

protected

Array for holding tree data member types.

Array size is m_iNumFileColumns.

◆ mp_oResultsGrid

clGrid* clHarvestInterface::mp_oResultsGrid

protected

Harvest results grid, with same format as in clDisturbance.

◆ mp_sFileColumns

std::string* clHarvestInterface::mp_sFileColumns

protected

Array of columns in the files.

These are labels of tree data members (with the exception of the generic "Diam"). The array is sized m_iNumFileColumns.

◆ mp_sNewTreeDataMembers

std::string* clHarvestInterface::mp_sNewTreeDataMembers

protected

Array of labels for any new tree data members that this interface is to create.

The array is sized m_iNewTreeFloats.

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

HarvestInterface.h

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ member_type

Constructor & Destructor Documentation

◆ clHarvestInterface()

◆ ~clHarvestInterface()

Member Function Documentation

◆ Action()

◆ GetData()

◆ RegisterTreeDataMembers()

◆ ResetResultsGrid()

◆ SetNameData()

◆ SetupResultsGrid()

Member Data Documentation

◆ m_iHarvestTypeCode

◆ m_iNextTimestepToHarvest

◆ m_iNumAllowedCutRanges

◆ m_iNumFileColumns

◆ m_iNumSpecies

◆ m_iPeriod

◆ m_iReasonCode

◆ m_sArguments

◆ m_sBatchFileIn

◆ m_sBatchParamsOut

◆ m_sExecutable

◆ m_sInputFile

◆ m_sTreesToCutFile

◆ m_sTreesToUpdateFile

◆ mp_bAppliesToTrees

◆ mp_bUserDefinedColumn

◆ mp_iBaCutCodes

◆ mp_iColumnTranslation

◆ mp_iDenCutCodes

◆ mp_iMemberType

◆ mp_oResultsGrid

◆ mp_sFileColumns

◆ mp_sNewTreeDataMembers