F5uniform.h

Go to the documentation of this file.

/*
 *
 * $Id: F5uniform.h,v 1.25 2007/01/16 18:42:49 werner Exp $
 *
 * $Log: F5uniform.h,v $
 * Revision 1.25  2007/01/16 18:42:49  werner
 * Revision of the chart/coordinate interface in FiberLib2, simpler, easier,
 * more existent now.
 *
 * Revision 1.24  2005/10/28 05:00:21  werner
 * slight improvement of documentation and vector field example added.
 * will add particle vectors and surface vectors soon.
 *
 * Revision 1.23  2004/03/22 15:30:05  werner
 * Generalized treatment of refinement within the framework of relative representations. Closer to better support of downsampling topologies.
 * Improved documentation.
 *
 * Revision 1.22  2004/03/10 16:27:14  werner
 * Introduced a type for rational numbers to specify coordinates of
 * refinement levels that are not exactly vertex-aligned.
 * Preliminiary Carpet F5 thorn appears to implement the fiber concept correctly
 * at first sight.
 *
 * Revision 1.21  2003/11/12 15:21:31  zib
 * added more ContentType stuff
 *
 * Revision 1.20  2003/11/06 20:50:12  zib
 * fixed typo
 *
 * Revision 1.19  2003/11/04 19:24:10  werner
 * Revised version including a table of contents and field info per grid, and
 * also telling the grids per field (reverse look). The API has been revised
 * somewhat, such that F5F... function are all functions operation on F5Path
 * objects with fields defined.
 *
 * Revision 1.18  2003/08/12 12:30:09  werner
 * API change: do not return F5Path* when the argument is only modified, just return boolean
 * indicating success.
 *
 * Revision 1.17  2003/07/17 10:36:41  werner
 * Corrected documentation.
 * Added F5Iignore() function to tell which groups shall be ignored during iteration.
 *
 * Revision 1.16  2003/06/16 11:00:20  werner
 * Changed the iterator functions to use F5Path objects instead of HDF5 ID's.
 * This makes encapsulates more of HDF5 and insists more of using F5,
 * but makes retrieving the F5 information easier.
 * Also changed back the shared data types to nameless types. Thus type
 * attributes cannot be determined directly, but when using F5 functions this
 * information, e.g. the Memory Order that is associated with a coordinate system
 * is available anyway.
 *
 * Revision 1.15  2003/06/14 12:09:25  werner
 * Incorporated Steffen's complains about the Size attribute of pseudo-datasets,
 * these are now written with an explicit DataSpace naming which is "reversed" like
 *  native HDF5 dataspaces, and an "extent" attributes, which specifies integer
 * coordinates.
 * Also optimized saving of types to only save types which have actually been used
 * for datasets (which is somewhat more work and requires more care when writing
 * datasets to register used datatypes).
 * Moreover shared datatypes are used now when possible to ease the access to
 * centralized datatype properties. However, this required replacing some attributes
 * with datasets in write_linear(), due to HDF5 insufficiencies. Hopefully this does not
 * introduce problems, it shouldn't.
 *
 * Revision 1.14  2003/06/13 16:30:57  zib
 * added F5Bswap_dims. renamed prop_id -> property_id
 * using F5Bswap is pending until size/Size/dataspacesize discussion
 * has settled.
 *
 * Revision 1.13  2003/05/27 11:52:15  zib
 * added F5_API stuff to build dll, if you like to build
 * a static lib you'll have to define F5_STATIC during every
 * build using the headers
 *
 * Revision 1.12  2003/05/09 15:50:57  werner
 * Ongoing support for user-defined coordinate systems.
 *
 * Revision 1.11  2003/05/06 11:00:29  werner
 * Added property lists to F5 field write() functions and
 * added an interface function for writing data in different refinement levels,
 * as a special case of AMR data.
 *
 * Revision 1.10  2003/04/28 09:07:12  werner
 * Disabled error message when creating a link to a group that already exists.
 *
 * Revision 1.9  2003/01/28 14:55:43  tino
 * Implemented F5write_uniform_cartesian3Dv(s)
 *
 * Revision 1.8  2003/01/28 00:34:21  tino
 * Only some small changes to docu.
 *
 * Revision 1.7  2002/12/21 19:02:11  werner
 * added a bunch of various coordinate systems
 * and better support on using them.
 *
 * Revision 1.6  2002/12/20 13:55:53  tino
 * Small change on Documentation
 *
 * Revision 1.5  2002/12/18 11:38:14  werner
 * improved documentation
 *
 * Revision 1.4  2002/12/11 16:29:25  werner
 * Simplified API, added documentation.
 * Still some functions need to be implemented.
 *
 * Revision 1.3  2002/12/10 15:43:19  werner
 * Added files for generating a good doxygen documentation.
 * Also included some preliminiary licensing as derived from Light++.
 * Modifications (enhancements!) are welcome, of course.
 *
 * Revision 1.2  2002/12/10 13:03:14  werner
 * Improved field interface, now also used for the uniform grid fields
 *
 * Revision 1.1  2002/10/17 15:29:28  werner
 * Added a couple of more or less randomly introduced functions, all of them
 * might be useful, but it really needs a better API design, otherwise we
 * end up with hundrets of functions. Some kind of object-oriented C-API
 * would be cool.
 *
 *
 */
 
