4.11.2. API Functions

When an API function is called that fills in an array, the array must already be allocated. The path used in all of these functions is the path to the geometric path folder.

Writing

These functions are used to store the properties and attributes of a geometric path group. Anyone using this API to read the geometric path group will have to know this in order to properly allocate their arrays.

The function xfCreateGeometricPath group creates the location in the HDF5 file to store the geometric path group. This function requires a GUID because we use GUIDs to match datasets to spatial objects. The NullLoc argument must be an array of size 3 and is used to define the fill value for NULL particles. If the number of nodes/particles increases in the time range, newly created nodes are added to all times steps, including previously stored timesteps. Since these particles didn’t exist at these time values, their location will for timesteps before they became active will be stored as the NullLoc.

The function xfWriteParticleTimestep is used to write all of the particle information for a single timestep. The function first checks to determine if the number of particles (nPaths) has not changed (it can be increased by not decreased). If the number of particles has increased, the function will extend the HDF5 dataset and fill in the previous timesteps for these elements with the Nullvalue. The timestep dimension is then extended by one. Lastly, the data for the new locations are stored in the HDF5 dataset. In C, the Locs array is a single dimensional double array which represents the x, y, and z values for all of the particles (the array is size number of particles * 3). The x values are stored in indices 0, 3, 6, etc. Likewise the y values are stored in indices 1, 4, 7, etc. and z in 2, 5, 8, etc. In FORTRAN the Locs array is a double dimensional array 3 x nParticles.

C/C++

int xfCreateGeometricPathGroup(xid ParentId, const char *Path,
                               const char *Guid, int Compression,
                               xid *PathGroup, double *NullLoc);
int xfWriteParticleTimestep(xid PathGroup, double Time, int nPaths, 
                            double *Locs);

FORTRAN

SUBROUTINE XF_CREATE_GEOMETRIC_PATH_GROUP(a_ParentId, a_Path, a_Guid,        &
                               a_Compression, a_PathGroup, a_NullVal, error)
  INTEGER,              INTENT(IN)   :: a_ParentId
  CHARACTER(LEN=*),     INTENT(IN)   :: a_Path, a_Guid
  INTEGER,              INTENT(IN)   :: a_Compression
  INTEGER,              INTENT(OUT)  :: a_PathGroup
  REAL*8, DIMENSION(*), INTENT(IN)   :: a_NullVal
  INTEGER,              INTENT(OUT)  :: error
SUBROUTINE XF_WRITE_PARTICLE_TIMESTEP(a_Id, a_nDim, a_Time, a_nPaths, a_Locs, &
                                      error)
  INTEGER,              INTENT(IN)   :: a_Id
  INTEGER,              INTENT(IN)   :: a_nDim
  REAL*8, DIMENSION(*), INTENT(IN)   :: a_Time
  INTEGER,              INTENT(IN)   :: a_nPaths
  REAL*8, DIMENSION(*), INTENT(IN)   :: a_Locs
  INTEGER,              INTENT(OUT)  :: error

Reading

These functions are provided to read the properties and attributes of a geometric path group.

Particle path locations can be read for a multiple indicies at a specific time or for a specific particle at multiple times. In each case the Locs array must already be allocated to the correct size.

C/C++

int xfGetNumberOfPaths(xid GroupId, int *NumPaths);
int xfGetNumberOfTimes(xid GroupId, int *NumTimes);
int xfGetPathTimesArray(xid GroupId, int NumTimes, double *Times);
int xfReadPathLocationsAtTime(xid GroupId, int TimeIndex,
                                      int FirstPathIndex,
                                      int NumIndicies, double *Locs);
int xfReadPathLocationsForParticle(xid GroupId, int PathIndex, 
                                   int FirstTimeIndex, int NumTimes,
                                   double *Locs);

FORTRAN

SUBROUTINE XF_GET_NUMBER_OF_PATHS(GroupId, NumPaths, error)
  INTEGER             , INTENT(IN)   :: GroupId
  INTEGER, INTENT(OUT)         :: NumPaths
  INTEGER, INTENT(OUT)         :: error
SUBROUTINE XF_GET_NUMBER_OF_TIMES(GroupId, NumTimes, error)
  INTEGER             , INTENT(IN)   ::  GroupId
  INTEGER, INTENT(OUT)         ::  NumTimes
  INTEGER, INTENT(OUT)         ::  error
SUBROUTINE XF_GET_PATH_TIMES_ARRAY(GroupId, NumTimes, Times, error)
  INTEGER,              INTENT(IN)    :: GroupId
  INTEGER,              INTENT(IN)    :: NumTimes
  REAL*8, DIMENSION(*), INTENT(INOUT) :: Times
  INTEGER                                error
SUBROUTINE XF_READ_PATH_LOCATIONS_AT_TIME(GroupId, TimeIndex, FirstPathIndex, &
                                          NumIndicies, Locs, error)
  INTEGER             , INTENT(IN)  :: GroupId
  INTEGER, INTENT(IN)         :: TimeIndex, FirstPathIndex, NumIndicies
  REAL*8, DIMENSION(*), INTENT(INOUT) :: Locs
  INTEGER, INTENT(OUT)        :: error
SUBROUTINE XF_READ_PATH_LOCS_FOR_PART(GroupId, PathIndex,        &
                                   FirstTimeIndex, NumTimes, Locs, error)
  INTEGER             , INTENT(IN)  :: GroupId
  INTEGER, INTENT(IN)         :: PathIndex, FirstTimeIndex, NumTimes
  REAL*8, DIMENSION(*), INTENT(INOUT) :: Locs
  INTEGER, INTENT(OUT)        :: error