Field Class

1. Description
2. Module interface
3. Functions and Subroutines
4. Examples

Description

The Grid class implements an abstract coordinate grid, i.e. a grid of which the number of dimensions is not known.

(See also the Compression, Coordinate, Field1D, Field2D, Field3D, Grid2D, Grid3D, FillValue and TimeCoordinate classes.)

Module Interface

MODULE Field_Class

TYPE Field
TYPE Grid

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

END MODULE Field_Class

Functions and Subroutines

This function checks whether the parameter this contains a valid Field object. It may be applied to any Field object at any time. A valid Field has a name and unit, a valid coordinate grid and has an array to contain field data.

This function checks whether the parameter this contains a valid Grid object. It may be applied to any Grid object at any time.

This subroutine initializes an (invalid) Field object using a FieldInfo record. This subroutine simplifies the initialization of Field 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 the record should have the value two. Either one of the optional parameters fill and fill_value can be specified to set the fill value of this field.

(See also the DataFile class.)

SUBROUTINE initialize(this,name,a_grid,time,fill,fill_value)
    TYPE(Field),          INTENT(out)          :: this
    CHARACTER(len=*),     INTENT(in)           :: name
    TYPE(Grid),           INTENT(in)           :: a_grid
    TYPE(TimeCoordinate), INTENT(in), OPTIONAL :: time
    TYPE(FillValue),      INTENT(in), OPTIONAL :: fill
    REAL,                 INTENT(in), OPTIONAL :: fill_value

This subroutine initializes an (invalid) Field object using a Grid object. In order to create a time-dependent Field object you should provide a TimeCoordinate object for the parameter time. Either one of the optional fill and fill_value parameters can be used to set the fill value of this Field object.

(See also the FillValue and TimeCoordinate classes.)

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

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

This subroutine finalizes the Grid object, this. This object should have been requested from a Field object using the getGrid function. After finalization, the object is invalid and should not be used anymore.

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

This function compares two Grid objects. When the two objects are equal, the value .TRUE. is returned. Otherwise, the return value is .FALSE..
This function can also be invoked via the binary operator ==.

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

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

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

This subroutine modifies the Field object, this. The optional parameters determine which information is modified. This subroutine can be invoked without any parameters. In this case, the subroutine is as a no-op.

This subroutine reads this Field object from a file. The object can be read successfully when all information that is associated with a Field 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:

Field_InvalidDimensions

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

Field_InvalidAttributeType

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

Field_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 Error class.)

This subroutine writes the contents of this Field 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:

Field_InvalidDimensions

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

Field_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 Coordinate and Error classes.)

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

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

SUBROUTINE addCoordinate(this,coord)
    TYPE(Grid),       INTENT(inout) :: this
    TYPE(Coordinate), INTENT(in)    :: coord

This subroutine increases the number of dimensions of a Grid object by adding a Coordinate object. This operation is only supported on one and two dimensional grids since in the current implementation a grid can have at most three dimensions.

(See also the Coordinate class.)

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.

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

(See also the Compression class.)

This function returns the description of this Field object.

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

(See also the FillValue class.)

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

This function returns the spatial grid of this Field object.

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

This function retrieves the height of the grid. In case the grid does  not have a height coordinate, a Coordinate object with the name "<Invalid>" and length zero is returned.

(See also the Coordinate class.)

This function returns the last time index of this Field 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 getLength(this) RESULT(result)
    TYPE(Coordinate), POINTER :: result
    TYPE(Grid), INTENT(in) :: this

This function retrieves the length of the grid.

(See also the Coordinate class.)

This function returns the name of this Field object.

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

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

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

(See also the TimeCoordinate class.)

This function returns the time value at the given time index of this Field 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.

This function returns the current time index of this Field 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.

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

This function returns a pointer to the array that contains the values of this Field object. This pointer remains valid until the field's grid is modified of the Field 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 getWidth(this) RESULT(result)
    TYPE(Coordinate), POINTER :: result
    TYPE(Grid), INTENT(in) :: this

This function retrieves the widthof the grid. In case the grid does  not have a width coordinate, a Coordinate object with the name "<Invalid>" and length zero is returned.

(See also the Coordinate class.)

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

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

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

This function checks whether two Grid objects match, i.e. that the sizes of their length width and height are equal.
This function can also be invoked with the binary operator .matches..

SUBROUTINE setTimeAt(this,index,time)
    TYPE(Field), 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 Field 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).

This subroutine sets the time index of this Field 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.

SUBROUTINE setValues(this,values)
    TYPE(Field),        INTENT(in) :: this
    REAL, DIMENSION(:), INTENT(in) :: values

This subroutine changes the values of this Field object (at the current time step when the field depends on time).

ASSIGNMENT (=)   <left> = <right>

This operator copies the content of the Field or Grid 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.

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

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

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

This operator checks whether two Grid objects match. It is an alternative for using the matches function.

Examples