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

DEFINITION MODULE RelHandler;

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

    Module  RelHandler     (Version 1.0)

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

    Purpose   Management of n:n-type relations between objects.

    Remarks   Usage of this module is based on terms taken from
              graph-theory.

              - Objects correspond to "nodes", relations correspond to
                "arcs" (ordered pairs of nodes).
              - The sets of nodes and arcs constitute a "directed graph"
                or "digraph".
              - A sequence of nodes is called a "path", a path from a
                node to itself a "cycle".
              - A node (object) x is called "adjacent" to a node y,
                if there is an arc from y to x.

              Literature: .... Chap.7, Graphs and their applications.


    Programming

      o Design
        Dimitrios Gyalistras      14/03/1991

      o Implementation
        Dimitrios Gyalistras      14/03/1991


    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:  06/05/1996  FT

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


  FROM SYSTEM IMPORT ADDRESS;

  TYPE
    Object =
      RECORD
        id  : ADDRESS;
        type: INTEGER;
      END;


  (* ------------------------ Module usage -------------------- *)

  PROCEDURE InitializeRelationHandler( maxObjects: INTEGER );
    (* (Re)Initializes handler able to handle relations between
    "maxObjects" Objects. *)

  PROCEDURE ReleaseRelationHandler;
    (* Releases handler and all allocated memory space. *)



  (* ------------ Digraph definition and modification --------- *)

  PROCEDURE NotifyObject( obj: Object );
    (* Notifies the existence of an object identified by its ident
    "obj.id" AND its type "obj.type", corresponding to a new node.
    Operation has no effect, if the object has been already
    notified. *)

  PROCEDURE IsNotified( obj: Object ): BOOLEAN;
    (* Returns TRUE, if an object has been already notified with
    id="obj.id" AND type="obj.type" *)

  PROCEDURE DenotifyObject( obj: Object );
    (* Denotifies the existence of an object identified by "obj.id"
    AND "obj.type", if such an object exists. All relations from
    other objects to "obj" are removed. *)


  PROCEDURE Relate( obj, toObj: Object );
    (* Adds an arc from "obj" to "toObj" if both parameters denote
    different objects, and if an arc does not already exist. *)

  PROCEDURE Related( obj, toObj: Object ): BOOLEAN;
    (* Returns TRUE if "obj" and "toObj" both exist and an arc
    exists from "obj" to "toObj". *)

  PROCEDURE Unrelate( obj, toObj: Object );
    (* Removes arc from "obj" to "toObj" if such an arc exists. *)



  (* ------------------- Operations on Digraph -----------------*)

  PROCEDURE RelatedTo( obj: ADDRESS; VAR lst: ARRAY OF Object; VAR count: INTEGER );
    (* Returns in "lst" a list of all objects for which "obj" is
    adjacent, in "count" the number of valid elements in "lst". *)

  PROCEDURE AdjacentTo( obj: ADDRESS; VAR lst: ARRAY OF Object; VAR count: INTEGER );
    (* Returns in "lst" a list of all objects adjacent to "obj", in
    "count" the number of valid elements in "lst". *)


  PROCEDURE CircularPaths( startFromObj: ADDRESS;
                           VAR path    : ARRAY OF Object;
                           VAR lgth    : INTEGER ):BOOLEAN;
    (* Returns TRUE if, following all possible paths starting from
    "startFromObj", a circle is encountered, otherwise FALSE. In
    the case of a circularity, "path" will contain the
    objects-sequence constituting the circle and "lgth" its length
    (= the number of valid elements in "path"; maximum returned
    nodes are "HIGH(path)-1", even if actual path is longer).*)



  PROCEDURE CircularGraph( VAR path: ARRAY OF Object; VAR lgth: INTEGER ):BOOLEAN;
     (* Returns TRUE if a circularity exists in current graph.
     "path" and "node:" see above. *)


END RelHandler.