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

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

    Module  DiscrSpaces     (Version 1.0)

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

    Purpose   Management of discrete spaces spanned by
              user-defined basis vectors (dimensions).

    Remarks   --


    Programming

      o Design
        Dimitrios Gyalistras      15/04/1998
        Andreas Fischlin          15/04/1998

      o Implementation
        Dimitrios Gyalistras      15/04/1998


    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/05/1998  DG

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


  FROM SYSTEM IMPORT ADDRESS;
  IMPORT DMLanguage;


  (**************************************)
  (*#####   General declarations   #####*)
  (**************************************)

  CONST
    DiscrSpacesOffset         = DMLanguage.userBase + 720;
    allOk                     = DMLanguage.allOk;
    discreteSpaceNotKnown     = DiscrSpacesOffset + 1;
    discreteSpaceNotAvailable = DiscrSpacesOffset + 2;
    atLeastOneDimEleRequired  = DiscrSpacesOffset + 3;
    atLeastOneDimRequired     = DiscrSpacesOffset + 4;
    dimensionDoesNotExist     = DiscrSpacesOffset + 5;
    dimensionUsedMoreThanOnce = DiscrSpacesOffset + 6;
    illegalTuple              = DiscrSpacesOffset + 7;
    (*
      For further error codes returned by this module see
      module TableLists.
    *)

  TYPE
    DiscreteSpace;
    Dimension;
    DiscreteSpaceAttribute     = ADDRESS;
    DimensionAttribute         = ADDRESS;
    DiscreteSpaceRemoveHandler = PROCEDURE( DiscreteSpaceAttribute );
    DimensionRemoveHandler     = PROCEDURE( DimensionAttribute );

  VAR
    unknownDiscreteSpace : DiscreteSpace;  (* read only *)
    unknownDimension     : Dimension;      (* read only *)

  CONST
    identDelim = "|";  (* delimiter used to separate identifiers in a list *)


  (****************************)
  (*#####   Dimensions   #####*)
  (****************************)

  (*----------------------------------------*)
  (*=====   Management of Dimensions   =====*)
  (*----------------------------------------*)

  PROCEDURE CreateDimension( VAR dim     : Dimension;
                             dimId       : ARRAY OF CHAR;
                             eleIds      : ARRAY OF CHAR;
                             VAR resCode : INTEGER );
    (*
      This routine creates a dimension with identifier
      dimId, e.g. "TreeSpecies", and elements as listed
      in eleIds (e.g., eleIds = "fir|oak|...").  Within a
      given dimension each element must be unique, but
      the same element can be used in several dimensions.
      You may create any number of dimensions which can
      then be used to define discrete spaces.
    *)

  PROCEDURE DimensionExists( dimId : ARRAY OF CHAR ): BOOLEAN;

  PROCEDURE GetDimensionId( dim       : Dimension;
                            VAR dimId : ARRAY OF CHAR );

  PROCEDURE NumDimensionEles( VAR dimId : ARRAY OF CHAR ): INTEGER;


  PROCEDURE GetFirstDimension( VAR dimId : ARRAY OF CHAR );
  PROCEDURE GetPrevDimension ( curDimId  : ARRAY OF CHAR;
                               VAR dimId : ARRAY OF CHAR );
  PROCEDURE GetNextDimension ( curDimId  : ARRAY OF CHAR;
                               VAR dimId : ARRAY OF CHAR );
  PROCEDURE GetLastDimension ( VAR dimId : ARRAY OF CHAR );
    (*
      Makes it possible to access all currently
      instantiated dimensions in the sequence they have
      been declared by CreateDimension.  Procedures
      return the empty string if dimension dimId does
      not exist.
    *)

  PROCEDURE DiscardDimension( VAR dim: Dimension );
    (*
      Discards dimension dim.  Note, removal of a
      dimension will cause removal also of all
      discrete spaces that depend from it.
    *)

  PROCEDURE AddDimensionRemoveHandler ( dimId : ARRAY OF CHAR;
                                        rmh   : DimensionRemoveHandler );

  PROCEDURE VoidDimensionRemoveHandler( dimId : ARRAY OF CHAR;
                                        rmh   : DimensionRemoveHandler );
    (*
      Adds (voids) a (previously added) remove handler rmh
      to (from) the dimension dimId.  The remove handler
      rmh is called when an dimension ceases to exist,
      i.e.  when DiscardDimension is called; this occurrs
      at a moment when the dimension's data are still
      intact and all routines (except DiscardDimension)
      from this module are still fully functional.
    *)


  (*------------------------------------------------------*)
  (*=====   Retrieval of information on Dimensions   =====*)
  (*------------------------------------------------------*)

  PROCEDURE GetDimensionEleIds( dimId      : ARRAY OF CHAR;
                                VAR eleIds : ARRAY OF CHAR );
    (*
      Returns in eleIds the identifiers of all elements of
      dimension dimId.
    *)

  PROCEDURE DimensionDim( dimId: ARRAY OF CHAR ): INTEGER;
    (*
      Returns the number of elements in dimension dimId.
    *)

  PROCEDURE DimEleOrd( dimId : ARRAY OF CHAR;
                       eleId : ARRAY OF CHAR ): INTEGER;
    (*
      Returns the order of element eleId in dimension
      dimId (order of first element = 0).  This is the
      inverse of GetDimEle.
    *)

  PROCEDURE GetDimEle( dimId     : ARRAY OF CHAR;
                       eleOrd    : INTEGER;
                       VAR eleId : ARRAY OF CHAR );
    (*
      Returns the identifier eleId of element with order
      eleOrd within dimension dimId.  This is the
      inverse of DimEleOrd.
    *)

  PROCEDURE AttachDimensionAttr( dimId : ARRAY OF CHAR;
                                 da    : DimensionAttribute );

  PROCEDURE DimensionAttr      ( dimId : ARRAY OF CHAR ): DimensionAttribute;
    (*
      Attaches respectively returns the previously
      attached attribute da to the dimension dimId.  An
      attribute is typically a pointer to a client data
      structure associated with the dimension.
    *)


  (*********************************)
  (*#####   Discrete Spaces   #####*)
  (*********************************)

  (*---------------------------------------------*)
  (*=====   Management of Discrete Spaces   =====*)
  (*---------------------------------------------*)

  PROCEDURE CreateDiscreteSpace( VAR spc     : DiscreteSpace;
                                 spcId       : ARRAY OF CHAR;
                                 dimIds      : ARRAY OF CHAR;
                                 VAR resCode : INTEGER );
    (*
      This routine creates a discrete space with
      identifier spcId.  The space is spanned by a list of
      dimensions specified in parameter dimIds.  For
      example, if you have previously defined the two
      dimensions "TreeSpecies" (with elements "fir" and
      "oak") and "Age" (with elements "young" and "old"),
      respectively, calling the above procedure with
      dimIds = "Age|TreeSpecies" will define a
      2-dimensional discrete space which contains all
      possible combinations for "Age" and "TreeSpecies",
      i.e.  the tuples (young,fir), (old,fir), (young,oak)
      and (old,oak).  Note, the same dimension may be used
      only once in one and the same discrete space.
    *)

  PROCEDURE DiscreteSpaceExists( spcId : ARRAY OF CHAR ): BOOLEAN;

  PROCEDURE GetDiscreteSpaceId( spc       : DiscreteSpace;
                                VAR spcId : ARRAY OF CHAR );

  PROCEDURE NumDiscreteSpaceDims( VAR spcId : ARRAY OF CHAR ): INTEGER;


  PROCEDURE GetFirstDiscreteSpace( VAR spcId : ARRAY OF CHAR );
  PROCEDURE GetPrevDiscreteSpace ( curSpcId  : ARRAY OF CHAR;
                                   VAR spcId : ARRAY OF CHAR );
  PROCEDURE GetNextDiscreteSpace ( curSpcId  : ARRAY OF CHAR;
                                   VAR spcId : ARRAY OF CHAR );
  PROCEDURE GetLastDiscreteSpace ( VAR spcId : ARRAY OF CHAR );
    (*
      Makes it possible to access all currently
      instantiated discrete spaces in the sequence they
      have been declared by CreateDiscreteSpace.
      Procedures return the empty string if discrete space
      spcId does not exist.
    *)

  PROCEDURE DiscardDiscreteSpace( VAR spc : DiscreteSpace );
    (*
      Discards the discrete space spc.
    *)

  PROCEDURE AddDiscreteSpaceRemoveHandler ( spcId : ARRAY OF CHAR;
                                            rmh  : DiscreteSpaceRemoveHandler );

  PROCEDURE VoidDiscreteSpaceRemoveHandler( spcId : ARRAY OF CHAR;
                                            rmh  : DiscreteSpaceRemoveHandler );
    (*
      Adds (voids) a (previously added) remove handler rmh to
      (from) the discrete space spcId.  The remove handler rmh is
      called when a discrete space ceases to exist, i.e. when
      DiscardDiscreteSpace is called; this occurrs at a moment
      when the discrete space's data are still intact and all
      routines (except DiscardDiscreteSpace) from this module are
      still fully functional.
    *)


  (*-----------------------------------------------------------*)
  (*=====   Retrieval of information on Discrete Spaces   =====*)
  (*-----------------------------------------------------------*)

  PROCEDURE GetDiscreteSpaceDimIds( spcId      : ARRAY OF CHAR;
                                    VAR dimIds : ARRAY OF CHAR );
    (*
      Returns in dimIds the identifiers of all dimensions
      defining the discrete space spcId.
    *)

  PROCEDURE DiscreteSpaceDim( spcId: ARRAY OF CHAR ): INTEGER;
    (*
      Returns the number of dimensions spanning the
      discrete space spcId.
    *)

  PROCEDURE DimOrd( spcId : ARRAY OF CHAR;
                    dimId : ARRAY OF CHAR ): INTEGER;
    (*
      Inverse of GetDim: returns the order of dimension
      dimId in discrete space spcId (first dimension = 0).
    *)

  PROCEDURE GetDim( spcId     : ARRAY OF CHAR;
                    dimOrd    : INTEGER;
                    VAR dimId : ARRAY OF CHAR );
    (*
      Inverse of DimOrd: returns the identifier dimId of
      dimension with order dimOrd within discrete space
      spcId.
    *)

  PROCEDURE AttachDiscreteSpaceAttr( spcId : ARRAY OF CHAR;
                                     da    : DiscreteSpaceAttribute );

  PROCEDURE DiscreteSpaceAttr      ( spcId : ARRAY OF CHAR ): DiscreteSpaceAttribute;
    (*
      Attaches respectively returns the previously
      attached attribute da to the discrete space spcId.
      An attribute is typically a pointer to a client data
      structure associated with the discrete space.
    *)


  (**************************************)
  (*#####   Management of tuples   #####*)
  (**************************************)

  PROCEDURE IsLegalTuple( spcId   : ARRAY OF CHAR;
                          idTuple : ARRAY OF CHAR ): BOOLEAN;
  (*
    Every point in a discrete space is described by a
    N-tuple of dimElements which is specified by a list
    of N identifiers separated by the special character
    identDelim, e.g.  "old|fir".  This procedure returns
    TRUE if idTuple is a valid tuple for the discrete
    space spcId.
  *)

  PROCEDURE GetFirstTuple( spcId       : ARRAY OF CHAR;
                           VAR idTuple : ARRAY OF CHAR );

  PROCEDURE GetNextTuple ( spcId       : ARRAY OF CHAR;
                           VAR idTuple : ARRAY OF CHAR );
  (*
    These procedures serve subsequently retrieving in
    variable idTuple all tuples that occur in discrete
    space spcId.  Retrieved are, however, only the tuples
    which have not been forbidden by means of procedure
    ForbidTuple exported below.
  *)

  PROCEDURE ForbidTuple ( spc         : DiscreteSpace;
                          idTuple     : ARRAY OF CHAR;
                          VAR resCode : INTEGER );

  PROCEDURE AllowTuple  ( spc         : DiscreteSpace;
                          idTuple     : ARRAY OF CHAR;
                          VAR resCode : INTEGER );
  (*
    By default, all tuples within a discrete space can be
    retrieved with the aid of GetFirstTuple/ GetNextTuple.
    The above procedures serve to forbid resectively
    re-allow retrieving a tuple idTuple in the discrete
    space spc.
  *)

  PROCEDURE TupleAllowed( spcId   : ARRAY OF CHAR;
                          idTuple : ARRAY OF CHAR ): BOOLEAN;
    (*
      Returns TRUE if a given tuple can be retrieved by
      means of procedures GetFirstTuple/GetNextTuple in
      discrete space spcId.
    *)


  PROCEDURE IdToOrd( spcId        : ARRAY OF CHAR;
                     idTuple      : ARRAY OF CHAR;
                     VAR ordTuple : ARRAY OF INTEGER );

  PROCEDURE OrdToId( spcId        : ARRAY OF CHAR;
                     ordTuple     : ARRAY OF INTEGER;
                     VAR idTuple  : ARRAY OF CHAR );
  (*
    A tuple from a discrete space can be represented as an
    array of N ordinal values for the elements of the
    dimensions spanning the space.  The above procedures
    allow you to switch between the identifier and ordinal
    representations of tuples.
  *)

  PROCEDURE GetNthSubString( VAR(*speed-up*) string : ARRAY OF CHAR;
                             n        : INTEGER;
                             VAR subs : ARRAY OF CHAR);
  (*
    Returns in subs the n'th substring found in string,
    assuming substrings are separated by "|" (identDelim).
    This string handling routine is provided for your
    convenience only.
  *)


END DiscrSpaces.

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