The most important API functions

On this page we list the functions of t8code that are most important for users to interface with t8code.

This list does not provide a detailed description of all these functions. Please see the code and the Doxygen documentation for further details.

The list may not be complete. If you feel a function is missing from this list, please contact the developers, or create an issue.

cmesh

The coarse mesh interface.

Creating a cmesh

Use these to create a cmesh from one of the provided examples or a .msh file:

t8_cmesh_new…

[t8_cmesh_from_msh_file](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__cmesh__readmshfile_8h.html#a8ed1717cf36d4fc27e0994dce1dade7c)

To partition an existing cmesh:

[t8_cmesh_init](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__cmesh_8c.html#a0519e5e1547bdc72c73b478bbc1f6e70)
[t8_cmesh_set_derive](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__cmesh_8c.html#aec27dd0425316269576fa4c69d7121e4)
[t8_cmesh_set_partition_uniform](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__cmesh_8c.html#ae640d2a19a094bfdceaa7d33084a9b8b)
[t8_cmesh_commit](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__cmesh__commit_8c.html#ac819795480f1b8fe562e3561761a0184)

Call these functions between t8_cmesh_init and t8_cmesh_commit to build a cmesh from scratch:

[t8_cmesh_set_tree_class](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__cmesh_8c.html#ad318211db9da3414ff89983b3e24c118)
[t8_cmesh_set_join](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__cmesh_8c.html#a7a3c52997f3d6eb9d02870c34171693b)
t8_cmesh_register_geometry
[t8_cmesh_set_tree_vertices](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__cmesh_8c.html#a431cb3f32f6661d7eaabfb2cf041ec5f)

You can find examples for some of these functions in the Step 1 tutorial.

Forest

The forest interface.

General

The most important functions for constructing and modifying a forest:

[t8_forest_new_uniform](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a13122ecb8c71af117e108b554cc41f08)
[t8_forest_new_adapt](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#ac86d9553e0795fd3f7f4623c748d0674)
[t8_forest_init](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a8671e8128c5b13943cbf7187fe688cbb)
[t8_forest_set_user_data](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a7bc48a9274b531319b4e28f983050152)
[t8_forest_get_user_data](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a384b80956287ea7345216785ce63f698)
[t8_forest_set_user_function](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#aa2391c77d5a4c6abb3ac08fa9f8d357c)
[t8_forest_get_user_function](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#aa6521dfcab29a0c1ee34dde8863e3b5a)
[t8_forest_set_adapt](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a67b66fdbf9b87c73ae5434b65fc2bfd9)
[t8_forest_set_balance](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a4d759bcefbcdc06b1bc00e7dd16f4099)
[t8_forest_set_ghost](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#addd122e73a15816cc4008fca293cca7b)
[t8_forest_set_partition](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a05da93c37e3cf8d6a1716f7f1ef7ff33)
[t8_forest_commit](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a306ce9301c2101a1c1d910299879109f)

Forests are usually unreferenced (thus, possibly deleted) when they are used as input to construct a new forest (for example when you adapt a forest). To keep a forest alive beyond such an operation, use [t8_forest_ref](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a87ef4ae265d4f6e47c125894fb142977) before. To unreference a forest manually when it is no longer needed, use [t8_forest_unref](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a905cc95650b71404bc6e9a5c82199ed5).

t8_forest_vtk_write_file

can be used to create a VTK output.

See also the Step 2, Step 3 and Step 4 tutorials.

Data handling

These are the most important functions to deal with user data:

[t8_forest_iterate_replace](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__iterate_8h.html#a0bf6c7e6e226f7df8307df121aa81391)
t8_forest_partition_data
[t8_forest_ghost_exchange_data](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#af18f68a52bd5a9d46b79b7efdac25bd5)
t8_forest_iterate_faces (currently not tested)
t8_forest_search

iterate_replace is used to interpolate data between different forests (that arise from each other via adapting).

partition_data is used to repartition user data after the forest partition has changed.

ghost_exchange_data communicates date from local elements to remote processes that have these elements as ghosts.

t8_forest_search carries out a recursive search to identify matching elements according to a user defined criterion. See also the Search tutorial.

Access

Getters to query certain values:

[t8_forest_get_num_local_trees](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#aa37b0c16e2cda8158343bc3f941884fc)
[t8_forest_get_tree_class](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#aa1fa11abecf14da2b64d2a9650faf525)
[t8_forest_get_eclass_scheme](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a05e22d44c52899b988fb10352548b151)
[t8_forest_get_tree_num_elements](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a9036d8400b36a0edc83e53b0e89e1ac9)
[t8_forest_get_local_num_elements](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a763ba815a06bffa1ecc76c65046c3b09)
[t8_forest_get_global_num_elements](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a437b818aff1d8ed62654a2b321ce15ae)
[t8_forest_get_element_in_tree](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a64cc8b1aeeb416044c1b1f3b607bb0f9)
[t8_forest_get_tree_element_offset](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a4a5621b6ba148944915af5eed75c597e)
[t8_forest_get_num_ghosts](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a4aa138bb419eef6e4a205a8def7d21d4)

Computing neighbor elements:

[t8_forest_leaf_face_neighbors](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#afcdf881ab0e893b53c607e1d8a34c672)
[t8_forest_element_face_neighbor](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#afbaf9e18d5dd43f725dc00a8b3033f73)

Note that t8_forest_leaf_face_neighbors returns all face neighbors of an element that exist as leaves in the forest as an array. t8_forest_element_face_neighbor returns a single same level face neighbor element that may not exist as a leaf in the forest.

Geometry

Functions to compute geometry information of a single element, these are currently all computed as linear approximations based on the geometrically correct vertex and midpoint coordinates of an element.

[t8_forest_element_centroid](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__geometrical_8h.html#a474b134743046b3f6203b5712ddae605)
[t8_forest_element_volume](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__geometrical_8h.html#a0dcf0659725ff2fca21c41ac64b41b1d)
[t8_forest_element_coordinate](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__geometrical_8h.html#ab41599ba8f675822359e17108a732969)
[t8_forest_element_diam](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__geometrical_8h.html#a15c4139a4dcf22fba9e7228b8d9f08b8)
[t8_forest_element_face_centroid](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__geometrical_8h.html#a41ea72b578fb1820111d9184bf025d42)
[t8_forest_element_face_normal](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__geometrical_8h.html#abc2919d07d71d2468b7bd3a43f4d51f5)
[t8_forest_element_face_area](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__geometrical_8h.html#a00a414730b32186f3ed0d42ec51b38a9)
[t8_forest_element_point_inside](https://dlr-amr.github.io/t8code/doc/v1.6.0/t8__forest__general_8h.html#a1022af56311f715bbdadda571dbe1411)

Element interface

The element scheme interface offers functions that operate on a per element level.

t8_element_level
t8_element_shape
t8_element_num_corners
t8_element_num_faces
t8_element_max_num_faces
t8_element_num_children
t8_element_num_face_children
t8_element_face_shape
t8_element_tree_face
t8_element_boundary_face
t8_element_is_root_boundary
t8_element_vertex_reference_coords