F5L.h

Go to the documentation of this file.

/*
 *
 * $Id: F5L.h,v 1.23 2008/03/19 21:21:43 werner Exp $
 *
 */
 
#ifndef __F5Lield_H
#define __F5Lield_H
 
#include "hdf5inc.h"
 
#include "F5WinDLLApi.h"
#include "F5defs.h"
 
#ifdef  __cplusplus
extern "C"
{
#endif
 
#define F5P_DEFAULT     (-1)
 
 
/**\defgroup F5L Low-Level Field Operations
 
  @todo Separate these functions into F5-Dataset functions, with prefix F5D,
        of the form:
 
   -# 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)
   -# Functions taking separated compounds (data given as void**), missing components
      supported:
        - F5DS...()     (6 functions)
 
   -# Special datasets:
        - F5D*_fraction()
        - F5D*_linear()
        - F5D*_entity()
 
   -# Utility functions:
        - F5Dget_type()
        - F5Dget_space()
 
   -# Low-level functions:
        - F5Dset_type_attribute()
  */
 
/**\ingroup F5L
 
        Create an HDF5 dataset for further treatment with raw HDF5 functions, e.g.
        to write an hyperslab instead of the full dataset at once.
 
   @return A HDF5 \b dataset ID. The caller must issue H5Dclose() on the returned identifier.
 
   @param property_id An HDF5 dataset property ID. If it is negative,
                      then a default property will be created locally
                      via <PRE>H5Pcreate(H5P_DATASET_CREATE)</PRE>.
 
   @param 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.
 
  @param 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.
 
  @param 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).
 
  @param dimension The dimensionality of the data set.
  @param dims      The extension of the data set.
  @param fieldtype An HDF5 type identifier.
*/
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);
 
 
/** \ingroup F5L
 */
F5_API hid_t    F5LTcreate_topology(hid_t Grid_hid,
                                    const char*TopologyName,
                                    int IndexDepth,
                                    int SkeletonDimensionality,
                                    int DataspaceDimensionality,
                                    const hsize_t*refinement);
 
/** \ingroup F5L
    Update the maximal refinement level for a certain Grid.
    @param IndexDepth There 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...
 */
F5_API  int     F5LTset_maximal_grid_refinement(hid_t ContentsGroup_id,
                                                const char*gridname,
                                                int     IndexDepth,
                                                int     Dimensionality,
                                                const hsize_t*refinement);
 
/** \ingroup F5L
    Get the maximal refinement level for a certain Grid.
    @code
    hsize_t     MaxRefinement[ FIBER_MAX_RANK ];
    int         Dims;
 
        Dims = F5LTget_maximal_grid_refinement(fpath->ContentsGroup_hid, "MyGridOfInterest", MaxRefinement);
    @endcode
 */
F5_API  int     F5LTget_maximal_grid_refinement(hid_t ContentsGroup_id,
                                                const char*gridname,
                                                hsize_t*refinement);
 
 
/** \ingroup F5L
    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:
    @code
    hsize_t     MaxRefinement[ FIBER_MAX_RANK ];
    int         Dims;
 
        Dims = F5LTget_maximal_skeleton_refinement(fpath->ContentsGroup_hid, "MyGridOfInterest", MaxRefinement, 1, 2);
    @endcode
 */
F5_API  int     F5LTget_maximal_skeleton_refinement(hid_t ContentsGroup_id,
                                                    const char*gridname,
                                                    hsize_t*refinement,
                                                    int IndexDepth,
                                                    int Dimensionality);
 
 
/** \ingroup F5L
    Get the index depth of a certain Topology ID.
 */
F5_API int   F5LTget_index_depth(hid_t Top_hid);
 
 
/**\ingroup F5L
   @return A HDF5 \b dataset ID. The caller must issue H5Dclose() on the returned identifier.
 
   @param property_id An HDF5 dataset property ID. If it is negative,
                      then a default property will be created locally
                      via <PRE>H5Pcreate(H5P_DATASET_CREATE)</PRE>.
 
   @param dimension The dimensionality of the data set. You may use F5Lwrite1D() as a convenience
                    shortcut for one-dimensional data sets.
 
   @param 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.
 
  @note  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().
 
  @param 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    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);
 
 
/**\ingroup F5L
   Write a contiguous compound data set as
   separated compound data into the file, which involves
   data transformation.
 
   @return The ID of the group, i.e. Container_id -> name
 */
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);
 
/**\ingroup F5L
   Read a dataset stored as separated compound as a continiguous compound dataset,
   involving some data transformation.
   Internally, hyperslabs are used.
 */
F5_API int      F5LreadS(hid_t Container_id, hid_t memtype, void * dataPtr,
                         hid_t  ElementLoadID);
 
 
/**\ingroup F5L
   Write a dataset which only covers a fraction of the entire representation's domain.
   @param dimension     The dimension of the data set.
   @param datastart     The (multidimensional) start index of the saved data set.
   @param dataend       The (multidimensional) end index of the saved data set.
   @param 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.
   @return A HDF5 \b 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 contiguious compound data set as
   separated compound data into the file, which involves
   data transformation.
 
   Calls F5LwriteS().
 */
F5_API hid_t    F5Lwrite_fractionS(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    F5Lwrite_fraction_external(hid_t R_id, const char*fieldname,
 
                                   const char *target_file_name,
                                   const char *target_obj_name,
                                   const char *prefix,
 
                                   int rank, 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);
 
 
/**\ingroup F5L
   Write a dataset of separate components that only cover a fraction of the entire
   representation's domain.
   @param dimension     The dimension of the data set.
   @param datastart     The (multidimensional) start index of the saved data set.
   @param dataend       The (multidimensional) end index of the saved data set.
   @param 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.
   @return A HDF5 \b dataset ID. The caller must issue H5Dclose() on the returned identifier.
  */
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);
 
 
 
/**\ingroup F5L
   Convenience function for writing one-dimensional data. Calls F5Lwrite();
 */
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);
 
 
/**\ingroup F5L
   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.
   @param  dims   The extensions of an HDF5 dataspace.
   @return A HDF5 \b group ID. The caller must issue H5Gclose() 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);
 
 
F5_API int F5Lis_linear(hid_t Rep_id, const char*fieldname);
 
/**\ingroup F5L
 
   Try to read a field as if it were a linear mapping of indices to some values.
 
   @param  dims   The extensions of an HDF5 dataspace.
 
   @return An HDF5 \b 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    F5Lread_linear(hid_t F_id,
                               hsize_t*dims,
                               hid_t fieldtype,
                               void * base, void * delta);
 
 
/**\ingroup F5L
   Write a field that is a constant for all elements.
   @return A HDF5 \b dataset ID. The caller must issue H5Dclose() on the returned identifier.
 */
F5_API hid_t    F5Lwrite_entity(hid_t R_id, const char*fieldname,
                                hid_t fieldtype,
                                const void * value);
 
 
 
/**\ingroup F5L
    @param enum_type The Atomic Field enumeration type that is associated with
                     the current file. Get it via F5LTmake_enum_type(fpath).
 
    @return A HDF5 \b group ID. The caller must issue H5Gclose() on the returned identifier.
 
    @todo should be named F5DSwrite() instead
*/
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);
 
/**
  Write a field as an n-dimensional direct product, where each dimensional
  extend is given as an explicit dataset or a polynom.
  Used e.g. for as rectilinear coordinates, uniform coordinates or "stacked"
  coordinates.
  @param rank The rank n (dimensionality) of the dataset.
  @param dims The extent (size) of the dataset in each dimension.
  @param fieldtype The type of the dataset; it must be a compound type with n members.
  @param memtype   The type of the dataset how it resides in memory;
                   it must be a compound type with n members where the ith member
                   must be convertible to the field type's ith member.
  @param polynom_order For each dimension, provides the order of the respective
                       polynom. If it is negative, then the respective coordinate
                       is interpreted as given explicitely by a dataset containing
                       each point and the extent is taken from the dims parameter.
 
  @param property_id    Data creation properties, may be F5P_DEFAULT.
  @param ProcIDLocation Group ID where the enumeration type is stored in the file.
 
  @note The component order of the field and memory type do not need to be identical,
        i.e. the field type may be {x,y,z}, while the memory type specifies {z,y,x}.
        The data are accessed in memory according to the memory type, but written
        into the file in the order as specified by the field type.
 
  */
F5_API hid_t F5LwriteX(hid_t R_id, const char*fieldname,
                       int Mrank, 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, hid_t ProcIDLocation);
 
