DEFINITION MODULE Grids;
(*******************************************************************
Module Grids (Version 1.0)
Copyright (c) 2004-2006 by Dimitrios Gyalistras and ETH Zurich.
Purpose Handling and manipulation of objects and/or
multi-layer numerical data arranged on a
two-dimensional, uniform rectangular grid.
Remarks Note, the word "grid" is used her with two
meanings:
Firstly, "grid" refers to a geometrical
structure, that is defined by its extent,
position in space, and gridpoint distance,
respectively cell size (see procedure
SetGridsAttributes).
Secondly, "Grid" (note the capital "G") is
used to refer to an object (data structure)
linked to a geometrical "grid".
Most procedures provided by this module deal
the management of "Grids" defined over a
common underlying "grid".
Programming
o Design
Dimitrios Gyalistras 12/03/2004
o Implementation
Dimitrios Gyalistras 12/03/2004
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: 17/02/2006 DG
*******************************************************************)
FROM SYSTEM IMPORT ADDRESS;
FROM DMFiles IMPORT TextFile;
IMPORT Errors;
CONST
notDone = Errors.onlyAnInsert;
(*
The procedures exported below return errCode = Errors.allOk if the
call to the procedure was succesfull, and resCode = notDone if not.
*)
(*************************************)
(*##### Global declarations #####*)
(*************************************)
TYPE
Grid;
GridData;
GridObjectPtr = ADDRESS;
GridObjectProc = PROCEDURE( (*x-coord*) INTEGER,
(*y-coord*) INTEGER,
(*pointer*) GridObjectPtr );
GridObjectsFilterProc = PROCEDURE( (*x-coord*) INTEGER,
(*y-coord*) INTEGER ): BOOLEAN;
RealPtr = POINTER TO REAL;
AttachedVarPtrProc = PROCEDURE( (*x-coord*) INTEGER,
(*y-coord*) INTEGER,
(*pointer*) RealPtr );
VAR
undefGrid : Grid;
undefGridData : GridData;
(************************************************)
(*##### Common attributes of all grids #####*)
(************************************************)
PROCEDURE SetGridsAttributes( sectorCode : LONGINT;
sectorDescr : ARRAY OF CHAR;
nX, nY : INTEGER;
inDegrees : BOOLEAN; (* FALSE: minLon, minLat, cellSize are given in CH meters grid *)
minLon : REAL;
minLat : REAL;
cellSize : REAL;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(* NOTE: Changing the attribute value for nX, nY or inDegrees
causes automatic removal of all currently declared grids *)
PROCEDURE GridsSectorCode(): LONGINT;
PROCEDURE GetGridsSectorDescr( VAR descr: ARRAY OF CHAR );
PROCEDURE GridsNumX(): INTEGER;
PROCEDURE GridsNumY(): INTEGER;
PROCEDURE GridsUseDegreesCoords(): BOOLEAN;
PROCEDURE GridsMinLon(): REAL;
PROCEDURE GridsMinLat(): REAL;
PROCEDURE GridsCellSize(): REAL;
(******************************************)
(*##### Testing of object access #####*)
(******************************************)
PROCEDURE ActivateGridsObjChecks;
(*
Call this procedure to switch on all checks when
accessing Grid or GridData objects or their attributes
using one of the procedurs below.
*)
PROCEDURE DeactivateGridsObjChecks;
(*
Switch off all checks. Use this procedure for faster
access to Grid or GridData objects and their attributes.
Note, passing of dangling or NIL pointers to some of the
procedures below may cause the program to crash.
*)
PROCEDURE GridsObjChecksActivated(): BOOLEAN;
(*
Find out whether object checks are currently activated.
The default setting is "TRUE".
*)
(***********************************)
(*##### Handling of grids #####*)
(***********************************)
PROCEDURE DeclareGrid ( VAR grid : Grid;
gridIdent : ARRAY OF CHAR;
gridObjectSize : INTEGER;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE SetAllocGridObjectsFilterProc( filterProc: GridObjectsFilterProc );
PROCEDURE CurAllocGridObjectsFilterProc(): GridObjectsFilterProc;
PROCEDURE FindGrid ( gridIdent : ARRAY OF CHAR ): Grid;
PROCEDURE GridExists ( grid : Grid ): BOOLEAN;
PROCEDURE GetGridIdent ( grid : Grid; VAR id: ARRAY OF CHAR );
PROCEDURE GridObjectSize( grid : Grid ): INTEGER;
PROCEDURE RemoveGrid ( VAR grid : Grid );
PROCEDURE GetGridObjectPtr ( grid : Grid;
xC, yC : INTEGER ): GridObjectPtr;
PROCEDURE DoWithAllGridObjects( grid : Grid;
action : GridObjectProc );
PROCEDURE SetDoWithAllGridObjectsFilterProc( filterProc: GridObjectsFilterProc );
PROCEDURE CurDoWithAllGridObjectsFilterProc(): GridObjectsFilterProc;
(***************************************)
(*##### Handling of grid data #####*)
(***************************************)
PROCEDURE DeclareGridData ( grid : Grid;
VAR gridData : GridData;
dataIdent : ARRAY OF CHAR;
dataCode : LONGINT;
nDataLayers : INTEGER;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR);
PROCEDURE FindGridData ( grid : Grid;
dataIdent : ARRAY OF CHAR ): GridData;
PROCEDURE ParentGrid ( gridData : GridData ): Grid;
PROCEDURE GridDataExist ( gridData : GridData ): BOOLEAN;
PROCEDURE GetGridDataIdent ( gridData : GridData; VAR id: ARRAY OF CHAR );
PROCEDURE GridDataCode ( gridData : GridData ): LONGINT;
PROCEDURE NumGridDataLayers ( gridData : GridData ): INTEGER;
PROCEDURE SetGridDataLayerIdent( gridData : GridData;
dataLayerNr : INTEGER;
ident : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE GetGridDataLayerIdent( gridData : GridData;
dataLayerNr : INTEGER;
VAR ident : ARRAY OF CHAR );
PROCEDURE FindGridDataLayerNr ( gridData : GridData;
ident : ARRAY OF CHAR ): INTEGER;
PROCEDURE SetGridDataVal ( gridData : GridData;
dataLayerNr : INTEGER;
xC, yC : INTEGER;
val : REAL );
PROCEDURE GridDataVal ( gridData : GridData;
dataLayerNr : INTEGER;
xC, yC : INTEGER ): REAL;
PROCEDURE RemoveGridData ( VAR gridData : GridData );
(*---------------------------------------*)
(*===== Attach/detach variables =====*)
(*---------------------------------------*)
PROCEDURE AttachGridDataVar ( gridData : GridData;
dataLayerNr : INTEGER;
xC, yC : INTEGER;
VAR variable : REAL );
PROCEDURE DetachGridDataVar ( gridData : GridData;
dataLayerNr : INTEGER;
xC, yC : INTEGER );
(*--------------------------------*)
(*===== Load/unload data =====*)
(*--------------------------------*)
PROCEDURE GridDataLoaded ( gridData : GridData ): BOOLEAN;
PROCEDURE LoadGridData ( gridData : GridData;
inFileName : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE UnloadGridData ( gridData : GridData );
PROCEDURE LoadDataForGrid ( grid : Grid;
dataFrameIdent : ARRAY OF CHAR;
gridDataIdent : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Data for all GridData objects belonging to Grid "grid" are loaded
from input files as specified in data frame "dataFrameIdent",
according to a choice specified in parameter "gridDataIdent".
Note, "gridDataIdent" is just used for input file selection,
it has nothing to do with the identifiers "gridIdent" in procedure
DeclareGrid or "dataIdent" in procedure DeclareGridData.
Example:
DATAFRAME FAE_InGrids; DATA:
(*============================================================*)
Ident gridDataIdent gridDataFileName ;
(*------------------------------------------------------------*)
kLat myData "MyData.GDS" ;
kBS noGridData "--" ;
kBS gd_fae_1 "FAE.test.kBS.4x3.GDS" ;
kBS gd_2634_1 "FAE.kBS.50x50.N-0-25.GDS" ;
(*============================================================*)
END FAE_InGrids;
Column "Ident" is used to specify the GridData object for which data is
to be loaded, column "gridDataIdent" is used to control the choice of
input file, and column "gridDataFileName" contains the name of the
input file to use.
Note, data for a given GridData object belonging to grid "grid" are only
loaded if the following conditions are met:
1. Entry in column "Ident" equals the GridData object's "dataIdent".
2. Entry in column "gridDataIdent" equals the specified value for
parameter "gridDataIdent".
3. Entry in column "gridDataFileName" is different from "--".
If several entries (rows) in the data frame satisfy the above conditions,
only the last found matching entry will be used for loading of data.
*)
PROCEDURE UnloadDataForGrid ( grid : Grid );
PROCEDURE LoadDataForAllGrids( dataFrameIdent : ARRAY OF CHAR;
gridDataIdent : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE UnloadDataForAllGrids;
(*------------------------------------*)
(*===== Assign/deassign data =====*)
(*------------------------------------*)
PROCEDURE AssignGridData ( gridData : GridData );
PROCEDURE DeassignGridData ( gridData : GridData );
PROCEDURE AssignDataForGrid ( grid : Grid );
PROCEDURE DeassignDataForGrid( grid : Grid );
PROCEDURE AssignDataForAllGrids;
PROCEDURE DeassignDataForAllGrids;
(*---------------------------------------------*)
(*===== Operate on attached variables =====*)
(*---------------------------------------------*)
PROCEDURE AttachedVarPtr ( gridData : GridData;
dataLayerNr : INTEGER;
xC, yC : INTEGER ): RealPtr;
PROCEDURE AttachedVarVal ( gridData : GridData;
dataLayerNr : INTEGER;
xC, yC : INTEGER ): REAL;
PROCEDURE AttachedVarsSum( gridData : GridData;
dataLayerNr : INTEGER ): REAL;
PROCEDURE AttachedVarsMean( gridData : GridData;
dataLayerNr : INTEGER ): REAL;
PROCEDURE DoWithAllAttachedVarsPtrs( gridData : GridData;
dataLayerNr : INTEGER;
action : AttachedVarPtrProc );
(*---------------------------------------*)
(*===== Dumping of data to file =====*)
(*---------------------------------------*)
PROCEDURE WriteAttachedVarsToFile ( gridData : GridData;
outFileName : ARRAY OF CHAR;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Creates a file named "outFileName" containing the attached
variables' values for all data layers of "gridData". The
file is written in GridDataSet (ASCII text) format.
*)
PROCEDURE DumpAttachedVars ( VAR outFile : TextFile;
gridData : GridData;
dataLayerNr : INTEGER;
date : LONGINT;
time : LONGINT;
checkInputs : BOOLEAN;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Dumps the attached variables' values for data layer
"dataLayerNr" of "gridData" to file "outFile". The data
are written out in longitude-latitude (lola binary) format.
Use checkInputs=FALSE to skip checks on validity of input
parameters (at your own risk).
*)
PROCEDURE DumpAttachedVarsForGridData( VAR outFile : TextFile;
gridData : GridData;
date : LONGINT;
time : LONGINT;
checkInputs : BOOLEAN;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Executes DumpAttachedVars, for all layers of "gridData".
*)
PROCEDURE DumpAttachedVarsForGrid ( VAR outFile : TextFile;
grid : Grid;
date : LONGINT;
time : LONGINT;
checkInputs : BOOLEAN;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Executes DumpAttachedVarsForGridData for all grid data sets
of "grid".
*)
PROCEDURE DumpAttachedVarsForAllGrids( VAR outFile : TextFile;
date : LONGINT;
time : LONGINT;
checkInputs : BOOLEAN;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Executes DumpAttachedVarsForGrid for all currently declared
grids.
*)
(***************************************************)
(*##### Retrieval of neighbour gridpoints #####*)
(***************************************************)
TYPE
GridClosureType = ( undefGridClosureType, rectangle, cylinder, torus );
PROCEDURE SetGridClosure( gc: GridClosureType );
PROCEDURE CurGridClosure(): GridClosureType;
TYPE
NeighboursSearchAreaType = ( undefNeighboursSearchAreaType, square, circle );
PROCEDURE SetTypeOfNeighboursSearchArea( nsat : NeighboursSearchAreaType );
PROCEDURE TypeOfNeighboursSearchArea(): NeighboursSearchAreaType;
PROCEDURE SetSizeOfNeighboursSearchArea( size : REAL );
PROCEDURE SizeOfNeighboursSearchArea(): REAL;
PROCEDURE GetNeighbourCellsCoords( xCoord : INTEGER;
yCoord : INTEGER;
VAR nNbrs : INTEGER;
VAR nbrX : ARRAY OF INTEGER;
VAR nbrY : ARRAY OF INTEGER;
VAR nbrCAF : ARRAY OF REAL );
PROCEDURE GetNeighbourCellsObjects( grid : Grid;
xCoord : INTEGER;
yCoord : INTEGER;
VAR nNbrs : INTEGER;
VAR nbrCAF : ARRAY OF REAL;
VAR nbrObj : ARRAY OF GridObjectPtr );
(*
xCoord = number of horizontal coordinate (1 <= xCoord <= SetGridsAttributes.nX)
yCoord = number of vertical coordinate (1 <= yCoord <= SetGridsAttributes.nY)
nNbrs = number of neighbour cells found within the neighbours search area
nbrX = x-coordinate numbers of neighbour cells
nbrX = y-coordinate numbers of neighbour cells
nbrCAF = fraction of the area of the respective neighbour cell that
falls within the neighbours search area
nbrObj = grid object associated with the respective neighbour cell
Bottom left cell : (xCoord,yCoord) = (1,1)
Top right cell : (xCoord,yCoord) = (nX,nY)
*)
END Grids.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib