clHarvestInterface Class Reference

Harvest Interface - Version 1.0. More...

#include <HarvestInterface.h>

Inheritance diagram for clHarvestInterface:

clBehaviorBase clWorkerBase List of all members.

Public Member Functions

 clHarvestInterface (clSimManager *p_oSimManager)
 Constructor.
 ~clHarvestInterface ()
 Destructor.
void Action ()
 Performs the harvest.
void GetData (xercesc::DOMDocument *p_oDoc)
 Performs setup.
void SetNameData (char *cNameString)
 Captures the namestring passed to this behavior.
void RegisterTreeDataMembers ()
 Registers any new data members requested by the user.

Protected Types

 notassigned
 Not assigned a type.
 isfloat
 Float data member.
 isint
 Int data member.
 ischar
 Char data member.
 isbool
 Bool data member.
enum  member_type {
  notassigned, isfloat, isint, ischar,
  isbool
}
 Enum for types of tree data members. More...

Protected Attributes

enum clHarvestInterface::member_typemp_iMemberType
 Enum for types of tree data members Array for holding tree data member types.
char ** mp_cNewTreeDataMembers
 Array of labels for any new tree data members that this interface is to create.
char ** mp_cFileColumns
 Array of columns in the files.
char m_cExecutable [MAX_FILENAME_SIZE]
 Path to user executable.
char m_cInputFile [MAX_FILENAME_SIZE]
 Path and filename of the input file to the harvest executable that this behavior will prepare.
char m_cTreesToCutFile [MAX_FILENAME_SIZE]
 Path and filename of the file of the trees to cut that is created by the harvest executable.
char m_cTreesToUpdateFile [MAX_FILENAME_SIZE]
 Path and filename of the file of the trees to update that is created by the harvest executable - empty string if not needed.
char m_cBatchFileIn [MAX_FILENAME_SIZE]
 Path and filename of the batch parameters input file that this will read - empty string if not needed.
char m_cBatchParamsOut [MAX_FILENAME_SIZE]
 Path and filename of the parameters output file that this will write in the event of a batch - empty string if not needed.
char m_cArguments [MAX_ARGUMENT_LENGTH]
 Argument string to pass to the user executable - empty string if not needed.
bool ** mp_bAppliesToTrees
 Which trees this behavior is applied to.
int * mp_iColumnTranslation
 Translation array between file columns and user-defined data members.
bool * mp_bUserDefinedColumn
 Which of the file columns are user-defined new tree data members.
int m_iNextTimestepToHarvest
 The next timestep a harvest will be performed.
int m_iPeriod
 How often, in timesteps, harvests occur.
int m_iNumFileColumns
 Number of columns in the text files.
int m_iNumSpecies
 Total number of species, for the destructor.
short int m_iReasonCode
 Reason code to pass to the tree population when trees are killed.

Detailed Description

Harvest Interface - Version 1.0.

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: "Harvest Interface (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 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 "Harvest Interface"; the parameter file call string is as described above.

Author:
Lora E. Murphy

Edit history:
-----------------
September 13, 2006 - Created (LEM)


Member Enumeration Documentation

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 ( clSimManager p_oSimManager  ) 

Constructor.

Parameters:
p_oSimManager Sim Manager object.


Member Function Documentation

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:

Reimplemented from clBehaviorBase.

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.

void clHarvestInterface::SetNameData ( char *  cNameString  )  [virtual]

Captures the namestring passed to this behavior.

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

Parameters:
cNameString Behavior's namestring.

Reimplemented from clBehaviorBase.


Member Data Documentation

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.

bool* clHarvestInterface::mp_bUserDefinedColumn [protected]

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

Array size is m_iNumFileColumns.

char** clHarvestInterface::mp_cFileColumns [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.

char** clHarvestInterface::mp_cNewTreeDataMembers [protected]

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

The array is sized m_iNewTreeFloats.

int* clHarvestInterface::mp_iColumnTranslation [protected]

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.

enum clHarvestInterface::member_type * clHarvestInterface::mp_iMemberType [protected]

Enum for types of tree data members Array for holding tree data member types.

Array size is m_iNumFileColumns.


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