FiberBundleHDF5  $Id: FiberHDF5.dfg,v 1.8 2006/12/12 12:32:50 werner Exp $
Functions
Low-Level Field Operations

Functions

F5_API void F5close (F5Path *f)
 
F5_API int F5Fread_linear (F5Path *fpath, hsize_t *dims, hid_t fieldtype, void *base, void *delta)
 
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)
 
F5_API hid_t F5LTcreate_topology (hid_t Grid_hid, const char *TopologyName, int IndexDepth, int SkeletonDimensionality, int DataspaceDimensionality, const hsize_t *refinement)
 
F5_API int F5LTset_maximal_grid_refinement (hid_t ContentsGroup_id, const char *gridname, int IndexDepth, int Dimensionality, const hsize_t *refinement)
 
F5_API int F5LTget_maximal_grid_refinement (hid_t ContentsGroup_id, const char *gridname, hsize_t *refinement)
 
F5_API int F5LTget_maximal_skeleton_refinement (hid_t ContentsGroup_id, const char *gridname, hsize_t *refinement, int IndexDepth, int Dimensionality)
 
F5_API int F5LTget_index_depth (hid_t Top_hid)
 
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)
 
F5_API hid_t F5LwriteS (hid_t Container_id, const char *name, int dimension, const hsize_t *dims, hid_t fieldtype, hid_t memtype, const void *dataPtr, hid_t enum_type, hid_t dcpl_id)
 
F5_API int F5LreadS (hid_t Container_id, hid_t memtype, void *dataPtr, hid_t ElementLoadID)
 
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)
 
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)
 
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)
 
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)
 
F5_API hid_t F5Lread_linear (hid_t F_id, hsize_t *dims, hid_t fieldtype, void *base, void *delta)
 
F5_API hid_t F5Lwrite_entity (hid_t R_id, const char *fieldname, hid_t fieldtype, const void *value)
 
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)
 
F5_API hid_t F5Lget_type (hid_t Field_hid, int FieldIDisGroup, hid_t elink_fapl_id)
 
F5_API int F5Lget_field_dimension_and_type (hid_t Representation_hid, const char *fieldname, hsize_t dims[FIBER_MAX_RANK], hid_t *type_id)
 
F5_API int F5LAsave_dimensions (hid_t Field_id, const char *aname, int rank, const hsize_t *dims)
 
F5_API int F5LAget_dimensions (hid_t Field_id, const char *aname, hsize_t dims[FIBER_MAX_RANK])
 
F5_API int F5Lset_space (hid_t Field_id, int rank, const hsize_t *dims)
 
F5_API int F5Lget_compound_extent_dims (hid_t CompoundGroupID, hsize_t *dims)
 
F5_API hid_t F5Lget_compound_space (hid_t CompoundGroupID)
 
F5PathF5LTcreateV (hid_t File_id, const double *time, const char *gridname, ChartDomain_IDs *ChartDomain, ChartDomain_IDs *coord_creator(void *udata), void *udata, const char *coordinate_system, const char *TopologyName, int IndexDepth, int SkeletonDimensionality, int Dimensionality, const hsize_t *refinement)
 
F5PathF5LTcreate (hid_t File_id, const double *time, const char *gridname, ChartDomain_IDs *ChartDomain, ChartDomain_IDs *coord_creator(), const char *coordinate_system, const char *TopologyName, int IndexDepth, int SkeletonDimensionality, int Dimensionality, const hsize_t *refinement)
 
F5_API F5PathF5LTcreate (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)
 

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)
  3. Special datasets:
    • F5D*_fraction()
    • F5D*_linear()
    • F5D*_entity()
  4. Utility functions:
    • F5Dget_type()
    • F5Dget_space()
  5. Low-level functions:
    • F5Dset_type_attribute()

Function Documentation

◆ F5close()

F5_API void F5close ( F5Path f)

◆ F5Fread_linear()

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 (origin) 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).

@params dims The dimensions of integer coordinates.

Returns
zero, if the entry could not be opened, non-zero if successfull.

References F5Lread_linear(), and F5Path::Field_hid.

◆ F5LAget_dimensions()

F5_API int F5LAget_dimensions ( hid_t  Field_id,
const char *  aname,
hsize_t  dims[FIBER_MAX_RANK] 
)

Read an n-dimensional attribute.

Parameters
dimsThe n values, maximally FIBER_MAX_RANK
Returns
The actual rank.

Referenced by F5LTget_maximal_grid_refinement(), F5LTget_maximal_skeleton_refinement(), F5LTset_maximal_grid_refinement(), and F5Tget_space().

◆ F5LAsave_dimensions()

F5_API int F5LAsave_dimensions ( hid_t  Field_id,
const char *  aname,
int  rank,
const hsize_t *  dims 
)

Save dimensional information to a certain location.

Returns
1 if successfull, 0 if some problem occurred during writing.

Referenced by F5Fwrite_linear(), F5Fwrite_linear_fraction(), F5Lset_space(), F5LSwrite_fraction(), F5LTset_maximal_grid_refinement(), and F5Lwrite_fraction().

◆ F5Lcreate()

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_idAn HDF5 dataset property ID. If it is negative, then a default property will be created locally via
H5Pcreate(H5P_DATASET_CREATE)
.
dataspace_idPointer 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_idThe group ID where the field shall be inserted, preferably a representation group ID that has been created by an F5create_representation() call.
fieldnameThe 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).
dimensionThe dimensionality of the data set.
dimsThe extension of the data set.
fieldtypeAn HDF5 type identifier.

References F5Dcreate().

Referenced by F5Fcreate(), and F5Lwrite().

◆ F5Lget_compound_extent_dims()

F5_API int F5Lget_compound_extent_dims ( hid_t  CompoundGroupID,
hsize_t *  dims 
)

Get the dataspace extension from a compound group.

References F5Lget_type().

◆ F5Lget_compound_space()

F5_API hid_t F5Lget_compound_space ( hid_t  CompoundGroupID)

Get the dataspace of a compound group.

References F5Lget_type().

◆ F5Lget_field_dimension_and_type()

F5_API int F5Lget_field_dimension_and_type ( hid_t  Representation_hid,
const char *  fieldname,
hsize_t  dims[FIBER_MAX_RANK],
hid_t *  type_id 
)

Retrieve dimensional and type information for a specific field.

References F5Aopen_name(), and F5Lget_type().

◆ F5Lget_type()

F5_API hid_t F5Lget_type ( hid_t  Field_hid,
int  FieldIDisGroup,
hid_t  elink_fapl_id 
)

Retrieve type information for a specific field.

References F5Aopen_name().

Referenced by F5Fget_type2(), F5Lget_compound_extent_dims(), F5Lget_compound_space(), and F5Lget_field_dimension_and_type().

◆ F5Lread_linear()

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
dimsThe 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.

References F5Aopen_name().

Referenced by F5Fread_linear().

◆ F5LreadS()

F5_API int F5LreadS ( hid_t  Container_id,
hid_t  memtype,
void *  dataPtr,
hid_t  ElementLoadID 
)

Read a dataset stored as separated compound as a continiguous compound dataset, involving some data transformation. Internally, hyperslabs are used.

◆ F5Lset_space()

F5_API int F5Lset_space ( hid_t  Field_id,
int  rank,
const hsize_t *  dims 
)

Save dimensional information to a certain location.

Returns
1 if successfull, 0 if some problem occurred during writing.

References F5LAsave_dimensions().

Referenced by F5Fwrite_linear_fraction(), F5LSwrite_fraction(), F5Lwrite_fraction(), and F5Lwrite_linear().

◆ F5LSwrite_fraction()

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
dimensionThe dimension of the data set.
datastartThe (multidimensional) start index of the saved data set.
dataendThe (multidimensional) end index of the saved data set.
fraction_nameAn 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.

References F5Gappend(), F5LAsave_dimensions(), F5Lset_space(), F5Lwrites(), and F5Xclose().

Referenced by F5FSwrite_fraction().

◆ F5LTcreate() [1/2]

F5Path* F5LTcreate ( hid_t  File_id,
const double *  time,
const char *  gridname,
ChartDomain_IDs ChartDomain,
ChartDomain_IDs coord_creator(),
const char *  coordinate_system,
const char *  TopologyName,
int  IndexDepth,
int  SkeletonDimensionality,
int  Dimensionality,
const hsize_t *  refinement 
)

Create a Topology of the given name with a representation in the certain coordinate system. If the ChartDomain has not been set yet, then the types in the newly created chart domain (F5Path->myChart) will contain valid types for the Points and tangential types, as they are created by the specified coord_creator(). Note that the coord_create() specifies the type of the coordinate system, while the coordinate_system parameter specifies the actual object that is of this respective type.

References F5LTcreateV().

Referenced by F5Rcreate_coordinate_topology(), F5Rcreate_edges_as_vertices_topology(), F5Rcreate_hexaedrons_as_vertices_topology(), F5Rcreate_relative_vertex_Irefinement3D(), F5Rcreate_relative_vertex_Qrefinement3D(), F5Rcreate_tetrahedrons_as_vertices_topology(), and F5Rcreate_triangles_as_vertices_topology().

◆ F5LTcreate() [2/2]

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
timePointer 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.
SkeletonDimensionalityThe dimensionality of the k-cells that is described by this Skeleton of a Grid.
DataspaceDimensionalityThe 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.

◆ F5LTcreateV()

F5Path* F5LTcreateV ( hid_t  File_id,
const double *  time,
const char *  gridname,
ChartDomain_IDs ChartDomain,
ChartDomain_IDs coord_creatorvoid *udata,
void *  udata,
const char *  coordinate_system,
const char *  TopologyName,
int  IndexDepth,
int  SkeletonDimensionality,
int  Dimensionality,
const hsize_t *  refinement 
)

The central F5Path constructor for write access: Creates the basic F5 structures in the file and sets up an F5Path object for subsequent use. Basically, all the information contained in an F5Path object can be created from the given parameters, however, some complexity arises when modifying some file that already has some structure. In such a case, it must re-use any found structures in a consistent way, especcially it has to use named types instead of intrinsic ones.

Todo:
Extend slice group creation to parameter spaces
Parameters
ChartDomainIf a chartdomain is given, i.e. it is used already or stems from another file opening, then we reuse this chart domain, otherwise a new one will be created. The ChartDomain describes all types of the fields in the respective representation group as they are transient in memory. It will become the F5Path's ‘myChart’ member. Specifying the ChartDomain is optional: if it is not given, then the coord_creator() callback function will be used to create a new coordinate object.

Note that F5LTcreateV() is more general in this respect than F5LTcreate() and F5LTcreateT(): Via the callback function, it allows to create an arbitrary subset of types for the chart domain, whereas F5LTcreate() always assumes that the representation domain is a coordinate system and creates the point, vector, covector and subsequent types for the tangential space. F5LTcreateT(), in contrast, does not create any tangential types (they are set to -1 in the ChartDomain), but only the point type, thus is more suitable for topological representations (cells referring to points, points to refined points, ...).

References F5Path::Chart_hid, F5Path::Charts_hid, F5Path::ContentsGroup_hid, F5Bappend_slice(), F5Gappend(), F5Path::field_enum_type_hid, F5Path::Grid_hid, F5Path::Slice_hid, and F5Path::Topology_hid.

Referenced by F5LTcreate().

◆ F5LTget_index_depth()

F5_API int F5LTget_index_depth ( hid_t  Top_hid)

Get the index depth of a certain Topology ID.

◆ F5LTget_maximal_grid_refinement()

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 int F5LTget_maximal_grid_refinement(hid_t ContentsGroup_id, const char *gridname, hsize_t *refinement)
Definition: F5LT.c:192
Definition: F5uniform.c:443

References F5Gappend(), and F5LAget_dimensions().

◆ F5LTget_maximal_skeleton_refinement()

