501 lines
16 KiB
HTML
Executable File
501 lines
16 KiB
HTML
Executable File
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>H5part, the Fortran API</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
|
<meta name="keywords" content="scientific visualization">
|
|
<meta name="sitemap" content="put a brief descriptive phrase here that will show up in the site map:foo">
|
|
|
|
<div id="maincenter">
|
|
|
|
|
|
<h1>The FORTRAN Application Programming Interface (API)</h1>
|
|
<P>
|
|
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
|
|
</P>
|
|
<UL>
|
|
<LI><a href="#Opening">Opening, Closing, and Validating Datafiles</a>
|
|
<LI><a href="#SetStep">Setting the Simulation Timestep</a>
|
|
<LI><a href="#SetNumParticles">Setting the Number of Particles</a>
|
|
<LI><a href="#Writing">Writing Datasets</a>
|
|
<LI><a href="#ReadingNumTimeSteps">Reading the Number of Time Steps</a>
|
|
<LI><a href="#ReadingNumTimeSteps">Reading the Number of Particles</a>
|
|
<LI><a href="#Reading">Reading Datasets</a>
|
|
<LI><a href="#DatasetsInfo">Reading the Number and the Names of Datasets</a>
|
|
<LI><a href="#AttributesInfo">Attributes Interface</a>
|
|
<LI><a href="#WriteAttribs">Writing Additional Attributes</a>
|
|
<LI><a href="#ReadAttribs">Reading Attributes</a>
|
|
</UL>
|
|
<hr>
|
|
<a name="Opening"><h2>Opening Datafiles</h2></a>
|
|
<P>
|
|
Like the familiar OPEN in FORTRAN files can be opened to read and write. Different functions are used for the serial and parallel case.
|
|
</P>
|
|
<b>FORTRAN Prototypes</b><br>
|
|
<P>
|
|
<b>Serial File</b><br>
|
|
<code>INTEGER*8 h5pt_openr</code><br>
|
|
<code>FUNCTION h5pt_openw(file)<br>
|
|
in CHARACTER file(*) : the filename to open for writing </code><br>
|
|
returns INTEGER*8 : and open filehandle for serial reads</code><br>
|
|
<br>
|
|
<code>INTEGER*8 h5pt_openw</code><br>
|
|
<code>FUNCTION h5pt_openw(file)<br>
|
|
in CHARACTER file(*) : the filename to open for writing<br>
|
|
returns INTEGER*8 : and open filehandle for serial writes</code><br>
|
|
<br>
|
|
<b>Parallel File</b><br>
|
|
<code>INTEGER*8 h5pt_openr_par</code><br>
|
|
<code>FUNCTION h5pt_openr_par(file,mpi_communicator)<br>
|
|
in CHARACTER file(*) : the filename to open for writing<br>
|
|
in INTEGER mpi_communicator : the MPI_Communicator used by the program<br>
|
|
returns INTEGER*8 : and open filehandle for parallel reads</code><br>
|
|
<br>
|
|
<code>INTEGER*8 h5pt_openw_par</code><br>
|
|
<code>FUNCTION h5pt_openw_par(file,mpi_communicator)<br>
|
|
in CHARACTER file(*) : the filename to open for writing<br>
|
|
in INTEGER mpi_communicator : the MPI_Communicator used by the program<br>
|
|
returns INTEGER*8 : and open filehandle for parallel reads</code><br>
|
|
</P>
|
|
<P>
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
include 'H5Part.inc'
|
|
INTEGER*8 file
|
|
...
|
|
file = h5pt_openw("testfilef.h5")
|
|
...
|
|
</pre>
|
|
</P>
|
|
<hr>
|
|
<h2>Closing Datafiles</h2>
|
|
<P>
|
|
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.</P>
|
|
<b>FORTRAN Prototype</b><br>
|
|
<code>EXTERNAL h5pt_close</code><br>
|
|
<code>SUBROUTINE h5pt_close(filehandle)<br>
|
|
in INTEGER*8 filehandle : close this open filehandle</code><br>
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
include 'H5Part.inc'
|
|
INTEGER*8 file
|
|
...
|
|
call h5pt_close(file)
|
|
...
|
|
</pre>
|
|
</P>
|
|
<hr>
|
|
<h2> Validating Datafiles</h2>
|
|
<P>
|
|
You can test if the file was opened successfully using the
|
|
h5p_isvalid() function. It returns 1 if valid, 0 if invalid.
|
|
</P>
|
|
<b>FORTRAN Prototype</b><br>
|
|
<code>INTEGER h5pt_isvalid</code><br>
|
|
<code>FUNCTION h5pt_isvalid(filehandle)<br>
|
|
in INTEGER*8 filehandle: an open filehandle <br>
|
|
returns INTEGER : 1 if the file is valid, 0 if it is not</code><br>
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
include 'H5Part.inc'
|
|
INTEGER*8 file
|
|
INTEGER status
|
|
...
|
|
status = h5pt_isvalid(file)
|
|
...
|
|
</pre>
|
|
</P>
|
|
<hr>
|
|
<a name="SetStep">
|
|
<h2>Setting the Timestep</h2>
|
|
</a>
|
|
<P>
|
|
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.
|
|
</P>
|
|
<b>FORTRAN Prototype</b><br>
|
|
<code>EXTERNAL h5pt_setstep</code><br>
|
|
<code>SUBROUTINE h5pt_setstep(filehandle,step)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in INTEGER step : Set the current timestep in the file to this
|
|
</code><br>
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
include 'H5Part.inc'
|
|
INTEGER*8 file
|
|
INTEGER I
|
|
INTEGER nstep
|
|
...
|
|
do I=1,nstep
|
|
call h5pt_setstep(file,I)
|
|
... more code ...
|
|
enddo
|
|
</pre>
|
|
</P>
|
|
<hr>
|
|
|
|
<a name="SetNumParticles">
|
|
</a>
|
|
<h2>Setting the Number of Particles</h2>
|
|
<P>
|
|
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.
|
|
</P>
|
|
<b>FORTRAN Prototype</b><br>
|
|
<code>EXTERNAL h5pt_setnpoints</code><br>
|
|
<code>SUBROUTINE h5pt_setnpoints(filehandle,npoints)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in INTEGER*8 npoints : The number of particles on *this* processor</code><br>
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
include 'H5Part.inc'
|
|
INTEGER*8 file
|
|
INTEGER*8 npoints
|
|
|
|
...
|
|
call h5pt_setnpoints(file,npoints)
|
|
...
|
|
</pre>
|
|
|
|
<hr>
|
|
<a name="Writing">
|
|
<h2>Writing Datasets</h2>
|
|
</a>
|
|
<P>
|
|
After setting the number of particles with
|
|
<a href="#SetNumParticles">h5pt_setnpoints()</a>
|
|
and the current timestep using
|
|
<a href="#SetStep">h5pt_setstep()</a>, 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.
|
|
</P>
|
|
<b>FORTRAN Prototypes</b><br>
|
|
<P>
|
|
The two data types supported for the moment are REAL*8 and INTEGER*8 (float64 and int64).
|
|
</P>
|
|
<code>EXTERNAL h5pt_writedata_r8</code><br>
|
|
<code>SUBROUTINE h5pt_writedata_r8(filehandle,name,data)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in CHARACTER name(*) : The name of the data we are writing eg. "X" or "Y" or "PX" etc...<br>
|
|
in REAL*8 data(*) : The dataarray to write</code><br>
|
|
<br>
|
|
<code>EXTERNAL h5pt_writedata_i8</code><br>
|
|
<code>SUBROUTINE h5pt_writedata_i8(filehandle,name,data)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in CHARACTER name(*) : The name of the data we are writing eg. "X" or "Y" or "PX" etc...<br>
|
|
in INTEGER*8 data(*) : The dataarray to write</code><br>
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
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
|
|
...
|
|
</pre>
|
|
<hr>
|
|
<a name="ReadingNumTimeSteps">
|
|
<h2>Reading the Number of Time Steps</h2>
|
|
</a>
|
|
<P>
|
|
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.
|
|
|
|
</P>
|
|
<b>FORTRAN Prototypes</b><br>
|
|
<code>INTEGER h5pt_getnsteps</code><br>
|
|
<code>FUNCTION h5pt_getnsteps(filehandle)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
returns INTEGER : number of timesteps stored in the file</code><br>
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
include 'H5Part.inc'
|
|
INTEGER*8 file
|
|
INTEGER nstep
|
|
|
|
file = h5pt_openr("testfilef.h5")
|
|
nstep = h5pt_getnsteps(file)
|
|
</pre>
|
|
<hr>
|
|
|
|
<a name="ReadingNumParticles">
|
|
<h2>Reading the Number of Particles</h2>
|
|
</a>
|
|
<P>
|
|
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().
|
|
|
|
</P>
|
|
<b>FORTRAN Prototypes</b><br>
|
|
<code>INTEGER h5pt_getnpointss</code><br>
|
|
<code>FUNCTION h5pt_getnpoints(filehandle)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
returns INTEGER : number of particles in the current time step</code><br>
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
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)
|
|
...
|
|
</pre>
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
<a name="Reading">
|
|
<h2>Reading Datasets</h2>
|
|
</a>
|
|
<P>
|
|
After setting the time step and getting the number of particles to allocate the data arrays, you can start to read the data.
|
|
</P>
|
|
<b>FORTRAN Prototypes</b><br>
|
|
<code>INTEGER h5pt_readdata_r8</code><br>
|
|
<code>FUNCTION h5pt_readdata_r8(filehandle,name,data)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in CHARACTER name(*) : The name of the data we are writing, eg. "X" or "Y" or "PX" etc...<br>
|
|
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).<br>
|
|
|
|
|
|
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
include 'H5Part.inc'
|
|
INTEGER*8 file
|
|
INTEGER err
|
|
INTEGER*8,ALLOCATABLE:: ID(:)
|
|
|
|
...
|
|
call h5pt_setstep(file,step)
|
|
err=h5pt_readdata_i8(file,"id",ID)
|
|
...
|
|
</pre>
|
|
<hr>
|
|
<a name="DatasetsInfo"><h2>Reading the Number and Names of Datasets</h2></a>
|
|
<P>
|
|
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.
|
|
</P>
|
|
<b>FORTRAN Prototypes</b><br>
|
|
<code>INTEGER h5pt_getndatasets</code><br>
|
|
<code>FUNCTION h5pt_getndatasets(filehandle)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
returns INTEGER*8 : number of datasets stored per timestep</code><br>
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
include 'H5Part.inc'
|
|
INTEGER*8 file
|
|
INTEGER ndata
|
|
|
|
...
|
|
call h5pt_setstep(file,1)
|
|
ndata = h5pt_getndatasets(file)
|
|
...
|
|
|
|
</pre>
|
|
<b>FORTRAN Prototypes</b><br>
|
|
<code>INTEGER h5pt_getdatasetname</code><br>
|
|
<code>FUNCTION h5pt_getdatasetname(filehandle,index,name)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in INTEGER index : Index for a given dataset name<br>
|
|
out CHARACTER name(*) returns the name of the dataset at that index<br>
|
|
returns INTEGER, 1 on success 0 on failure.</code><br>
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
include 'H5Part.inc'
|
|
INTEGER*8 file
|
|
INTEGER err
|
|
CHARACTER,ALLOCATABLE:: name(:)
|
|
|
|
...
|
|
err=h5pt_getdatasetname(file, 1, name)
|
|
...
|
|
</pre>
|
|
<hr>
|
|
|
|
<a name="AttributesInfo">
|
|
<h2>Attributes Interface</h2></a>
|
|
<P>
|
|
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.
|
|
</P>
|
|
<b>FORTRAN Prototypes</b><br>
|
|
<code>INTEGER h5pt_getnstepattribs</code><br>
|
|
<code>FUNCTION h5pt_getnstepattribs(filehandle)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
returns INTEGER : number of attributes bound to this particular step<br>
|
|
</code>
|
|
<br>
|
|
<code>INTEGER h5pt_getnfileattribs</code><br>
|
|
<code>FUNCTION h5pt_getnfileattribs(filehandle)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
returns INTEGER : number of attributes bound to the file<br>
|
|
</code>
|
|
<br>
|
|
<code>INTEGER h5pt_getstepattribinfo</code><br>
|
|
<code>FUNCTION h5pt_getstepattribinfo(filehandle,idx,attribname,nelem)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in INTEGER idx : index of the attribute being queried<br>
|
|
out CHARACTER name(*) : The name of the attribute<br>
|
|
out INTEGER nelem : Number of elements in the attrib array<br>
|
|
returns INTEGER, 1 on success 0 on failure.<br>
|
|
</code>
|
|
<br>
|
|
<code>INTEGER h5pt_getfileattribinfo</code><br>
|
|
<code>FUNCTION h5pt_getfileattribinfo(filehandle,idx,attribname,nelem)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in INTEGER idx : index of the attribute being queried<br>
|
|
out CHARACTER name(*) : The name of the attribute<br>
|
|
out INTEGER nelem : Number of elements in the attrib array<br>
|
|
returns INTEGER, 1 on success 0 on failure.
|
|
</code>
|
|
<br>
|
|
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
<a name="WriteAttribs">
|
|
<h2>Writing Attributes</h2>
|
|
</a>
|
|
<P>
|
|
An attribute can be bound to the file or after setting the time step to this time step.
|
|
</P>
|
|
<b>FORTRAN Prototypes</b><br>
|
|
<code>INTEGER h5pt_writefileattrib_r8</code><br>
|
|
<code>
|
|
FUNCTION h5pt_writefileattrib_r8(filehandle,name,attrib,nelem)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in CHARACTER name(*) : The name of the attribute<br>
|
|
in REAL*8 attrib(*) : The array of data to write into the attribute<br>
|
|
in INTEGER nelem : Number of elements in the attrib array<br>
|
|
returns INTEGER, 1 on success 0 on failure<br>
|
|
</code>
|
|
<br>
|
|
<code>INTEGER h5pt_writefileattrib_i8</code><br>
|
|
<code>FUNCTION h5pt_writefileattrib_i8(filehandle,name,attrib,nelem)<br>
|
|
in INTEGER*8 filehandle : The filehandle<br>
|
|
in CHARACTER name(*) : The name of the attribute<br>
|
|
in INTEGER*8 attrib(*) : The array of data to write into the attribute<br>
|
|
in INTEGER nelem : Number of elements in the attrib array<br>
|
|
returns INTEGER, 1 on success 0 on failure<br>
|
|
</code>
|
|
<br>
|
|
<code>INTEGER h5pt_writefileattrib_string</code><br>
|
|
<code>FUNCTION h5pt_writefileattrib_string(filehandle,name,string)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in CHARACTER name(*) : The name of the attribute<br>
|
|
in CHARACTER*8 attrib(*) : The array of data to write into the attribute<br>
|
|
returns INTEGER, 1 on success 0 on failure<br>
|
|
</code>
|
|
<br>
|
|
<code>INTEGER h5pt_writestepattrib_r8</code><br>
|
|
<code>FUNCTION h5pt_writestepattrib_r8(filehandle,name,attrib,nelem)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in CHARACTER name(*) : The name of the attribute<br>
|
|
in REAL*8 attrib(*) : The array of data to write into the attribute<br>
|
|
in INTEGER nelem : Number of elements in the attrib array
|
|
returns INTEGER, 1 on success 0 on failure<br>
|
|
</code>
|
|
<br>
|
|
<code>INTEGER h5pt_writestepattrib_i8</code><br>
|
|
<code>FUNCTION h5pt_writestepattrib_i8(filehandle,name,attrib,nelem)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in CHARACTER name(*) : The name of the attribute<br>
|
|
in INTEGER*8 attrib(*) : The array of data to write into the attribute<br>
|
|
in INTEGER nelem : Number of elements in the attrib array<br>
|
|
returns INTEGER, 1 on success 0 on failure<br>
|
|
</code>
|
|
<br>
|
|
<code>INTEGER h5pt_writestepattrib_string</code><br>
|
|
<code>FUNCTION h5pt_writestepattrib_string(filehandle,name,string)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in CHARACTER name(*) : The name of the attribute<br>
|
|
in CHARACTER*8 attrib(*) : The array of data to write into the attribute<br>
|
|
returns INTEGER, 1 on success 0 on failure<br>
|
|
</code>
|
|
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
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)
|
|
...
|
|
|
|
</pre>
|
|
|
|
<hr>
|
|
<a name="ReadAttribs">
|
|
<h2>Reading Attributes</h2>
|
|
</a>
|
|
<P>
|
|
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.
|
|
</P>
|
|
<b>FORTRAN Prototypes</b><br>
|
|
|
|
<code>INTEGER h5pt_readstepattrib</code><br>
|
|
<code>FUNCTION h5pt_readstepattrib(filehandle,name,data)<br>
|
|
in INTEGER*8 filehandle : an open filehandle<br>
|
|
in CHARACTER attributename(*) : name of the attribute to read<br>
|
|
out <anytype> data(*) : the attribute data will be read into this array<br>
|
|
returns INTEGER, 1 on success 0 on failure<br>
|
|
</code>
|
|
<br>
|
|
<code>INTEGER h5pt_readfileattrib</code><br>
|
|
<code>FUNCTION h5pt_readfileattrib(filehandle,name,data)<br>
|
|
in INTEGER*8 filehandle an open filehandle<br>
|
|
in CHARACTER attributename(*) : name of the attribute to read<br>
|
|
out <anytype> data(*) : the attribute data will be read into this array<br>
|
|
returns INTEGER, 1 on success 0 on failure<br>
|
|
</code>
|
|
|
|
<b>Example Use</b><br>
|
|
<pre>
|
|
include 'H5Part.inc'
|
|
INTEGER*8 file
|
|
REAL*8 REALTIME
|
|
|
|
...
|
|
call h5pt_setstep(file,0)
|
|
err=h5pt_readstepattrib(file,"RealTime",data)
|
|
...
|
|
</pre>
|
|
|
|
|
|
</div>
|