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

DEFINITION MODULE StateEvents;

  (*******************************************************************

    Module  StateEvents     (Version 1.0)

      Copyright (c) 1994-2006 by Andreas Fischlin and ETH Zurich.

    Purpose   Support the detection of state events in
              ModelWorks simulations.

    Remarks   This module imports from the ModelWorks client
              interface.


    Programming

      o Design
        Andreas Fischlin          10/03/1994

      o Implementation
        Andreas Fischlin          10/03/1994


    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:  10/03/1994  AF

  *******************************************************************)


  FROM SimBase IMPORT StateVar;


  TYPE
    StateEvt;

  VAR
    unexpectedStateEvt: StateEvt; (* read only! *)
    (*
      Read only variable which may be used for variables of type
      StateEvt to denote that they have not yet been declared, i.e.
      ExpectStateEvt has not yet been called.  It is a good
      programming practice to assign this value to all state event
      variables during the initialization phase of a program.
    *)



  PROCEDURE ExpectStateEvt(VAR evt: StateEvt; x: StateVar; theta1,theta2: REAL);
    (*
      Declare a state event evt, which is expected to occur as soon
      as theta1 <= x <= theta2.  Note that this procedure allows
      to detect state events according to the following four cases:

        case    remark        condition     typical call
        --------------------------------------------------------------------------
        (i)     exact match   x = theta     ExpectStateEvt(evt,x,theta,theta);
        (ii)    smaller than  x <= theta    ExpectStateEvt(evt,x,MIN(REAL),theta);
        (iii)   bigger than   x >= theta    ExpectStateEvt(evt,x,theta,MAX(REAL));
        (iv)    in range      th1<=x<=th2   ExpectStateEvt(evt,x,th1,th2);
        --------------------------------------------------------------------------

      For actual state event detection see comments on procedure
      IsStateEvt.

      Important Note: In case (i) x must contain the correct
      current value of the state variable, otherwise state event
      detection may fail.

      ExpectStateEvt may also be called to redefine state events which have
      already been declared previously, i.e. it acts as SetStateEvt.

      Implementation restriction: case (i) requires to pass two
      really identical actual arguments for the formal parameters
      th1 and th2.
    *)

  PROCEDURE StateEvtExpected(evt: StateEvt): BOOLEAN;
    (*
      Checks wether the event evt is currently really expected, i.e.
      evt has been declared by a call to ExpectStateEvt.
    *)

  PROCEDURE IsStateEvt(evt: StateEvt; x: StateVar): BOOLEAN;
    (*
      Returns whether state event occurred, i.e. the current value
      of x satiesfies the condition associated with evt (see
      comments on procedure ExpectStateEvt).

      By definition, in the case (i) the state event can occur only
      once, in all other cases IsStateEvt returns TRUE as long as
      the condition, theta1 <= x <= theta2 is satisified.

      Note, in case (i) no exact match is actually detected, i.e.
      no iteration is performed by the run time system till the
      event is matched with a given precision.  Instead it is
      detected wether the coordinate x of the trajectory of the
      state variable x has actually crossed the value theta during
      the last integration step, i.e. the current state x is in the
      other half subspace (theta divides space of x into 2 half
      spaces) than it was at the begin of the last time step. Thus,
      in case of a continous time system (DESS) x may not exactly
      match theta but only be close to theta.  The precision of the
      match may vary, depending on the current integration step.

      This implementation offers the advantage, that it can also be
      used for difference equations (SQM) or discrete event systems
      (DEVS), where theta might not be defined at all and iteration
      procedures are likely not to converge.

      Non-scalar state events can be detected by calling IsStateEvt
      for each component one after the other.  Thus, only state
      events can be detected where the current state falls into an
      orthogonal region of the system's state space.
    *)

  PROCEDURE SetStateEvt(evt: StateEvt; x: StateVar; theta1,theta2: REAL);
  PROCEDURE GetStateEvt(evt: StateEvt; VAR theta1,theta2: REAL);
    (*
      Allow to set or get the current specifications of an already
      declared state event evt. For the meaning of the parameters see
      procedures ExpectStateEvt respectively IsStateEvt.
    *)


  PROCEDURE IgnoreStateEvt(VAR evt: StateEvt);
    (*
      Ignore from now on any state event evt, i.e. reverse effect
      of ExpectStateEvt.
    *)


END StateEvents.