ETHZ_Logo RAMSES_Logo_Right   RAMSES   RAMSES_Logo_Left Systems Ecology  
Start    search button      Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

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.

  Contact RAMSES@env.ethz.ch Last updated: 25-Jul-2011 [Top of page]