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