F5iterate.h

Go to the documentation of this file.

/*
 $Id: F5iterate.h,v 1.17 2008/04/23 19:16:30 werner Exp $
*/
 
#ifndef __F5iterate_H
#define __F5iterate_H
 
#include "hdf5inc.h"
#include "F5P.h"
#include "F5F.h"
#include "F5parameter.h"
 
#include "F5WinDLLApi.h"
 
#ifdef  __cplusplus
extern "C"
{
#endif
 
/** \defgroup F5iterate Iterator Functions
 
  Synopsis:
        -# Open a file
        -# Call F5iterate_timeslices() on it
        -# Let the timeslice callback function call F5iterate_grids()
        -# Let the grid callback function call F5iterate_vertex_fields() if you are
          interested in all available vertex-related fields.
 
  The current implementation status only allows to scan all fields given
  on the default Topology of Grid objects.
*/
 
/**
  \example RegularReader.c
  Scans through an HDF5 file and looks for grids with regular vertices.
*/
 
/** @{ */
 
/**@ingroup F5iterate
   Simple (mostly internal) helper function to detect which attributes or groups
   shall be ignored generally. F5 ignores all groups starting with a dot or underline.
   Normally this function will not be used by application code.
 
   @return non-zero if the string shall be ignored.
   @note returns true if the string is invalid (i.e.: "ignore invalid strings")
  */
F5_API int F5Iignore(const char*s);
 
 
typedef herr_t F5_iterate_paramspace_t(F5Path*path, const F5ParameterSpace*params, void *user_data);
 
/**@ingroup F5iterate
 @todo Implement, and reformulate F5iterate_timeslices() via this function.
 */
F5_API int F5iterate_paramspace(hid_t file_id, int *idx,
                                const F5ParameterSpace*selection,
                                F5_iterate_paramspace_t*callback, void *user_data ) ;
 
 
/**@ingroup F5iterate
   The iterator function that is called for each time slice.
   \see F5iterate_timeslices().
   @param slice_id  An HDF5 group identifier. Call H5Gclose() in the iterater function.
*/
typedef herr_t F5_iterate_timeslices_t(F5Path*path, double time, void *user_data);
 
/**@ingroup F5iterate
   Iterate over all time slices within a file.
  */
F5_API int F5iterate_timeslices(hid_t file_id, hsize_t *idx, F5_iterate_timeslices_t*callback, void *user_data ) ;
 
 
/**@ingroup F5iterate
   The iterator callback function that is called
   for each grid of a time slice that fullfills the
   specified grid property.
   \see  F5iterate_grids().
   @param F5Grid An F5 path with a valid Grid identifier.
*/
typedef herr_t F5_iterate_grids_t(F5Path*F5Grid, const char*gridname, void *user_data);
 
 
/**@ingroup F5iterate
   Iterate over all grids within a slice.
   @param gridtypes NULL-terminated array of grid property functions. May be NULL to retrieve all grids.
   @param coordinate_system The coordinate system in which to check for grid properties.
                            E.g. a grid may be uniform in one coordinate system, but is
                            just regular in another one. May be NULL to specify the default
                            cartesian coordinate system.
 
   @param F5Slice An F5 path with a valid slice identifier.
  */
F5_API int F5iterate_grids(F5Path*F5Slice, int *idx, F5_iterate_grids_t*callback, void *operator_data,
                           F5_gridproperty_t**gridtypes, const char*coordinate_system ) ;
 
 
/**@ingroup F5iterate
   The call back function that will be invoked by F5iterate_topologies(). It traverses all
   Skeletons of a Grid object.
 
@param index_depth The number of "hops" that are required to go from the elements described in this
                   group to vertex coordinates in a chart.
@param topological_dimension The dimension of the k-cells that are stored within this Skeleton group.
 */
typedef herr_t F5_iterate_topologies_t(F5Path*field, const char*topologyname,
                                       int index_depth,
                                       int topological_dimension,
                                       void *operator_data);
 
/**@ingroup F5iterate
   Traverses all Skeletons of a Grid object.
   Usually it is invoked via F5iterate_grids() and invokes F5iterate_topology_fields();
*/
F5_API int F5iterate_topologies(F5Path*grid, int *idx, F5_iterate_topologies_t*callback, void *operator_data);
 
 
 
/**@ingroup F5iterate
 @param Representation The F5Path to the currently traversed Represention
 @param RepresentationTarget The location of the Representer if its from another Grid.
 @relates F5iterate_representations()
 */
typedef herr_t F5_iterate_representations_t(F5Path*Representation,
                                            void*operator_data,
                                            const char*Representer_name,
                                            F5Path*RepresentationTarget);
 
 
/**@ingroup F5iterate
   Traverses all Representations per skeleton.
   Typically invoked by the callback function of F5iterate_topologies() .
 */
F5_API  int     F5iterate_representations(F5Path*skeleton, int *idx, F5_iterate_representations_t*callback, void *operator_data);
 
 
/**@ingroup F5iterate
   Called per grid function.
   @param field_id The HDF5 ID of the respective field.
   Note that it may be an HDF5 group ID or a dataset ID.
   Call H5Gclose() or H5Dclose() in the iterator function.
 
   @param representer_name The name of the containing group where this field resides.
  */
typedef herr_t F5_iterate_fields_t(F5Path*field, const char*fieldname, void *operator_data,
                                   const char*representer_name);
 
 
/**@ingroup F5iterate
   Traverses all fields per representation.
   Typically invoked by the callback function of F5iterate_representations().
   @see Higher level functionality provided by F5iterate_vertex_fields() and F5iterate_topology_fields().
   @param representer_name The name of the representation group, as come callbacks want to know this.
 */
F5_API  int     F5iterate_fields(F5Path*representation, int *idx,
                                 const char*representer_name,
                                 F5_iterate_fields_t*callback, void *operator_data); 
 
 
        
/**@ingroup F5iterate
   Prototype of a function that allows only certain types.
  */
typedef int F5_fieldtype_t(hid_t type_id);
 
 
/**@ingroup F5iterate
   Iterate over all fields given on the vertices per grid in the specified coordinate system.
   @param what Function to select which field types are allowed. May be a NULL pointer to retrieve
               all fields on the grid.
  */
F5_API int F5iterate_vertex_fields(F5Path*grid, int *idx, F5_iterate_fields_t*callback, void *operator_data,
                                   const char*coordinate_system,
                                   F5_fieldtype_t*what) ;
 
/**@ingroup F5iterate
   Iterate over an arbitrary topology group.
   The group ID grid->Topology_id must be a valid group ID when calling this function.
 */
F5_API int F5iterate_topology_fields(F5Path*skeleton, int *idx, F5_iterate_fields_t*callback, void *operator_data,
                                     const char*coordinate_system, F5_fieldtype_t*what);
 
/**@ingroup F5iterate
   @param grid An F5Path pointing to the current grid with its members myChart and FileIDs being defined.
 */
typedef herr_t F5_iterate_grid_atlas_t(F5Path*grid, const char*coordinate_name,
                                       hid_t global_chart_hid, hid_t domain_group_hid,
                                       void *operator_data);
 
F5_API  int F5iterate_grid_atlas(F5Path*grid, int *idx, F5_iterate_grid_atlas_t*callback, void *operator_data);
 
 
/**@ingroup F5iterate
   Check whether this grid object has some fields in the standard vertex topology,
   i.e. an Points/ entry.
 */
F5_API  int F5has_standard_vertex_fields(F5Path*grid);
 
typedef herr_t F5_iterate_fields_fragments_t(F5Path*field, const char*fragmentname, void *operator_data);
 
F5_API int F5iterate_field_fragments(F5Path*field, int *idx, F5_iterate_fields_fragments_t*callback,
                                     void *operator_data);
 
 
 
 
 
/**@ingroup F5iterate
   The iterator function that is called for each grid that is found in the file.
   \see F5iterate_grids_per_bundle().
*/
typedef herr_t F5_iterate_grids_per_bundle_t(hid_t file_id, hid_t gridinfo_id, const char*gridname, void *user_data);
 
/**@ingroup F5iterate
   Iterate over all grids slices within a file.
  */
F5_API int F5iterate_grids_per_bundle(hid_t file_id, int *idx, F5_iterate_grids_per_bundle_t*callback, void *user_data ) ;
 
 
//typedef herr_t F5_iterate_gridevolution_per_bundle_t(hid_t file_id, const char*gridname, double time, hid_t slice_id, void *user_data);
 
/**@ingroup F5iterate
   Callback function type for F5iterate_gridevolution().
   @param file_id The HDF5 file ID.
   @param gridname The name of the current grid under investigation.
   @param time     The time at which this grid exists.
   @param slicename The name of the time slice group where this grid resides in.
 */
typedef herr_t F5_iterate_gridevolution_per_bundle_t(hid_t file_id, const char*gridname, double time, const char*slicename, void *user_data);
 
/**@ingroup F5iterate
   @param gridinfo Optional per-grid callback function. May be just NULL.
 */
F5_API int F5iterate_gridevolution(hid_t file_id, int *idx, F5_iterate_gridevolution_per_bundle_t*callback, void *user_data,
                                   F5_iterate_grids_per_bundle_t*gridinfo ) ;
 
 
/** @} */
 
#ifdef  __cplusplus
}    /* extern "C" */
#endif
 
#endif  /* __F5iterate_H */