dm_hdf5 Module

Abstraction layer around HDF5. Has to be linked against -lhdf5 and -lhdf5_fortran.

The module provides wrapper procedures to HDF5 in order to read and write derived types as 1-dimensional compound data sets. Only nodes, observations, sensors, and targets are supported.

The following example writes and reads eight empty observations as group timeseries to and from file sample.hdf5:

integer, parameter :: NOBSERVS = 8

integer                        :: rc
type(hdf5_file_type)           :: file
type(hdf5_group_type)          :: group
type(observ_type), allocatable :: input(:), output(:)

allocate (output(N))

! Initialise HDF5, create file and group.
rc = dm_hdf5_init()
rc = dm_hdf5_open(file, 'sample.hdf5', create=.true.)
rc = dm_hdf5_open(file, group, 'timeseries', create=.true.)

! Write array to file, then read array back from file.
rc = dm_hdf5_write(group, output)
rc = dm_hdf5_read(group, input)

! Clean-up.
rc = dm_hdf5_close(group)
rc = dm_hdf5_close(file)
rc = dm_hdf5_destroy()

References


Uses

  • module~~dm_hdf5~~UsesGraph module~dm_hdf5 dm_hdf5 hdf5 hdf5 module~dm_hdf5->hdf5 module~dm_error dm_error module~dm_hdf5->module~dm_error module~dm_kind dm_kind module~dm_hdf5->module~dm_kind module~dm_error->module~dm_kind module~dm_ascii dm_ascii module~dm_error->module~dm_ascii iso_fortran_env iso_fortran_env module~dm_kind->iso_fortran_env

Used by

  • module~~dm_hdf5~~UsedByGraph module~dm_hdf5 dm_hdf5 module~dmpack dmpack module~dmpack->module~dm_hdf5

Variables

Type Visibility Attributes Name Initial
character(len=*), public, parameter :: HDF5_DATASET_NODE = 'node_type'

Default name of node data set.
character(len=*), public, parameter :: HDF5_DATASET_OBSERV = 'observ_type'

Default name of observation data set.
character(len=*), public, parameter :: HDF5_DATASET_SENSOR = 'sensor_type'

Default name of sensor data set.
character(len=*), public, parameter :: HDF5_DATASET_TARGET = 'target_type'

Default name of target data set.
integer, public, parameter :: HDF5_RDONLY = 0

Read-only access.
integer, public, parameter :: HDF5_RDWR = 1

Read/write access.
integer, public, parameter :: HDF5_FILTER_DEFLATE = 1

gzip or deflate compression (H5Z_FILTER_DEFLATE).
integer, public, parameter :: HDF5_FILTER_SHUFFLE = 2

Shuffle algorithm (H5Z_FILTER_SHUFFLE).
integer, public, parameter :: HDF5_FILTER_FLETCHER32 = 3

Fletcher32 checksum (H5Z_FILTER_FLETCHER32).
integer, public, parameter :: HDF5_FILTER_SZIP = 4

SZIP compression (H5Z_FILTER_SZIP).

Interfaces

public interface dm_hdf5_close

Generic HDF5 close function.

  • private function hdf5_close_file(file) result(rc)

    Closes HDF5 file. Returns E_INVALID if the passed HDF5 file is not opened. Returns E_HDF5 if closing the file failed.

    Arguments

    Type IntentOptional Attributes Name
    type(hdf5_file_type), intent(inout) :: file

    HDF5 file type.

    Return Value integer

  • private function hdf5_close_group(group) result(rc)

    Closes HDF5 group. Returns E_INVALID if the passed HDF5 group is not opened. Returns E_HDF5 if closing the group failed.

    Arguments

    Type IntentOptional Attributes Name
    type(hdf5_group_type), intent(inout) :: group

    HDF5 group type.

    Return Value integer

public interface dm_hdf5_open

Generic HDF5 open function.

  • private function hdf5_open_file(file, path, mode, create) result(rc)

    Opens HDF5 file, by default in read/write access mode, unless mode is passed. If create is .true., a new file will be created.

    The function returns the following error codes:

    • E_EXIST if the file to create already exists.
    • E_HDF5 if opening or creating the file failed.
    • E_INVALID if the file is opened already or argument mode is invalid.
    • E_NOT_FOUND if the file was not found.

    Arguments

    Type IntentOptional Attributes Name
    type(hdf5_file_type), intent(out) :: file

    HDF5 file type.
    character(len=*), intent(in) :: path

    Path to HDF5 file.
    integer, intent(in), optional :: mode

    Open mode (HDF5_RDONLY or HDF5_RDWR).
    logical, intent(in), optional :: create

    Create HDF5 file.

    Return Value integer

  • private function hdf5_open_group(id, group, name, create) result(rc)

    Opens or creates group of name name. The function returns E_INVALID if the file is not opened, and E_HDF5 if the group operation failed.

    Arguments

    Type IntentOptional Attributes Name
    class(hdf5_id_type), intent(inout) :: id

    HDF5 file or group type.
    type(hdf5_group_type), intent(out) :: group

    HDF5 group type.
    character(len=*), intent(in) :: name

    Group name.
    logical, intent(in), optional :: create

    Create group.

    Return Value integer

