Creating F5Path objects and field representations.

Functions
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])
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])
int	F5Rlink_default_vertex_topology (F5Path *grid, const hsize_t target_refinement[3])
F5_API F5Path *	F5Rcreate_cartesian (hid_t File_id, double time, const char *gridname, const char *coordinate_system)
F5_API F5Path *	F5Rcreate_static_cartesian (hid_t File_id, const char *gridname, const char *coordinate_system)
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)
F5_API F5Path *	F5Rcreate_triangles_as_vertices_topology (hid_t File_id, double time, const char *gridname)
F5_API F5Path *	F5Rcreate_edges_as_vertices_topology (hid_t File_id, double time, const char *gridname)
F5_API F5Path *	F5Rcreate_faces_as_vertices_topology (hid_t File_id, double time, const char *gridname)
F5_API F5Path *	F5Rcreate_tetrahedrons_as_vertices_topology (hid_t File_id, double time, const char *gridname)
F5_API F5Path *	F5Rcreate_hexaedrons_as_vertices_topology (hid_t File_id, double time, const char *gridname)
F5_API F5Path *	F5Rcreate_vertex_refinement3D (hid_t File_id, double time, const char *gridname, const hsize_t refinement[3], const char *coordinate_system)
F5_API void	F5Rcreate_downsampling (F5Path *Topology, const hsize_t *downsampling)
F5_API void	F5Rcreate_subsampling (F5Path *Topology, const hsize_t *subsampling)
F5_API int	F5Rset_timestep (F5Path *path, long timestep)
F5_API long *	F5Rget_timestep (F5Path *path, long *timestep)

---

Detailed Description

These functions create F5Path objects for subsequent usage by F5F field functions. They are created directly from HDF5 id's and native types.

---

Function Documentation

F5_API F5Path* F5Rcreate_cartesian	(	hid_t	File_id,
		double	time,
		const char *	gridname,
		const char *	coordinate_system
	)

Create a Field object for a given representation of a grid's vertices in a certain coordinate system.

Returns:

A new F5Path pointer. Call F5close() if it is no longer used.

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
	)

Create a representation for a specific topological space on the grid in a certain coordinate system. Mostly of internal use.

F5_API void F5Rcreate_downsampling	(	F5Path *	Topology,
		const hsize_t *	downsampling
	)

Create a topology suitable for downsampled data, i.e. where the 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 F5Path* F5Rcreate_edges_as_vertices_topology	(	hid_t	File_id,
		double	time,
		const char *	gridname
	)

Create the default topology of the edges of a grid, as specified by vertices.

Returns:

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_faces_as_vertices_topology	(	hid_t	File_id,
		double	time,
		const char *	gridname
	)

Create the default topology of the facet of a grid, as specified by vertices.

Returns:

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_hexaedrons_as_vertices_topology	(	hid_t	File_id,
		double	time,
		const char *	gridname
	)

Create the default topology of the cells of a grid as hexahedrons, as specified by vertices. It will be a 3-dimensional grid.

Returns:

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_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]
	)

Define refinement by integer numbers. Here, the vertices of the refined objects have to match up exactly with the vertices of the coarse levels. It is only possible to refine entire cells on the coarse grid.

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_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]
	)

Define refinement by rational numbers. Here, the vertices of the refined objects may cover fractions of the coarser cells. Still, vertices have to line up exactly and no refined cell may be split by the boundary of a coarser cell.

Create a refinement topology whose refined cells may partially cover coarse cells. The refinement coordinates are given as rational numbers.

F5_API F5Path* F5Rcreate_static_cartesian	(	hid_t	File_id,
		const char *	gridname,
		const char *	coordinate_system
	)

Construct a Field object for a representation of a grid's vertices in a certain coordinate system.

Parameters:

	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() ).
	coord_creator	A procedure to create a new class of coordinate systems.
	coordinate_system	A name for an instance of the coordinate system, i.e. for the current chart object to use.
	TopologyName	On which topological space of the grid to create the coordinate representation (e.g. vertices, cells, edges, refinement level ...)
	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.

Returns:

A new F5Path pointer. Call F5close() if it is no longer used. Construct a Field object for a representation of a grid's vertices in a certain coordinate system that is independent from any time information.

Parameters:

	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() ).
	coord_creator	A procedure to create a new class of coordinate systems.
	coordinate_system	A name for an instance of the coordinate system, i.e. for the current chart object to use.
	TopologyName	On which topological space of the grid to create the coordinate representation (e.g. vertices, cells, edges, refinement level ...)

Returns:

A new F5Path pointer. Call F5close() if it is no longer used.

F5_API void F5Rcreate_subsampling	(	F5Path *	Topology,
		const hsize_t *	subsampling
	)

Create a topology suitable for subsampled data, i.e. where a 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 F5Path* F5Rcreate_tetrahedrons_as_vertices_topology	(	hid_t	File_id,
		double	time,
		const char *	gridname
	)

Create the default topology of the cells of a grid as tetrahedra, as specified by vertices. It will be a 3-dimensional grid.

Returns:

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_triangles_as_vertices_topology	(	hid_t	File_id,
		double	time,
		const char *	gridname
	)

Create the default topology of the cells of a grid as triangles, as specified by vertices. It will result in a two-dimensional grid.

Returns:

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_vertex_refinement3D	(	hid_t	File_id,
		double	time,
		const char *	gridname,
		const hsize_t	refinement[3],
		const char *	coordinate_system
	)

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 also:

F5Lwrite_fraction(), Adaptive Hierarchical Meshes

Parameters:

refinement

The refinement factor as compared to the finest resolution. 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.

Returns:

A new F5Path pointer. Call F5close() if it is no longer used.

F5_API long* F5Rget_timestep	(	F5Path *	path,
		long *	timestep
	)

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.

Returns:

NULL, if no timestep information was found, or the F5Path does not refer to a Grid object.

F5_API int F5Rlink_default_vertex_topology	(	F5Path *	grid,
		const hsize_t	target_refinement[3]
	)

Treat some refinement level as the default level for refinement-unaware readers.

Creates a symbolic link from some refinement level on vertices to appear as the default points topology.

Parameters:

	grid	A valid F5Path object pointing to some grid.
	target_refinement	The refinement level that shall be visible as default.

Note:

Currently only 3D refinements are supported.

If a point topology already exists, it will not be touched.

Create a symbolic links from some vertex refinement topology group to the default group "Points".

Returns:

non-zero in case of errors, like invalid arguments.

Parameters:

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 F5Rset_timestep	(	F5Path *	path,
		long	timestep
	)

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.

Returns:

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.