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 SimObjects;

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

    Module  SimObjects     (MW_V3.0)

      Copyright (c) 1991-2006 by Dimitrios Gyalistras, Andreas Fischlin
      and ETH Zurich.

    Purpose   Access to the model and model objects base of
              'ModelWorks', plus  procedures to attach reference
              attributes to 'ModelWorks' objects.

    Remarks   This module is part of the optional client interface of
              'ModelWorks', an interactive Modula-2 modelling and
              simulation environment.


    Programming

      o Design
        Dimitrios Gyalistras      25/07/1991
        Andreas Fischlin          27/11/1992

      o Implementation
        Dimitrios Gyalistras      31/07/1991
        Andreas Fischlin          27/11/1992


    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:  30/05/1998  AF

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


  FROM SYSTEM    IMPORT ADDRESS;
  FROM DMStrings IMPORT String;
  FROM SimBase   IMPORT Model, StashFiling, Tabulation, Graphing;


  (****************************)
  (*#####   Attributes   #####*)
  (****************************)

  TYPE
    RefAttr;

  VAR
    aDetachedRefAttr: RefAttr; (* read only variable *)


  PROCEDURE AttachRefAttrToModel  (m: Model; VAR a: RefAttr; val: ADDRESS);
  PROCEDURE DetachRefAttrFromModel(m: Model; VAR a: RefAttr );

  PROCEDURE AttachRefAttrToObject  (m: Model; VAR o: REAL; VAR a: RefAttr; val: ADDRESS);
  PROCEDURE DetachRefAttrFromObject(m: Model; VAR o: REAL; VAR a: RefAttr );

  PROCEDURE FindModelRefAttr (m: Model; VAR a: RefAttr);
  PROCEDURE FindObjectRefAttr(m: Model; VAR o: REAL; VAR a: RefAttr);

  PROCEDURE SetRefAttr(a: RefAttr; val: ADDRESS);
  PROCEDURE GetRefAttr(a: RefAttr): ADDRESS;
  (*
    You may associate with any model or model object an address
    attribute by calling AttachRefAttrToModel respectively
    AttachRefAttrToObject.  The attribute's value may then be
    freely used via SetRefAttr for assignments or GetRefAttr for
    retrieval purposes. RefAttrs are particularly useful when using
    one of the SimBase.DoForAllXYZ procedures. Note that in case
    there is currently no attribute attached to a model or object,
    the value aDetachedRefAttr is passed by ModelWorks.  It is also
    possible to access an attribute via model respectively model
    plus object by the procedures FindModelRefAttr respectively
    FindObjectRefAttr.  Note however, that the latter method is
    less efficient and is therefore not recommended in heavy
    number-crunching simulations. Again aDetachedRefAttr is
    returned in case there is currently no attribute attached.
  *)



  PROCEDURE CurCalcMRefAttr(): ADDRESS;
  (*
    Returns first attribute associated to the model of which the
    initialize, input, output, or dynamic etc. procedure is
    currently calculated. The value NIL is returned if
    (SimMaster.MWState <> simulating) or (SimMaster.MWSubState <>
    running), or if no attribute has been attached to the model.
  *)

  PROCEDURE CurAboutMRefAttr(): ADDRESS;
  (*
    Returns first attribute associated to the model of which the
    about procedure is currently executed. The value NIL is returned
    if this procedure is called outside 'about'.
  *)


  (***********************************)
  (*#####   Subprogram levels   #####*)
  (***********************************)

  (*
    Only of relevance if implementation features a dynamic linking-loader
    such as is the case for MacMETH.
  *)

  PROCEDURE ModelLevel(m: Model): CARDINAL;
  (*
    Returns the program level at which model m has been
    instanciated if the model exists, otherwise 0.
  *)

  PROCEDURE ObjectLevel(m: Model; VAR o: REAL): CARDINAL;
  (*
    Returns the program level at which object o of model m has been
    instanciated if such an object exists, otherwise 0.
  *)


  (*********************************************)
  (*#####   Direct object manipulations   #####*)
  (*********************************************)

  (*
    the following type and procedures allow for very efficient access to
    the most important ModelWorks objects.  These information are provided
    for the advanced client who writes additional, generally usable tools
    for the ModelWorks environment.  The direct access to some of these
    data can be risky - the programmer ought to understand well what
    he/she does.
  *)

  TYPE
    MWObj = (Mo, SV, Pa, MV, AV );
    RealPtr = POINTER TO REAL;
    PtrToClientObject = ADDRESS;

    ModelPtr = POINTER TO ModelHeader;
    ModelHeader = RECORD
      ident     : String;
      descr     : String;
      fill1     : String;  (* not used *)
      fill2     : RealPtr; (* not used *)
      fill3,               (* not used *)
      fill4     : REAL;    (* not used *)
      nrAttr    : INTEGER;
      refAttr   : PtrToClientObject; (* read only *)
      chAttr    : CHAR;   (* may be freely used to mark the object *)
      kind      : MWObj;  (* read only!! *)
      parentM   : Model;  (* owning model/system, used for hierarchical modeling *)
      next      : ModelPtr; (* read only!! *)
      prev      : ModelPtr; (* read only!! *)
      lev       : CARDINAL; (* read only!! *)
    END(*ModelHeader*);

    MObjPtr = POINTER TO MObjectHeader;
    MObjectHeader = RECORD
      ident     : String;
      descr     : String;
      unit      : String;
      varAdr    : RealPtr; (* read only!!; real itself may be altered
                              is the actual state var in case of an sv *)
      min, max  : REAL;    (* is curScaleMin, curScaleMax in case of mv *)
      nrAttr    : INTEGER; (* SimBase.Attribute *)
      refAttr   : PtrToClientObject; (* read only *)
      chAttr    : CHAR;    (* may be freely used to mark the object;
                             e.g. used by module IdentifyPars to mark
                             parameters for identification. *)
      kind      : MWObj;  (* read only!! *)
      parentM   : Model;  (* read only!! *)
      next      : MObjPtr; (* read only!! *)
      prev      : MObjPtr; (* read only!! *)
      lev       : CARDINAL; (* read only!! *)
    END(*MObjectHeader*);

    (*
       Note: In case of a state variable, its derivative or new
       state, respectively, plus its initial values are not
       among the fields of MObjectHeader; use procedure SVsDeriv
       and GetSVsInits to access them.  Similarily, in case of a
       monitoring variable, the monitoring attributes can only
       be accessed via the routines GetMVsDfltMon and GetMVsCurMon.
     *)



    PROCEDURE MPtrToM(m: ModelPtr): Model;
    PROCEDURE MToMPtr(m: Model): ModelPtr;

    PROCEDURE FirstM(): ModelPtr;
    PROCEDURE FirstSV( m: Model ): MObjPtr;
    PROCEDURE SVsDeriv( objp: MObjPtr ): RealPtr;
    PROCEDURE GetSVsInits( objp: MObjPtr; VAR defaultInit,curInit: REAL);
    PROCEDURE FirstP ( m: Model ): MObjPtr;
    PROCEDURE FirstMV( m: Model ): MObjPtr;
    PROCEDURE GetMVsDfltMon ( objp: MObjPtr;
                              VAR defaultScaleMin,defaultScaleMax: REAL;
                              VAR defaultSf: StashFiling;
                              VAR defaultT: Tabulation;
                              VAR defaultG: Graphing);
    PROCEDURE GetMVsCurMon( objp: MObjPtr;
                            VAR curSf: StashFiling;
                            VAR curT: Tabulation;
                            VAR curG: Graphing);

    PROCEDURE IsSystem(m: ModelPtr): BOOLEAN;
    (*
      Lets you learn whether the model m is a pseudo model
      representing only an ISIS System (see ISIS module
      SysModBase).  Ignore such models, since they are no real
      dynamic models belonging to ModelWorks.  WARNING: Never
      remove any of these models, in particular not the very first
      or you risk to seriously disrupt the functioning of the
      overall system dynamics. Note, however, it is still safe
      to call SimBase.RemoveAllModels.
    *)

    PROCEDURE LastM(): ModelPtr;
    PROCEDURE LastSV( m: Model ): MObjPtr;
    PROCEDURE LastP ( m: Model ): MObjPtr;
    PROCEDURE LastMV( m: Model ): MObjPtr;


  (****************************************)
  (*#####   Removing model objects   #####*)
  (****************************************)

  PROCEDURE RemoveAllSVsOfM (m: Model);
  PROCEDURE RemoveAllPsOfM (m: Model);
  PROCEDURE RemoveAllMVsOfM (m: Model);
  PROCEDURE RemoveAllOfM (m: Model);
  (*
    Efficient removal routines which let you remove model objects
    without having to remove the owning model itself (useful to
    preserve relative positioning of models, yet to efficiently
    remove model objects).
  *)

END SimObjects.

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