DEFINITION MODULE SimBase;
(*******************************************************************
Module SimBase (MW_V3.0)
Copyright (c) 1986-2006 by Markus Ulrich, Andreas Fischlin, Dimitrios
Gyalistras, Olivier Roth and ETH Zurich.
Purpose Run time library containing basic objects for the
declaration of models, state variables, model parameters,
and monitorable variables. Furthermore there
are procedures which may be used by the modeller
to set or get defaults, current values and to control
simulations in various ways.
Remarks This module is part of the mandatory client interface of
'ModelWorks', an interactive Modula-2 modelling and
simulation environment.
Programming
o Design
Markus Ulrich 20/08/1986
Andreas Fischlin 02/05/1987
o Implementation
Markus Ulrich 20/08/1986
Andreas Fischlin 02/05/1987
Dimitrios Gyalistras 13/06/1989
Olivier Roth 23/06/1989
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: 24/09/1997 AF
*******************************************************************)
FROM SYSTEM IMPORT ADDRESS;
(*********************************************************)
(*##### Declaration of models and model objects #####*)
(*********************************************************)
(*---------------------------------*)
(*===== Model declaration =====*)
(*---------------------------------*)
TYPE
Model; (* variables of this type are used to reference models *)
(* Model objects, always belonging to a model *)
StateVar = REAL;
Derivative = REAL;
NewState = REAL;
Parameter = REAL;
AuxVar = REAL;
InVar = REAL;
OutVar = REAL;
IntegrationMethod = (Euler, Heun, RungeKutta4,
RungeKutta45Var, stiff,
discreteTime, discreteEvent);
VAR
notDeclaredModel: Model; (* read only variable, e.g. use it for initializations *)
PROCEDURE DeclM(VAR m: Model; defaultMethod: IntegrationMethod;
initialize, input, output, dynamic, terminate: PROC;
declModelObjects: PROC;
descriptor, identifier: ARRAY OF CHAR; about: PROC);
(*
Model declaration ("Declare model"):
m variable, to be declared in client module(s), used for
further references to the (sub)model.
defaultMethod:
Default integration method of (sub)model m
2 cases have to be distinguished:
- discrete: discrete time model (system of ordinary
difference equations)
IMPORTANT NOTE: this method can NOT be
changed! The default and the current
method will always be the same.
- continuous method (e.g. Heun): continuous time
numerical integration method for solving
ordinary differential equations is being
installed; This method is associated with
(sub)model m (any model may have
a different method), and is stored for
reinstallation for resetting after
eventual interactive selection of a
different method. Note: the size of
the integration step is the same for
all (sub)models, except for the discrete
time (sub)models, which may have individual
time steps.
The default integration method is
(re)assigned to the current integration
method by ModelWorks during the
initialization phase of the simulation
session or after every reset of the
integration methods. During a simulation
session the current integration method may
be changed by the simulationist (using an
IO-window) or by the modeller via the
procedure SetM.
initialize
For any initializations before a simulation run. It is
only called once at the begin of a simulation run.
input
Calculates the input variables of (sub)model m. It is
only called once during a time (integration) step.
output
Calculates the output variables of (sub)model m. It is
only called once during a time (integration) step.
Implementation restriction: Output variables must not
depend directly on input variables.
dynamic
Contains equations of (sub)model m.
- continuous time: calculates the new derivatives from
the current values of the state variables. Depending
on the order of the integration method, this procedure
is called at least once up to several times during
one time (integration) step.
- discrete time: calculates new values of the state
variables. It is only called once during a time
step (also called integration step).
terminate
For any termination actions to be performed just
before leaving a simulation run. It is only called
once at the end of a simulation run.
installModelObjects
Procedure declaring all model objects, i.e. state
variables, model parameters, and monitorable variables
of (sub)model m. Implementation restriction:
Declarations of (sub)models within this procedure are
not allowed.
descriptor
String containing a long description of (sub)model m
identifier
Short string identifying (sub)model m
about
Procedure writing additional information about the
(sub)model, e.g. by using routines from the "Dialog
Machine" module DMWindIO, into a special help window.
*)
PROCEDURE CurCalcM(): Model;
(*
Returns model of which the initialize, input, output, or
dynamic etc. procedure is currently calculated. The value
notDeclaredModel is returned if (SimMaster.MWState <>
simulating) or (SimMaster.MWSubState <> running).
*)
PROCEDURE CurAboutM(): Model;
(*
Returns model of which the about procedure is currently
executed. The value notDeclaredModel is returned if this
procedure is called outside 'about'.
*)
(*
The following empty body procedures allow to declare a model
with minimum effort, i.e. use any of these procedures as actual
parameters when calling DeclM if for instance only Dynamic is
to be used for the model definition
*)
PROCEDURE NoInitialize;
PROCEDURE NoInput;
PROCEDURE NoOutput;
PROCEDURE NoDynamic;
PROCEDURE NoTerminate;
PROCEDURE NoModelObjects;
PROCEDURE NoAbout;
PROCEDURE DoNothing;
(*------------------------------------------*)
(*===== State variable declaration =====*)
(*------------------------------------------*)
PROCEDURE DeclSV(VAR s: StateVar; VAR ds: Derivative (* or NewState*);
defaultInitial, minCurInit, maxCurInit: REAL;
descriptor, identifier, unit: ARRAY OF CHAR);
(*
State variable declaration ("Declare as state variable"):
s
Variable to be declared as state variable. "DeclSV" does assign
to "s" the value "defaultInitial".
ds
Variable to be declared as the derivative (for continuous
time simulation / type Derivative) or the new value (for
discrete time simulation / type NewState) of "s". The
derivative or the new value must be written into this
variable by the procedure "dynamic" (see procedure DeclM),
which is called during the numerical integration by
ModelWorks' run time system. Consider ds as
"dummy"-variable, which may appear only on the left side of
the dynamic equations in procedure "dynamic". Warning:
Any further use may lead to unpredictable results.
"DeclSV" assigns to "ds" the value 0.0.
defaultInitial
Default initial value for state variable "s".
ModelWorks uses the current initial value at the beginning
of each simlation run to initialize "s". The default
initial value is (re)assigned to the current initial value
by ModelWorks during the initialization phase of the
simulation session or after every reset of the state
variables. During a simulation session the current initial
value may be changed by the simulationist (using an
IO-window) or by the modeller via the procedure SetSV.
The modeller could also overwrite the value of s with
another value within procedure Initial (see procedure
DeclM), since ModelWorks has already assigned the
current initial value to the state variable s. Note
however, that in the latter case inconsistencies might
occur between the display of the current value in the
IO-window with the current values actually used in the
simulations. Avoid this method.
minCurInit, maxCurInit
Lower and upper bounds for the current initial value.
Attempts by the simulationist to assign values out of this
range are not accepted.
descriptor
String containing a long description of the state variable s.
This string may be truncated when it is displayed during a
simulation session (see also identifier).
identifier
Short string identifying the state variable s. This
abbreviated description should be kept as small as possible
in order to ensure full visibility for the displays during
a simulation session.
unit
String containing the unit used for the state variable s.
This string is used for displays during a simulation
session. Example: "kcal/m2/day".
*)
(*-------------------------------------------*)
(*===== Model parameter declaration =====*)
(*-------------------------------------------*)
TYPE
RTCType = (rtc, noRtc);
PROCEDURE DeclP(VAR p: Parameter; defaultVal, minCurVal, maxCurVal: REAL;
runTimeChange: RTCType;
descriptor, identifier, unit: ARRAY OF CHAR);
(*
Model parameter declaration "Declare as parameter":
p
Variable to be declared as model parameter. "DeclP" assigns
to "p" the value of "default". If the value of "p" should
be out of range [minCurVal, maxCurVal], a warning message will be
produced.
defaultVal
Default value for the model parameter "p".
The default value is (re)assigned to the current parameter
value p by ModelWorks during the initialization phase of
the simulation session or after every reset of the model
parameters. During a simulation session the current
parameter value p may be changed by the simulationist
(using an IO-window) or by the modeller via overwriting the
value of p with another value, e.g. within procedure
Initial (see also procedure DeclM).
minCurVal, maxCurVal
Lower and upper value bounds for "p".
Attempts by the simulationist to assign values out of this
range are not accepted.
runTimeChange
"rtc" (=run time change) changing of values of model parameter
"p" during a simulation run in the program state "Pause"
is enabled.
"noRtc" (=no run time change) disallows completely any changing
of values of the model parameter "p" during a
simulation run, even in the program state
"Pause".
descriptor/identifier
Strings containing a long and a short description (identifier) of
the model parameter p.
unit
Unit of model parameter p.
*)
(*------------------------------------------------*)
(*===== Monitorable variable declaration =====*)
(*------------------------------------------------*)
TYPE
StashFiling = (writeOnFile, notOnFile);
(*
controls stashing away (writing) of simulation results on the
stash file (a text file) for future reference.
*)
Tabulation = (writeInTable, notInTable);
(* controls tabulation of simulation results in the table window *)
Graphing = (isX, isY, isZ, notInGraph);
(* Kind of graphical monitoring of simulation results in the graph *)
PROCEDURE DeclMV(VAR mv: REAL; defaultScaleMin, defaultScaleMax: REAL;
descriptor, identifier, unit: ARRAY OF CHAR;
defaultSf: StashFiling; defaultT: Tabulation; defaultG: Graphing);
(*
Declaration of monitorable variable "Declare as monitorable
variable":
mv
The variable to be declared as monitorable variable.
Note: "DeclMV" assigns to "mv" the value 0.0.
defaultScaleMin/defaultScaleMax
Default minimum and maximum values used for the scaling of
the curve to the ordinate while drawing values of the
monitorable variable mv in the graph.
The default minimum and maximum of the ordinate scale is
(re)assigned to the current scale minimum and scale maximum
by ModelWorks during the initialization phase of the
simulation session or after every reset of the scaling.
During a simulation session the current scale minimum and
scale maximum may be changed by the simulationist (using an
IO-window) or by the modeller via procedure SetMV.
descriptor/identifier
Strings containing a long and a short description (identifier) of
the monitorable variable mv.
unit
Unit of monitorable variable mv.
defaultSf, defaultT, defaultG
Default settings for the kind of monitoring for the
monitorable variable mv. If defaultSf, defaultT, defaultG
are selected to be written on a file, tabulated or to be
plotted, the values of the variable mv is written in the
default stashFile, resp. table, or drawn in the graph as a
curve vs the current independent variable. The defaults for
the kind of monitoring are (re)assigned to the current kind
by ModelWorks during the initialization phase of the
simulation session or after every reset of the stash
filing, tabulation respectively graphing. During a
simulation session the current kind of monitoring may be
changed by the simulationist (using the IO-window for
monitorable variables) or by the modeller via procedure
SetMV.
*)
PROCEDURE SelectM (m: Model; VAR done: BOOLEAN);
(*
Overrides current selection of the model to which model objects
will be attached after their declaration by means of the
procedures DeclSV, DeclP and DeclMV. A call to "DeclM" allways
resets this selection to the model it is declaring. The current
selection remains unchanged, if m can not be found ("done" will
then be returned FALSE). If a selected model is removed by a call
to "RemoveM" (see below), the selection is reset to the last
declared model.
*)
(*******************************************************)
(*##### Modifying of models and model objects #####*)
(*******************************************************)
(*
The model and model objects themselves are static and once
declared may not be changed during a simulation session.
However, it is possible to modify the attributes and values
associated with a model or model object. Modifications are
supported by the existence of procedure pairs: a get and a set
procedure. Moreover the procedures are grouped into two sets:
The first set is to modify the defaults, the other to modify
the current values. The meaning of the parameters are the same
as listed under the declaration procedures DeclM, DeclSV,
DeclP, and DeclMV. The parameter lists are kept similar to the
ones used by the declaration procedures; with one exception:
the procedure installModelObjects to declare the model objects
may not be accessed because of the object's static nature.
*)
(*******************************************************************)
(*##### Modifying of defaults of models and model objects #####*)
(*******************************************************************)
PROCEDURE GetDefltM(VAR m: Model; VAR defaultMethod: IntegrationMethod;
VAR initialize, input, output, dynamic, terminate: PROC;
VAR descriptor, identifier: ARRAY OF CHAR; VAR about: PROC);
PROCEDURE SetDefltM(VAR m: Model; defaultMethod: IntegrationMethod;
initialize, input, output, dynamic, terminate: PROC;
descriptor, identifier: ARRAY OF CHAR; about: PROC);
PROCEDURE GetDefltSV(m: Model; VAR s: StateVar; VAR defaultInit,
minCurInit, maxCurInit: REAL;
VAR descriptor, identifier, unit: ARRAY OF CHAR);
PROCEDURE SetDefltSV(m: Model; VAR s: StateVar; defaultInit,
minCurInit, maxCurInit: REAL;
descriptor, identifier, unit: ARRAY OF CHAR);
PROCEDURE GetDefltP(m: Model; VAR p: Parameter; VAR defaultVal, minCurVal, maxCurVal: REAL;
VAR runTimeChange: RTCType;
VAR descriptor, identifier, unit: ARRAY OF CHAR);
PROCEDURE SetDefltP(m: Model; VAR p: Parameter; defaultVal, minCurVal, maxCurVal: REAL;
runTimeChange: RTCType;
descriptor, identifier, unit: ARRAY OF CHAR);
PROCEDURE GetDefltMV(m: Model; VAR mv: REAL; VAR defaultScaleMin, defaultScaleMax: REAL;
VAR descriptor, identifier, unit: ARRAY OF CHAR;
VAR defaultSf: StashFiling; VAR defaultT: Tabulation;
VAR defaultG: Graphing);
PROCEDURE SetDefltMV(m: Model; VAR mv: REAL; defaultScaleMin, defaultScaleMax: REAL;
descriptor, identifier, unit: ARRAY OF CHAR;
defaultSf: StashFiling; defaultT: Tabulation;
defaultG: Graphing);
(*
Setting defaults with any of above procedures will not imply a
setting of the current values also, i.e. no implicit reset!
Until the next corresponding reset, no changes will become
effective or visible. Only the change of the descriptors,
identifiers, and the unit strings as well as the change of the
range boundaries (used during the interactive changing of
initial values or model parameter values via IO-windows) will
become effective immediately.
*)
(*************************************************************************)
(*##### Modifying of current values of models and model objects #####*)
(*************************************************************************)
PROCEDURE GetM (VAR m: Model; VAR curMethod: IntegrationMethod);
PROCEDURE SetM (VAR m: Model; curMethod: IntegrationMethod);
PROCEDURE GetSV (m: Model; VAR s: StateVar; VAR curInit: REAL);
PROCEDURE SetSV (m: Model; VAR s: StateVar; curInit: REAL);
PROCEDURE GetP (m: Model; VAR p: Parameter; VAR curVal: REAL);
PROCEDURE SetP (m: Model; VAR p: Parameter; curVal: REAL);
PROCEDURE GetMV (m: Model; VAR mv: REAL; VAR curScaleMin, curScaleMax: REAL;
VAR curSf: StashFiling; VAR curT: Tabulation;
VAR curG: Graphing);
PROCEDURE SetMV (m: Model; VAR mv: REAL; curScaleMin, curScaleMax: REAL;
curSf: StashFiling; curT: Tabulation; curG: Graphing);
(*
If SetMV is called in the middle of a simulation run (progam
state 'Running') the call will have no effect at all! SetM
should not be called from within procedure Dynamic, all other
Set procedures may be called freely and the effect will be
immediate. Note however, that the change of an initial value,
even if it is immediate, won't affect an already running
simulation; the change will become effective only at the begin
of the next simulation run.
*)
(***************************************************************)
(*##### Resetting of current values to their defaults #####*)
(***************************************************************)
PROCEDURE ResetAllIntegrationMethods;
PROCEDURE ResetAllInitialValues;
PROCEDURE ResetAllParameters;
PROCEDURE ResetAllScaling;
PROCEDURE ResetAllStashFiling;
PROCEDURE ResetAllTabulation;
PROCEDURE ResetAllGraphing;
(*
The first three procedures reset all currently declared models,
state variables and parameters, respectively, to their default
values. The second four procedures operate on the respective
attributes of all currently declared monitorable variables.
*)
(******************************************************************)
(*##### Attaching attributes to models and model objects #####*)
(******************************************************************)
TYPE
Attribute = INTEGER;
CONST
noAttr = MIN(Attribute);
PROCEDURE SetModelAttr(m: Model; val: Attribute);
PROCEDURE GetModelAttr(m: Model): Attribute;
PROCEDURE SetObjAttr(m: Model; VAR o: REAL; val: Attribute);
PROCEDURE GetObjAttr(m: Model; VAR o: REAL): Attribute;
(*
You may associate with any model or model object an integer
attribute by calling SetModelAttr or SetObjAttr respectively.
This attribute's value may then be freely
used via SetObjAttr for assignments or GetObjAttr for retrieval
purposes. Attributes are particularly useful when using one of
the following DoForAllXYZ procedures. Note that in case there
is currently no attribute attached to a model or object, the
value noAttr is returned by ModelWorks.
*)
(*******************************************************************)
(*##### Access helps for all models and all model objects #####*)
(*******************************************************************)
PROCEDURE MDeclared(m: Model): BOOLEAN;
PROCEDURE SVDeclared(m: Model; VAR sv: StateVar): BOOLEAN;
PROCEDURE PDeclared(m: Model; VAR p: Parameter): BOOLEAN;
PROCEDURE MVDeclared(m: Model; VAR mv: REAL): BOOLEAN;
(*
Above routines allow to test whether a model or a model
object is currently declared.
*)
TYPE
ModelProc = PROCEDURE( VAR Model, VAR Attribute );
ModelObjectProc = PROCEDURE( Model, VAR REAL, VAR Attribute );
PROCEDURE DoForAllModels( p: ModelProc );
PROCEDURE DoForAllSVs ( m: Model; p: ModelObjectProc );
PROCEDURE DoForAllPs ( m: Model; p: ModelObjectProc );
PROCEDURE DoForAllMVs ( m: Model; p: ModelObjectProc );
(*
Be careful when using these procedures, since they allow
to access also models and model objects which might not
belong to the caller.
*)
(******************************************************)
(*##### Removing of models and model objects #####*)
(******************************************************)
PROCEDURE RemoveM (VAR m: Model);
PROCEDURE RemoveSV (m: Model; VAR s : StateVar);
PROCEDURE RemoveMV (m: Model; VAR mv: REAL);
PROCEDURE RemoveP (m: Model; VAR p : Parameter);
PROCEDURE RemoveAllModels;
(**********************************************************************)
(*##### Global simulation parameters and project description #####*)
(**********************************************************************)
(*-----------------------------------*)
(*===== Setting of defaults =====*)
(*-----------------------------------*)
PROCEDURE SetDefltGlobSimPars( t0, tend, h, er, c, hm: REAL);
PROCEDURE GetDefltGlobSimPars(VAR t0, tend, h, er, c, hm: REAL);
PROCEDURE SetDefltProjDescrs( title,remark,footer: ARRAY OF CHAR;
wtitle,wremark,autofooter,
recM, recSV, recP, recMV, recG: BOOLEAN);
PROCEDURE GetDefltProjDescrs(VAR title,remark,footer: ARRAY OF CHAR;
VAR wtitle,wremark,autofooter,
recM, recSV, recP, recMV, recG: BOOLEAN);
(*
Sets or gets the defaults for the global simulation parameters
or the project description plus the recording option flags.
Where:
t0 Simulation start time
tend Simulation stop time
h Integration step (if fixed step length method)
maximum integration step (if at least one variable
step length method in use)
(h is only used if at least one continuous time
model present, otherwise ignored)
er Maximum relative local error
(er is only used if at least one variable step length
method in use)
c Discrete time step (if only discrete time models present)
Coincidence interval (if continous as well as discrete
discrete time models present)
hm Monitoring interval
title Project title string
remark Remark string
footer Footer string
wtitle With title in graph
wremark With remarks in graph
autofooter Automatic update of date, time, and run# in footer
recM Recording of data on models in stash file
recSV Recording of data on state variables in stash file
recP Recording of data on model parameters in stash file
recMV Recording of data on monitorable variables in stash file
recG Automatic dumping of the current graph once a
simulation run has been completed onto the stash
file (RTF-Format which can be opened by Microsoftš
Word document processing software)
The call of procedure SetDefltGlobSimPars or SetDefltProjDescrs
will have no effect until the global simulation parameters
respectively the project description are reset.
*)
PROCEDURE SetDefltTabFuncRecording( recTF: BOOLEAN);
PROCEDURE GetDefltTabFuncRecording( VAR recTF: BOOLEAN);
(*
Set or get the default for the recording option flag of table
functions.
*)
PROCEDURE SetDefltIndepVarIdent(descr,ident,unit: ARRAY OF CHAR);
PROCEDURE GetDefltIndepVarIdent(VAR descr, ident, unit: ARRAY OF CHAR);
(*
Set or get the default descriptor, identifier and unit of the
default independent variable, which is used by ModelWorks if no
monitorable variable has been selected as independent variable
('X', 'isX'). The predefined values ModelWorks uses are
descriptor = "time", ident = "t" and unit = "". Setting of
the defaults will become visible once the global simulation
parameters are reset.
*)
(* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
The following procedures are actually only kept for upward
compatibility with previous versions of the ModelWorks client
interface. Their functions are also available (>= V1.2) by
using the procedure SetDefltGlobSimPars and SetGlobSimPars)
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *)
PROCEDURE SetMonInterval(hm: REAL);
(*
Sets the default of the monitoring interval only, not the
current value. The call of this procedure will have no
effect until the global simulation parameters are
reset.
*)
PROCEDURE SetIntegrationStep(h: REAL);
(*
Sets the default integration step only, not the current
value. The call of this procedure will have no effect
until the global simulation parameters are
reset.
*)
PROCEDURE SetSimTime(t0,tend: REAL);
(*
Sets the defaults for the simulation start and stop time as
well as the current simulation start and stop time (Differs
in this respect from all other parameter setting routines,
which affect either only the defaults or only the current
values!) Do not call this procedure from within a model,
during a simulation run or an experiment, since the
simulation time must not be changed during a simulation run
(procedure is ineffective if called while running a
simulation).
*)
(*-----------------------------------------*)
(*===== Setting of current values =====*)
(*-----------------------------------------*)
PROCEDURE SetGlobSimPars( t0, tend, h, er, c, hm: REAL);
PROCEDURE GetGlobSimPars(VAR t0, tend, h, er, c, hm: REAL);
(*
Set or get the current global simulation parameters where:
t0 Simulation start time
tend Simulation stop time
h Integration step (if fixed step length method)
maximum integration step (if at least one variable
step length method in use)
(h is only used if at least one continuous time
model present, otherwise ignored)
er Maximum relative local error
(er is only used if at least one variable step length
method in use)
c Discrete time step (if only discrete time models present)
Coincidence interval (if continous as well as discrete
discrete time models present)
hm Monitoring interval
The call of procedure SetGlobSimPars in the middle of a
simulation will become effective from the next integration
or monitoring or coincidence time point on, depending on
which of the three events occurs first.
*)
PROCEDURE SetProjDescrs( title,remark,footer: ARRAY OF CHAR;
wtitle,wremark,autofooter,
recM, recSV, recP, recMV, recG: BOOLEAN);
PROCEDURE GetProjDescrs(VAR title,remark,footer: ARRAY OF CHAR;
VAR wtitle,wremark,autofooter,
recM, recSV, recP, recMV, recG: BOOLEAN);
(*
Set or get the current project description where:
title Project title string
remark Remark string
footer Footer string
wtitle With title in graph
wremark With remarks in graph
autofooter Automatic update of date, time, and run# in footer
recM Recording of data on models in stash file
recSV Recording of data on state variables in stash file
recP Recording of data on model parameters in stash file
recMV Recording of data on monitorable variables in stash file
recG Automatic dumping of the current graph once a
simulation run has been completed onto the stash
file (RTF-Format which can be opened by Microsoftš
Word document processing software)
*)
PROCEDURE SetTabFuncRecording( recTF: BOOLEAN);
PROCEDURE GetTabFuncRecording( VAR recTF: BOOLEAN);
(*
Set or get the current recording option flag of tabl functions.
*)
PROCEDURE SetIndepVarIdent(descr,ident,unit: ARRAY OF CHAR);
PROCEDURE GetIndepVarIdent(VAR descr,ident,unit: ARRAY OF CHAR);
(*
Set or get the current descripotr, identifier and unit of the
default independent variable, which is used by ModelWorks if no
monitorable variable has been selected as independent variable
('X', 'isX'). The predefined values ModelWorks uses are
descriptor = "time", ident = "t" and unit = "". The call of
this procedure will have no effect until the next simulation
run.
*)
(*------------------------------------------------------------*)
(*===== Reseting of current values to their defaults =====*)
(*------------------------------------------------------------*)
PROCEDURE ResetGlobSimPars;
(*
Reset the following current values to their defaults:
t0, tend, h, er, c, hm
and the
descr, ident, unit
of the default independent variable.
*)
PROCEDURE ResetProjDescrs;
(*
Reset the following variables to their defaults:
title,remark,footer, wtitle, wremark,
autofooter, recM, recSV, recP, recMV, recG
as well as
recTF.
*)
(***************************************************)
(*##### Control of Display and Monitoring #####*)
(***************************************************)
(*-----------------------*)
(*===== Windows =====*)
(*-----------------------*)
PROCEDURE TileWindows; (* tile windows on the screen *)
PROCEDURE StackWindows; (* stack windows on the screen similar
to start up display *)
PROCEDURE InstallTileWindowsHandler(doAtTile:PROC);
PROCEDURE InstallStackWindowsHandler(doAtStack:PROC);
(*
The installed procedures atTile or atStack will be called
immediately after TileWindows or StackWindows, if the the level
at which their installation ocurred is the current DM-level.
*)
TYPE
MWWindow = (MIOW, SVIOW, PIOW, MVIOW, TableW, GraphW, AboutMW, TimeW);
PROCEDURE SetWindowPlace(mww: MWWindow; x,y,w,h: INTEGER);
(*
Place the window mww with its lower left corner at the position
x,y and resize it to the width w and height h (size of outer
frame including title bar and margins). The point [x,y] is
given in coordinates with an origin at the lower left corner of
the main computer screen. All values are given in pixels. If
this procedure is called in case the window should not already
be open, it will open the window with the specified properties.
*)
PROCEDURE GetWindowPlace( mww: MWWindow; VAR x,y,w,h: INTEGER;
VAR isOpen : BOOLEAN );
PROCEDURE SetDefltWindowPlace(mww: MWWindow; x,y,w,h: INTEGER);
PROCEDURE GetDefltWindowPlace( mww: MWWindow; VAR x,y,w,h: INTEGER;
VAR enabled: BOOLEAN );
PROCEDURE CloseWindow(w: MWWindow);
TYPE
IOWColsDisplay = RECORD
descrCol, identCol : BOOLEAN;
CASE iow: MWWindow OF
MIOW : m : RECORD
integMethCol: BOOLEAN;
END(*RECORD*);
| SVIOW : sv: RECORD
unitCol, sVInitCol: BOOLEAN;
fw,dec: INTEGER;
END(*RECORD*);
| PIOW : p : RECORD
unitCol, pValCol, pRtcCol: BOOLEAN;
fw,dec: INTEGER;
END(*RECORD*);
| MVIOW : mv: RECORD
unitCol, scaleMinCol, scaleMaxCol, mVMonSetCol: BOOLEAN;
fw,dec: INTEGER;
END(*RECORD*);
END(*CASE*)
END(*RECORD*);
PROCEDURE SetIOWColDisplay( mww: MWWindow; wd: IOWColsDisplay );
PROCEDURE GetIOWColDisplay( mww: MWWindow; VAR wd: IOWColsDisplay );
PROCEDURE SetDefltIOWColDisplay( mww: MWWindow; wd: IOWColsDisplay );
PROCEDURE GetDefltIOWColDisplay( mww: MWWindow; VAR wd: IOWColsDisplay );
PROCEDURE DisableWindow(w: MWWindow);
PROCEDURE EnableWindow(w: MWWindow);
(*
Disable the window w for any usage, i.e. opening or closing
of the window, or reenable a previously disabled window.
*)
TYPE
MWWindowArrangement = (current, stacked, tiled);
PROCEDURE SetDefltWindowArrangement( a: MWWindowArrangement);
PROCEDURE GetDefltWindowArrangement(VAR a: MWWindowArrangement);
(*
Sets or gets, respectively, the default window arrangement.
If you call SetDefltWindowArrangement with the argument
current, all current windows and window positions are used
as the defaults (inverse function of ResetWindows).
Otherwise the defaults are exactly those you would obtain
if you called procedure StackWindows (stacked) or
TileWindows (tiled), respectively. Note: To make good use
of screen space, the actual positions you obtain differ in
function of the sizes of the screen(s) which you actually
use; this is particularly critical in case of a tiled
window arrangement.
*)
PROCEDURE GetWindowArrangement(VAR a: MWWindowArrangement);
(*
Allows you to learn about the current window arrangement.
NOTE: There is no routine SetWindowArrangement, since you can
use StackWindows (stacked), TileWindows (tiled), and
the routines SetWindowPlace (current) instead.
*)
PROCEDURE ResetWindows;
(*
Reset window places and columns display to their default values
*)
(*-----------------------------------------*)
(*===== Global Monitoring Control =====*)
(*-----------------------------------------*)
PROCEDURE SuppressMonitoring;
PROCEDURE ResumeMonitoring;
(*
Suppress respectively resume all monitoring without affecting
any of the current monitoring settings.
*)
PROCEDURE InstallClientMonitoring( initClientMon, doClientMon, termClientMon: PROC );
(*
Installs in ModelWorks client provided monitoring procedures.
At the begin respectively the end of every simulation run the
procedures initClientMon respectively termClientMon are
called. During the simulation run the monitoring procedure
doClientMon is called every time or integration step once.
Procedure initClientMon serves to initialize the client
monitoring such as opening of a window, a file, and is called
at the very first monitoring point (time = t0). The procedures
initClientMon and doClientMon will be called as the last
monitoring procedure, i.e. after ModelWorks executes its stash
file, tabulation, and graph monitoring procedures.
termClientMon will be called as the first monitoring
termination procedure, i.e. before ModelWorks closes the stash
file, terminates tabulation, and draws in the graph for the
last time.
*)
PROCEDURE SetStashFileName ( sfn: ARRAY OF CHAR);
PROCEDURE GetStashFileName (VAR sfn: ARRAY OF CHAR);
(*
Sets or gets the current name of the stash file (may contain a
path, e.g. Disk:Folder:MyFile.DAT). The call to
SetStashFileName will have no effect until the stash file is
actually opened during a subsequent simulation. Calling this
procedure in the middle of a simulation run (substate
'Running') will have no effect, however in the substate 'No
run' it allows to switch the stash file, e.g. during an
experiment, by closing the one currently in use and open as the
new stash file one with the name sfn.
I M P O R T A N T N O T I C E: If a file with the same
name should already exist, it will be overwritten without any
warning!! This behavior contrasts with the setting of the
name via the user interface (menu command 'Settings/Select
stash file...').
*)
PROCEDURE SetDefltStashFileName( dsfn: ARRAY OF CHAR);
PROCEDURE GetDefltStashFileName(VAR dsfn: ARRAY OF CHAR);
(*
Sets or gets the default name of the stash file (may contain a path,
e.g. Disk:Folder:MyFile.DAT). The call to SetDefltStashFileName
will have no effect until the stash file name is actually reset.
I M P O R T A N T N O T I C E: If a file with the same
name should already exist, stash filing will overwrite this
file without any warning!!
*)
PROCEDURE SwitchStashFile(newsfn: ARRAY OF CHAR);
(*
Similar to SetStashFileName, but always actually switches
to a new file (forced switch). In particular, if a stash
file is currently open, this routine always closes first
the currently opened stash file and opens another, new one
with the name 'newsfn'. Of course, in case if there is
currently no stash file open, this routine behaves similar
to what SetStashFileName does, i.e. the name of the stash
file to be opened next time a simulation run requires stash
filing, is the name passed for argument 'newsfn'.
*)
PROCEDURE SetStashFileType ( filetype, creator: ARRAY OF CHAR);
PROCEDURE GetStashFileType (VAR filetype, creator: ARRAY OF CHAR);
PROCEDURE SetDefltStashFileType( dFiletype,dCreator: ARRAY OF CHAR);
PROCEDURE GetDefltStashFileType(VAR dFiletype,dCreator: ARRAY OF CHAR);
(*
On the Macintosh, any file is of a particular type and is
associated with a particular application characterized by the
creator, each given by a 4 character long string. The purpose
and timing of the effects by these routines is exactly the same
as that described for the routines affecting the name of the
stash file. The predefined defaults are those inherited from
the 'Dialog Machine'.
*)
PROCEDURE ResetStashFile;
(*
Resets the current name of the stash file, its type and its
creator to its default name, type and creator.
*)
PROCEDURE Message(m: ARRAY OF CHAR);
(*
Write the message m onto the stash file and into the window
table. This procedure surrounds the string m with quotes
'"' and preceeds it with the reserved word MESSAGE. In
case neither the stash file nor the table window are
currently open, the call to this procedure will not force
the opening of the stash file or the table and the message
display will be suppressed.
*)
(*--------------------------------*)
(*===== Curve Attributes =====*)
(*--------------------------------*)
TYPE
Stain =
(coal, snow, ruby, emerald, sapphire, turquoise, pink, gold, autoDefCol);
(* Order is the same as the sequence in which the color variables are
listed in the definition of module DMWindIO; for autoDefCol see comment
for procedures Set/GetCurveAttrForMV *)
LineStyle =
(unbroken, broken, dashSpotted, spotted, invisible, purge, autoDefStyle);
CONST
autoDefSym = 200C;
PROCEDURE SetCurveAttrForMV(m: Model; VAR mv: REAL;
col: Stain; ls: LineStyle;
sym: CHAR);
PROCEDURE GetCurveAttrForMV(m: Model; VAR mv: REAL;
VAR col: Stain; VAR ls: LineStyle;
VAR sym: CHAR);
(*
Sets or gets the curve attributes used by ModelWorks for the
monitoring of simulation results in the graph for the monitorable
variable mv belonging to model m. Where:
col Stain to be used to draw the lines and/or symbols
of a curve in the graph (autoDefCol can be used for
automatic color definition provided by ModelWorks)
ls LineStyle of lines to be drawn between monitoring
times.
unbroken _______________ broken - - - - - - - -
dashSpotted -.-.-.-.-.-.-.- spotted ...............
invisible (no drawing at all,
may be used to stop drawing of a particular curve,
while others are still drawn)
wipeout (used to erase already
drawn curves)
autoDefStyle (used for automatic style
definition provided by
ModelWorks)
sym Character to be used to draw a value at a monitoring
time, e.g. "*" to obtain curves like ---*---*---
(autoDefSym can be used for automatic symbol definition)
*)
PROCEDURE SetDefltCurveAttrForMV(m: Model; VAR mv: REAL;
col: Stain; ls: LineStyle;
sym: CHAR);
PROCEDURE GetDefltCurveAttrForMV(m: Model; VAR mv: REAL;
VAR col: Stain; VAR ls: LineStyle;
VAR sym: CHAR);
PROCEDURE ResetAllCurveAttributes;
(*
Reset curve attributes of all monitorable variables to their
defaults.
*)
PROCEDURE ClearTable;
PROCEDURE ClearGraph;
(*
Clear and redraw the table respectively the graph window.
*)
PROCEDURE DumpGraph;
(*
Dumps the graph onto the stash file in case it is currently in
use. The data are written to the file in the so-called
RTF-Format which can be opened by the Microsoftš Word document
processing software. Note: the graph is dumped regardless of
the current setting of the flag «Automatic dumping of graph at
end of simulation run» recG (see procedures to access the
project descriptors).
*)
(*************************************************)
(*##### Assignment of predefined values #####*)
(*************************************************)
PROCEDURE SetPredefinitions;
(*
Sets the defaults for the
global simulation parameters,
project description,
stash file (name, type, creator)
and the
windows (position, columns display)
to ModelWorks-predefined values. See the ModelWorks manual for
more information on the predefined defaults.
*)
PROCEDURE ResetAll;
(*
Resets all
global simulation parameters,
project description,
stash file (name, type, creator)
windows (position, columns display)
as well as all declared
models,
state variables,
parameters,
monitorable variables (filing, tabulation, graphing,
scaling, curve attributes)
to their defaults.
*)
(**************************************************************)
(*##### Preferences and simulation environment modes #####*)
(**************************************************************)
(* The simulation environment of ModelWorks knows several modes
which can be set according to the preferences of the
simulationist (see Menu command "Preferences…") or which can be
controlled via the client interface by the following procedures.
Note that these procedures affect the current settings of the
modes permanently such that they will be remembered and used
again by the simulation environment if it is started the next
time. Note also that this behavior differs from the default
concept ModelWorks normally adopts for the maintenance of other
values, i.e. there exist no defaults for the modes of the
simulation environment, just current values. *)
PROCEDURE SetDocumentRunAlwaysMode(dra: BOOLEAN);
PROCEDURE GetDocumentRunAlwaysMode(VAR dra: BOOLEAN);
(*
If the mode «document run allways» is activated, every
execution of a simulation run will be documented onto
stash-file according to the current settings of the project
descriptors. Note that the stash file gets rewritten with every
new run.
*)
PROCEDURE SetAskStashFileTypeMode(asft: BOOLEAN);
PROCEDURE GetAskStashFileTypeMode(VAR asft: BOOLEAN);
(*
If the mode «ask for stash file type» is activated, every time
the simulationist has selected a new stash file a dialog is
displayed allowing to specify the file's type and creator.
*)
PROCEDURE SetRedrawTableAlwaysMode(rta: BOOLEAN);
PROCEDURE GetRedrawTableAlwaysMode(VAR rta: BOOLEAN);
(*
The mode «redraw table always» describes the behaviour of the
table window in respect to modifications of the tabulation
monitoring settings. For further explanations see mode «redraw
graph always» below.
*)
PROCEDURE SetCommonPageUpRows(rows: CARDINAL);
PROCEDURE GetCommonPageUpRows(VAR rows: CARDINAL);
(*
This mode controls the number of common rows between page ups
in the table window.
*)
PROCEDURE SetRedrawGraphAlwaysMode(rga: BOOLEAN);
PROCEDURE GetRedrawGraphAlwaysMode(VAR rga: BOOLEAN);
(*
If the mode «redraw graph always» is activated, each
modification of the graphing monitoring settings will be
displayed immediately, not only just at the begin of the next
simulation run. This implies an immediate loss of all
simulation results eventually currently visible in the graph.
If this mode is not active, the current graph will not be
touched unless the user starts the next simulation run, before
which the graph will be completely redrawn. It is recommended
to activate this mode, since if deactivated this might result
in discrepancies between current settings and what is visible
on the screen. Only in situations where another simulation run
is too costly (rerun takes too much time) such discrepancies
can be tolerated in order to keep the precious simulation results
as long as possible.
*)
PROCEDURE SetColorVectorGraphSaveMode(cvgs: BOOLEAN);
PROCEDURE GetColorVectorGraphSaveMode(VAR cvgs: BOOLEAN);
(*
If the mode «color and vector graph saving» is activated, each
time the graph window needs to be redrawn because some parts of
it become visible again after they have been covered by another
window (see also description of restore or update mechanism in
module DMWindows of the 'Dialog Machine') the graph will be
reconstructed in colors otherwise only black and white. Note
that this mode won't affect the very first drawing of the
graph, i.e. on a color screen you may get colored curves, even
if this mode should be turned off. Since the full
reconstruction in colors for complicated graphs may be slow,
especially on monochrome monitors it may be preferable to
deactivate this mode (trade-off between colors and speed). In
addition to the colors all graphical output is stored as
vectorized objects. This allows printing and copying to the
clipboard of graphs in high resolution quality, but requires a
corresponding amount of memory. Deactivation of this mode
results in storing graphical output in a bitmap without colors,
with a coarser resolution and more modest memory requirements.
Note that on black-and-white monitors only, this mode must be
active in order to obtain colored output on a printer or other
color device (transferred via clipboard).
*)
(***********************************************************************)
(*##### Customization of keyboard shortcuts for menu commands #####*)
(***********************************************************************)
(* Alias characters associated with ModelWorks menu-commands may
be customized according to the needs of the simulationist either
interactively (see Menu command “Customize…”) or by means of the
following procedures. While an interactive specification is only
possible for the most important commands, the so-called “core”
menu commands, the client interface allows to modify the keyboard
equivalents for all commands (except the ones listed under the
“Edit” Menu). In either case, the newly set alias characters will
be immediately used and remembered by the simulation environment
when it is started the next time. *)
TYPE
MWMenuCommand = ( pageSetUpCmd, printGraphCmd, preferencesCmd, customizeCmd,
(*core commands*) setGlobSimParsCmd, setProjDescrCmd, selectStashFileCmd,
resetGlobSimParsCmd, resetProjDescrCmd, resetStashFileCmd,
resetWindowsCmd, resetAllIntegrMethodsCmd, resetAllInitialValuesCmd,
resetAllParametersCmd, resetAllStashFilingCmd, resetAllTabulationCmd,
resetAllGraphingCmd, resetAllScalingCmd, resetAllCurveAttrsCmd,
resetAllCmd, defineSimEnvCmd,
(*core commands*) tileWindowsCmd, stackWindowsCmd, modelsCmd, stateVarsCmd,
(*core commands*) modelParamsCmd, monitorableVarsCmd, tableCmd, clearTableCmd,
(*core commands*) graphCmd, clearGraphCmd,
(*core commands*) startRunCmd, haltOrResumeRunCmd, stopCmd, startExperimentCmd);
PROCEDURE SetMenuCmdAliasChar(cmd: MWMenuCommand; alias: CHAR);
PROCEDURE GetMenuCmdAliasChar(cmd: MWMenuCommand; VAR alias: CHAR);
(*
Get, respectively set, an alias character (i.e. keyboard equivalent or
shortcut) associated with a particular ModelWorks menu-command.
*)
PROCEDURE ResetCoreMenuCmdsAliasChars;
(*
The interactively specifiable alias characters are reset to
their default values as described in the ModelWorks reference.
*)
PROCEDURE ResetAllMenuCmdsAliasChars;
(*
The alias characters of all menu commands are reset to the
defaults described in the ModelWorks reference.
*)
END SimBase.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib