|
XMDF
2.2
|
Multiple Data sets groups A multiple data sets group stores datasets for a specific spatial data object (mesh or grid). The mesh or grid that the data sets are to be used with is identified by using a global unique identifier or GUID. The following functions are used to create multiple data sets groups, retrieve paths to multiple data sets groups, and retrieve the GUID for the spatial data object. The GUID string should be of size XF_GUID_STRINGLENGTH as defined in the XMDF source code.
The multiple data sets group for a spatial data object is created automatically upon first use. The following function is used to open the data sets group associated with a spatial data object. Note this is the only case where a GUID is not needed for a multiple datasets group because the spatial data object that the datasets belong to is obvious.
Shortcut to setup writing to datasets A shortcut is provided in XMDF to allow model developers to easily setup the files and groups to write datasets. This shortcut is the function xfSetupToWriteDatasets. This function should always be used by model developers because it ensures that all models used with XMDF have a consistent and easy to use method to begin writing datasets.
The arguments for xfSetupToWriteDatasets should be given to the model using an external text file or command line arguments. The arguments include the filename to save the datasets, the path to a special group called the multi-datasets group path, the path to start writing datasets in this path, the GUID for the spatial data object that all the datasets will be tied to, and the overwrite options. The overwrite options are listed below by number and the corresponding C/FORTRAN constant (either the number or the constant may be used).
Creating and Writing Data sets The following functions are used to create data sets to write to HDF5. The units for the data set are specified when the data set is created. The maximum length for the units is 100 characters.
Valid time units are identified using the constants TS_DAYS, TS_HOURS, TS_MINUTES, TS_SECONDS, or TS_NOTAPPLICABLE. The compression value is applied to all arrays in the data set.
All date/time values stored in XMDF should be stored as Julian dates for consistency. A Julian day is the absolute count of days that have elapsed since Noon Universal Time on January 1, 4713 BCE on the Julian calendar (http://aa.usno.navy.mil/data/docs/JulianDate.html). While Julian dates are a good standard date format to follow, they aren’t very meaningful to most people. XMDF contains functions to convert calendar days to Julian days and Julian days to Calendar days. The conversion algorithms were adapted from code on a website maintained by the U.S. Naval Observatory (http://aa.usno.navy.mil/data/docs/JulianDate.html).
The following function is used to store a reference time for a data set. This reference time should be a double precision float specifying the Julian day of time zero for the simulation. The data set times are an array of offset values from the reference time.
Data sets are written as single precision floats by default. When data set values are appended the number of values must match the number of values previously written. The timesteps must be written in chronological order. Scalar value arrays are two-dimensional arrays of size NumValues. Vector value arrays are three-dimensional arrays of size NumValues X NumComponents (reversed for FORTRAN). For the C library, all arrays must be contiguous arrays of the correct size.
XMDF stores the minimum and maximum values for each timestep in the data set. The minimum and maximum values can be specified or they are determined automatically from the values arrays. For vector data sets the minimum and maximum values are the minimum and maximum values for vector magnitudes.
Activity/Inactive data set values can be specified in two ways. With the first method, a null value is defined for a data set. Any time a data set value is the null value any elements or cells containing the data value will be considered inactive for that time step. When null values are used, they must be set before writing the data set values or else the minimum and maximum values may be incorrect. A null value is set by writing a float property to the dataset group using the defined name PROP_NULL_VALUE. The second method to storing active/inactive data set locations is by using an activity array. For C, Activity arrays are two-dimensional arrays of unsigned characters of size number of times X the number of active values. For FORTRAN, the activity arrays are read/written using integers. The number of active values is based upon the number of cells or elements in the grid or mesh.
Datasets and Activity information can also be written in pieces which allows data from multiple arrays to be stored within a timestep.
If you write in pieces, and it is more convenient you can set the min and max values at the end using xfSetDatasetTimestepMinMax.
The function xfSetDatasetNumTimes is used to truncate time steps to the specified NumTimes. Once called, xfWriteActivityTimestep must either never be called or must always be called once after each time step write, writes such as xfWriteScalarTimestep, xfWriteScalarTimestepMinMax, xfWriteVectorTimestep, xfWriteVectorTimestepMinMax.
To read data sets from an XMDF file, you need to first open the data set group and get a group id. If the file only contains data sets, this group id is the file id. The following function is used to get the data set group id from a mesh or grid. The variable EntityId is the group id for the mesh or grid.
The following function is called to get the number of scalar data sets and the maximum path length for scalar data sets inside a "data sets" folder. This information is necessary to allocate the arrays necessary to retrieve the scalar data set paths.
The next function is used to get the paths to all scalar data sets inside a folder of data sets. These paths are the subsequent group paths to get to a data set divided by forward slashes ‘\’. Paths must be allocated to a size of NumDataSets X MaximumPathLength as obtained from GetScalarDatasetsInfo.
The following functions are used to obtain paths to vector data sets and work just like their scalar data set counterparts.
The variable Units must be a string of length at least 100.
The following functions are used to read time values.
This function is used to retrieve the time offsets for every time step in the data set. The variable Times must already be allocated to the number of time steps.
Minimum and maximum values at each time are written out automatically when a data set is stored. This information is used for to develop contour intervals in visualization packages. The following functions are used to retrieve the minimum and maximum values for the time steps. The arrays must already be allocated to the number of time steps.
The number of values in an activity array is not necessarily the same as the number of values in a data set. This function is used to determine the number of values in the activity array.
The following function is used to retrieve the activity status for the data set. The variable Active must already be allocated to hold the number of active values.
The next two functions are used to retrieve values for a particular time step. The values arrays must be allocated at least as big as the variable NumVals. xfReadScalarValuesTimestep() is much faster than xfReadScalarValuesAtIndicesFloat().
The next function is used to retrieve values for a data set index for one or more timesteps. The array Values must be a one-dimensional array of size at least NumTimesteps.
One can also retrieve activity values at specific locations just like data set values. These functions work just like their data set value counterparts. Remember that activity indices are based upon elements and cells and may not be the same as the locations where the data set values exist.
Timesteps can be deleted from the end of the existing dataset before continuing to add timesteps. Once timesteps have been deleted, care must be taken with writing the activity values for timesteps in the dataset.
The ::xfSetDatasetNumTimes function can be called after some number of timesteps have been written, i.e. after writing with any of the following xfWrite functions: ::xfWriteScalarTimestep, ::xfWriteScalarTimestepMinMax, ::xfWriteVectorTimestep, ::xfWriteVectorTimestepMinMax. For example, the ::xfSetDatasetNumTimes function, when called with an argument of 3, will delete all but the first 3 timesteps. Subsequent calls to the other xfWrite functions will append timesteps from the point of deletion.
If ::xfWriteActivityTimestep is to be called, then it must be called each time any of the other xfWrite functions are called. Failing to do this will cause the activity data to get out of sync with the rest of the timestep data.
Scalar Values in datasets with floating point values can be changed by using the function xfChangeScalarValuesTimestepFloat
1.8.6