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

DEFINITION MODULE CAMonit;

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

    Module  CAMonit     (Version 1.0)

      Copyright (c) 1991-2006 by Thomas Nemecek and ETH Zurich.

    Purpose   Monitor cellular automatons in windows and on files.

    Remarks   The monitoring data structure is associated with
              the variable caMod and can be referenced with
              this variable.  It is automatically removed
              if the variable caMod is removed.

              CAUTION:
              do not overwrite the remove procedure
              associated with caMod since this procedure is
              used to remove the monitoring data structure.

              Usage
                1. declare the cellular automaton model
                   with CAModBase.DeclCAMod
                2. declare the CA-monitoring with CAMonit.DeclCAMonit
                3. initialize the needed attributes with
                   CAMonit.SetCALegendDescrs (graphical display
                   and file output) and CAMonit.SetDisplayAttr
                4a.For graphical display:
                    - initialize the monitoring with
                      CAMonit.InitCADisplay
                    - use DisplayCA, DisplayCell and
                      DisplayLegend for graphical monitoring
                4b.For file output:
                    - use DumpCA

               Limitations:  A maximum of 128 states can be
               labelled and displayed.

    Programming

      o Design
        Thomas Nemecek            23/04/1991

      o Implementation
        Thomas Nemecek            23/04/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:  21/05/2002   FG

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


(*. FROM CAMonit    IMPORT
     Str255,Str63,DeclCAMonit,GetCAMonit,RemoveCAMonit,InitCADisplay,TermCADisplay,
     SetCALegendDescrs,GetCALegendDescrs,SetDisplayAttr,GetDisplayAttr,DisplayCA,
     DisplayCell,DisplayLegend,SetTimeDisplay,GetTimeDisplay,DumpCA,CAMonitDeclared;   .*)

  FROM CAModBase      IMPORT CAMod;
  FROM DMFiles        IMPORT TextFile;
  FROM DMWindows      IMPORT Window, RectArea;
  FROM DMWindIO       IMPORT Pattern, Color;

  TYPE
    Str255 = ARRAY [0..255] OF CHAR;
    Str63  = ARRAY [0..63]  OF CHAR;


  (*******************************)
  (* Management of CA monitoring *)
  (*******************************)
  PROCEDURE DeclCAMonit  (caMod: CAMod;     title, subTitle: Str255);
  PROCEDURE GetCAMonit   (caMod: CAMod; VAR title, subTitle: Str255);
  PROCEDURE RemoveCAMonit(caMod: CAMod);
  PROCEDURE CAMonitDeclared(caMod: CAMod): BOOLEAN;



  (*******************************)
  (* Management of CA display    *)
  (*******************************)
  PROCEDURE InitCADisplay(caMod:                CAMod;
                          w:                    Window;
                          caArea, legendArea:   RectArea;
                          withLines:            BOOLEAN);
    (* prepares the window for output. The monitoring must be
       installed previously by call of DeclCAMonit *)

  PROCEDURE TermCADisplay(caMod: CAMod);
    (* Termination of window output, the CA-graph is cleared.
       !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
       ! The whole window is cleared in the current version!
       !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! *)

  PROCEDURE SetCALegendDescrs  (caMod: CAMod;     legendDescrs: ARRAY OF Str63);
  PROCEDURE GetCALegendDescrs  (caMod: CAMod; VAR legendDescrs: ARRAY OF Str63);
    (*
      assigns the descriptor strings of the different states,
        which are displayed at the right of the graph,
        resp. written after the data matrix on the file
   *)


  PROCEDURE SetDisplayAttr (caMod:      CAMod;
                            colors:     ARRAY OF Color;
                            patterns:   ARRAY OF Pattern;
                            symbols:    ARRAY OF CHAR);

  PROCEDURE GetDisplayAttr (caMod:      CAMod;
                        VAR colors:     ARRAY OF Color;
                        VAR patterns:   ARRAY OF Pattern;
                        VAR symbols:    ARRAY OF CHAR);

  PROCEDURE DisplayCA    (caMod: CAMod;  time: REAL);
    (* display of whole CA state, faster than subsequent calls of DisplayCell! *)
  PROCEDURE DisplayCell  (caMod: CAMod;  x,y: INTEGER;  time: REAL);
    (* display of the state of a cell of the current CAMod. *)
  PROCEDURE DisplayLegend  (caMod: CAMod);

  PROCEDURE SetTimeDisplay  (    dispT: BOOLEAN);
  PROCEDURE GetTimeDisplay  (VAR dispT: BOOLEAN);  (* default is TRUE *)

  (*****************)
  (* File output   *)
  (*****************)
  PROCEDURE DumpCA (caMod: CAMod; VAR f: TextFile; time: REAL; writeLegend, useStatsCond: BOOLEAN);
    (* writes the current state of the CA to the cuurent position on the file.
       If useStatsCond=TRUE, the current statistcs conditions from module
       CAModBase is used and only those states are written to the file, for which the
       current statistcs condition procedure yields the value TRUE. *)
END CAMonit.