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

DEFINITION MODULE MultiNormal;

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

    Module  MultiNormal     (Version 1.0)

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

    Purpose   Generate variates from a multinormal distribution.

    Remarks   Inputs are the means, standard deviations and
              correlation matrix of n random variables.

              In order to obtain appropriately correlated variates, a
              vector of n independently generated normal random numbers
              is multiplied by the principal component factor loadings
              (eigenvectors) of the random variables' covariance matrix.
              The vector's elements are than transformed to match the
              specified means of the respective random variables.

              This module uses the procedures "RandGen.U()",
              "RandNormal.InstallU(…)" and "RandNormal.N()". It
              does not modify the seeds available in "RandGen", nor
              does it call any other procedures exported in
              "RandNormal" than those mentioned above. In
              particular, "RandNormal.N()" is always expected to
              return a normally distributed random variable with
              mean 0.0 and standard deviation 1.0 (corresponds to
              the "RandNormal" default settings).

              NOTE: "RandNormal.N()" will be called n times in a row
              each time a n-dimensional sample is requested from
              this module.


    Programming

      o Design
        Dimitrios Gyalistras      15/04/1992

      o Implementation
        Dimitrios Gyalistras      15/04/1992


    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:  04/04/2000  AF

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


  FROM Jacobi IMPORT Vector, Matrix;


  TYPE
    MultiNDistr;
  VAR
    notDeclaredMultiNDistr: MultiNDistr; (* read only *)



  PROCEDURE DeclareMultiNDistr( VAR muVec  : Vector;
                                VAR sigVec : Vector;
                                VAR corMat : Matrix;
                                    dim    : INTEGER;
                                VAR mnd    : MultiNDistr);
  (*
    Declare a multinormal distribution for 'dim' random variables
    (dimensions). 'muVec' and 'sigVec' contain the means and
    standard deviations for each random variable, 'corMat' contains
    in its LOWER HALF the correlation coefficients between each
    pair of variables (upper diagonal and diagonal elements are
    meaningless for this routine).
    All VAR-parameters for speed-up reasons, except parameter 'mnd'
    which returns reference for further usage of the defined
    distribution.
    NOTE: Declaration of an already declared distribution results in
    its redeclaration.
  *)


  PROCEDURE MultiNDistrDeclared( mnd: MultiNDistr ): BOOLEAN;
  (*
    Returns true, if distribution 'mnd' has already been declared.
  *)

  PROCEDURE SetMultiNDistrMeans (mnd: MultiNDistr; newMuVec: Vector);
  (*
    Sets new means for mnd given mnd has previously been declared
    by MultiNDistrDeclared
  *)


  PROCEDURE MultiN( mnd: MultiNDistr; VAR vals: Vector );
  (*
    Returns in the first 'dim' (see DeclareMultiNDistr) elements
    of vector 'vals' a sample from distribution 'mnd'.
    NOTE: Existence of mnd is not checked for reasons of efficiency.
  *)


  PROCEDURE UndeclareMultiNDistr( VAR mnd: MultiNDistr );
  (*
    Give up declared distribution 'mnd' (frees associated memory
    space).
  *)


END MultiNormal.