Grid3D Class

1. Description

2. Module Interface

3. Subroutines and Functions

4. Examples

Description

The Grid3D class combines three Coordinate objects, a length, width and height coordinate, to a threedimensional spatial coordinate grid. The lengths of the coordinate axes is fixed. This class is a similar to the Grid2D class.

(See also the Coordinate and Grid2D classes.)

Module Interface

MODULE Grid3D_Class

TYPE Grid3D

INTERFACE isValid
INTERFACE initialize
INTERFACE finalize
INTERFACE equal
INTERFACE unequal
INTERFACE get
INTERFACE set
INTERFACE read
INTERFACE write
INTERFACE print
INTERFACE arrayFor
INTERFACE getHeight
INTERFACE getLength
INTERFACE getWidth
INTERFACE matches
INTERFACE ASSIGNMENT (=)
INTERFACE OPERATOR (==)
INTERFACE OPERATOR (/=)
INTERFACE OPERATOR (.matches.)

END MODULE Grid3D_Class

Functions and Subroutines

FUNCTION isValid(this) RESULT(result)
    LOGICAL :: result
    TYPE(Grid3D), INTENT(in) :: this

This function checks whether the parameter this contains a valid Grid3D object. It may be applied to any Grid3D object at any time. A valid Grid3D has three valid Coordinate objects all having a fixed length.

SUBROUTINE initialize(this,height,length,width)
    TYPE(Grid3D),     INTENT(out)          :: this
    TYPE(Coordinate), INTENT(in), OPTIONAL :: height
    TYPE(Coordinate), INTENT(in), OPTIONAL :: length
    TYPE(Coordinate), INTENT(in), OPTIONAL :: width

This subroutine initializes an (invalid) Grid3D object. This subroutine should be invoked on an object before any other function or subroutine except isValid. After initialization, the parameter this contains a valid Grid3D object.
The following parameters can optionally be specified:

height

A valid Coordinate object that specifies the height coordinate axis of the grid.

length

A valid Coordinate object that specifies the length coordinate axis of the grid.

width

A valid Coordinate object that specifies the width coordinate axis of the grid.

A Grid3D object can also be initialized by duplicating an existing object using the assignment operator.

(See also the Coordinate class.)

SUBROUTINE initialize(this,grid,height)
    TYPE(Grid3D),     INTENT(out)          :: this
    TYPE(Grid2D),     INTENT(in), OPTIONAL :: grid
    TYPE(Coordinate), INTENT(in), OPTIONAL :: height

This subroutine initializes an (invalid) Grid3D object. This subroutine should be invoked on an object before any other function or subroutine except isValid. After initialization, the parameter this contains a valid Grid3D object.
The following parameters can optionally be specified:

grid

A valid Grid2D objects that defines the length and width coordinate axis of the grid.

height

A valid Coordinate object that specifies the height coordinate axis of the grid.

A Grid3D object can also be initialized by duplicating an existing object using the assignment operator.

(See also the Coordinate and Grid2D classes.)

SUBROUTINE finalize(this)
    TYPE(Grid3D), INTENT(inout) :: this

This subroutine finalizes the (valid) Grid3D object, this. This object should have been initialized earlier in the program. After finalization, the object is invalid and should not be used anymore.

