We define routines for a forest of elements that are not part of the official t8_forest.h interface but used internally. More...

#include <t8.h>
#include <t8_forest.h>

Functions
void	t8_forest_compute_desc (t8_forest_t forest)

void	t8_forest_populate (t8_forest_t forest)

t8_eclass_scheme_c *	t8_forest_get_eclass_scheme_before_commit (t8_forest_t forest, t8_eclass_t eclass)
	Return the eclass scheme of a given element class associated to a forest. More...

void	t8_forest_compute_maxlevel (t8_forest_t forest)
	Compute the maximum possible refinement level in a forest. More...

int	t8_forest_min_nonempty_level (t8_cmesh_t cmesh, t8_scheme_cxx_t *scheme)
	Compute the minimum possible uniform refinement level on a cmesh such that no process is empty. More...

int	t8_forest_first_tree_shared (t8_forest_t forest)
	return nonzero if the first tree of a forest is shared with a smaller process. More...

int	t8_forest_last_tree_shared (t8_forest_t forest)
	return nonzero if the last tree of a forest is shared with a bigger process. More...

void	t8_forest_copy_trees (t8_forest_t forest, t8_forest_t from, int copy_elements)

t8_ctree_t	t8_forest_get_coarse_tree_ext (t8_forest_t forest, t8_locidx_t ltreeid, t8_locidx_t face_neigh, int8_t ttf)
	Given the local id of a tree in a forest, return the coarse tree of the cmesh that corresponds to this tree, also return the neighbor information of the tree. More...

void	t8_forest_compute_elements_offset (t8_forest_t forest)
	Given a forest whose trees are already filled with elements compute the element offset of each local tree. More...

t8_element_t *	t8_forest_get_tree_element (t8_tree_t tree, t8_locidx_t elem_in_tree)
	Return an element of a tree. More...

t8_element_array_t *	t8_forest_get_tree_element_array (t8_forest_t forest, t8_locidx_t ltreeid)
	Return the array of elements of a tree. More...

int	t8_forest_element_find_owner_old (t8_forest_t forest, t8_gloidx_t gtreeid, t8_element_t element, t8_eclass_t eclass, sc_array_t all_owners_of_tree)
	Find the owner process of a given element, deprecated version. More...

int	t8_forest_element_find_owner (t8_forest_t forest, t8_gloidx_t gtreeid, t8_element_t *element, t8_eclass_t eclass)
	Find the owner process of a given element. More...

int	t8_forest_element_find_owner_ext (t8_forest_t forest, t8_gloidx_t gtreeid, t8_element_t *element, t8_eclass_t eclass, int lower_bound, int upper_bound, int guess, int element_is_desc)
	Find the owner process of a given element, if bounds for the owner process are known. More...

int	t8_forest_element_check_owner (t8_forest_t forest, t8_element_t *element, t8_gloidx_t gtreeid, t8_eclass_t eclass, int rank, int element_is_desc)
	Perform a constant runtime check if a given rank is owner of a given element. More...

void	t8_forest_element_owners_at_face (t8_forest_t forest, t8_gloidx_t gtreeid, const t8_element_t element, t8_eclass_t eclass, int face, sc_array_t owners)
	Find all owner processes that own descendant of a given element that touch a given face. More...

void	t8_forest_element_owners_bounds (t8_forest_t forest, t8_gloidx_t gtreeid, const t8_element_t element, t8_eclass_t eclass, int lower, int *upper)
	Constant time algorithm to compute lower and upper bounds for the owner processes of a given element. More...

void	t8_forest_element_owners_at_face_bounds (t8_forest_t forest, t8_gloidx_t gtreeid, const t8_element_t element, t8_eclass_t eclass, int face, int lower, int *upper)
	Constant time algorithm to compute lower and upper bounds for the owner processes of the face leafs of a given element. More...

void	t8_forest_element_owners_at_neigh_face (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t element, int face, sc_array_t owners)
	Find all owner processes that own descendant of a face neighbor of a given local element that touch the given face. More...

void	t8_forest_element_owners_at_neigh_face_bounds (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t element, int face, int lower, int *upper)
	Constant time algorithm to find bounds for the owner processes that own descendant of a face neighbor of a given local element that touch the given face. More...

t8_gloidx_t	t8_forest_element_half_face_neighbors (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t elem, t8_element_t neighs[], t8_eclass_scheme_c *neigh_scheme, int face, int num_neighs, int dual_faces[])
	Construct all face neighbors of half size of a given element. More...

void	t8_forest_print_all_leaf_neighbors (t8_forest_t forest)
	Iterate over all leafs of a forest and for each face compute the face neighbor leafs with t8_forest_leaf_face_neighbors and print their local element ids. More...

int	t8_forest_element_has_leaf_desc (t8_forest_t forest, t8_gloidx_t gtreeid, const t8_element_t element, t8_eclass_scheme_c ts)
	Compute whether for a given element there exist leaf or ghost leaf elements in the local forest that are a descendant of the element but not the element itself. More...

Detailed Description

We define routines for a forest of elements that are not part of the official t8_forest.h interface but used internally.

Function Documentation

◆ t8_forest_compute_elements_offset()

void t8_forest_compute_elements_offset ( t8_forest_t forest )

Given a forest whose trees are already filled with elements compute the element offset of each local tree.

The element offset of a tree is the number of local elements of the forest that live in all the trees with a smaller treeid.

Parameters

[in,out] forest The forest. forest does not need to be committed before calling this function, but all elements must have been constructed.

◆ t8_forest_compute_maxlevel()

void t8_forest_compute_maxlevel ( t8_forest_t forest )

Compute the maximum possible refinement level in a forest.

This is the minimum over all maimum refinement level of the present element classes.

Parameters

[in,out] forest The forest.

◆ t8_forest_element_check_owner()

int t8_forest_element_check_owner	(	t8_forest_t	forest,
		t8_element_t *	element,
		t8_gloidx_t	gtreeid,
		t8_eclass_t	eclass,
		int	rank,
		int	element_is_desc
	)

Perform a constant runtime check if a given rank is owner of a given element.

If the element is owned by more than one rank, then this check is only true for the smallest.

Parameters

[in]	forest	A forest.
[in]	element	An element of forest.
[in]	gtreeid	The global tree in which element is in.
[in]	eclass	The element class of the tree.
[in]	rank	An mpi rank.
[in]	element_is_desc	This should be true, if element is its own first_descendant at the maximum level. Must be false otherwise.

Returns: True if and only if rank is the (first) owner process of element.

◆ t8_forest_element_find_owner()

int t8_forest_element_find_owner	(	t8_forest_t	forest,
		t8_gloidx_t	gtreeid,
		t8_element_t *	element,
		t8_eclass_t	eclass
	)

Find the owner process of a given element.

Parameters

[in]	forest	The forest.
[in]	gtreeid	The global id of the tree in which the element lies.
[in]	element	The element to look for.
[in]	eclass	The element class of the tree gtreeid.

Returns: The mpirank of the process that owns element.

Note: The element must not exist in the forest, but an ancestor of its first descendant has to. If the element's owner is not unique, the owner of the element's first descendant is returned.; forest must be committed before calling this function.

See also: t8_forest_element_find_owner_ext; t8_forest_element_owners_bounds

◆ t8_forest_element_find_owner_ext()

int t8_forest_element_find_owner_ext	(	t8_forest_t	forest,
		t8_gloidx_t	gtreeid,
		t8_element_t *	element,
		t8_eclass_t	eclass,
		int	lower_bound,
		int	upper_bound,
		int	guess,
		int	element_is_desc
	)

Find the owner process of a given element, if bounds for the owner process are known.

Parameters

[in]	forest	The forest.
[in]	gtreeid	The global id of the tree in which the element lies.
[in]	element	The element to look for.
[in]	eclass	The element class of the tree gtreeid.
[in]	lower_bound	A known lower bound for the owner process.
[in]	upper_bound	A known upper bound for the owner process.
[in]	guess	An initial guess for the owner. Must satisfy lower_bound <= guess <= upper_bound

Returns: The mpirank of the process that owns element.

Note: If lower_bound = upper_bound, the function assumes that lower_bound is the owner process and immediately returns.; The owner p must satisfy lower_bound <= p <= upper_bound.; The element must not exist in the forest, but an ancestor of its first descendant has to. If the element's owner is not unique, the owner of the element's first descendant is returned.; forest must be committed before calling this function.

See also: t8_forest_element_find_owner; t8_forest_element_owners_bounds

◆ t8_forest_element_find_owner_old()

int t8_forest_element_find_owner_old	(	t8_forest_t	forest,
		t8_gloidx_t	gtreeid,
		t8_element_t *	element,
		t8_eclass_t	eclass,
		sc_array_t *	all_owners_of_tree
	)

Find the owner process of a given element, deprecated version.

Use t8_forest_element_find_owner instead.

Parameters

[in]	forest	The forest.
[in]	gtreeid	The global id of the tree in which the element lies.
[in]	element	The element to look for.
[in]	eclass	The element class of the tree gtreeid.
[in,out]	all_owners_of_tree	If not NULL, a sc_array of integers. If the element count is zero then on output all owners of the tree are stored. If the element count is non-zero then it is assumed to be filled with all owners of the tree.

Returns: The mpirank of the process that owns element.

Note: The element must exist in the forest.; forest must be committed before calling this function.

◆ t8_forest_element_half_face_neighbors()

t8_gloidx_t t8_forest_element_half_face_neighbors	(	t8_forest_t	forest,
		t8_locidx_t	ltreeid,
		const t8_element_t *	elem,
		t8_element_t *	neighs[],
		t8_eclass_scheme_c *	neigh_scheme,
		int	face,
		int	num_neighs,
		int	dual_faces[]
	)

Construct all face neighbors of half size of a given element.

Parameters

[in]	forest	The forest.
[in]	ltreeid	The local tree id of the tree in which the element is.
[in]	elem	The element of which to construct the neighbors.
[in,out]	neighs	An array of allocated elements of the correct element class. On output the face neighbors of elem across face of one bigger refinement level are stored.
[in]	neigh_scheme	The eclass scheme of the neighbors.
[in]	face	The number of the face of elem.
[in]	num_neighs	The number of allocated element in neighs. Must match the number of face neighbors of one bigger refinement level.
[out]	dual_face	If not NULL, on output the face id's of the neighboring elements' faces.

Returns: The global id of the tree in which the neighbors are. -1 if there exists no neighbor across that face.

◆ t8_forest_element_has_leaf_desc()

int t8_forest_element_has_leaf_desc	(	t8_forest_t	forest,
		t8_gloidx_t	gtreeid,
		const t8_element_t *	element,
		t8_eclass_scheme_c *	ts
	)

Compute whether for a given element there exist leaf or ghost leaf elements in the local forest that are a descendant of the element but not the element itself.

Parameters

[in]	forest	The forest.
[in]	gtreeid	The global id of the tree the element is in
[in]	element	The element
[in]	ts	The eclass scheme of element.

Returns: True if in the forest there exists a local leaf or ghost leaf that is a descendant of element but not equal to element.

Note: If no ghost layer was created for the forest, only local elements are tested.; forest must be committed before calling this function.

◆ t8_forest_element_owners_at_face()

void t8_forest_element_owners_at_face	(	t8_forest_t	forest,
		t8_gloidx_t	gtreeid,
		const t8_element_t *	element,
		t8_eclass_t	eclass,
		int	face,
		sc_array_t *	owners
	)

Find all owner processes that own descendant of a given element that touch a given face.

The element does not need to be a local element.

Parameters

[in]	forest	The forest.
[in]	gtreeid	The global id of the tree in which the element lies.
[in]	element	The element to look for.
[in]	eclass	The element class of the tree gtreeid.
[in]	face	A face of element.
[in,out]	owners	On input an array of integers. Its first and second entry are taken as lower and upper bounds for the owner processes. If empty, then no bounds are taken. On output it stores all owners of descendants of elem that touch face in ascending order.

◆ t8_forest_element_owners_at_face_bounds()

void t8_forest_element_owners_at_face_bounds	(	t8_forest_t	forest,
		t8_gloidx_t	gtreeid,
		const t8_element_t *	element,
		t8_eclass_t	eclass,
		int	face,
		int *	lower,
		int *	upper
	)

Constant time algorithm to compute lower and upper bounds for the owner processes of the face leafs of a given element.

Parameters

[in]	forest	The forest.
[in]	gtreeid	The global id of the tree in which the element lies.
[in]	element	The element to look for.
[in]	eclass	The element class of the tree gtreeid.
[in]	face	The face of element to consider.
[in,out]	lower	On input a known lower bound for the owner process, on output a (better) bound.
[in,out]	upper	On input a known upper bound for the owner process, on output a (better) bound.

Note: If on input lower >= upper, then the bounds are not changed by this algorithm. We interpret lower = such that the owner is unique and equals lower.; forest must be committed before calling this function.

◆ t8_forest_element_owners_at_neigh_face()

void t8_forest_element_owners_at_neigh_face	(	t8_forest_t	forest,
		t8_locidx_t	ltreeid,
		const t8_element_t *	element,
		int	face,
		sc_array_t *	owners
	)

Find all owner processes that own descendant of a face neighbor of a given local element that touch the given face.

Parameters

[in]	forest	The forest.
[in]	ltreeid	The local id of the tree in which the element lies.
[in]	element	The element, whose neighbor's face owners should be computed.
[in]	face	A face of element.
[in,out]	owners	On input an array of integers. Its first and second entry are taken as lower and upper bounds for the owner processes. If empty, then no bounds are taken. On output it stores all owners of descendants of the neighbor of elem across face that touch this face. If the neighbor element does not exist, owners will be empty. This is equivalent to calling t8_forest_element_face_neighbor and t8_forest_element_owners_at_face for the resulting neighbor.

Note: forest must be committed before calling this function.

◆ t8_forest_element_owners_at_neigh_face_bounds()

void t8_forest_element_owners_at_neigh_face_bounds	(	t8_forest_t	forest,
		t8_locidx_t	ltreeid,
		const t8_element_t *	element,
		int	face,
		int *	lower,
		int *	upper
	)

Constant time algorithm to find bounds for the owner processes that own descendant of a face neighbor of a given local element that touch the given face.

Parameters

[in]	forest	The forest.
[in]	ltreeid	The local id of the tree in which the element lies.
[in]	element	The element, whose neighbor's face owners should be computed.
[in]	face	A face of element.
[in,out]	lower	On input a known lower bound for the owner process, on output a (better) bound.
[in,out]	upper	On input a known upper bound for the owner process, on output a (better) bound.

Note: If on input lower >= upper, then the bounds are not changed by this algorithm. We interpret lower = such that the owner is unique and equals lower.; forest must be committed before calling this function. This is equivalent to calling t8_forest_element_face_neighbor and t8_forest_element_owners_at_face_bounds for the resulting neighbor.

◆ t8_forest_element_owners_bounds()

void t8_forest_element_owners_bounds	(	t8_forest_t	forest,
		t8_gloidx_t	gtreeid,
		const t8_element_t *	element,
		t8_eclass_t	eclass,
		int *	lower,
		int *	upper
	)

Constant time algorithm to compute lower and upper bounds for the owner processes of a given element.

Parameters

[in]	forest	The forest.
[in]	gtreeid	The global id of the tree in which the element lies.
[in]	element	The element to look for.
[in]	eclass	The element class of the tree gtreeid.
[in,out]	lower	On input a known lower bound for the owner process, on output a (better) bound.
[in,out]	upper	On input a known upper bound for the owner process, on output a (better) bound.

Note: If on input lower >= upper, then the bounds are not changed by this algorithm. We interpret lower = such that the owner is unique and equals lower.; forest must be committed before calling this function.

See also: t8_forest_element_find_owner; t8_forest_element_owners_bounds

◆ t8_forest_first_tree_shared()

int t8_forest_first_tree_shared ( t8_forest_t forest )

return nonzero if the first tree of a forest is shared with a smaller process.

This is the case if and only if the first descendant of the first tree that we store is not the first possible descendant of that tree.

Parameters

[in] forest The forest.

Returns: True if the first tree in the forest is shared with a smaller rank. False otherwise.

Note: forest must be committed before calling this function.

◆ t8_forest_get_coarse_tree_ext()

t8_ctree_t t8_forest_get_coarse_tree_ext	(	t8_forest_t	forest,
		t8_locidx_t	ltreeid,
		t8_locidx_t **	face_neigh,
		int8_t **	ttf
	)

Given the local id of a tree in a forest, return the coarse tree of the cmesh that corresponds to this tree, also return the neighbor information of the tree.

Parameters

[in]	forest	The forest.
[in]	ltreeid	The local id of a tree in the forest.
[out]	face_neigh	If not NULL a pointer to the trees face_neighbor array is stored here on return.
[out]	ttf	If not NULL a pointer to the trees tree_to_face array is stored here on return.

Returns: The coarse tree that matches the forest tree with local id ltreeid.

See also: t8_cmesh_trees_get_tree_ext

◆ t8_forest_get_eclass_scheme_before_commit()

t8_eclass_scheme_c* t8_forest_get_eclass_scheme_before_commit	(	t8_forest_t	forest,
		t8_eclass_t	eclass
	)

Return the eclass scheme of a given element class associated to a forest.

This function does not check whether the given forest is committed, use with caution and only if you are sure that the eclass_scheme was set.

Parameters

[in]	forest.	A nearly committed forest.
[in]	eclass.	An element class.

Returns: The eclass scheme of eclass associated to forest.

See also: t8_forest_set_scheme

Note: The forest is not required to have trees of class eclass.

◆ t8_forest_get_tree_element()

t8_element_t* t8_forest_get_tree_element	(	t8_tree_t	tree,
		t8_locidx_t	elem_in_tree
	)

Return an element of a tree.

Parameters

[in]	tree	The tree.
[in]	elem_in_tree	The index of the element within the tree.

Returns: Returns the elemen with index elem_in_tree of the element array of tree.

◆ t8_forest_get_tree_element_array()

t8_element_array_t* t8_forest_get_tree_element_array	(	t8_forest_t	forest,
		t8_locidx_t	ltreeid
	)

Return the array of elements of a tree.

Parameters

[in]	forest	The forest.
[in]	ltreeid	The local id of a local tree. Must be a valid local tree id.

Returns: Returns the array of elements of the tree. forest must be committed before calling this function.

◆ t8_forest_last_tree_shared()

int t8_forest_last_tree_shared ( t8_forest_t forest )

return nonzero if the last tree of a forest is shared with a bigger process.

This is the case if and only if the first descendant of the first tree that we store is not the first possible descendant of that tree.

Parameters

[in] forest The forest.

Returns: True if the last tree in the forest is shared with a bigger rank. False otherwise.

Note: forest must be committed before calling this function.

◆ t8_forest_min_nonempty_level()

int t8_forest_min_nonempty_level	(	t8_cmesh_t	cmesh,
		t8_scheme_cxx_t *	scheme
	)

Compute the minimum possible uniform refinement level on a cmesh such that no process is empty.

Parameters

[in]	cmesh	The cmesh.
[in]	scheme	The element scheme for which refinement is considered.

Returns: The smallest refinement level l, such that a uniform level l refined forest would have no empty processes.

See also: t8_forest_new_uniform.

◆ t8_forest_print_all_leaf_neighbors()

void t8_forest_print_all_leaf_neighbors ( t8_forest_t forest )

Iterate over all leafs of a forest and for each face compute the face neighbor leafs with t8_forest_leaf_face_neighbors and print their local element ids.

This function is meant for debugging only.

Parameters

[in] forest The forest.

Note: Currently forest must be balanced.; forest must be committed before calling this function.

Functions

Detailed Description

Function Documentation

◆ t8_forest_compute_elements_offset()

◆ t8_forest_compute_maxlevel()

◆ t8_forest_element_check_owner()

◆ t8_forest_element_find_owner()

◆ t8_forest_element_find_owner_ext()

◆ t8_forest_element_find_owner_old()

◆ t8_forest_element_half_face_neighbors()

◆ t8_forest_element_has_leaf_desc()

◆ t8_forest_element_owners_at_face()

◆ t8_forest_element_owners_at_face_bounds()

◆ t8_forest_element_owners_at_neigh_face()

◆ t8_forest_element_owners_at_neigh_face_bounds()

◆ t8_forest_element_owners_bounds()

◆ t8_forest_first_tree_shared()

◆ t8_forest_get_coarse_tree_ext()

◆ t8_forest_get_eclass_scheme_before_commit()

◆ t8_forest_get_tree_element()

◆ t8_forest_get_tree_element_array()

◆ t8_forest_last_tree_shared()

◆ t8_forest_min_nonempty_level()

◆ t8_forest_print_all_leaf_neighbors()