F5_API int F5LTget_maximal_skeleton_refinement ( hid_t  ContentsGroup_id,
const char *  gridname,
hsize_t *  refinement,
int  IndexDepth,
int  Dimensionality 
)

Get the maximal refinement level for a certain topological property of a Grid. For example, get the maximum refinement level for faces on a Grid:

hsize_t MaxRefinement[ FIBER_MAX_RANK ];
int Dims;
Dims = F5LTget_maximal_skeleton_refinement(fpath->ContentsGroup_hid, "MyGridOfInterest", MaxRefinement, 1, 2);
F5_API int F5LTget_maximal_skeleton_refinement(hid_t ContentsGroup_id, const char *gridname, hsize_t *refinement, int IndexDepth, int Dimensionality)
Definition: F5LT.c:211

References F5Gappend(), and F5LAget_dimensions().

◆ F5LTset_maximal_grid_refinement()

F5_API int F5LTset_maximal_grid_refinement ( hid_t  ContentsGroup_id,
const char *  gridname,
int  IndexDepth,
int  Dimensionality,
const hsize_t *  refinement 
)

Update the maximal refinement level for a certain Grid.

Parameters
IndexDepthThere can be different levels of refinement depending on the topological type of the Skeleton. Usually refinement will only be relevant for vertices, thus IndexDepth=0, but it is also possible for higher dimensional skeletons such as edges, lines, triangles...

References F5Gappend(), F5LAget_dimensions(), and F5LAsave_dimensions().

◆ F5Lwrite()

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  dcpl_id 
)
Returns
A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.
Parameters
property_idAn HDF5 dataset property ID. If it is negative, then a default property will be created locally via
H5Pcreate(H5P_DATASET_CREATE)
.
dimensionThe dimensionality of the data set. You may use F5Lwrite1D() as a convenience shortcut for one-dimensional data sets.
dimsThe 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_typeThe Atomic Field enumeration type that is associated with the current file. Get it via F5LTmake_enum_type(fpath).
Todo:
Expose xfer_plist_id parameter
Returns
An HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.

References F5Lcreate().

Referenced by F5Fwrite_fraction(), F5FwriteIMAGE(), F5Lwrite1D(), and F5Lwrite_fraction().

◆ F5Lwrite1D()

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();

References F5Lwrite().

Referenced by F5Rcreate_rectilinear(), F5write_particle_cartesian3Dv(), and F5write_particle_cartesian3DvU().

◆ F5Lwrite_entity()

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.

◆ F5Lwrite_fraction()

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
dimensionThe dimension of the data set.
datastartThe (multidimensional) start index of the saved data set.
dataendThe (multidimensional) end index of the saved data set.
fraction_nameAn 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.

References F5Gappend(), F5LAsave_dimensions(), F5Lset_space(), F5Lwrite(), and F5Xclose().

Referenced by F5Fwrite_fraction().

◆ F5Lwrite_linear()

F5_API hid_t F5Lwrite_linear ( hid_t  R_id,
const char *  fieldname,
int  dimension,
const hsize_t *  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
dimsThe extensions of an HDF5 dataspace.
Returns
A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.

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

Returns
A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.

References F5Gcreate(), and F5Lset_space().

Referenced by F5Fwrite_linear(), and F5Fwrite_linear_fraction().

◆ F5LwriteS()

F5_API hid_t F5LwriteS ( hid_t  Container_id,
const char *  name,
int  dimension,
const hsize_t *  dims,
hid_t  fieldtype,
hid_t  memtype,
const void *  dataPtr,
hid_t  enum_type,
hid_t  dcpl_id 
)

Write a contiguous compound data set as separated compound data into the file, which involves data transformation.

Returns
The ID of the group, i.e. Container_id -> name

References F5Gappend().

◆ F5Lwrites()

F5_API hid_t F5Lwrites ( hid_t  R_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_typeThe 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.
Todo:
should be named F5DSwrite() instead
Returns
A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.
Note
If some component array is undefined (NULL), then its place will be left empty in the file.

References F5Gcreate().

Referenced by F5FSwrite_fraction(), and F5LSwrite_fraction().