Functions
F5_API void	F5close (F5Path *f)
F5_API int	F5Fread_linear (F5Path fpath, hsize_t dims, hid_t fieldtype, void base, void delta)
F5_API hid_t	F5Lcreate (hid_t R_id, const char fieldname, int dimension, const hsize_t dims, hid_t fieldtype, hid_t property_id)
F5_API hid_t	F5LTcreate_topology (hid_t Grid_hid, const char TopologyName, int IndexDepth, int SkeletonDimensionality, int DataspaceDimensionality, const hsize_t refinement)
F5_API int	F5LTset_maximal_grid_refinement (hid_t ContentsGroup_id, const char gridname, int Dimensionality, const hsize_t refinement)
F5_API int	F5LTget_maximal_grid_refinement (hid_t ContentsGroup_id, const char gridname, hsize_t refinement)
F5_API int	F5LTget_index_depth (hid_t Top_hid)
F5_API hid_t	F5Lwrite (hid_t R_id, const char fieldname, int dimension, const hsize_t dims, hid_t fieldtype, hid_t memtype, const void *dataPtr, hid_t enum_type, hid_t property_id)
F5_API hid_t	F5Lwrite_fraction (hid_t R_id, const char fieldname, int dimension, const hsize_t full_dims, const hsize_t datasize, hid_t fieldtype, hid_t memtype, const void dataPtr, const hsize_t datastart, const hsize_t start_border, const hsize_t end_border, const char fraction_name, hid_t enum_type, hid_t property_id)
F5_API hid_t	F5LSwrite_fraction (hid_t R_id, const char fieldname, int dimension, const hsize_t full_dims, const hsize_t datasize, hid_t fieldtype, hid_t memtype, const void const dataPtr, const hsize_t datastart, const hsize_t start_border, const hsize_t end_border, const char *fraction_name, hid_t enum_type, hid_t property_id)
F5_API hid_t	F5Lwrite1D (hid_t R_id, const char fieldname, hsize_t nElements, hid_t fieldtype, hid_t memtype, const void dataPtr, hid_t enum_type, hid_t property_id)
F5_API hid_t	F5Lwrite_linear (hid_t R_id, const char fieldname, int dimension, const hsize_t dataspace_dims, hid_t fieldtype, const void base, const void delta)
F5_API hid_t	F5Lread_linear (hid_t F_id, hsize_t dims, hid_t fieldtype, void base, void *delta)
F5_API hid_t	F5Lwrite_entity (hid_t R_id, const char fieldname, hid_t fieldtype, const void value)
F5_API hid_t	F5Lwrites (hid_t F_id, const char fieldname, int dimension, const hsize_t dims, hid_t fieldtype, hid_t memtype, const void const dataPtr, hid_t enum_type, hid_t property_id)
F5_API hid_t	F5Lwrite_permutation (hid_t R_id, const char fieldname, hsize_t size, hsize_t permutation_indices, hsize_t nvalues, hid_t fieldtype, const void *dataPtr)
F5_API hid_t	F5Lget_type (hid_t Field_hid, int FieldIDisGroup)
F5_API int	F5Lget_field_dimension_and_type (hid_t Representation_hid, const char fieldname, hsize_t dims[FIBER_MAX_RANK], hid_t type_id)
F5Path *	F5LTcreateV (hid_t File_id, const double time, const char gridname, ChartDomain_IDs ChartDomain, ChartDomain_IDs coord_creator(void udata), void udata, const char coordinate_system, const char TopologyName, int IndexDepth, int SkeletonDimensionality, int Dimensionality, const hsize_t *refinement)
F5Path *	F5LTcreate (hid_t File_id, const double time, const char gridname, ChartDomain_IDs ChartDomain, ChartDomain_IDs coord_creator(), const char coordinate_system, const char TopologyName, int IndexDepth, int SkeletonDimensionality, int Dimensionality, const hsize_t *refinement)
F5_API F5Path *	F5LTcreate (hid_t File_id, const double time, const char gridname, ChartDomain_IDs ChartDomain, new_global_chart_f coord_creator, const char coordinate_system, const char TopologyName, int IndexDepth, int SkeletonDimensionality, int DataspaceDimensionality, const hsize_t refinement)

Detailed Description

Todo:: Separate these functions into F5-Dataset functions, with prefix F5D, of the form:

Functions taking contigous compounds (data given as void*), zero components not supported:
- F5Dcreate()
- F5Dwrite()
- F5Dsave() (convenience function: create + write with same field type, no I/O type conversion)
- F5Dis()
- F5Dopen()
- F5Dread()
- F5Dload() (convenience function: open + read)
Functions taking separated compounds (data given as void**), missing components supported:
- F5DS...() (6 functions)

Special datasets:
- F5D*_fraction()
- F5D*_linear()
- F5D*_entity()

Utility functions:
- F5Dget_type()
- F5Dget_space()

Low-level functions:
- F5Dset_type_attribute()

Function Documentation

F5_API void F5close ( F5Path * f )

Remove a F5Path object.

F5_API int F5Fread_linear	(	F5Path *	fpath,
		hsize_t *	dims,
		hid_t	fieldtype,
		void *	base,
		void *	delta
	)

Try to read a field which is a linear mapping of a base and delta value. The fpath object gets the the field identifier set to the opened field (which is available to retrieve additional user-defined attributes and such).

dims The dimensions of integer coordinates.

Returns:: zero, if the entry could not be opened, non-zero if successfull.

F5_API hid_t F5Lcreate	(	hid_t	R_id,
		const char *	fieldname,
		int	dimension,
		const hsize_t *	dims,
		hid_t	fieldtype,
		hid_t	property_id
	)

Create an HDF5 dataset for further treatment with raw HDF5 functions, e.g. to write an hyperslab instead of the full dataset at once.

Returns:: A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.

Parameters:

	property_id	An HDF5 dataset property ID. If it is negative, then a default property will be created locally via H5Pcreate(H5P_DATASET_CREATE) .
	dataspace_id	Pointer to an HDF5 identifier, that will be used to store a shared dataspace. It may be NULL, in which case a local dataspace is created. Until shared dataspaces are implemented in HDF5, this will make no difference in the actual HDF5 file.
	R_id	The group ID where the field shall be inserted, preferably a representation group ID that has been created by an F5create_representation() call.
	fieldname	The name of the field. It may be chosen arbitrarily, but must not contain slashes "/". It is furthermore recommended to avoid special characters - even if they work - and to keep the name short and concise).
	dimension	The dimensionality of the data set.
	dims	The extension of the data set.
	fieldtype	An HDF5 type identifier.

F5_API int F5Lget_field_dimension_and_type	(	hid_t	Representation_hid,
		const char *	fieldname,
		hsize_t	dims[FIBER_MAX_RANK],
		hid_t *	type_id
	)

Retrieve dimensional and type information for a specific field.

F5_API hid_t F5Lget_type	(	hid_t	Field_hid,
		int	FieldIDisGroup
	)

Retrieve type information for a specific field.

F5_API hid_t F5Lread_linear	(	hid_t	F_id,
		hsize_t *	dims,
		hid_t	fieldtype,
		void *	base,
		void *	delta
	)

Try to read a field as if it were a linear mapping of indices to some values.

Parameters:

dims

The extensions of an HDF5 dataspace.

Returns:: An HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.

Todo:: Add error checkings if the used attributes do not exist.

F5_API hid_t F5LSwrite_fraction	(	hid_t	R_id,
		const char *	fieldname,
		int	dimension,
		const hsize_t *	full_dims,
		const hsize_t *	datasize,
		hid_t	fieldtype,
		hid_t	memtype,
		const void const	dataPtr,
		const hsize_t *	datastart,
		const hsize_t *	start_border,
		const hsize_t *	end_border,
		const char *	fraction_name,
		hid_t	enum_type,
		hid_t	property_id
	)

Write a dataset of separate components that only cover a fraction of the entire representation's domain.

Parameters:

	dimension	The dimension of the data set.
	datastart	The (multidimensional) start index of the saved data set.
	dataend	The (multidimensional) end index of the saved data set.
	fraction_name	An optional string to name this fraction. It may be NULL to use an internal default.

Note:: Subsampling can not be specified here. Subsampled data need to go into another Topology group.

Returns:: A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.

F5_API F5Path* F5LTcreate	(	hid_t	File_id,
		const double *	time,
		const char *	gridname,
		ChartDomain_IDs *	ChartDomain,
		new_global_chart_f	coord_creator,
		const char *	coordinate_system,
		const char *	TopologyName,
		int	IndexDepth,
		int	SkeletonDimensionality,
		int	DataspaceDimensionality,
		const hsize_t *	refinement
	)

