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

DEFINITION MODULE SimDeltaCalc;

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

    Module  SimDeltaCalc     (MW_V3.0)

      Copyright (c) 1991-2006 by Olivier Roth and ETH Zurich.

    Purpose   Compute and handle deviations (Δ) of simulations
              compared to e.g. observed data series.

    Remarks   This module is typically used to compute a performance
              index for identification or validation.

              This module works together with module "SimGraphUtils",
              i.e. the procedures DeclDispData or DeclDispDataM must
              be used to install the reference data to which the
              delta's (d) should be computed.

              This module is part of the optional client interface of
              'ModelWorks', an interactive Modula-2 modelling and
              simulation environment.


    Programming

      o Design
        Olivier Roth              15/10/1991

      o Implementation
        Olivier Roth              17/10/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:  15/10/1991  OR

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


  (* The problem:

   Y  |                  v
      |                 xxxxxx
      |                x    v xxxxxxx
      |         v     x              xx
      |xxxxxx        x    v            xx
      |      xx     x                    xx
      |        xx  x
      |          xx
      |-----|-----|-----|-----|-----|-----| ->t
      0     1     2     3     4     5     6
               A     B     C

      Validation statistics example (see fig. above):
      Y is e.g. a state variable, x = simulated, v = observed or
      measured; t stands for an independent variable e.g. time.

      A series of n (v,t) points has to be declared by DeclDispData
      from module SimGraphUtils. As a goodness of fit criterion we
      look for the vertical distances (d) of simulated (linearly
      interpolated) results (x) and the observed data (v).
      There may ocurr 3 cases (see fig. above): A) one observed
      data point falls into the last simulated time interval;
      B) no observed data point was encountered during last time
      interval; C) many observed data points were encountered during
      the last time interval.  The procedures "AccuDelta" and
      "GetDelta" keep track on the last independent variable
      and look ahead to the next element in the data array if a new
      Δ has to be computed.  This requires correct sorting of the
      data array before declaration!
   *)


  TYPE
    DeltaVar;

    DeltaProc = PROCEDURE ( (*ySim~*)REAL, (*yData*)REAL ): REAL;
    (* ySim~ denotes simulated y interpolated at position xData,
       yData denotes the y value from the installed data series at
       position xData *)


  VAR defaultDelta: DeltaProc;

  PROCEDURE InstallDeltaProc( VAR mvDepVar: REAL; compDelta: DeltaProc );


  PROCEDURE InitDeltaStat( VAR mvDepVar: REAL;  xSim, ySim: REAL;
                           VAR dv: DeltaVar );
  (* initializes the internal variables which hold the wanted statistics.
  - call InitDeltaStat from within your "Initial" procedure,
  note: set xSim to its actual value at t0 before!
  mvDepVar should be declared previously with DeclDispData;
  returns dv for later reference when calling AccuDelta *)


  PROCEDURE AccuDelta( dv: DeltaVar; xSim, ySim: REAL );
  (* This procedures accumulates simple statistics intermediates such as:
  Σ Δ;    Σ Δ^2;   Σ |Δ|;   n;  where Δ is the difference between
  the installed data series (DeclDispDat) and the interpolated
  simulated variable (Δ is computed by means of the installed DeltaProc)
  and n holds the count of accumulated Δs.
  - AccuDelta should be called once for each time step, i.e. normally
  in procedure "output" of your model;
  assumes that dv is correct! *)



  PROCEDURE GetDeltaStat( VAR mvDepVar: REAL;
                          VAR sumY, sumY2, sumAbsY: REAL;
                          VAR count: INTEGER );
  (* allows you to get the stored statistics which were accumulated
  since the last InitDeltaStat (normally a simulation run, see AccuDelta
  for more details). *)

  PROCEDURE SetDeltaStat( VAR mvDepVar: REAL;
                          sumY, sumY2, sumAbsY: REAL; count: INTEGER );
  (* allows to set these statistics. This procedure can be usefull
  if you have to resume an interrupted run or ev. for a complete reset *)


  PROCEDURE WriteDeltaStatMsg( VAR mvDepVar: REAL );
  (* writes the stored statistics for each variable to the table window
  and to the stashfile in form of a message. *)


END SimDeltaCalc.