TODO: document this file. More...

#include <sc_statistics.h>
#include <t8_cmesh.h>
#include <t8_cmesh_vtk_writer.h>
#include <t8_cmesh/t8_cmesh_geometry.h>
#include <t8_geometry/t8_geometry_implementations/t8_geometry_linear.h>
#include <t8_refcount.h>
#include <t8_data/t8_shmem.h>
#include <t8_vec.h>
#include <t8_eclass.h>
#include "t8_cmesh_trees.h"

Functions
int	t8_cmesh_is_initialized (t8_cmesh_t cmesh)
	Check whether a cmesh is not NULL, initialized and not committed. More...

int	t8_cmesh_is_committed (t8_cmesh_t cmesh)
	Check whether a cmesh is not NULL, initialized and committed. More...

int	t8_cmesh_comm_is_valid (t8_cmesh_t cmesh, sc_MPI_Comm comm)
	Check whether a given MPI communicator assigns the same rank and mpisize as stored in a cmesh. More...

void	t8_cmesh_init (t8_cmesh_t *pcmesh)
	Create a new cmesh with reference count one. More...

void	t8_cmesh_set_derive (t8_cmesh_t cmesh, t8_cmesh_t set_from)
	This function sets a cmesh to be derived from. More...

t8_shmem_array_t	t8_cmesh_alloc_offsets (int mpisize, sc_MPI_Comm comm)
	Allocate a shared memory array to store the tree offsets of a cmesh. More...

void	t8_cmesh_set_partition_range (t8_cmesh_t cmesh, int set_face_knowledge, t8_gloidx_t first_local_tree, t8_gloidx_t last_local_tree)
	Declare if the cmesh is understood as a partitioned cmesh and specify the processor local tree range. More...

void	t8_cmesh_set_partition_offsets (t8_cmesh_t cmesh, t8_shmem_array_t tree_offsets)
	Declare if the cmesh is understood as a partitioned cmesh and specify the first local tree for each process. More...

void	t8_cmesh_set_partition_uniform (t8_cmesh_t cmesh, int element_level, t8_scheme_cxx_t *ts)
	Declare if the cmesh is understood as a partitioned cmesh where the partition table is derived from an assumed uniform refinement of a given level. More...

void	t8_cmesh_set_refine (t8_cmesh_t cmesh, int level, t8_scheme_cxx_t *scheme)
	Refine the cmesh to a given level. More...

t8_gloidx_t	t8_cmesh_get_first_treeid (t8_cmesh_t cmesh)
	Return the global index of the first local tree of a cmesh. More...

int	t8_cmesh_treeid_is_local_tree (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid)
	Query whether a given t8_locidx_t belongs to a local tree of a cmesh. More...

int	t8_cmesh_treeid_is_ghost (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid)
	Query whether a given t8_locidx_t belongs to a ghost of a cmesh. More...

t8_locidx_t	t8_cmesh_ltreeid_to_ghostid (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid)
	Given a local tree id that belongs to a ghost, return the index of the ghost. More...

t8_ctree_t	t8_cmesh_get_tree (t8_cmesh_t cmesh, t8_locidx_t ltree_id)
	Return a pointer to a given local tree. More...

t8_ctree_t	t8_cmesh_get_first_tree (t8_cmesh_t cmesh)
	Return a pointer to the first local tree in a cmesh. More...

t8_ctree_t	t8_cmesh_get_next_tree (t8_cmesh_t cmesh, t8_ctree_t tree)
	Given a local tree in a cmesh return a pointer to the next local tree. More...

void	t8_cmesh_set_attribute (t8_cmesh_t cmesh, t8_gloidx_t gtree_id, int package_id, int key, void *data, size_t data_size, int data_persists)
	Store an attribute at a tree in a cmesh. More...

void	t8_cmesh_set_attribute_string (t8_cmesh_t cmesh, t8_gloidx_t gtree_id, int package_id, int key, const char *string)
	Store a string as an attribute at a tree in a cmesh. More...

double *	t8_cmesh_get_tree_vertices (t8_cmesh_t cmesh, t8_locidx_t ltreeid)
	Return a pointer to the vertex coordinates of a tree. More...

void *	t8_cmesh_get_attribute (t8_cmesh_t cmesh, int package_id, int key, t8_locidx_t ltree_id)
	Return the attribute pointer of a tree. More...

t8_shmem_array_t	t8_cmesh_get_partition_table (t8_cmesh_t cmesh)
	Return the shared memory array storing the partition table of a partitioned cmesh. More...

void	t8_cmesh_set_dimension (t8_cmesh_t cmesh, int dim)
	Set the dimension of a cmesh. More...

void	t8_cmesh_set_tree_class (t8_cmesh_t cmesh, t8_gloidx_t gtree_id, t8_eclass_t tree_class)
	Set the class of a tree in the cmesh. More...

int	t8_cmesh_tree_vertices_negative_volume (t8_eclass_t eclass, double *vertices, int num_vertices)
	Given a set of vertex coordinates for a tree of a given eclass. More...

void	t8_cmesh_set_tree_vertices (t8_cmesh_t cmesh, t8_locidx_t ltree_id, double *vertices, int num_vertices)
	Set the vertex coordinates of a tree in the cmesh. More...

void	t8_cmesh_set_join (t8_cmesh_t cmesh, t8_gloidx_t gtree1, t8_gloidx_t gtree2, int face1, int face2, int orientation)
	Insert a face-connection between two trees in a cmesh. More...

void	t8_cmesh_set_profiling (t8_cmesh_t cmesh, int set_profiling)
	Enable or disable profiling for a cmesh. More...

int	t8_cmesh_is_equal (t8_cmesh_t cmesh_a, t8_cmesh_t cmesh_b)
	Check whether two given cmeshes carry the same information. More...

int	t8_cmesh_is_empty (t8_cmesh_t cmesh)
	Check whether a cmesh is empty on all processes. More...

t8_cmesh_t	t8_cmesh_bcast (t8_cmesh_t cmesh_in, int root, sc_MPI_Comm comm)
	Broadcast a cmesh structure that exists only on one process to all processes in the cmesh's communicator. More...

int	t8_cmesh_is_partitioned (t8_cmesh_t cmesh)
	Query whether a committed cmesh is partitioned or replicated. More...

t8_gloidx_t	t8_cmesh_get_num_trees (t8_cmesh_t cmesh)
	Return the global number of trees in a cmesh. More...

t8_locidx_t	t8_cmesh_get_num_local_trees (t8_cmesh_t cmesh)
	Return the number of local trees of a cmesh. More...

t8_locidx_t	t8_cmesh_get_num_ghosts (t8_cmesh_t cmesh)
	Return the number of ghost trees of a cmesh. More...

int	t8_cmesh_tree_face_is_boundary (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid, const int face)
	Query whether a face of a local tree or ghost is at the domain boundary. More...

t8_eclass_t	t8_cmesh_get_tree_class (t8_cmesh_t cmesh, t8_locidx_t ltree_id)
	Return the eclass of a given local tree. More...

t8_eclass_t	t8_cmesh_get_ghost_class (t8_cmesh_t cmesh, t8_locidx_t lghost_id)
	Return the eclass of a given local ghost. More...

t8_gloidx_t	t8_cmesh_get_global_id (t8_cmesh_t cmesh, t8_locidx_t local_id)
	Return the global id of a given local tree or ghost. More...

t8_locidx_t	t8_cmesh_get_local_id (t8_cmesh_t cmesh, t8_gloidx_t global_id)
	Return the local id of a give global tree. More...

t8_locidx_t	t8_cmesh_get_face_neighbor (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid, const int face, int dual_face, int orientation)
	Given a local tree id and a face number, get information about the face neighbor tree. More...

void	t8_cmesh_print_profile (t8_cmesh_t cmesh)
	Print the collected statistics from a cmesh profile. More...

void	t8_cmesh_ref (t8_cmesh_t cmesh)
	Increase the reference counter of a cmesh. More...

void	t8_cmesh_unref (t8_cmesh_t *pcmesh)
	Decrease the reference counter of a cmesh. More...

void	t8_cmesh_destroy (t8_cmesh_t *pcmesh)
	Verify that a coarse mesh has only one reference left and destroy it. More...

void	t8_cmesh_translate_coordinates (const double coords_in, double coords_out, int num_vertices, double translate[3])
	Compute y = x + translate on an array of doubles, interpreting each 3 as one vector x. More...

void	t8_cmesh_new_translate_vertices_to_attributes (t8_locidx_t tvertices, double vertices, double *attr_vertices, int num_vertices)
	TODO: Add proper documentation.

void	t8_cmesh_coords_axb (const double coords_in, double coords_out, int num_vertices, double alpha, const double b[3])
	Compute y = ax + b on an array of doubles, interpreting each 3 as one vector x. More...

void	t8_cmesh_debug_print_trees (const t8_cmesh_t cmesh, sc_MPI_Comm comm)

Detailed Description

TODO: document this file.

Function Documentation

◆ t8_cmesh_alloc_offsets()

t8_shmem_array_t t8_cmesh_alloc_offsets	(	int	mpisize,
		sc_MPI_Comm	comm
	)

Allocate a shared memory array to store the tree offsets of a cmesh.

Parameters

[in]	mpisize	The number of processes.
[in]	comm	The MPI communicator to use. Its mpisize must match mpisize. The shared memory type must have been set. Best practice would be calling sc_shmem_set_type (comm, T8_SHMEM_BEST_TYPE).

Returns: A t8_shmem_array struct that stores mpisize + 1 t8_gloidx_t entries.

See also: t8_shmem.h

◆ t8_cmesh_bcast()

t8_cmesh_t t8_cmesh_bcast	(	t8_cmesh_t	cmesh_in,
		int	root,
		sc_MPI_Comm	comm
	)

Broadcast a cmesh structure that exists only on one process to all processes in the cmesh's communicator.

TODO: Input structure must be replicated, not parallelized. TODO: Recommend to call this just before commit. Earlier is thinkable too. On the other processors, it will be allocated. It is not allowed to call this function after t8_cmesh_commit.

Parameters

[in]	cmesh_in	For the root process the cmesh to be broadcast, for the other processes it must be NULL.
[in]	root	The rank of the process that provides the cmesh.
[in]	comm	The mpi communicator. Must match cmesh's communicator on the root process.

Returns: For the root process this is a pointer to cmesh_in. Else, a pointer to a newly allocated cmesh structure with the same values as conn_in on the root process.

Note: It is illegal to broadcast a cmesh with a registered geometry (t8_cmesh_register_geometry). All geometries must be registered after the broadcast (You can set tree attributes before bcast, though).

◆ t8_cmesh_comm_is_valid()

int t8_cmesh_comm_is_valid	(	t8_cmesh_t	cmesh,
		sc_MPI_Comm	comm
	)

Check whether a given MPI communicator assigns the same rank and mpisize as stored in a cmesh.

Parameters

[in]	cmesh	The cmesh to be considered.
[in]	comm	A MPI communicator.

Returns: True if mpirank and mpisize from comm are the same as the values stored in cmesh. False otherwise. cmesh must be committed before calling this function.

◆ t8_cmesh_coords_axb()

void t8_cmesh_coords_axb	(	const double *	coords_in,
		double *	coords_out,
		int	num_vertices,
		double	alpha,
		const double	b[3]
	)

Compute y = ax + b on an array of doubles, interpreting each 3 as one vector x.

Parameters

[in]	coords_in	The incoming coordinates of the vectors
[out]	coords_out	The computed coordinates of the vectors
[in]	num_vertices	The number of vertices/vectors
[in]	alpha	Scaling factor for the vectors
[in]	b	Translation of the vectors.

◆ t8_cmesh_debug_print_trees()

void t8_cmesh_debug_print_trees	(	const t8_cmesh_t	cmesh,
		sc_MPI_Comm	comm
	)

Warning: This function is only available in debug-modus and should only be used in debug-modus.

Prints the vertices of each tree of each process

Parameters

[in] cmesh Source-cmesh, which trees get printed.

◆ t8_cmesh_destroy()

void t8_cmesh_destroy ( t8_cmesh_t * pcmesh )

Verify that a coarse mesh has only one reference left and destroy it.

This function is preferred over t8_cmesh_unref when it is known that the last reference is to be deleted.

Parameters

[in,out]	pcmesh	This cmesh must have a reference count of one. It can be in any state (committed or not). Then it effectively calls t8_cmesh_unref.
[in]	comm	A mpi communicator that is valid with cmesh.

◆ t8_cmesh_get_attribute()

void* t8_cmesh_get_attribute	(	t8_cmesh_t	cmesh,
		int	package_id,
		int	key,
		t8_locidx_t	ltree_id
	)

Return the attribute pointer of a tree.

Parameters

[in]	cmesh	The cmesh.
[in]	package_id	The identifier of a valid software package.

See also: sc_package_register

Parameters

[in]	key	A key used to identify the attribute under all attributes of this tree with the same package_id.
[in]	tree_id	The local number of the tree.
[out]	data_size	The size of the attribute in bytes.

Returns: The attribute pointer of the tree ltree_id or NULL if the attribute is not found. cmesh must be committed before calling this function.

See also: t8_cmesh_set_attribute

◆ t8_cmesh_get_face_neighbor()

t8_locidx_t t8_cmesh_get_face_neighbor	(	const t8_cmesh_t	cmesh,
		const t8_locidx_t	ltreeid,
		const int	face,
		int *	dual_face,
		int *	orientation
	)

Given a local tree id and a face number, get information about the face neighbor tree.

Parameters

[in]	cmesh	The cmesh to be considered.
[in]	ltreeid	The local id of a tree or a ghost.
[in]	face	A face number of the tree/ghost.
[out]	dual_face	If not NULL, the face number of the neighbor tree at this connection.
[out]	orientation	If not NULL, the face orientation of the connection.

Returns: If non-negative: The local id of the neighbor tree or ghost. If negative: There is no neighbor across this face. dual_face and orientation remain unchanged.

Note: If ltreeid is a ghost and it has a neighbor which is neither a local tree or ghost, then the return value will be negative. Thus, a negative return value does not necessarily mean that this is a domain boundary. To find out whether a tree is a domain boundary or not

See also: t8_cmesh_tree_face_is_boundary.

◆ t8_cmesh_get_first_tree()

t8_ctree_t t8_cmesh_get_first_tree ( t8_cmesh_t cmesh )

Return a pointer to the first local tree in a cmesh.

Parameters

[in] cmesh The cmesh to be queried.

Returns: A pointer to the first local tree in cmesh. If cmesh has no local trees, NULL is returned. cmesh must be committed before calling this function.

◆ t8_cmesh_get_first_treeid()

t8_gloidx_t t8_cmesh_get_first_treeid ( t8_cmesh_t cmesh )

Return the global index of the first local tree of a cmesh.

If the cmesh is not partitioned this is allways 0.

Parameters

[in] cmesh The cmesh to be considered.

Returns: The global id of the first local tree in cmesh. cmesh must be committed before calling this function.

◆ t8_cmesh_get_ghost_class()

t8_eclass_t t8_cmesh_get_ghost_class	(	t8_cmesh_t	cmesh,
		t8_locidx_t	lghost_id
	)

Return the eclass of a given local ghost.

TODO: Should we refer to indices or consequently use cghost_t?

Parameters

[in]	cmesh	The cmesh to be considered.
[in]	ghost_id	The local id of the ghost whose eclass will be returned. 0 <= tree_id < cmesh.num_ghosts.

Returns: The eclass of the given ghost. cmesh must be committed before calling this function.

◆ t8_cmesh_get_global_id()

t8_gloidx_t t8_cmesh_get_global_id	(	t8_cmesh_t	cmesh,
		t8_locidx_t	local_id
	)

Return the global id of a given local tree or ghost.

Parameters

[in]	cmesh	The cmesh to be considered.
[in]	local_id	The local id of a tree or a ghost. If local_id < cmesh.num_local_trees then it is a tree, otherwise a ghost.

Returns: The global id of the tree/ghost.

See also: https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing.

◆ t8_cmesh_get_local_id()

t8_locidx_t t8_cmesh_get_local_id	(	t8_cmesh_t	cmesh,
		t8_gloidx_t	global_id
	)

Return the local id of a give global tree.

Parameters

[in]	cmesh	The cmesh.
[in]	global_id	A global tree id.

Returns

Either a value l 0 <= l < num_local_trees if global_id corresponds to a local tree, or num_local_trees <= l < num_local_trees

num_ghosts if global_id corresponds to a ghost trees, or negative if global_id neither matches a local nor a ghost tree.

See also: https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing.

◆ t8_cmesh_get_next_tree()

t8_ctree_t t8_cmesh_get_next_tree	(	t8_cmesh_t	cmesh,
		t8_ctree_t	tree
	)

Given a local tree in a cmesh return a pointer to the next local tree.

Parameters

[in]	cmesh	The cmesh to be queried.
[in]	tree	A local tree in cmesh.

Returns

A pointer to the next local tree in cmesh after tree. If no such tree exists, NULL is returned.

cmesh must be committed before calling this function. TODO: If we run over tree numbers only, don't use ctree_t in API if possible.

◆ t8_cmesh_get_num_ghosts()

t8_locidx_t t8_cmesh_get_num_ghosts ( t8_cmesh_t cmesh )

Return the number of ghost trees of a cmesh.

If the cmesh is not partitioned this is equivalent to t8_cmesh_get_num_trees.

Parameters

[in] cmesh The cmesh to be considered.

Returns: The number of ghost trees of the cmesh. cmesh must be committed before calling this function.

◆ t8_cmesh_get_num_local_trees()

t8_locidx_t t8_cmesh_get_num_local_trees ( t8_cmesh_t cmesh )

Return the number of local trees of a cmesh.

If the cmesh is not partitioned this is equivalent to t8_cmesh_get_num_trees.

Parameters

[in] cmesh The cmesh to be considered.

Returns: The number of local trees of the cmesh. cmesh must be committed before calling this function.

◆ t8_cmesh_get_num_trees()

t8_gloidx_t t8_cmesh_get_num_trees ( t8_cmesh_t cmesh )

Return the global number of trees in a cmesh.

Parameters

[in] cmesh The cmesh to be considered.

Returns: The number of trees associated to cmesh. cmesh must be committed before calling this function.

◆ t8_cmesh_get_partition_table()

t8_shmem_array_t t8_cmesh_get_partition_table ( t8_cmesh_t cmesh )

Return the shared memory array storing the partition table of a partitioned cmesh.

Parameters

[in] cmesh The cmesh.

Returns: The partition array. NULL if the cmesh is not partitioned or the partition array is not stored in cmesh. cmesh must be committed before calling this function.

◆ t8_cmesh_get_tree()

t8_ctree_t t8_cmesh_get_tree	(	t8_cmesh_t	cmesh,
		t8_locidx_t	ltree_id
	)

Return a pointer to a given local tree.

Parameters

[in]	cmesh	The cmesh to be queried.
[in]	ltree_id	The local id of the tree that is asked for.

Returns: A pointer to tree in cmesh with local id ltree_id. The cmesh must have at least ltree_id + 1 local trees when calling this function. cmesh must be committed before calling this function.

◆ t8_cmesh_get_tree_class()

t8_eclass_t t8_cmesh_get_tree_class	(	t8_cmesh_t	cmesh,
		t8_locidx_t	ltree_id
	)

Return the eclass of a given local tree.

TODO: Should we refer to indices or consequently use ctree_t?

Parameters

[in]	cmesh	The cmesh to be considered.
[in]	tree_id	The local id of the tree whose eclass will be returned.

Returns: The eclass of the given tree. TODO: Call tree ids ltree_id or gtree_id etc. instead of tree_id. cmesh must be committed before calling this function.

◆ t8_cmesh_get_tree_vertices()

double* t8_cmesh_get_tree_vertices	(	t8_cmesh_t	cmesh,
		t8_locidx_t	ltreeid
	)

Return a pointer to the vertex coordinates of a tree.

Parameters

[in]	cmesh	The cmesh.
[in]	ltreeid	The id of a local tree.

Returns: If stored, a pointer to the vertex coordinates of tree. If no coordinates for this tree are found, NULL.

◆ t8_cmesh_init()

void t8_cmesh_init ( t8_cmesh_t * pcmesh )

Create a new cmesh with reference count one.

This cmesh needs to be specialized with the t8_cmesh_set_* calls. Then it needs to be set up with t8_cmesh_commit.

Parameters

[in,out] pcmesh On input, this pointer must be non-NULL. On return, this pointer set to the new cmesh.

◆ t8_cmesh_is_committed()

int t8_cmesh_is_committed ( t8_cmesh_t cmesh )

Check whether a cmesh is not NULL, initialized and committed.

In addition, it asserts that the cmesh is consistent as much as possible.

Parameters

[in] cmesh This cmesh is examined. May be NULL.

Returns: True if cmesh is not NULL and t8_cmesh_init has been called on it as well as t8_cmesh_commit. False otherwise.

◆ t8_cmesh_is_empty()

int t8_cmesh_is_empty ( t8_cmesh_t cmesh )

Check whether a cmesh is empty on all processes.

Parameters

[in] cmesh A committed cmesh.

Returns: True (non-zero) if and only if the cmesh has trees at all.

◆ t8_cmesh_is_equal()

int t8_cmesh_is_equal	(	t8_cmesh_t	cmesh_a,
		t8_cmesh_t	cmesh_b
	)

Check whether two given cmeshes carry the same information.

Parameters

[in]	cmesh_a	The first of the two cmeshes to be checked.
[in]	cmesh_b	The second of the two cmeshes to be checked.

Returns: True if both cmeshes carry the same information, false otherwise. TODO: define carefully. Orders, sequences, equivalences? This function works on committed and uncommitted cmeshes.

◆ t8_cmesh_is_initialized()

int t8_cmesh_is_initialized ( t8_cmesh_t cmesh )

Check whether a cmesh is not NULL, initialized and not committed.

In addition, it asserts that the cmesh is consistent as much as possible.

Parameters

[in] cmesh This cmesh is examined. May be NULL.

Returns: True if cmesh is not NULL, t8_cmesh_init has been called on it, but not t8_cmesh_commit. False otherwise.

◆ t8_cmesh_is_partitioned()

int t8_cmesh_is_partitioned ( t8_cmesh_t cmesh )

Query whether a committed cmesh is partitioned or replicated.

Parameters

[in] cmesh A committed cmesh.

Returns: True if cmesh is partitioned. False otherwise. cmesh must be committed before calling this function.

◆ t8_cmesh_ltreeid_to_ghostid()

t8_locidx_t t8_cmesh_ltreeid_to_ghostid	(	const t8_cmesh_t	cmesh,
		const t8_locidx_t	ltreeid
	)

Given a local tree id that belongs to a ghost, return the index of the ghost.

Parameters

[in]	cmesh	The cmesh to be considered.
[in]	ltreeid	The local id of a ghost, satisfying t8_cmesh_treeid_is_ghost, thus num_trees <= ltreeid < num_trees + num_ghosts

Returns: The index of the ghost whithin all ghosts, thus an index 0 <= index < num_ghosts cmesh must be committed before calling this function.

◆ t8_cmesh_print_profile()

void t8_cmesh_print_profile ( t8_cmesh_t cmesh )

Print the collected statistics from a cmesh profile.

Parameters

[in] cmesh The cmesh.

cmesh must be committed before calling this function.

See also: t8_cmesh_set_profiling

◆ t8_cmesh_ref()

void t8_cmesh_ref ( t8_cmesh_t cmesh )

Increase the reference counter of a cmesh.

Parameters

[in,out] cmesh On input, this cmesh must exist with positive reference count. It may be in any state.

◆ t8_cmesh_set_attribute()

void t8_cmesh_set_attribute	(	t8_cmesh_t	cmesh,
		t8_gloidx_t	gtree_id,
		int	package_id,
		int	key,
		void *	data,
		size_t	data_size,
		int	data_persists
	)

Store an attribute at a tree in a cmesh.

Attributes can be arbitrary data that is copied to an internal storage associated to the tree. Each application can set multiple attributes and attributes are distinguished by an interger key, where each application can use any integer as key.

Parameters

[in,out]	cmesh	The cmesh to be updated.
[in]	gtree_id	The global id of the tree.
[in]	package_id	Unique identifier of a valid software package.

See also: sc_package_register

Parameters

[in]	key	An integer key used to identify this attribute under all attributes with the same package_id. key must be a unique value for this tree and package_id.
[in]	data	A pointer to the attribute data.
[in]	data_size	The number of bytes of the attribute.
[in]	data_persists	This flag can be used to optimize memory. If true then t8code assumes that the attribute data is present at the memory that data points to when t8_cmesh_commit is called (This is more memory efficient). If the flag is false an internal copy of the data is created immediately and this copy is used at commit. In both cases a copy of the data is used by t8_code after t8_cmesh_commit.

Note: If an attribute with the given package_id and key already exists, then it will get overwritten.

◆ t8_cmesh_set_attribute_string()

void t8_cmesh_set_attribute_string	(	t8_cmesh_t	cmesh,
		t8_gloidx_t	gtree_id,
		int	package_id,
		int	key,
		const char *	string
	)

Store a string as an attribute at a tree in a cmesh.

Parameters

[in,out]	cmesh	The cmesh to be updated.
[in]	gtree_id	The global id of the tree.
[in]	package_id	Unique identifier of a valid software package.

See also: sc_package_register

Parameters

[in]	key	An integer key used to identify this attribute under all attributes with the same package_id. key must be a unique value for this tree and package_id.
[in]	string	The string to store as attribute.

Note: You can also use t8_cmesh_set_attribute, but we recommend using this specialized function for strings.

◆ t8_cmesh_set_derive()

void t8_cmesh_set_derive	(	t8_cmesh_t	cmesh,
		t8_cmesh_t	set_from
	)

This function sets a cmesh to be derived from.

The default is to create a cmesh standalone by specifying all data manually. A coarse mesh can also be constructed by deriving it from an existing one. The derivation from another cmesh may optionally be combined with a repartition or uniform refinement of each tree. This function overrides a previously set cmesh to be derived from.

Parameters

[in,out]	cmesh	Must be initialized, but not committed. May even be NULL to revert to standalone.
[in,out]	set_from	Reference counter on this cmesh is bumped. It will be unbumped by t8_cmesh_commit, after which from is no longer remembered. Other than that the from object is not changed.

◆ t8_cmesh_set_dimension()

void t8_cmesh_set_dimension	(	t8_cmesh_t	cmesh,
		int	dim
	)

Set the dimension of a cmesh.

If any tree is inserted to the cmesh via t8_cmesh_set_tree_class, then the dimension is set automatically to that of the inserted tree. However, if the cmesh is constructed partitioned and the part on this process is empty, it is neccessary to set the dimension by hand.

Parameters

[in,out]	cmesh	The cmesh to be updated.
[in]	dim	The dimension to be set. Must satisfy 0 <= dim <= 3. The cmesh must not be committed before calling this function.

◆ t8_cmesh_set_join()

void t8_cmesh_set_join	(	t8_cmesh_t	cmesh,
		t8_gloidx_t	gtree1,
		t8_gloidx_t	gtree2,
		int	face1,
		int	face2,
		int	orientation
	)

Insert a face-connection between two trees in a cmesh.

Parameters

[in,out]	cmesh	The cmesh to be updated.
[in]	tree1	The tree id of the first of the two trees.
[in]	tree2	The tree id of the second of the two trees.
[in]	face1	The face number of the first tree.
[in]	face2	The face number of the second tree.
[in]	orientation	Specify how face1 and face2 are oriented to each other TODO: orientation needs to be carefully defined for all element classes. TODO: document orientation

◆ t8_cmesh_set_partition_offsets()

void t8_cmesh_set_partition_offsets	(	t8_cmesh_t	cmesh,
		t8_shmem_array_t	tree_offsets
	)

Declare if the cmesh is understood as a partitioned cmesh and specify the first local tree for each process.

This call is only valid when the cmesh is not yet committed via a call to t8_cmesh_commit. If instead t8_cmesh_set_partition_range was called and the cmesh is derived then the offset array is constructed during commit.

Parameters

[in,out]	cmesh	The cmesh to be updated.
[in]	tree_offsets	An array of global tree_id offsets for each process can be specified here. TODO: document flag for shared trees.

◆ t8_cmesh_set_partition_range()

void t8_cmesh_set_partition_range	(	t8_cmesh_t	cmesh,
		int	set_face_knowledge,
		t8_gloidx_t	first_local_tree,
		t8_gloidx_t	last_local_tree
	)

Declare if the cmesh is understood as a partitioned cmesh and specify the processor local tree range.

This function should be preferred over t8_cmesh_set_partition_offsets when the cmesh is not derived from another cmesh. This call is only valid when the cmesh is not yet committed via a call to t8_cmesh_commit.

Parameters

[in,out]	cmesh	The cmesh to be updated. \parma [in] set_face_knowledge Several values are possible that define how much information is required on face connections, specified by t8_cmesh_set_join. 0: Expect face connection of local trees. 1: In addition, expect face connection from ghost trees to local trees. 2: In addition, expect face connection between ghost trees. 3: Expect face connection of local and ghost trees. Consistency of this requirement is checked on t8_cmesh_commit. -1: Co not change the face_knowledge level but keep any previously set ones. (Possibly by a previous call to t8_cmesh_set_partition_range)
[in]	first_local_tree	The global index ID of the first tree on this process. If this tree is also the last tree on the previous process, then the argument must be -ID - 1.
[in]	last_local_tree	The global index of the last tree on this process. If this process should be empty then last_local_tree must be strictly smaller than first_local_tree.

See also: t8_cmesh_set_partition_offset; t8_cmesh_set_partition_uniform

Note: A value of set_face_knowledge other than -1 or 3 is not yet supported.

◆ t8_cmesh_set_partition_uniform()

void t8_cmesh_set_partition_uniform	(	t8_cmesh_t	cmesh,
		int	element_level,
		t8_scheme_cxx_t *	ts
	)

Declare if the cmesh is understood as a partitioned cmesh where the partition table is derived from an assumed uniform refinement of a given level.

This call is only valid when the cmesh is not yet committed via a call to t8_cmesh_commit.

Parameters

[in,out]	cmesh	The cmesh to be updated.
[in]	element_level	The refinement_level.
[in]	ts	The element scheme describing the refinement pattern. We take ownership. This can be prevented by referencing ts before calling this function.

◆ t8_cmesh_set_profiling()

void t8_cmesh_set_profiling	(	t8_cmesh_t	cmesh,
		int	set_profiling
	)

Enable or disable profiling for a cmesh.

If profiling is enabled, runtimes and statistics are collected during cmesh_commit.

Parameters

[in,out]	cmesh	The cmesh to be updated.
[in]	set_profiling	If true, profiling will be enabled, if false disabled.

Profiling is disabled by default. The cmesh must not be committed before calling this function.

See also: t8_cmesh_print_profile

◆ t8_cmesh_set_refine()

void t8_cmesh_set_refine	(	t8_cmesh_t	cmesh,
		int	level,
		t8_scheme_cxx_t *	scheme
	)

Refine the cmesh to a given level.

Thus split each tree into x^level subtrees TODO: implement

◆ t8_cmesh_set_tree_class()

void t8_cmesh_set_tree_class	(	t8_cmesh_t	cmesh,
		t8_gloidx_t	gtree_id,
		t8_eclass_t	tree_class
	)

Set the class of a tree in the cmesh.

It is not allowed to call this function after t8_cmesh_commit. It is not allowed to call this function multiple times for the same tree.

Parameters

[in,out]	cmesh	The cmesh to be updated.
[in]	tree_id	The global number of the tree.
[in]	tree_class	The element class of this tree.

◆ t8_cmesh_set_tree_vertices()

void t8_cmesh_set_tree_vertices	(	t8_cmesh_t	cmesh,
		t8_locidx_t	ltree_id,
		double *	vertices,
		int	num_vertices
	)

Set the vertex coordinates of a tree in the cmesh.

This is currently inefficient, since the vertices are duplicated for each tree. Eventually this function will be replaced by a more efficient one. It is not allowed to call this function after t8_cmesh_commit. The eclass of the tree has to be set before calling this function.

Parameters

[in,out]	cmesh	The cmesh to be updated.
[in]	ltree_id	The local number of the tree.
[in]	vertices	An array of 3 doubles per tree vertex.
[in]	num_vertices	The number of verticess in vertices. Must match the number of corners of the tree.

◆ t8_cmesh_translate_coordinates()

void t8_cmesh_translate_coordinates	(	const double *	coords_in,
		double *	coords_out,
		int	num_vertices,
		double	translate[3]
	)

Compute y = x + translate on an array of doubles, interpreting each 3 as one vector x.

Parameters

[in]	coords_in	The incoming coordinates of the vectors
[out]	coords_out	The computed coordinates of the vectors
[in]	num_vertices	The number of vertices/vectors
[in]	translate	Translation of the vectors.

◆ t8_cmesh_tree_face_is_boundary()

int t8_cmesh_tree_face_is_boundary	(	t8_cmesh_t	cmesh,
		t8_locidx_t	ltree_id,
		int	face
	)

Query whether a face of a local tree or ghost is at the domain boundary.

Parameters

