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

DEFINITION MODULE IdentParMod;

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

    Module  IdentParMod     (Version 1.0)

      Copyright (c) 1997-2006 by Andreas Fischlin and ETH Zurich.

    Purpose   Identification parallel model which can identify
              parameters of any discrete time model system with
              a single output within RAMSES (Fischlin, 1991).

    Remarks   Installs an experiment using InstallExperiment from
              module SimMaster, which starts the parameter
              identification.  Any parameter declared as a ModelWorks
              parameter (SimBase.DeclP) from any model can be identified
              in any combination.  A 2-dimensional projection from the
              k-dimensional parameter space into a graph (window called
              parameter space provided by module DrawParSpace) can be
              watched during identification.  This supports a fully
              interactive identification allowing the human user to
              detect local minima and to avoid them.

              Imports: Requires ModelWorks and from the auxiliary
              library the modules IdentifyPars and DrawParSpace.
              Hint: The installation of this model is best done by
              means of auxiliary library module StructModAux.

              Reference:  Fischlin, A. (1991). Interactive modeling
              and simulation of environmental systems on workstations.
              In:  Möller, D.P.F. (ed.), Analysis of Dynamic Systems in
              Medicine, Biology, and Ecology.  Springer, Berlin a.o.,
              pp. 131-145.


    Programming

      o Design
        Andreas Fischlin          09/05/1997

      o Implementation
        Andreas Fischlin          09/05/1997


    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:  08/06/2002  AF

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


  FROM SimBase IMPORT Model, OutVar;


  VAR
    identifyParModDescr: ARRAY [0..63] OF CHAR; (* read only *)

  PROCEDURE ActivateIdentifyParMod;
  PROCEDURE IdentifyParModIsActive(): BOOLEAN;
  PROCEDURE DeactivateIdentifyParMod;
    (*
      Activates, informs, and deactivates, respectively, a
      parallell model which allows to identify a single output
      (y, see below InstallSysOutput) model system using a time
      series of measurements (yDash, see below
      InstallMeasurement).  The 3 procedures and
      identifyParModDescr are designed to be used while
      installing this model via module StructModAux for
      interactive activation and deactivation. IMPLEMENTATION
      RESTRICTION: To function correctly, this model has to be
      installed as the last in sequence of models (cf. module
      StructModAux).
    *)



  PROCEDURE InstallSysOutput(VAR y: OutVar);
  PROCEDURE SysOutputInstalled(): BOOLEAN;
  PROCEDURE DeinstallSysOutput;
    (*
      Make the variable which holds the current system output
      known to the identification parallel model.  NOTE: This
      module assumes y exists at all times between a call to
      InstallSysOutput and DeinstallSysOutput
    *)


  PROCEDURE InstallMeasurement(VAR yDash: OutVar; t0,tn: REAL);
  PROCEDURE MeasurementInstalled(): BOOLEAN;
  PROCEDURE DeinstallMeasurement;
    (*
      Make the variable which holds the current measurements
      known to the identification parallel model.  The domain in
      which the measurements are defined is specified by t0 and
      tn.  NOTE: This module assumes yDash exists at all times
      between a call to InstallMeasurement and
      DeinstallMeasurement.
    *)

  PROCEDURE IgnoreMissingValues(ignore: BOOLEAN);
  PROCEDURE MissingValuesIgnored(): BOOLEAN;
    (*
      Mode how the performance index is calculated when the
      measurements contain missing values within the domain [t0..tn].
      Either missing values are simply ignored and the performance
      index is computed with any measurements available or a warning
      message is produced (default).
    *)

  PROCEDURE UseLogPerformanceIndex(uselg: BOOLEAN);
  PROCEDURE LogPerformanceIndexInUse(): BOOLEAN;
  PROCEDURE SetNegLogOffset(    q0: REAL);
  PROCEDURE GetNegLogOffset(VAR q0: REAL);
    (*
      By default sum of squares of (y-yDash)^2 are computed as the
      performance index to be optimized.  Alternatively it is also
      possible to use the logarithms, i.e. a performance index with the
      sum of (Ln(y)-Ln(yDash))^2.  To ensure computability of such a
      performance index at all times (especially important for
      measurements with zero values), a small number q0 is used to
      compute the performance index actually according to this formula:
      (Ln(q0+y)-Ln(q0+yDash))^2.  Of course, in case all measurements
      and the system output are positive at all times, it is possible
      to use a q0 of zero.  The default value of q0 is 0.01.
    *)

  PROCEDURE HideParFromIdentification (m: Model; ident: ARRAY OF CHAR; hideit: BOOLEAN);
  PROCEDURE IsParHiddenFromIdentification (m: Model; ident: ARRAY OF CHAR): BOOLEAN;
    (*
      HideParFromIdentification controls wether a parameter owned by
      model m and identifier ident will be displayed in the list of
      parameters offered for identification when starting the
      identification experiment.
    *)

  PROCEDURE ScalePerfIndexBy(scalePI: REAL);
  PROCEDURE PerfIndexIsScaledBy(VAR scalePI: REAL);
    (*
      During identification the performance index is displayed in the
      graph window of the standard simulation environment.  The initial
      performance index is used to estimate the scale of its display
      multiplied by scalePI. Some identification methods do enlarge the
      performance index during the course of identification, some do
      only diminish it.  In the first case, e.g. when using the
      algorithm 'amoeba' (see module IdentifyPars), set scalePI to a
      value ~2.5 (default) or larger.  In the second case set scalePI
      to a value ~1.0.
    *)


END IdentParMod.