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

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

    Module  SysModBase     (ISIS_Version_1.2)

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

    Purpose   Supports the modeling of structured systems.
              Provides means to declare systems, their
              structure, and all their mathematical properties.

    Remarks   A system may consist of any number of models of
              various types, such as continuous time, discrete
              time, or discrete event models (any mixing
              possible).  Models can consist of any number of
              model objects such as state variables, model
              parameters etc.

              Systems are opaque, abstract objects, not
              accessible via an identifier.  However, models,
              and model objects are identified via unique
              identifiers, where the model identifier forms the
              first part and the object's identifier the second
              part.

              Ex.: "model.stateVar", "m.x", "model.par", "m.K"

              Certain operations on models and model objects
              are restricted and require to be the owner, i.e.
              to know the owning system; thus, for such a
              private access, you have to pass as an actual
              argument the owning system instantiation.  Other
              operations are of a public kind; thus, it is
              sufficient to know just the identifier of a model
              or model object in order to access it.

              A typical public access is the exchange of data
              among models, i.e. the directional linking of a
              model's output variables to particular input
              variables of other models;  however, such a
              coupling is only possible, if a particular model
              object has made some of its data accessible by
              declaring output variable(s).  Note, output
              variables are a particular class of auxiliary
              variables.  IMPLEMENTATION RESTRICTION: Output
              variables have to be computed within the
              procedure "Output" of the parent model, which
              owns the output variable.

              See also companion module SysModDSBase for
              declaring structured model objects.

              See also modules SysDatAccess and SysDatAux.  They
              provide means to manage the numerical data hold by
              model objects.  Typically all data are made
              available in form of so called data frames (see
              module DataFrames).

              This module uses the 'ModelWorks' simulation
              environment to solve models.  The entire ISIS
              software layer is designed such, that it fully
              cooperates with the 'ModelWorks' modules SimBase,
              SimMaster, and SimEvents.

              This module belongs to ISIS
              Integrative Systems Implementation Software.


    Programming

      o Design
        Andreas Fischlin         24/07/1997
        Dimitrios Gyalistras     24/07/1997

      o Implementation
        Andreas Fischlin         16/09/1997


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

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


  FROM SYSTEM IMPORT ADDRESS;

  FROM DMLanguage IMPORT userBase;
  FROM DMStrings IMPORT String;

  IMPORT SimEvents;


  (************************************************)
  (*#####   Constants, Types and Variables   #####*)
  (************************************************)

  (* Error constants: sysModBaseErrOffset = DMLanguage.userBase + 300 .. 350-1 *)

  TYPE
    IDENT = ARRAY [0..63] OF CHAR;
    MObjVar = REAL;


  TYPE
    System;
    ChildSystem = System;

    Model       = IDENT;
    ModelKind   = (pseudo, static, IORelation, DESS, SQM, DEVS);

    ModelObject = IDENT;
    MObjType    = ( stateVar, derivative(*DESS*), newStateVar(*SQM (or DEVS)*),
                    modParam, inVar, outVar, auxVar );
    (*
      stateVar    - state variables (DESS, SQM, DEVS)
      derivative  - variable functioning as derivative (DESS) or
      newStateVar - new state variable (SQM, DEVS)
      modParam    - model parameter functioning as constant
                    during model solving (may be present in all model kinds)
      inVar       - input variable varying in time but depending
                    only on variables external to the owning model,
                    such as the independent variable (e.g. time) or
                    an output from another model
      outVar      - output variable varying in time and depending
                    only on stateVar, modParam, or auxVar (but not
                    on inVar, implementation restriction as a
                    consequence of modular modeling). They are the
                    only variables which may be accessed, i.e. used as inputs,
                    by another model (Note, all other variables are invisible
                    from the outside of the owning model).
      auxVar      - all remaining variables only used internally of
                    the model

      Note, any variable or constant must belong uniquely to a particular
      model object type.  The following hierarchical classification
      is valid, depending on systems theoretical criterias:

        systems theoretical criterias                class of model object
        ------------------------------------------------------------------

        constant                                     => modParam

        variable    defines state                    => stateVar

                    functions as
                    derivative or
                    new state                        => derivative
                                                        or newStateVar

                    functions as    functions
                    intermediate    as input         => inVar
                    auxiliary
                    variable

                                    functions as
                                    output           => outVar

                                    none of the
                                    above            => auxVar
    *)

    DataAccess   = (private, public);
    (*
      Generally it is possible to assign data to or retrieve data
      from any model or model object via the modules SysDatAccess
      and/or SysDatAux.  DataAccess gives the modeler control
      over the access to models or model objects during such
      operations.  If the model or model object is private, no
      such operations can succeed, but if the object is declared
      as being public, data assigning or retrieving operations
      from modules SysDatAccess or SysDatAux are always
      successful (given of course identifiers match; for matching
      rules see module DataFrames).  DataAccess can be specified
      separately for assignment (write) or retrieval (read)
      access.

      By default models and model objects are private.  However,
      there is an important exception available.  If the owning
      system is properly passed as an actual argument, data
      assignment or retrieval is possible even to private models
      or model objects.  The parameter parent system of type
      System serves then as a key unlocking the access to the
      private object.  Since the owner of a model or model object
      always knows the parent system, the owner has exclusive
      access rights.  Yet, the owner can still allow access to
      other clients, e.g.  by making the key available to others,
      e.g.  by exporting the parent system.  Note, in all the
      cases the control remains with the owner.

      REMARK: Note, public models and model objects are visible
      for data assignment, typically via data frames, without
      having to know the owning system, and for data retrieval.
      Thus public model objects could be misused for linking
      purposes.  This is NOT (!) the purpose of public model
      objects, since "publishing" a model object has no systems
      theoretical meaning.  Always use routine EstablishLink (see below)
      for properly linking submodels!!
            DataAccess only regulates the accessibility of the
      data and is safe in all cases, where the public objects can
      have no effect on the dynamics of the system under study.
      Thus "Publishing" model objects mainly serves merely
      monitoring purposes of objects, e.g.  for programming a
      customized user interface or allowing for parameterless,
      free data assignment via data frames in uncritical cases
      (see also module SysDatAccess).  Small models may "publish"
      all is objects, e.g.  to assign data via data frames by
      using a general purpose menu command of a preprogrammed
      user interface (for an example of this see "Simulation
      Session" of the "RAMSES Shell").  Then the user interface
      needn't know the owning system.  However, for complex
      systems consisting of several subsystems and models it is
      highly recommended to keep as many models and model objects
      private as possible.  This is the main reason why all
      models and model objects declared by this module are by
      default private.
    *)

    StateVar    = MObjVar;
    Derivative  = MObjVar;
    NewStateVar = MObjVar;
    Parameter   = MObjVar;
    InVar       = MObjVar;
    OutVar      = MObjVar;
    AuxVar      = MObjVar;
    StateTransition = SimEvents.StateTransition;

    AtLinkEstabProc    = PROCEDURE ( String ); (* outVarQualIdent|inVarQualIdent *)
    AtLinkBreakProc    = PROCEDURE ( String ); (* outVarQualIdent|inVarQualIdent *)

    Condition          = PROCEDURE (): BOOLEAN;

    AnyAttribute       = ADDRESS;
    ModelAttribute     = AnyAttribute;
    MObjAttribute      = AnyAttribute;
    ModelAttrProcedure = PROCEDURE( ModelAttribute );
    MObjAttrProcedure  = PROCEDURE( MObjAttribute );


  VAR
    unknownSystem      : System;         (* read only *)
    unknownChildSystem : ChildSystem;    (* read only *)
    unknownModel       : Model;          (* read only *)
    unknownMObj        : ModelObject;    (* read only *)
    unknownModelAttr   : ModelAttribute; (* read only *)
    unknownMObjAttr    : MObjAttribute;  (* read only *)
    undefMObjVar       : MObjVar;        (* read only *)
    anyLinkPair        : String;         (* read only *)



  (*******************************)
  (*#####   Invoking ISIS   #####*)
  (*******************************)

  PROCEDURE InvokeISIS ( atStartUp: PROC );
    (*
      Invokes ISIS by activating her standard simulation environment
      and executing atStartUp.  Procedure atStartUp is called as the
      very first routine and a soon as the standard simulation
      environment has been activated (in particular before any
      preparation routines are executed, see ISIS module
      SysStructure).  Procedure atStartUp is typically used to
      extend the simulation environment, e.g.  to load some
      numerical data, by calling a specific about routine, or by
      adding some custom menus.  IMPLEMENTATION RESTRICTION: ISIS
      calls 'ModelWorks' as her standard simulation environment (see
      also procedure RunSimEnvironment from module SimMaster).
    *)



  (***********************************)
  (*#####   Declaring Systems   #####*)
  (***********************************)


  PROCEDURE DeclSystem   ( VAR s: System; sysName: ARRAY OF CHAR );

  PROCEDURE DeclChildSystem ( parentName: ARRAY OF CHAR;
                              VAR s: ChildSystem; sysName: ARRAY OF CHAR );
    (*
      Systems are typically identified with the abstracted type
      System.  This type allows the modeller to control the
      instantiation of any models or model objects belonging to
      a particular system.  sysName has to be unique within the
      scope of all currently declared systems and must not be
      the empty string.  Note, sysName is used to identify a
      particular system, e.g.  a parent when declaring children
      systems; thus separate modules may reference a parent
      without having to import the parent's opaque variable of
      type System.  Normally, a system will be listed within the
      I/O-windows of the simulation environment (use procedure
      HideSystem from this module to avoid this).  Children can
      also function as parents, allowing for a hierarchy of
      nested systems to any level of nesting.  A parent owns all
      its children and any objects the children may own, e.g.
      children systems or dynamic models, their model objects etc.
      NOTE: DeclSystem and DeclChildSystem are not effective if called
      during the termination of a subprogram level (cf.  procedure
      LevelIsTerminating from module DMSystem).
    *)

  PROCEDURE SystemExists ( s: System ): BOOLEAN;

  PROCEDURE UndeclSystem ( VAR s: System );
    (*
      If s is a parent system, UndeclSystem undeclares all
      children (over any level of hierarchy) and all involved
      models, model objects, model attributes, and model object
      attributes (calls client installed, optional
      atUndeclModel and/or atUndeclMObj procedures of type
      ModelAttrProcedure or MObjAttrProcedure) owned by a
      system.
    *)



  (**********************************)
  (*#####   Declaring Models   #####*)
  (**********************************)


  PROCEDURE DeclModel   ( s                    : System;
                          modelIdent           : ARRAY OF CHAR;
                          kind                 : ModelKind;
                          dynamicOrDeclDynamic : PROC;
                          initialize           : PROC;
                          input                : PROC;
                          output               : PROC;
                          terminate            : PROC;
                          about                : PROC);
    (*
      In case of DESS and SQM models procedure dynamicOrDeclDynamic is
      the procedure defining the model dynamics, i.e.  the model
      equations.  In all other cases, in particular if the model is of
      kind DEVS, pass as actual argument a procedure which calls
      SetDEVSDynamic (see below) or make sure that immediately after
      returning from this procedure procedure SetDEVSDynamic is
      called.  Implementation restriction: In case you disrupt above
      described sequence of procedure calls, a model of types
      'pseudo', 'static', 'IORelation', or 'DEVS' will not be declared
      at all.
      NOTE: DeclModel is not effective if called during the termination
      of a subprogram level (cf.  procedure LevelIsTerminating from
      module DMSystem).
    *)




  PROCEDURE SetDEVSDynamic(s          : System;
                           modelIdent : ARRAY OF CHAR;
                           stfcts     : ARRAY OF StateTransition);
    (*
      To be called from within dynamicOrDeclDynamic or
      immediately after having called DeclModel to complete the
      declaration of the DEVS model modelName.  It defines the
      state transition functions associated with modelName.
      WARNING: If not called from within dynamicOrDeclDynamic or
      right after DeclModel, this procedure is not functional.
      NOTE: SetDEVSDynamic is not effective if called during the
      termination of a subprogram level (cf.  procedure
      LevelIsTerminating from module DMSystem).
    *)



  PROCEDURE NoDynamic;
  PROCEDURE NoInitialize;
  PROCEDURE NoInput;
  PROCEDURE LinkedInput; (* use it if all inputs are directly linked to outputs *)
  PROCEDURE NoOutput;
  PROCEDURE NoTerminate;
  PROCEDURE NoAbout;
  PROCEDURE DoNothing;

  PROCEDURE ModelExists ( modelIdent: ARRAY OF CHAR ): BOOLEAN;
  PROCEDURE UndeclModel ( s: System; modelIdent: ARRAY OF CHAR );
  PROCEDURE UndeclAllMs ( s: System );




  (*****************************************)
  (*#####   Declaring Model Objects   #####*)
  (*****************************************)

  PROCEDURE MakeMObjQualifIdent  ( modelIdent        : ARRAY OF CHAR;
                                   mObjIdent         : ARRAY OF CHAR;
                                   VAR mObjQualIdent : ARRAY OF CHAR );

  PROCEDURE SplitMObjQualifIdent ( mObjQualIdent     : ARRAY OF CHAR;
                                   VAR modelIdent    : ARRAY OF CHAR;
                                   VAR mObjIdent     : ARRAY OF CHAR );


  PROCEDURE DeclMObj ( s             : System;
                       mObjQualIdent : ARRAY OF CHAR;
                       objType       : MObjType;
                       VAR obj       : MObjVar );

    (*
      State variables, derivatives or new state variables have all to be
      declared consistently by means of this procedure.  If you declare a
      state variable to belong to a DESS, this module expects you to
      declare also the associated derivative (in any sequence).  The two
      model obejcts share the first part of the qualified identifier.  The
      derivative is characterized by having a predefined postfix added at
      the end of the name.  The following rules apply:

      Model type    Associated model object type    Postfix
      ----------    ----------------------------    -------
      DESS          Derivative                      "Dot" or "_Dot"
      SQM           NewStateVar                     "New" or "_New"
      DEVS          none or NewStateVar             optional declaration or
                                                    "New" or "_New"

      IMPORTANT NOTE: If names don't match or no paired calls to DeclMObj
      have been properly made, i.e.  a state variable is declared without
      the corresponding derivative or new state variable, any simulations
      involving numerical integration or solving of a SQM model will
      fail!!!  The declaration of new state variables is optional only in
      the case of DEVS.
      NOTE: DeclMObj is not effective if called during the termination
      of a subprogram level (cf.  procedure LevelIsTerminating from
      module DMSystem).
    *)

  PROCEDURE MObjExists  ( mObjQualIdent: ARRAY OF CHAR): BOOLEAN;
  PROCEDURE UndeclMObj( s: System; mObjQualIdent: ARRAY OF CHAR );
  PROCEDURE UndeclAllMObj( s: System; modelIdent: ARRAY OF CHAR );
    (*
      Efficient routine to remove all model objects belonging to
      the model denoted by modelIdent.  Note, it also removes all
      structured model objects which belong to the model (see
      module SysModDSBase).
    *)


  (****************************************************)
  (*#####   Declaring Structured Model Objects   #####*)
  (****************************************************)


  (*
    The RAMSES model base as supported by this module allows to declare
    any type of data structure as a so called structured model object.
    The use of this functionality is optional and would make this
    module unnecessary large.  Thus see the companion module
    SysModDSBase for this feature.
  *)


  (********************************************************************)
  (*#####   Controlling DataAccess of Models and Model Objects   #####*)
  (********************************************************************)


  PROCEDURE SetDataAccess( s                         : System;
                           modelIdentOrmObjQualIdent : ARRAY OF CHAR;
                           readDA                    : DataAccess;
                           writeDA                   : DataAccess );

  PROCEDURE GetDataAccess( modelIdentOrmObjQualIdent : ARRAY OF CHAR;
                           VAR readDA                : DataAccess;
                           VAR writeDA               : DataAccess );

  PROCEDURE SetDataAccessForAllMObjs( s          : System;
                                      modelIdent : ARRAY OF CHAR;
                                      readDA     : DataAccess;
                                      writeDA    : DataAccess );

  PROCEDURE SetDataAccessForAllMs( s       : System;
                                   readDA  : DataAccess;
                                   writeDA : DataAccess );


  PROCEDURE SetDataAccessForSystem( s       : System;
                                    readDA  : DataAccess;
                                    writeDA : DataAccess );



  (**************************************************)
  (*#####   Linking Subsystems and Submodels   #####*)
  (**************************************************)

  (*-------------------------------------*)
  (*=====   Vector & Scalar Links   =====*)
  (*-------------------------------------*)

  PROCEDURE EstablishAllLinks;
  PROCEDURE BreakAllLinks;
    (*
      Establishes or breaks all links between output and input
      variables currently present in all systems.  EstablishAllLinks
      connects all input variables (inVar) to an output variable
      (outVar) if their identifiers match and all links for which
      DeclLink has been called.  Note, in the first case a match is
      given if merely the unqualified identifiers are identical,
      since the model identifiers typically differ.  E.g.  the
      outVarQualIdent "outGenModel.Evapotranspiration" would match
      the inVarQualIdent "inUsingModel.Evapotranspiration" hereby
      providing a link.  After a call to EstablishAllLinks any
      computations done in the procedure Input of the model
      "inUsingModel" using the input variable
      "inUsingModel.Evapotranspiration" would then be done with the
      needed values as computed in a procedure Output of the model
      "outGenModel".  These routines are typically called within a
      procedure Initialize of a model, or by a master module, or the
      user via a user interface.
    *)

  (*----------------------------*)
  (*=====   Scalar Links   =====*)
  (*----------------------------*)

  PROCEDURE DeclLink( outVarQualIdent : ARRAY OF CHAR;
                      inVarQualIdent  : ARRAY OF CHAR);
    (*
      Declares a link between the output named outVarQualIdent and
      the input variable named inVarQualIdent.  Once declared,
      EstablishAllLinks or an explicit call to EstablishLink
      actually establishes the link.  The declaration does not
      require the involved model objects to exist.
    *)

  PROCEDURE EstablishLink( outVarQualIdent : ARRAY OF CHAR;
                           inVarQualIdent  : ARRAY OF CHAR);
  PROCEDURE BreakLink    ( outVarQualIdent : ARRAY OF CHAR;
                           inVarQualIdent  : ARRAY OF CHAR);
    (*
      Similarily to EstablishAllLinks but establishes (or breaks) a
      particular link between the output (outVarQualIdent) and input
      variable (inVarQualIdent).  EstablishLink implicitely calls DeclLink.
      A link can be
      established only between a model object which has really been
      declared as OutVar or InVar by the respective owning
      subsystem/model (see above routine DeclMObj).  EstablishLink
      may be called multiple times to reestablish the same link.
      NOTE: EstablishLink is not effective if called during the
      termination of a subprogram level (cf.  procedure
      LevelIsTerminating from module DMSystem)
    *)

  PROCEDURE LinkExists( outVarQualIdent : ARRAY OF CHAR;
                        inVarQualIdent  : ARRAY OF CHAR): BOOLEAN;
    (*
      Returns wether the link between the output named
      outVarQualIdent and the input variable named inVarQualIdent
      has been declared implicitely or explicitely (see also
      LinkEstablished to test for the actual establishment of the
      link).
    *)

  PROCEDURE LinkEstablished( outVarQualIdent : ARRAY OF CHAR;
                             inVarQualIdent  : ARRAY OF CHAR): BOOLEAN;
    (*
      Returns wether the link between the output (outVarQualIdent)
      and the input variable (inVarQualIdent) is currently
      established.  LinkEstablished implies of course LinkExists.
    *)

  PROCEDURE AddLinkHandlers(  outVarQualIdent : ARRAY OF CHAR;
                              inVarQualIdent  : ARRAY OF CHAR;
                              atLinkEstablish : AtLinkEstabProc;
                              atLinkBreak     : AtLinkBreakProc );
    (*
      Allows to attach particular handlers, i.e.  procedures
      atLinkEstablish or atLinkBreak, for the individual link as
      specified by the outVar identifier 'outVarQualIdent' and inVar
      identifier 'inVarQualIdent'.  If the specified link is
      established (EstablishAllLinks, EstablishLink) or broken
      (BreakAllLinks, BreakLink) or the involved output or input
      variable ceases to exist (e.g.  owner calls UndeclMObj,
      UndeclModel, or UndeclSystem), the client subsystem/model is
      notified by a call to procedure atLinkEstablish or atLinkBreak,
      respectively.  AddLinkHandlers requires the link to have been
      declared previously or all required model objects to exist.  In
      the latter case, AddLinkHandlers implicitely declares the link.

      Handler atLinkEstablish is called right after the link has been
      established and the involved inputs have received the wanted
      outputs.

      Handler atLinkBreak is called right after the link has been
      broken, but early enough so that all involved objects do still
      exist and operations on them (except undeclaring) are fully
      functional.  Moreover, in the latter case note that the involved
      input has already been set to UndefREAL (from module
      DMConversions) before atLinkBreak is called, allowing for a
      redefinition of the input by atLinkBreak; e.g.  by assigning a
      constant value to the inVar, transforming it into a model
      parameter or any other action like activating a IO-Relation or
      even to establish another link etc.

      Hints: You may call AddLinkHandlers multiple times for the same
      handlers without penalty (if identical, handler will still be
      installed only once).  Use read-only variable anyLinkPair when
      calling atLinkEstablish or atLinkBreak yourself.

      NOTE: This routine is not effective if called during the
      termination of a subprogram level (cf.  procedure
      LevelIsTerminating from module DMSystem)
    *)

  PROCEDURE VoidLinkHandlers( outVarQualIdent : ARRAY OF CHAR;
                              inVarQualIdent  : ARRAY OF CHAR;
                              atLinkEstablish : AtLinkEstabProc;
                              atLinkBreak     : AtLinkBreakProc );
    (*
      VoidLinkHandlers reverts the effect of AddLinkHandlers and
      is typically called by the inputting subsystem/model when it
      is no longer interested in a particular link.
      atLinkEstablish and atLinkBreak must be both the same
      procedures which have been passed as actual arguments while
      calling AddLinkHandlers.  After a successful call to
      VoidLinkHandlers, neither atLinkEstablish nor atLinkBreak
      will be called in the event the involved output or input
      variables cease to exist or the link is otherwise affected
      (e.g.  by procedures EstablishAllLinks, BreakAllLinks,
      EstablishLink, or BreakLink).  Hint: Use read-only variable
      anyLinkPair when calling atLinkEstablish or atLinkBreak
      yourself.
    *)

  PROCEDURE IgnoreLinkEvent( idents: String );
    (*
      Use this procedure to pass as actual argument when
      calling AddLinkHandlers for one of the formal arguments
      atLinkEstablish or atLinkBreak in case you wish to ignore
      a link event.
    *)

  PROCEDURE UndeclLink( outVarQualIdent : ARRAY OF CHAR;
                        inVarQualIdent  : ARRAY OF CHAR);
    (*
      Undeclares the link between the output named outVarQualIdent
      and the input variable named inVarQualIdent.  In case it is
      currently established, the link is broken by also calling any
      possibly involved link break handlers.
    *)



  (**********************************************************************)
  (*#####   Constraints of Model Objects and Among Model Objects   #####*)
  (**********************************************************************)

  (*--------------------------------------*)
  (*=====   Individual Constraints   =====*)
  (*--------------------------------------*)

  PROCEDURE LimitMObjsRange(s : System; mObjQualIdent : ARRAY OF CHAR;
                            min,max: REAL);
    (*
      Sets for model object with identifier mObjQualIdent the
      range [min..max] within which the model object is valid.
      E.g.  if a model parameter is a probability you can call
      for it LimitMObjsRange (s,"m.p",0.0,1.0).  Another
      example: Call LimitMObjsRange (s,"m.sv",0.0,MAX(REAL)) to
      constrain a state variable "m.sv" to positive values.
      Consequently, any operations performed by this module or
      the modules SysDatAccess and/or SysDatAux will ensure
      that the involved model object has always a valid value
      falling within this range.  Range errors, e.g.  while
      assigning data from a data frame, will be produced
      according to the current preferences of the package (see
      module SysDatAux routine SetSDAPreferences and parameter
      packageErrMode).
    *)

  PROCEDURE GetMObjsRange(mObjQualIdent : ARRAY OF CHAR;
                          VAR min,max: REAL);
    (*
      Allows to learn about the range constraints currently
      imposed on model object denoted by identifier
      mObjQualIdent.  In case routine LimitMObjsRange has
      never been called for the model object, the routine
      returns the range [MIN(REAL) ..  MAX(REAL)].  In case the
      model object doesn't exist, the range [UndefREAL() ..
      UndefREAL()] from module DMConversions is returned.
    *)


  (*-----------------------------------------------------------*)
  (*=====   Constraints Involving Several Model Objects   =====*)
  (*-----------------------------------------------------------*)

  PROCEDURE AssertConstraint(c: Condition; descr: ARRAY OF CHAR);
  PROCEDURE NullifyConstraint(c: Condition);
    (*
      Use AssertConstraint to add a constraining condition for
      a global consistency of data among all currently declared
      model objects and their data.  A condition may involve
      any number of model objects.  A simulation run will only
      be possible, if all asserted conditions are satsified.
      Otherwise the underlining run time system of this module
      will refuse to perform a simulation, which is usually
      anyway meaningless or may even crash your model
      definition program.  For instance you can add a condition
      for a probability vector used by a Markov process, where
      all elements, typically declared as model objects of type
      model parameter, have to add up to the sum of 1.  The
      parameter descr describes the condition and may contain
      any information which helps you to identify the
      particular condition; e.g.  pass "p1 + p2 + p3 = 1" for a
      condition procedure which calculates this sum.  If the
      condition is tested and fails, this string will be
      diplayed to explain to the user the reason for the
      failure.  Use NullifyConstraint to remove a previously
      added condition from the set of currently know
      conditions.
    *)

  PROCEDURE ConstraintAsserted (c: Condition): BOOLEAN;
    (*
      Returns wether constraining condition c has been asserted
    *)

  PROCEDURE GetConstraintDescr (c: Condition; VAR descr: ARRAY OF CHAR);
    (*
      Returns for constraining condition c its descriptor in
      descr.  Returns the empty string if c has never been
      asserted.
    *)

  PROCEDURE Equal(x,y: REAL): BOOLEAN;
    (*
      Returns wether two values are equal or differ at most by
      a small amount epsilon (ABS(x-y)<=epsilon).  The
      parameter epsilon is computed in a machine dependent way
      and represents the absolute minimum difference between
      two real variables as defined by the floating point
      precision of the machine on which this module currently
      executes.  This routine may be useful to implement
      conditions to be declared via procedure AssertConstraint.
      Ex.: PROCEDURE MyCond(): BOOLEAN;
           BEGIN RETURN Equal(p1+p2+p3,1.0) END MyCond;
    *)

  PROCEDURE AllConditionsMet(): BOOLEAN;
    (*
      Returns wether all currently asserted conditions are
      satisfied (see routine AssertConstraint).  It displays
      for every failing constraint a message (Errors.Info)
      together with its descriptor (as specified while calling
      AssertConstraint).  It is recommended to call
      CheckForErrors after having called this routine to make
      sure, you actually learn about the failing conditions
      (depends on current mode and message display preference;
      see also explanations of CheckForErrors).  If there is at
      least one system installed, this routine is installed in
      'ModelWorks' via routine InstallStartConsistency from
      module SimMaster.
    *)


  (***************************************************)
  (*#####   Model and Model Object Attributes   #####*)
  (***************************************************)


  PROCEDURE SetModelAttr ( s             : System;
                           modelIdent    : ARRAY OF CHAR;
                           attr          : ModelAttribute;
                           atUndeclModel : ModelAttrProcedure );

  PROCEDURE ModelAttr ( s          : System;
                        modelIdent : ARRAY OF CHAR ): ModelAttribute;


  PROCEDURE SetMObjAttr ( s             : System;
                          mObjQualIdent : ARRAY OF CHAR;
                          attr          : MObjAttribute;
                          atUndeclMObj  : MObjAttrProcedure );

  PROCEDURE MObjAttr ( s             : System;
                       mObjQualIdent : ARRAY OF CHAR ): MObjAttribute;

  PROCEDURE DummyAtUndeclProc(a: AnyAttribute);



  (********************************)
  (*#####   Erorr Handling   #####*)
  (********************************)

  PROCEDURE CheckForErrors;
    (*
      Checks for the presence of some errors possibly
      encountered during past routines from this module.
      Depending on the current error mode of the entire package
      (see procedure SetSDAPreferences from modules SysDatAux
      and/or SimDatAux for argument packageErrMode) any display
      of errors might be currently suppressed; errors will then
      be stored in memory for later display.  Call
      CheckForErrors to make the errors visible in case there
      should have been some encountered.  This routine does
      nothing if no errors are currently held in memory.  For
      more details see also module Errors.  You typically call
      this routine after having called a series of routines
      from this module, like model and model object declaring
      routines or procedure AllConditionsMet.  WARNING: The
      latter is highly recommended or you may never learn
      about the failure of some routines, e.g.  identifier
      clashes etc., in the default mode of the package.
    *)


  (**********************************)
  (*#####   System Utilities   #####*)
  (**********************************)

  PROCEDURE DescribeSystem( s: System );
    (*
      Generates on the current output window (see module DMWindowIO)
      a description of the system according to current preferences.
      Note, ISIS uses this routine to display information about a
      system when calling the about function (button '?') in the
      I/O-window 'Models' of the standard simulation environment of
      ISIS.
    *)

  PROCEDURE HideSystem( s: System );
    (*
      Call procedure HideSystem to hide any system from the list
      of items shown in the I/O windows of the simulation
      environment.  IMPLEMENTATION RESTRICTION: This routine is
      without effect if called for the very first system
      declared, since this system serves as a dynamic 'ModelWorks'
      model which implements the global systems dynamics of all
      currently declared systems and models.  Thus it should
      remain present at all times or linking dependent data flow
      (see e.g.  procedure EstablishLink from this module) among
      subsystems may fail entirely.
    *)

END SysModBase.

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