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.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib