Functions

Field Operations

Interfacing data set creation/write routines using the F5Path structure. More...

Functions

Detailed Description

Interfacing data set creation/write routines using the F5Path structure.

Calls the low-level Field operation functions, but is designed for the end-user.

Function Documentation

F5_API int F5Fcreate ( F5Path *  fpath,
const char *  fieldname,
int  dimension,
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.

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.
fpath An F5 Path object that has been created by a F5Rcreate() or related calls from the F5R group. Any previous field ID contained there will be closed and overwritten.
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.
See also:
F5Lcreate()
Todo:
Add consistency check of sustained dataspace properties across multiple fields per representation.
Returns:
zero if the entry could not be opened, non-zero otherwise.
F5_API hid_t F5Fget_type ( F5Path *  f  ) 

Get the data type of an field, given an F5 path.

Returns:
An HDF5 datatype, caller must call H5Tclose().

Referenced by H5ID::find().

F5_API hid_t F5Fgrab ( F5Path *  f  ) 

Take an HDF5 field identifier out of control of the F5Path.

The path identifier is no longer pointing to a field after this operations, it is just a truncated path up to the representation group. It is the responsibility of the caller to close the returned HDF5 identifier, which can either be a group or dataset. This can be determined either by inspecting f->FieldIDisGroup or by H5Gget_objinfo() . Note that using this function allows to keep a field ID open for later use, but undermines the transparency of fields as beeing stored as either datasets or a group with multiple datasets.

F5_API int F5Fis_linear ( F5Path *  fpath,
const char *  fieldname 
)

Check if a field within an F5 path is a linear mapping of points to values.

Todo:
Implement. Similar to F5Lread_linear().
F5_API int F5Fopen ( F5Path *  f,
const char *  fieldname 
)

Open a field entry within an F5Path object and leave all other entries intact.

An previously opened field entry is closed before the new one is opened.

Returns:
zero if the entry could not be opened, non-zero otherwise.
Note:
F5 does no HDF5 error management by itself. If any error messages from HDF5 when trying to open a non-existing field shall be emitted, the application code has to set the HDF5 error handler. F5 guarantees to leave these error handlers intact, even if they are locally disabled during some operations.
F5_API int F5FSwrite_fraction ( F5Path *  fpath,
const char *  fieldname,
int  rank,
const hsize_t *  full_dims,
const hsize_t *  fragment_dims,
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  property_id,
int  AllowFullCoverage 
)

Write a dataset given as separate components which only covers a fraction of the entire representation's domain.

Parameters:
dimension The dimension of the data set.
full_dims The extension of the full (virtual) data set in each dimension, i.e. the size of the entire field when reconstructed from all fragments covering this field.
datastart The (multidimensional) start index of the saved data set.
fragment_dims The number of elements of this fraction.
fraction_name An optional string to name this fraction. It may be NULL to use an internal default.
AllowFullCoverage If non-zero, then the data set is not written as a fragment in case its dimensions cover the entire data space. Use this reduction option with care. This automatism might lead to bad effects, especcially it eliminates the capability to add fragments later. By default, leave this parameter at 0.
Note:
Subsampling can not be specified here. Subsampled data need to go into another Topology group.
Returns:
true
F5_API F5ErrorCode F5Fwrite ( F5Path *  fpath,
const char *  fieldname,
int  dimension,
hsize_t *  dims,
hid_t  fieldtype,
hid_t  memtype,
const void *  dataPtr,
hid_t  property_id 
)
Returns:
An F5 path. It is identical to the fpath parameter, but with the field ID filled in. Any previous field ID contained there will be closed and overwritten.
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().
Todo:
Implement, and add consistency check of sustained dataspace properties across multiple fields per representation.
See also:
F5Fwrite();
Returns:
error code telling the success of the write:
Examples:
mm5-nc2F5.c.
F5_API int F5Fwrite_fraction ( F5Path *  fpath,
const char *  fieldname,
int  rank,
const hsize_t *  full_dims,
const hsize_t *  fragment_dims,
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  property_id 
)

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

Such datasets are called "fragmented".

Parameters:
fpath An F5 Path object that has been created by a F5Rcreate() or related calls from the F5R group. Any previous field ID contained there will be closed and overwritten.
rank The rank (dimensionality) of the data set. Maximum value 8 is set by HDF5.
full_dims The extension of the full (virtual) data set in each dimension, i.e. the size of the entire field when reconstructed from all fragments covering this field.
datastart The (multidimensional) start index of the saved data set. Also known as the minimum integer coordinates of this fragment in the coarse grid.
fragment_dims The number of elements of this fraction.
fraction_name A string to name this fraction. It may be an arbitrary name, but should be consistently used among all fragmented fields. It may be NULL to use an internal default (this feauture is not implemented yet, so please DO specify a valid name here).
property_id An HDF5 dataset property ID. If it is negative, then a default property will be created locally via H5Pcreate(H5P_DATASET_CREATE).
start_border The number of overlapping elements at the lower border (also known as ghost zones). It may be NULL if the fragments do no overlap.
end_border The number of overlapping elements at the upper border (also known as ghost zones). It may be NULL if the fragments do no overlap.
fieldtype The data type of the field as it should appear in the file.
memtype The data type of the field as it exists in memory. It may be negative if it is identical to the field type. For instance, if an array of doubles should be written into a file in single precision, specify fieldtype=H5T_NATIVE_DOUBLE and memtype=H5T_NATIVE_FLOAT .
Note:
Subsampling can not be specified here. Subsampled data need to go into another Topology group.
Returns:
true if successful.
Examples:
FragmentedField.c.
F5_API int F5Fwrite_linear ( F5Path *  fpath,
const char *  fieldname,
int  dimension,
hsize_t *  dims,
hid_t  fieldtype,
const void *  base,
const void *  delta 
)

Write a field which is a linear mapping of a base and delta value.

dims The dimensions of integer coordinates.

Returns:
zero, if the entry could not be opened, non-zero if successful.
Deprecated:
Use F5FwriteX instead.
Examples:
FragmentedField.c.
F5_API int F5Fwrite_linear_fraction ( F5Path *  fpath,
const char *  fieldname,
int  rank,
const hsize_t *  full_dims,
const hsize_t *  fragment_dims,
hid_t  fieldtype,
const void *  base,
const void *  delta,
const hsize_t *  datastart,
const char *  fraction_name 
)

Write a dataset given as small "linear mappings" which only covers a fraction of the entire representation's domain.

Useful to specify local bounding boxes.

Parameters:
dimension The dimension of the data set.
full_dims The extension of the full (virtual) data set in each dimension, i.e. the size of the entire field when reconstructed from all fragments covering this field.
datastart The (multidimensional) start index of the saved data set.
fragment_dims The number of elements of this fraction.
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:
true
F5_API F5ErrorCode F5FwriteX ( F5Path *  fpath,
const char *  fieldname,
int  rank,
const hsize_t  dims[],
hid_t  fieldtype,
hid_t  memtype,
const void *const   dataPtr[],
const int  polynom_order[],
const int  component_map[],
hid_t  property_id 
)

Write a field which is defined procedurally as a polynomial function of each manifold coordinate index.

Parameters:
rank Dimensionality of the base manifold
dims[rank] Extension of the base manifold
fieldtype The type of the field as it should appear in the file
memtype The type of the field as it resides in memory
dataPtr[COMPONENTS] An array of polynom coefficients for each component of fieldtype
polynom_order[COMPONENTS] The order of each component's polynom
component_map[rank] Mapping from manifold index to component
F5_API hid_t F5Tget_space ( F5Path *  f  ) 

Get the data space of an field, given an F5 path.

Returns:
An HDF5 dataspace, caller must call H5Sclose().
Generated on Wed Jan 26 07:24:16 2011 for FiberVISH by  doxygen 1.6.2