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

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

    Module  TabFunc     (Version 1.0)

      Copyright (c) 1989-2006 by Olivier Roth, Dimitrios Gyalistras, Frank
      Thommen and ETH Zurich.

    Purpose   Interpolate/extrapolate functions
              defined by a table of values.

    Remarks   --


    Programming

    Programming

      o Design
        Olivier Roth              30/08/1989

      o Implementation
        Olivier Roth              30/08/1989
        Dimitrios Gyalistras      20/09/1990
        Frank Thommen             30/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:  09/03/1992  DG

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


  FROM Matrices IMPORT Matrix;


  TYPE
    TabFUNC;
    ExtrapolMode = (lastSlope, horizontally);
    TabFProc = PROCEDURE( VAR TabFUNC );

  VAR
    notExistingTabF: TabFUNC;   (* read only! *)
  (* used to initialize variables of the type TabFUNC *)



  PROCEDURE DeclTabF( VAR  t       : TabFUNC;
                      xx, yy       : ARRAY OF REAL;
                      NValPairs    : INTEGER;
                      modifiable   : BOOLEAN;
                      tabName,
                      xName, yName,
                      xUnit, yUnit : ARRAY OF CHAR;
                      xMin, xMax,
                      yMin, yMax   : REAL );

  (* Allows to declare a function table for later linear interpolation
  (see procedures Yi and Yie).
  Such table functions may be declared modifiable what means that
  they may be edited with a special editor. A new menu "TabFuncs"
  is added to the already existing menus when the first table
  function is declared.
  If the table function already exists, then the user is warned and the
  table is NOT changed.

  Explanations of parameters:
  The variable t is used to identify and update the table function
  values and parameters (therefore don't modify it!). The vector
  xx defines the independent and yy the dependent values of the
  table function being defined. The variable NValPairs has to contain the
  number of elements of the vectors xx and yy which hold a value.
  The table functions may be modified by means of an editor if the
  boolean variable modifiable is set TRUE. For identification and later
  use the table function and the axes variables can be named through the
  variables tabName, xName and yName. The variables xUnit and yUnit
  contain unit descriptor of each axis. The last four parameters (xMin,
  xMax, yMin, yMax) define the valid range for each axis's values. Please
  note that the xx vector must be given sorted ascendingly, otherwise the
  program will halt execution!

  By default table functions are declared with extrapolation mode
  lastSlope. Use procedure DefineExtrapolationMode to change to
  another extrapolation mode.


  Short description of the table function editor:
  ----------------------------------------------
  When a table function is declared a new menu "TabFuncs" is automatically
  added to the already existing menus. This menu offers three commands:
  "Edit/View table function…", "Reset table function…" and
  "Reset all table function".
  The "Edit..." command changes its text according to the types of
  table functions that have sofar been declared:

   "Edit/View table function…": modifiable AND not modifiable table
                                functions have been declared
   "Edit table function…"     : only modifiable table functions have been
                                declared
   "View table function…"     : only not modifiable table functions have
                                been declared

  Selection of the "Edit..." command displays a dialog box in which you
  may select one of the sofar declared tables to edit or view. Pressing the
  "OK" button invokes the table function editor, whereas "Cancel" will lead
  you back to the same situation as before. The table function editor
  will build up a new window titled "Table Function Editor" and show the
  table at the right, a graph of the table at the left and four
  pushbuttons at the bottom of the window. The values of the table may now
  be altered in the corresponding fields or by dragging the circled
  points with the mouse (regular click allows to drag vertically, option-click
  allows to drag horizontally). Please note that the values are checked to be
  in the defined range and that the x-values must be sorted ascendingly. At
  left and at right of the graph a small blue line indicates the direction of
  the extrapolation of the table function.
  If an unmodifiable table function (not marked by a "•" in the list) has been
  chosen, then no circled points appear and the values are not written in
  fields, therefore it's not possible to change any data in these table functions.
  Only one pushbutton appears.
  The following actions take place after a click into a pushbutton:
  Close   : Remove the table function editor window. If any editing action
            has been executed since last saving (Use-pushbutton, see below),
            then you are asked wether you want to use or to discard the chan-
            gings.
  Initial : The initially defined values, i.e. the values used to declare the table
            function, are activated again (can be cancelled).
  Draw    : Update the graph of the table.
  Use     : Store the edited values.
  Const   : The top x-value is copied to all other x-values and the graph redrawn.
            This allows to declare quickly a constant table function.

  Selection of the "Reset..." command displays a dialog box in which you
  may select one of the sofar declared modifiable tables to reset.
  Pressing the "OK" button resets the specified table function to its
  originally defined values. This action does not display any warning messages
  nor is it undoable. The "Cancel" will lead you back to the same situation as
  before whithout doing any resettings.

  Selection of the "Reset all..." command resets all of the sofar declared
  modifiable table functions to its originally defined values. This action
  does neither display any warning messages nor is it undoable. *)


  PROCEDURE DeclTabFM( VAR  t       : TabFUNC;
                       xyVecs       : Matrix;
                       modifiable   : BOOLEAN;
                       tabName,
                       xName, yName,
                       xUnit, yUnit : ARRAY OF CHAR;
                       xMin, xMax,
                       yMin, yMax   : REAL );

  (* the same procedure as DeclTabF but using a matrix to pass
  the data to the module. *)


  PROCEDURE RemoveTabF( VAR t: TabFUNC );

  (* Allows to remove a function table of type TabFUNC and free the
  memory it allocated. If the last table function is removed then
  the menu "TabFuncs" will also be removed. *)


  PROCEDURE SetTabF( t            : TabFUNC;
                     xx, yy       : ARRAY OF REAL;
                     NValPairs    : INTEGER;
                     modifiable   : BOOLEAN;
                     tabName,
                     xName, yName,
                     xUnit, yUnit : ARRAY OF CHAR;
                     xMin, xMax,
                     yMin, yMax   : REAL );

  (* All parameters associated with the table function variable t may be
  changed to another value. This procedure allows to do this. Please
  note that the declared index range of the two vectors xx and yy may not
  be greater than those used for the originally declared and NValPairs must
  match EXACTLY NValPairs used for declaration of the table function! *)


  PROCEDURE GetTabF( t: TabFUNC;
                     VAR xx, yy       : ARRAY OF REAL;
                     VAR NValPairs    : INTEGER;
                     VAR modifiable   : BOOLEAN;
                     VAR tabName,
                         xName, yName,
                         xUnit, yUnit : ARRAY OF CHAR;
                     VAR xMin, xMax,
                         yMin, yMax   : REAL );

  (* All parameters associated the table function variable t may be
  read whith the help of that procedure. *)



  PROCEDURE SetTabFM( t            : TabFUNC;
                      xyVecs       : Matrix;
                      modifiable   : BOOLEAN;
                      tabName,
                      xName, yName,
                      xUnit, yUnit : ARRAY OF CHAR;
                      xMin, xMax,
                      yMin, yMax   : REAL );

  PROCEDURE GetTabFM( t: TabFUNC;
                      VAR xyVecs       : Matrix;
                      VAR modifiable   : BOOLEAN;
                      VAR tabName,
                          xName, yName,
                          xUnit, yUnit : ARRAY OF CHAR;
                      VAR xMin, xMax,
                          yMin, yMax   : REAL );

  (* The matrix versions of the Set/GetTabF procedures with the exception, that the
  dimensions of the new matrix doesn't have to match the dimensions of the originally
  used matrix. For more explanations see above. *)



  PROCEDURE EditTabF ( t: TabFUNC );
  PROCEDURE ResetTabF( t: TabFUNC );
  (* these procedures allow for invoking the tableFunction Editor for a
  specified TabFUNC *)

  PROCEDURE FreezeEditorGraphBounds(VAR t:TabFUNC;
                                      xMin, xMax,
                                      yMin, yMax: REAL);

  (* Allows to fix the extremas of the axes in the graph of the table
  function editor. By default the axes' extremas are adjusted to the
  current maximal and minimal values given by the table function. *)


  PROCEDURE UnfreezeEditorGraphBounds( VAR t:TabFUNC );

  (* Removes the fixing of the axes in the editor. *)



  PROCEDURE DefineExtrapolationMode( VAR t:TabFUNC; extrapolation:ExtrapolMode );

  (* Sets the extrapolation mode of the table t:
      horizontally: extrapolation returns the y value of the first/last defined
                    x/y pair
      lastSlope   : extrapolation is done by elongating the first/last section
                    of the graph.
     By default table functions are declared with extrapolation mode lastSlope. *)


  PROCEDURE ExtrapolationMode( t:TabFUNC ): ExtrapolMode;

  (* Returns the extrapolation mode of the table. *)


  PROCEDURE Yi ( t: TabFUNC; x: REAL ): REAL;

  (* Returns the y value at x defined by the linear interpolation of
  the previously defined table function t (TYPE TabFUNC). NO extrapolation
  is allowed, i.e. the program will halt execution if it should occurr! *)


  PROCEDURE Yie( t: TabFUNC; x: REAL ): REAL;

  (* Returns the y value at x defined by the linear interpolation of
  the previously defined table function t (TYPE TabFUNC). Extrapolation
  is allowed and will return the last defined y values. *)


  PROCEDURE DoForAllTabF( p: TabFProc );
  (* Calls procedure p for all table functions currently declared. Be
  careful when using this procedure, since it allows to access
  also table functions which may not belong to the caller.  *)



END TabFunc.

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