public interface dm_hdf5_read

Generic HDF5 read function.

  • private function hdf5_read_nodes(id, nodes, data_set) result(rc)

    Reads array of node_type from compound data in HDF5 file. If data_set is not passed, the name will be set to the value of HDF5_DATASET_NODE.

    The function returns the following error codes:

    • E_INVALID if the passed id is invalid.
    • E_ALLOC if allocation of array nodes failed.
    • E_HDF5 if the HDF5 library call failed.

    Arguments

    Type IntentOptional Attributes Name
    class(hdf5_id_type), intent(inout) :: id

    HDF5 file or group type.
    type(node_type), intent(out), allocatable, target :: nodes(:)

    Node type array.
    character(len=*), intent(in), optional :: data_set

    Name of data set.

    Return Value integer

  • private function hdf5_read_observs(id, observs, data_set) result(rc)

    Reads array of observ_type from compound data in HDF5 file. If data_set is not passed, the name will be set to the value of HDF5_DATASET_OBSERV.

    The function returns the following error codes:

    • E_INVALID if the passed id is invalid.
    • E_ALLOC if allocation of array observs failed.
    • E_HDF5 if the HDF5 library call failed.

    Arguments

    Type IntentOptional Attributes Name
    class(hdf5_id_type), intent(inout) :: id

    HDF5 file or group type.
    type(observ_type), intent(out), allocatable, target :: observs(:)

    Observation type array.
    character(len=*), intent(in), optional :: data_set

    Name of data set.

    Return Value integer

  • private function hdf5_read_sensors(id, sensors, data_set) result(rc)

    Reads array of sensor_type from compound data in HDF5 file. If data_set is not passed, the name will be set to the value of HDF5_DATASET_SENSOR.

    The function returns the following error codes:

    • E_INVALID if the passed id is invalid.
    • E_ALLOC if allocation of array sensors failed.
    • E_HDF5 if the HDF5 library call failed.

    Arguments

    Type IntentOptional Attributes Name
    class(hdf5_id_type), intent(inout) :: id

    HDF5 file or group type.
    type(sensor_type), intent(out), allocatable, target :: sensors(:)

    Sensor type array.
    character(len=*), intent(in), optional :: data_set

    Name of data set.

    Return Value integer

  • private function hdf5_read_targets(id, targets, data_set) result(rc)

    Reads array of target_type from compound data in HDF5 file. If data_set is not passed, the name will be set to the value of HDF5_DATASET_TARGET.

    The function returns the following error codes:

    • E_INVALID if the passed id is invalid.
    • E_ALLOC if allocation of array targets failed.
    • E_HDF5 if the HDF5 library call failed.

    Arguments

    Type IntentOptional Attributes Name
    class(hdf5_id_type), intent(inout) :: id

    HDF5 file or group type.
    type(target_type), intent(out), allocatable, target :: targets(:)

    Target type array.
    character(len=*), intent(in), optional :: data_set

    Name of data set.

    Return Value integer

public interface dm_hdf5_write