[in]	cmesh	The cmesh to be considered.
[in]	ltree_id	The local id of a tree.
[in]	face	The number of a face of the tree.

Returns: True if the face is at the domain boundary. False otherwise. cmesh must be committed before calling this function.

◆ t8_cmesh_tree_vertices_negative_volume()

int t8_cmesh_tree_vertices_negative_volume	(	t8_eclass_t	eclass,
		double *	vertices,
		int	num_vertices
	)

Given a set of vertex coordinates for a tree of a given eclass.

Query whether the geometric volume of the tree with this coordinates would be negative.

Parameters

[in]	eclass	The eclass of a tree.
[in]	vertices	The coordinates of the tree's vertices.
[in]	num_vertices	The number of vertices. vertices must hold 3 * num_vertices many doubles. num_vertices must match t8_eclass_num_vertices[eclass]

Returns: True if the geometric volume describe by vertices is negative. Fals otherwise. Returns true if a tree of the given eclass with the given vertex coordinates does have negative volume.

◆ t8_cmesh_treeid_is_ghost()

int t8_cmesh_treeid_is_ghost	(	const t8_cmesh_t	cmesh,
		const t8_locidx_t	ltreeid
	)

Query whether a given t8_locidx_t belongs to a ghost of a cmesh.

Parameters

[in]	cmesh	The cmesh to be considered.
[in]	ltreeid	An (possible) ghost index.

Returns: True if ltreeid matches the range of ghost trees of cmesh. False if not. cmesh must be committed before calling this function.

◆ t8_cmesh_treeid_is_local_tree()

int t8_cmesh_treeid_is_local_tree	(	const t8_cmesh_t	cmesh,
		const t8_locidx_t	ltreeid
	)

Query whether a given t8_locidx_t belongs to a local tree of a cmesh.

Parameters

[in]	cmesh	The cmesh to be considered.
[in]	ltreeid	An (possible) tree index.

Returns: True if ltreeid matches the range of local trees of cmesh. False if not. cmesh must be committed before calling this function.

◆ t8_cmesh_unref()

void t8_cmesh_unref ( t8_cmesh_t * pcmesh )

Decrease the reference counter of a cmesh.

If the counter reaches zero, this cmesh is destroyed. See also t8_cmesh_destroy, which is to be preferred when it is known that the last reference to a cmesh is deleted.

Parameters

[in,out] pcmesh On input, the cmesh pointed to must exist with positive reference count. It may be in any state. If the reference count reaches zero, the cmesh is destroyed and this pointer set to NULL. Otherwise, the pointer is not changed and the cmesh is not modified in other ways.

Functions

Detailed Description

Function Documentation

◆ t8_cmesh_alloc_offsets()

◆ t8_cmesh_bcast()

◆ t8_cmesh_comm_is_valid()

◆ t8_cmesh_coords_axb()

◆ t8_cmesh_debug_print_trees()

◆ t8_cmesh_destroy()

◆ t8_cmesh_get_attribute()

◆ t8_cmesh_get_face_neighbor()

◆ t8_cmesh_get_first_tree()

◆ t8_cmesh_get_first_treeid()

◆ t8_cmesh_get_ghost_class()

◆ t8_cmesh_get_global_id()

◆ t8_cmesh_get_local_id()

◆ t8_cmesh_get_next_tree()

◆ t8_cmesh_get_num_ghosts()

◆ t8_cmesh_get_num_local_trees()

◆ t8_cmesh_get_num_trees()

◆ t8_cmesh_get_partition_table()

◆ t8_cmesh_get_tree()

◆ t8_cmesh_get_tree_class()

◆ t8_cmesh_get_tree_vertices()

◆ t8_cmesh_init()

◆ t8_cmesh_is_committed()

◆ t8_cmesh_is_empty()

◆ t8_cmesh_is_equal()

◆ t8_cmesh_is_initialized()

◆ t8_cmesh_is_partitioned()

◆ t8_cmesh_ltreeid_to_ghostid()

◆ t8_cmesh_print_profile()

◆ t8_cmesh_ref()

◆ t8_cmesh_set_attribute()

◆ t8_cmesh_set_attribute_string()

◆ t8_cmesh_set_derive()

◆ t8_cmesh_set_dimension()

◆ t8_cmesh_set_join()

◆ t8_cmesh_set_partition_offsets()

◆ t8_cmesh_set_partition_range()

◆ t8_cmesh_set_partition_uniform()

◆ t8_cmesh_set_profiling()

◆ t8_cmesh_set_refine()

◆ t8_cmesh_set_tree_class()

◆ t8_cmesh_set_tree_vertices()

◆ t8_cmesh_translate_coordinates()

◆ t8_cmesh_tree_face_is_boundary()

◆ t8_cmesh_tree_vertices_negative_volume()

◆ t8_cmesh_treeid_is_ghost()

◆ t8_cmesh_treeid_is_local_tree()

◆ t8_cmesh_unref()