Functions

Low-Level Field Operations

Functions

Detailed Description

Todo:
Separate these functions into F5-Dataset functions, with prefix F5D, of the form:
  1. Functions taking contigous compounds (data given as void*), zero components not supported:
    • F5Dcreate()
    • F5Dwrite()
    • F5Dsave() (convenience function: create + write with same field type, no I/O type conversion)
    • F5Dis()
    • F5Dopen()
    • F5Dread()
    • F5Dload() (convenience function: open + read)
  2. Functions taking separated compounds (data given as void**), missing components supported:
    • F5DS...() (6 functions)
  1. Special datasets:
    • F5D*_fraction()
    • F5D*_linear()
    • F5D*_entity()
  1. Utility functions:
    • F5Dget_type()
    • F5Dget_space()
  1. Low-level functions:
    • F5Dset_type_attribute()

Function Documentation

F5_API int F5Fread_linear ( F5Path *  fpath,
hsize_t *  dims,
hid_t  fieldtype,
void *  base,
void *  delta 
)

Try to read a field which is a linear mapping of a base and delta value.

The fpath object gets the the field identifier set to the opened field (which is available to retrieve additional user-defined attributes and such).

dims The dimensions of integer coordinates.

Returns:
zero, if the entry could not be opened, non-zero if successfull.
F5_API hid_t F5Lcreate ( hid_t  R_id,
const char *  fieldname,
int  dimension,
const hsize_t *  dims,
hid_t  fieldtype,
hid_t  property_id 
)

Create an HDF5 dataset for further treatment with raw HDF5 functions, e.g.

to write an hyperslab instead of the full dataset at once.

Returns:
A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.
Parameters:
property_id An HDF5 dataset property ID. If it is negative, then a default property will be created locally via 

H5Pcreate(H5P_DATASET_CREATE)

.

dataspace_id Pointer to an HDF5 identifier, that will be used to store a shared dataspace. It may be NULL, in which case a local dataspace is created. Until shared dataspaces are implemented in HDF5, this will make no difference in the actual HDF5 file.
R_id The group ID where the field shall be inserted, preferably a representation group ID that has been created by an F5create_representation() call.
fieldname The name of the field. It may be chosen arbitrarily, but must not contain slashes "/". It is furthermore recommended to avoid special characters - even if they work - and to keep the name short and concise).
dimension The dimensionality of the data set.
dims The extension of the data set.
fieldtype An HDF5 type identifier.
F5_API hid_t F5Lread_linear ( hid_t  F_id,
hsize_t *  dims,
hid_t  fieldtype,
void *  base,
void *  delta 
)

Try to read a field as if it were a linear mapping of indices to some values.

Parameters:
dims The extensions of an HDF5 dataspace.
Returns:
An HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.
Todo:
Add error checkings if the used attributes do not exist.
F5_API hid_t F5LSwrite_fraction ( hid_t  R_id,
const char *  fieldname,
int  dimension,
const hsize_t *  full_dims,
const hsize_t *  datasize,
hid_t  fieldtype,
hid_t  memtype,
const void *const *  dataPtr,
const hsize_t *  datastart,
const hsize_t *  start_border,
const hsize_t *  end_border,
const char *  fraction_name,
hid_t  enum_type,
hid_t  property_id 
)

Write a dataset of separate components that only cover a fraction of the entire representation's domain.

Parameters:
dimension The dimension of the data set.
datastart The (multidimensional) start index of the saved data set.
dataend The (multidimensional) end index of the saved data set.
fraction_name An optional string to name this fraction. It may be NULL to use an internal default.
Note:
Subsampling can not be specified here. Subsampled data need to go into another Topology group.
Returns:
A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.
F5_API F5Path* F5LTcreate ( hid_t  File_id,
const double *  time,
const char *  gridname,
ChartDomain_IDs *  ChartDomain,
new_global_chart_f  coord_creator,
const char *  coordinate_system,
const char *  TopologyName,
int  IndexDepth,
int  SkeletonDimensionality,
int  DataspaceDimensionality,
const hsize_t *  refinement 
)

Low-level creation function for F5Path objects.

Parameters:
time Pointer to the time instance of the current parameter space slices, or NULL if the data reside in a zero-dimensional parameter space, i.e. they are static. In a future extension, this may be a point to a multidimensional structure specifying the location in multidimensional parameter space.
SkeletonDimensionality The dimensionality of the k-cells that is described by this Skeleton of a Grid.
DataspaceDimensionality The dimensionality of the data that is used for the data on this Skeleton. This is best to be identical to the SkeletonDimensionality, but may differ, for instance one can store data in one-dimensional arrays over a 2D grid, or have some kind of irregular point distribution.
F5_API int F5LTget_maximal_grid_refinement ( hid_t  ContentsGroup_id,
const char *  gridname,
hsize_t *  refinement 
)

