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 SysDatAccess;

  (*******************************************************************

    Module  SysDatAccess     (ISIS_Version_1.2)

      Copyright (c) 1997-2006 by Andreas Fischlin, Dimitrios Gyalistras
      and ETH Zurich.

    Purpose   Support the reading of data frames, retrieval of
              information from the data frames, and the
              assignment of the data to systems, models, and
              model objects.

    Remarks   All objects have to be declared via routines from
              module SysModBase (objects declared via 'ModelWorks'
              can not be accessed).  However, this is different for
              the global parameters of the simulation environment,
              which can also be accessed via module SimBase from
              'ModelWorks'.

              This module is a sister module to SimDatAccess.
              In contrast to the latter, this module works only
              for ISIS models and model objects, i.e.  entities
              which have been declared via the routines from
              the module SysModBase or SysModDSBase.

              See also modules SimDatAccess, SysModBase, and
              DataFrames.

              This module belongs to ISIS
              Integrative Systems Implementation Software.


    Programming

      o Design
        Andreas Fischlin         23/01/1997
        Dimitrios Gyalistras     23/01/1997

      o Implementation
        Andreas Fischlin         16/09/1997


    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:  07/06/1998  AF

  *******************************************************************)

  FROM DMLanguage IMPORT userBase;
  FROM SysModBase IMPORT System, OutVar;


  (* Error constants: sysDatAccessErrOffset = DMLanguage.userBase + 390 .. 400 *)



  (**********************************)
  (*#####   Easy Use Routine   #####*)
  (**********************************)

  PROCEDURE LoadAndAssignData(pfn: ARRAY OF CHAR; s: System);
    (*
      Convenient procedure which first loads the data from the
      data frame file pfn (may contain a path) into memory and
      assigns them to the system s as declared by means of module
      SysModBase.

      Loading is done only conditionally, i.e. if pfn is a
      non-empty string it will load the data frames specified in
      that file.  If pfn is the empty string the routine tries to
      use the data from whichever data frames are currently in
      memory.  However, in case there are currently no data
      frames in memory and pfn is the empty string, the routine
      offers a file opening dialog.  In the latter case if you
      wish to learn which file was actually opened, you must use
      routines from module DatFraAux (see procedure
      InspectDataFrame, especially parameter storedOnFsWithName
      and/or procedure InspectDataFrameFile).  No filtering takes
      place while loading the data frames, i.e. the filter range
      is set to [DataFrames.minFilter..DataFrames.maxFilter].

      Matching rules for assignments are those described for all
      assigning procedures from this module (see in particular
      routines AssignModelData, AssignModelsMObjData,
      AssignModelsMonitoring, and AssignModelsTallying).

      If s is an existing system, the assignment is done by
      calling these procedures:

         - AssignSystemsModelData,
         - AssignSystemsMObjData
         - AssignSystemsMonitoring, and
         - AssignSystemsTallying.

      Every model or model object which belongs to the system
      will be affected.  If the system is a parent system, the
      effect will be inherited to the system's children!  If mode
      reportOnCheckFail (see module SysStrctAux) is active, the
      following check procedures are also called:

         - CheckSystemsMObjData,
         - CheckModelsMonitoring, and
         - CheckModelsTallying.

      If you pass unknownSystem from SysModBase as actual argument
      for s, assignment takes place for all models and all model
      objects with public access for writing (see DataAccess from
      module SysModBase)!
    *)


  (**********************************************************)
  (*#####         Setting of global parameters         #####*)
  (**********************************************************)


  PROCEDURE AssignGlobalSimulationData;
    (*
      Assigns the data stored in all currently available data
      frames (see also module DataFrames) to the matching
      global simulation parameters.  The following global
      parameters are supported (see also module SimBase from
      'ModelWorks'):

       DATAFRAME     Meaning and Examples
       ---------     -----------------------------------------
       GlobSimPars   Global simulation parameters: t0, tend, h
                     er, c, hm
       Windows       Arrangement of windows: ModelsIOW,
                     StateVarsIOW, ModelParsIOW, MonitVarsIOW,
                     TableW, GraphW, AboutW, TimeW,
                     and DatFraViewerW
       SimEnvOptions Global options of simulation environment:
                     wtitle, wremark, autofooter, recM, recSV,
                     recP, recMV, recG, recTF, wtitle, wremark,
                     autofooter, recM, askStashFType,
                     docuAlwRuns, redrawAlwT, redrawAlwG,
                     colorVectGrap, and windowsTiled
       Project       Project description: projTitl, projRema,
                     and projFoot


       Examples:

          DATAFRAME GlobSimPars;
          KEYCOLUMN = Ident; DATA:
          (*---------------*)
          Ident   DfltVal   ;
          (*---------------*)
          t0       0.0      ;
          tend    30.0      ;
          h        0.05     ;
          er       0.001    ;
          c        1.0      ;
          hm       0.25     ;
          (*---------------*)
          END GlobSimPars;


          DATAFRAME Project; KEYCOLUMN = Ident; DATA:
          (*---------------------------------------*)
          Ident     DfltString                      ;
          (*---------------------------------------*)
          projTitl  ''                              ;
          projRema  ''                              ;
          projFoot  '28/Sep/1997   15:18   Run 1'   ;
          (*---------------------------------------*)
          END Project;


          DATAFRAME Windows; REMARK = 'Arrangement of windows'; KEYCOLUMN = Ident; DATA:
          (*--------------------------------------------------------------------------------*)
          Ident Open WinLowLeftX WinLowLeftY WinWidth WinHeight ShowCurVal ShowIdent ShowDescr
          ShowUnit RealFieldWidth RealDecDigits ShowRTCFlag ShowScaleMin ShowScaleMax        ;
          (*--------------------------------------------------------------------------------*)
          ModelsIOW     TRUE      0 625 511 104 TRUE TRUE TRUE NA   NA  NA  NA    NA    NA   ;
          StateVarsIOW  TRUE    513 625 511 104 TRUE TRUE TRUE TRUE 0   3   NA    NA    NA   ;
          ModelParsIOW  TRUE      0 501 511 104 TRUE TRUE TRUE TRUE 0   3   FALSE NA    NA   ;
          MonitVarsIOW  TRUE    513 501 511 104 TRUE TRUE TRUE TRUE 0   3   NA    FALSE FALSE;
          TableW        TRUE     -1   2 339 255 NA   NA   NA   NA   NA  NA  NA    NA    NA   ;
          GraphW        TRUE    341   0 683 481 NA   NA   NA   NA   NA  NA  NA    NA    NA   ;
          AboutW        FALSE    51  36 922 658 NA   NA   NA   NA   NA  NA  NA    NA    NA   ;
          TimeW         FALSE   960 737  64  11 NA   NA   NA   NA   NA  NA  NA    NA    NA   ;
          DatFraViewerW TRUE     -1 276 341 224 NA   NA   NA   NA   NA  NA  NA    NA    NA   ;
          (*--------------------------------------------------------------------------------*)
          END Windows;


          DATAFRAME SimEnvOptions;
          KEYCOLUMN = Ident; DATA:
          (*-----------------------*)
          Ident	          DfltFlag	;
          (*-----------------------*)
          wtitle	      TRUE	    ;
          wremark	      TRUE	    ;
          autofooter	  TRUE	    ;
          recM	          TRUE	    ;
          recSV	          FALSE	    ;
          recP	          FALSE	    ;
          recMV	          TRUE	    ;
          recG	          FALSE	    ;
          recTF	          FALSE	    ;
          askStashFType	  FALSE	    ;
          docuAlwRuns	  FALSE	    ;
          redrawAlwT  	  TRUE	    ;
          redrawAlwG	  TRUE	    ;
          colorVectGraph  TRUE	    ;
          windowsTiled	  TRUE	    ;
          (*-----------------------*)
          END SimEnvOptions;

    *)

  PROCEDURE DeassignGlobalSimulationData;
    (*
      Reverts the effect of AssignGlobalSimulationData and
      restores the values which were present just before the
      last call to AssignGlobalSimulationData.
    *)




  (**************************************************************)
  (*#####            Setting the data of models            #####*)
  (**************************************************************)


  PROCEDURE AssignModelData( s: System; modelIdent: ARRAY OF CHAR );
    (*
      Assigns the data stored in all currently available data
      frames (see also module DataFrames) to the matching model
      "modelIdent" as declared by means of module SysModBase.  A
      match is given if the same identifier is used for both the
      value definition in the data frame and the model.  Note, in
      case of multiple value definitions encountered during
      reading the data frames, the data finally assigned to the
      model are those found last in the reading sequence
      (overwriting principle).

      If s is the system which owns the model, the assignment
      is successful it the model is private (see DataAccess
      from module SysModBase).  If the model is public (see
      module SysModBase) you may pass also unknownSystem from
      SysModBase and the assignment is still successful.

      The assignment of following data are supported:

       DATAFRAME     Meaning and Examples
       ---------     -----------------------------------------
       Models        Model specifications: Method (Euler, Heun,
                     RungeKutta4, RungeKutta45Var, discreteTime,
                     discreteEvent) and Descr

       Implementation restriction: It is of course only possible
       to alter the integration methods for models of kind DESS.
       Any other changes would imply that the model transforms
       from one basic kind to another, e.g.  the coercion of a
       DESS into a SQM or vice versa is not possible.

       Example:

       Having declared a system and a model using routines from module
       SysModBase as this

          DeclSystem (s);
          DeclModel (s, "myModel", DESS, LogisticDiffEqu, ...

       loading this data frame

          DATAFRAME Models; MODEL = ANY; KEYCOLUMN = Ident;
          DATA:
          (*-----------------------------------------------*)
          Ident     Method  Descr                           ;
          (*-----------------------------------------------*)
          myModel   Euler   'Logistic grass growth model'   ;
          (*-----------------------------------------------*)
          END Models;

       plus calling

          AssignModelData(s, "myModel");

       will lead to an assignment of the data contained in the
       data frame to the model myModel.

    *)

  PROCEDURE SetModelData ( s: System; modelIdent: ARRAY OF CHAR;
                           method: ARRAY OF CHAR);
    (*
       Works the same way as AssignModelData but data are not
       taken from data frames but are passed as actual arguments.
       Only the core data, i.e.  the integration method for
       models of type DESS, can be assigned by this technique.
       The general rules for the DataAccess attribute of the
       involved model apply.

       Example:

       Having declared a system and a model using routines from module
       SysModBase as this

          DeclSystem (s);
          DeclModel (s, "myModel", DESS, LogisticDiffEqu, ...

       plus calling

         SetModelData(s, "myModel", 'RungeKutta4');

       will lead to an assignment of the integration method
       Runge-Kutta4th order to the model myModel.
     *)

  PROCEDURE DeassignModelData( s: System; modelIdent: ARRAY OF CHAR );
    (*
      Reverts the effect of AssignModelData or SetModelData
      and restores the data of the model which were present
      before the last assignment made by any of these
      procedures.
    *)

  PROCEDURE AssignSystemsModelData  ( s: System );	
  PROCEDURE DeassignSystemsModelData( s: System );	
    (*
      Work the same way as AssignModelData or DeassignModelData,
      respectively, but perform the operation on all models which
      belong to the system s.  There are two differences in
      behavior in comparison with AssignModelData: (i) If s is
      unknownSystem from SysModBase, s is considered to be not
      existing and the routine has no effect and will not affect
      any of the public models.  (ii) If the system is a parent
      system, the effect will be inherited to all the system's
      children!
    *)

  PROCEDURE AssignAllModelData;
    (*
      Similar to AssignModelData but affects not a specific
      model, but all currently existing models in case they are
      public (see DataAccess from module SysModBase).
    *)

  PROCEDURE DeassignAllModelData;
    (*
      Basically reverts the effect of AssignAllModelData.
      However, note, it actually restores the data which were
      present before the last assignment made to any public
      model currently declared, regardless wether the
      assignment was made by AssignModelData, SetModelData, or
      AssignAllModelData.
    *)

  PROCEDURE GetModelData( s: System; modelIdent: ARRAY OF CHAR;
                          VAR method: ARRAY OF CHAR);
    (*
      Allows to learn about the current method of a model via
      the model's identifier.  GetModelData succeeds for a
      public model also if you pass as actual argument
      unknownSystem for s; however, it succeds for a private
      model only if you pass the correct owning system.
    *)



  (***********************************************************)
  (*#####       Setting the data of model objects       #####*)
  (***********************************************************)

  (*---------------------------------------*)
  (*=====   Individual Model Object   =====*)
  (*---------------------------------------*)

  PROCEDURE AssignMObjData( s: System; mObjQualIdent: ARRAY OF CHAR );
    (*
      Assigns the data stored in all currently available data
      frames (see also module DataFrames) to the matching model
      object "mObjQualIdent".  A match is given if the same
      identifier is used for both the value definition in the
      data frame and the model object.  Note, in case of multiple
      value definitions encountered during loading of the data
      frames, the data finally assigned to the model object are
      those found last in the reading sequence (overwriting
      principle).

      If s is the system which owns the model, the assignment
      is also successful for any private model object (see
      DataAccess from module SysModBase).  For all model
      objects which are public (see module SysModBase) you may
      pass also unknownSystem from SysModBase and the
      assignment may still be successful.

      The assignment of following data are supported:

       DATAFRAME       Meaning and Examples
       ---------       -----------------------------------------
       ModIDModObjects Model objects of model ModID: Unit, Descr
       ModIDStateVars  State Variables of model ModID: DfltInit,
                       MinInit, MaxInit
       ModIDPars       Parameters of model ModID: DfltVal, MinVal,
                       MaxVal, RTC

      Example:

       Having declared model objects using routines from module
       SysModBase as this

          DeclMObj  (s, "myModel.G", stateVar, G);
          DeclMObj  (s, "myModel.GDot", derivative, GDot);
          DeclMObj  (s, "myModel.c1", modParam, c1);
          DeclMObj  (s, "myModel.c2", modParam, c2);

       loading these data frames

          DATAFRAME myModelModObjects; MODEL = myModel;
          KEYCOLUMN = Ident; DATA:
          (*------------------------------------------------*)
          Ident Unit                   Descr                 ;
          (*------------------------------------------------*)
          G     'g dry weight/m^2'     'Grass'               ;
          GDot  'g dry weight/m^2/day' 'Grass derivative'    ;
          c1    '/day'                 'c1 (growth rate)'    ;
          c2    'm^2/g dw/day'         'c2 (self inhibition)';
          (*------------------------------------------------*)
          END myModelModObjects;


          DATAFRAME myModelPars; MODEL = myModel;
          KEYCOLUMN = Ident; DATA:
          (*-----------------------------------------------*)
          Ident DfltVal    MinVal   MaxVal   RTC            ;
          (*-----------------------------------------------*)
          c1    0.7        0.0      10.0     TRUE           ;
          c2    0.0012345  0.0       1.0     TRUE           ;
          (*-----------------------------------------------*)
          END myModelPars;

       plus calling

          AssignMObjData(s, "myModel.c1");

       will lead to an assignment of data to the model parameter
       c1 as follows: value 0.7, the unit string "/day", the
       descriptor string "c1 (growth rate)", the range used to
       constrain interactive editing [0.0 ..  10.0], and the flag
       RTC will be enabled, i.e.  parameter changes at run time
       will be allowed.

    *)


  PROCEDURE SetMObjData( s: System; mObjQualIdent: ARRAY OF CHAR;
                          value: REAL);
   (*
      Works similar to AssignMObjData bit data are not taken from
      data frames but are passed as actual arguments.  Only the
      core data, i.e.  for example the initial value for state
      variables, can be assigned by this technique.  The general
      rules for the DataAccess attribute of the involved
      model objects apply.

      Example:

      Having declared model objects using routines from module
      SysModBase as this

         DeclMObj  (s, "myModel.G", stateVar, G);
         DeclMObj  (s, "myModel.GDot", derivative, GDot);
         DeclMObj  (s, "myModel.c1", modParam, c1);

      plus calling

        SetMObjData(s, "myModel.G", 2.1);
        SetMObjData(s, "myModel.c1", 0.31);

      will lead to an assignment of 2.1 to the initial value of
      the state variable G and of 0.31 to the value of model
      parameter c1.

    *)

  PROCEDURE MObjData( s: System; mObjQualIdent: ARRAY OF CHAR): REAL;
    (*
      Allows to learn about the current value of a model
      object via the model object's qualified identifier
      mObjQualIdent.  MObjData succeeds for a public
      model object also if you pass as actual argument
      unknownSystem for s; however, it succeds for a
      private model object only if you pass the correct
      owning system.

      Type                      Value returned
      ----                      --------------
      stateVar                  current initial value
      derivative                DMConversions.UndefREAL()
      modParam                  current value
      inVar, outVar, auxVar     current value

      WARNING: public model objects are not output variables
      (OutVar) from a systems theoretical viewpoint.
      Therefore correct linking between submodels SHOULD ONLY
      be made by routine EstablishLink from module SysModBase
      and NOT by using public model objects which may be of
      any kind of system variable, e.g.  they may even be a
      model parameter.  Moreover, this procedure is much less
      efficient for actual linking of submodels than if you
      use routine EstablishLink from module SysModBase.
      Thus, don't use MObjData for linking, ONLY USE
      EstablishLink from SysModBase!
    *)

  PROCEDURE OutVal(mObjQualIdent: ARRAY OF CHAR): OutVar;
    (*
      Similar to MObjData but returns the current value of the
      output variable denoted by mObjQualIdent.  In contrast to
      MObjData, the data (values) of output variables may be
      accessed by any model and require therefore not to know
      the owning system.  If the model object does not exist or
      is not an output variable, UndefREAL from DMConversions is
      returned.

      WARNING: This routine is not particularly efficient; thus
      use the linking feature from module SysModBase instead if
      you want to link outputs of a model to inputs of another
      model for actual simulation purposes (see e.g.  routine
      EstablishLink).  This routine is mainly of use in
      exceptional cases where you need to learn about the current
      output value, e.g.  in a link break handler, when you want to
      implement a sample and hold connection between an output and
      its corresponding link at the time the link is broken (e.g.
      the output variable ceases to exist etc.).  See comments on
      data linking in module SysModBase for more details on this.
    *)

  PROCEDURE DeassignMObjData( s: System; mObjQualIdent: ARRAY OF CHAR );
    (*
      Reverts the effect of e.g.  AssignMObjData and restores
      the values which were present just before the last call to
      a procedure which has assigned data.  Depending on the
      current mode (see preference 'clearAtDeassignMode' from
      module SysDatAux) either the values as present before last
      assignment are restored or missing value data are assigned
      to all involved model objects.
    *)


  (*-------------------------------------*)
  (*=====   Model's Model Objects   =====*)
  (*-------------------------------------*)

  PROCEDURE AssignModelsMObjData( s: System; modelIdent: ARRAY OF CHAR );
    (*
      Similar to AssingMObjData but assigns the data stored in
      all currently available data frames (see also module
      DataFrames) to all matching model objects of model
      "modelIdent".

      Example:

       Having declared model objects using routines from module
       SysModBase as this

          DeclMObj  (s, "myModel.G", stateVar, G);
          DeclMObj  (s, "myModel.GDot", derivative, GDot);
          DeclMObj  (s, "myModel.c1", modParam, c1);
          DeclMObj  (s, "myModel.c2", modParam, c2);

       loading these data frames

          DATAFRAME myModelModObjects; MODEL = myModel;
          KEYCOLUMN = Ident; DATA:
          (*------------------------------------------------*)
          Ident Unit                   Descr                 ;
          (*------------------------------------------------*)
          G     'g dry weight/m^2'     'Grass'               ;
          GDot  'g dry weight/m^2/day' 'Grass derivative'    ;
          c1    '/day'                 'c1 (growth rate)'    ;
          c2    'm^2/g dw/day'         'c2 (self inhibition)';
          (*------------------------------------------------*)
          END myModelModObjects;


          DATAFRAME myModelStateVars; MODEL = myModel;
          KEYCOLUMN = Ident; DATA:
          (*-----------------------------------------------*)
          Ident DfltInit    MinInit    MaxInit              ;
          (*-----------------------------------------------*)
          G     1.0         0.0        10000.0              ;
          (*-----------------------------------------------*)
          END myModelStateVars;


          DATAFRAME myModelPars; MODEL = myModel;
          KEYCOLUMN = Ident; DATA:
          (*-----------------------------------------------*)
          Ident DfltVal    MinVal   MaxVal   RTC            ;
          (*-----------------------------------------------*)
          c1    0.7        0.0      10.0     TRUE           ;
          c2    0.0012345  0.0       1.0     TRUE           ;
          (*-----------------------------------------------*)
          END myModelPars;

       plus calling

          AssignModelsMObjData(s, "myModel");

       will lead to an assignment of all data contained in the
       data frames to the model objects G, GDot, c1, and c2.
    *)

  PROCEDURE DeassignModelsMObjData( s: System; modelIdent: ARRAY OF CHAR );
    (*
      Reverts the effect of AssignModelsMObjData and restores the
      values which were present just before the last call to
      a procedure which has assigned data.
    *)


  (*--------------------------------------*)
  (*=====   System's Model Objects   =====*)
  (*--------------------------------------*)

  PROCEDURE AssignSystemsMObjData  ( s: System );
  PROCEDURE DeassignSystemsMObjData( s: System );
    (*
      Work the same way as AssignModelsMObjData or
      DeassignModelsMObjData, respectively, but perform the
      operation on all models which belong to the system s.  There
      are two differences in behavior in comparison with
      AssignModelsMObjData: (i) If s is unknownSystem from
      SysModBase, s is considered to be not existing and the
      routine has no effect and will not affect any of the public
      model objects.  (ii) If the system is a parent system, the
      effect will be inherited to all the system's children!
    *)


  (*---------------------------------*)
  (*=====   All Model Objects   =====*)
  (*---------------------------------*)

  PROCEDURE AssignAllMObjData;
    (*
      Similar to AssignModelsMObjData but affects all currently
      existing model objecs of all models and systems, but only
      if they are public (see DataAccess from module
      SysModBase).
    *)
  PROCEDURE DeassignAllMObjData;
    (*
      Reverts the effect of AssignAllMObjData and restores the
      values which were present just before the last call to
      a procedure which has assigned data.
    *)


  (*****************************************************)
  (*#####              Checking data              #####*)
  (*****************************************************)

  PROCEDURE CheckMObjData       ( mObjQualIdent: ARRAY OF CHAR; VAR allOk: BOOLEAN );
  PROCEDURE CheckModelsMObjData ( modelIdent   : ARRAY OF CHAR; VAR allOk: BOOLEAN );
  PROCEDURE CheckSystemsMObjData( s            : System;        VAR allOk: BOOLEAN);	
  PROCEDURE CheckAllMObjData    (                               VAR allOk: BOOLEAN);
    (*
      Checks whether model objects of model "modelIdent", of
      system s (s may be any ancestor), or of all currently
      declared model objects, respectively, have a valid value,
      i.e.  whether (value <> DMConversions.UndefREAL()).  Issues
      a message of type Errors.Info for each found model object
      with a non-valid value.  Returns in allOk whether all model
      objects have valid values.  Note, you can anytime use
      SetDebugMode(TRUE) from module Errors or keyboard shortcut
      "Command^Shift^Capslock^D" to activate the debug mode.  In
      this mode, Errors.Halt messages which allow for calling the
      debugger, are called instead of Errors.Info.
    *)



  (*************************************************************)
  (*#####           Setting of monitoring data            #####*)
  (*************************************************************)


  CONST
    noMonitoring = 0;


  PROCEDURE AssignMObjMonitoring   ( mObjQualIdent: ARRAY OF CHAR; level: CARDINAL );
  PROCEDURE AssignModelsMonitoring ( modelIdent   : ARRAY OF CHAR; level: CARDINAL );
  PROCEDURE AssignSystemsMonitoring( s            : System;        level: CARDINAL);	
  PROCEDURE AssignAllMonitoring    (                               level: CARDINAL );
    (*

      Assigns the monitoring data stored in all currently available
      data frames (see also module DataFrames) to the matching model
      object (AssignMObjMonitoring), to all matching model objects
      of model "modelIdent" (AssignModelsMonitoring), to all model
      objects belonging to system s (s may be any ancestor), or to
      all matching model objects (AssignAllMonitoring),
      respectively.  A match is given if the same identifier is used
      for both the value definition in the data frame and the model
      object.  Note, in case of multiple value definitions
      encountered during loading of the data frames, the data
      finally assigned to the monitoring attributes of the matching
      model object are those found last in the reading sequence
      (overwriting principle).

      The data frame may contain monitoring data for any number
      of so-called monitoring levels.  In the range [1..12] you
      may define completely separate monitoring attributes, which
      allows to define up to 12 separate graphs, tables, and
      stash filing sets.  Beyond the highest monitoring level
      defined within the data frames, a higher monitoring level
      implies the lower levels, which still allows to define many
      graphs or tables of simulation data for any set of model
      objects with increasing complexity, i.e.  zooming in.
      level specifies on which level of monitoring monitoring
      attributes are actually to be assigned to the model
      objects.

      The assignment of following data are supported:

       DATAFRAME       Meaning and Examples
       ---------       -----------------------------------------
       ModIDMonit      Monitoring settings of model ModID: MonitLev,
                       ScaleMin, ScaleMax, Filing, Tabulation,
                       Graphing (noG, X, Y), Color (black, white,
                       red, green, blue, cyan, magenta, yellow,
                       auto), LineStyle (unbroken, broken,
                       dashSpotted, spotted, invisible, purge,
                       auto), PlotSym

                       ( see module SimBase for exact explanations
                       of the meaning of Line and PlotSym )

      Example:

       Having declared model objects using routines from module
       SysModBase as this

          DeclMObj  (s, "myModel.G", stateVar, G);
          DeclMObj  (s, "myModel.GDot", derivative, GDot);

       loading this data frame

        DATAFRAME myModelMonit; MODEL = myModel;
        KEYCOLUMN = Ident; DATA:
        (*-----------------------------------------------------------*)
        Ident MonitLev ScaleMin ScaleMax  Filing  Tabulation  Graphing;
        (*-----------------------------------------------------------*)
        G     1        0.0      1000.0    FALSE   TRUE        Y       ;
        GDot  1        0.0       500.0    FALSE   FALSE       noG     ;
        G     2        0.0      1000.0    FALSE   TRUE        X       ;
        GDot  2        0.0       500.0    FALSE   FALSE       Y       ;
        (*-----------------------------------------------------------*)
        END myModelMonit;

       plus calling

          AssignModelsMonitoring("myModel",1);

       will lead to the activation of a plot with G vs time t and

          AssignModelsMonitoring("myModel",2);

       will lead to the activation of a plot with GDot vs G.

       Note, calling

          AssignModelsMonitoring("myModel",0);

       will omit any listing of monitoring variables.  Monitoring
       levels can be controlled via keyboard shortcuts and a
       simple entry form if the Data Manager provided by the
       modules SimDatAux (can act only on 'ModelWorks' objects) or
       SysDatAux (can act on all models and model objects,
       'ModelWorks' installed as well as SysModBase declared ones)
       is activated.

      Optionally the data frame myModelMonit can be extended to
      define curve attributes.

      Example:

        DATAFRAME myModelMonit; MODEL = myModel;
        KEYCOLUMN = Ident; DATA:
        (*-------------------------------------------------------*)
        Ident MonitLev Color     LineStyle   PlotSym   Graphing   ;
        (*-------------------------------------------------------*)
        G     1        green     unbroken    'v'       Y          ;
        GDot  1        auto        auto      ''        noG        ;
        G     2        auto        auto      ''        X          ;
        GDot  2        red       spotted     ''        Y          ;
        (*-------------------------------------------------------*)
        END myModelMonit;

      Note, when saving data frames from current data within the
      simulation environment, in case all monitoring variables
      are of LineStyle autoDefStyle only, no columns Color, Line,
      and PlotSym will be output, since they are redundant.  For any
      model object to be monitored and the attributes Color, Line, or
      PlotSym are missing (not in data frame or given as auto), the
      model object's curve attributes will be treates as autoDefStyle.

    *)


  PROCEDURE DeassignMObjMonitoring   ( mObjQualIdent: ARRAY OF CHAR );
  PROCEDURE DeassignModelsMonitoring ( modelIdent   : ARRAY OF CHAR );
  PROCEDURE DeassignSystemsMonitoring( s            : System        );	
  PROCEDURE DeassignAllMonitoring;
    (*
      Reverts the effect of AssignMObjMonitoring,
      AssignModelsMonitoring, or AssignAllMonitoring,
      respectively, and restores the values which were present
      just before the last call to a procedure from this module
      which has assigned data.  Otherwise the same rules apply as
      described for the corrsponding assigning routines such as
      AssignMObjMonitoring.
    *)


  PROCEDURE CheckMObjMonitoring   ( mObjQualIdent: ARRAY OF CHAR; VAR allOk: BOOLEAN );
  PROCEDURE CheckModelsMonitoring ( modelIdent   : ARRAY OF CHAR; VAR allOk: BOOLEAN );
  PROCEDURE CheckSystemsMonitoring( s            : System;        VAR allOk: BOOLEAN );
  PROCEDURE CheckAllMonitoring    (                               VAR allOk: BOOLEAN );
    (*
      Checks whether monitoring attributes of all monitored
      objects of an individual model object, of all model objects
      of a model, of all model objects of a system (s may be any
      ancestor), or of all currently declared model objects,
      respectively, are set to valid values (ScaleMin, ScaleMax <>
      DMConversions.UndefREAL() AND (ScaleMin < ScaleMax)).
      Issues a message of type Errors.Info for each found
      non-valid attribute.  Returns in allOk whether monitoring
      attributes of all monitored model objects have valid values.
      Note, you can anytime use SetDebugMode(TRUE) from module
      Errors or keyboard shortcut "Command^Shift^Capslock^D" to
      activate the debug mode.  In this mode, Errors.Halt messages
      which allow for calling the debugger, are called instead of
      Errors.Info.
    *)




  (****************************************************************)
  (*#####       Setting of multi-run tally computations      #####*)
  (****************************************************************)


  CONST
    noTallying = 0;


  PROCEDURE AssignMObjTallying   ( mObjQualIdent: ARRAY OF CHAR; level: CARDINAL);
  PROCEDURE AssignModelsTallying ( modelIdent   : ARRAY OF CHAR; level: CARDINAL);
  PROCEDURE AssignSystemsTallying( s            : System;        level: CARDINAL);	
  PROCEDURE AssignAllTallying    (                               level: CARDINAL);
    (*

      Assigns the tallying data stored in all currently available
      data frames (see also module DataFrames) to the matching model
      object (AssignMObjTallying), to all matching model objects of
      model "modelIdent" (AssignModelsTallying), to all matching
      model objects of system "s" (s may be any ancestor), or to all
      matching model objects of all models (AssignAllTallying),
      respectively.  A match is given if the same identifier is used
      for both the value definition in the data frame and the model
      object.  Note, in case of multiple value definitions
      encountered during loading of the data frames, the data
      finally assigned to the tallying attributes of the matching
      model object are those found last in the reading sequence
      (overwriting principle).

      AssignMObjTallying, AssignModelsTallying,
      AssignSystemsTallying, and AssignAllTallying work similar to
      AssignMObjMonitoring, AssignModelsMonitoring,
      AssignSystemsMonitoring, and AssignAllMonitoring, but operate
      on multiple run statistics collected for particular model
      objects and are of course only of use for stochastic models.
      If level >= that as specified in the data frame for a
      particular model object, tallying is performed, otherwise not.

      The assignment of following data are supported:

       DATAFRAME       Meaning and Examples
       ---------       -----------------------------------------
       myModelTallying Tallying settings of model ModID: TallyLev,
                       StatFuncs, HTally, DeclAV, FileTally, ListTally,
                       PlotTally (noG, Y, ErrBars)

      Example:

       Having declared model objects using routines from module
       SysModBase as this

          DeclMObj  (s, "myModel.G", stateVar, G);
          DeclMObj  (s, "myModel.GDot", derivative, GDot);

       loading this data frame

       DATAFRAME myModelTallying; MODEL = myModel;
       KEYCOLUMN = Ident; DATA:
       (*-------------------------------------------------------------------------*)
       Ident TallyLev StatFuncs         HTally DeclAV FileTally ListTally PlotTally;
       (*-------------------------------------------------------------------------*)
       G     1        "Mean, MyStat"    200    TRUE   TRUE      FALSE      ErrBars ;
       GDot  2        "Histo(-1,+1,20)"  10    FALSE  TRUE      FALSE      noG     ;
       (*-------------------------------------------------------------------------*)
       END myModelTallying;

       plus calling

          AssignModelsTallying("myModel",1);

       will lead to the collection of tally statistics for state
       variable G in multiple run experiments.  Every 200th run
       the mean and a custom statistical function MyStat of every
       realized run will be computed at every monitoring point
       along time for the state variable G.
             Since DeclAV is TRUE, the results will be stored in
       automatically declared auxiliary variables with identifier
       G_Mean and G_MyStat (see below for a complete list of
       predefined suffixes for commonly used statistical
       functions).  These auxiliary variables will belong to the
       system and model (see module SysModBase) which owns G,
       i.e.  myModel.  The DataAccess attributes will also be
       inherited from G.
             Result output of tallies works differently from
       continuous monitoring as offered by ordinary monitoring
       attributes (see above routine AssignModelsMonitoring).  Tally
       output is done after several runs have been computed (with
       or without ordinary monitoring) and is always based on
       some multiple run statistics, such as a mean computed at a
       particular point in time across several runs.  Tally
       output is always done only after a particular run has been
       terminated, i.e.  after hTally runs have been completed.
       This means, hTally is the sample size of the computed
       tally statistics).
             In above example, FileTally is TRUE; therefore, G_Mean
       and G_MyStat will also be written onto a file every 200th
       run.  Moreover, G_Mean and G_MyStat will be displayed in
       the Graph window at the end of every 200th run, featuring
       error bars as computed by the statistical functions
       MeanLL, MeanUL, MyStatLL, and MyStatUL (the suffixes: LL -
       Lower Limit, UL - Upper Limit are automatically added to the
       identifier of the statistical function).
             Note, in general statistical functions listed in
       colum 'StatFuncs' are recognized by their identifiers.
       Some are predefined (see below) and some may have been
       installed by the callee using function installing routines
       from module FormulIntrpr (e.g. by using InstallMonadicFunc,
       or InstallTriadicFunc).  For example the callee would have
       to install statistical function 'MyStat' via routine
       InstallDiadicFunc before calling AssignModelsTallying for model
       'myModel'.

       On the other hand

          AssignModelsTallying("myModel",2);

       will lead to the collection of tally statistics for state
       variable G plus GDot in multiple run experiments.  Every
       10th run histogram data will be computed for 22 classes
       (1st class: all values < -1, 20 classes (buckets) in range
       [-1..+1], last class: all values > +1).  No auxiliary
       variables will be declared, since DeclAV is FALSE.  Every
       10th run the histogram data will be written onto a file,
       which would be typically opened by graphics/statistical
       application which can draw histograms (e.g. see also
       module Histograms).

       If DeclAV is TRUE the computed statistics will be also
       stored in auxiliary variables which are automatically
       declared.  The identifier of the statistical function will
       be added as a suffix to the identifier of the original
       model object.  The additionaly declared auxiliary
       variables are owned by the same system and model which
       owns the original model object (see module SysModBase).
       The DataAccess attributes (see module SysModBase) are
       inherited as well.

       Ex.: Requesting calculation of means for state variable
       'G' will store means in an auxiliary variable with
       identifier 'myModel.G_Mean'.  This variable is of course
       accessible for any operation wich operates on an auxiliary
       variable (see module SysModBase and this module)

       The following statistical functions are predefined

          Meaning              Identifier   Arguments (#, idents)
          -------              ----------   --------------------
          mean                 Mean          0, uses N, Sum
          standard deviation   StDev         0, uses N, Sum, SumSqr
          count                N             0
          sum                  Sum           0
          sum of squares       SumSqr        0
          confidence interval  CIL           1 - alfa, uses N, StDev
          lower limit
          confidence interval  CIU           1 - alfa, uses N, StDev
          upper limit

    *)

  PROCEDURE SetMObjsTallyData( mObjQualIdent : ARRAY OF CHAR;
                               statFuncs     : ARRAY OF CHAR;
                               hTally        : INTEGER);
   (*
      Works similar to AssignMObjTallying but data are not taken
      from data frames but are passed as actual arguments.

      Example:

      Having declared model objects using routines from module
      SysModBase as this

         DeclMObj  (s, "myModel.G", stateVar, G);
         DeclMObj  (s, "myModel.GDot", derivative, GDot);

      plus calling

        SetMObjsTallyData("myModel.G", "Mean", 200);

      will lead to the computation of means for state variable G
      after every 200th run.  FileTally is assumed to be true but
      all other tallying attributes, in particular DeclAV, are
      assumed to be FALSE.  Of course AssignModelsTallying could anytime
      overrule any of these settings.

    *)

  PROCEDURE GetMObjsTallyData( mObjQualIdent : ARRAY OF CHAR;
                               VAR statFuncs : ARRAY OF CHAR;
                               VAR hTally    : INTEGER);
    (*
      Allows to learn about the current core data of a tally
      for model object denoted by identifier mObjQualIdent.
    *)


  PROCEDURE DeassignMObjTallying   ( mObjQualIdent: ARRAY OF CHAR );
  PROCEDURE DeassignModelsTallying ( modelIdent   : ARRAY OF CHAR );
  PROCEDURE DeassignSystemsTallying( s            : System        );	
  PROCEDURE DeassignAllTallying;
    (*
      Reverts the effect of AssignMObjTallying,
      AssignModelsTallying, AssignSystemsTallying, or
      AssignAllTallying, respectively, and restores the values
      which were present just before the last call to a procedure
      which has assigned data.
    *)


  PROCEDURE CheckMObjTallying   ( mObjQualIdent: ARRAY OF CHAR; VAR allOk: BOOLEAN );
  PROCEDURE CheckModelsTallying ( modelIdent   : ARRAY OF CHAR; VAR allOk: BOOLEAN );
  PROCEDURE CheckSystemsTallying( s            : System;        VAR allOk: BOOLEAN );
  PROCEDURE CheckAllTallying    (                               VAR allOk: BOOLEAN );
    (*
      Checks whether tallying attributes of all model objects of
      an individual model, or of the system s (s may be any
      ancestor), or of all currently declared models,
      respectively, are all valid values (all statistical
      functions plus hTally defined).  Issues a message of type
      Errors.Info for each found non-valid attribute.  Returns in
      allOk whether monitoring attributes of all monitored model
      objects have valid values.  Note, you can anytime use
      SetDebugMode(TRUE) from module Errors or keyboard shortcut
      "Command^Shift^Capslock^D" to activate the debug mode.  In
      this mode, Errors.Halt messages which allow for calling the
      debugger, are called instead of Errors.Info.
    *)


END SysDatAccess.

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