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