#if 0 /* use hyperslabs instead? */
/**\ingroup F5L
    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.
   @param R_id                An hdf5 identifier of the representation group in charge.
   @param size                The number of elements in the representation group.
   @param permutation_indices A mapping from element indices to value indices.
   @param nvalues             How many data values are actually here.
   @param fieldtype           Hdf5 identifier of the data type.
   @param dataPtr             The data
   @return A HDF5 \b group ID. The caller must issue H5Gclose() on the returned identifier.
   \todo implement
   \todo add structure function
   \todo add possibility to share permutation index datasets
  */
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);
#endif
 
/**\ingroup F5L
    Retrieve type information for a specific field.
*/
F5_API hid_t    F5Lget_type(hid_t Field_hid, int FieldIDisGroup, hid_t elink_fapl_id);
 
 
/**@ingroup F5L
    Retrieve dimensional and type information for a specific field.
*/
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);
 
/**@ingroup F5L
   Save dimensional information to a certain location.
   @return 1 if successfull, 0 if some problem occurred during writing.
 */
F5_API int      F5LAsave_dimensions(hid_t Field_id, const char*aname, int rank, const hsize_t*dims);
 
/**@ingroup F5L
   Read an n-dimensional attribute.
   @param dims The n values, maximally FIBER_MAX_RANK
   @return The actual rank.
 */
F5_API int      F5LAget_dimensions(hid_t Field_id, const char*aname, hsize_t dims[FIBER_MAX_RANK]);
 
/**@ingroup F5L
   Save dimensional information to a certain location.
   @return 1 if successfull, 0 if some problem occurred during writing.
 */
F5_API int      F5Lset_space(hid_t Field_id, int rank, const hsize_t*dims);
 
F5_API int      F5Dset_type_attribute(hid_t F_id, hid_t fieldtype);
 
 
/**
   Get the dataspace of an F5 field.
   The field id may be a group or a dataset ID.
   If it has an dimensions attribute, then this one is
   taken for dataspace information.
   Otherwise, the dataspace of the dataset is used.
   If it's not a dataset and does not have a dimension attribute,
   then it's an error.
*/
F5_API  hid_t   F5Lget_space(hid_t Field_id);
 
/**@ingroup F5L
   Get the dataspace extension from a compound group.
 */
F5_API  int     F5Lget_compound_extent_dims(hid_t CompoundGroupID, hsize_t*dims);
 
/**@ingroup F5L
   Get the dataspace of a compound group.
 */
F5_API  hid_t   F5Lget_compound_space(hid_t CompoundGroupID);
 
#ifdef  __cplusplus
}    /* extern "C" */
 
#ifdef  F5_CPLUSPLUS_XXXXXXXXXXXX
 
namespace F5
{
 
template <int N, typename Trait>
inline hid_t LwriteX(hid_t R_id, const char*fieldname,
                     const Extent<N, hsize_t, Trait>&dims,
                     hid_t fieldtype, hid_t memtype,
                     const Extent<N, const void*, Trait>&dataPtr,
                     const Extent<N, int, Trait>&polynom_order,
                     hid_t property_id = F5P_DEFAULT)
{
        return F5LwriteX(R_id, fieldname, N, dims.data,
                        fieldtype, memtype,
                        dataPtr.data, polynom_order.data,
                        property_id);
 
}
 
template <int N, typename Trait>
inline hid_t LwriteX(hid_t R_id, const char*fieldname,
                     const Extent<N, hsize_t, Trait>&dims,
                     hid_t fieldtype,
                     const Extent<N, const void*, Trait>&dataPtr,
                     const Extent<N, int, Trait>&polynom_order,
                     hid_t property_id = F5P_DEFAULT)
{
        return F5LwriteX(R_id, fieldname, N, dims.data,
                        fieldtype, 0,
                        dataPtr.data, polynom_order.data,
                        property_id = F5P_DEFAULT);
 
}
 
template <typename T, typename value>
inline T evalPolynom(const value&v, const T*data, int n)
{
        if (n==0) return 0;
        if (n==1) return T[0];
        if (n==1) return T[0] + v*T[1];
        return T[0] + v*evalPolynom(v, data+1, n-1);
}
 
 
} /* namespace F5 */
 
#endif  /* F5_CPLUSPLUS */
 
#endif
 
#endif  /* __F5Lield_H */