F5.doxm

Go to the documentation of this file.

/**
  \mainpage The Fiber Bundle HDF5 Library.
 
\image html TensorFibers-F5Logo.png "The F5 Library"
 
 The purpose of this library is to provide a simple C-API for
writing HDF5 files using the concept of fiber bundles. It allows
to cover a wide range of data types used for scientific computing
through a common denominator in a mathematically founded 
systematic approach.
 
In the concept of fiber bundles, we distinguish among a base space
and a fiber space. The base space corresponds to a mesh type or
"grid", e.g. a regular or irregular grid. The fiber space corresponds
to data given on each vertex or cell type, e.g. scalar fields,
vector fields, tensor fields, spinor fields. Taking into account
practical requirements in scientific visualization, the abstract
concept has been cast into six levels of hierarchy within an HDF5
file layout.
 
 
A detailed description of the concept has been developed as part of the PhD
thesis
<A HREF="http://www.lob.de/cgi-bin/work/outputexpert?id=433b39bc517ad&frame=yes&flag=new&menupic=yes&mode=viewone&titnr=242395908&linkcol=005c21&stich=benger+&katalog=255">Visualization of General Relativistic Tensor Fields via a Fiber Bundle Data Structure</A>.
<IMG ALIGN=RIGHT SRC="http://images.lob.de/lob_100_pics/386/541/10/88.jpg">.
 
See \ref GettingStarted for a practical guide on getting started.
 
<H2>Supported Features</H2>
 
        - Intrinsic support for time
                - one or many timesteps per file
                - connectivity information across time steps
                - using other ordering parameters instead of time
        - Multiple coordinate systems
                - cartesian coordinates
                - polar coordinates
                - two-dimensional coordinates (e.g. texture coordinates)
                - transformation rules among coordinate systems
                - abstraction level to allow coordinate-free formulations
        - Extended data types
                - vector fields
                - tensor fields
                - covariant and contravariant indices
                - coordinate transformation rules for vector and tensor fields
        - Transparent support for different field layouts
                - arrays of structs
                - struct of arrays
        - Arbitrary dimensions
                - one-dimensional data
                - two-dimensional data (surfaces)
                - three-dimensional data (volumes)
                - higher dimensions up to HDF5 limit
        - Structured and unstructured grid types
                - particle systems
                - triangular surfaces
                - regular surfaces
                - uniform grids
                - regular grids
                - adaptive hierarchical meshes (AMR data)
                - curvilinear grids (n.i.)
                - tetrahedral grids (n.i.)
                - hexahedral grids (n.i.)
                - unstructured grids (n.i.)
        - Cell complexes
                - grouping of grid cells
                - assigning values to cell groups (surface patches)
        - Designed to support remote file I/O
                - streaming HDF5
                - HDF5 via GridFTP
                - all required information can be contained in a single HDF5 file
                - data can also be spread among multiple files and uniquely merged
                - file split possible on adjustable granularity
        - Simple end-user API
                - minimal API overhead
                - allows access to HDF5 structure
                - open for non-interfering user extensions
 
 
<H2>Implementation Concepts</H2>
 
        - avoid implicit assumptions as much as possible
        - use existing HDF5 functionality as much as possible
        - avoid relying on textual information as much as possible
                - avoid special naming conventions for groups, datasets, attributes
                - formulate relationships via grouping structure, types and links
                - enhances robustness when allowing user-defined extensions
 
<H2>Installation Notice</H2>
F5 requires at least
<A HREF="http://www.hdfgroup.org/">HDF5 1.6.1</A>. 
Earlier versions of HDF5 will not work because they
failed to support shared types on attributes.
 
F5 is available under \ref copyright.
 
For compilation, two modes are available: `Debug' and `Optimize'.
Switch between these modi by setting the environment variable <TT>MAKE_CFG</TT>
or on the command line when invoking make:
<TT>make MAKE_CFG=Optimize</TT>
or <TT>make MAKE_CFG=Debug</TT>. Alternatively,
<TT>MAKE_CFG</TT> may be set as environmment variable, too. 
 
The licensing conditions allow F5 to be freely to used for academic and private
purposes. Distribution with GNU software is permitted, as long as this other 
software does not require this software to be GNU, too.
 
*/
 
 
/** \page internal File structure 
 
The HDF5 file is organized into six hierarchy levels.
These are called the Bundle, Slice, Grid, Topology, Representation and Field levels.
The Bundle group is the toplevel group, i.e. the HDF5 file itself.
Subgroups with a time attribute constitute a Slice group, which contains
all data related to a specific time.
<P>
A Slice group may contain many geometrical objects, called "Grids".
The name of this group is arbitrary, each Grid group contains a
self-consistent geometrical entity (e.g. a uniform grid with
refinement levels, a triangular surface, a tetrahedral grid,
an adaptive mesh with all refinement levels).
<P>
A Grid will be described by one or many datasets.
All datasets within a Grid which are of the same size and dimensioniality
and are semantically related to the same indexing scheme (e.g. all data fields
within a given AMR refinement level, or data given on the cells of a tetrahedral
grid) are grouped together into Topology groups.
<P>
Data sets within Topology groups are further organized into Representation
groups according to their relationship to other objects. The name of the
Representation group (and possible attributes) tell the relation of a certain
data set, e.g. a Representation group may be named "cartesian chart 3D" or
"parent level".
*/