ETHZ_Logo RAMSES_Logo_Right   RAMSES   RAMSES_Logo_Left Systems Ecology  
Start    search button      Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

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.

  Contact RAMSES@env.ethz.ch Last updated: 25-Jul-2011 [Top of page]