DEFINITION MODULE SimDatAux;
(*******************************************************************
Module SimDatAux (SD_Version_2.0)
Copyright (c) 1997-2006 by Andreas Fischlin and ETH Zurich.
Purpose Support the use of models and their
needed data as provided by data frames.
Remarks The core routine is AssignDatFraData, which
assigns data from all data frames currently stored
in memory to all models and model objects via
identifier match.
Provides menu commands which can be installed
with a single command or can be used for
installation in any other context of all major
functions provided by this module. This module
provides operations to make the link between data
frames and models plus model objects declared via
SimBase from ModelWorks.
See also modules SimBase (from ModelWorks),
SimDatAccess, DataFrames, and DatFraViewer. This
module does not let you look at the data frames,
which remain hidden in memory at all times.
However, module DatFraViewer lets you view,
inspect, and even manage data frames.
Uses SimDatAccess, SimDatDump, and DataFrames plus
ModelWorks and the "Dialog Machine".
Programming
o Design
Andreas Fischlin 17/09/1997
o Implementation
Andreas Fischlin 17/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: 25/05/1998 AF
*******************************************************************)
FROM DMMenus IMPORT Menu;
FROM DMLanguage IMPORT userBase;
(* Error constants: simDatAuxErrOffset = DMLanguage.userBase + 380 .. 390-1 *)
(******************************************)
(* Model Data Base menu and menu commands *)
(******************************************)
PROCEDURE InstallSDAMenuCmds (title: ARRAY OF CHAR);
(*
Installs a menu with the title 'title' plus the basic
model data base management commands (see routines below).
Typical usage: InstallSDAMenuCmds(''). In case 'title'
is the empty string, a default menu title will be
provided.
*)
PROCEDURE RemoveSDAMenuCmds;
(*
Reverts the effect of InstallSDAMenuCmds by removing the
current model base menu (plus any possibly client installed
commands as well!).
*)
(*---------------*)
(* Customization *)
(*---------------*)
PROCEDURE SimDatAuxMenu(): Menu;
(*
Returns the model data base's menu in order to customize
the menu by installing additional commands in it, e.g. by
using routines from DMMenus.
*)
PROCEDURE SetSDAPreferences( clearAtDeassignMode : BOOLEAN;
showIDsAlways : BOOLEAN;
reportOnCheckFail : BOOLEAN;
packageErrMode : INTEGER;
globLikePkgErrMode : BOOLEAN);
PROCEDURE GetSDAPreferences(VAR clearAtDeassignMode : BOOLEAN;
VAR showIDsAlways : BOOLEAN;
VAR reportOnCheckFail : BOOLEAN;
VAR packageErrMode : INTEGER;
VAR globLikePkgErrMode : BOOLEAN);
(*
Lets you control the current preferences. The values
will be remembered and stored as part of the permanent
preferences. Meaning:
clearAtDeassignMode A call to routine DeassignData clears
all assignments instead of restoring
the last present before last call to
AssignDatFraData
showIDsAlways Identifiers are shown of model objects
even if they have been fully cleared
reportOnCheckFail After an assignment of data using
core procedure AssignDatFraData
from this module a dialog will
report in case any model objects
have still invalid data. This
warns the user about possible
failures of subsequent simulations.
*)
CONST
suppressAllErrMode = 0; (* values used for packageErrMode *)
warnOnceErrMode = 1;
immediateErrMode = 2;
debugErrMode = 3;
(*
Routines GetSDAPreferences and SetSDAPreferences recognize
these values for preference packageErrMode
packageErrMode meaning
-------------- -------
suppressAllErrMode Never show any error messages, i.e.
SuppressMsgDisplay from Errors is
called. Investigation of error presence
and possible display of them is
completely the callees responsibility.
Use module Errors to check for error
occurrence and display of possibly
accumulated errors.
warnOnceErrMode Inform about single or warn and ask for
inspection if many errors (default mode).
immediateErrMode No suppression of error displays at all
and all errors are shown immediately, i.e.
SuppressMsgDisplay from Errors is not called
like in above modes.
debugErrMode Similar to above but offers the advantage
that Errors.Info messages are displayed
as Errors.Halt messages and may display
additional, internal debugging messages
(calls Errors.SetDebugMode(TRUE)).
Note, if you call SetSDAPreferences and change packageErrMode,
this may trigger the display of errors if the mode changes to a
less quiet one. You can use this effect for instance to
acchieve temporarily a completely quiet mode
(suppressAllErrMode) and then call SetSDAPreferences to change
to warnOnceErrMode to learn about the possible presence of some
errors encountered in the past.
IMPLEMENTATION RESTRICTION: Note changing packageErrMode
values by calling SetSDAPreferences affects the error
mode of the packages ModelWorks Data extension (SimData, menu
"Data") and ISIS throughout.
globLikePkgErrMode This flags lets you control the
behavior of error handling for
the category of global errors identical
to that as defined by packageErrMode.
Note, any errors not falling within the
range DMLanguage.userBase + 300
and + 450, i.e. [600..750]) are not
affected by packageErrMode. All errors
as defined by modules DMLanguage (or
Errors) are predefined global errors
and may also be raised by any operation
of the SimData package, e.g. file opening
or memory shortage errors etc.
*)
PROCEDURE GetSDAMenuAliasChars ( VAR loadDatAlCh, loadDatFromAlCh,
sdfAlCh, sasdfAlCh,
assgnDatAlCh, deassignDatAlCh,
assgnGloSiPsAlCh, chMLevAlCh, chTLevAlCh,
placeWinsAlCh, chkErrAlCh,
editPrefsAlCh, editAlChsAlCh: CHAR);
PROCEDURE SetSDAMenuAliasChars ( loadDatAlCh, loadDatFromAlCh,
sdfAlCh, sasdfAlCh,
assgnDatAlCh, deassignDatAlCh,
assgnGloSiPsAlCh, chMLevAlCh, chTLevAlCh,
placeWinsAlCh, chkErrAlCh,
editPrefsAlCh, editAlChsAlCh: CHAR);
(*
Above two procedures lets you control the keyboard short
cuts used by the model data base menu commands.
GetSDAMenuAliasChars is typically used if you wish to modify
only a few of the keyboard shortcuts in a
GetSDAMenuAliasChars(loadDatAlCh,... ;
SetSDAMenuAliasChars(loadDatAlCh,...
sequence. The values will be remembered and stored as part
of the permanent preferences. The characters are used as
alias characters for the commands (see below) as follows:
loadDatAlCh - LoadDFFromFileIntoMem
loadDatFromAlCh - LoadDFFromOtherFileIntoMem
sdfAlCh - SaveDF
sasdfAlCh - SaveAsDF
assgnDatAlCh - AssignDatFraData
deassignDatAlCh - DeassignData
assgnGloSiPsAlCh - AssignGlobSimPars
chMLevAlCh - AssignModelsMonitoringForLevel
chTLevAlCh - AssignModelsTallyingForLevel
placeWinsAlCh - PlaceSimEnvsWindows
chkErrAlCh - CheckForErrPresence
editPrefsAlCh - (not available, but see SetSDAPreferences)
editAlChsAlCh - (not available, but see SetSDAMenuAliasChars)
*)
PROCEDURE ResetSDAToPresettings;
(*****************************)
(* Model Data Base Functions *)
(*****************************)
(* each function is available as a command in the default menu *)
PROCEDURE LoadDFFromFileIntoMem;
(*
Starting from the current anchor file, routine
LoadDFFromFileIntoMem scans the file's (and possibly
therein referenced other files') content and loads all the
data found into memory (for details see module DataFrames).
Note, no filtering takes place and all data frames and file
references are recognized during this reading and loading
process. If the user has never selected an anchor file,
this routine behaves like LoadDFFromOtherFileIntoMem
(called with empty string parameters). After successful
completion data are kept in memory and are ready to be
used, e.g. to be assigned to models and model objects.
Use AssignDatFraData to actually assign the data to the
currently known model and model objects. Loading can also
be repeated and the result will be a merging and
accumulation of all data encountered during any previous
loading process. However, if the same data are
encountered, especially if the data frame identifier is
identical, the previously stored data are discarded and
replaced with the latest read, supporting a convenient
updating.
NOTE: As an alternative you may also use module
DatFraViewer to load data frames into memory. The latter
module offers the advantage to allow for inspection of the
data currently stored in memory, plus many more functions,
such as unloading and versatile filtering during the
loading process etc. Note, it does not matter by which
method data were actually loaded into memory; the data are
always accessible via the retrieval methods offered by
module DataFrames.
*)
PROCEDURE LoadDFFromOtherFileIntoMem(path,filename: ARRAY OF CHAR);
(*
Like LoadDFFromFileIntoMem but operates on the anchor
file denoted by path and filename. In case path and
filename are the empty string, this routine offers the
standard file opening dialog to interactively select an
anchor file for reading.
*)
(********************************************)
(*##### Assigning/Deassigning Data #####*)
(********************************************)
PROCEDURE AssignDatFraData;
(*
Assigns all data presently stored in memory in form of so
called data frames (see module DataFrames) to the
currently known models and model objects. Use
DeassignData to revert the effect of this
routine.
Such an assignment is only possible if the identifier of a
particular model object and its owning model match the
identifier given by the data value definition (see module
DataFrames for details). For instance the following data given
according to the data frame syntax (for EBNF see module
DataFrames):
(*============================================================*)
(* Model Parameters *)
(*============================================================*)
DATAFRAME Parameters; REMARK = 'For any logistic growth model' ;
MODEL = ANY; KEYCOLUMN = Ident; DATA:
(*============================================================*)
Ident Descr DfltVal MinVal MaxVal Unit RTC ;
(*------------------------------------------------------------*)
r 'Relative growth rate' 0.7 0.0 10.0 'd^-1' TRUE ;
K 'Carrying capacity' 700.0 0.0 1.0E+38 'g/m^2' FALSE ;
(*------------------------------------------------------------*)
END Parameters;
(*============================================================*)
will match model objects of the logistic growth model equation,
given they have been declared in the model definition program
with matching identifiers like this:
VAR
m : Model;
grass : StateVar;
grassDot : Derivative;
r, K : Parameter;
DeclP(r, 0.7, 0.0, 10.0, rtc,
"r (growth rate of grass)", "r", "/day");
DeclP(K, 700.0, 0.0, 10000.0, rtc,
"K (carrying capacity)", "K", "g dry weight/m^2");
Routine DeclP is available from module SimBase. Above
data frame Parameters can be assigned to any model (see
phrase MODEL = ANY) as long as the identifiers listed in
the key column headed with the identifier 'Ident' (see
phrase KEYCOLUMN = Ident) match those specified in DeclP.
E.g. the DfltVal 0.7 tabulated for Ident = r is assigned
to the variable r (type Parameter). With the phrase MODEL
= LogGrowth it would be possible to have a more specific
match, i.e. 'LogGrowth.r'. The success of AssignDatFraData
requires the model has been declared as follows:
DeclM(m, Euler, NoInitialize, NoInput, NoOutput, Dynamic,
NoTerminate, ModelObjects, "Logistic grass growth model",
"LogGrowth", NoAbout);
Routine DeclM is available from module SimBase. To
numerically solve the logistic equation use the parameters
r and K in this procedure as follows:
PROCEDURE Dynamic;
BEGIN
grassDot:= r*((K-grass)/K)*grass;
END Dynamic;
Data frames can be formatted freely, as long as they observe
the syntax (see module DataFrames). In addition
AssignDatFraData requires that column headers use reserved
identifiers. These are:
Reserved identifier State Model Monitoring
Variables Parameters attributes
------------------- --------- ---------- ----------
S Ident yes yes yes
S Descr yes yes yes
S Unit yes yes -
R DfltInit yes - -
R MinInit yes - -
R DfltVal - yes -
R MinVal - yes -
R MaxVal - yes -
B RTC - yes -
R ScaleMin - - yes
R ScaleMax - - yes
B Filing - - yes
B Tabulation - - yes
I Graphing * - - yes
where S = Identifier or string, R = real, I = integer number, B =
boolean. * denotes monitoring level
*)
PROCEDURE DeassignData;
(*
Discards all data possibly assigned by
AssignDatFraData and assigns to all model objects an
undefined value. Note: This routine has no effect if
executed in the ModelWorks state simulating or sub-state
running (see module SimMaster) respectively to avoid a
crash during simulation because you typically assign
undefREAL (from module DMConversions) to model objects
which are used in calculations. Instead a sound is
generated to inform the simulationist about the refused
operation.
*)
PROCEDURE AssignGlobSimPars;
(*
Assigns all data presently stored in memory in form of so
called data frames (see module DataFrames) to the global
simulation parameters. Use DeassignData to revert the
effect of this routine. Such an assignment is only
possible if the identifier of a particular global
simulation parameter matches the identifier given by the
data value definition (see module DataFrames and routine
AssignGlobalSimulationData from module SysDatAccess for
details).
*)
PROCEDURE AssignModelsMonitoringForLevel;
(*
Offers an entry form which let's the user define a level
on which the monitoring attributes are to be assigned to
the currently present model objects. If the dialog is
answered with OK all monitoring attributes of the entered
level such as curves, scales, or colors, are assigned
accordingly. The monitoring level is an integer as
tabulated in a column with reserved heading 'MonitLev'.
Any variable whose monitoring level is equal the current
monitoring level will be in display, any other will
remain invisible. At monitoring level 0 all monitoring
variables are discarded and there is normally no
monitoring done. Beyond an upper limit the same settings
from the last level are used at all times. This
mechanism allows for easy activation or deactivation,
respectively, of many monitoring variables with a single
command. There are even keyboard short cuts available to
alter the current monitoring level without this dialog.
IMPORTANT NOTE: Each time the monitoring level is changed
there happens actually a full assignment (calls
AssignAllMonitoring from module SimDatAccess), i.e. any
graphs, tables, graphing settings etc. present previously
to the switch of the level will be discarded and
overwritten. Thus, always save the current state to the a
data frame if you wish to preserve at least the monitoring
settings before changing to another level. Moreover, from
this principle follows, if you wish to preserve the
monitoring settings from several levels, make sure you
always save AND load (!) the to and from the data frame
before switching the monitoring level. Otherwise you loose
your precious editing since the saving does only write
newly edited monitoring attributes to the data frame for
the current monitoring level; for all other monitoring
levels it uses only the values currently stored in memory
from the last load of the data frame. IMPLEMENTATION
RESTRICTION: Only a maximum of 7 monitoring levels are
fully remembered.
*)
PROCEDURE AssignModelsTallyingForLevel;
(*
Similar to AssignModelsMonitoringForLevel. Offers an entry
form which lets the simulationist edit the tallying level
and cause an assignment of the tallying attributes to the
present model objects. For any model object with a
TallyLev equal to the current tallying level tally
statistics will be computed and output made according to
the current tallying specifications, typically provided
by means of data frames. Implies a data assignment as
provided by the routine AssignAllTallying from module
SimDatAccess.
*)
PROCEDURE PlaceSimEnvsWindows;
(*
Places all windows according to the frame definitions as
specified in the data frame with name "Windows". In case
the data frame has not been loaded into memory, procedure
does nothing. (Note, that the RAMSES shell may
automatically call this procedure when entering the
Simulation Session in case the sessions preferences are
set such that the data frame utils are automatically
activated!)
*)
(***********************************************************)
(*##### Storing Current Data on a Data Frame File #####*)
(***********************************************************)
PROCEDURE SaveDF;
(*
Saves the data of all currently available models and
model objects as data frames in the current anchor file.
Separate data frames are created for each class of model
objects, i.e. one for variables, for parameters, and for
monitoring attributes, again on a per model basis. Note,
all these data frames are written into the same file,
regardless of the number of files the data may have come
from when they were originally loaded. Upon first time
call to SaveDF, the standard file creating dialog is
offered, which lets the user choose the file on which to
save the data. Subsequent calls will write to the same
file unless SaveAsDF is called. IMPORTANT NOTE: During
the first call to this routine after having loaded
freshly data, the user is asked whether the original data
may actually be overwritten. However, subsequent calls
quietly overwrite the file without any warning!!!
*)
PROCEDURE SaveAsDF;
(*
Similar to SaveDF but offers always a file creating
dialog.
*)
(********************************)
(*##### Error Handling #####*)
(********************************)
PROCEDURE CheckForErrPresence;
(*
Checks for the presence of errors which might have been
encountered during past operations. In case
packageErrMode = suppressAllErrMode OR packageErrMode =
warnOnceErrMode possibly occurring errors are not
displayed but kept in memory for display till you call
this procedure.
*)
END SimDatAux.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib