|
|
|
|
||
|
DEFINITION MODULE Tallies; (******************************************************************* Module Tallies (Version 1.0) Copyright (c) 2006 by Dimitrios Gyalistras and ETH Zurich. Purpose Supports the monitoring, efficient retrieval, and statistical analysis of realizations of REAL-typed variables in a 2-dimensional, indexed space. Remarks The maximum number of index values supported by this software, as well as the maximum number of values that can be tallied for a given index combination is plattform-dependent (MacMETH compiler: 8'190, EPC & P1 compilers: 4'194'304). Smaller numbers may actually apply depending on the currently available memory. Programming o Design Dimitrios Gyalistras 25/01/2006 o Implementation Dimitrios Gyalistras 25/01/2006 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: 23/06/2006 DG *******************************************************************) FROM SYSTEM IMPORT ADDRESS; (***********************) (*##### Types #####*) (***********************) TYPE Tally; TallyAdrAttr = ADDRESS; TallyP = PROCEDURE( Tally ); StatisticsType = ( undefStatistic, n, mean, sd, skw, min, p05, p10, p25, med, p75, p90, p95, max ); VAR undefTally : Tally; (* read only *) undefTallyAdrAttr : Tally; (* read only *) (******************************************) (*##### Testing of object access #####*) (******************************************) PROCEDURE ActivateTalliesObjChecks; (* Call this procedure to switch on all checks when accessing Tally objects or their attributes using one of the procedurs below. *) PROCEDURE DeactivateTalliesObjChecks; (* Switch off all checks. Use this procedure for faster access to Tally objects and their attributes. Note, passing of dangling or NIL pointers to some of the procedures below may cause the program to crash. *) PROCEDURE TalliesObjChecksActivated(): BOOLEAN; (* Find out whether object checks are currently activated. The default setting is "TRUE". *) (***********************************************) (*##### Tally declaration and removal #####*) (***********************************************) PROCEDURE DeclareTally( VAR t : Tally; ident : ARRAY OF CHAR; storeValues : BOOLEAN; maxIndex1 : INTEGER; maxIndex2 : INTEGER ); (* Declares a tally "t" that can be used to tally values of REAL-typed variables. All tallied values are indexed using two indices that cover the range [1..maxIndex1] and [1..maxIndex2], respectively. Typically, this procedure will be called by a (sub-)model at the begin of multiple simulation runs. Tallying of simulation results can be done using procedure "TallyValue" (see below). The first index can be used e.g. to refer to the simulation run number, and the second one to the monitoring timepoint number (or vice versa). Use "storeValues = TRUE" if you plan to request from "t" other statistics than "n" or "mean" (see procedure GetStatistic below), or if you want to be able to retrieve vectors of the tallied values using procedure GetValues (see below). In some cases you may wish to tally data using only one indexing dimension, e.g. if you wish to retrieve the tallied data only by monitoring timepoint (results of different runs are pooled). Then for maximum efficiency it is recommended to keep index1 constant and to use index2 as the varying index (i.e., declare tally with maxIndex1 = const = 1 and maxIndex2 > 1). *) PROCEDURE FindTally( ident: ARRAY OF CHAR ): Tally; PROCEDURE TallyExists( t: Tally ): BOOLEAN; PROCEDURE FirstTally(): Tally; PROCEDURE NextTally( t: Tally ): Tally; PROCEDURE LastTally(): Tally; PROCEDURE PrevTally( t: Tally ): Tally; PROCEDURE RemoveTally( VAR t: Tally ); PROCEDURE RemoveAllTallies; (* This procedure is typically called by the main model at the end of multiple simulation runs. *) (**********************************) (*##### Tally attributes #####*) (**********************************) PROCEDURE TalliedValuesAreStored( t: Tally ): BOOLEAN; PROCEDURE GetTallyIdent( t: Tally; VAR ident: ARRAY OF CHAR ); PROCEDURE TallyMaxIndex1( t: Tally ): INTEGER; PROCEDURE TallyMaxIndex2( t: Tally ): INTEGER; PROCEDURE SetTallyProc( t: Tally; p: TallyP ); PROCEDURE GetTallyProc( t: Tally; VAR p: TallyP ); PROCEDURE SetTallyAddressAttr( t: Tally; attr: TallyAdrAttr ); PROCEDURE TallyAddressAttr( t: Tally): TallyAdrAttr; PROCEDURE SetTallyLongIntAttr( t: Tally; l: LONGINT ); PROCEDURE TallyLongIntAttr( t: Tally): LONGINT; PROCEDURE SetTallyIntAttr( t: Tally; i: INTEGER ); PROCEDURE TallyIntAttr( t: Tally): INTEGER; (************************************************) (*##### Values associated with indices #####*) (************************************************) (* The procedures below can be used to manage real values that are associated with the two indices used for tallying. For example, if "index2" refers to different monitoring timepoints, "AuxVal2" can be used to store the corresponding values of the time (independent) variable. *) PROCEDURE SetAuxVal1( i1: INTEGER; val1: REAL ); PROCEDURE AuxVal1( i1: INTEGER ): REAL; PROCEDURE ClearAuxVals1; PROCEDURE SetAuxVal2( i2: INTEGER; val2: REAL ); PROCEDURE AuxVal2( i2: INTEGER ): REAL; PROCEDURE ClearAuxVals2; (*********************************************) (*##### Tallying of variable values #####*) (*********************************************) PROCEDURE TallyValue( t : Tally; i1 : INTEGER; (* index value 1 *) i2 : INTEGER; (* index value 2 *) r : REAL ); (* the value *) (* Tallies the value "r" using tally "t" and index pair (i1, i2). This procedure is typically called once per monitoring event by a (sub-)model in order to tally values that can not be tallied automatically using one of the procedures provided below. NOTE: For efficiency, values equal to DMConversions.UndefREAL() are not tallied, i.e. discarded. *) PROCEDURE ForgetTalliedValues( t : Tally ); (* Forgets all tallied values for tally "t". *) PROCEDURE ForgetAllTalliedValues; (* Forgets all tallied values for all tallies. *) (*******************************************) (*##### Retrieval of tallied data #####*) (*******************************************) PROCEDURE NumTalliedValues( t : Tally; i1 : INTEGER; (* 0: discard i1, i.e. i1 = [1..maxIndex1] *) i2 : INTEGER ): INTEGER; (* 0: discard i2, i.e. i2 = [1..maxIndex2] *) PROCEDURE GetTalliedValues( t : Tally; i1 : INTEGER; (* 0: discard i1, i.e. i1 = [1..maxIndex1] *) i2 : INTEGER; (* 0: discard i2, i.e. i2 = [1..maxIndex2] *) VAR vals : ARRAY OF REAL; VAR nVals : INTEGER ); (* Note, the last up to 4 requested value vectors are stored internally to enable efficient repeated data retrieval. However, vector storage is done globally, i.e. there is a total of 4 stored vectors (not 4 vectors per tally). A possibly stored value vector for a given tally "t" is cleared each time an additional valid value (<> DMConversions.UndefREAL()) gets tallied for "t". *) (*****************************************) (*##### Retrieval of statistics #####*) (*****************************************) PROCEDURE GetIdentOfStatisticsType( stat : StatisticsType; VAR ident : ARRAY OF CHAR ); PROCEDURE StatisticsTypeOfIdent( ident: ARRAY OF CHAR ): StatisticsType; PROCEDURE GetStatistic( t : Tally; i1 : INTEGER; (* 0: discard i1, i.e. i1 = [1..maxIndex1] *) i2 : INTEGER; (* 0: discard i2, i.e. i2 = [1..maxIndex2] *) st : StatisticsType ): REAL; (* Note, every requested statistic for tally "t" is stored internally to enable efficient repeated retrieval. All stored statistics for "t" are however cleared each time an additional valid value (<> DMConversions.UndefREAL()) gets tallied for "t". *) (*****************************************) (*##### Retrieval of histograms #####*) (*****************************************) PROCEDURE GetHistogram( t : Tally; i1 : INTEGER; (* 0: discard i1, i.e. i1 = [1..maxIndex1] *) i2 : INTEGER; (* 0: discard i2, i.e. i2 = [1..maxIndex2] *) minFirstClass : REAL; maxLastClass : REAL; numClasses : INTEGER; VAR histogram : ARRAY OF INTEGER ); (* Returns in "histogram" the number of tally values from tally "t" that fall in the respective classes (bins). Class width equals (maxLastClass-minFirstClass)/numClasses. Class membership of tally values (val) is determined as follows: histogram[ 0 ]: [MIN(REAL) .. minFirstClass[ histogram[ 1 ]: [minFirstClass .. minFirstClass+classWidth[ histogram[ 2 ]: [minFirstClass+classWidth .. minFirstClass+2*classWidth[ ... histogram[ numClasses ]: [maxLastClass-classWidth .. maxLastClass[ histogram[ numClasses+1 ]: [maxLastClass .. MAX(REAL)[ *) END Tallies.
|
||
|
|
|