Coordinate Class

Description
Module Interface
Subroutines and Functions
Examples

Description

The Coordinate class represents a coordinate axis of a data field grid.

Module Interface

MODULE Coordinate_Class

TYPE Coordinate

INTERFACE isValid
INTERFACE initialize
INTERFACE finalize
INTERFACE equal
INTERFACE unequal
INTERFACE get
INTERFACE set
INTERFACE read
INTERFACE write
INTERFACE print
INTERFACE arrayFor
INTERFACE getDescription
INTERFACE getLength
INTERFACE getName
INTERFACE getUnit
INTERFACE getValues
INTERFACE getValueAt
INTERFACE isUnlimited
INTERFACE matches
INTERFACE setValueAt
INTERFACE ASSIGNMENT (=)
INTERFACE OPERATOR (==)
INTERFACE OPERATOR (/=)
INTERFACE OPERATOR (.matches.)

INTEGER, PARAMETER :: Coordinate_InvalidDimensions
INTEGER, PARAMEGER :: Coordinate_InvalidAttributeType
INTEGER, PARAMETER :: Coordinate_InvalidAttributeSize
INTEGER, PARAMETER :: Coordinate_DefinitionFailed
INTEGER, PARAMETER :: Coordinate_VariableNotUnlimited
INTEGER, PARAMETER :: Coordinate_VariableIsUnlimited
INTEGER, PARAMETER :: Coordinate_InvalidVariableSize

END MODULE Coordinate_Class

Functions and Subroutines

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

This function checks whether the parameter this contains a valid Coordinate object. It may be applied to any Coordinate object at any time. A valid Coordinate object has a name and a unit.

SUBROUTINE initialize(this,description,length,name,unit,unlimited,values)
    TYPE(Coordinate),   INTENT(out)          :: this
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: description
    INTEGER,            INTENT(in), OPTIONAL :: length
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: name
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: unit
    LOGICAL,            INTENT(in), OPTIONAL :: unlimited
    REAL, DIMENSION(:), INTENT(in), OPTIONAL :: values

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

description: A text that gives a more detailed description of this coordinate axis than its name.
length: The number of values that are specified for this coordinate. Note that when the values parameter is also specified, the value of this parameter should be equal to the size of values.
name: The name of this coordinate axis. This name should not be the empty string.
unit: The unit in which the values of this coordinate axis are expressed. This unit should not be the empty string.
unlimited: When this parameter has the value .TRUE., the length of this coordinate can be increased. Otherwise, the length is fixed.
values: The values of this coordinate axis. Note that when the length parameter is also specified, the size of this parameter should be equal to the value of length.

A Coordinate object can also be initialized using the assignment operator.

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

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

This function compares two Coordinate objects. When the two objects are equal, the value .TRUE. is returned. Otherwise, the return value is .FALSE.. Two Coordinate object are equal when their names, descriptions, units, lengths, unlimitedness, and values are equal.
This function can also be invoked via the binary operator ==.

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

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

SUBROUTINE get(this,description,length,name,unit,unlimited,values)
    TYPE(Coordinate),   INTENT(in)            :: this
    CHARACTER(len=*),   INTENT(out), OPTIONAL :: description
    INTEGER,            INTENT(out), OPTIONAL :: length
    CHARACTER(len=*),   INTENT(out), OPTIONAL :: name
    CHARACTER(len=*),   INTENT(out), OPTIONAL :: unit
    LOGICAL,            INTENT(out), OPTIONAL :: unlimited
    REAL, DIMENSION(:), INTENT(out), OPTIONAL :: values

This subroutine retrieves information from the Coordinate object, this. The object is not modified. The optional parameters determine which information will be retrieved. This subroutine can be invoked without any parameters. In this case, the subroutine is as a no-op.

SUBROUTINE set(this,description,length,name,unit,unlimited,values)
    TYPE(Coordinate),   INTENT(inout)        :: this
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: description
    INTEGER,            INTENT(in), OPTIONAL :: length
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: name
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: unit
    LOGICAL,            INTENT(in), OPTIONAL :: unlimited
    REAL, DIMENSION(:), INTENT(in), OPTIONAL :: values

This subroutine modifies the Coordinate 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. Note that the name and unit parameters may not be set to the empty string.

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

This subroutine reads this Coordinate object using a file. The object can be read successfully when a one-dimensional variable with the name of the Coordinate object is present in the data file. 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 following error codes can be set:

Coordinate_InvalidDimensions

The file contains a variable with the given name but this variable does not have one dimension.

Coordinate_InvalidAttributeType

An attribute required by the COARDS conventions for NetCDF file was found but this attribute was of the wrong type.

Coordinate_InvalidAttributeSize

An attribute required by the COARDS conventions for NetCDF file was found but this attribute had the wrong size.