Get the maximal refinement level for a certain Grid. 

    hsize_t     MaxRefinement[ FIBER_MAX_RANK ];
    int         Dims;

        Dims = F5LTget_maximal_grid_refinement(fpath->ContentsGroup_hid, "MyGridOfInterest", MaxRefinement);
F5_API hid_t F5Lwrite ( hid_t  R_id,
const char *  fieldname,
int  dimension,
const hsize_t *  dims,
hid_t  fieldtype,
hid_t  memtype,
const void *  dataPtr,
hid_t  enum_type,
hid_t  property_id 
)
Returns:
A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.
Parameters:
property_id An HDF5 dataset property ID. If it is negative, then a default property will be created locally via 

H5Pcreate(H5P_DATASET_CREATE)

.

dimension The dimensionality of the data set. You may use F5Lwrite1D() as a convenience shortcut for one-dimensional data sets.
dims The extension of the data set.
Note:
Fields are always associated to certain coordinates system. The field type must be consistent with its coordinate system, e.g. one may not store a vector field in polar coordinates in a cartesian chart. Formally, this can be done because not all API functions have the ability to check for this consistency. However, a field type which is not part of a certain coordinate system will be treated as non-existent when reading the file later.
If a field is a structure made by separate data arrays, e.g. a vector field with components x,y,z stored as three arrays of floats, then use function F5Lwrites().
Parameters:
enum_type The Atomic Field enumeration type that is associated with the current file. Get it via F5LTmake_enum_type(fpath).
F5_API hid_t F5Lwrite1D ( hid_t  R_id,
const char *  fieldname,
hsize_t  nElements,
hid_t  fieldtype,
hid_t  memtype,
const void *  dataPtr,
hid_t  enum_type,
hid_t  property_id 
)

Convenience function for writing one-dimensional data.

Calls F5Lwrite();

F5_API hid_t F5Lwrite_entity ( hid_t  R_id,
const char *  fieldname,
hid_t  fieldtype,
const void *  value 
)

Write a field that is a constant for all elements.

Returns:
A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.
F5_API hid_t F5Lwrite_fraction ( hid_t  R_id,
const char *  fieldname,
int  dimension,
const hsize_t *  full_dims,
const hsize_t *  datasize,
hid_t  fieldtype,
hid_t  memtype,
const void *  dataPtr,
const hsize_t *  datastart,
const hsize_t *  start_border,
const hsize_t *  end_border,
const char *  fraction_name,
hid_t  enum_type,
hid_t  property_id 
)

Write a dataset which only covers a fraction of the entire representation's domain.

Parameters:
dimension The dimension of the data set.
datastart The (multidimensional) start index of the saved data set.
dataend The (multidimensional) end index of the saved data set.
fraction_name An optional string to name this fraction. It may be NULL to use an internal default.
Note:
Subsampling can not be specified here. Subsampled data need to go into another Topology group.
Returns:
A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.
F5_API hid_t F5Lwrite_linear ( hid_t  R_id,
const char *  fieldname,
int  dimension,
const hsize_t *  dataspace_dims,
hid_t  fieldtype,
const void *  base,
const void *  delta 
)

Write a field that is a linear map from coordinate indices to some data value.

Todo:
Remove dimension parameter, it is clear from the fieldtype's members.
Parameters:
dims The extensions of an HDF5 dataspace.
Returns:
A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.
F5_API hid_t F5Lwrite_permutation ( hid_t  R_id,
const char *  fieldname,
hsize_t  size,
hsize_t *  permutation_indices,
hsize_t  nvalues,
hid_t  fieldtype,
const void *  dataPtr 
)

Write a field which is accessed via some index permutation.

In addition to the raw data values, also some index array needs to be specified.

Parameters:
R_id An hdf5 identifier of the representation group in charge.
size The number of elements in the representation group.
permutation_indices A mapping from element indices to value indices.
nvalues How many data values are actually here.
fieldtype Hdf5 identifier of the data type.
dataPtr The data
Returns:
A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.
Todo:

implement

add structure function

add possibility to share permutation index datasets

F5_API hid_t F5Lwrites ( hid_t  F_id,
const char *  fieldname,
int  dimension,
const hsize_t *  dims,
hid_t  fieldtype,
hid_t  memtype,
const void *const *  dataPtr,
hid_t  enum_type,
hid_t  property_id 
)
Parameters:
enum_type The Atomic Field enumeration type that is associated with the current file. Get it via F5LTmake_enum_type(fpath).
Returns:
A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.
Generated on Wed Jan 26 07:24:16 2011 for FiberVISH by  doxygen 1.6.2