F5R.h

Go to the documentation of this file.

/*
//
// $Id: F5R.h,v 1.17 2007/07/31 13:42:02 werner Exp $
//
*/
 
#ifndef __F5R_H
#define __F5R_H
 
#include "F5F.h"
#include "F5B.h"
#include "F5coordinates.h"
 
#ifdef  __cplusplus
extern "C"
{
#endif
 
/**\defgroup F5R Creating F5Path objects and field representations.
   These functions create F5Path objects for subsequent usage by F5F
   field functions. They are created directly from HDF5 id's and
   native types.
  */
 
 
/**\ingroup F5R
   Create a Field object for a given representation of a grid's vertices
   in a certain coordinate system for a three-dimensional distribution
   of vertices, i.e. a 3D grid. Not to be used for surfaces, lines or
   point clouds - use F5Rcreate_cartesian_nD() for this case.
 
   @return A new F5Path pointer. Call F5close() if it is no longer used.
  */
F5_API F5Path*F5Rcreate_cartesian_3D(hid_t File_id, double time,
                                     const char*gridname,
                                     const char*coordinate_system);
 
 
 
/**\ingroup F5R
   Create a Field object for a given representation of a grid's vertices
   in a certain coordinate system, specifying the dimensionality of the
   grid vertices.
 
   @return A new F5Path pointer. Call F5close() if it is no longer used.
  */
F5_API F5Path*F5Rcreate_cartesian_nD(hid_t File_id, double time,
                                     const char*gridname,
                                     int        Dims,
                                     const char*coordinate_system);
 
 
/**\ingroup F5R
   Construct a Field object for a representation of a grid's vertices
   in a certain coordinate system.
 
   @param ChartDomain A coordinate system domain object. It may be NULL to create
                        a new one via the coord_creator parameter locally for this
                        field. If a class of coordinate systems shall be used for
                        multiple grids (which is required to enable interpolation),
                        then a shared ChartDomain object needs to be given. If
                        is reference counted among all grids that use it (taken care
                        of in F5close() ).
 
   @param coord_creator A procedure to create a new class of coordinate systems.
   @param coordinate_system A name for an instance of the coordinate system, i.e. for
                            the current chart object to use.
 
   @param TopologyName  On which topological space of the grid to create the coordinate
                        representation (e.g. vertices, cells, edges, refinement level ...)
 
   @param time          The time to which the succeeding data will be attached. Use
                        F5Rcreate_static_cartesian() if no time information is reasonable
                        for the given data. Note that static data currently requires
                        special handling when reading data, so it is recommended to
                        adjust any data to a timeslice, except if there is an absolute
                        requirement to specify that these data are constant for all
                        thinkable times.
 
   @return A new F5Path pointer. Call F5close() if it is no longer used.
  */
/*
F5_API F5Path*F5Rcreate(hid_t File_id, double time,
                        const char*gridname,
                        ChartDomain_IDs*ChartDomain,
                        new_global_chart_f coord_creator,
                        const char*coordinate_system,
                        const char*TopologyName);
*/
 
 
/**\ingroup F5R
   Construct a Field object for a representation of a grid's vertices
   in a certain coordinate system that is independent from any time information.
 
   @param ChartDomain A coordinate system domain object. It may be NULL to create
                        a new one via the coord_creator parameter locally for this
                        field. If a class of coordinate systems shall be used for
                        multiple grids (which is required to enable interpolation),
                        then a shared ChartDomain object needs to be given. If
                        is reference counted among all grids that use it (taken care
                        of in F5close() ).
 
   @param coord_creator A procedure to create a new class of coordinate systems.
   @param coordinate_system A name for an instance of the coordinate system, i.e. for
                            the current chart object to use.
 
   @param TopologyName  On which topological space of the grid to create the coordinate
                        representation (e.g. vertices, cells, edges, refinement level ...)
 
   @return A new F5Path pointer. Call F5close() if it is no longer used.
  */
F5_API F5Path*F5Rcreate_static_cartesian(hid_t File_id,
                                         const char*gridname,
                                         const char*coordinate_system);
 
 
/**\ingroup F5R
   Create a representation for a specific topological
   space on the grid in a certain coordinate system.
   Mostly of internal use.
 */
F5_API F5Path*F5Rcreate_coordinate_topology(hid_t File_id, const double*time,
                                            const char*gridname,
                                            const char*coordinate_system,
                                            const char*TopologyName,
                                            int IndexDepth, int SkeletonDimensionality,
                                            int Dimensionality,
                                            const hsize_t*refinement);
 
 
/**\ingroup F5R
   Create the default topology of the cells of a grid as triangles,
   as specified by vertices. It will result in a two-dimensional grid.
   @return An F5Path object referring to the cells (i.e. triangles). All subsequent
           field operations on this F5Path object will refer to fields on the triangles.
 */
F5_API F5Path*F5Rcreate_triangles_as_vertices_topology(hid_t File_id, double time, const char*gridname);
 
 
/* ==== [RH] 20061229 .. added
   ---------------------------
 */
/**\ingroup F5R
   Create the default topology of the edges of a grid,
   as specified by vertices.
   @return An F5Path object referring to the edges. All subsequent
           field operations on this F5Path object will refer to fields on the edges.
 */
F5_API F5Path*F5Rcreate_edges_as_vertices_topology(hid_t File_id, double time, const char*gridname);
 
 
 
/* ==== [RH] 20061229 .. added
   ---------------------------
 */
/**\ingroup F5R
   Create the default topology of the facet of a grid,
   as specified by vertices.
   @return An F5Path object referring to the facet. All subsequent
           field operations on this F5Path object will refer to fields on the facet.
 */
F5_API F5Path*F5Rcreate_faces_as_vertices_topology(hid_t File_id, double time, const char*gridname);
 
 
/* ==== [RH] 20061221 .. added
   ---------------------------
 */
/**\ingroup F5R
   Create the default topology of the cells of a grid as tetrahedra,
   as specified by vertices. It will be a 3-dimensional grid.
   @return An F5Path object referring to the cells. All subsequent
           field operations on this F5Path object will refer to fields on the cells.
 */
F5_API F5Path*F5Rcreate_tetrahedrons_as_vertices_topology(hid_t File_id, double time, const char*gridname);
 
/**\ingroup F5R
   Create the default topology of the cells of a grid as hexahedrons,
   as specified by vertices. It will be a 3-dimensional grid.
   @return An F5Path object referring to the hexahedral cells. All subsequent
           field operations on this F5Path object will refer to fields on the hexahedrons.
 */
F5_API F5Path*F5Rcreate_hexaedrons_as_vertices_topology(hid_t File_id, double time, const char*gridname);
 
 
 
/* Internal function naming convention for vertex or cell refinement topologies */
F5_API void TopologyName(char*name, int nlength,
                         const hsize_t*level, int Centering, int dims);
 
 
/**\ingroup F5R
   Create an Field object for vertices of a grid
   in a certain coordinate system that is intended to store
   subsampled data of the full grid.
   Note that this function is intended to store contigous datasets,
   which can be hyperslabs of other datasets. It can be used as
   a "cache" for hyperslabbed data such that they require less
   disc space.
 
   @note This function only refers to the vertices of a grid.
         Use the AMR functions for more handling cell, face or edge-related
         data and/or if refined data only exist on a subset of the full
         coordinate space.
 
   @see F5Lwrite_fraction(), AMR
 
   @param refinement The refinement factor as compared to the finest resolution.
                     It will most likely be a power of two.
                     Note that the coarsest resolution should get the smallest
                     number and the finest resolution (i.e. the complete dataset)
                     the largest number.
                     It is recommended to start counting at zero, given a
                     refinement level, this refinement to be given here will
                     be a power of two given the level number.
   @return A new F5Path pointer. Call F5close() if it is no longer used.
  */
F5_API F5Path*F5Rcreate_vertex_refinement3D(hid_t File_id, double time,
                                            const char*gridname,
                                            const hsize_t refinement[3],
                                            const char*coordinate_system);
 
/**\ingroup F5R
 Create a refinement topology whose refined cells fully cover
 coarse cells. The border vertices line up exactly,
 i.e. the positions of a subregion may be given in integers of
 a coarse region.
 */
F5_API F5Path*F5Rcreate_relative_vertex_Irefinement3D(hid_t File_id, double time,
                                                      const char*gridname,
                                                      const hsize_t current_refinement[3],
                                                      double target_time,
                                                      const hsize_t target_refinement[3]);
 
/**\ingroup F5R
 Create a refinement topology whose refined cells may partially cover
 coarse cells. The refinement coordinates are given as rational numbers.
 */
F5_API F5Path*F5Rcreate_relative_vertex_Qrefinement3D(hid_t File_id, double time,
                                                      const char*gridname,
                                                      const hsize_t current_refinement[3],
                                                      double target_time,
                                                      const hsize_t target_refinement[3]);
 
/**\ingroup F5R
 Create a topology suitable for downsampled data, i.e. where the \b average
 of another topology's cells are stored.  The index depth of the new
 topology will be one more than that of the original one.
 */
F5_API void F5Rcreate_downsampling(F5Path*Topology, const hsize_t*downsampling);
 
/**\ingroup F5R
 Create a topology suitable for subsampled data, i.e. where a \b subset
 of another topology's cells are stored. Note that the same data can also
 be retrieved by HDF5 hyperslabbing, but storing an hyperslab as a contigous
 data set may be helpful for faster data access. The index depth of the new
 topology will be identical to the original one.
 */
F5_API void F5Rcreate_subsampling (F5Path*Topology, const hsize_t*subsampling);
 
 
 
 
 
/**\ingroup F5R
  Create a symbolic links from some vertex refinement topology group
  to the default group "Points".
  @return non-zero in case of errors, like invalid arguments.
  @param grid Pointer to an F5Path object. It must contain a valid
                   Grid_id identifiert.
 @todo Check for an eventually existing "Points" group and handle HDF5 error codes.
 */
F5_API int F5Rlink_default_vertex_topology(F5Path*grid,
                                           const hsize_t target_refinement[3]);
 
 
/**\ingroup F5R
   Set information about an integer timestep (per Grid object!)
   This is an recommended attribute for data originating from
   subsequent simulations. It may be omitted on interpolated
   grid objects to specify that these are secondary data that
   can be reproduced from grids with Timestep information.
   @return non-zero if the timestep could be set, and zero (false)
           if the grid object in charge already has a timestep
           attached with it but is inconsistent with the specified one.
 */
F5_API int F5Rset_timestep(F5Path*path, long timestep);
 
/**\ingroup F5R
   Get information about the optional integer timestep of an Grid object.
   All fields per grid object must refer to the same integer timestep.
   If a Grid object does not provide such timestep information, it
   may be an interpolated grid that can be computed from others
   that contain such timestep information. The timestep value
   by itself is arbitrary, but must be unique among all Grid objects
   with the same Grid identifier.
   @return NULL, if no timestep information was found, or the F5Path
           does not refer to a Grid object.
 */
F5_API long*F5Rget_timestep(F5Path*path, long*timestep);
 
#ifdef  __cplusplus
}    /* extern "C" */
#endif
 
#endif  /* __F5R_H */