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

DEFINITION MODULE LgMatInv;

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

    Module  LgMatInv     (Version 1.0)

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

    Purpose   Compute the inverse of a double precision matrix 
              and solve a linear equation system 
              (large matrices, more than 4k x 4k elements). 

    Remarks   Algorithms taken from W.H. Press et.al., Numerical
              Recipes, Cambridge 1988, ISBN 0521 30811 9, p31-38
              (LU Decomposition).

              This module is part of the package LgMatrices.


    Programming

      o Design
        Dimitrios Gyalistras      11/05/1995

      o Implementation
        Dimitrios Gyalistras      11/05/1995


    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:  24/05/2002  AF

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


  IMPORT Errors;
  FROM LgMatrices IMPORT LMatrix, LVector;


  (******************************************************************)

  CONST  (* result codes returned *)
    allOk   = Errors.allOk;
    notDone = Errors.onlyAnInsert;

  (*
    Note: the dimensions of all LVector and LMatrix objects used below
    are determined automatically via procedures LgMatrices.NElems,
    LgMatrices.NRows and LgMatrices.NCols.
  *)


   PROCEDURE InvertMatrix( mat         : LMatrix;
                           inv         : LMatrix;  (* out *)
                           VAR resCode : INTEGER;
                           VAR errTxt  : ARRAY OF CHAR );

   (*
     Computes the inverse matrix "inv" of matrix "mat" based on
     the LU Decomposition of "mat".  The procedure leaves "mat"
     untouched (unless the same variable is also passed as "inv").

     The procedure tests (1) whether "mat" is singular, and (2)
     whether
          | mat[i,j]*inv[i,j] - one[i,j] | <= tol   (for all i,j),
     where "one" is the identity matrix, and "tol" is the currently
     set absolute tolerance.

     Returns FALSE and a corresponding error message in "errTxt"
     if one of these conditions is not met.
   *)


   PROCEDURE SolveLinEqu( A           : LMatrix;
                          b           : LVector;
                          x           : LVector;  (* out *)
                          VAR resCode : INTEGER;
                          VAR errTxt  : ARRAY OF CHAR );
   (*
     Computes the solution "x" of the matrix equation "A x = b".
     The procedure leaves "A" and "b" untouched (unless the same
     variable is also passed as "x").

     The procedure tests (1) whether "mat" is singular, and (2)
     whether
            | (A*x)[i] - b[i] | <= tol   (for all i),
     where "tol" is the currently set absolute tolerance.

     Returns FALSE and a corresponding error message in "errTxt"
     if one of these conditions is not met.
   *)


   PROCEDURE GetMatInvertTolerance( VAR tol: LONGREAL );

   PROCEDURE SetMatInvertTolerance( tol: LONGREAL );
   (*
     Absolute tolerance for testing the inverse of a matrix or the
     solution of a linear system. Default value is 1.0E-12.
   *)


END LgMatInv.