Skip to content

Documentation: Fix doxygen errors and update documentation in src/t8_forest/ directory. #1867

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Davknapp merged 4 commits into from
Sep 23, 2025
Merged

Documentation: Fix doxygen errors and update documentation in src/t8_forest/ directory. #1867

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f4ef1d5
Documentation: Removed all doxygen warnings from src/t8_forest/ direc…
spenke91 Sep 17, 2025
2087318
Replace placeholders by actual doxygen documentation
spenke91 Sep 17, 2025
af84a57
Merge branch 'main' into doc_t8_forest
Davknapp Sep 23, 2025
87c5378
Update src/t8_forest/t8_forest_private.h
Davknapp Sep 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions src/t8_forest/t8_forest.cxx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2068,12 +2068,11 @@ t8_forest_element_check_owner (t8_forest_t forest, t8_element_t *element, t8_glo
* It contains the linear id of the element that we look for and
* a pointer to the forest, we also store the index of the biggest owner process.
*/

struct find_owner_data_t
{
t8_linearidx_t linear_id;
t8_forest_t forest;
int last_owner;
t8_linearidx_t linear_id; /**< The linear id of the element we look for. */
t8_forest_t forest; /**< Pointer to the forest. */
int last_owner; /**< Index of the owner process with the highest index. */
};

static int
Expand Down
6 changes: 5 additions & 1 deletion src/t8_forest/t8_forest_adapt.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,11 @@
#include <t8_forest/t8_forest_general.h>

T8_EXTERN_C_BEGIN ();
/* TODO: comment */
/**
* Adapt a forest.
*
* \param[in, out] forest The forest to be adapted
*/
void
t8_forest_adapt (t8_forest_t forest);

Expand Down
16 changes: 13 additions & 3 deletions src/t8_forest/t8_forest_balance.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,22 @@

T8_EXTERN_C_BEGIN ();

/* TODO: document
* only temporary and will be replaced in future */
/**
* Balance the forest.
*
* This function adjust the forest such that it satisfies a 2:1 balance condition: The levels of neighboring
* elements may differ by at most one. Such a balanced forest simplifies many algorithms, making balancing
* an important procedure for both developers and external users.
*
* \param[in,out] forest The forest to be balanced.
* \param[in] repartition Switch deciding whether the forest is repartitioned after balancing.
*/
void
t8_forest_balance (t8_forest_t forest, int repartition);

/* Check whether the local elements of a forest are balanced. */
/**
* Check whether the local elements of a forest are balanced.
*/
int
t8_forest_is_balanced (t8_forest_t forest);

Expand Down
64 changes: 40 additions & 24 deletions src/t8_forest/t8_forest_general.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@

/** Opaque pointer to a forest implementation. */
typedef struct t8_forest *t8_forest_t;

/** Opaque pointer to a tree implementation. */
typedef struct t8_tree *t8_tree_t;

/** This type controls, which neighbors count as ghost elements.
Expand Down Expand Up @@ -119,8 +121,8 @@ typedef int (*t8_forest_adapt_t) (t8_forest_t forest, t8_forest_t forest_from, t

/** Create a new forest with reference count one.
* This forest needs to be specialized with the t8_forest_set_* calls.
* Currently it is mandatory to either call the functions \ref
* t8_forest_set_mpicomm, \ref t8_forest_set_cmesh, and \ref t8_forest_set_scheme,
* Currently it is mandatory to either call the functions \see t8_forest_set_mpicomm,
* \ref t8_forest_set_cmesh, and \ref t8_forest_set_scheme,
* or to call one of \ref t8_forest_set_copy, \ref t8_forest_set_adapt, or
* \ref t8_forest_set_partition. It is illegal to mix these calls, or to
* call more than one of the three latter functions
Expand Down Expand Up @@ -168,7 +170,7 @@ t8_forest_no_overlap (t8_forest_t forest);
* \param [in] forest_b The second forest.
* \return True if \a forest_a and \a forest_b do have the same
* number of local trees and each local tree has the same
* elements, that is \ref t8_element_equal returns true
* elements, that is \ref t8_element_is_equal returns true
* for each pair of elements of \a forest_a and \a forest_b.
* \note This function is not collective. It only returns the state on the current
* rank.
Expand All @@ -185,6 +187,7 @@ t8_forest_is_equal (t8_forest_t forest_a, t8_forest_t forest_b);
* \param [in,out] forest The forest whose cmesh variable will be set.
* \param [in] cmesh The cmesh to be set. We take ownership.
* This can be prevented by referencing \b cmesh.
* \param [in] comm The MPI communicator.
*/
void
t8_forest_set_cmesh (t8_forest_t forest, t8_cmesh_t cmesh, sc_MPI_Comm comm);
Expand Down Expand Up @@ -361,6 +364,11 @@ t8_forest_set_ghost (t8_forest_t forest, int do_ghost, t8_ghost_type_t ghost_typ
/** Like \ref t8_forest_set_ghost but with the additional options to change the
* ghost algorithm. This is used for debugging and timing the algorithm.
* An application should almost always use \ref t8_forest_set_ghost.
* \param [in] forest The forest.
* \param [in] do_ghost If non-zero a ghost layer will be created.
* \param [in] ghost_type Controls which neighbors count as ghost elements,
* currently only T8_GHOST_FACES is supported. This value
* is ignored if \a do_ghost = 0.
* \param [in] ghost_version If 1, the iterative ghost algorithm for balanced forests is used.
* If 2, the iterative algorithm for unbalanced forests.
* If 3, the top-down search algorithm for unbalanced forests.
Expand All @@ -369,8 +377,12 @@ t8_forest_set_ghost (t8_forest_t forest, int do_ghost, t8_ghost_type_t ghost_typ
void
t8_forest_set_ghost_ext (t8_forest_t forest, int do_ghost, t8_ghost_type_t ghost_type, int ghost_version);

/* TODO: use assertions and document that the forest_set (..., from) and
* set_load are mutually exclusive. */
/**
* Use assertions and document that the forest_set (..., from) and
* set_load are mutually exclusive.
*
* TODO: Unused function -> remove?
*/
void
t8_forest_set_load (t8_forest_t forest, const char *filename);

Expand Down Expand Up @@ -489,7 +501,7 @@ t8_forest_ltreeid_to_cmesh_ltreeid (t8_forest_t forest, t8_locidx_t ltreeid);

/** Given the local id of a tree in the coarse mesh of a forest, compute the tree's local id in the forest.
* \param [in] forest The forest.
* \param [in] ltreeid The local id of a tree in the coarse mesh of \a forest.
* \param [in] lctreeid The local id of a tree in the coarse mesh of \a forest.
* \return The local id of the tree in the forest. -1 if the tree is not forest local.
* \a forest must be committed before calling this function.
* \note For forest local trees, this is the inverse function of \ref t8_forest_ltreeid_to_cmesh_ltreeid.
Expand Down Expand Up @@ -592,7 +604,7 @@ t8_forest_leaf_face_neighbors (t8_forest_t forest, t8_locidx_t ltreeid, const t8
* \param [out] orientation If not NULL on input, the face orientation is computed and stored here.
* Thus, if the face connection is an inter-tree connection the orientation of the tree-to-tree connection is stored.
* Otherwise, the value 0 is stored.
* All other parameters and behavior are identical to \ref `t8_forest_leaf_face_neighbors`.
* All other parameters and behavior are identical to \ref t8_forest_leaf_face_neighbors.
* \note If there are no face neighbors, then *neighbor_leaves = NULL, num_neighbors = 0,
* and *pelement_indices = NULL on output.
* \note Currently \a forest must be balanced.
Expand Down Expand Up @@ -795,7 +807,7 @@ t8_gloidx_t
t8_forest_get_first_local_leaf_element_id (t8_forest_t forest);

/** Return the element scheme associated to a forest.
* \param [in] forest. A committed forest.
* \param [in] forest A committed forest.
* \return The element scheme of the forest.
* \see t8_forest_set_scheme
*/
Expand All @@ -804,10 +816,10 @@ t8_forest_get_scheme (const t8_forest_t forest);

/** Return the eclass of the tree in which a face neighbor of a given element
* lies.
* \param [in] forest. A committed forest.
* \param [in] ltreeid. The local tree in which the element lies.
* \param [in] elem. An element in the tree \a ltreeid.
* \param [in] face. A face number of \a elem.
* \param [in] forest A committed forest.
* \param [in] ltreeid The local tree in which the element lies.
* \param [in] elem An element in the tree \a ltreeid.
* \param [in] face A face number of \a elem.
* \return The local tree id of the tree in which the face
* neighbor of \a elem across \a face lies.
*/
Expand All @@ -817,24 +829,29 @@ t8_forest_element_neighbor_eclass (t8_forest_t forest, t8_locidx_t ltreeid, cons
/** Construct the face neighbor of an element, possibly across tree boundaries.
* Returns the global tree-id of the tree in which the neighbor element lies in.
*
* \param [in] elem The element to be considered.
* \param [in,out] neigh On input an allocated element of the scheme of the
* face_neighbors eclass.
* On output, this element's data is filled with the
* data of the face neighbor. If the neighbor does not exist
* the data could be modified arbitrarily.
* \param [in] forest The forest.
* \param [in] ltreeid The local tree in which the element lies.
* \param [in] elem The element to be considered.
* \param [in,out] neigh On input an allocated element of the scheme of the
* face_neighbors eclass.
* On output, this element's data is filled with the
* data of the face neighbor. If the neighbor does not exist
* the data could be modified arbitrarily.
* \param [in] neigh_eclass The eclass of \a neigh.
* \param [in] face The number of the face along which the neighbor should be
* constructed.
* \param [out] neigh_face The number of the face viewed from perspective of \a neigh.
* \param [in] face The number of the face along which the neighbor should be constructed.
* \param [out] neigh_face The number of the face viewed from perspective of \a neigh.
* \return The global tree-id of the tree in which \a neigh is in.
* -1 if there exists no neighbor across that face.
*/
t8_gloidx_t
t8_forest_element_face_neighbor (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *elem, t8_element_t *neigh,
const t8_eclass_t neigh_eclass, int face, int *neigh_face);

/* TODO: implement */
/**
* TODO: Can be removed since it is unused.
*
* \param[in] forest The forest.
*/
void
t8_forest_iterate (t8_forest_t forest);

Expand All @@ -843,7 +860,7 @@ t8_forest_iterate (t8_forest_t forest);
* if the four vertices lie in the same plane, but it may produce only approximate results if
* the vertices do not lie in the same plane.
* \param [in] forest The forest.
* \param [in] ltree_id The forest local id of the tree in which the element is.
* \param [in] ltreeid The forest local id of the tree in which the element is.
* \param [in] element The element.
* \param [in] points 3-dimensional coordinates of the points to check
* \param [in] num_points The number of points to check
Expand Down Expand Up @@ -896,7 +913,6 @@ t8_forest_new_uniform (t8_cmesh_t cmesh, const t8_scheme_c *scheme, const int le
/** Build a adapted forest from another forest.
* \param [in] forest_from The forest to refine
* \param [in] adapt_fn Adapt function to use
* \param [in] replace_fn Replace function to use
* \param [in] recursive If true adptation is recursive
* \param [in] do_face_ghost If true, a layer of ghost elements is created for the forest.
* \param [in] user_data If not NULL, the user data pointer of the forest is set to this value.
Expand Down
14 changes: 7 additions & 7 deletions src/t8_forest/t8_forest_geometrical.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ t8_forest_element_from_ref_coords (t8_forest_t forest, t8_locidx_t ltreeid, cons
* The centroid can be seen as the midpoint of an element and thus can for example be used
* to compute level-set values or the distance between two elements.
* \param [in] forest The forest.
* \param [in] ltree_id The forest local id of the tree in which the element is.
* \param [in] ltreeid The forest local id of the tree in which the element is.
* \param [in] element The element.
* \param [out] coordinates On input an allocated array to store 3 doubles, on output
* the x, y and z coordinates of the centroid.
Expand All @@ -109,7 +109,7 @@ t8_forest_element_centroid (t8_forest_t forest, t8_locidx_t ltreeid, const t8_el
/** Compute the diameter of an element if a geometry for this tree is registered in the forest's cmesh.
* This is only an approximation.
* \param [in] forest The forest.
* \param [in] ltree_id The forest local id of the tree in which the element is.
* \param [in] ltreeid The forest local id of the tree in which the element is.
* \param [in] element The element.
* \return The diameter of the element.
* \note For lines the value is exact while for other element types it is only
Expand All @@ -121,7 +121,7 @@ t8_forest_element_diam (t8_forest_t forest, t8_locidx_t ltreeid, const t8_elemen
/** Compute the volume of an element if a geometry for this tree is registered in the forest's cmesh.
* This is only an approximation.
* \param [in] forest The forest.
* \param [in] ltree_id The forest local id of the tree in which the element is.
* \param [in] ltreeid The forest local id of the tree in which the element is.
* \param [in] element The element.
* \return The diameter of the element.
* \note This function assumes d-linear interpolation for the
Expand All @@ -135,7 +135,7 @@ t8_forest_element_volume (t8_forest_t forest, t8_locidx_t ltreeid, const t8_elem
* Currently implemented for 2D elements only.
* This is only an approximation.
* \param [in] forest The forest.
* \param [in] ltree_id The forest local id of the tree in which the element is.
* \param [in] ltreeid The forest local id of the tree in which the element is.
* \param [in] element The element.
* \param [in] face A face of \a element.
* \return The area of \a face.
Expand All @@ -147,10 +147,10 @@ t8_forest_element_face_area (t8_forest_t forest, t8_locidx_t ltreeid, const t8_e
/** Compute the vertex coordinates of the centroid of an element's face if a geometry
* for this tree is registered in the forest's cmesh.
* \param [in] forest The forest.
* \param [in] ltree_id The forest local id of the tree in which the element is.
* \param [in] ltreeid The forest local id of the tree in which the element is.
* \param [in] element The element.
* \param [in] face A face of \a element.
* \param [out] normal On output the centroid of \a face.
* \param [out] centroid On output the centroid of \a face.
* \a forest must be committed when calling this function.
*/
void
Expand All @@ -160,7 +160,7 @@ t8_forest_element_face_centroid (t8_forest_t forest, t8_locidx_t ltreeid, const
/** Compute the normal vector of an element's face if a geometry for this tree is registered in the forest's cmesh.
* Currently implemented for 2D elements only.
* \param [in] forest The forest.
* \param [in] ltree_id The forest local id of the tree in which the element is.
* \param [in] ltreeid The forest local id of the tree in which the element is.
* \param [in] element The element.
* \param [in] face A face of \a element.
* \param [out] normal On output the normal vector of \a element at \a face.
Expand Down
Loading