DEFINITION MODULE TreeSpecies;
(*******************************************************************
Module TreeSpecies (Version 1.0)
Copyright (c) 2003-2006 by Dimitrios Gyalistras and ETH Zurich.
Purpose Handling of tree species and their parameters.
Remarks This module is part of the package Trees.
Programming
o Design
Dimitrios Gyalistras 19/07/2003
o Implementation
Dimitrios Gyalistras 19/07/2003
ETH Zurich
Systems Ecology
CHN E 35.1
Universitaetstrasse 16
8092 Zurich
SWITZERLAND
URLs:
<mailto:RAMSES@env.ethz.ch>
<http://www.sysecol.ethz.ch>
<http://www.sysecol.ethz.ch/SimSoftware/RAMSES>
Last revision of definition: 31/12/2005 DG
*******************************************************************)
IMPORT Errors;
(**************************************)
(*##### General declarations #####*)
(**************************************)
CONST
notDone = Errors.onlyAnInsert;
(*
The procedures exported below return resCode = Errors.allOk if the
call to the procedure was succesfull, and resCode = notDone if not.
*)
CONST
kB1 = 137.0; (* "breast height", cm *)
TYPE
TreeSpecies;
TreeSpeciesType = ( undefTSType, deciduous, evergreen );
FoliageCalcType = ( undefFCType, fcFC24, fcFC26 );
WinTemperLimType = ( undefWTLType, wtlFC24, wtlFC29 );
LightLimType = ( undefLLType, llFC24, llFC26 );
DegDaysLimType = ( undefDDLType, ddlFC24, ddlFC29 );
SoilMoistGFType = ( undefSMGFType, smgfFC24, smgfFC26, smgfFC29 );
DegDaysGFType = ( undefDDGFType, ddgfFC24, ddgfFC29 );
NitrogenGFType = ( undefNGFType, ngfFC24, ngfFC29 );
LitterProdType = ( undefLPType, lpFC24, lpFC26 );
TSParamsPtr = POINTER TO TSParamsRec;
TSParamsRec = RECORD
(* Species type *)
tsType : TreeSpeciesType;
(* Real-valued parameters *)
(* Identifier Description Unit MinVal MaxVal *)
(* 1.1 - Foliage and maximum growth parameters *)
folType : REAL; (* foliage type [-] 1 5 *)
kDMax : REAL; (* maximum diameter at breast height [cm] 1.0 500.0 *)
kHMax : REAL; (* maximum height [cm] kB1 10000.0 *)
kAMax : REAL; (* maximum age [y] 1.0 3000.0 *)
kG : REAL; (* growth rate parameter [cm/y] 0.001 1000.0 *)
(* 1.2 - Derived foliage and maximum growth parameters *)
kA1 : REAL; (* f{ folType }, allometric param. for dry foliage weight [kg/cm] 0.03 0.6 *)
kA2 : REAL; (* f{ folType }, allometric param. for dry foliage weight [-] 1.4 1.7 *)
kB2 : REAL; (* f{ kDMax, kHMax }, allometric parameter [-] 0.0 19726.0 *)
kB3 : REAL; (* f{ kDMax, kHMax }, allometric parameter [1/cm] 0.0 9863.0 *)
kC1 : REAL; (* f{ tsType, fcType }, foliage dry to wet weight ratio [%/100] 0.2 0.7 *)
kC2 : REAL; (* f{ tsType, fcType }, foliage area per unit flg weight [m^2/kg] 3.0 18.0 *)
(* 2 - Tree establishment parameters *)
kWiTN : REAL; (* minimum winter minimum temperature [degC] -100.0 10.0 *)
kWiTX : REAL; (* maximum winter minimum temperature [degC] -10.0 100.0 *)
kLy : REAL; (* shade tolerance for tree establishment [-] 0.5 9.5 (llFC24) *)
(* 0.0 1.0 (llFC26) *)
kBrow : REAL; (* browsing susceptibility parameter [-] 0.5 3.5 *)
kDDMinE : REAL; (* minimum annual degree-day sum for establishment [degC*d] 1.0 8000.0 *)
kDDMaxE : REAL; (* maximum annual degree-day sum for establishment [degC*d] 1.0 8000.0 *)
(* 3.1 - Growth factor calculation parameters *)
kLa : REAL; (* shade tolerance of adult trees [-] 0.5 9.5 *)
kDrT : REAL; (* drought tolerance [-] 0.01 1.0 *)
kFlTol : REAL; (* flooding tolerance [-] 0 5 *)
kDDMinG : REAL; (* minimum annual degree-day sum for growth [degC*d] 1.0 8000.0 *)
kDDMaxG : REAL; (* maximum annual degree-day sum for growth [degC*d] 1.0 8000.0 *)
kNTol : REAL; (* nitrogen tolerance [-] 1 3 (ngfFC24) *)
(* 1 5 (ngfFC29) *)
(* 3.2 - Derived growth factor calculation parameters *)
kFl : REAL; (* f{ kFlTol }, flooding response function parameter [-] 0.0 1.0 *)
kN1 : REAL; (* f{ ntType, kNTol }, N response function parameter [-] -0.04 -0.005 *)
kN2 : REAL; (* f{ ntType, kNTol }, soil N response function parameter [-] 1.0 60.0 *)
(* 4.1 - Litter production parameters *)
kLQ : REAL; (* leaf litter type [-] 1 3 (lpFC24) *)
(* 1 6 (lpFC26) *)
(* 4.2 - Derived litter production parameters *)
kFRT : REAL; (* f{ tsType, lpType } foliage retention time [-] 0.5 6.0 *)
kTwig : REAL; (* f{ lpType } twig litter production parameter [kg/cm^2] 0.001 0.004 *)
kAFW : REAL; (* f{ lpType } ash-free weight of litter [%/100] 0.5 1.5 *)
kRSR : REAL; (* root:shoot ratio of litter (used if lpType=lpFC24) [-] 1.0 9.0 *)
END;
TSParamType = ( undefTSPType,
(* 1.1 - Foliage and maximum growth parameters *)
folType, kDMax, kHMax, kAMax, kG,
(* 1.2 - Derived foliage and maximum growth parameters *)
kA1, kA2, kB2, kB3, kC1, kC2,
(* 2 - Tree establishment parameters *)
kWiTN, kWiTX, kLy, kBrow, kDDMinE, kDDMaxE,
(* 3.1 - Growth factor calculation parameters *)
kLa, kDrT, kFlTol, kDDMinG, kDDMaxG, kNTol,
(* 3.2 - Derived growth factor calculation parameters *)
kFl, kN1, kN2,
(* 4.1 - Litter production parameters *)
kLQ,
(* 4.2 - Derived litter production parameters *)
kFRT, kTwig, kAFW, kRSR
);
VAR
undefTreeSpecies : TreeSpecies; (* read only *)
(***************************)
(*##### Auxiliary #####*)
(***************************)
PROCEDURE IsValidTSParamId( VAR (*speed-up*) id: ARRAY OF CHAR ): BOOLEAN;
(* Returns TRUE if a parameter with identifier "id" is
known/supported by this module. *)
PROCEDURE TSParamTypeOfId( ts : TreeSpecies;
id : ARRAY OF CHAR ): TSParamType;
(* Returns the parameter type of parameter with identifier "id". *)
PROCEDURE ClearTSParamsRec( VAR params: TSParamsRec );
PROCEDURE CheckTSParamsRec( VAR callee : ARRAY OF CHAR; (* VAR for speed up only *)
checkDrvd : BOOLEAN; (* if TRUE derived parameters are also checked *)
VAR spIdent : ARRAY OF CHAR; (* VAR for speed up only *)
fcType : FoliageCalcType;
wtlType : WinTemperLimType;
llType : LightLimType;
ddlType : DegDaysLimType;
smgfType : SoilMoistGFType;
ddgfType : DegDaysGFType;
ngfType : NitrogenGFType;
lpType : LitterProdType;
VAR params : TSParamsRec; (* VAR for speed up only *)
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE CheckTSParamsRecForTreeSpecies( VAR callee : ARRAY OF CHAR; (* VAR for speed up only *)
checkDrvd : BOOLEAN; (* if TRUE derived parameters are also checked *)
ts : TreeSpecies;
VAR params : TSParamsRec; (* VAR for speed up only *)
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE CalcDerivedParams( ts : TreeSpecies;
VAR params : TSParamsRec );
(********************************************************)
(*##### Declaration and removal of TreeSpecies #####*)
(********************************************************)
PROCEDURE DeclTreeSpecies( (* naming *)
ident : ARRAY OF CHAR;
scientificName : ARRAY OF CHAR;
commonEnglishName : ARRAY OF CHAR;
commonGermanName : ARRAY OF CHAR;
(* used parameterizations *)
fcType : FoliageCalcType;
wtlType : WinTemperLimType;
llType : LightLimType;
ddlType : DegDaysLimType;
smgfType : SoilMoistGFType;
ddgfType : DegDaysGFType;
ngfType : NitrogenGFType;
lpType : LitterProdType;
(* the parameter values *)
params : TSParamsRec;
(* calculation of derived parameters *)
calcDerivedParams : BOOLEAN;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
If "caclDerivedParams" = TRUE the "derived parameters" (see definition
of "TSParamsRec" above) are determined based on the "primary"
parameters found within the variable "params", depending on the used
parameterizations. Otherwise parameter values for the "derived parameters"
are used as specified in variable "params".
*)
PROCEDURE DeclTreeSpeciesFromDataFrames( fcType : FoliageCalcType;
wtlType : WinTemperLimType;
llType : LightLimType;
ddlType : DegDaysLimType;
smgfType : SoilMoistGFType;
ddgfType : DegDaysGFType;
ngfType : NitrogenGFType;
lpType : LitterProdType;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Declares tree species based on contents of the currently
loaded data frames (see procedure DataFrames.LoadDataFrames).
Considered are all data frames with definitions "MODEL = ANY;"
and "KEYCOLUMN = OutFileIdent;".
NOTE: The set of species actually declared is defined by the
species list available in the *last* loaded data frame with
a key column named "TSIdent" of type "Identifier" (see also
procedure DataFrames.GetIdVec). Moreover, a species is only
declared if a data frame value definition
".useTreeSpecies" of type BOOLEAN exists and
has the value "TRUE".
*)
PROCEDURE UndeclTreeSpecies( ts: TreeSpecies );
PROCEDURE UndeclAllTreeSpecies;
(****************************************************)
(*##### Retrieval/Looping over TreeSpecies #####*)
(****************************************************)
PROCEDURE NumTreeSpecies(): INTEGER;
PROCEDURE FindTreeSpecies( ident: ARRAY OF CHAR ): TreeSpecies;
PROCEDURE TreeSpeciesExists( ts: TreeSpecies ): BOOLEAN;
PROCEDURE FirstTreeSpecies(): TreeSpecies;
PROCEDURE NextTreeSpecies( ts: TreeSpecies ): TreeSpecies; (* does not check ts for efficiency! *)
(***************************************************)
(*##### Get/set attributes of TreeSpecies #####*)
(***************************************************)
PROCEDURE TreeSpeciesUniqueId( ts: TreeSpecies ): LONGINT;
(*
Returns a unique number associated with tree species
"ts". The number corresponds to the declaration order
of the species (see procedure "DeclTreeSpecies") since
loading of this module, or since the last call to
UndeclAllTreeSpecies.
*)
PROCEDURE GetTreeSpeciesIdent( ts: TreeSpecies; VAR ident: ARRAY OF CHAR );
PROCEDURE SetTreeSpeciesIdent( ts: TreeSpecies; ident: ARRAY OF CHAR );
PROCEDURE GetTreeSpeciesNames( ts : TreeSpecies;
VAR scientificName : ARRAY OF CHAR;
VAR commonEnglishName : ARRAY OF CHAR;
VAR commonGermanName : ARRAY OF CHAR );
PROCEDURE SetTreeSpeciesNames( ts : TreeSpecies;
scientificName : ARRAY OF CHAR;
commonEnglishName : ARRAY OF CHAR;
commonGermanName : ARRAY OF CHAR );
PROCEDURE GetTreeSpeciesParameterizations( ts : TreeSpecies;
VAR fcType : FoliageCalcType;
VAR wtlType : WinTemperLimType;
VAR llType : LightLimType;
VAR ddlType : DegDaysLimType;
VAR smgfType : SoilMoistGFType;
VAR ddgfType : DegDaysGFType;
VAR ngfType : NitrogenGFType;
VAR lpType : LitterProdType );
PROCEDURE GetTSParamsPtr( ts: TreeSpecies ): TSParamsPtr;
(* Enables efficient access to the tree species' parameters.
Should be used read-only. *)
PROCEDURE GetTSParamsRec( ts : TreeSpecies;
VAR params : TSParamsRec );
PROCEDURE SetTSParamsRec( ts : TreeSpecies;
params : TSParamsRec;
calcDerivedParams : BOOLEAN;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE TSParamVal( pType : TSParamType;
VAR params : TSParamsRec ): REAL; (* VAR for speed-up only *)
(* Get the value of parameter of type "pType" from
record "params". *)
PROCEDURE SetTSParamVal( pType : TSParamType;
VAR params : TSParamsRec;
value : REAL );
(* Set the value of parameter of type "pType" in record
"params" to "value". WARNING: for efficiency reasons no
validity or range checks are performed on "value".
Moreover, note that if "params" belongs to a TreeSpecies
object, no handlers will be called (see procedure
InstallTSEventHandler below). *)
(*******************************************************)
(*##### Attributes of tree species parameters #####*)
(*******************************************************)
PROCEDURE GetTSParamAttrs( pType : TSParamType;
fcType : FoliageCalcType;
wtlType : WinTemperLimType;
llType : LightLimType;
ddlType : DegDaysLimType;
smgfType : SoilMoistGFType;
ddgfType : DegDaysGFType;
ngfType : NitrogenGFType;
lpType : LitterProdType;
VAR id : ARRAY OF CHAR; (* identifier *)
VAR used : BOOLEAN; (* TRUE if currently used under the given parameterizations *)
VAR drvd : BOOLEAN; (* TRUE if parameter value is derived from primary parameter(s) *)
VAR min : REAL; (* minimum value *)
VAR max : REAL ); (* maximum value *)
PROCEDURE GetTSParamAttrsForTreeSpecies( ts : TreeSpecies;
pType : TSParamType;
VAR id : ARRAY OF CHAR;
VAR used : BOOLEAN;
VAR drvd : BOOLEAN;
VAR min : REAL;
VAR max : REAL );
PROCEDURE GetTSParamId ( ts : TreeSpecies;
pType : TSParamType;
VAR id : ARRAY OF CHAR );
PROCEDURE TSParamUsed ( ts : TreeSpecies;
pType : TSParamType ): BOOLEAN;
PROCEDURE IsDerivedTSParam( ts : TreeSpecies;
pType : TSParamType ): BOOLEAN;
PROCEDURE TSParamMin ( ts : TreeSpecies;
pType : TSParamType ): REAL;
PROCEDURE TSParamMax ( ts : TreeSpecies;
pType : TSParamType ): REAL;
(************************************************)
(*##### Handling of derived parameters #####*)
(************************************************)
(*
The following procedures enable retrieval and setting of the
derived parameters values for the derived parameters that are
functions of tsType, fcType, llType, lpType (see definition
of "TSParamsRec" above). Note, the "Set" procedures
will affect all currently declared tree species objects.
*)
PROCEDURE GetAllometricParams24( VAR kC1Decid : REAL;
VAR kC2Decid : REAL;
VAR kC1Evrgr : REAL;
VAR kC2Evrgr : REAL );
PROCEDURE GetAllometricParams26( VAR kC1Decid : REAL;
VAR kC2Decid : REAL;
VAR kC1Evrgr : REAL;
VAR kC2Evrgr : REAL );
PROCEDURE SetAllometricParams24( kC1Decid : REAL;
kC2Decid : REAL;
kC1Evrgr : REAL;
kC2Evrgr : REAL );
PROCEDURE SetAllometricParams26( kC1Decid : REAL;
kC2Decid : REAL;
kC1Evrgr : REAL;
kC2Evrgr : REAL );
PROCEDURE GetLitterProductionParams24( VAR kFRTDecid : REAL;
VAR kFRTEvrgr : REAL;
VAR kTwig : REAL;
VAR kAFW : REAL;
VAR kRSR : REAL );
PROCEDURE GetLitterProductionParams26( VAR kFRTDecid : REAL;
VAR kFRTEvrgr : REAL;
VAR kTwig : REAL;
VAR kAFW : REAL );
PROCEDURE SetLitterProductionParams24( kFRTDecid : REAL;
kFRTEvrgr : REAL;
kTwig : REAL;
kAFW : REAL;
kRSR : REAL );
PROCEDURE SetLitterProductionParams26( kFRTDecid : REAL;
kFRTEvrgr : REAL;
kTwig : REAL;
kAFW : REAL );
(********************************)
(*##### Event handling #####*)
(********************************)
TYPE
TreeSpeciesEventType = ( undefTSEType, tsDeclared, tsParamChanged, tsRemoved );
TreeSpeciesEventHandler = PROCEDURE( TreeSpeciesEventType, TreeSpecies );
PROCEDURE InstallTSEventHandler( h: TreeSpeciesEventHandler );
PROCEDURE RemoveTSEventHandler ( h: TreeSpeciesEventHandler );
END TreeSpecies.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib