F5Bchart.h

Go to the documentation of this file.

/*
 $Id: F5Bchart.h,v 1.23 2008/03/19 21:21:43 werner Exp $
*/
 
#ifndef __F5_F5Bchart_H
#define __F5_F5Bchart_H
 
#include "hdf5inc.h"
#include "F5defs.h"
#include "F5types.h"
 
#include "F5WinDLLApi.h"
 
#ifdef  __cplusplus
extern "C"
{
#endif
 
enum
{
        /** number of additional file types in ChartPrecisions */
        F5ChartPrecisionMaxNumberOfFileTypes = 32
};
 
 
/**
   A structure containing a set of commonly used
   types per chart, notation according to geometric
   algebra and differential geometry.
   @relates F5Bchart_add_tangential_types()
 
Constructor:void F5Bchart_init_tangential_types(F5_ChartPrecisionTypes*IDs,
                                        const char*coordnames[],
                                        int dimension,
                                        hid_t coord_type);
 
Destructor: void F5B_delete_tangential_types(F5_ChartPrecisionTypes*IDs);
 
 */
struct  _F5_ChartPrecisionTypes
{
                /** HDF5 type ID for points */
        hid_t   Point_hid_t,
 
                /** HDF5 type ID for directions (tangential vectors) */
                Vector_hid_t,
 
                /** HDF5 type ID for covectors */
                Covector_hid_t,
 
                /** HDF5 type ID for bivectors */
                Bivector_hid_t,
 
                /** HDF5 type ID for bicovectors */
                Bicovector_hid_t,
 
                Pseudoscalar_hid_t,
 
                Pseudocoscalar_hid_t,
 
                Metric_hid_t,
 
                Cometric_hid_t;
 
        /**
           Additional file types that may be stored here.
         */
        hid_t   AdditionalFileTypes[F5ChartPrecisionMaxNumberOfFileTypes];
};
 
typedef struct _F5_ChartPrecisionTypes F5_ChartPrecisionTypes;
 
/**
   Initializes the Poind_hit_t with some newly constructed
   transient HDF5 type while setting all other entries to 0.
 */
F5_API void F5B_init_tangential_types(F5_ChartPrecisionTypes*H5Types,
                                      const char*coordnames[],
                                      int dimension,
                                      hid_t coord_type);
 
 
F5_API void F5Bt_add_tangential_types(F5_ChartPrecisionTypes*H5Types,
                                      const char*coordnames[],
                                      int dimension,
                                      hid_t coord_type);
 
/**
   Add a type ID to the additional file types, ready to
   be deleted by F5B_delete_tangential_types(F5_ChartPrecisionTypes*IDs);
 */
F5_API int F5B_inject_precision_type(F5_ChartPrecisionTypes*IDs,
                                     hid_t type_id);
 
/**
   Destructor for F5_ChartPrecisionTypes.
 */
F5_API  void F5B_delete_tangential_types(F5_ChartPrecisionTypes*IDs);
 
F5_API  void F5Bchart_read_tangential_types(F5_ChartPrecisionTypes*H5Types,
                                           hid_t        location);
 
 
/**
  Description of a class of coordinate systems,
  i.e. coordinate system that are allowed to share
  their positional types.
 */
typedef struct
{
        /** name for this class of coordinate systems (e.g. cartesian 3D, polar 2D, ...) */
        const char*domain_name;
 
        unsigned  refs;                 /**< reference counter */
 
        /**
           Each type of coordinate system is associated with a certain
           ordering of multidimensional data.
           This is the place to specify whether FORTRAN or C order is used
           for multidimensional arrays.
           @note The predefined F5 coordinate systems use FORTRAN order for
                 compatibility with
                 - numerical simulation programs, which are mostly written in FORTRAN
                 - OpenGL, where the lowest dimension (x) runs fastest
                 - the Amira visualization system
                 - the canonical indexing of images, where the lowest dimension x runs
                   faster than y
                 This convention is reversed as compared to a native definition of a
                 matrix using C arrays of the form
                 <PRE>
                 float  matrix[X][Y];
                 </PRE>
                 Here, the dimension Y would run faster in memory than X.
                 If data are stored in this layout (C order), they have to be put
                 into another coordinate system within the context of F5.
                 Different indexing layouts can be mapped onto each other like
                 a coordinate transformation rule. Such a mapping might be
                 straightforward, but involves some computation (which is similar
                 to true coordinate transformations).
         */
        int     perm_vector[FIBER_MAX_RANK];
        int     cell_dimensionality;
 
        F5_ChartPrecisionTypes
                OneBytePrecision,       /**<  1 Byte,   8 bit */
                HalfPrecision,          /**<  2 Byte,  16 bit */
                SinglePrecision,        /**<  4 Byte,  32 bit */
                DoublePrecision,        /**<  8 Byte,  64 bit */
                ExtendedPrecision;      /**< 16 Byte, 128 bit */
 
        /**
          Array of pointers to tensor type descriptions.
          Terminated by NULL pointer;
         */
        F5Ttensor_t**TensorTypes;
 
}
        ChartDomain_IDs;
 
 
F5_API void F5Binsert_tensor_type(ChartDomain_IDs*CD, F5Ttensor_t*);
F5_API F5Ttensor_t*F5Bget_tensor_type_byname(ChartDomain_IDs*CD, const char*name);
 
/**@ingroup F5B
   Given the size of some type in byte, yield the appropriate
   precision type structur from a chart domain.
   The function will fail if the TypeSize is anything but 1,2,4,8 or 16.
 */
F5_API F5_ChartPrecisionTypes*F5Bget_precision_by_size(ChartDomain_IDs*CD, int TypeSize);
 
/**@ingroup F5B
   Given some compound type, yield the precision type corresponding to the
   compound type's first member.
   The function will fail if the provided type is not a compound type.
 */
F5_API F5_ChartPrecisionTypes*F5Bget_precision_by_type(ChartDomain_IDs*CD, hid_t type_id);
 
 
/**
 Prototype of a function creating a new class of coordinate systems.
 (Chart domain constructor).
 */
typedef ChartDomain_IDs*(*new_global_chart_f)();
 
/**\ingroup F5B
  Construct a new domain type.
  A domain type specifies how points from one topology are mapped onto
  another one. It is a subset of a chart, in that it defines the
  basic mapping from points onto another, but no tangential types
  like vectors.
@TODO Add complementary cleanup function.
 */
F5_API ChartDomain_IDs*F5B_new_global_domain(const char*coordnames[],
                                             int dimension,
                                             const char*name,
                                             const int perm_vector[],
                                             int cell_dimensionality,
                                             hid_t SinglePrecisionType,
                                             hid_t DoublePrecisionType
        );
 
 
/**\ingroup F5B
 Construct a new coordinate type.
 @param coordnames Array of names for each coordinate.
 @param dimension  Dimensionality of this coordinate system.
 @param name       Some naming for all instances of this coordinate systems.
 @todo Reorder argument list.
 @TODO Add complementary cleanup function.
 
  Creates a chart with floating point types.
 
  Only the creation of homogeneous coordinates is supported
  through this interface.
*/
F5_API ChartDomain_IDs*F5B_new_global_float_chart(const char*coordnames[],
                                                  int dimension,
                                                  const char*name,
                                                  const int perm_vector[FIBER_MAX_RANK] );
 
F5_API ChartDomain_IDs*F5B_new_global_int_chart(const char*coordnames[],
                                           int dimension,
                                           const char*name,
                                                const int perm_vector[FIBER_MAX_RANK]);
 
/**
   Create a domain with positions in n-dimensional integer coordinates,
   where 32bit and 64bit are available ( H5T_NATIVE_B32 and  H5T_NATIVE_B64
   in HDF5.)
 */
F5_API ChartDomain_IDs*F5B_new_global_int_domain(const char*coordnames[],
                                                 int dimension,
                                                 const char*name,
                                                 const int perm_vector[FIBER_MAX_RANK],
                                                 int cell_dimensionality);
 
F5_API ChartDomain_IDs*F5B_new_global_fractional_domain(const char*coordnames[],
                                                        int dimension,
                                                        const char*name,
                                                        const int perm_vector[],
                                                        int cell_dimensionality);
 
 
/*F5_API ChartDomain_IDs*F5Bcopy_chart(ChartDomain_IDs*oldchart, const char*newname); */
 
/**
   Make a copy of a coordinate domain. All types are created from the
   existing information as if it were created from scratch.
   This function may be used to convert named data types into
   transient types. This is e.g. useful when reading a file.
@TODO Add complementary cleanup function.
 */
F5_API ChartDomain_IDs*F5Bcopy_chart_domain(const ChartDomain_IDs*IDs);
 
 
/**
   Get the dimensionality of this chart.
   This information is taken from the number of elements of
   the associated point type.
 */
F5_API int      F5Bget_chart_dims(const ChartDomain_IDs*IDs);
 
#ifdef  __cplusplus
#define F5_FORTRAN_ORDER        reinterpret_cast<int*>(0)
#define F5_C_ORDER              reinterpret_cast<int*>(-1)
#else
#define F5_FORTRAN_ORDER        ((int*)(0))
#define F5_C_ORDER              ((int*)(-1))
#endif
 
/**
   Permute a given dimensions array according to the given permutation vector.
   @param source_dims The source dimensions.
   @param target_dims The target dimensions array, may be identical to the source
                      dimensions array.
   @return A pointer to the target dimensions array.
 
   @param perm_vector The permutation vector, may be F5_FORTRAN_ORDER, F5_C_ORDER
                      or an explicity integer array specifying an arbitrary reodering
                      of indices.
 
  @see  F5B_fortran_permute_vector()
 
  @todo Make the define  F5_FORTRAN_ORDER identical to the return value of
        F5B_fortran_permute_vector(). This is a possible optimization, currently there
        are two equivalent ways of specifying FORTRAN ordering.
 */
F5_API hsize_t*F5B_permute_dimensions(hsize_t*target_dims,
                                      int rank,
                                      const hsize_t*source_dims,
                                      int perm_vector[FIBER_MAX_RANK],
                                      int perm_vector_size);
 
/**
   Return a (static) permutation vector for fortran memory layout.
   It always has FIBER_MAX_RANK entries, i.e. is of the form
   { FIBER_MAX_RANK-1, FIBER_MAX_RANK-2, ..., 2,1,0 }
  */
F5_API const int*F5B_fortran_permute_vector();
 
/**
 Free the memory resources that are associated with a certain
 coordinate system.
*/
F5_API void F5B_delete_global_chart(ChartDomain_IDs*ID);
 
F5_API void F5Bincrement_domain_refs(ChartDomain_IDs*ChartDomain);
 
F5_API ChartDomain_IDs*F5B_save_global_chart(const ChartDomain_IDs*IDs, hid_t Domain_hid);
F5_API ChartDomain_IDs*F5B_read_global_chart(hid_t ChartsID, const char*name);
 
F5_API ChartDomain_IDs*F5B_read_chart_domain(hid_t ChartDomainLocationID, const char*DefaultChartName);
        
F5_API ChartDomain_IDs*F5B_new_global_cartesian_chart3D();
 
#ifdef  __cplusplus
}    /* extern "C" */
#endif
 
#endif  /* __F5_F5Bchart_H */