Field3D Class

1. Description

2. Module interface

3. Functions and Subroutines

4. Examples

Description

The Field3D class implements a three-dimensional field. Such a field consists of a three dimensional coordinate grid, a three-dimensional array of real values, and optionally a time axis.

(See also the Compression, Coordinate, Grid3D, FillValue and TimeCoordinate classes.)

Module Interface

MODULE Field3D_Class

TYPE Field3D

INTERFACE isValid
INTERFACE initialize
INTERFACE finalize
INTERFACE equal
INTERFACE unequal
INTERFACE get
INTERFACE set
INTERFACE read
INTERFACE write
INTERFACE print
INTERFACE addNewTime
INTERFACE getCompression
INTERFACE getDescription
INTERFACE getFill
INTERFACE getFillValue
INTERFACE getGrid
INTERFACE getLastTimeIndex
INTERFACE getName
INTERFACE getOffset
INTERFACE getScale
INTERFACE getTime
INTERFACE getTimeAt
INTERFACE getTimeIndex
INTERFACE getUnit
INTERFACE getValues
INTERFACE hasFillValue
INTERFACE isTimeDependent
INTERFACE setTimeAt
INTERFACE setTimeIndex
INTERFACE ASSIGNMENT (=)
INTERFACE OPERATOR (==)
INTERFACE OPERATOR (/=)

INTEGER, PARAMETER :: Field3D_InvalidDimensions
INTEGER, PARAMETER :: Field3D_InvalidAttributeType
INTEGER, PARAMETER :: Field3D_InvalidAttributeSize
INTEGER, PARAMETER :: Field3D_DefinitionFailed
INTEGER, PARAMETER :: Field3D_NoTimeDimensionFound
INTEGER, PARAMETER :: Field3D_NonExistingVariable

END MODULE Field3D_Class

Functions and Subroutines

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

This function checks whether the parameter this contains a valid Field3D object. It may be applied to any Field3D object at any time. A valid Field3D has a name and unit, a valid coordinate grid and has an array to contain field data (for the current time step when the field is time-dependent).

SUBROUTINE initialize(this,compress,description,fill,fill_value,grid,name,
                         offset,scale,time,time_dependent,unit,values)
    TYPE(Field3D),        INTENT(out)          :: this
    TYPE(Compression),    INTENT(in), OPTIONAL :: compress
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: description
    TYPE(FillValue),      INTENT(in), OPTIONAL :: fill
    REAL,                 INTENT(in), OPTIONAL :: fill_value
    TYPE(Grid3D),         INTENT(in), OPTIONAL :: grid
    CHARACTER(len=*),     INTENT(in)           :: name
    REAL,                 INTENT(in), OPTIONAL :: offset
    REAL,                 INTENT(in), OPTIONAL :: scale
    TYPE(TimeCoordinate), INTENT(in), OPTIONAL :: time
    LOGICAL,              INTENT(in), OPTIONAL :: time_dependent
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: unit
    REAL, DIMENSION(:,:), INTENT(in), OPTIONAL :: values

This subroutine initializes an (invalid) Field3D 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 Field3D object.
The following parameters can optionally be specified:

compress

The Compression object associated with this field. Either this parameter should be provided or the offset and/or scale parameters.

description

A text string that describes the data field in more detail than its name.

fill

A FillValue object that is used to identify missing values. This parameter can only be specified when initializing a Field3D object. It cannot be changed later on. When you provide this parameter, you should not provide the fill_value parameter.

fill_value

A real number that is used to identify missing values. This parameter can only be specified when initializing a Field3D object. It cannot be changed later on. You should provide either this parameter or the fill parameter.

grid

The spatial coordinate grid of the field. The length and width of the grid determine the size of the array that contains the field values.

name

The name of the field. This name is used to identify data in a file. Therefore, this name must be specified.

offset

This parameter gives the offset of the field values. The default value when this parameter is not specified is zero. This parameter can only be specified when initializing a Field3D object. It cannot be changed later on. This parameter should not be provided when the compress parameter is.

scale

This parameter gives the scale factor of the field values. The default value when this parameter is not specified is one. This parameter can only be specified when initializing a Field3D object. It cannot be changed later on. This parameter should not be provided when the compress parameter is.

time

A valid TimeCoordinate object that specifies the time axis of the field. When this parameter is given, the only value allowed for the parameter time_dependent is .TRUE.. This parameter can only be specified when initializing a Field3D object. It cannot be changed later on.

time_dependent

This parameter indicates whether the field is time dependent or not. This parameter can only be specified when initializing a Field3D object. It cannot be changed later on.

unit

A text string giving the unit in which the data values of this field are expressed.

values

A two-dimensional array of real numbers that will be used to initialize the field's values. When the grid parameter is also given, this array should have the same sizes as the grid.

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

(See also the Compression, FillValue, Grid3D and TimeCoordinate classes.)

SUBROUTINE initialize(this,info)
    TYPE(Field3D),   INTENT(out) :: this
    TYPE(FieldInfo), INTENT(in)  :: info

This subroutine initializes an (invalid) Field3D object using a FieldInfo record. This subroutine simplifies the initialization of Field3D objects that will be read from a DataFile object. A FieldInfo record can be obtained from a DataFile object using the getFieldInfo function. Note that the grid_dimensions field of this record should have the value three.

(See also the DataFile class.)

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

This subroutine finalizes the (valid) Field3D 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(Field3D), INTENT(in) :: left
    TYPE(Field3D), INTENT(in) :: right

This function compares two Field3D objects. When the two objects are equal, the value .TRUE. is returned. Otherwise, the return value is .FALSE.. Two Field3D object are equal when their name, unit, description, grid, etc. are equal.
This function can also be invoked via the binary operator ==.

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

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

SUBROUTINE get(this,compress,description,grid,name,offset,scale,time,unit,values)
    TYPE(Field3D),        INTENT(in)            :: this
    TYPE(Compression),    INTENT(out), OPTIONAL :: compress
    CHARACTER(len=*),     INTENT(out), OPTIONAL :: description
    TYPE(Grid3D),         INTENT(out), OPTIONAL :: grid
    CHARACTER(len=*),     INTENT(out), OPTIONAL :: name
    REAL,                 INTENT(out), OPTIONAL :: offset
    REAL,                 INTENT(out), OPTIONAL :: scale
    TYPE(TimeCoordinate), INTENT(out), OPTIONAL :: time
    CHARACTER(len=*),     INTENT(out), OPTIONAL :: unit
    REAL, DIMENSION(:,:), INTENT(out), OPTIONAL :: values

This subroutine retrieves information from the Field3D object, this. The object itself is not modified. The optional parameters determine which information will be retrieved. Note that the Grid3D and TimeCoordinate 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 Compression, Grid3D and TimeCoordinate classes.)

SUBROUTINE set(this,description,grid,name,unit,values)
    TYPE(Field3D),        INTENT(inout)          :: this
    CHARACTER(len=*),     INTENT(in),   OPTIONAL :: description
    TYPE(Grid3D),         INTENT(in),   OPTIONAL :: grid
    CHARACTER(len=*),     INTENT(in),   OPTIONAL :: name
    CHARACTER(len=*),     INTENT(in),   OPTIONAL :: unit
    REAL, DIMENSION(:,:), INTENT(in),   OPTIONAL :: values

This subroutine modifies the Field3D object, this. The optional parameters determine which information is modified. The Grid3D object 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 Grid3D class.)

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

This subroutine reads this Field3D object from a file. The object can be read successfully when all information that is associated with a Field3D object can be read successfully. The old contents of the object is destroyed. Note that after reading a field, its data still needs to be scaled and adjusted.

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 following errors can occur:

Field3D_InvalidDimensions

The information in the data file specifies a number of dimensions for the field that differs from that of this Field3D object. The number of dimensions of a Field3D object is either two or three depending on whether the field depends on time or not.

Field3D_InvalidAttributeType

One of the attributes in the data file does not have the expected data type. Its value could not be read.

Field3D_InvalidAttributeSize

One of the attributes in the data file does not have the expected data size. As a result, its value could not be read.

(See also the DataFile and Error classes.)

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

This subroutine writes the contents of this Field3D object to a file. When the object was written to the same file before, the new contents replaces the old. Note that the field data should have been scaled and adjusted before writing the object.
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 following errors can occur:

Field3D_InvalidDimensions

The information in the data file specifies a number of dimensions for the field that differs from that of this Field3D object. This prevents that the data can be written.

Field3D_DefinitionFailed

This object has not been written to the data file before. Therefore, a definition must be created for it. While making the definition an error occured.

(See also the DataFile and Error classes.)

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

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

SUBROUTINE addNewTime(this,time)
    TYPE(Field3D), INTENT(in) :: this
    REAL,          INTENT(in) :: time

This subroutine appends a new time value to the time coordinate of this field and sets the time index to point to this value, unless the field is not time dependent. In that case, this subroutine is a no-op. This routine increases the value of the last time index that is returned by the function getLastTimeIndex.

FUNCTION getCompression(this) RESULT(result)
    TYPE(Compression) :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the Compression object associated with this Field3D object.

(See also the Compression class.)

FUNCTION getDescription(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the description of this Field3D object.

FUNCTION getFill(this) RESULT(result)
    TYPE(FillValue) :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the FillValue object used to indicate empty spots in the data of this Field3D object.

(See also the FillValue class.)

FUNCTION getFillValue(this) RESULT(result)
    REAL :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the fill value used to indicate empty spots in the data of this Field3D object. This function returns only a meaningful result when the function hasFillValue returns the value .TRUE..

FUNCTION getGrid(this) RESULT(result)
    TYPE(Grid3D) :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the spatial grid of this Field3D object.

(See also the Grid3D class.)

FUNCTION getLastTimeIndex(this) RESULT(result)
    INTEGER :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the last time index of this Field3D object for which a time value has been specified. The last time index increases by one each time a new time is added using the addNewTime subroutine. Note that this applies only to time-dependent data fields. For static fields, the return value of this function is always zero.

FUNCTION getName(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the name of this Field3D object.

FUNCTION getOffset(this) RESULT(result)
    REAL :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the data offset of this Field3D object. This offset should be added to the field data after scaling and reading and subtracted before scaling followed by writing.

FUNCTION getScale(this) RESULT(result)
    REAL :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the data scale factor of this Field3D object. This scale factor should be applied immediately after reading and before writing data.

FUNCTION getTime(this) RESULT(result)
    TYPE(TimeCoordinate) :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns (a copy of) the time coordinate of this Field3D object.

(See also the TimeCoordinate class.)

FUNCTION getTimeAt(this,index) RESULT(result)
    REAL :: result
    TYPE(Field3D), INTENT(in) :: this
    INTEGER,       INTENT(in) :: index

This function returns the time value at the given time index of this Field3D object. The index should be the range from one to the last time index for time-dependent fields. For static fields the value 0.0 is returned.

FUNCTION getTimeIndex(this) RESULT(result)
    INTEGER :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the current time index of this Field3D object. This index is in the range from one to the last time index for time-dependent fields. For static fields the index is always one.

FUNCTION getUnit(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns the unit in which the values of this Field3D object are expressed.

FUNCTION getValues(this) RESULT(result)
    REAL, DIMENSION(:,:,:), POINTER :: result
    TYPE(Field3D), INTENT(in) :: this

This function returns a pointer to the array that contains the values of this Field3D object. This pointer remains valid until the field's grid is modified of the Field3D object is finalized. The contents of the array changes when the field is read from a data file. The pointer can be used to modifiy the field data but it should never be deallocated.

FUNCTION hasFillValue(this) RESULT(result)
    LOGICAL :: result
    TYPE(Field3D), INTENT(in) :: this

The return value of this function indicates whether this field uses a fill value to indicate empty areas.

FUNCTION isTimeDependent(this) RESULT(result)
    LOGICAL :: result
    TYPE(Field3D), INTENT(in) :: this

This function checks whether the Field3D object, this, is time dependent and returns the result.

SUBROUTINE setTimeAt(this,index,time)
 TYPE(Field3D), INTENT(inout) :: this
 INTEGER, INTENT(in) :: index
 REAL, INTENT(in) :: time

This subroutine sets the time value at a given time index. This subroutine should only be called for time dependent Field3D objects, i.e. isTimeDependent(this) should return the value .TRUE.. The parameter index must have a value in the range from one to getLastTimeIndex(this).

SUBROUTINE setTimeIndex(this,index)
    TYPE(Field3D), INTENT(inout) :: this
    INTEGER,       INTENT(in)    :: index

This subroutine sets the time index of this Field3D object. The value of the parameter, index, should be in the range from one to the last time index. Use the subroutine addNewTime to increase the upper boundary of this range. This subroutine acts as a no-op for static fields.

ASSIGNMENT (=)    <left> = <right>

This operator copies the content of the Field3D 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 Field3D objects for equality. It is an alternative for using the equal function.

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

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

Examples