#ifndef __F5uniform_H
#define __F5uniform_H
 
#include "F5F.h"
#include "F5coordinates.h"
#include "F5L.h"
 
#include "F5WinDLLApi.h"
 
#define FIBER_REGULAR_GRID_URL FIBER_VERSION_URL "RegularGrid-0.1.0/"
 
#ifdef  __cplusplus
extern "C"
{
#endif
 
/** \defgroup regular Regular Grids
*/
 
/** @{ */
 
/**
   Create a representation that is rectilinear, uniform or stacked in the given
   coordinate system.
 
  @param origin          The origin of the grid, must be of the coordinate type that
                         is associated with the coordinate system.
  @param spacing         The distance among neighboring points of the grid, must be of
                         the vector type of the coordinate system, i.e. the coordinate
                         type that stores coordinate differences.
  @param coordinate_system The coordinate system.
                         May be NULL to refer to the standard cartesian chart.
 
  @param property_id     HDF5 property for storing the coordinate arrays in the file,
                         e.g. chunked and/or compressed. May be F5P_DEFAULT.
             The property will be used to create 1D arrays.
             The coordinate arrays are usually small compared
             to the field data. Therefore, the default should be fine
             for all cases.
 
  @param ...            The argument list is to be succeeded by a list of data
                        pointers, each of them pointing to a one-dimensional
                        array of data values. One array per coordinate needs to
                        be specified (but may be NULL), with exactly the same type
                        as in the coordinate system's point type.
*/
F5_API F5Path*F5Rcreate_rectilinear(hid_t File_id, double time,
                                     const char*gridname,
                                     const void*origin,
                                     const void*spacing,
                                     hsize_t*dims,
                                     const char*coordinate_system,
                                     hid_t property_id,
                                     ...);
 
F5_API int F5get_extension(F5Path*grid,  hsize_t dims[FIBER_MAX_RANK]);
 
 
/**
  Create a regular grid with rectilinear or stacked coordinates.
  If the one-dimensional coordinate arrays are omitted, then a linear
  mapping based on the origin and spacing parameters is assumed.
  If all coordinate arrays are given, then the origin and spacing
  information is not used. Otherwise, if none of the coordinate arrays
  is given, then the coordinates will be uniform.
  \see F5create_uniform_cartesian3D(),F5create_rectilinear()
 
  @param x Coordinate values in x direction, may be NULL.
  @param y Coordinate values in y direction, may be NULL.
  @param z Coordinate values in z direction, may be NULL.
 
*/
F5_API F5Path*F5Rcreate_rectilinear_cartesian3D(hid_t File_id, double time,
                                     const char*gridname,
                                     const F5_vec3_point_t*origin,
                                     const F5_vec3_float_t*spacing,
                                     hsize_t dims[3],
                                     const char*coordinate_system,
                                     hid_t property_id,
                                     float*x,float*y,float*z);
 
 
/**
  Create a regular grid with curvilinear coordinates.
  \see F5create_uniform_cartesian3D(),F5create_rectilinear()
*/
F5Path*F5Rcreate_curvilinear_cartesian3D(hid_t File_id, double time,
                                         const char*gridname,
                                         const F5_vec3_point_t*coords,
                                         hsize_t dims[3],
                                         const char*coordinate_system,
                                         hid_t property_id);
 
/** \defgroup unigrid Uniform Grids
*/
 
/** @{ */
 
/**
 Create a regular grid which is uniform in the specified coordinate system.
 
  @param origin          The origin of the grid, must be of the coordinate type that
                         is associated with the coordinate system.
  @param spacing         The distance among neighboring points of the grid, must be of
                         the vector type of the coordinate system, i.e. the coordinate
                         type that stores coordinate differences.
  @param coordinate_system The coordinate system.
                         May be NULL to refer to the standard cartesian chart.
 
  @return A new F5Path pointer. Call F5close() if it is no longer used.
 */
F5_API F5Path*F5Rcreate_uniform(hid_t File_id, double time,
                                const char*gridname,
                                const void*origin,
                                const void*spacing,
                                hsize_t*dims,
                                const char*coordinate_system);
 
 
/** Create a regular three-dimensional grid which is uniform in the specified
        coordinate system.
 
  @param coordinate_system The coordinate system.
                           May be NULL to refer to a standard chart.
 
  @return A new F5Path pointer. Call F5close() if it is no longer used.
 */
F5_API F5Path*F5Rcreate_uniform_cartesian3D(hid_t file_id, double time,
                                            const char*gridname,
                                            const F5_vec3_point_t*origin,
                                            const F5_vec3_float_t*spacing,
                                            hsize_t dims[3],
                                            const char*coordinate_system);
 
F5_API F5Path*F5Rcreate_uniform_cartesian3Dbbox(hid_t File_id, double time,
                                                const char*gridname,
                                                const F5_vec3_point_t*start,
                                                const F5_vec3_point_t*end,
                                                hsize_t dims[3],
                                                const char*coordinate_system);
 
/**
 *  Write a data field given on uniform cartesian grid into file.
 
        @param coordinate_system The coordinate system.
                          May be NULL to refer to a standard chart.
 
 
  @return A new F5Path pointer. Call F5close() if it is no longer used.
 */
F5_API F5Path* F5Fwrite_uniform_cartesian3D(hid_t file_id, double time,
                                            const char*gridname,
                                            const F5_vec3_point_t*origin,
                                            const F5_vec3_float_t*spacing,
                                            hsize_t dims[3],
                                            const char*fieldname,
                                            hid_t fieldtype,
                                            const void * dataPtr,
                                            const char*coordinate_system,
                                            hid_t property_id);
 
/**
Write a bunch of data fields given on the same uniform cartesian grid.
This variation of the uniform grid writer function uses a variable number
of arguments list. Each field is defined by a triple of
<PRE>
  const char *fieldname
  hid_t fieldtype
  const void  *dataPtr
</PRE>
If either the fieldname or the dataPtr are NULL, then the traversal of the
argument is terminated.
 
@param coordinate_system The coordinate system.
                  May be NULL to refer to a standard chart.
 
@return The number of successfully written fields.
 */
F5_API int F5write_uniform_cartesian3Dv(hid_t file_id, double time,
                                 const char*gridname,
                                 const F5_vec3_point_t*origin,
                                 const F5_vec3_float_t*spacing,
                                 hsize_t dims[3],
                                 const char*coordinate_system,
                                 hid_t property_id,
                                 ...);
 
/**
Write a bunch of data fields given on the same uniform cartesian grid.
This variation of the uniform grid writer function uses a variable number
of arguments list. Each field is defined by a triple of
<PRE>
  const char *fieldname
  hid_t fieldtype
  const void **dataPtr
</PRE>
If either the fieldname or the dataPtr are NULL, then the traversal of the
argument is terminated.
 
@param coordinate_system The coordinate system.
                  May be NULL to refer to a standard chart.
 
@return The number of successfully written fields.
 */
F5_API int F5write_uniform_cartesian3Dvs(hid_t file_id, double time,
                                 const char*gridname,
                                 const F5_vec3_point_t*origin,
                                 const F5_vec3_float_t*spacing,
                                 hsize_t dims[3],
                                 const char*coordinate_system,
                                 hid_t property_id,
                                 ...);
 
/**
Write a data field given on uniform cartesian grid for a given coordinate system
into file.
If the data is a compound data type, then it is given as distinct
homogeneous arrays in memory.
 
@param coordinate_system The coordinate system.
                  May be NULL to refer to a standard chart.
 
@return A new F5Path pointer. Call F5close() if it is no longer used.
 */
F5_API F5Path* F5Fwrite_uniform_cartesian3Ds(hid_t file_id, double time,
                                             const char*gridname,
                                             const F5_vec3_point_t*origin,
                                             const F5_vec3_float_t*spacing,
                                             hsize_t dims[3],
                                             const char*fieldname,
                                             hid_t fieldtype,
                                             const void ** dataPtr,
                                             const char*coordinate_system,
                                             hid_t property_id);
 
 
/* A sparse uniform grid only has values at explicitely specified indices, which are decribed
   in a field called Sparse. Sparse contains 1D indices (which can be mapped to and from an
   N dimensional index.
   Origin, delta and dimensions size are stored in the positions field (as group attributes).
   Alternative version, see below.
*/
F5_API F5Path*F5Rcreate_uniform_sparse( hid_t file_id, double time,
                                        const char*gridname,
                                        const void*origin,
                                        const void*spacing,
                                        hsize_t*dims,
                                        const char*coordinate_system,
                                        const hsize_t*sparse_idx_Ptr,
                                        const hsize_t sparse_size,
                                        hid_t property_id );
 
/* Experimental alterntive, by using attributes on the index field 'Sparse'. Seems a bit more consistent. */
F5_API F5Path*F5Rcreate_uniform_sparse2( hid_t file_id, double time,
                                         const char*gridname,
                                         const F5_vec3_double_t*origin,
                                         const F5_vec3_double_t*spacing,
                                         hsize_t*dims,
                                         const char*coordinate_system,
                                         const hsize_t*sparse_idx_Ptr,
                                         hsize_t sparse_size,
                                         hid_t property_id );
 
 
#if 0
/**
   Get the vertex data for a given grid- and fieldname in cartesion coordinates.
 */
F5_API hid_t F5BgetUniformCartesianGridVertexData3D(hid_t SliceID,
                                                    const char*gridname,
                                                    const char*fieldname,
                                                    F5_vec3_point_t*bbox_min, F5_vec3_point_t*bbox_max,
                                                    int dims[3]);
#endif
 
 
 
/** @} */
 
/** @} */
 
 
#ifdef  __cplusplus
}    /* extern "C" */
#endif
 
#endif  /* __F5uniform_H */