|
|
|
|
||
|
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.
|
||
|
|
|