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

DEFINITION MODULE TrSpecRSampl;

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

    Module  TrSpecRSampl     (Version 1.0)

      Copyright (c) 2005-2006 by Dimitrios Gyalistras and ETH Zurich.

    Purpose   Types and procedures for random sampling
              of tree species parameters as managed by
              companion module TreeSpecies.

    Remarks   This module is part of the package Trees.


    Programming

      o Design
        Dimitrios Gyalistras      21/12/2005

      o Implementation
        Dimitrios Gyalistras      21/12/2005


    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/12/2005  DG

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


  IMPORT Errors;

  FROM TreeSpecies IMPORT
    TreeSpecies, TSParamType, TSParamsRec;


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

  CONST
    notDone = Errors.onlyAnInsert;
    (*
      The procedures exported below return resCode = Errors.allOk if the
      call to the procedure was succesfull, and resCode = notDone if not.
    *)

  TYPE
    RandomSamplingDistribType = ( undefRSDType, uniform, normal );
    RandomSamplingSpreadType  = ( undefRSSType, absolute, relative );



  PROCEDURE RandomSamplingPossible( pType : TSParamType ): BOOLEAN;


  PROCEDURE SetRandomSamplingForParam( ts            : TreeSpecies;
                                       pType         : TSParamType;
                                       distribSpecif : RandomSamplingDistribType;
                                       spreadSpecif  : RandomSamplingSpreadType;
                                       spread        : REAL;
                                       VAR resCode   : INTEGER;
                                       VAR errTxt    : ARRAY OF CHAR );
  (*
    Defines random sampling scheme for parameter "pType" of tree species
    "ts".  Parameter "distribSpecif" defines the type of distribution to use:

      - uniform:  U( min, max )
      - normal:   N( mu, sig )

    The mean of the distribution ("mu") is given by the tree species'
    current parameter value (see procedure "TreeSpecies.DeclTreeSpecies").

    The variance of the distribution is determined from parameters
    "spreadSpecif" and "spread", as follows:

      distribSpecif  spreadSpecif  used distribution
      -------------  ------------  ------------------
      uniform        absolute      U( mu-spread, mu+spread )
      uniform        relative      U( mu-mu*spread/100, mu+mu*spread/100 )
      normal         absolute      N( mu, 0.5*spread )
      normal         relative      N( mu, 0.5*mu*spread/100 )

    I.e, in case of a normal distribution and spreadSpecif = absolute
    ~95.5% of all sampled values will be found within the range
    [mu-spread ..mu+spread].

    Note, all sampled values are restricted to the parameter's
    plausibility range (see "TreeSpecies.TSParamMin/Max").
    This may cause deviations from the used theoretical distribution, in
    particular if "spread" is large (accumulation of sampled values at
    edges of allowed value range).
  *)

  PROCEDURE SetRandomSamplingFromDataFrames( VAR resCode : INTEGER;
                                             VAR errTxt  : ARRAY OF CHAR );


  PROCEDURE GetRandomSamplingForParam( ts                : TreeSpecies;
                                       pType             : TSParamType;
                                       VAR distribSpecif : RandomSamplingDistribType;
                                       VAR spreadSpecif  : RandomSamplingSpreadType;
                                       VAR spread        : REAL );


  PROCEDURE ClearRandomSamplingForParam( ts: TreeSpecies; pType: TSParamType );


  PROCEDURE ClearRandomSamplingForSpecies( ts: TreeSpecies );


  PROCEDURE ClearRandomSamplingForAllSpecies;


  PROCEDURE SampleTSParamValue( ts: TreeSpecies; pType: TSParamType ): REAL;
  (*
    Samples a parameter value for parameter "pType" of tree species
    "ts".  If random sampling is not currently set for that particular
    parameter (see procedure "SetRandomSamplingForParam") the procedure
    returns the species' corresponding current parameter value (see
    procedure "TreeSpecies.DeclTreeSpecies").
  *)

  PROCEDURE SampleTSParamsRec( ts: TreeSpecies; VAR params: TSParamsRec );
  (*
    Samples an entire parameter record for tree species "ts".  If
    sampling is not possible or not currently set for a particular
    parameter (see procedure "SetRandomSamplingForParam") the result
    variable "params" will contain the species' corresponding default
    parameter value (see procedure "TreeSpecies.DeclTreeSpecies"), or
    the appropriate derived parameter value.  Note, all parameters are
    sampled independently of each other (covariance matrix = unit
    matrix).
  *)



END TrSpecRSampl.