Generic HDF5 write function.

  • private function hdf5_write_nodes(id, nodes, data_set) result(rc)

    Creates HDF5 data space and writes nodes to HDF5 file or group. If data_set is not passed, the name will be set to the value of HDF5_DATASET_NODE.

    The function returns the following error codes:

    • E_INVALID if the given HDF5 id type (file, group) is invalid.
    • E_EMPTY if the passed node array is of size 0.
    • E_HDF5 if the HDF5 library call failed.

    Arguments

    Type IntentOptional Attributes Name
    class(hdf5_id_type), intent(inout) :: id

    HDF5 file or group type.
    type(node_type), intent(inout), target :: nodes(:)

    Node type array.
    character(len=*), intent(in), optional :: data_set

    Name of data set.

    Return Value integer

  • private function hdf5_write_observs(id, observs, data_set) result(rc)

    Creates HDF5 data space and writes observations to HDF5 file or group. If data_set is not passed, the name will be set to the value of HDF5_DATASET_OBSERV.

    The function returns the following error codes:

    • E_INVALID if the given HDF5 id type (file, group) is invalid.
    • E_EMPTY if the passed observation array is of size 0.
    • E_HDF5 if the HDF5 library call failed.

    Arguments

    Type IntentOptional Attributes Name
    class(hdf5_id_type), intent(inout) :: id

    HDF5 file or group type.
    type(observ_type), intent(inout), target :: observs(:)

    Observation type array.
    character(len=*), intent(in), optional :: data_set

    Name of data set.

    Return Value integer

  • private function hdf5_write_targets(id, targets, data_set) result(rc)

    Creates HDF5 data space and writes targets to HDF5 file or group. If data_set is not passed, the name will be set to the value of HDF5_DATASET_TARGET.

    The function returns the following error codes:

    • E_INVALID if the given HDF5 id type (file, group) is invalid.
    • E_EMPTY if the passed target array is of size 0.
    • E_HDF5 if the HDF5 library call failed.

    Arguments

    Type IntentOptional Attributes Name
    class(hdf5_id_type), intent(inout) :: id

    HDF5 file or group type.
    type(target_type), intent(inout), target :: targets(:)

    Target type array.
    character(len=*), intent(in), optional :: data_set

    Name of data set.

    Return Value integer

  • private function hdf5_write_sensors(id, sensors, data_set) result(rc)

    Creates HDF5 data space and writes sensors to HDF5 file or group. If data_set is not passed, the name will be set to the value of HDF5_DATASET_SENSOR.

    The function returns the following error codes:

    • E_INVALID if the given HDF5 id type (file, group) is invalid.
    • E_EMPTY if the passed sensor array is of size 0.
    • E_HDF5 if the HDF5 library call failed.

    Arguments

    Type IntentOptional Attributes Name
    class(hdf5_id_type), intent(inout) :: id

    HDF5 file or group type.
    type(sensor_type), intent(inout), target :: sensors(:)

    Sensor type array.
    character(len=*), intent(in), optional :: data_set

    Name of data set.

    Return Value integer


Derived Types

type, public, extends(../../hdf5_id_type) ::  hdf5_file_type

Opaque HDF5 file type.

type, public, extends(../../hdf5_id_type) ::  hdf5_group_type

Opaque HDF5 group type.


Functions

public function dm_hdf5_destroy() result(rc)

Destroys HDF5 Fortran interface. Returns E_HDF5 on error.

Arguments

None

Return Value integer

public function dm_hdf5_file_free(file, free_space) result(rc)

Returns amount of free space within a file in argument free_space.

Read more…

Arguments

Type IntentOptional Attributes Name
type(hdf5_file_type), intent(inout) :: file

HDF5 file type.
integer(kind=i8), intent(out) :: free_space

Free space in bytes.

Return Value integer

public function dm_hdf5_file_is_valid(path) result(is)

Returns .true. if file at given path is a valid HDF5 file.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: path

File path.

Return Value logical

public function dm_hdf5_file_path(file, path, n) result(rc)

Returns file path of given HDF5 file in path. The argument path must be large enough to hold the full path. The actual length is returned in optional argument n.

Read more…

Arguments

Type IntentOptional Attributes Name
type(hdf5_file_type), intent(inout) :: file

HDF5 file type.
character(len=*), intent(inout) :: path

Path of HDF5 file.
integer, intent(out), optional :: n

Path length.

Return Value integer

public function dm_hdf5_has_filter(filter, error) result(available)

Returns the status of the given filter. The following filters are supported:

Read more…

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: filter

Filter enumerator.
integer, intent(out), optional :: error

Error code.

Return Value logical

public function dm_hdf5_group_exists(id, name, error) result(exists)

Returns .true. if group of given name name exists in file or group id. The function returns the following error codes in error:

Read more…

Arguments

Type IntentOptional Attributes Name
class(hdf5_id_type), intent(inout) :: id

HDF5 file or group type.
character(len=*), intent(in) :: name

Group name.
integer, intent(out), optional :: error

Error code.

Return Value logical

public function dm_hdf5_init() result(rc)

Initialises HDF5 Fortran interface. The function returns E_HDF5 on error.

Arguments

None

Return Value integer

public function dm_hdf5_version(name) result(version)

Returns HDF5 library version as allocatable string.

Arguments

Type IntentOptional Attributes Name
logical, intent(in), optional :: name

Add prefix libhdf5/.

Return Value character(len=:), allocatable

public function dm_hdf5_version_number(major, minor, release) result(rc)

Returns version numbers of HDF5 library. The function returns E_HDF5 on error.

Arguments

Type IntentOptional Attributes Name
integer, intent(out), optional :: major

Major version of HDF5 library.
integer, intent(out), optional :: minor

Minor version of HDF5 library.
integer, intent(out), optional :: release

Release version of HDF5 library.

Return Value integer