(See also the DataFile and Error classes.)

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

This subroutine writes the contents of this Coordinate 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 following error codes can be set:

Coordinate_DefinitionFailed

The object was not written to the file before. Therefore, it must be defined first. However, when attempting to do this, an error occured.

Coordinate_NotUnlimited

The content of an object with the same name but with a limited instead of unlimited length was written earlier to the file. This information cannot be replaced.

Coordinate_IsUnlimited

The content of an object with the same name but with an unlimited instead of limited length was written earlier to the file. This information cannot be replaced.

Coordinate_InvalidVariableSize

A similar object with a different length was written to the file before. This information cannot be replaced.

(See also the DataFile and Error classes.)

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

This subroutine is the equivalent of the Fortran PRINT statement. It prints the Coordinate 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(Coordinate), INTENT(in) :: this

This function allocates a one-dimensional array with a shape matching this Coordinate object and returns a pointer to this array.

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

This function retrieves the description of this Coordinate object.

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

This function returns the length of this Coordinate object. The return value zero indicates that the length of the object has not been set.

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

This function retrieves the name of this Coordinate object. This is the name that is used to identify the object in a data file.

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

This function retrieves the unit in which the values of this Coordinate object are expressed.

FUNCTION getValues(this) RESULT(result)
REAL, DIMENSION(1:getLength(this)) :: result
TYPE(Coordinate), INTENT(in) :: this

This function retrieves the values of this Coordinate object.

FUNCTION getValueAt(this,index) RESULT(result)
    REAL :: result
    TYPE(Coordinate), INTENT(in) :: this
    INTEGER,          INTENT(in) :: index

This function retrieves the coordinate value at the given index. The value of the index parameter should be in the range from 1 to getLength(this).

FUNCTION isUnlimited(this) RESULT(result)
LOGICAL :: result
TYPE(Coordinate), INTENT(in) :: this

This function checks whether this Coordinate object has an unlimited length and returns the result.

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

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

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

These functions compare two Coordinate objects or an one-dimensional real array and a Coordinate object for similarity. In the case of two Coordinate objects, the objects are similar when their lengths are equal. An array and a Coordinate object match when the size of the array equals the length of the Coordinate object.
An alternative way of invoking these functions is offered by the .matches. operator.

SUBROUTINE setValueAt(this,index,value)
    TYPE(Coordinate), INTENT(inout) :: this
    INTEGER,          INTENT(in)    :: index
    REAL,             INTENT(in)    :: value

This subroutine sets the coordinate value at the given index. The value of the index parameter should be in the range from 1 to getLength(this).

ASSIGNMENT (=) <left> = <right>

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

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

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

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

This operator compares two Coordinate objects or an one-dimensional real array and a Coordinate object for similarity. It is an alternative for using the matches functions.

Examples

The following example program shows how a Coordinate object can be written to and read from a file.

PROGRAM Coordinate_Class_Example
USE Coordinate_Class
USE DataFile_Class
USE Error_Class
IMPLICIT NONE

CHARACTER(len=*), PARAMETER :: filename    = "data.nc"
CHARACTER(len=*), PARAMETER :: description = "A sample coordinate axis"
CHARACTER(len=*), PARAMETER :: name        = "coord"
CHARACTER(len=*), PARAMETER :: unit        = "meter"
REAL, DIMENSION(1:4), &
       &            PARAMETER :: values      = (/ 1.0,2.0,3.0,4.0 /)

TYPE(Coordinate)   :: coord
TYPE(DataFile)     :: file
TYPE(Error)        :: err

CALL initialize(err)
CALL initialize(file,name=filename,type=NetCDFFile,err=err)
IF (isSet(err)) THEN
CALL print(err)
STOP "initialize(file)"
END IF

IF (isWriteable(file)) THEN
    CALL initialize(coord,name=name,unit=unit, &
       & description=description,unlimited=.FALSE., &
       & values=values)
    CALL write(coord,file,err)
    IF (isSet(err)) THEN
      CALL print(err)
      STOP "write(coord)"
    END IF
    PRINT*,"Wrote the following Coordinate object:"
    CALL print(coord)
    PRINT*,"Execute this program again"// &
        & " to read this object from the file"
ELSE
    CALL initialize(coord,name=name)
    CALL read(coord,file,err)
    IF (isSet(err)) THEN
      CALL print(err)
      STOP "read(coord)"
    END IF
    PRINT*,"Read the following Coordinate object:"
    CALL print(coord)
END IF

CALL finalize(coord)
CALL finalize(file,err=err)
IF (isSet(err)) THEN
CALL print(err)
STOP "finalize(coord)"
END IF
CALL finalize(err)
END PROGRAM Coordinate_Class_Example