Low-level creation function for F5Path objects.

Parameters:

	time	Pointer to the time instance of the current parameter space slices, or NULL if the data reside in a zero-dimensional parameter space, i.e. they are static. In a future extension, this may be a point to a multidimensional structure specifying the location in multidimensional parameter space.
	SkeletonDimensionality	The dimensionality of the k-cells that is described by this Skeleton of a Grid.
	DataspaceDimensionality	The dimensionality of the data that is used for the data on this Skeleton. This is best to be identical to the SkeletonDimensionality, but may differ, for instance one can store data in one-dimensional arrays over a 2D grid, or have some kind of irregular point distribution.

F5Path* F5LTcreate	(	hid_t	File_id,
		const double *	time,
		const char *	gridname,
		ChartDomain_IDs *	ChartDomain,
		ChartDomain_IDs *	coord_creator(),
		const char *	coordinate_system,
		const char *	TopologyName,
		int	IndexDepth,
		int	SkeletonDimensionality,
		int	Dimensionality,
		const hsize_t *	refinement
	)

Create a Topology of the given name with a representation in the certain coordinate system. If the ChartDomain has not been set yet, then the types in the newly created chart domain (F5Path->myChart) will contain valid types for the Points and tangential types, as they are created by the specified coord_creator(). Note that the coord_create() specifies the type of the coordinate system, while the coordinate_system parameter specifies the actual object that is of this respective type.

F5Path* F5LTcreateV	(	hid_t	File_id,
		const double *	time,
		const char *	gridname,
		ChartDomain_IDs *	ChartDomain,
		ChartDomain_IDs *	coord_creatorvoid *udata,
		void *	udata,
		const char *	coordinate_system,
		const char *	TopologyName,
		int	IndexDepth,
		int	SkeletonDimensionality,
		int	Dimensionality,
		const hsize_t *	refinement
	)

The central F5Path constructor for write access: Creates the basic F5 structures in the file and sets up an F5Path object for subsequent use. Basically, all the information contained in an F5Path object can be created from the given parameters, however, some complexity arises when modifying some file that already has some structure. In such a case, it must re-use any found structures in a consistent way, especcially it has to use named types instead of intrinsic ones.

Todo:: Extend slice group creation to parameter spaces

Parameters:

ChartDomain

If a chartdomain is given, i.e. it is used already or stems from another file opening, then we reuse this chart domain, otherwise a new one will be created. The ChartDomain describes all types of the fields in the respective representation group as they are transient in memory. It will become the F5Path's `myChart' member. Specifying the ChartDomain is optional: if it is not given, then the coord_creator() callback function will be used to create a new coordinate object.

Note that F5LTcreateV() is more general in this respect than F5LTcreate() and F5LTcreateT(): Via the callback function, it allows to create an arbitrary subset of types for the chart domain, whereas F5LTcreate() always assumes that the representation domain is a coordinate system and creates the point, vector, covector and subsequent types for the tangential space. F5LTcreateT(), in contrast, does not create any tangential types (they are set to -1 in the ChartDomain), but only the point type, thus is more suitable for topological representations (cells referring to points, points to refined points, ...).

F5_API int F5LTget_index_depth ( hid_t Top_hid )

Get the index depth of a certain Topology ID.

F5_API int F5LTget_maximal_grid_refinement	(	hid_t	ContentsGroup_id,
		const char *	gridname,
		hsize_t *	refinement
	)

Get the maximal refinement level for a certain Grid.

    hsize_t     MaxRefinement[ FIBER_MAX_RANK ];
    int         Dims;

        Dims = F5LTget_maximal_grid_refinement(fpath->ContentsGroup_hid, "MyGridOfInterest", MaxRefinement);

F5_API int F5LTset_maximal_grid_refinement	(	hid_t	ContentsGroup_id,
		const char *	gridname,
		int	Dimensionality,
		const hsize_t *	refinement
	)

Update the maximal refinement level for a certain Grid.

F5_API hid_t F5Lwrite	(	hid_t	R_id,
		const char *	fieldname,
		int	dimension,
		const hsize_t *	dims,
		hid_t	fieldtype,
		hid_t	memtype,
		const void *	dataPtr,
		hid_t	enum_type,
		hid_t	property_id
	)

Returns:: A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.

Parameters:

property_id

An HDF5 dataset property ID. If it is negative, then a default property will be created locally via

H5Pcreate(H5P_DATASET_CREATE)

.

dimension

The dimensionality of the data set. You may use F5Lwrite1D() as a convenience shortcut for one-dimensional data sets.

dims

The extension of the data set.

Note:: Fields are always associated to certain coordinates system. The field type must be consistent with its coordinate system, e.g. one may not store a vector field in polar coordinates in a cartesian chart. Formally, this can be done because not all API functions have the ability to check for this consistency. However, a field type which is not part of a certain coordinate system will be treated as non-existent when reading the file later.; If a field is a structure made by separate data arrays, e.g. a vector field with components x,y,z stored as three arrays of floats, then use function F5Lwrites().

Parameters:

enum_type

The Atomic Field enumeration type that is associated with the current file. Get it via F5LTmake_enum_type(fpath).

Returns:: An HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.

F5_API hid_t F5Lwrite1D	(	hid_t	R_id,
		const char *	fieldname,
		hsize_t	nElements,
		hid_t	fieldtype,
		hid_t	memtype,
		const void *	dataPtr,
		hid_t	enum_type,
		hid_t	property_id
	)

Convenience function for writing one-dimensional data. Calls F5Lwrite();

F5_API hid_t F5Lwrite_entity	(	hid_t	R_id,
		const char *	fieldname,
		hid_t	fieldtype,
		const void *	value
	)

Write a field that is a constant for all elements.

Returns:: A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.

F5_API hid_t F5Lwrite_fraction	(	hid_t	R_id,
		const char *	fieldname,
		int	dimension,
		const hsize_t *	full_dims,
		const hsize_t *	datasize,
		hid_t	fieldtype,
		hid_t	memtype,
		const void *	dataPtr,
		const hsize_t *	datastart,
		const hsize_t *	start_border,
		const hsize_t *	end_border,
		const char *	fraction_name,
		hid_t	enum_type,
		hid_t	property_id
	)

Write a dataset which only covers a fraction of the entire representation's domain.

Parameters:

	dimension	The dimension of the data set.
	datastart	The (multidimensional) start index of the saved data set.
	dataend	The (multidimensional) end index of the saved data set.
	fraction_name	An optional string to name this fraction. It may be NULL to use an internal default.

Note:: Subsampling can not be specified here. Subsampled data need to go into another Topology group.

Returns:: A HDF5 dataset ID. The caller must issue H5Dclose() on the returned identifier.

F5_API hid_t F5Lwrite_linear	(	hid_t	R_id,
		const char *	fieldname,
		int	dimension,
		const hsize_t *	dims,
		hid_t	fieldtype,
		const void *	base,
		const void *	delta
	)

Write a field that is a linear map from coordinate indices to some data value.

Todo:: Remove dimension parameter, it is clear from the fieldtype's members.

Parameters:

dims

The extensions of an HDF5 dataspace.

Returns:: A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.

Write a field that is a linear map from coordinate indices to some data value.

Returns:: A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.

F5_API hid_t F5Lwrite_permutation	(	hid_t	R_id,
		const char *	fieldname,
		hsize_t	size,
		hsize_t *	permutation_indices,
		hsize_t	nvalues,
		hid_t	fieldtype,
		const void *	dataPtr
	)

Write a field which is accessed via some index permutation. In addition to the raw data values, also some index array needs to be specified.

Parameters:

	R_id	An hdf5 identifier of the representation group in charge.
	size	The number of elements in the representation group.
	permutation_indices	A mapping from element indices to value indices.
	nvalues	How many data values are actually here.
	fieldtype	Hdf5 identifier of the data type.
	dataPtr	The data

Returns:: A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.

Todo:

implement

add structure function

add possibility to share permutation index datasets

F5_API hid_t F5Lwrites	(	hid_t	R_id,
		const char *	fieldname,
		int	dimension,
		const hsize_t *	dims,
		hid_t	fieldtype,
		hid_t	memtype,
		const void const	dataPtr,
		hid_t	enum_type,
		hid_t	property_id
	)

Parameters:

enum_type

The Atomic Field enumeration type that is associated with the current file. Get it via F5LTmake_enum_type(fpath).

Returns:: A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.; A HDF5 group ID. The caller must issue H5Gclose() on the returned identifier.

Note:: If some component array is undefined (NULL), then its place will be left empty in the file.

Low-Level Field Operations

Functions

Detailed Description

Function Documentation