FUNCTION equal(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(Grid3D), INTENT(in) :: left
    TYPE(Grid3D), INTENT(in) :: right

This function compares two Grid3D objects. When the two objects are equal, the value .TRUE. is returned. Otherwise, the return value is .FALSE.. Two Grid3D object are equal when their height, length and width coordinates are equal.
This function can also be invoked via the binary operator ==.

FUNCTION unequal(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(Grid3D), INTENT(in) :: left
    TYPE(Grid3D), INTENT(in) :: right

This function checks whether two Grid3D objects are different.
This function can also be invoked via the binary operator /=.

SUBROUTINE get(this,height,length,width)
    TYPE(Grid3D),     INTENT(in)            :: this
    TYPE(Coordinate), INTENT(out), OPTIONAL :: height
    TYPE(Coordinate), INTENT(out), OPTIONAL :: length
    TYPE(Coordinate), INTENT(out), OPTIONAL :: width

This subroutine retrieves information from the Grid3D object, this. The object itself is not modified. The optional parameters determine which information will be retrieved. Note that the Coordinate objects don't have to be in a valid state. They will be after this subroutine returns.
This subroutine can be invoked without any parameters. In this case, the subroutine is as a no-op.

(See also the Coordinate class.)

SUBROUTINE set(this,height,length,width)
    TYPE(Grid3D),     INTENT(inout)        :: this
    TYPE(Coordinate), INTENT(in), OPTIONAL :: height
    TYPE(Coordinate), INTENT(in), OPTIONAL :: length
    TYPE(Coordinate), INTENT(in), OPTIONAL :: width

This subroutine modifies the Grid3D, this. The optional parameters determine which information is modified. The Coordinate objects must be valid before invoking this subroutine.
This subroutine can be invoked without any parameters. In this case, the subroutine is as a no-op.

(See also the Coordinate class.)

SUBROUTINE read(this,file,err)
    TYPE(Grid3D),   INTENT(inout)           :: this
    TYPE(DataFile), INTENT(in)              :: file
    TYPE(Error),    INTENT(inout), OPTIONAL :: err

This subroutine reads this Grid3D object from a file. The object can be read successfully when the three Coordinate objects that it contains can be read successfully. The old contents of the object is destroyed.

An Error object can be passed to this subroutine to catch run-time errors that would otherwise cause the execution of the program to be aborted. The errors that can occur are the same as for reading a Coordinate object.

(See also the Coordinate, DataFile and Error classes.)

SUBROUTINE write(this,file,err)
    TYPE(Grid3D),   INTENT(in)              :: this
    TYPE(DataFile), INTENT(in)              :: file
    TYPE(Error),    INTENT(inout), OPTIONAL :: err

This subroutine writes the contents of this Grid3D object to a file. When the object was written to the same file before, the new contents replaces the old. An Error object can be passed to this subroutine to catch run-time errors that would otherwise cause the execution of the program to be aborted. The errors that can be returned are the same as for writing a Coordinate object.

(See also the Coordinate, DataFile and Error classes.)

SUBROUTINE print(this)
    TYPE(Grid3D), INTENT(in) :: this

This subroutine is the equivalent of the Fortran PRINT statement. It prints the Grid3D object, this, to the standard output unit in standardized format. The object is not modified.

FUNCTION arrayFor(this) RESULT(result)
    REAL, DIMENSION(:,:,:), POINTER :: result
    TYPE(Grid3D), INTENT(in) :: this

This function allocates a three-dimensional array of real numbers that matches the Grid3D object, this, and returns it. It is the responsibility of the caller of this function to deallocate the storage when it is no longer needed.

FUNCTION getHeight(this) RESULT(result)
    TYPE(Coordinate) :: result
    TYPE(Grid3D), INTENT(in) :: this

This function returns (a copy of) the height coordinate of this Grid3D object.

(See also the Coordinate class.)

FUNCTION getLength(this) RESULT(result)
    TYPE(Coordinate) :: result
    TYPE(Grid3D), INTENT(in) :: this

This function returns (a copy of) the length coordinate of this Grid3D object.

(See also the Coordinate class.)

FUNCTION getWidth(this) RESULT(result)
    TYPE(Coordinate) :: result
    TYPE(Grid3D), INTENT(in) :: this

This function returns (a copy of) the width coordinate of this Grid3D object.

(See also the Coordinate class.)

FUNCTION matches(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(Grid3D), INTENT(in) :: left
    TYPE(Grid3D), INTENT(in) :: right

This function checks whether two Grid3D objects match, i.e., whether the lengths of their height, length and width coordinates are the same. Note that this is a weaker condition than equality because the values of the coordinates may differ. This function can also be invoked using the operator .matches..

FUNCTION matches(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(Grid3D),           INTENT(in) :: left
    REAL, DIMENSION(:,:,:), INTENT(in) :: right

This function checks whether a Grid3D coordinates matches a three-dimensional array, i.e. whether the lengths of the length, width and height coordinates are equal to the size of the first, second and third dimension of the array. This function can also be invoked using the operator .matches..

FUNCTION matches(left,right) RESULT(result)
    LOGICAL :: result
    REAL, DIMENSION(:,:,:), INTENT(in) :: left
    TYPE(Grid3D),           INTENT(in) :: right

This function is the similar to the previous function. The only difference is that the left and right arguments have their types exchanged. This function can also be invoked using the operator .matches..

ASSIGNMENT (=)    <left> = <right>

This operator copies the content of the Grid3D object at the right of the assignment operator to the one at the left. The latter object can invalid before the assignment. After the assignment it is valid.

OPERATOR (==)    <left> == <right>

This operator compares two Grid3D objects for equality. It is an alternative for using the equal function.

OPERATOR (/=)    <left> /= <right>

This operator compares two Grid3D objects for inequality. It is an alternative for using the unequal function.

OPERATOR (.matches.)    <left> .matches. <right>

This operator checks whether two Grid3D objects or one Grid3D object and a three-dimensional real array match in size. It is an alternative for using the matches function.

Examples

The example program shows how you can create a Grid3D object from a Grid2D object and check that their coordinate axes are equal as is to be expected.

PROGRAM Grid3D_Class_Example
  USE Coordinate_Class
  USE Grid2D_Class
  USE Grid3D_Class
  IMPLICIT NONE

  TYPE(Coordinate) :: xcoord, ycoord, zcoord, coord1, coord2
  TYPE(Grid2D)     :: g2d
  TYPE(Grid3D)     :: g3d

  CALL initialize(xcoord,name="X")
  CALL initialize(ycoord,name="Y")
  CALL initialize(g2d,length=xcoord,width=ycoord)
  CALL initialize(zcoord,name="Z")
  CALL initialize(g3d,grid=grid,height=zcoord)

  coord1 = getLength(g3d)
  coord2 = getLength(g2d)
  IF (coord1 /= coord2) THEN
    STOP "x coordinates are different"
  END IF
  CALL finalize(coord1)
  CALL finalize(coord2)

  coord1 = getWidth(g3d)
  coord2 = getWidth(g2d)
  IF (coord1 /= coord2) THEN
    STOP "y coordinates are different"
  END IF
  CALL finalize(coord1)
  CALL finalize(coord2)

  CALL finalize(g3d)
  CALL finalize(g2d)
  CALL finalize(zcoord)
  CALL finalize(ycoord)
  CALL finalize(xcoord)
END PROGRAM Grid3D_Class_Example

Note that the coord1 and coord2 objects are initialized using the assignment operator. Therefore, they have to be finalized before they are assigned new values to ensure that memory that was allocated before is freed.