DEFINITION MODULE EasyMWFcts;
(*******************************************************************
Module EasyMWFcts (Easy_ModelWorks_1.5)
Copyright (c) 1996-2006 by Andreas Fischlin and ETH Zurich.
Purpose Client (programmer's) interface of 'Easy ModelWorks'.
It can be used to access all functions 'Easy ModelWorks'
offers in addition to those of its big sister 'ModelWorks'.
Remarks See also module SampleMods [files SampleMods.DEF
and SampleMods.MOD (Template)] for further explanations
and sample code for typical use of this module.
Reference:
Fischlin et al., 1994. ModelWorks - An Interactive
Simulation Environment for Personal Computers and
Workstations. Systems Ecology Report #14, 324pp.
Programming
o Design
Andreas Fischlin 10/04/1996
o Implementation
Andreas Fischlin 10/04/1996
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: 08/05/1996 AF
*******************************************************************)
CONST
maxSysOrder = 9; (* x1 .. x9 *)
maxParams = 31;
noSampleModelActive = 0;
ModelWorksMDPsActive = -1;
dynLoadedProgActive = -2;
(* values CurrentSampleModel may return *)
(*******************************************************************
Meaning of following so-called Enter procedures is the same as when
entering data for a system specification interactively during the
dialog in 'Easy ModelWorks' when making a new model. These routines
are typically used while specifiying the so-called sample models.
For sample code see the template implementation for module
SampleMods (SampleMods.MOD (Template)).
*******************************************************************)
PROCEDURE EnterModelOk(name: ARRAY OF CHAR; sysOrd,nrPars: INTEGER;
contTime: BOOLEAN): BOOLEAN;
(* Always call this procedure at the beginning of any system
specification programmed by means of Enter procedures. contTime = TRUE
=> interpret as differential equation (DESS), if FALSE interpret as
difference equation system (SQM). NOTE: This funtion does clear any
previously existing 'Easy ModelWorks' model (albeit user get's a warning
and can save previous editing). This procedure returns FALSE if the
user has cancelled the process, while having been asked to save
changes. In this case you should not continue with any system
specifications. In all other cases the result is TRUE, which indicates
you may continue with calling further Enter procedures (see below). *)
PROCEDURE EnterDiffEqu(index: INTEGER;
diffEquExpression: ARRAY OF CHAR; x0: REAL);
(* Call EnterDiffEqu for every differential/difference equation,
i.e. 1..sysOrd times. *)
PROCEDURE EnterMonitoring(index: INTEGER; xmin, xmax: REAL;
tabulation, plotting: CHAR);
(* Call EnterMonitoring for every state variable for which you
wish to specify a monitoring which deviates from the default values.
Defaults are xmin = -1.0, xmax = +1.0, tabulation = "T" (values will
be tabulated), and plotting = "Y" (values will be plotted vs. time).
The index has to be a value between 1..sysOrd, or the procedure
will have no effect. If you wish to suppress tabulation or plotting,
pass 0C. For plotting where you wish to use the state variable on the
x-axis (abscissa), pass 'X'. *)
PROCEDURE EnterParam(ident: ARRAY OF CHAR; value: REAL);
(* Call EnterParam for every model parameter, i.e. 1..nrPars times
as passed to last call of EnterModelOk. Once EnterParam has been
called, the identifier ident may be used in equations. *)
PROCEDURE EnterSimParams(tmin,tmax,deltat: REAL);
(*******************************************************************
The following procedures are typically used while programing a
the so-called user function (see module SampleMods), especially
SampleMods.MOD (Ctrl. Theor.) which demonstrate the use of these
procedures to display a signal flow diagram with parameters which
can be edited in the diagram by means of scroll bars (even during
simulations).
*******************************************************************)
PROCEDURE EditSystem;
(* Enters a modal dialog to edit the current 'Easy ModelWorks' model, in
particular the equations, but also other items can be edited (even the
system order!). *)
PROCEDURE DisallowEquationEditing;
(* Suppresses the editing of equations of the current sample model.
However, initial conditions, plot ranges, as well as parameters can
still be edited. The mode will be cleared as soon as another sample
model or ordinary user model becomes active *)
PROCEDURE EnableUserFunction;
(* Call this procedure to enable the so-called user function as
exported my module SampleMods. By default this function is disabled
(dimmed menu command) and in order to make it available to the user of
'Easy ModelWorks' you should call EnableUserFunction within the body of a
specific sample model. See 'SampleMods.MOD (Ctrl. Theor.)' for some
sample code of how to use this feature. *)
PROCEDURE GetCurrentSysSpecs (VAR name: ARRAY OF CHAR;
VAR n,m: INTEGER;
VAR contTime: BOOLEAN);
(* Returns the current system specifications, where name is the current
name string, n is the number of equations (x1Dot .. xnDot resp. x1New
.. xnNew), m is the number of parameters (p1 .. pm), and contTime
tells you whether the system specification is a continuous time DESS
(Differential Equation System Specification) or a discrete time SQM
(Sequential Machine - Difference Equations). *)
PROCEDURE CurrentSampleModel(): INTEGER;
(* Returns the number (index) of the currently active sample model
(1..6). Returns noSampleModelActive (0), if none of the sample models
is active, e.g. the model the user has defined or loaded from disk.
Returns ModelWorksMDPsActive if currently a Model Definition Program
(MDP) is active (for explanations on MDPs see Fischlin et al., 1994).
*)
PROCEDURE GetEquation (i: INTEGER; VAR equ: ARRAY OF CHAR);
(* Returns the current right hand expression of the equation i
(i IN [1..curMaxSysOrder]). *)
PROCEDURE X(i: INTEGER): REAL;
(* Returns the current value of the state variable xi (i IN
[1..curMaxSysOrder]). E.g. X(1) returns the value of the state
variable x1 (as used in the differential resp. difference equations).
If the index is out of range, DMConversions.UndefREAL is returned. *)
PROCEDURE X0(i: INTEGER): REAL;
(* Returns the initial condition value of the state variable xi (i IN
[1..curMaxSysOrder]). E.g. X0(1) returns the value of the state variable
x10 (as used in the differential resp. difference equations). If the
index is out of range, DMConversions.UndefREAL is returned. *)
PROCEDURE Xmin(i: INTEGER): REAL;
(* Returns the minimum of the plotting range for state variable xi (i IN
[1..curMaxSysOrder]). E.g. Xmin(1) returns the value of x1min (as used
in the system specification). If the index is out of range,
DMConversions.UndefREAL is returned. *)
PROCEDURE Xmax(i: INTEGER): REAL;
(* Returns the maximum of the plotting range for state variable xi (i IN
[1..curMaxSysOrder]). E.g. Xmax(1) returns the value of x1max (as used
in the system specification). If the index is out of range,
DMConversions.UndefREAL is returned. *)
PROCEDURE P(ident: ARRAY OF CHAR): REAL;
(* Returns the current value of the parameter with the identifier ident
as used in the differential resp. difference equations. If the
parameter is not known DMConversions.UndefREAL is returned. *)
PROCEDURE SetNewX(i: INTEGER; x: REAL);
(* Sets the state variable xi (i IN [1..curMaxSysOrder]) to the value
x. This procedure can be used to change values anytime, i.e. even
during simulations (Note the change will always take place only at well
defined times, i.e. only at descretization points, regardless of the
time when this procedure has been called. 'Easy ModelWorks' uses the
rather sophisticated run-time system of ModelWorks; for details see
Fischlin et al., 1994). The procedure is ineffective if the index is
out of range. *)
PROCEDURE SetNewX0(i: INTEGER; newx0: REAL);
(* Sets a new value for the initial condition of state variable xi (i
IN [1..curMaxSysOrder]). This procedure can be used to change initial
values anytime, i.e. even during simulations. However, note the
change will take effect only at the begin of the next simulation run.
The procedure is ineffective if the index is out of range. *)
PROCEDURE SetNewMonitoring(i: INTEGER; xmin, xmax: REAL;
tabulation, plotting: CHAR);
(* Sets new monitoring attributes for the state variable xi (i IN
[1..curMaxSysOrder]). Note, this procedure is similar to
EnterMonitoring, except that it's effect is slightly different.
SetNewMonitoring is typically called outside of a procedure
SampleModeli (see module SampleMods). Hence, at its end the
consequences of the new monitoring will be immediate. For instance,
if you call this routine while a simulation is running, it might
immediately change the graph and all drawing previous to the call of
SetNewMonitoring will be lost. *)
PROCEDURE SetNewP(ident: ARRAY OF CHAR; newval: REAL);
(* Sets a new value for the parameter with the identifier ident.
This procedure can be used to change parameter values anytime, i.e.
even during simulations. However, note the procedure is ineffective
if the parameter is not know, i.e. has not been made known to
'Easy ModelWorks', e.g. by EnterParam or by the user while editing
equations. *)
(* Message exchanges between 'Easy ModelWorks' and User Function code *)
PROCEDURE ForceUpdating;
(* Sends 'Easy ModelWorks' the message that all use and display of the
model specifications need to be updated, e.g. the values shown in the
window Equations etc. Note, 'Easy ModelWorks' already calls this
function at the end of any call to the procedures SampleModeli (see
module SampleMods). All SeNew... procedures such as SetNewP, do also
already call ForceUpdating. You need this procedure only in those
cases where you should use any of the Enter procedures outside of a
SampleModeli procedure. Then you should call this procedure at the end
of your sequence of calls to Enter procedures (otherwise the internal
data structure may not be consistent). However, typically there is
rarely a need to call this procedure. *)
PROCEDURE InstallCleanUpHandler (cluphdl: PROC);
(* Use this procedure to install a clean up handler. Such a handler
may be useful for cleaning up in case of a switch to another model.
For instance, if the user function associated with a particular sample
model opens a window, this procedure can be used to close that window
if the user of 'Easy ModelWorks' decides to switch to another model,
where this window becomes meaningless. See 'SampleMods.MOD (Ctrl.
Theor.)' for some sample code of how to use this feature. *)
PROCEDURE InstallUpdateHandler (updthdl: PROC);
(* Use this procedure to install an update handler. Such a handler is
useful if you represent the same objects, like parameters, initial
conditions etc. in an additional view such as a window activated by
the user function. If the 'Easy ModelWorks' user uses the ordinary
editing facilities offered by 'Easy ModelWorks', such a handler makes it
possible to update the additional views on these objects accordingly.
'Easy ModelWorks' will call the installed updthdl each time any parameter
value, initial condition, equation etc. within the current sample
model changes (however, will not be called if only state variables
change during simulation. You need to use ModelWorks client monitoring
feature to animate simulations; see also Fischlin et al., 1994). See
'SampleMods.MOD (Ctrl. Theor.)' for some sample code of how to use
this feature. *)
TYPE
BooleanFct = PROCEDURE (): BOOLEAN;
PROCEDURE AnnounceMWMDP (VAR which: INTEGER; descr: ARRAY OF CHAR;
act,deact,prefs: PROC; isact: BooleanFct;
byDfltAct: BOOLEAN);
(* Announces to 'Easy ModelWorks' an ordinary ModelWorks (MW) Model
Definition Program (MDP). Since up to 16 such models can be announced,
each is identified by the unique number which (which is assigned at the
moment of announcement). Each model is described by descr, which is
also used in the selector dialog. The procedures act, deact activate,
respectively deactivate the model. prefs is a procedure which
determines initial settings, e.g. ModelWorks simulation time etc., at
activation of the model. isact returns whether the model is currently
active. If AnnounceMWMDP is called, 'Easy ModelWorks' offers an
additional menu command in the submenu "Sample Models", by which models
can be activated or deactivated any time. byDfltAct determines whether
the model is by default checked during the selection dialog. For a
typical use of this procedure see the template for SampleMods. *)
PROCEDURE NoGlobPrefs;
(* For your convenience provided. It may be used while calling
AnnounceMWMDP to be passed as an actual argument for prefs *)
PROCEDURE ActivateStateSpaceClick; (* implies abscissa drawing *)
PROCEDURE DeactivateStateSpaceClick;
PROCEDURE DeactivateAbscissaDrawing;
(*
You can activate a so-called state space click mechanism: If this
mechanism is active you can click with the mouse into the graph window
to set new initial conditions (and halt the current simulation run).
The pointed at location is then interpreted as a point in state space
and the initial conditions of the state variables which are currently
used for drawing in the graph window set accordingly. This supports
interactive phase portrait construction.
If the origin moves above the lower left corner of the graph panel,
ModelWorks does not draw an abscissa. 'Easy ModelWorks' supports such a
mechanism. ActivateStateSpaceClick implicitly activates also the mode
abscissa drawing. With the routines DeactivateStateSpaceClick or
DeactivateAbscissaDrawing you can control all possible settings.
By default for each model both modes are active. The current settings
are visible via checkmarks in the menu Windows, where they can also
be controlled freely.
*)
END EasyMWFcts.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib