# H5part, the Fortran API
Keywords: scientific visualization

# The FORTRAN Application Programming Interface (API)

These references contain the information on how to access the H5Part API using FORTRAN bindings. All pointers are cast to haddr_t (a unint64_t) within the C/C++ code. In fortran, these pointers (handles) are carried as INTEGER*8

- Opening, Closing, and Validating Datafiles
- Setting the Simulation Timestep
- Setting the Number of Particles
- Writing Datasets
- Reading the Number of Time Steps
- Reading the Number of Particles
- Reading Datasets
- Reading the Number and the Names of Datasets
- Attributes Interface
- Writing Additional Attributes
- Reading Attributes

## Opening Datafiles

Like the familiar OPEN in FORTRAN files can be opened to read and write. Different functions are used for the serial and parallel case.

FORTRAN Prototypes

Serial File
`INTEGER*8 h5pt_openr`
`FUNCTION h5pt_openw(file)
in CHARACTER file(*) : the filename to open for writing`
returns INTEGER*8 : and open filehandle for serial reads
`INTEGER*8 h5pt_openw`
`FUNCTION h5pt_openw(file)
in CHARACTER file(*) : the filename to open for writing
returns INTEGER*8 : and open filehandle for serial writes`
Parallel File
`INTEGER*8 h5pt_openr_par`
`FUNCTION h5pt_openr_par(file,mpi_communicator)
in CHARACTER file(*) : the filename to open for writing
in INTEGER mpi_communicator : the MPI_Communicator used by the program
returns INTEGER*8 : and open filehandle for parallel reads`
`INTEGER*8 h5pt_openw_par`
`FUNCTION h5pt_openw_par(file,mpi_communicator)
in CHARACTER file(*) : the filename to open for writing
in INTEGER mpi_communicator : the MPI_Communicator used by the program
returns INTEGER*8 : and open filehandle for parallel reads`

Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    ...
    file = h5pt_openw("testfilef.h5")
    ...

## Closing Datafiles

To close the file, you simply use h5pt_close() for both parallel and serial files. You must call h5pt_close() on any file descriptor created by h5pt_open*() regardless of whether the file turns out to be valid or not.

FORTRAN Prototype
`EXTERNAL h5pt_close`
`SUBROUTINE h5pt_close(filehandle)
in INTEGER*8 filehandle : close this open filehandle`
Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    ...
    call h5pt_close(file)
    ...

## Validating Datafiles

You can test if the file was opened successfully using the h5p_isvalid() function. It returns 1 if valid, 0 if invalid.

FORTRAN Prototype
`INTEGER h5pt_isvalid`
`FUNCTION h5pt_isvalid(filehandle)
in INTEGER*8 filehandle: an open filehandle
returns INTEGER : 1 if the file is valid, 0 if it is not`
Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    INTEGER status
    ...
    status = h5pt_isvalid(file)
    ...

## Setting the Timestep

When writing data to a file the current time step must be set (even if there is only one). In a file with N time steps, the steps are numbered from 0 to N-1.

FORTRAN Prototype
`EXTERNAL h5pt_setstep`
`SUBROUTINE h5pt_setstep(filehandle,step)
in INTEGER*8 filehandle : an open filehandle
in INTEGER step : Set the current timestep in the file to this`
Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    INTEGER I
    INTEGER nstep
    ...
    do I=1,nstep
    	call h5pt_setstep(file,I)
    ... more code ...
    enddo

## Setting the Number of Particles

This function's sole purpose is to prevent needless creation of new HDF5 DataSpace handles if the number of particles is invariant throughout the sim. That's its only reason for existence. After you call this subroutine, all subsequent operations will assume this number of particles will be written.

FORTRAN Prototype
`EXTERNAL h5pt_setnpoints`
`SUBROUTINE h5pt_setnpoints(filehandle,npoints)
in INTEGER*8 filehandle : an open filehandle
in INTEGER*8 npoints : The number of particles on *this* processor`
Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    INTEGER*8 npoints

    ...
    call h5pt_setnpoints(file,npoints)
    ...

## Writing Datasets

After setting the number of particles with h5pt_setnpoints() and the current timestep using h5pt_setstep(), you can start writing datasets into the file. Each dataset has a name associated with it (chosen by the user) in order to facilitate later retrieval. The writing routines also implicitly store the datatype of the array so that the array can be reconstructed properly on other systems with incompatible type representations. The data is committed to disk before the routine returns. All data that is written after setting the timestep is associated with that timestep. While the number of particles can change for each timestep, you cannot change the number of particles in the middle of a given timestep.

FORTRAN Prototypes

The two data types supported for the moment are REAL*8 and INTEGER*8 (float64 and int64).

`EXTERNAL h5pt_writedata_r8`
`SUBROUTINE h5pt_writedata_r8(filehandle,name,data)
in INTEGER*8 filehandle : an open filehandle
in CHARACTER name(*) : The name of the data we are writing eg. "X" or "Y" or "PX" etc...
in REAL*8 data(*) : The dataarray to write`
`EXTERNAL h5pt_writedata_i8`
`SUBROUTINE h5pt_writedata_i8(filehandle,name,data)
in INTEGER*8 filehandle : an open filehandle
in CHARACTER name(*) : The name of the data we are writing eg. "X" or "Y" or "PX" etc...
in INTEGER*8 data(*) : The dataarray to write`
Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    INTEGER nstep
    INTEGER I
    REAL*8,ALLOCATABLE:: X(:)

    ...
    do I=1,nstep
    	call h5pt_setstep(file,I)
    	call h5pt_writedata_r8(file,"x",X)
    enddo
    ...

## Reading the Number of Time Steps

This reads the number of datasteps that are currently stored in the datafile. It works for both reading and writing of files, but is probably only typically used when you are reading.

FORTRAN Prototypes
`INTEGER h5pt_getnsteps`
`FUNCTION h5pt_getnsteps(filehandle)
in INTEGER*8 filehandle : an open filehandle
returns INTEGER : number of timesteps stored in the file`
Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    INTEGER nstep

    file = h5pt_openr("testfilef.h5")
    nstep = h5pt_getnsteps(file)

## Reading the Number of Particles

This reads the number of particles that are currently stored in the current time step. It will arbitrarily select a timestep if you haven't already set the timestep with H5PartSetStep().

FORTRAN Prototypes
`INTEGER h5pt_getnpointss`
`FUNCTION h5pt_getnpoints(filehandle)
in INTEGER*8 filehandle : an open filehandle
returns INTEGER : number of particles in the current time step`
Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    INTEGER*8 npoints
    INTEGET step;

    file = h5pt_openr("testfilef.h5")
    call h5pt_setstep(file,0)
    npoints = h5pt_getnpoints(file)
    ...

## Reading Datasets

After setting the time step and getting the number of particles to allocate the data arrays, you can start to read the data.

FORTRAN Prototypes
`INTEGER h5pt_readdata_r8`
`FUNCTION h5pt_readdata_r8(filehandle,name,data)
in INTEGER*8 filehandle : an open filehandle
in CHARACTER name(*) : The name of the data we are writing, eg. "X" or "Y" or "PX" etc...
out REAL*8 data(*) : The data array to read. The number of points to read is either the number within the view setby h5pt_setview() or the default (the total number of particles in the file).
Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    INTEGER err
    INTEGER*8,ALLOCATABLE:: ID(:)

    ...
    call h5pt_setstep(file,step)
    err=h5pt_readdata_i8(file,"id",ID)
    ...

## Reading the Number and Names of Datasets

H5Part provides funtions to find out how many datasets are stored at a particular timestep and what their names are if you don't know what they are a-priori.

FORTRAN Prototypes
`INTEGER h5pt_getndatasets`
`FUNCTION h5pt_getndatasets(filehandle)
in INTEGER*8 filehandle : an open filehandle
returns INTEGER*8 : number of datasets stored per timestep`
Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    INTEGER ndata

    ...
    call h5pt_setstep(file,1)
    ndata = h5pt_getndatasets(file)
    ...

FORTRAN Prototypes
`INTEGER h5pt_getdatasetname`
`FUNCTION h5pt_getdatasetname(filehandle,index,name)
in INTEGER*8 filehandle : an open filehandle
in INTEGER index : Index for a given dataset name
out CHARACTER name(*) returns the name of the dataset at that index
returns INTEGER, 1 on success 0 on failure.`
Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    INTEGER err
    CHARACTER,ALLOCATABLE:: name(:)

    ...
    err=h5pt_getdatasetname(file, 1, name)
    ...

## Attributes Interface

In the current H5Part implemtation there are two types of attributes: file attributes which are bound to the file and step attributes which are bound to the current timestep. You must set the timestep explicitly before writing the attributes (just as you must do when you write a new dataset. Currently there are no attributes that are bound to a particular data array, but this could easily be done if required.

FORTRAN Prototypes
`INTEGER h5pt_getnstepattribs`
`FUNCTION h5pt_getnstepattribs(filehandle)
in INTEGER*8 filehandle : an open filehandle
returns INTEGER : number of attributes bound to this particular step
`
`INTEGER h5pt_getnfileattribs`
`FUNCTION h5pt_getnfileattribs(filehandle)
in INTEGER*8 filehandle : an open filehandle
returns INTEGER : number of attributes bound to the file
`
`INTEGER h5pt_getstepattribinfo`
`FUNCTION h5pt_getstepattribinfo(filehandle,idx,attribname,nelem)
in INTEGER*8 filehandle : an open filehandle
in INTEGER idx : index of the attribute being queried
out CHARACTER name(*) : The name of the attribute
out INTEGER nelem : Number of elements in the attrib array
returns INTEGER, 1 on success 0 on failure.
`
`INTEGER h5pt_getfileattribinfo`
`FUNCTION h5pt_getfileattribinfo(filehandle,idx,attribname,nelem)
in INTEGER*8 filehandle : an open filehandle
in INTEGER idx : index of the attribute being queried
out CHARACTER name(*) : The name of the attribute
out INTEGER nelem : Number of elements in the attrib array
returns INTEGER, 1 on success 0 on failure.`

## Writing Attributes

An attribute can be bound to the file or after setting the time step to this time step.

FORTRAN Prototypes
`INTEGER h5pt_writefileattrib_r8`
`FUNCTION h5pt_writefileattrib_r8(filehandle,name,attrib,nelem)
in INTEGER*8 filehandle : an open filehandle
in CHARACTER name(*) : The name of the attribute
in REAL*8 attrib(*) : The array of data to write into the attribute
in INTEGER nelem : Number of elements in the attrib array
returns INTEGER, 1 on success 0 on failure
`
`INTEGER h5pt_writefileattrib_i8`
`FUNCTION h5pt_writefileattrib_i8(filehandle,name,attrib,nelem)
in INTEGER*8 filehandle : The filehandle
in CHARACTER name(*) : The name of the attribute
in INTEGER*8 attrib(*) : The array of data to write into the attribute
in INTEGER nelem : Number of elements in the attrib array
returns INTEGER, 1 on success 0 on failure
`
`INTEGER h5pt_writefileattrib_string`
`FUNCTION h5pt_writefileattrib_string(filehandle,name,string)
in INTEGER*8 filehandle : an open filehandle
in CHARACTER name(*) : The name of the attribute
in CHARACTER*8 attrib(*) : The array of data to write into the attribute
returns INTEGER, 1 on success 0 on failure
`
`INTEGER h5pt_writestepattrib_r8`
`FUNCTION h5pt_writestepattrib_r8(filehandle,name,attrib,nelem)
in INTEGER*8 filehandle : an open filehandle
in CHARACTER name(*) : The name of the attribute
in REAL*8 attrib(*) : The array of data to write into the attribute
in INTEGER nelem : Number of elements in the attrib array returns INTEGER, 1 on success 0 on failure
`
`INTEGER h5pt_writestepattrib_i8`
`FUNCTION h5pt_writestepattrib_i8(filehandle,name,attrib,nelem)
in INTEGER*8 filehandle : an open filehandle
in CHARACTER name(*) : The name of the attribute
in INTEGER*8 attrib(*) : The array of data to write into the attribute
in INTEGER nelem : Number of elements in the attrib array
returns INTEGER, 1 on success 0 on failure
`
`INTEGER h5pt_writestepattrib_string`
`FUNCTION h5pt_writestepattrib_string(filehandle,name,string)
in INTEGER*8 filehandle : an open filehandle
in CHARACTER name(*) : The name of the attribute
in CHARACTER*8 attrib(*) : The array of data to write into the attribute
returns INTEGER, 1 on success 0 on failure
` Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    REAL*8 REALTIME
    INTEGER err

    ...
    err=h5pt_writefileattrib_string(file,"Annotation","Testing 1 2 3")
    err=h5pt_writestepattrib_r8(file,"RealTime",REALTIME,1)
    ...

## Reading Attributes

As with the writing of attributes, there are two basic reading interfaces one that reads file bound attributes and one that reads step bound attributes. If the step is not set the current one will be used.

FORTRAN Prototypes
`INTEGER h5pt_readstepattrib`
`FUNCTION h5pt_readstepattrib(filehandle,name,data)
in INTEGER*8 filehandle : an open filehandle
in CHARACTER attributename(*) : name of the attribute to read
out <anytype> data(*) : the attribute data will be read into this array
returns INTEGER, 1 on success 0 on failure
`
`INTEGER h5pt_readfileattrib`
`FUNCTION h5pt_readfileattrib(filehandle,name,data)
in INTEGER*8 filehandle an open filehandle
in CHARACTER attributename(*) : name of the attribute to read
out <anytype> data(*) : the attribute data will be read into this array
returns INTEGER, 1 on success 0 on failure
` Example Use

    include 'H5Part.inc'
    INTEGER*8 file
    REAL*8 REALTIME

    ...
    call h5pt_setstep(file,0)
    err=h5pt_readstepattrib(file,"RealTime",data)
    ...

`