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

DEFINITION MODULE LgMatrices;

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

    Module  LgMatrices     (Version 1.0)

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

    Purpose   Handling of double precision matrices and vectors
              (large matrices, more than 4k x 4k elements). 

    Remarks   See also modules LgMatIO, LgMatCalc, LgMatInv.


    Programming

      o Design
        Dimitrios Gyalistras      12/05/1995

      o Implementation
        Dimitrios Gyalistras      12/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:  04/04/2005  AF

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


  FROM SYSTEM IMPORT ADDRESS;
  IMPORT Errors;


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

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

  (* IF VERSION_MacMETH *)
  CONST
    MaxElems   = 4*1024-1;
  (* ENDIF VERSION_MacMETH *)

  (* IF VERSION_EPC *) (*.
  CONST
    MaxElems   = 8*512*1024;  (* = 8*524'288 = 4'194'304 *)
  .*) (* ENDIF VERSION_EPC *)

  (* IF VERSION_STONYBROOK *) (*.
  CONST
    MaxElems   = 8*1024-1;
  .*) (* ENDIF VERSION_STONYBROOK *)

  (* IF VERSION_P1 *) (*.
  CONST
    MaxElems   = 8*512*1024;  (* = 8*524'288 = 4'194'304 *)
  .*) (* ENDIF VERSION_P1 *)

 TYPE
   LVec            = ARRAY [1..MaxElems] OF LONGREAL;
   LVector         = POINTER TO LVec;
   LMat            = ARRAY [1..MaxElems] OF LVector;
   LMatrix         = POINTER TO LMat;
   MatrixType      = LONGINT;
   MatrixCode      = LONGINT;
   MatrixAttribute = ADDRESS;

 VAR  (* read only *)
   notAllocatedLVector  : LVector;
   notAllocatedLMatrix  : LMatrix;
   undefMatrixType      : MatrixType;
   anyMatrixType        : MatrixType;
   undefMatrixCode      : MatrixCode;
   anyMatrixCode        : MatrixCode;
   undefMatrixAttribute : MatrixAttribute;


  (************************************)
  (*#####   Objects management   #####*)
  (************************************)


  PROCEDURE AllocMatrix( VAR mat     : LMatrix;
                         nRows       : INTEGER;   (* actually allocated *)
                         nCols       : INTEGER;   (* actually allocated *)
                         initVal     : LONGREAL;  (* value to use for initialization *)
                         VAR resCode : INTEGER;
                         VAR errTxt  : ARRAY OF CHAR );
   (*  The (i,j)-th element is dereferenced as mat^[i]^[j]
       IMPORTANT NOTE: To warrant successful completion of this
       routine under all circumstances, it is recommended to
       initialize mat with value notAllocatedLMatrix prior to
       calling AllocMatric.
   *)


  PROCEDURE MatrixExists( mat: LMatrix ): BOOLEAN;

  PROCEDURE DeallocMatrix( VAR mat: LMatrix );



  PROCEDURE AllocVector( VAR vec     : LVector;
                         nElems      : INTEGER;   (* actually allocated *)
                         initVal     : LONGREAL;  (* value to use for initialization *)
                         VAR resCode : INTEGER;
                         VAR errTxt  : ARRAY OF CHAR );
   (*  The i-the element is dereferenced as vec^[i]
       IMPORTANT NOTE: To warrant successful completion of this
       routine under all circumstances, it is recommended to
       initialize vec with value notAllocatedLVector prior to
       calling AllocVector.
   *)


  PROCEDURE VectorExists( vec: LVector ): BOOLEAN;

  PROCEDURE DeallocVector( VAR vec: LVector );
  (*
    IMPLEMENTATION RESCTRICTION: operates only correctly on
    inidividual vectors, not on rows of matrices!  For
    efficiency reasons, no testing of this precondition is
    done.
  *)


  (**************************************)
  (*#####   Dimensions retrieval   #####*)
  (**************************************)

  PROCEDURE NRows( mat: LMatrix ): INTEGER;
    (*  Returns number of allocated rows  *)


  PROCEDURE NCols( mat: LMatrix ): INTEGER;
    (*  Returns number of allocated columns  *)



  PROCEDURE NElems( vec: LVector ): INTEGER;
    (*  Returns number of allocated elements  *)



  (*************************************)
  (*#####   Checking of objects   #####*)
  (*************************************)


  PROCEDURE GetQuotedMatDescr( mat             : LMatrix;
                               genericDescr    : ARRAY OF CHAR; (*  used if mat has no descriptor attached to it *)
                               VAR quotedDescr : ARRAY OF CHAR );

  PROCEDURE MatrixOK( mat          : LMatrix;
                      genericDescr : ARRAY OF CHAR;
                      callee       : ARRAY OF CHAR;
                      minRows      : INTEGER;
                      minCols      : INTEGER;
                      VAR errTxt   : ARRAY OF CHAR ): BOOLEAN;

  PROCEDURE MatTypeOK( mat          : LMatrix;
                       genericDescr : ARRAY OF CHAR;
                       callee       : ARRAY OF CHAR;
                       expectedType : MatrixType;
                       VAR errTxt   : ARRAY OF CHAR ): BOOLEAN;

  PROCEDURE MatCodeOK( mat          : LMatrix;
                       genericDescr : ARRAY OF CHAR;
                       callee       : ARRAY OF CHAR;
                       expectedCode : MatrixCode;
                       VAR errTxt   : ARRAY OF CHAR ): BOOLEAN;


  PROCEDURE GetQuotedVecDescr( vec             : LVector;
                               genericDescr    : ARRAY OF CHAR; (*  used if vec has no descriptor attached to it *)
                               VAR quotedDescr : ARRAY OF CHAR );

  PROCEDURE VectorOK( vec          : LVector;
                      genericDescr : ARRAY OF CHAR;
                      callee       : ARRAY OF CHAR;
                      minElems     : INTEGER;
                      VAR errTxt   : ARRAY OF CHAR ): BOOLEAN;



  (***********************************)
  (*#####   Matrix attributes   #####*)
  (***********************************)

  PROCEDURE SetMatrixDescr( mat   : LMatrix;
                            descr : ARRAY OF CHAR );

  PROCEDURE GetMatrixDescr( mat       : LMatrix;
                            VAR descr : ARRAY OF CHAR );



  PROCEDURE SetMatrixType( mat  : LMatrix;
                           type : MatrixType );

  PROCEDURE MatType( mat: LMatrix ): MatrixType;



  PROCEDURE SetMatrixCode( mat  : LMatrix;
                           code : MatrixCode );

  PROCEDURE MatCode( mat: LMatrix ): MatrixCode;



  PROCEDURE SetColIds( mat     : LMatrix;
                       VAR ids : ARRAY OF CHAR ); (* VAR for speed-up only *)

  PROCEDURE GetColIds( mat     : LMatrix;
                       VAR ids : ARRAY OF CHAR );



  PROCEDURE SetRowIds( mat     : LMatrix;
                       VAR ids : ARRAY OF CHAR ); (* VAR for speed-up only *)

  PROCEDURE GetRowIds( mat     : LMatrix;
                       VAR ids : ARRAY OF CHAR );



  PROCEDURE SetMatrixAttr( mat  : LMatrix;
                           attr : MatrixAttribute );

  PROCEDURE MatrixAttr( mat: LMatrix ): MatrixAttribute;


  PROCEDURE CopyAllMatrixAttributes( from, to: LMatrix );


  (*********************************************)
  (*#####   Manipulation of object data   #####*)
  (*********************************************)


   PROCEDURE SetMatrix( mat : LMatrix;
                        val : LONGREAL );


   PROCEDURE SetMatrixCol( mat     : LMatrix;
                           colNr   : INTEGER;
                           colData : LVector );

   PROCEDURE GetMatrixCol( mat     : LMatrix;
                           colNr   : INTEGER;
                           colData : LVector );


   PROCEDURE SetMatrixRow( mat     : LMatrix;
                           rowNr   : INTEGER;
                           rowData : LVector );

   PROCEDURE GetMatrixRow( mat     : LMatrix;
                           rowNr   : INTEGER;
                           rowData : LVector );


   PROCEDURE SetMatCol( mat         : LMatrix;
                        colNr       : INTEGER;
                        nElems      : INTEGER;
                        VAR colData : ARRAY OF LONGREAL );  (* VAR for speed-up only *)

   PROCEDURE GetMatCol( mat         : LMatrix;
                        colNr       : INTEGER;
                        VAR nElems  : INTEGER;
                        VAR colData : ARRAY OF LONGREAL );


   PROCEDURE SetMatRow( mat         : LMatrix;
                        rowNr       : INTEGER;
                        nElems      : INTEGER;
                        VAR rowData : ARRAY OF LONGREAL );  (* VAR for speed-up only *)

   PROCEDURE GetMatRow( mat         : LMatrix;
                        rowNr       : INTEGER;
                        VAR nElems  : INTEGER;
                        VAR rowData : ARRAY OF LONGREAL );


   PROCEDURE CopyMatrix( mat : LMatrix;
                         res : LMatrix );


   PROCEDURE Transpose( mat : LMatrix;
                        res : LMatrix );


   PROCEDURE SetVector( vec : LVector;
                        val : LONGREAL );


   PROCEDURE CopyVector( vec : LVector;
                         res : LVector );


END LgMatrices.