diff --git a/Project.toml b/Project.toml index 77f1318..5532b5b 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,7 @@ name = "T8code" uuid = "d0cc0030-9a40-4274-8435-baadcfd54fa1" authors = ["Johannes Markert "] -version = "0.9.2" +version = "0.9.3" [deps] CEnum = "fa961155-64e5-5f13-b03f-caf6b980ea82" diff --git a/dev/Project.toml b/dev/Project.toml index c4dab81..4a757a6 100644 --- a/dev/Project.toml +++ b/dev/Project.toml @@ -1,7 +1,5 @@ [deps] Clang = "40e3b903-d033-50b4-a0cc-940c62c95e31" -Glob = "c27321d9-0574-5035-807b-f59d2c89b15c" [compat] -Clang = "0.18" -Glob = "1" +Clang = "0.19" diff --git a/dev/generator.jl b/dev/generator.jl index bda0ec1..01f395d 100644 --- a/dev/generator.jl +++ b/dev/generator.jl @@ -7,7 +7,6 @@ Pkg.instantiate() using Artifacts cp(joinpath(artifact"t8code", "include"), "t8code_include"; force = true) -using Glob using Clang.Generators cd(@__DIR__) @@ -19,12 +18,11 @@ options = load_options(joinpath(@__DIR__, "generator.toml")) args = get_default_args() # Note you must call this function firstly and then append your own flags push!(args, "-I$include_dir") -headers = [ - glob("t8_*.h", include_dir) ; - glob("**/t8_*.h", include_dir) ; - glob("**/**/t8_*.h", include_dir) ; - # glob("**/**/**/t8_*.h", include_dir) -] +filter_out = (x -> !startswith(basename(x), "t8_") || + !endswith(basename(x), ".h") || + basename(x) == "t8_dtri_to_dtet.h") # this header contains redefinitions which seem harmful + +headers = detect_headers(include_dir, args, Dict(), filter_out) # create context ctx = create_context(headers, args, options) diff --git a/dev/prologue.jl b/dev/prologue.jl index 3aa09cb..8960df9 100644 --- a/dev/prologue.jl +++ b/dev/prologue.jl @@ -56,3 +56,4 @@ const INT32_MIN = typemin(Cint) const INT32_MAX = typemax(Cint) const INT64_MIN = typemin(Clonglong) const INT64_MAX = typemax(Clonglong) +const P4EST_QMAXLEVEL = 29 diff --git a/src/Libt8.jl b/src/Libt8.jl index a1b9f1a..2c9c822 100644 --- a/src/Libt8.jl +++ b/src/Libt8.jl @@ -65,6 +65,7 @@ const INT32_MIN = typemin(Cint) const INT32_MAX = typemax(Cint) const INT64_MIN = typemin(Clonglong) const INT64_MAX = typemax(Clonglong) +const P4EST_QMAXLEVEL = 29 """ @@ -311,6 +312,192 @@ function sc_shmem_free(package, array, comm) @ccall libsc.sc_shmem_free(package::Cint, array::Ptr{Cvoid}, comm::MPI_Comm)::Cvoid end +""" + t8_eclass + +This enumeration contains all possible element classes. + +| Enumerator | Note | +| :--------------------- | :----------------------------------------------------------------------------------------------------------------- | +| T8\\_ECLASS\\_ZERO | Zero-dimensional element class. | +| T8\\_ECLASS\\_VERTEX | The vertex is the only zero-dimensional element class. | +| T8\\_ECLASS\\_LINE | The line is the only one-dimensional element class. | +| T8\\_ECLASS\\_QUAD | The quadrilateral is one of two element classes in two dimensions. | +| T8\\_ECLASS\\_TRIANGLE | The element class for a triangle. | +| T8\\_ECLASS\\_HEX | The hexahedron is one three-dimensional element class. | +| T8\\_ECLASS\\_TET | The tetrahedron is another three-dimensional element class. | +| T8\\_ECLASS\\_PRISM | The prism has five sides: two opposing triangles joined by three quadrilaterals. | +| T8\\_ECLASS\\_PYRAMID | The pyramid has a quadrilateral as base and four triangles as sides. | +| T8\\_ECLASS\\_COUNT | This is no element class but can be used as the number of element classes. | +| T8\\_ECLASS\\_INVALID | This is no element class but can be used for the case a class of a third party library is not supported by t8code | +""" +@cenum t8_eclass::UInt32 begin + T8_ECLASS_ZERO = 0 + T8_ECLASS_VERTEX = 0 + T8_ECLASS_LINE = 1 + T8_ECLASS_QUAD = 2 + T8_ECLASS_TRIANGLE = 3 + T8_ECLASS_HEX = 4 + T8_ECLASS_TET = 5 + T8_ECLASS_PRISM = 6 + T8_ECLASS_PYRAMID = 7 + T8_ECLASS_COUNT = 8 + T8_ECLASS_INVALID = 9 +end + +"""This enumeration contains all possible element classes.""" +const t8_eclass_t = t8_eclass + +"""Type definition for the geometric shape of an element. Currently the possible shapes are the same as the possible element classes. I.e. T8\\_ECLASS\\_VERTEX, T8\\_ECLASS\\_TET, etc...""" +const t8_element_shape_t = t8_eclass_t + +""" + sc_refcount + +The refcount structure is declared in public so its size is known. Its members should really never be accessed directly. + +| Field | Note | +| :----------- | :----------------------------------------------------------- | +| package\\_id | The sc package that uses this reference counter. | +| refcount | The reference count is always positive for a valid counter. | +""" +struct sc_refcount + package_id::Cint + refcount::Cint +end + +"""The refcount structure is declared in public so its size is known. Its members should really never be accessed directly.""" +const sc_refcount_t = sc_refcount + +""" + sc_refcount_ref(rc) + +Increase a reference counter. The counter must be active, that is, have a value greater than zero. + +# Arguments +* `rc`:\\[in,out\\] This reference counter must be valid (greater zero). Its count is increased by one. +### Prototype +```c +void sc_refcount_ref (sc_refcount_t * rc); +``` +""" +function sc_refcount_ref(rc) + @ccall libsc.sc_refcount_ref(rc::Ptr{sc_refcount_t})::Cvoid +end + +""" + sc_refcount_unref(rc) + +Decrease the reference counter and notify when it reaches zero. The count must be greater zero on input. If the reference count reaches zero, which is indicated by the return value, the counter may not be used further with sc_refcount_ref or + +# Arguments +* `rc`:\\[in,out\\] This reference counter must be valid (greater zero). Its count is decreased by one. +# Returns +True if the count has reached zero, false otherwise. +# See also +[`sc_refcount_unref`](@ref). It is legal, however, to reactivate it later by calling, [`sc_refcount_init`](@ref). + +### Prototype +```c +int sc_refcount_unref (sc_refcount_t * rc); +``` +""" +function sc_refcount_unref(rc) + @ccall libsc.sc_refcount_unref(rc::Ptr{sc_refcount_t})::Cint +end + +""" + sc_refcount_is_active(rc) + +Check whether a reference counter has a positive value. This means that the reference counter is in use and corresponds to a live object. + +# Arguments +* `rc`:\\[in\\] A reference counter. +# Returns +True if the count is greater zero, false otherwise. +### Prototype +```c +int sc_refcount_is_active (const sc_refcount_t * rc); +``` +""" +function sc_refcount_is_active(rc) + @ccall libsc.sc_refcount_is_active(rc::Ptr{sc_refcount_t})::Cint +end + +""" + sc_refcount_is_last(rc) + +Check whether a reference counter has value one. This means that this counter is the last of its kind, which we may optimize for. + +# Arguments +* `rc`:\\[in\\] A reference counter. +# Returns +True if the count is exactly one. +### Prototype +```c +int sc_refcount_is_last (const sc_refcount_t * rc); +``` +""" +function sc_refcount_is_last(rc) + @ccall libsc.sc_refcount_is_last(rc::Ptr{sc_refcount_t})::Cint +end + +""" + sc_MPI_Error_string(errorcode, string, resultlen) + +Turn MPI error code into a string. + +# Arguments +* `errorcode`:\\[in\\] This (MPI) error code is converted. +* `string`:\\[in,out\\] At least [`sc_MPI_MAX_ERROR_STRING`](@ref) bytes. +* `resultlen`:\\[out\\] Length of string on return. +# Returns +[`sc_MPI_SUCCESS`](@ref) on success or other MPI error cocde on invalid arguments. +### Prototype +```c +int sc_MPI_Error_string (int errorcode, char *string, int *resultlen); +``` +""" +function sc_MPI_Error_string(errorcode, string, resultlen) + @ccall libsc.sc_MPI_Error_string(errorcode::Cint, string::Cstring, resultlen::Ptr{Cint})::Cint +end + +""" + sc_io_read(mpifile, ptr, zcount, t, errmsg) + +### Prototype +```c +void sc_io_read (sc_MPI_File mpifile, void *ptr, size_t zcount, sc_MPI_Datatype t, const char *errmsg); +``` +""" +function sc_io_read(mpifile, ptr, zcount, t, errmsg) + @ccall libsc.sc_io_read(mpifile::MPI_File, ptr::Ptr{Cvoid}, zcount::Csize_t, t::Cint, errmsg::Cstring)::Cvoid +end + +""" + sc_io_write(mpifile, ptr, zcount, t, errmsg) + +### Prototype +```c +void sc_io_write (sc_MPI_File mpifile, const void *ptr, size_t zcount, sc_MPI_Datatype t, const char *errmsg); +``` +""" +function sc_io_write(mpifile, ptr, zcount, t, errmsg) + @ccall libsc.sc_io_write(mpifile::MPI_File, ptr::Ptr{Cvoid}, zcount::Csize_t, t::Cint, errmsg::Cstring)::Cvoid +end + +"""Typedef for quadrant coordinates.""" +const p4est_qcoord_t = Int32 + +"""Typedef for counting topological entities (trees, tree vertices).""" +const p4est_topidx_t = Int32 + +"""Typedef for processor-local indexing of quadrants and nodes.""" +const p4est_locidx_t = Int32 + +"""Typedef for globally unique indexing of quadrants.""" +const p4est_gloidx_t = Int64 + """ sc_mpi_is_enabled() @@ -427,26 +614,6 @@ function sc_MPI_Error_class(errorcode, errorclass) @ccall libsc.sc_MPI_Error_class(errorcode::Cint, errorclass::Ptr{Cint})::Cint end -""" - sc_MPI_Error_string(errorcode, string, resultlen) - -Turn MPI error code into a string. - -# Arguments -* `errorcode`:\\[in\\] This (MPI) error code is converted. -* `string`:\\[in,out\\] At least [`sc_MPI_MAX_ERROR_STRING`](@ref) bytes. -* `resultlen`:\\[out\\] Length of string on return. -# Returns -[`sc_MPI_SUCCESS`](@ref) on success or other MPI error cocde on invalid arguments. -### Prototype -```c -int sc_MPI_Error_string (int errorcode, char *string, int *resultlen); -``` -""" -function sc_MPI_Error_string(errorcode, string, resultlen) - @ccall libsc.sc_MPI_Error_string(errorcode::Cint, string::Cstring, resultlen::Ptr{Cint})::Cint -end - """ sc_mpi_sizeof(t) @@ -3229,13657 +3396,17447 @@ function sc_shmem_prefix(sendbuf, recvbuf, count, type, op, comm) @ccall libsc.sc_shmem_prefix(sendbuf::Ptr{Cvoid}, recvbuf::Ptr{Cvoid}, count::Cint, type::Cint, op::Cint, comm::MPI_Comm)::Cvoid end -""" - t8_load_mode +mutable struct t8_shmem_array end -This enumeration contains all modes in which we can open a saved cmesh. The cmesh can be loaded with more processes than it was saved and the mode controls, which of the processes open files and distribute the data. +const t8_shmem_array_t = Ptr{t8_shmem_array} -| Enumerator | Note | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| T8\\_LOAD\\_FIRST | First mode. | -| T8\\_LOAD\\_SIMPLE | In simple mode, the first n processes load the file | -| T8\\_LOAD\\_BGQ | In BGQ mode, the file is loaded on n nodes and from one process of each node. This needs MPI Version 3.1 or higher. | -| T8\\_LOAD\\_STRIDE | Every n-th process loads a file. Handle with care, we introduce it, since on Juqueen MPI-3 was not available. The parameter n has to be passed as an extra parameter. # See also [`t8_cmesh_load_and_distribute`](@ref) | -| T8\\_LOAD\\_COUNT | Number of modes in which we can open a saved cmesh. | """ -@cenum t8_load_mode::UInt32 begin - T8_LOAD_FIRST = 0 - T8_LOAD_SIMPLE = 0 - T8_LOAD_BGQ = 1 - T8_LOAD_STRIDE = 2 - T8_LOAD_COUNT = 3 -end - -"""This enumeration contains all modes in which we can open a saved cmesh. The cmesh can be loaded with more processes than it was saved and the mode controls, which of the processes open files and distribute the data.""" -const t8_load_mode_t = t8_load_mode - -mutable struct t8_cmesh end + t8_shmem_init(comm) -"""Forward pointer reference to hidden cmesh implementation. This reference needs to be known by [`t8_geometry`](@ref), hence we put it before the include.""" -const t8_cmesh_t = Ptr{t8_cmesh} +### Prototype +```c +int t8_shmem_init (sc_MPI_Comm comm); +``` +""" +function t8_shmem_init(comm) + @ccall libt8.t8_shmem_init(comm::MPI_Comm)::Cint +end """ - sc_refcount + t8_shmem_finalize(comm) -The refcount structure is declared in public so its size is known. Its members should really never be accessed directly. +### Prototype +```c +void t8_shmem_finalize (sc_MPI_Comm comm); +``` +""" +function t8_shmem_finalize(comm) + @ccall libt8.t8_shmem_finalize(comm::MPI_Comm)::Cvoid +end -| Field | Note | -| :----------- | :----------------------------------------------------------- | -| package\\_id | The sc package that uses this reference counter. | -| refcount | The reference count is always positive for a valid counter. | """ -struct sc_refcount - package_id::Cint - refcount::Cint -end - -"""The refcount structure is declared in public so its size is known. Its members should really never be accessed directly.""" -const sc_refcount_t = sc_refcount - -""" - sc_refcount_init_invalid(rc) - -Initialize a well-defined but unusable reference counter. Specifically, we set its package identifier and reference count to -1. To make this reference counter usable, call sc_refcount_init. + t8_shmem_set_type(comm, type) -# Arguments -* `rc`:\\[out\\] This reference counter is defined as invalid. It will return false on both sc_refcount_is_active and sc_refcount_is_last. It can be made valid by calling sc_refcount_init. No other functions must be called on it. ### Prototype ```c -void sc_refcount_init_invalid (sc_refcount_t * rc); +void t8_shmem_set_type (sc_MPI_Comm comm, sc_shmem_type_t type); ``` """ -function sc_refcount_init_invalid(rc) - @ccall libsc.sc_refcount_init_invalid(rc::Ptr{sc_refcount_t})::Cvoid +function t8_shmem_set_type(comm, type) + @ccall libt8.t8_shmem_set_type(comm::MPI_Comm, type::sc_shmem_type_t)::Cvoid end """ - sc_refcount_init(rc, package_id) - -Initialize a reference counter to 1. It is legal if its status prior to this call is undefined. + t8_shmem_array_init(parray, elem_size, elem_count, comm) -# Arguments -* `rc`:\\[out\\] This reference counter is initialized to one. The object's contents may be undefined on input. -* `package_id`:\\[in\\] Either -1 or a package registered to libsc. ### Prototype ```c -void sc_refcount_init (sc_refcount_t * rc, int package_id); +void t8_shmem_array_init (t8_shmem_array_t *parray, size_t elem_size, size_t elem_count, sc_MPI_Comm comm); ``` """ -function sc_refcount_init(rc, package_id) - @ccall libsc.sc_refcount_init(rc::Ptr{sc_refcount_t}, package_id::Cint)::Cvoid +function t8_shmem_array_init(parray, elem_size, elem_count, comm) + @ccall libt8.t8_shmem_array_init(parray::Ptr{t8_shmem_array_t}, elem_size::Csize_t, elem_count::Csize_t, comm::MPI_Comm)::Cvoid end """ - sc_refcount_new(package_id) + t8_shmem_array_start_writing(array) -Create a new reference counter with count initialized to 1. Equivalent to calling sc_refcount_init on a newly allocated rc object. +Enable writing mode for a shmem array. Only some processes may be allowed to write into the array, which is indicated by the return value being non-zero. The shared memory is managed via inter- and intranode communicators. Only rank 0 of the intranode communicator will be allowed to write into the array. + +!!! note + + This function is MPI collective. # Arguments -* `package_id`:\\[in\\] Either -1 or a package registered to libsc. +* `array`:\\[in,out\\] Initialized array. Writing will be enabled on certain processes. # Returns -A reference counter with count one. +True if the calling process can write into the array. ### Prototype ```c -sc_refcount_t *sc_refcount_new (int package_id); +int t8_shmem_array_start_writing (t8_shmem_array_t array); ``` """ -function sc_refcount_new(package_id) - @ccall libsc.sc_refcount_new(package_id::Cint)::Ptr{sc_refcount_t} +function t8_shmem_array_start_writing(array) + @ccall libt8.t8_shmem_array_start_writing(array::t8_shmem_array_t)::Cint end """ - sc_refcount_destroy(rc) + t8_shmem_array_end_writing(array) -Destroy a reference counter. It must have been counted down to zero before, thus reached an inactive state. +Disable writing mode for a shmem array. + +!!! note + + This function is MPI collective. # Arguments -* `rc`:\\[in,out\\] This reference counter must have reached count zero. +* `array`:\\[in,out\\] Initialized with writing mode enabled. +# See also +[`t8_shmem_array_start_writing`](@ref). + ### Prototype ```c -void sc_refcount_destroy (sc_refcount_t * rc); +void t8_shmem_array_end_writing (t8_shmem_array_t array); ``` """ -function sc_refcount_destroy(rc) - @ccall libsc.sc_refcount_destroy(rc::Ptr{sc_refcount_t})::Cvoid +function t8_shmem_array_end_writing(array) + @ccall libt8.t8_shmem_array_end_writing(array::t8_shmem_array_t)::Cvoid end """ - sc_refcount_ref(rc) + t8_shmem_array_set_gloidx(array, index, value) -Increase a reference counter. The counter must be active, that is, have a value greater than zero. +Set an entry of a t8\\_shmem array that is used to store [`t8_gloidx_t`](@ref). The array must have writing mode enabled t8_shmem_array_start_writing. # Arguments -* `rc`:\\[in,out\\] This reference counter must be valid (greater zero). Its count is increased by one. +* `array`:\\[in,out\\] The array to be modified. +* `index`:\\[in\\] The array entry to be modified. +* `value`:\\[in\\] The new value to be set. ### Prototype ```c -void sc_refcount_ref (sc_refcount_t * rc); +void t8_shmem_array_set_gloidx (t8_shmem_array_t array, int index, t8_gloidx_t value); ``` """ -function sc_refcount_ref(rc) - @ccall libsc.sc_refcount_ref(rc::Ptr{sc_refcount_t})::Cvoid +function t8_shmem_array_set_gloidx(array, index, value) + @ccall libt8.t8_shmem_array_set_gloidx(array::t8_shmem_array_t, index::Cint, value::t8_gloidx_t)::Cvoid end """ - sc_refcount_unref(rc) + t8_shmem_array_copy(dest, source) -Decrease the reference counter and notify when it reaches zero. The count must be greater zero on input. If the reference count reaches zero, which is indicated by the return value, the counter may not be used further with sc_refcount_ref or +Copy the contents of one t8\\_shmem array into another. -# Arguments -* `rc`:\\[in,out\\] This reference counter must be valid (greater zero). Its count is decreased by one. -# Returns -True if the count has reached zero, false otherwise. -# See also -[`sc_refcount_unref`](@ref). It is legal, however, to reactivate it later by calling, [`sc_refcount_init`](@ref). +!!! note + *dest* must be initialized and match in element size and element count to *source*. + +!!! note + + *dest* must have writing mode disabled. + +# Arguments +* `dest`:\\[in,out\\] The array in which *source* should be copied. +* `source`:\\[in\\] The array to copy. ### Prototype ```c -int sc_refcount_unref (sc_refcount_t * rc); +void t8_shmem_array_copy (t8_shmem_array_t dest, t8_shmem_array_t source); ``` """ -function sc_refcount_unref(rc) - @ccall libsc.sc_refcount_unref(rc::Ptr{sc_refcount_t})::Cint +function t8_shmem_array_copy(dest, source) + @ccall libt8.t8_shmem_array_copy(dest::t8_shmem_array_t, source::t8_shmem_array_t)::Cvoid end """ - sc_refcount_is_active(rc) - -Check whether a reference counter has a positive value. This means that the reference counter is in use and corresponds to a live object. + t8_shmem_array_allgather(sendbuf, sendcount, sendtype, recvarray, recvcount, recvtype) -# Arguments -* `rc`:\\[in\\] A reference counter. -# Returns -True if the count is greater zero, false otherwise. ### Prototype ```c -int sc_refcount_is_active (const sc_refcount_t * rc); +void t8_shmem_array_allgather (const void *sendbuf, int sendcount, sc_MPI_Datatype sendtype, t8_shmem_array_t recvarray, int recvcount, sc_MPI_Datatype recvtype); ``` """ -function sc_refcount_is_active(rc) - @ccall libsc.sc_refcount_is_active(rc::Ptr{sc_refcount_t})::Cint +function t8_shmem_array_allgather(sendbuf, sendcount, sendtype, recvarray, recvcount, recvtype) + @ccall libt8.t8_shmem_array_allgather(sendbuf::Ptr{Cvoid}, sendcount::Cint, sendtype::Cint, recvarray::t8_shmem_array_t, recvcount::Cint, recvtype::Cint)::Cvoid end """ - sc_refcount_is_last(rc) - -Check whether a reference counter has value one. This means that this counter is the last of its kind, which we may optimize for. + t8_shmem_array_allgatherv(sendbuf, sendcount, sendtype, recvarray, recvtype, comm) -# Arguments -* `rc`:\\[in\\] A reference counter. -# Returns -True if the count is exactly one. ### Prototype ```c -int sc_refcount_is_last (const sc_refcount_t * rc); +void t8_shmem_array_allgatherv (void *sendbuf, const int sendcount, sc_MPI_Datatype sendtype, t8_shmem_array_t recvarray, sc_MPI_Datatype recvtype, sc_MPI_Comm comm); ``` """ -function sc_refcount_is_last(rc) - @ccall libsc.sc_refcount_is_last(rc::Ptr{sc_refcount_t})::Cint +function t8_shmem_array_allgatherv(sendbuf, sendcount, sendtype, recvarray, recvtype, comm) + @ccall libt8.t8_shmem_array_allgatherv(sendbuf::Ptr{Cvoid}, sendcount::Cint, sendtype::Cint, recvarray::t8_shmem_array_t, recvtype::Cint, comm::MPI_Comm)::Cvoid end -mutable struct t8_ctree end - -"""Forward pointer references to hidden implementations of tree.""" -const t8_ctree_t = Ptr{t8_ctree} - -mutable struct t8_cghost end - -"""Forward pointer references to hidden implementations of ghost tree.""" -const t8_cghost_t = Ptr{t8_cghost} - """ - t8_cmesh_init(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. + t8_shmem_array_prefix(sendbuf, recvarray, count, type, op, comm) -# Arguments -* `pcmesh`:\\[in,out\\] On input, this pointer must be non-NULL. On return, this pointer set to the new cmesh. ### Prototype ```c -void t8_cmesh_init (t8_cmesh_t *pcmesh); +void t8_shmem_array_prefix (const void *sendbuf, t8_shmem_array_t recvarray, const int count, sc_MPI_Datatype type, sc_MPI_Op op, sc_MPI_Comm comm); ``` """ -function t8_cmesh_init(pcmesh) - @ccall libt8.t8_cmesh_init(pcmesh::Ptr{t8_cmesh_t})::Cvoid +function t8_shmem_array_prefix(sendbuf, recvarray, count, type, op, comm) + @ccall libt8.t8_shmem_array_prefix(sendbuf::Ptr{Cvoid}, recvarray::t8_shmem_array_t, count::Cint, type::Cint, op::Cint, comm::MPI_Comm)::Cvoid end -# no prototype is found for this function at t8_cmesh.h:79:1, please use with caution """ - t8_cmesh_new() - -Allocate a new un-committed cmesh. + t8_shmem_array_get_comm(array) -# Returns -A pointer to an un-committed [`t8_cmesh`](@ref) structure. ### Prototype ```c -t8_cmesh_t t8_cmesh_new (); +sc_MPI_Comm t8_shmem_array_get_comm (t8_shmem_array_t array); ``` """ -function t8_cmesh_new() - @ccall libt8.t8_cmesh_new()::t8_cmesh_t +function t8_shmem_array_get_comm(array) + @ccall libt8.t8_shmem_array_get_comm(array::t8_shmem_array_t)::Cint end """ - t8_cmesh_is_initialized(cmesh) + t8_shmem_array_get_elem_size(array) -Check whether a cmesh is not NULL, initialized and not committed. In addition, it asserts that the cmesh is consistent as much as possible. +Get the element size of a [`t8_shmem_array`](@ref) # Arguments -* `cmesh`:\\[in\\] This cmesh is examined. May be NULL. +* `array`:\\[in\\] The array. # Returns -True if cmesh is not NULL, t8_cmesh_init has been called on it, but not t8_cmesh_commit. False otherwise. +The element size of *array*'s elements. ### Prototype ```c -int t8_cmesh_is_initialized (t8_cmesh_t cmesh); +size_t t8_shmem_array_get_elem_size (t8_shmem_array_t array); ``` """ -function t8_cmesh_is_initialized(cmesh) - @ccall libt8.t8_cmesh_is_initialized(cmesh::t8_cmesh_t)::Cint +function t8_shmem_array_get_elem_size(array) + @ccall libt8.t8_shmem_array_get_elem_size(array::t8_shmem_array_t)::Csize_t end """ - t8_cmesh_is_committed(cmesh) + t8_shmem_array_get_elem_count(array) -Check whether a cmesh is not NULL, initialized and committed. In addition, it asserts that the cmesh is consistent as much as possible. +Get the number of elements of a [`t8_shmem_array`](@ref) # Arguments -* `cmesh`:\\[in\\] This cmesh is examined. May be NULL. +* `array`:\\[in\\] The array. # Returns -True if cmesh is not NULL and t8_cmesh_init has been called on it as well as t8_cmesh_commit. False otherwise. +The number of elements in *array*. ### Prototype ```c -int t8_cmesh_is_committed (const t8_cmesh_t cmesh); +size_t t8_shmem_array_get_elem_count (t8_shmem_array_t array); ``` """ -function t8_cmesh_is_committed(cmesh) - @ccall libt8.t8_cmesh_is_committed(cmesh::t8_cmesh_t)::Cint +function t8_shmem_array_get_elem_count(array) + @ccall libt8.t8_shmem_array_get_elem_count(array::t8_shmem_array_t)::Csize_t end """ - t8_cmesh_disable_negative_volume_check(cmesh) + t8_shmem_array_get_gloidx_array(array) -Disable the debug check for negative volumes in trees during t8_cmesh_commit. Does nothing outside of debug mode. +Return a read-only pointer to the data of a shared memory array interpreted as an [`t8_gloidx_t`](@ref) array. + +!!! note + + Writing mode must be disabled for *array*. # Arguments -* `cmesh`:\\[in,out\\] +* `array`:\\[in\\] The [`t8_shmem_array`](@ref) +# Returns +The data of *array* as [`t8_gloidx_t`](@ref) pointer. ### Prototype ```c -void t8_cmesh_disable_negative_volume_check (t8_cmesh_t cmesh); +const t8_gloidx_t * t8_shmem_array_get_gloidx_array (t8_shmem_array_t array); ``` """ -function t8_cmesh_disable_negative_volume_check(cmesh) - @ccall libt8.t8_cmesh_disable_negative_volume_check(cmesh::t8_cmesh_t)::Cvoid +function t8_shmem_array_get_gloidx_array(array) + @ccall libt8.t8_shmem_array_get_gloidx_array(array::t8_shmem_array_t)::Ptr{t8_gloidx_t} end """ - t8_cmesh_set_derive(cmesh, set_from) + t8_shmem_array_get_gloidx_array_for_writing(array) -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. +Return a pointer to the data of a shared memory array interpreted as an [`t8_gloidx_t`](@ref) array. The array must have writing enabled t8_shmem_array_start_writing and you should not write into the memory after t8_shmem_array_end_writing was called. # Arguments -* `cmesh`:\\[in,out\\] Must be initialized, but not committed. May even be NULL to revert to standalone. -* `set_from`:\\[in,out\\] 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. +* `array`:\\[in\\] The [`t8_shmem_array`](@ref) +# Returns +The data of *array* as [`t8_gloidx_t`](@ref) pointer. ### Prototype ```c -void t8_cmesh_set_derive (t8_cmesh_t cmesh, t8_cmesh_t set_from); +t8_gloidx_t * t8_shmem_array_get_gloidx_array_for_writing (t8_shmem_array_t array); ``` """ -function t8_cmesh_set_derive(cmesh, set_from) - @ccall libt8.t8_cmesh_set_derive(cmesh::t8_cmesh_t, set_from::t8_cmesh_t)::Cvoid +function t8_shmem_array_get_gloidx_array_for_writing(array) + @ccall libt8.t8_shmem_array_get_gloidx_array_for_writing(array::t8_shmem_array_t)::Ptr{t8_gloidx_t} end -mutable struct t8_shmem_array end +""" + t8_shmem_array_get_gloidx(array, index) -const t8_shmem_array_t = Ptr{t8_shmem_array} +Return an entry of a shared memory array that stores [`t8_gloidx_t`](@ref). -""" - t8_cmesh_alloc_offsets(mpisize, comm) +!!! note + + Writing mode must be disabled for *array*. +# Arguments +* `array`:\\[in\\] The [`t8_shmem_array`](@ref) +* `index`:\\[in\\] The index of the entry to be queried. +# Returns +The *index*-th entry of *array* as [`t8_gloidx_t`](@ref). ### Prototype ```c -t8_shmem_array_t t8_cmesh_alloc_offsets (int mpisize, sc_MPI_Comm comm); +t8_gloidx_t t8_shmem_array_get_gloidx (t8_shmem_array_t array, int index); ``` """ -function t8_cmesh_alloc_offsets(mpisize, comm) - @ccall libt8.t8_cmesh_alloc_offsets(mpisize::Cint, comm::MPI_Comm)::t8_shmem_array_t +function t8_shmem_array_get_gloidx(array, index) + @ccall libt8.t8_shmem_array_get_gloidx(array::t8_shmem_array_t, index::Cint)::t8_gloidx_t end """ - t8_cmesh_set_partition_range(cmesh, set_face_knowledge, first_local_tree, last_local_tree) + t8_shmem_array_get_array(array) -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. +Return a pointer to the data array of a [`t8_shmem_array`](@ref). !!! note - A value of *set_face_knowledge* other than -1 or 3 is not yet supported. + Writing mode must be disabled for *array*. # Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `set_face_knowledge`:\\[in\\] 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: Do not change the face\\_knowledge level but keep any previously set ones. (Possibly by a previous call to t8_cmesh_set_partition_range) -* `first_local_tree`:\\[in\\] 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. -* `last_local_tree`:\\[in\\] 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`](@ref) - +* `array`:\\[in\\] The [`t8_shmem_array`](@ref). +# Returns +A pointer to the data array of *array*. ### Prototype ```c -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); +const void * t8_shmem_array_get_array (t8_shmem_array_t array); ``` """ -function t8_cmesh_set_partition_range(cmesh, set_face_knowledge, first_local_tree, last_local_tree) - @ccall libt8.t8_cmesh_set_partition_range(cmesh::t8_cmesh_t, set_face_knowledge::Cint, first_local_tree::t8_gloidx_t, last_local_tree::t8_gloidx_t)::Cvoid +function t8_shmem_array_get_array(array) + @ccall libt8.t8_shmem_array_get_array(array::t8_shmem_array_t)::Ptr{Cvoid} end """ - t8_cmesh_set_partition_offsets(cmesh, tree_offsets) + t8_shmem_array_index(array, index) -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. +Return a read-only pointer to an element in a [`t8_shmem_array`](@ref). + +!!! note + + You should not modify the value. + +!!! note + + Writing mode must be disabled for *array*. # Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `tree_offsets`:\\[in\\] An array of global tree\\_id offsets for each process can be specified here. TODO: document flag for shared trees. +* `array`:\\[in\\] The [`t8_shmem_array`](@ref). +* `index`:\\[in\\] The index of an element. +# Returns +A pointer to the element at *index* in *array*. ### Prototype ```c -void t8_cmesh_set_partition_offsets (t8_cmesh_t cmesh, t8_shmem_array_t tree_offsets); +const void * t8_shmem_array_index (t8_shmem_array_t array, size_t index); ``` """ -function t8_cmesh_set_partition_offsets(cmesh, tree_offsets) - @ccall libt8.t8_cmesh_set_partition_offsets(cmesh::t8_cmesh_t, tree_offsets::t8_shmem_array_t)::Cvoid +function t8_shmem_array_index(array, index) + @ccall libt8.t8_shmem_array_index(array::t8_shmem_array_t, index::Csize_t)::Ptr{Cvoid} end -mutable struct t8_scheme end +""" + t8_shmem_array_index_for_writing(array, index) -"""The scheme holds implementations for one or more element classes. Opaque pointer for C interface. Detailed documentation at t8_scheme.""" -const t8_scheme_c = t8_scheme +Return a pointer to an element in a [`t8_shmem_array`](@ref) in writing mode. + +!!! note + + You can modify the value before the next call to t8_shmem_array_end_writing. + +!!! note + + Writing mode must be enabled for *array*. + +# Arguments +* `array`:\\[in\\] The [`t8_shmem_array`](@ref). +* `index`:\\[in\\] The index of an element. +# Returns +A pointer to the element at *index* in *array*. +### Prototype +```c +void * t8_shmem_array_index_for_writing (t8_shmem_array_t array, size_t index); +``` +""" +function t8_shmem_array_index_for_writing(array, index) + @ccall libt8.t8_shmem_array_index_for_writing(array::t8_shmem_array_t, index::Csize_t)::Ptr{Cvoid} +end """ - t8_cmesh_set_partition_uniform(cmesh, element_level, scheme) + t8_shmem_array_is_equal(array_a, array_b) -Declare if a derived cmesh should be partitioned according to a uniform refinement of a given level for the provided scheme. This call is only valid when the cmesh is not yet committed via a call to t8_cmesh_commit and when the cmesh will be derived. +Check if two t8\\_shmem arrays are equal. + +!!! note + + Writing mode must be disabled for *array_a* and *array_b*. # Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `element_level`:\\[in\\] The refinement\\_level. -* `scheme`:\\[in\\] The element scheme describing the refinement pattern. We take ownership. This can be prevented by referencing **scheme** before calling this function. +* `array_a`:\\[in\\] The first [`t8_shmem_array`](@ref) to compare. +* `array_b`:\\[in\\] The second [`t8_shmem_array`](@ref) to compare. +# Returns +1 if the arrays are equal, 0 otherwise. ### Prototype ```c -void t8_cmesh_set_partition_uniform (t8_cmesh_t cmesh, const int element_level, const t8_scheme_c *scheme); +int t8_shmem_array_is_equal (t8_shmem_array_t array_a, t8_shmem_array_t array_b); ``` """ -function t8_cmesh_set_partition_uniform(cmesh, element_level, scheme) - @ccall libt8.t8_cmesh_set_partition_uniform(cmesh::t8_cmesh_t, element_level::Cint, scheme::Ptr{t8_scheme_c})::Cvoid +function t8_shmem_array_is_equal(array_a, array_b) + @ccall libt8.t8_shmem_array_is_equal(array_a::t8_shmem_array_t, array_b::t8_shmem_array_t)::Cint end """ - t8_cmesh_set_refine(cmesh, level, scheme) + t8_shmem_array_destroy(parray) -Refine the cmesh to a given level. Thus split each tree into x^level subtrees TODO: implement +Free all memory associated with a [`t8_shmem_array`](@ref). +# Arguments +* `parray`:\\[in,out\\] On input a pointer to a valid [`t8_shmem_array`](@ref). This array is freed and *parray* is set to NULL on return. ### Prototype ```c -void t8_cmesh_set_refine (t8_cmesh_t cmesh, const int level, const t8_scheme_c *scheme); +void t8_shmem_array_destroy (t8_shmem_array_t *parray); ``` """ -function t8_cmesh_set_refine(cmesh, level, scheme) - @ccall libt8.t8_cmesh_set_refine(cmesh::t8_cmesh_t, level::Cint, scheme::Ptr{t8_scheme_c})::Cvoid +function t8_shmem_array_destroy(parray) + @ccall libt8.t8_shmem_array_destroy(parray::Ptr{t8_shmem_array_t})::Cvoid end """ - t8_cmesh_set_dimension(cmesh, dim) + t8_shmem_array_binary_search(array, value, size, compare) -Set the dimension of a cmesh. If any tree is inserted to the cmesh via [`t8_cmesh_set_tree_class`](@ref), 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 necessary to set the dimension by hand. +Perform a binary search in a [`t8_shmem_array`](@ref). # Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `dim`:\\[in\\] The dimension to be set. Must satisfy 0 <= dim <= 3. The cmesh must not be committed before calling this function. +* `array`:\\[in\\] The [`t8_shmem_array`](@ref) to search in. +* `value`:\\[in\\] The value to search for. +* `size`:\\[in\\] The number of elements in the array. +* `compare`:\\[in\\] A function that compares an element of the array with the value. +# Returns +The index of the element in *array* that matches *value*. ### Prototype ```c -void t8_cmesh_set_dimension (t8_cmesh_t cmesh, int dim); +int t8_shmem_array_binary_search (t8_shmem_array_t array, const t8_gloidx_t value, const int size, int (*compare) (t8_shmem_array_t, const int, const t8_gloidx_t)); ``` """ -function t8_cmesh_set_dimension(cmesh, dim) - @ccall libt8.t8_cmesh_set_dimension(cmesh::t8_cmesh_t, dim::Cint)::Cvoid +function t8_shmem_array_binary_search(array, value, size, compare) + @ccall libt8.t8_shmem_array_binary_search(array::t8_shmem_array_t, value::t8_gloidx_t, size::Cint, compare::Ptr{Cvoid})::Cint end """ - t8_eclass + t8_load_mode -This enumeration contains all possible element classes. +This enumeration contains all modes in which we can open a saved cmesh. The cmesh can be loaded with more processes than it was saved and the mode controls, which of the processes open files and distribute the data. -| Enumerator | Note | -| :--------------------- | :----------------------------------------------------------------------------------------------------------------- | -| T8\\_ECLASS\\_ZERO | Zero-dimensional element class. | -| T8\\_ECLASS\\_VERTEX | The vertex is the only zero-dimensional element class. | -| T8\\_ECLASS\\_LINE | The line is the only one-dimensional element class. | -| T8\\_ECLASS\\_QUAD | The quadrilateral is one of two element classes in two dimensions. | -| T8\\_ECLASS\\_TRIANGLE | The element class for a triangle. | -| T8\\_ECLASS\\_HEX | The hexahedron is one three-dimensional element class. | -| T8\\_ECLASS\\_TET | The tetrahedron is another three-dimensional element class. | -| T8\\_ECLASS\\_PRISM | The prism has five sides: two opposing triangles joined by three quadrilaterals. | -| T8\\_ECLASS\\_PYRAMID | The pyramid has a quadrilateral as base and four triangles as sides. | -| T8\\_ECLASS\\_COUNT | This is no element class but can be used as the number of element classes. | -| T8\\_ECLASS\\_INVALID | This is no element class but can be used for the case a class of a third party library is not supported by t8code | +| Enumerator | Note | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| T8\\_LOAD\\_FIRST | First mode. | +| T8\\_LOAD\\_SIMPLE | In simple mode, the first n processes load the file | +| T8\\_LOAD\\_BGQ | In BGQ mode, the file is loaded on n nodes and from one process of each node. This needs MPI Version 3.1 or higher. | +| T8\\_LOAD\\_STRIDE | Every n-th process loads a file. Handle with care, we introduce it, since on Juqueen MPI-3 was not available. The parameter n has to be passed as an extra parameter. # See also [`t8_cmesh_load_and_distribute`](@ref) | +| T8\\_LOAD\\_COUNT | Number of modes in which we can open a saved cmesh. | """ -@cenum t8_eclass::UInt32 begin - T8_ECLASS_ZERO = 0 - T8_ECLASS_VERTEX = 0 - T8_ECLASS_LINE = 1 - T8_ECLASS_QUAD = 2 - T8_ECLASS_TRIANGLE = 3 - T8_ECLASS_HEX = 4 - T8_ECLASS_TET = 5 - T8_ECLASS_PRISM = 6 - T8_ECLASS_PYRAMID = 7 - T8_ECLASS_COUNT = 8 - T8_ECLASS_INVALID = 9 +@cenum t8_load_mode::UInt32 begin + T8_LOAD_FIRST = 0 + T8_LOAD_SIMPLE = 0 + T8_LOAD_BGQ = 1 + T8_LOAD_STRIDE = 2 + T8_LOAD_COUNT = 3 end -"""This enumeration contains all possible element classes.""" -const t8_eclass_t = t8_eclass +"""This enumeration contains all modes in which we can open a saved cmesh. The cmesh can be loaded with more processes than it was saved and the mode controls, which of the processes open files and distribute the data.""" +const t8_load_mode_t = t8_load_mode """ - t8_cmesh_set_tree_class(cmesh, gtree_id, tree_class) + t8_eclass_count_boundary(theclass, min_dim, per_eclass) -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. +Query the element class and count of boundary points. # Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `gtree_id`:\\[in\\] The global number of the tree. -* `tree_class`:\\[in\\] The element class of this tree. +* `theclass`:\\[in\\] We query a point of this element class. +* `min_dim`:\\[in\\] Ignore boundary points of lesser dimension. The ignored points get a count value of 0. +* `per_eclass`:\\[out\\] Array of length T8\\_ECLASS\\_COUNT to be filled with the count of the boundary objects, counted per each of the element classes. +# Returns +The count over all boundary points. ### Prototype ```c -void t8_cmesh_set_tree_class (t8_cmesh_t cmesh, t8_gloidx_t gtree_id, t8_eclass_t tree_class); +int t8_eclass_count_boundary (t8_eclass_t theclass, int min_dim, int *per_eclass); ``` """ -function t8_cmesh_set_tree_class(cmesh, gtree_id, tree_class) - @ccall libt8.t8_cmesh_set_tree_class(cmesh::t8_cmesh_t, gtree_id::t8_gloidx_t, tree_class::t8_eclass_t)::Cvoid +function t8_eclass_count_boundary(theclass, min_dim, per_eclass) + @ccall libt8.t8_eclass_count_boundary(theclass::t8_eclass_t, min_dim::Cint, per_eclass::Ptr{Cint})::Cint end """ - t8_cmesh_set_attribute(cmesh, gtree_id, package_id, key, data, data_size, 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 integer key, where each application can use any integer as key. - -!!! note + t8_eclass_compare(eclass1, eclass2) - If an attribute with the given package\\_id and key already exists, then it will get overwritten. +Compare two eclasses of the same dimension as necessary for face neighbor orientation. The implemented order is Triangle < Square in 2D and Tet < Hex < Prism < Pyramid in 3D. # Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `gtree_id`:\\[in\\] The global id of the tree. -* `package_id`:\\[in\\] Unique identifier of a valid software package. -* `key`:\\[in\\] 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. -* `data`:\\[in\\] A pointer to the attribute data. -* `data_size`:\\[in\\] The number of bytes of the attribute. -* `data_persists`:\\[in\\] 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`](@ref). -# See also -[`sc_package_register`](@ref) - +* `eclass1`:\\[in\\] The first eclass to compare. +* `eclass2`:\\[in\\] The second eclass to compare. +# Returns +0 if the eclasses are equal, 1 if eclass1 > eclass2 and -1 if eclass1 < eclass2 ### Prototype ```c -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); +int t8_eclass_compare (t8_eclass_t eclass1, t8_eclass_t eclass2); ``` """ -function t8_cmesh_set_attribute(cmesh, gtree_id, package_id, key, data, data_size, data_persists) - @ccall libt8.t8_cmesh_set_attribute(cmesh::t8_cmesh_t, gtree_id::t8_gloidx_t, package_id::Cint, key::Cint, data::Ptr{Cvoid}, data_size::Csize_t, data_persists::Cint)::Cvoid +function t8_eclass_compare(eclass1, eclass2) + @ccall libt8.t8_eclass_compare(eclass1::t8_eclass_t, eclass2::t8_eclass_t)::Cint end """ - t8_cmesh_set_attribute_string(cmesh, gtree_id, package_id, key, string) - -Store a string as an attribute at a tree in a cmesh. - -!!! note - - You can also use t8_cmesh_set_attribute, but we recommend using this specialized function for strings. - -!!! note + t8_eclass_is_valid(eclass) - If an attribute with the given package\\_id and key already exists, then it will get overwritten. +Check whether a class is a valid class. Returns non-zero if it is a valid class, returns zero, if the class is equal to T8\\_ECLASS\\_INVALID. # Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `gtree_id`:\\[in\\] The global id of the tree. -* `package_id`:\\[in\\] Unique identifier of a valid software package. -* `key`:\\[in\\] 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. -* `string`:\\[in\\] The string to store as attribute. -# See also -[`sc_package_register`](@ref) - +* `eclass`:\\[in\\] The eclass to check. +# Returns +Non-zero if *eclass* is valid, zero otherwise. ### Prototype ```c -void t8_cmesh_set_attribute_string (t8_cmesh_t cmesh, t8_gloidx_t gtree_id, int package_id, int key, const char *string); +int t8_eclass_is_valid (t8_eclass_t eclass); ``` """ -function t8_cmesh_set_attribute_string(cmesh, gtree_id, package_id, key, string) - @ccall libt8.t8_cmesh_set_attribute_string(cmesh::t8_cmesh_t, gtree_id::t8_gloidx_t, package_id::Cint, key::Cint, string::Cstring)::Cvoid +function t8_eclass_is_valid(eclass) + @ccall libt8.t8_eclass_is_valid(eclass::t8_eclass_t)::Cint end """ - t8_cmesh_set_attribute_gloidx_array(cmesh, gtree_id, package_id, key, data, data_count, data_persists) - -Store an array of [`t8_gloidx_t`](@ref) as an attribute at a tree in a cmesh. - -!!! note - - You can also use t8_cmesh_set_attribute, but we recommend using this specialized function for arrays. + t8_element_shape_num_faces(element_shape) -!!! note - - If an attribute with the given package\\_id and key already exists, then it will get overwritten. - -!!! note - - We do not store the number of data entries *data_count* of the attribute array. You can keep track of the data count yourself by using another attribute. - -# Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `gtree_id`:\\[in\\] The global id of the tree. -* `package_id`:\\[in\\] Unique identifier of a valid software package. -* `key`:\\[in\\] 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. -* `data`:\\[in\\] The array to store as attribute. -* `data_count`:\\[in\\] The number of entries in *data*. -* `data_persists`:\\[in\\] 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`](@ref). -# See also -[`sc_package_register`](@ref) +The number of codimension-one boundaries of an element class. ### Prototype ```c -void t8_cmesh_set_attribute_gloidx_array (t8_cmesh_t cmesh, t8_gloidx_t gtree_id, int package_id, int key, const t8_gloidx_t *data, const size_t data_count, int data_persists); +int t8_element_shape_num_faces (int element_shape); ``` """ -function t8_cmesh_set_attribute_gloidx_array(cmesh, gtree_id, package_id, key, data, data_count, data_persists) - @ccall libt8.t8_cmesh_set_attribute_gloidx_array(cmesh::t8_cmesh_t, gtree_id::t8_gloidx_t, package_id::Cint, key::Cint, data::Ptr{t8_gloidx_t}, data_count::Csize_t, data_persists::Cint)::Cvoid +function t8_element_shape_num_faces(element_shape) + @ccall libt8.t8_element_shape_num_faces(element_shape::Cint)::Cint end """ - t8_cmesh_set_join(cmesh, gtree1, gtree2, face1, face2, orientation) - -Insert a face-connection between two trees in a cmesh. - -!!! note + t8_element_shape_max_num_faces(element_shape) - The orientation is defined as: Let my\\_face and other\\_face be the two face numbers of the connecting trees. We chose a main\\_face from them as follows: Either both trees have the same element class, then the face with the lower face number is the main\\_face or the trees belong to different classes in which case the face belonging to the tree with the lower class according to the ordering triangle < quad, hex < tet < prism < pyramid, is the main\\_face. Then face corner 0 of the main\\_face connects to a face corner k in the other face. The face orientation is defined as the number k. If the classes are equal and my\\_face == other\\_face, treating either of both faces as the main\\_face leads to the same result. See https://arxiv.org/pdf/1611.02929.pdf for more details. +For each dimension the maximum possible number of faces of an element\\_shape of that dimension. -# Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `gtree1`:\\[in\\] The tree id of the first of the two trees. -* `gtree2`:\\[in\\] The tree id of the second of the two trees. -* `face1`:\\[in\\] The face number of the first tree. -* `face2`:\\[in\\] The face number of the second tree. -* `orientation`:\\[in\\] Specify how face1 and face2 are oriented to each other ### Prototype ```c -void t8_cmesh_set_join (t8_cmesh_t cmesh, t8_gloidx_t gtree1, t8_gloidx_t gtree2, int face1, int face2, int orientation); +int t8_element_shape_max_num_faces (int element_shape); ``` """ -function t8_cmesh_set_join(cmesh, gtree1, gtree2, face1, face2, orientation) - @ccall libt8.t8_cmesh_set_join(cmesh::t8_cmesh_t, gtree1::t8_gloidx_t, gtree2::t8_gloidx_t, face1::Cint, face2::Cint, orientation::Cint)::Cvoid +function t8_element_shape_max_num_faces(element_shape) + @ccall libt8.t8_element_shape_max_num_faces(element_shape::Cint)::Cint end """ - t8_cmesh_set_profiling(cmesh, set_profiling) - -Enable or disable profiling for a cmesh. If profiling is enabled, runtimes and statistics are collected during cmesh\\_commit. - -Profiling is disabled by default. The cmesh must not be committed before calling this function. + t8_element_shape_num_vertices(element_shape) -# Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `set_profiling`:\\[in\\] If true, profiling will be enabled, if false disabled. -# See also -[`t8_cmesh_print_profile`](@ref) +The number of vertices of an element class. ### Prototype ```c -void t8_cmesh_set_profiling (t8_cmesh_t cmesh, int set_profiling); +int t8_element_shape_num_vertices (int element_shape); ``` """ -function t8_cmesh_set_profiling(cmesh, set_profiling) - @ccall libt8.t8_cmesh_set_profiling(cmesh::t8_cmesh_t, set_profiling::Cint)::Cvoid +function t8_element_shape_num_vertices(element_shape) + @ccall libt8.t8_element_shape_num_vertices(element_shape::Cint)::Cint end """ - t8_cmesh_is_equal(cmesh_a, cmesh_b) + t8_element_shape_vtk_type(element_shape) -Check whether two given cmeshes carry the same information. +The vtk cell type for the element\\_shape -# Arguments -* `cmesh_a`:\\[in\\] The first of the two cmeshes to be checked. -* `cmesh_b`:\\[in\\] 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. ### Prototype ```c -int t8_cmesh_is_equal (t8_cmesh_t cmesh_a, t8_cmesh_t cmesh_b); +int t8_element_shape_vtk_type (int element_shape); ``` """ -function t8_cmesh_is_equal(cmesh_a, cmesh_b) - @ccall libt8.t8_cmesh_is_equal(cmesh_a::t8_cmesh_t, cmesh_b::t8_cmesh_t)::Cint +function t8_element_shape_vtk_type(element_shape) + @ccall libt8.t8_element_shape_vtk_type(element_shape::Cint)::Cint end """ - t8_cmesh_is_empty(cmesh) + t8_element_shape_t8_to_vtk_corner_number(element_shape, index) -Check whether a cmesh is empty on all processes. +Maps the t8code corner number of the element to the vtk corner number # Arguments -* `cmesh`:\\[in\\] A committed cmesh. +* `element_shape`:\\[in\\] The shape of the element. +* `index`:\\[in\\] The index of the corner in z-order (t8code numeration). # Returns -True (non-zero) if and only if the cmesh has trees at all. -### Prototype -```c -int t8_cmesh_is_empty (t8_cmesh_t cmesh); -``` -""" -function t8_cmesh_is_empty(cmesh) - @ccall libt8.t8_cmesh_is_empty(cmesh::t8_cmesh_t)::Cint -end - -""" - t8_cmesh_bcast(cmesh_in, root, comm) - +The corresponding vtk index. ### Prototype ```c -t8_cmesh_t t8_cmesh_bcast (t8_cmesh_t cmesh_in, int root, sc_MPI_Comm comm); +int t8_element_shape_t8_to_vtk_corner_number (int element_shape, int index); ``` """ -function t8_cmesh_bcast(cmesh_in, root, comm) - @ccall libt8.t8_cmesh_bcast(cmesh_in::t8_cmesh_t, root::Cint, comm::MPI_Comm)::t8_cmesh_t +function t8_element_shape_t8_to_vtk_corner_number(element_shape, index) + @ccall libt8.t8_element_shape_t8_to_vtk_corner_number(element_shape::Cint, index::Cint)::Cint end -mutable struct t8_geometry end - -"""This typedef holds virtual functions for a particular geometry. We need it so that we can use [`t8_geometry_c`](@ref) pointers in .c files without them seeing the actual C++ code (and then not compiling)""" -const t8_geometry_c = t8_geometry - """ - t8_cmesh_register_geometry(cmesh, geometry) - -Register a geometry in the cmesh. The cmesh takes ownership of the geometry. - -If no geometry is registered and cmesh is modified from another cmesh then the other cmesh's geometries are used. - -!!! note + t8_element_shape_t8_corner_number(element_shape, index) - If you need to use t8_cmesh_bcast, then all geometries must be registered *after* the bcast operation, not before. +Maps the vtk corner number of the element to the t8code corner number # Arguments -* `cmesh`:\\[in,out\\] The cmesh. -* `geometry`:\\[in\\] The geometry to register. +* `element_shape`:\\[in\\] The shape of the element. +* `index`:\\[in\\] The index of the corner in vtk ordering. +# Returns +The corresponding t8code index. ### Prototype ```c -void t8_cmesh_register_geometry (t8_cmesh_t cmesh, t8_geometry_c *geometry); +int t8_element_shape_t8_corner_number (int element_shape, int index); ``` """ -function t8_cmesh_register_geometry(cmesh, geometry) - @ccall libt8.t8_cmesh_register_geometry(cmesh::t8_cmesh_t, geometry::Ptr{t8_geometry_c})::Cvoid +function t8_element_shape_t8_corner_number(element_shape, index) + @ccall libt8.t8_element_shape_t8_corner_number(element_shape::Cint, index::Cint)::Cint end """ - t8_cmesh_set_tree_geometry(cmesh, gtreeid, geom) + t8_element_shape_to_string(element_shape) -Set the geometry for a tree, thus specify which geometry to use for this tree. +For each element\\_shape, the name of this class as a string -# Arguments -* `cmesh`:\\[in\\] A non-committed cmesh. -* `gtreeid`:\\[in\\] A global tree id in *cmesh*. -* `geom`:\\[in\\] The geometry to use for this tree. See also t8_cmesh_get_tree_geometry ### Prototype ```c -void t8_cmesh_set_tree_geometry (t8_cmesh_t cmesh, t8_gloidx_t gtreeid, const t8_geometry_c *geom); +const char* t8_element_shape_to_string (int element_shape); ``` """ -function t8_cmesh_set_tree_geometry(cmesh, gtreeid, geom) - @ccall libt8.t8_cmesh_set_tree_geometry(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t, geom::Ptr{t8_geometry_c})::Cvoid +function t8_element_shape_to_string(element_shape) + @ccall libt8.t8_element_shape_to_string(element_shape::Cint)::Cstring end """ - t8_cmesh_commit(cmesh, comm) + t8_element_shape_compare(element_shape1, element_shape2) + +Compare two element\\_shapes of the same dimension as necessary for face neighbor orientation. The implemented order is Triangle < Square in 2D and Tet < Hex < Prism < Pyramid in 3D. +# Arguments +* `element_shape1`:\\[in\\] The first element\\_shape to compare. +* `element_shape2`:\\[in\\] The second element\\_shape to compare. +# Returns +0 if the element\\_shapes are equal, 1 if element\\_shape1 > element\\_shape2 and -1 if element\\_shape1 < element\\_shape2 ### Prototype ```c -void t8_cmesh_commit (t8_cmesh_t cmesh, sc_MPI_Comm comm); +int t8_element_shape_compare (t8_element_shape_t element_shape1, t8_element_shape_t element_shape2); ``` """ -function t8_cmesh_commit(cmesh, comm) - @ccall libt8.t8_cmesh_commit(cmesh::t8_cmesh_t, comm::MPI_Comm)::Cvoid +function t8_element_shape_compare(element_shape1, element_shape2) + @ccall libt8.t8_element_shape_compare(element_shape1::t8_element_shape_t, element_shape2::t8_element_shape_t)::Cint end -""" - t8_cmesh_save(cmesh, fileprefix) +mutable struct t8_element end -Save the cmesh to a file with the given fileprefix. +"""Opaque structure for a generic element, only used as pointer. Implementations are free to cast it to their internal data structure.""" +const t8_element_t = t8_element -!!! note +mutable struct t8_scheme end - IMPORTANT: Currently, this functionality is deactivated, because it is outdated. Calling it will thus result in an error. +"""The scheme holds implementations for one or more element classes. Opaque pointer for C interface. Detailed documentation at t8_scheme.""" +const t8_scheme_c = t8_scheme -!!! note +""" + t8_scheme_ref(scheme) - So far, it was only legal to save cmeshes that use the linear geometry. +Increase the reference counter of a scheme. # Arguments -* `cmesh`:\\[in\\] The cmesh to save. -* `fileprefix`:\\[in\\] The prefix of the file to save the cmesh to. +* `scheme`:\\[in,out\\] On input, this scheme must be alive, that is, exist with positive reference count. ### Prototype ```c -int t8_cmesh_save (t8_cmesh_t cmesh, const char *fileprefix); +void t8_scheme_ref (t8_scheme_c *scheme); ``` """ -function t8_cmesh_save(cmesh, fileprefix) - @ccall libt8.t8_cmesh_save(cmesh::t8_cmesh_t, fileprefix::Cstring)::Cint +function t8_scheme_ref(scheme) + @ccall libt8.t8_scheme_ref(scheme::Ptr{t8_scheme_c})::Cvoid end """ - t8_cmesh_load(filename, comm) + t8_scheme_unref(pscheme) + +Decrease the reference counter of a scheme. If the counter reaches zero, this scheme is destroyed. +# Arguments +* `pscheme`:\\[in,out\\] On input, the scheme pointed to must exist with positive reference count. If the reference count reaches zero, the scheme is destroyed and this pointer set to NULL. Otherwise, the pointer is not changed and the scheme is not modified in other ways. ### Prototype ```c -t8_cmesh_t t8_cmesh_load (const char *filename, sc_MPI_Comm comm); +void t8_scheme_unref (t8_scheme_c **pscheme); ``` """ -function t8_cmesh_load(filename, comm) - @ccall libt8.t8_cmesh_load(filename::Cstring, comm::MPI_Comm)::t8_cmesh_t +function t8_scheme_unref(pscheme) + @ccall libt8.t8_scheme_unref(pscheme::Ptr{Ptr{t8_scheme_c}})::Cvoid end """ - t8_cmesh_load_and_distribute(fileprefix, num_files, comm, mode, procs_per_node) + t8_element_get_element_size(scheme, tree_class) + +Return the size of any element of a given class. +# Returns +The size of an element of class **ts**. We provide a default implementation of this routine that should suffice for most use cases. ### Prototype ```c -t8_cmesh_t t8_cmesh_load_and_distribute (const char *fileprefix, int num_files, sc_MPI_Comm comm, t8_load_mode_t mode, int procs_per_node); +size_t t8_element_get_element_size (const t8_scheme_c *scheme, const t8_eclass_t tree_class); ``` """ -function t8_cmesh_load_and_distribute(fileprefix, num_files, comm, mode, procs_per_node) - @ccall libt8.t8_cmesh_load_and_distribute(fileprefix::Cstring, num_files::Cint, comm::MPI_Comm, mode::t8_load_mode_t, procs_per_node::Cint)::t8_cmesh_t +function t8_element_get_element_size(scheme, tree_class) + @ccall libt8.t8_element_get_element_size(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Csize_t end """ - t8_cmesh_comm_is_valid(cmesh, comm) + t8_element_refines_irregular(scheme, tree_class) + +Returns true, if there is one element in the tree, that does not refine into 2^dim children. Returns false otherwise. ### Prototype ```c -int t8_cmesh_comm_is_valid (t8_cmesh_t cmesh, sc_MPI_Comm comm); +int t8_element_refines_irregular (const t8_scheme_c *scheme, const t8_eclass_t tree_class); ``` """ -function t8_cmesh_comm_is_valid(cmesh, comm) - @ccall libt8.t8_cmesh_comm_is_valid(cmesh::t8_cmesh_t, comm::MPI_Comm)::Cint +function t8_element_refines_irregular(scheme, tree_class) + @ccall libt8.t8_element_refines_irregular(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Cint end """ - t8_cmesh_is_partitioned(cmesh) + t8_element_get_maxlevel(scheme, tree_class) -Query whether a committed cmesh is partitioned or replicated. +Return the maximum allowed level for any element of a given class. # Arguments -* `cmesh`:\\[in\\] A committed cmesh. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. # Returns -True if *cmesh* is partitioned. False otherwise. *cmesh* must be committed before calling this function. +The maximum allowed level for elements of class **ts**. ### Prototype ```c -int t8_cmesh_is_partitioned (t8_cmesh_t cmesh); +int t8_element_get_maxlevel (const t8_scheme_c *scheme, const t8_eclass_t tree_class); ``` """ -function t8_cmesh_is_partitioned(cmesh) - @ccall libt8.t8_cmesh_is_partitioned(cmesh::t8_cmesh_t)::Cint +function t8_element_get_maxlevel(scheme, tree_class) + @ccall libt8.t8_element_get_maxlevel(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Cint end """ - t8_cmesh_get_dimension(cmesh) + t8_element_get_level(scheme, tree_class, element) -Get the dimension of a cmesh. +Return the level of an element. # Arguments -* `cmesh`:\\[in\\] The cmesh. *cmesh* must be committed before calling this function. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. +# Returns +The level of *element*. ### Prototype ```c -int t8_cmesh_get_dimension (const t8_cmesh_t cmesh); +int t8_element_get_level (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); ``` """ -function t8_cmesh_get_dimension(cmesh) - @ccall libt8.t8_cmesh_get_dimension(cmesh::t8_cmesh_t)::Cint +function t8_element_get_level(scheme, tree_class, element) + @ccall libt8.t8_element_get_level(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint end """ - t8_cmesh_get_num_trees(cmesh) + t8_element_copy(scheme, tree_class, source, dest) -Return the global number of trees in a cmesh. +Copy all entries of **source** to **dest**. **dest** must be an existing element. No memory is allocated by this function. -# Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -# Returns -The number of trees associated to *cmesh*. *cmesh* must be committed before calling this function. +!!! note + + *source* and *dest* may point to the same element. + +# Arguments +* `scheme`:\\[in\\] Implementation of a class scheme. +* `tree_class`:\\[in\\] The eclass of the current tree. +* `source`:\\[in\\] The element whose entries will be copied to **dest**. +* `dest`:\\[in,out\\] This element's entries will be overwritten with the entries of **source**. ### Prototype ```c -t8_gloidx_t t8_cmesh_get_num_trees (t8_cmesh_t cmesh); +void t8_element_copy (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *source, t8_element_t *dest); ``` """ -function t8_cmesh_get_num_trees(cmesh) - @ccall libt8.t8_cmesh_get_num_trees(cmesh::t8_cmesh_t)::t8_gloidx_t +function t8_element_copy(scheme, tree_class, source, dest) + @ccall libt8.t8_element_copy(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, source::Ptr{t8_element_t}, dest::Ptr{t8_element_t})::Cvoid end """ - t8_cmesh_get_num_local_trees(cmesh) + t8_element_compare(scheme, tree_class, elem1, elem2) -Return the number of local trees of a cmesh. If the cmesh is not partitioned this is equivalent to t8_cmesh_get_num_trees. +Compare two elements with respect to the scheme. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `elem1`:\\[in\\] The first element. +* `elem2`:\\[in\\] The second element. # Returns -The number of local trees of the cmesh. *cmesh* must be committed before calling this function. +negative if elem1 < elem2, zero if elem1 equals elem2 and positive if elem1 > elem2. If elem2 is a copy of elem1 then the elements are equal. ### Prototype ```c -t8_locidx_t t8_cmesh_get_num_local_trees (t8_cmesh_t cmesh); +int t8_element_compare (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *elem1, const t8_element_t *elem2); ``` """ -function t8_cmesh_get_num_local_trees(cmesh) - @ccall libt8.t8_cmesh_get_num_local_trees(cmesh::t8_cmesh_t)::t8_locidx_t +function t8_element_compare(scheme, tree_class, elem1, elem2) + @ccall libt8.t8_element_compare(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem1::Ptr{t8_element_t}, elem2::Ptr{t8_element_t})::Cint end """ - t8_cmesh_get_num_ghosts(cmesh) + t8_element_is_equal(scheme, tree_class, elem1, elem2) -Return the number of ghost trees of a cmesh. If the cmesh is not partitioned this is equivalent to t8_cmesh_get_num_trees. +Check if two elements are equal. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `elem1`:\\[in\\] The first element. +* `elem2`:\\[in\\] The second element. # Returns -The number of ghost trees of the cmesh. *cmesh* must be committed before calling this function. +1 if the elements are equal, 0 if they are not equal ### Prototype ```c -t8_locidx_t t8_cmesh_get_num_ghosts (t8_cmesh_t cmesh); +int t8_element_is_equal (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *elem1, const t8_element_t *elem2); ``` """ -function t8_cmesh_get_num_ghosts(cmesh) - @ccall libt8.t8_cmesh_get_num_ghosts(cmesh::t8_cmesh_t)::t8_locidx_t +function t8_element_is_equal(scheme, tree_class, elem1, elem2) + @ccall libt8.t8_element_is_equal(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem1::Ptr{t8_element_t}, elem2::Ptr{t8_element_t})::Cint end """ - t8_cmesh_get_first_treeid(cmesh) + element_is_refinable(scheme, tree_class, element) -Return the global index of the first local tree of a cmesh. If the cmesh is not partitioned this is always 0. +Indicates if an element is refinable. Possible reasons for being not refinable could be that the element has reached its max level. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element to check. # Returns -The global id of the first local tree in cmesh. *cmesh* must be committed before calling this function. +1 if the element is refinable, 0 otherwise. ### Prototype ```c -t8_gloidx_t t8_cmesh_get_first_treeid (t8_cmesh_t cmesh); +int element_is_refinable (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); ``` """ -function t8_cmesh_get_first_treeid(cmesh) - @ccall libt8.t8_cmesh_get_first_treeid(cmesh::t8_cmesh_t)::t8_gloidx_t +function element_is_refinable(scheme, tree_class, element) + @ccall libt8.element_is_refinable(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint end """ - t8_cmesh_get_tree_geometry(cmesh, gtreeid) + t8_element_get_parent(scheme, tree_class, element, parent) -Get the geometry of a tree. +Compute the parent of a given element **element** and store it in **parent**. **parent** needs to be an existing element. No memory is allocated by this function. **element** and **parent** can point to the same element, then the entries of **element** are overwritten by the ones of its parent. # Arguments -* `cmesh`:\\[in\\] The cmesh. -* `gtreeid`:\\[in\\] The global tree id of the tree for which the geometry should be returned. -# Returns -The geometry of the tree. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element whose parent will be computed. +* `parent`:\\[in,out\\] This element's entries will be overwritten by those of **element**'s parent. The storage for this element must exist and match the element class of the parent. ### Prototype ```c -const t8_geometry_c * t8_cmesh_get_tree_geometry (t8_cmesh_t cmesh, t8_gloidx_t gtreeid); +void t8_element_get_parent (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, t8_element_t *parent); ``` """ -function t8_cmesh_get_tree_geometry(cmesh, gtreeid) - @ccall libt8.t8_cmesh_get_tree_geometry(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t)::Ptr{t8_geometry_c} +function t8_element_get_parent(scheme, tree_class, element, parent) + @ccall libt8.t8_element_get_parent(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, parent::Ptr{t8_element_t})::Cvoid end """ - t8_cmesh_treeid_is_local_tree(cmesh, ltreeid) + t8_element_get_num_siblings(scheme, tree_class, element) -Query whether a given [`t8_locidx_t`](@ref) belongs to a local tree of a cmesh. +Compute the number of siblings of an element. That is the number of Children of its parent. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -* `ltreeid`:\\[in\\] An (possible) tree index. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. # Returns -True if *ltreeid* matches the range of local trees of *cmesh*. False if not. *cmesh* must be committed before calling this function. +The number of siblings of *element*. Note that this number is >= 1, since we count the element itself as a sibling. ### Prototype ```c -int t8_cmesh_treeid_is_local_tree (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid); +int t8_element_get_num_siblings (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); ``` """ -function t8_cmesh_treeid_is_local_tree(cmesh, ltreeid) - @ccall libt8.t8_cmesh_treeid_is_local_tree(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t)::Cint +function t8_element_get_num_siblings(scheme, tree_class, element) + @ccall libt8.t8_element_get_num_siblings(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint end """ - t8_cmesh_treeid_is_ghost(cmesh, ltreeid) + t8_element_get_sibling(scheme, tree_class, elem, sibid, sibling) -Query whether a given [`t8_locidx_t`](@ref) belongs to a ghost of a cmesh. +Compute a specific sibling of a given element **element** and store it in **sibling**. **sibling** needs to be an existing element. No memory is allocated by this function. **element** and **sibling** can point to the same element, then the entries of **element** are overwritten by the ones of its i-th sibling. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -* `ltreeid`:\\[in\\] 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. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `elem`:\\[in\\] The element whose sibling will be computed. +* `sibid`:\\[in\\] The id of the sibling computed. +* `sibling`:\\[in,out\\] This element's entries will be overwritten by those of **element**'s sibid-th sibling. The storage for this element must exist and match the element class of the sibling. ### Prototype ```c -int t8_cmesh_treeid_is_ghost (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid); +void t8_element_get_sibling (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *elem, const int sibid, t8_element_t *sibling); ``` """ -function t8_cmesh_treeid_is_ghost(cmesh, ltreeid) - @ccall libt8.t8_cmesh_treeid_is_ghost(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t)::Cint +function t8_element_get_sibling(scheme, tree_class, elem, sibid, sibling) + @ccall libt8.t8_element_get_sibling(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem::Ptr{t8_element_t}, sibid::Cint, sibling::Ptr{t8_element_t})::Cvoid end """ - t8_cmesh_ltreeid_to_ghostid(cmesh, ltreeid) + t8_element_get_num_corners(scheme, tree_class, element) -Given a local tree id that belongs to a ghost, return the index of the ghost. +Compute the number of corners of an element. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -* `ltreeid`:\\[in\\] The local id of a ghost, satisfying t8_cmesh_treeid_is_ghost, thus num\\_trees <= *ltreeid* < num\\_trees + num\\_ghosts +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. # Returns -The index of the ghost within all ghosts, thus an index 0 <= index < num\\_ghosts *cmesh* must be committed before calling this function. +The number of corners of *element*. ### Prototype ```c -t8_locidx_t t8_cmesh_ltreeid_to_ghostid (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid); +int t8_element_get_num_corners (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); ``` """ -function t8_cmesh_ltreeid_to_ghostid(cmesh, ltreeid) - @ccall libt8.t8_cmesh_ltreeid_to_ghostid(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t)::t8_locidx_t +function t8_element_get_num_corners(scheme, tree_class, element) + @ccall libt8.t8_element_get_num_corners(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint end """ - t8_cmesh_get_first_tree(cmesh) + t8_element_get_num_faces(scheme, tree_class, element) -Return a pointer to the first local tree in a cmesh. +Compute the number of faces of an element. # Arguments -* `cmesh`:\\[in\\] The cmesh to be queried. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. # 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. +The number of faces of *element*. ### Prototype ```c -t8_ctree_t t8_cmesh_get_first_tree (t8_cmesh_t cmesh); +int t8_element_get_num_faces (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); ``` """ -function t8_cmesh_get_first_tree(cmesh) - @ccall libt8.t8_cmesh_get_first_tree(cmesh::t8_cmesh_t)::t8_ctree_t +function t8_element_get_num_faces(scheme, tree_class, element) + @ccall libt8.t8_element_get_num_faces(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint end """ - t8_cmesh_get_next_tree(cmesh, tree) + t8_element_get_max_num_faces(scheme, tree_class, element) -Given a local tree in a cmesh return a pointer to the next local tree. +Compute the maximum number of faces of a given element and all of its descendants. # Arguments -* `cmesh`:\\[in\\] The cmesh to be queried. -* `tree`:\\[in\\] A local tree in *cmesh*. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. # 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. +The number of faces of *element*. ### Prototype ```c -t8_ctree_t t8_cmesh_get_next_tree (t8_cmesh_t cmesh, t8_ctree_t tree); +int t8_element_get_max_num_faces (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); ``` """ -function t8_cmesh_get_next_tree(cmesh, tree) - @ccall libt8.t8_cmesh_get_next_tree(cmesh::t8_cmesh_t, tree::t8_ctree_t)::t8_ctree_t +function t8_element_get_max_num_faces(scheme, tree_class, element) + @ccall libt8.t8_element_get_max_num_faces(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint end """ - t8_cmesh_get_tree(cmesh, ltree_id) + t8_element_get_num_children(scheme, tree_class, element) -Return a pointer to a given local tree. +Compute the number of children of an element when it is refined. # Arguments -* `cmesh`:\\[in\\] The cmesh to be queried. -* `ltree_id`:\\[in\\] The local id of the tree that is asked for. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. # 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. +The number of children of *element*. ### Prototype ```c -t8_ctree_t t8_cmesh_get_tree (t8_cmesh_t cmesh, t8_locidx_t ltree_id); +int t8_element_get_num_children (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); ``` """ -function t8_cmesh_get_tree(cmesh, ltree_id) - @ccall libt8.t8_cmesh_get_tree(cmesh::t8_cmesh_t, ltree_id::t8_locidx_t)::t8_ctree_t +function t8_element_get_num_children(scheme, tree_class, element) + @ccall libt8.t8_element_get_num_children(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint end """ - t8_cmesh_get_tree_class(cmesh, ltree_id) + t8_get_max_num_children(scheme, tree_class) -Return the eclass of a given local tree. TODO: Should we refer to indices or consequently use ctree\\_t? +Return the max number of children of an eclass. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -* `ltree_id`:\\[in\\] The local id of the tree whose eclass will be returned. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. # 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. +The max number of children of *element*. ### Prototype ```c -t8_eclass_t t8_cmesh_get_tree_class (t8_cmesh_t cmesh, t8_locidx_t ltree_id); +int t8_get_max_num_children (const t8_scheme_c *scheme, const t8_eclass_t tree_class); ``` """ -function t8_cmesh_get_tree_class(cmesh, ltree_id) - @ccall libt8.t8_cmesh_get_tree_class(cmesh::t8_cmesh_t, ltree_id::t8_locidx_t)::t8_eclass_t +function t8_get_max_num_children(scheme, tree_class) + @ccall libt8.t8_get_max_num_children(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Cint end """ - t8_cmesh_tree_face_is_boundary(cmesh, ltree_id, face) + t8_element_get_num_face_children(scheme, tree_class, element, face) -Query whether a face of a local tree or ghost is at the domain boundary. +Compute the number of children of an element's face when the element is refined. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -* `ltree_id`:\\[in\\] The local id of a tree. -* `face`:\\[in\\] The number of a face of the tree. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. +* `face`:\\[in\\] A face of *element*. # Returns -True if the face is at the domain boundary. False otherwise. *cmesh* must be committed before calling this function. +The number of children of *face* if *element* is to be refined. ### Prototype ```c -int t8_cmesh_tree_face_is_boundary (t8_cmesh_t cmesh, t8_locidx_t ltree_id, int face); +int t8_element_get_num_face_children (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face); ``` """ -function t8_cmesh_tree_face_is_boundary(cmesh, ltree_id, face) - @ccall libt8.t8_cmesh_tree_face_is_boundary(cmesh::t8_cmesh_t, ltree_id::t8_locidx_t, face::Cint)::Cint +function t8_element_get_num_face_children(scheme, tree_class, element, face) + @ccall libt8.t8_element_get_num_face_children(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint)::Cint end """ - t8_cmesh_get_ghost_class(cmesh, lghost_id) + t8_element_get_face_corner(scheme, tree_class, element, face, corner) -Return the eclass of a given local ghost. TODO: Should we refer to indices or consequently use cghost\\_t? +Return the corner number of an element's face corner. Example quad: 2 x --- x 3 | | | | face 1 0 x --- x 1 Thus for face = 1 the output is: corner=0 : 1, corner=1: 3 + +The order in which the corners must be given is determined by the eclass of *element*: LINE/QUAD/TRIANGLE: No specific order. HEX : In Z-order of the face starting with the lowest corner number. TET : Starting with the lowest corner number counterclockwise as seen from 'outside' of the element. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -* `lghost_id`:\\[in\\] The local id of the ghost whose eclass will be returned. 0 <= *tree_id* < cmesh.num\\_ghosts. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. +* `face`:\\[in\\] A face index for *element*. +* `corner`:\\[in\\] A corner index for the face 0 <= *corner* < num\\_face\\_corners. # Returns -The eclass of the given ghost. *cmesh* must be committed before calling this function. +The corner number of the *corner*-th vertex of *face*. ### Prototype ```c -t8_eclass_t t8_cmesh_get_ghost_class (t8_cmesh_t cmesh, t8_locidx_t lghost_id); +int t8_element_get_face_corner (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face, const int corner); ``` """ -function t8_cmesh_get_ghost_class(cmesh, lghost_id) - @ccall libt8.t8_cmesh_get_ghost_class(cmesh::t8_cmesh_t, lghost_id::t8_locidx_t)::t8_eclass_t +function t8_element_get_face_corner(scheme, tree_class, element, face, corner) + @ccall libt8.t8_element_get_face_corner(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint, corner::Cint)::Cint end """ - t8_cmesh_get_global_id(cmesh, local_id) + t8_element_get_corner_face(scheme, tree_class, element, corner, face) -Return the global id of a given local tree or ghost. +Compute the face numbers of the faces sharing an element's corner. Example quad: 2 x --- x 3 | | | | face 1 0 x --- x 1 face 2 Thus for corner = 1 the output is: face=0 : 2, face=1: 1 # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -* `local_id`:\\[in\\] The local id of a tree or a ghost. If *local_id* < cmesh.num\\_local\\_trees then it is a tree, otherwise a ghost. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. +* `corner`:\\[in\\] A corner index for the face. +* `face`:\\[in\\] A face index for *corner*. # 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. - +The face number of the *face*-th face at *corner*. ### Prototype ```c -t8_gloidx_t t8_cmesh_get_global_id (t8_cmesh_t cmesh, t8_locidx_t local_id); +int t8_element_get_corner_face (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int corner, const int face); ``` """ -function t8_cmesh_get_global_id(cmesh, local_id) - @ccall libt8.t8_cmesh_get_global_id(cmesh::t8_cmesh_t, local_id::t8_locidx_t)::t8_gloidx_t +function t8_element_get_corner_face(scheme, tree_class, element, corner, face) + @ccall libt8.t8_element_get_corner_face(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, corner::Cint, face::Cint)::Cint end """ - t8_cmesh_get_local_id(cmesh, global_id) + t8_element_get_child(scheme, tree_class, element, childid, child) -Return the local id of a give global tree. +Construct the child element of a given number. # Arguments -* `cmesh`:\\[in\\] The cmesh. -* `global_id`:\\[in\\] 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. - +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] This must be a valid element, bigger than maxlevel. +* `childid`:\\[in\\] The number of the child to construct. +* `child`:\\[in,out\\] The storage for this element must exist. On output, a valid element. It is valid to call this function with element = child. ### Prototype ```c -t8_locidx_t t8_cmesh_get_local_id (t8_cmesh_t cmesh, t8_gloidx_t global_id); +void t8_element_get_child (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int childid, t8_element_t *child); ``` """ -function t8_cmesh_get_local_id(cmesh, global_id) - @ccall libt8.t8_cmesh_get_local_id(cmesh::t8_cmesh_t, global_id::t8_gloidx_t)::t8_locidx_t +function t8_element_get_child(scheme, tree_class, element, childid, child) + @ccall libt8.t8_element_get_child(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, childid::Cint, child::Ptr{t8_element_t})::Cvoid end """ - t8_cmesh_get_face_neighbor(cmesh, ltreeid, face, dual_face, orientation) - -Given a local tree id and a face number, get information about the face neighbor tree. - -!!! note + t8_element_get_children(scheme, tree_class, element, length, c) - 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 +Construct all children of a given element. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -* `ltreeid`:\\[in\\] The local id of a tree or a ghost. -* `face`:\\[in\\] A face number of the tree/ghost. -* `dual_face`:\\[out\\] If not NULL, the face number of the neighbor tree at this connection. -* `orientation`:\\[out\\] 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. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] This must be a valid element, bigger than maxlevel. +* `length`:\\[in\\] The length of the output array *c* must match the number of children. +* `c`:\\[in,out\\] The storage for these *length* elements must exist and match the element class in the children's ordering. On output, all children are valid. It is valid to call this function with element = c[0]. # See also -[`t8_cmesh_tree_face_is_boundary`](@ref). +t8\\_element\\_num\\_children ### Prototype ```c -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); +void t8_element_get_children (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int length, t8_element_t *c[]); ``` """ -function t8_cmesh_get_face_neighbor(cmesh, ltreeid, face, dual_face, orientation) - @ccall libt8.t8_cmesh_get_face_neighbor(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t, face::Cint, dual_face::Ptr{Cint}, orientation::Ptr{Cint})::t8_locidx_t +function t8_element_get_children(scheme, tree_class, element, length, c) + @ccall libt8.t8_element_get_children(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, length::Cint, c::Ptr{Ptr{t8_element_t}})::Cvoid end """ - t8_cmesh_get_tree_face_neighbor_eclass(cmesh, ltreeid, face) + t8_element_get_child_id(scheme, tree_class, element) -Given a local tree id (of a local tree or ghost tree) and a face compute the eclass of the tree's face neighbor. +Compute the child id of an element. # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -* `ltreeid`:\\[in\\] The local id of a tree or a ghost. -* `face`:\\[in\\] A face number of the tree/ghost. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] This must be a valid element. # Returns -The eclass of a neighbor tree of *ltreeid* across *face*. T8\\_ECLASS\\_INVALID if no neighbor exists. +The child id of element. ### Prototype ```c -t8_eclass_t t8_cmesh_get_tree_face_neighbor_eclass (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid, const int face); +int t8_element_get_child_id (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); ``` """ -function t8_cmesh_get_tree_face_neighbor_eclass(cmesh, ltreeid, face) - @ccall libt8.t8_cmesh_get_tree_face_neighbor_eclass(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t, face::Cint)::t8_eclass_t +function t8_element_get_child_id(scheme, tree_class, element) + @ccall libt8.t8_element_get_child_id(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint end """ - t8_cmesh_print_profile(cmesh) - -Print the collected statistics from a cmesh profile. + t8_element_get_ancestor_id(scheme, tree_class, element, level) -*cmesh* must be committed before calling this function. +Compute the ancestor id of an element, that is the child id at a given level. # Arguments -* `cmesh`:\\[in\\] The cmesh. -# See also -[`t8_cmesh_set_profiling`](@ref) - +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] This must be a valid element. +* `level`:\\[in\\] A refinement level. Must satisfy *level* < element.level +# Returns +The child\\_id of *element* in regard to its *level* ancestor. ### Prototype ```c -void t8_cmesh_print_profile (t8_cmesh_t cmesh); +int t8_element_get_ancestor_id (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int level); ``` """ -function t8_cmesh_print_profile(cmesh) - @ccall libt8.t8_cmesh_print_profile(cmesh::t8_cmesh_t)::Cvoid +function t8_element_get_ancestor_id(scheme, tree_class, element, level) + @ccall libt8.t8_element_get_ancestor_id(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, level::Cint)::Cint end """ - t8_cmesh_get_tree_vertices(cmesh, ltreeid) + t8_elements_are_family(scheme, tree_class, fam) -Return a pointer to the vertex coordinates of a tree. +Query whether a given set of elements is a family or not. # Arguments -* `cmesh`:\\[in\\] The cmesh. -* `ltreeid`:\\[in\\] The id of a local tree. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `fam`:\\[in\\] An array of as many elements as an element of class **scheme** has children. # Returns -If stored, a pointer to the vertex coordinates of *tree*. If no coordinates for this tree are found, NULL. +Zero if **fam** is not a family, nonzero if it is. ### Prototype ```c -double * t8_cmesh_get_tree_vertices (t8_cmesh_t cmesh, t8_locidx_t ltreeid); +int t8_elements_are_family (const t8_scheme_c *scheme, const t8_eclass_t tree_class, t8_element_t *const *fam); ``` """ -function t8_cmesh_get_tree_vertices(cmesh, ltreeid) - @ccall libt8.t8_cmesh_get_tree_vertices(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t)::Ptr{Cdouble} +function t8_elements_are_family(scheme, tree_class, fam) + @ccall libt8.t8_elements_are_family(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, fam::Ptr{Ptr{t8_element_t}})::Cint end """ - t8_cmesh_get_attribute(cmesh, package_id, key, ltree_id) - -Return the attribute pointer of a tree. - -!!! note + t8_element_get_nca(scheme, tree_class, elem1, elem2, nca) - *cmesh* must be committed before calling this function. +Compute the nearest common ancestor of two elements. That is, the element with highest level that still has both given elements as descendants. # Arguments -* `cmesh`:\\[in\\] The cmesh. -* `package_id`:\\[in\\] The identifier of a valid software package. -* `key`:\\[in\\] A key used to identify the attribute under all attributes of this tree with the same *package_id*. -* `ltree_id`:\\[in\\] The local number of the tree. -# Returns -The attribute pointer of the tree *ltree_id* or NULL if the attribute is not found. -# See also -[`sc_package_register`](@ref), [`t8_cmesh_set_attribute`](@ref) - +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `elem1`:\\[in\\] The first of the two input elements. +* `elem2`:\\[in\\] The second of the two input elements. +* `nca`:\\[in,out\\] The storage for this element must exist and match the element class of the child. On output the unique nearest common ancestor of **elem1** and **elem2**. ### Prototype ```c -void * t8_cmesh_get_attribute (const t8_cmesh_t cmesh, const int package_id, const int key, const t8_locidx_t ltree_id); +void t8_element_get_nca (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *elem1, const t8_element_t *elem2, t8_element_t *nca); ``` """ -function t8_cmesh_get_attribute(cmesh, package_id, key, ltree_id) - @ccall libt8.t8_cmesh_get_attribute(cmesh::t8_cmesh_t, package_id::Cint, key::Cint, ltree_id::t8_locidx_t)::Ptr{Cvoid} +function t8_element_get_nca(scheme, tree_class, elem1, elem2, nca) + @ccall libt8.t8_element_get_nca(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem1::Ptr{t8_element_t}, elem2::Ptr{t8_element_t}, nca::Ptr{t8_element_t})::Cvoid end """ - t8_cmesh_get_attribute_gloidx_array(cmesh, package_id, key, ltree_id, data_count) - -Return the attribute pointer of a tree for a gloidx\\_t array. - -!!! note - - *cmesh* must be committed before calling this function. - -!!! note + t8_element_get_face_shape(scheme, tree_class, element, face) - No check is performed whether the attribute actually stored *data_count* many entries since we do not store the number of data entries of the attribute array. You can keep track of the data count yourself by using another attribute. +Compute the shape of the face of an element. # Arguments -* `cmesh`:\\[in\\] The cmesh. -* `package_id`:\\[in\\] The identifier of a valid software package. -* `key`:\\[in\\] A key used to identify the attribute under all attributes of this tree with the same *package_id*. -* `ltree_id`:\\[in\\] The local number of the tree. -* `data_count`:\\[in\\] The number of entries in the array that are requested. This must be smaller or equal to the *data_count* parameter of the corresponding call to t8_cmesh_set_attribute_gloidx_array +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. +* `face`:\\[in\\] A face of *element*. # Returns -The attribute pointer of the tree *ltree_id* or NULL if the attribute is not found. -# See also -[`sc_package_register`](@ref), [`t8_cmesh_set_attribute_gloidx_array`](@ref) - +The element shape of the face. I.e. T8\\_ECLASS\\_LINE for quads, T8\\_ECLASS\\_TRIANGLE for tets and depending on the face number either T8\\_ECLASS\\_QUAD or T8\\_ECLASS\\_TRIANGLE for prisms. ### Prototype ```c -t8_gloidx_t * t8_cmesh_get_attribute_gloidx_array (const t8_cmesh_t cmesh, const int package_id, const int key, const t8_locidx_t ltree_id, const size_t data_count); +t8_element_shape_t t8_element_get_face_shape (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face); ``` """ -function t8_cmesh_get_attribute_gloidx_array(cmesh, package_id, key, ltree_id, data_count) - @ccall libt8.t8_cmesh_get_attribute_gloidx_array(cmesh::t8_cmesh_t, package_id::Cint, key::Cint, ltree_id::t8_locidx_t, data_count::Csize_t)::Ptr{t8_gloidx_t} +function t8_element_get_face_shape(scheme, tree_class, element, face) + @ccall libt8.t8_element_get_face_shape(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint)::t8_element_shape_t end """ - t8_cmesh_get_partition_table(cmesh) + t8_element_get_children_at_face(scheme, tree_class, element, face, children, num_children, child_indices) -Return the shared memory array storing the partition table of a partitioned cmesh. +Given an element and a face of the element, compute all children of the element that touch the face. # Arguments -* `cmesh`:\\[in\\] 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. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. +* `face`:\\[in\\] A face of *element*. +* `children`:\\[in,out\\] Allocated elements, in which the children of *element* that share a face with *face* are stored. They will be stored in order of their linear id. +* `num_children`:\\[in\\] The number of elements in *children*. Must match the number of children that touch *face*. t8_scheme::element_get_num_face_children +* `child_indices`:\\[in,out\\] If not NULL, an array of num\\_children integers must be given, on output its i-th entry is the child\\_id of the i-th face\\_child. It is valid to call this function with element = children[0]. ### Prototype ```c -t8_shmem_array_t t8_cmesh_get_partition_table (t8_cmesh_t cmesh); +void t8_element_get_children_at_face (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face, t8_element_t *children[], const int num_children, int *child_indices); ``` """ -function t8_cmesh_get_partition_table(cmesh) - @ccall libt8.t8_cmesh_get_partition_table(cmesh::t8_cmesh_t)::t8_shmem_array_t +function t8_element_get_children_at_face(scheme, tree_class, element, face, children, num_children, child_indices) + @ccall libt8.t8_element_get_children_at_face(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint, children::Ptr{Ptr{t8_element_t}}, num_children::Cint, child_indices::Ptr{Cint})::Cvoid end """ - t8_cmesh_uniform_bounds_equal_element_count(cmesh, level, tree_scheme, first_local_tree, child_in_tree_begin, last_local_tree, child_in_tree_end, first_tree_shared) + t8_element_face_get_child_face(scheme, tree_class, element, face, face_child) -Calculate the section of a uniform forest for the current rank. +Given a face of an element and a child number of a child of that face, return the face number of the child of the element that matches the child face. + +```c++ + x ---- x x x x ---- x + | | | | | | | <-- f + | | | x | x--x + | | | | | + x ---- x x x ---- x + element face face_child Returns the face number f +``` # Arguments -* `cmesh`:\\[in\\] The cmesh to be considered. -* `level`:\\[in\\] The uniform refinement level to be created. -* `tree_scheme`:\\[in\\] The element scheme for which to compute the bounds. -* `first_local_tree`:\\[out\\] The first tree that contains elements belonging to the calling processor. -* `child_in_tree_begin`:\\[out\\] The tree-local index of the first element belonging to the calling processor. Not computed if NULL. -* `last_local_tree`:\\[out\\] The last tree that contains elements belonging to the calling processor. -* `child_in_tree_end`:\\[out\\] The tree-local index of the first element that does not belonging to the calling processor anymore. Not computed if NULL. -* `first_tree_shared`:\\[out\\] If not NULL, 1 or 0 is stored here depending on whether *first_local_tree* is the same as *last_local_tree* on the previous process. *cmesh* must be committed before calling this function. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. +* `face`:\\[in\\] Then number of the face. +* `face_child`:\\[in\\] A number 0 <= *face_child* < num\\_face\\_children, specifying a child of *element* that shares a face with *face*. These children are counted in linear order. This coincides with the order of children from a call to t8_scheme::element_get_children_at_face. +# Returns +The face number of the face of a child of *element* that coincides with *face_child*. ### Prototype ```c -void t8_cmesh_uniform_bounds_equal_element_count (t8_cmesh_t cmesh, const int level, const t8_scheme_c *tree_scheme, t8_gloidx_t *first_local_tree, t8_gloidx_t *child_in_tree_begin, t8_gloidx_t *last_local_tree, t8_gloidx_t *child_in_tree_end, int8_t *first_tree_shared); +int t8_element_face_get_child_face (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face, const int face_child); ``` """ -function t8_cmesh_uniform_bounds_equal_element_count(cmesh, level, tree_scheme, first_local_tree, child_in_tree_begin, last_local_tree, child_in_tree_end, first_tree_shared) - @ccall libt8.t8_cmesh_uniform_bounds_equal_element_count(cmesh::t8_cmesh_t, level::Cint, tree_scheme::Ptr{t8_scheme_c}, first_local_tree::Ptr{t8_gloidx_t}, child_in_tree_begin::Ptr{t8_gloidx_t}, last_local_tree::Ptr{t8_gloidx_t}, child_in_tree_end::Ptr{t8_gloidx_t}, first_tree_shared::Ptr{Int8})::Cvoid +function t8_element_face_get_child_face(scheme, tree_class, element, face, face_child) + @ccall libt8.t8_element_face_get_child_face(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint, face_child::Cint)::Cint end """ - t8_cmesh_uniform_bounds_for_irregular_refinement(cmesh, level, scheme, first_local_tree, child_in_tree_begin, last_local_tree, child_in_tree_end, first_tree_shared, comm) + t8_element_face_get_parent_face(scheme, tree_class, element, face) + +Given a face of an element return the face number of the parent of the element that matches the element's face. Or return -1 if no face of the parent matches the face. + +!!! note + + For the root element this function always returns *face*. +# Arguments +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. +* `face`:\\[in\\] Then number of the face. +# Returns +If *face* of *element* is also a face of *element*'s parent, the face number of this face. Otherwise -1. ### Prototype ```c -void t8_cmesh_uniform_bounds_for_irregular_refinement (const t8_cmesh_t cmesh, const int level, const t8_scheme_c *scheme, t8_gloidx_t *first_local_tree, t8_gloidx_t *child_in_tree_begin, t8_gloidx_t *last_local_tree, t8_gloidx_t *child_in_tree_end, int8_t *first_tree_shared, sc_MPI_Comm comm); +int t8_element_face_get_parent_face (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face); ``` """ -function t8_cmesh_uniform_bounds_for_irregular_refinement(cmesh, level, scheme, first_local_tree, child_in_tree_begin, last_local_tree, child_in_tree_end, first_tree_shared, comm) - @ccall libt8.t8_cmesh_uniform_bounds_for_irregular_refinement(cmesh::t8_cmesh_t, level::Cint, scheme::Ptr{t8_scheme_c}, first_local_tree::Ptr{t8_gloidx_t}, child_in_tree_begin::Ptr{t8_gloidx_t}, last_local_tree::Ptr{t8_gloidx_t}, child_in_tree_end::Ptr{t8_gloidx_t}, first_tree_shared::Ptr{Int8}, comm::MPI_Comm)::Cvoid +function t8_element_face_get_parent_face(scheme, tree_class, element, face) + @ccall libt8.t8_element_face_get_parent_face(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint)::Cint end """ - t8_cmesh_ref(cmesh) + t8_element_get_tree_face(scheme, tree_class, element, face) -Increase the reference counter of a cmesh. +Given an element and a face of this element. If the face lies on the tree boundary, return the face number of the tree face. If not the return value is arbitrary. # Arguments -* `cmesh`:\\[in,out\\] On input, this cmesh must exist with positive reference count. It may be in any state. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in\\] The element. +* `face`:\\[in\\] The index of a face of *element*. +# Returns +The index of the tree face that *face* is a subface of, if *face* is on a tree boundary. Any arbitrary integer if *is* not at a tree boundary. ### Prototype ```c -void t8_cmesh_ref (t8_cmesh_t cmesh); +int t8_element_get_tree_face (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face); ``` """ -function t8_cmesh_ref(cmesh) - @ccall libt8.t8_cmesh_ref(cmesh::t8_cmesh_t)::Cvoid +function t8_element_get_tree_face(scheme, tree_class, element, face) + @ccall libt8.t8_element_get_tree_face(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint)::Cint end """ - t8_cmesh_unref(pcmesh) + t8_element_transform_face(scheme, tree_class, elem1, elem2, orientation, sign, is_smaller_face) -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. +Suppose we have two trees that share a common face f. Given an element e that is a subface of f in one of the trees and given the orientation of the tree connection, construct the face element of the respective tree neighbor that logically coincides with e but lies in the coordinate system of the neighbor tree. + +!!! note + + *elem1* and *elem2* may point to the same element. # Arguments -* `pcmesh`:\\[in,out\\] 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. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `elem1`:\\[in\\] The face element. +* `elem2`:\\[in,out\\] On return the face element *elem1* with respect to the coordinate system of the other tree. +* `orientation`:\\[in\\] The orientation of the tree-tree connection. +* `sign`:\\[in\\] Depending on the topological orientation of the two tree faces, either 0 (both faces have opposite orientation) or 1 (both faces have the same top. orientation). t8_eclass_face_orientation +* `is_smaller_face`:\\[in\\] Flag to declare whether *elem1* belongs to the smaller face. A face f of tree T is smaller than f' of T' if either the eclass of T is smaller or if the classes are equal and fbytes\\_in and sink->bytes\\_out are updated. +Count how many leaf descendants of a given uniform level the root element will produce. + +This is a convenience function, and can be implemented via t8_element_count_leaves. # Arguments -* `sink`:\\[in,out\\] The sink object to write to. -* `data`:\\[in\\] Data passed into sink must be non-NULL. -* `bytes_avail`:\\[in\\] Number of data bytes passed in. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `level`:\\[in\\] A refinement level. # Returns -0 on success, nonzero on error. +The value of t8_element_count_leaves if the input element is the root (level 0) element. ### Prototype ```c -int sc_io_sink_write (sc_io_sink_t * sink, const void *data, size_t bytes_avail); +t8_gloidx_t t8_element_count_leaves_from_root (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const int level); ``` """ -function sc_io_sink_write(sink, data, bytes_avail) - @ccall libsc.sc_io_sink_write(sink::Ptr{sc_io_sink_t}, data::Ptr{Cvoid}, bytes_avail::Csize_t)::Cint +function t8_element_count_leaves_from_root(scheme, tree_class, level) + @ccall libt8.t8_element_count_leaves_from_root(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, level::Cint)::t8_gloidx_t end """ - sc_io_sink_complete(sink, bytes_in, bytes_out) + t8_element_to_string(scheme, tree_class, element, debug_string, string_size) -Flush all buffered output data to sink. This function may return SC\\_IO\\_ERROR\\_AGAIN if another write is required. Currently this may happen if BUFFER requires an integer multiple of bytes. If successful, the updated value of bytes read and written is returned in bytes\\_in/out, and the sink status is reset as if the sink had just been created. In particular, the bytes counters are reset to zero. The internal state of the sink is not changed otherwise. It is legal to continue writing to the sink hereafter. The sink actions taken depend on its type. BUFFER, FILEFILE: none. FILENAME: call fclose on sink->file. +Fill a string with readable information about the element # Arguments -* `sink`:\\[in,out\\] The sink object to write to. -* `bytes_in`:\\[in,out\\] Bytes received since the last new or complete call. May be NULL. -* `bytes_out`:\\[in,out\\] Bytes written since the last new or complete call. May be NULL. -# Returns -0 if completed, nonzero on error. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of the current tree. +* `element`:\\[in\\] The element to translate into human-readable information. +* `debug_string`:\\[in,out\\] The string to fill. +* `string_size`:\\[in\\] The length of *debug_string*. ### Prototype ```c -int sc_io_sink_complete (sc_io_sink_t * sink, size_t *bytes_in, size_t *bytes_out); +void t8_element_to_string (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, char *debug_string, const int string_size); ``` """ -function sc_io_sink_complete(sink, bytes_in, bytes_out) - @ccall libsc.sc_io_sink_complete(sink::Ptr{sc_io_sink_t}, bytes_in::Ptr{Csize_t}, bytes_out::Ptr{Csize_t})::Cint +function t8_element_to_string(scheme, tree_class, element, debug_string, string_size) + @ccall libt8.t8_element_to_string(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, debug_string::Cstring, string_size::Cint)::Cvoid end """ - sc_io_sink_align(sink, bytes_align) + t8_element_new(scheme, tree_class, length, elems) -Align sink to a byte boundary by writing zeros. +Allocate memory for an array of elements of a given class and initialize them. + +!!! note + + Not every element that is created in t8code will be created by a call to this function. However, if an element is not created using t8_element_new, then it is guaranteed that t8_scheme::element_init is called on it. + +!!! note + + In debugging mode, an element that was created with t8_element_new must pass t8_element_is_valid. + +!!! note + + If an element was created by t8_element_new then t8_scheme::element_init may not be called for it. Thus, t8_element_new should initialize an element in the same way as a call to t8_scheme::element_init would. # Arguments -* `sink`:\\[in,out\\] The sink object to align. -* `bytes_align`:\\[in\\] Byte boundary. -# Returns -0 on success, nonzero on error. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `length`:\\[in\\] The number of elements to be allocated. +* `elems`:\\[in,out\\] On input an array of **length** many unallocated element pointers. On output all these pointers will point to an allocated and initialized element. +# See also +[`t8_element_init`](@ref), element\\_is\\_valid + ### Prototype ```c -int sc_io_sink_align (sc_io_sink_t * sink, size_t bytes_align); +void t8_element_new (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const int length, t8_element_t **elems); ``` """ -function sc_io_sink_align(sink, bytes_align) - @ccall libsc.sc_io_sink_align(sink::Ptr{sc_io_sink_t}, bytes_align::Csize_t)::Cint +function t8_element_new(scheme, tree_class, length, elems) + @ccall libt8.t8_element_new(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, length::Cint, elems::Ptr{Ptr{t8_element_t}})::Cvoid end -# automatic type deduction for variadic arguments may not be what you want, please use with caution -@generated function sc_io_source_new(iotype, ioencode, va_list...) - :(@ccall(libsc.sc_io_source_new(iotype::Cint, ioencode::Cint; $(to_c_type_pairs(va_list)...))::Ptr{sc_io_source_t})) - end - """ - sc_io_source_destroy(source) + t8_element_init(scheme, tree_class, length, elem) -Free data source. Calls [`sc_io_source_complete`](@ref) and requires it to return no error. This is to avoid discarding buffered data that has not been passed to read. +Initialize an array of allocated elements. + +!!! note + + In debugging mode, an element that was passed to t8_element_init must pass t8_element_is_valid. + +!!! note + + If an element was created by t8_element_new then t8_element_init may not be called for it. Thus, t8_element_init should initialize an element in the same way as a call to t8_element_new would. + +!!! note + + Every call to # Arguments -* `source`:\\[in,out\\] The source object to free. -# Returns -0 on success. Nonzero if an error is encountered or is\\_complete returns one. +* `scheme`:\\[in\\] The scheme to use. +* `tree_class`:\\[in\\] The eclass of the current tree. +* `length`:\\[in\\] The number of elements to be initialized. +* `elem`:\\[in,out\\] On input an array of *length* many allocated elements. +# See also +[`t8_element_init`](@ref) must be matched by a call to, [`t8_element_deinit`](@ref), [`t8_element_deinit`](@ref), [`t8_element_new`](@ref), t8\\_element\\_is\\_valid + ### Prototype ```c -int sc_io_source_destroy (sc_io_source_t * source); +void t8_element_init (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const int length, t8_element_t *elem); ``` """ -function sc_io_source_destroy(source) - @ccall libsc.sc_io_source_destroy(source::Ptr{sc_io_source_t})::Cint +function t8_element_init(scheme, tree_class, length, elem) + @ccall libt8.t8_element_init(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, length::Cint, elem::Ptr{t8_element_t})::Cvoid end """ - sc_io_source_destroy_null(source) + t8_element_deinit(scheme, tree_class, length, elems) -Free data source and NULL the pointer to it. Except for the handling of the pointer argument, the behavior is the same as for sc_io_source_destroy. +Deinitialize an array of allocated elements. + +!!! note + + Call this function if you called t8_element_init on the element pointers. # Arguments -* `source`:\\[in,out\\] Non-NULL pointer to source pointer. The source pointer may be NULL, in which case this function does nothing successfully, or a valid sc_io_source, which is passed to sc_io_source_destroy, and the source pointer is set to NULL afterwards. -# Returns -0 on success, nonzero on error. +* `scheme`:\\[in\\] The scheme to use. +* `tree_class`:\\[in\\] The eclass of the current tree. +* `length`:\\[in\\] The number of elements to be deinitialized. +* `elems`:\\[in,out\\] On input an array of *length* many allocated and initialized elements, on output an array of *length* many allocated, but not initialized elements. +# See also +[`t8_element_init`](@ref) + ### Prototype ```c -int sc_io_source_destroy_null (sc_io_source_t ** source); +void t8_element_deinit (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const int length, t8_element_t *elems); ``` """ -function sc_io_source_destroy_null(source) - @ccall libsc.sc_io_source_destroy_null(source::Ptr{Ptr{sc_io_source_t}})::Cint +function t8_element_deinit(scheme, tree_class, length, elems) + @ccall libt8.t8_element_deinit(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, length::Cint, elems::Ptr{t8_element_t})::Cvoid end """ - sc_io_source_read(source, data, bytes_avail, bytes_out) + t8_element_destroy(scheme, tree_class, length, elems) -Read data from a source. The internal counters source->bytes\\_in and source->bytes\\_out are updated. Data is read until the data buffer has not enough room anymore, or source becomes empty. It is possible that data already read internally remains in the source object for the next call. Call [`sc_io_source_complete`](@ref) and check its return value to find out. Returns an error if bytes\\_out is NULL and less than bytes\\_avail are read. +Deallocate an array of elements. # Arguments -* `source`:\\[in,out\\] The source object to read from. -* `data`:\\[in\\] Data buffer for reading from source. If NULL the output data will be ignored and we seek forward in the input. -* `bytes_avail`:\\[in\\] Number of bytes available in data buffer. -* `bytes_out`:\\[in,out\\] If not NULL, byte count read into data buffer. Otherwise, requires to read exactly bytes\\_avail. If this condition is not met, return an error. -# Returns -0 on success, nonzero on error. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `length`:\\[in\\] The number of elements in the array. +* `elems`:\\[in,out\\] On input an array of **length** many allocated element pointers. On output all these pointers will be freed. **element** itself will not be freed by this function. ### Prototype ```c -int sc_io_source_read (sc_io_source_t * source, void *data, size_t bytes_avail, size_t *bytes_out); +void t8_element_destroy (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const int length, t8_element_t **elems); ``` """ -function sc_io_source_read(source, data, bytes_avail, bytes_out) - @ccall libsc.sc_io_source_read(source::Ptr{sc_io_source_t}, data::Ptr{Cvoid}, bytes_avail::Csize_t, bytes_out::Ptr{Csize_t})::Cint +function t8_element_destroy(scheme, tree_class, length, elems) + @ccall libt8.t8_element_destroy(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, length::Cint, elems::Ptr{Ptr{t8_element_t}})::Cvoid end """ - sc_io_source_complete(source, bytes_in, bytes_out) + t8_element_set_to_root(scheme, tree_class, element) -Determine whether all data buffered from source has been returned by read. If it returns SC\\_IO\\_ERROR\\_AGAIN, another [`sc_io_source_read`](@ref) is required. If the call returns no error, the internal counters source->bytes\\_in and source->bytes\\_out are returned to the caller if requested, and reset to 0. The internal state of the source is not changed otherwise. It is legal to continue reading from the source hereafter. +Fills an element with the root element. # Arguments -* `source`:\\[in,out\\] The source object to read from. -* `bytes_in`:\\[in,out\\] If not NULL and true is returned, the total size of the data sourced. -* `bytes_out`:\\[in,out\\] If not NULL and true is returned, total bytes passed out by source\\_read. -# Returns -SC\\_IO\\_ERROR\\_AGAIN if buffered data remaining. Otherwise return ERROR\\_NONE and reset counters. +* `scheme`:\\[in\\] The scheme of the forest. +* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `element`:\\[in,out\\] The element to be filled with root. ### Prototype ```c -int sc_io_source_complete (sc_io_source_t * source, size_t *bytes_in, size_t *bytes_out); +void t8_element_set_to_root (const t8_scheme_c *scheme, const t8_eclass_t tree_class, t8_element_t *element); ``` """ -function sc_io_source_complete(source, bytes_in, bytes_out) - @ccall libsc.sc_io_source_complete(source::Ptr{sc_io_source_t}, bytes_in::Ptr{Csize_t}, bytes_out::Ptr{Csize_t})::Cint +function t8_element_set_to_root(scheme, tree_class, element) + @ccall libt8.t8_element_set_to_root(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cvoid end """ - sc_io_source_align(source, bytes_align) - -Align source to a byte boundary by skipping. + t8_element_MPI_Pack(scheme, tree_class, elements, count, send_buffer, buffer_size, position, comm) -# Arguments -* `source`:\\[in,out\\] The source object to align. -* `bytes_align`:\\[in\\] Byte boundary. -# Returns -0 on success, nonzero on error. ### Prototype ```c -int sc_io_source_align (sc_io_source_t * source, size_t bytes_align); +void t8_element_MPI_Pack (const t8_scheme_c *scheme, const t8_eclass_t tree_class, t8_element_t **const elements, const unsigned int count, void *send_buffer, const int buffer_size, int *position, sc_MPI_Comm comm); ``` """ -function sc_io_source_align(source, bytes_align) - @ccall libsc.sc_io_source_align(source::Ptr{sc_io_source_t}, bytes_align::Csize_t)::Cint +function t8_element_MPI_Pack(scheme, tree_class, elements, count, send_buffer, buffer_size, position, comm) + @ccall libt8.t8_element_MPI_Pack(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elements::Ptr{Ptr{t8_element_t}}, count::Cuint, send_buffer::Ptr{Cvoid}, buffer_size::Cint, position::Ptr{Cint}, comm::MPI_Comm)::Cvoid end """ - sc_io_source_activate_mirror(source) + t8_element_MPI_Pack_size(scheme, tree_class, count, comm, pack_size) -Activate a buffer that mirrors (i.e., stores) the data that was read. +### Prototype +```c +void t8_element_MPI_Pack_size (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const unsigned int count, sc_MPI_Comm comm, int *pack_size); +``` +""" +function t8_element_MPI_Pack_size(scheme, tree_class, count, comm, pack_size) + @ccall libt8.t8_element_MPI_Pack_size(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, count::Cuint, comm::MPI_Comm, pack_size::Ptr{Cint})::Cvoid +end + +""" + t8_element_MPI_Unpack(scheme, tree_class, recvbuf, buffer_size, position, elements, count, comm) -# Arguments -* `source`:\\[in,out\\] The source object to activate mirror in. -# Returns -0 on success, nonzero on error. ### Prototype ```c -int sc_io_source_activate_mirror (sc_io_source_t * source); +void t8_element_MPI_Unpack (const t8_scheme_c *scheme, const t8_eclass_t tree_class, void *recvbuf, const int buffer_size, int *position, t8_element_t **elements, const unsigned int count, sc_MPI_Comm comm); ``` """ -function sc_io_source_activate_mirror(source) - @ccall libsc.sc_io_source_activate_mirror(source::Ptr{sc_io_source_t})::Cint +function t8_element_MPI_Unpack(scheme, tree_class, recvbuf, buffer_size, position, elements, count, comm) + @ccall libt8.t8_element_MPI_Unpack(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, recvbuf::Ptr{Cvoid}, buffer_size::Cint, position::Ptr{Cint}, elements::Ptr{Ptr{t8_element_t}}, count::Cuint, comm::MPI_Comm)::Cvoid end +mutable struct t8_cmesh end + +"""Forward pointer reference to hidden cmesh implementation. This reference needs to be known by [`t8_geometry`](@ref), hence we put it before the include.""" +const t8_cmesh_t = Ptr{t8_cmesh} + """ - sc_io_source_read_mirror(source, data, bytes_avail, bytes_out) + sc_refcount_init_invalid(rc) -Read data from the source's mirror. Same behaviour as [`sc_io_source_read`](@ref). +Initialize a well-defined but unusable reference counter. Specifically, we set its package identifier and reference count to -1. To make this reference counter usable, call sc_refcount_init. # Arguments -* `source`:\\[in,out\\] The source object to read mirror data from. -* `data`:\\[in\\] Data buffer for reading from source's mirror. If NULL the output data will be thrown away. -* `bytes_avail`:\\[in\\] Number of bytes available in data buffer. -* `bytes_out`:\\[in,out\\] If not NULL, byte count read into data buffer. Otherwise, requires to read exactly bytes\\_avail. -# Returns -0 on success, nonzero on error. +* `rc`:\\[out\\] This reference counter is defined as invalid. It will return false on both sc_refcount_is_active and sc_refcount_is_last. It can be made valid by calling sc_refcount_init. No other functions must be called on it. ### Prototype ```c -int sc_io_source_read_mirror (sc_io_source_t * source, void *data, size_t bytes_avail, size_t *bytes_out); +void sc_refcount_init_invalid (sc_refcount_t * rc); ``` """ -function sc_io_source_read_mirror(source, data, bytes_avail, bytes_out) - @ccall libsc.sc_io_source_read_mirror(source::Ptr{sc_io_source_t}, data::Ptr{Cvoid}, bytes_avail::Csize_t, bytes_out::Ptr{Csize_t})::Cint +function sc_refcount_init_invalid(rc) + @ccall libsc.sc_refcount_init_invalid(rc::Ptr{sc_refcount_t})::Cvoid end """ - sc_io_file_save(filename, buffer) + sc_refcount_init(rc, package_id) -Save a buffer to a file in one call. This function performs error checking and always returns cleanly. +Initialize a reference counter to 1. It is legal if its status prior to this call is undefined. # Arguments -* `filename`:\\[in\\] Name of the file to save. -* `buffer`:\\[in\\] An array of element size 1 and arbitrary contents, which are written to the file. -# Returns -0 on success, -1 on error. +* `rc`:\\[out\\] This reference counter is initialized to one. The object's contents may be undefined on input. +* `package_id`:\\[in\\] Either -1 or a package registered to libsc. ### Prototype ```c -int sc_io_file_save (const char *filename, sc_array_t * buffer); +void sc_refcount_init (sc_refcount_t * rc, int package_id); ``` """ -function sc_io_file_save(filename, buffer) - @ccall libsc.sc_io_file_save(filename::Cstring, buffer::Ptr{sc_array_t})::Cint +function sc_refcount_init(rc, package_id) + @ccall libsc.sc_refcount_init(rc::Ptr{sc_refcount_t}, package_id::Cint)::Cvoid end """ - sc_io_file_load(filename, buffer) + sc_refcount_new(package_id) -Read a file into a buffer in one call. This function performs error checking and always returns cleanly. +Create a new reference counter with count initialized to 1. Equivalent to calling sc_refcount_init on a newly allocated rc object. # Arguments -* `filename`:\\[in\\] Name of the file to load. -* `buffer`:\\[in,out\\] On input, an array (not a view) of element size 1 and arbitrary contents. On output and success, the complete file contents. On error, contents are undefined. +* `package_id`:\\[in\\] Either -1 or a package registered to libsc. # Returns -0 on success, -1 on error. +A reference counter with count one. ### Prototype ```c -int sc_io_file_load (const char *filename, sc_array_t * buffer); +sc_refcount_t *sc_refcount_new (int package_id); ``` """ -function sc_io_file_load(filename, buffer) - @ccall libsc.sc_io_file_load(filename::Cstring, buffer::Ptr{sc_array_t})::Cint +function sc_refcount_new(package_id) + @ccall libsc.sc_refcount_new(package_id::Cint)::Ptr{sc_refcount_t} end """ - sc_io_encode(data, out) - -Encode a block of arbitrary data with the default sc\\_io format. The corresponding decoder function is sc_io_decode. This function cannot crash unless out of memory. - -Currently this function calls sc_io_encode_zlib with compression level Z\\_BEST\\_COMPRESSION (subject to change). Without zlib configured that function works uncompressed. + sc_refcount_destroy(rc) -The encoding method and input data size can be retrieved, optionally, from the encoded data by sc_io_decode_info. This function decodes the method as a character, which is 'z' for sc_io_encode_zlib. We reserve the characters A-C, d-z indefinitely. +Destroy a reference counter. It must have been counted down to zero before, thus reached an inactive state. # Arguments -* `data`:\\[in,out\\] If *out* is NULL, we work in place. In this case, the array must on input have an element size of 1 byte, which is preserved. After reading all data from this array, it assumes the identity of the *out* argument below. Otherwise, this is a read-only argument that may have arbitrary element size. On input, all data in the array is used. -* `out`:\\[in,out\\] If not NULL, a valid array of element size 1. It must be resizable (not a view). We resize the array to the output data, which always includes a final terminating zero. +* `rc`:\\[in,out\\] This reference counter must have reached count zero. ### Prototype ```c -void sc_io_encode (sc_array_t *data, sc_array_t *out); +void sc_refcount_destroy (sc_refcount_t * rc); ``` """ -function sc_io_encode(data, out) - @ccall libsc.sc_io_encode(data::Ptr{sc_array_t}, out::Ptr{sc_array_t})::Cvoid +function sc_refcount_destroy(rc) + @ccall libsc.sc_refcount_destroy(rc::Ptr{sc_refcount_t})::Cvoid end -""" - sc_io_encode_zlib(data, out, zlib_compression_level, line_break_character) - -Encode a block of arbitrary data, compressed, into an ASCII string. This is a two-stage process: zlib compress and then encode to base 64. The output is a NUL-terminated string of printable characters. - -We first compress the data into the zlib deflate format (RFC 1951). The compressor must use no preset dictionary (this is the default). If zlib is detected on configuration, we compress with the given level. If zlib is not detected, we write data equivalent to Z\\_NO\\_COMPRESSION. The status of zlib detection can be queried at compile time using #ifdef [`SC_HAVE_ZLIB`](@ref) or at run time using sc_have_zlib. Both types of result are readable by a standard zlib uncompress call. +"""We can reuse the reference counter type from libsc.""" +const t8_refcount_t = sc_refcount_t -Secondly, we process the input data size as an 8-byte big-endian number, then the letter 'z', and then the zlib compressed data, concatenated, with a base 64 encoder. We break lines after 76 code characters. Each line break consists of two configurable but arbitrary bytes. The line breaks are considered part of the output data specification. The last line is terminated with the same line break and then a NUL. +""" + t8_refcount_init(rc) -This routine can work in place or write to an output array. The corresponding decoder function is sc_io_decode. This function cannot crash unless out of memory. +Initialize a reference counter to 1. It is legal if its status prior to this call is undefined. # Arguments -* `data`:\\[in,out\\] If *out* is NULL, we work in place. In this case, the array must on input have an element size of 1 byte, which is preserved. After reading all data from this array, it assumes the identity of the *out* argument below. Otherwise, this is a read-only argument that may have arbitrary element size. On input, all data in the array is used. -* `out`:\\[in,out\\] If not NULL, a valid array of element size 1. It must be resizable (not a view). We resize the array to the output data, which always includes a final terminating zero. -* `zlib_compression_level`:\\[in\\] Compression level between 0 (no compression) and 9 (best compression). The value -1 indicates some default level. -* `line_break_character`:\\[in\\] This character is arbitrary and specifies the first of two line break bytes. The second byte is always ''. +* `rc`:\\[out\\] The reference counter is set to one by this call. ### Prototype ```c -void sc_io_encode_zlib (sc_array_t *data, sc_array_t *out, int zlib_compression_level, int line_break_character); +void t8_refcount_init (t8_refcount_t *rc); ``` """ -function sc_io_encode_zlib(data, out, zlib_compression_level, line_break_character) - @ccall libsc.sc_io_encode_zlib(data::Ptr{sc_array_t}, out::Ptr{sc_array_t}, zlib_compression_level::Cint, line_break_character::Cint)::Cvoid +function t8_refcount_init(rc) + @ccall libt8.t8_refcount_init(rc::Ptr{t8_refcount_t})::Cvoid end """ - sc_io_decode_info(data, original_size, format_char, re) - -Decode length and format of original input from encoded data. We expect at least 12 bytes of the format produced by sc_io_encode. No matter how much data has been encoded by it, this much is available. We decode the original data size and the character indicating the format. - -This function does not require zlib. It works with any well-defined data. + t8_refcount_new() -Note that this function is not required before sc_io_decode. Calling this function on any result produced by sc_io_encode will succeed and report a legal format. This function cannot crash. +Create a new reference counter with count initialized to 1. Equivalent to calling [`t8_refcount_init`](@ref) on a newly allocated refcount\\_t. It is mandatory to free this with t8_refcount_destroy. -# Arguments -* `data`:\\[in\\] This must be an array with element size 1. If it contains less than 12 code bytes we error out. It its first 12 bytes do not base 64 decode to 9 bytes we error out. We generally ignore the remaining data. -* `original_size`:\\[out\\] If not NULL and we do not error out, set to the original size as encoded in the data. -* `format_char`:\\[out\\] If not NULL and we do not error out, the ninth character of decoded data indicating the format. -* `re`:\\[in,out\\] Provided for error reporting, presently must be NULL. # Returns -0 on success, negative value on error. +An allocated reference counter whose count has been set to one. ### Prototype ```c -int sc_io_decode_info (sc_array_t *data, size_t *original_size, char *format_char, void *re); +t8_refcount_t * t8_refcount_new (void); ``` """ -function sc_io_decode_info(data, original_size, format_char, re) - @ccall libsc.sc_io_decode_info(data::Ptr{sc_array_t}, original_size::Ptr{Csize_t}, format_char::Cstring, re::Ptr{Cvoid})::Cint +function t8_refcount_new() + @ccall libt8.t8_refcount_new()::Ptr{t8_refcount_t} end """ - sc_io_decode(data, out, max_original_size, re) - -Decode a block of base 64 encoded compressed data. The base 64 data must contain two arbitrary bytes after every 76 code characters and also at the end of the last line if it is short, and then a final NUL character. This function does not require zlib but benefits for speed. - -This is a two-stage process: we decode the input from base 64 first. Then we extract the 8-byte big-endian original data size, the character 'z', and execute a zlib decompression on the remaining decoded data. This function detects malformed input by erroring out. + t8_refcount_destroy(rc) -If we should add another format in the future, the format character may be something else than 'z', as permitted by our specification. To this end, we reserve the characters A-C and d-z indefinitely. - -Any error condition is indicated by a negative return value. Possible causes for error are: - -- the input data string is not NUL-terminated - the first 12 characters of input do not decode properly - the input data is corrupt for decoding or decompression - the output data array has non-unit element size and the length of the output data is not divisible by the size - the output data would exceed the specified threshold - the output array is a view of insufficient length - -We also error out if the data requires a compression dictionary, which would be a violation of above encode format specification. - -The corresponding encode function is sc_io_encode. When passing an array as output, we resize it properly. This function cannot crash unless out of memory. +Destroy a reference counter that we allocated with t8_refcount_new. Its reference count must have decreased to zero. # Arguments -* `data`:\\[in,out\\] If *out* is NULL, we work in place. In that case, output is written into this array after a suitable resize. Either way, we expect a NUL-terminated base 64 encoded string on input that has in turn been obtained by zlib compression. It must be in the exact format produced by sc_io_encode; please see documentation. The element size of the input array must be 1. -* `out`:\\[in,out\\] If not NULL, a valid array (may be a view). If NULL, the input array becomes the output. If the output array is a view and the output data larger than its view size, we error out. We expect commensurable element and data size and resize the output to fit exactly, which restores the original input passed to encoding. An output view array of matching size may be constructed using sc_io_decode_info. -* `max_original_size`:\\[in\\] If nonzero, this is the maximal data size that we will accept after uncompression. If exceeded, return a negative value. -* `re`:\\[in,out\\] Provided for error reporting, presently must be NULL. -# Returns -0 on success, negative on malformed input data or insufficient output space. +* `rc`:\\[in,out\\] Allocated, formerly valid reference counter. ### Prototype ```c -int sc_io_decode (sc_array_t *data, sc_array_t *out, size_t max_original_size, void *re); +void t8_refcount_destroy (t8_refcount_t *rc); ``` """ -function sc_io_decode(data, out, max_original_size, re) - @ccall libsc.sc_io_decode(data::Ptr{sc_array_t}, out::Ptr{sc_array_t}, max_original_size::Csize_t, re::Ptr{Cvoid})::Cint +function t8_refcount_destroy(rc) + @ccall libt8.t8_refcount_destroy(rc::Ptr{t8_refcount_t})::Cvoid end """ - sc_vtk_write_binary(vtkfile, numeric_data, byte_length) + t8_geometry_type -This function writes numeric binary data in VTK base64 encoding. +This enumeration contains all possible geometries. -# Arguments -* `vtkfile`: Stream opened for writing. -* `numeric_data`: A pointer to a numeric data array. -* `byte_length`: The length of the data array in bytes. -# Returns -Returns 0 on success, -1 on file error. -### Prototype -```c -int sc_vtk_write_binary (FILE * vtkfile, char *numeric_data, size_t byte_length); -``` +| Enumerator | Note | +| :--------------------------------------------- | :----------------------------------------------------------------------------------------------- | +| T8\\_GEOMETRY\\_TYPE\\_ZERO | The zero geometry maps all points to zero. | +| T8\\_GEOMETRY\\_TYPE\\_LINEAR | The linear geometry uses linear interpolations to interpolate between the tree vertices. | +| T8\\_GEOMETRY\\_TYPE\\_LINEAR\\_AXIS\\_ALIGNED | The linear, axis aligned geometry uses only 2 vertices, since it is axis aligned. | +| T8\\_GEOMETRY\\_TYPE\\_LAGRANGE | The Lagrange geometry uses a mapping with Lagrange polynomials to approximate curved elements . | +| T8\\_GEOMETRY\\_TYPE\\_ANALYTIC | The analytic geometry uses a user-defined analytic function to map into the physical domain. | +| T8\\_GEOMETRY\\_TYPE\\_CAD | The opencascade geometry uses CAD shapes to map trees exactly to the underlying CAD model. | +| T8\\_GEOMETRY\\_TYPE\\_COUNT | This is no geometry type but can be used as the number of geometry types. | +| T8\\_GEOMETRY\\_TYPE\\_INVALID | This is no geometry type but is used as error type to describe invalid geometries | +| T8\\_GEOMETRY\\_TYPE\\_UNDEFINED | This is no geometry type but is used for every geometry, where no type is defined | """ -function sc_vtk_write_binary(vtkfile, numeric_data, byte_length) - @ccall libsc.sc_vtk_write_binary(vtkfile::Ptr{Libc.FILE}, numeric_data::Cstring, byte_length::Csize_t)::Cint +@cenum t8_geometry_type::UInt32 begin + T8_GEOMETRY_TYPE_ZERO = 0 + T8_GEOMETRY_TYPE_LINEAR = 1 + T8_GEOMETRY_TYPE_LINEAR_AXIS_ALIGNED = 2 + T8_GEOMETRY_TYPE_LAGRANGE = 3 + T8_GEOMETRY_TYPE_ANALYTIC = 4 + T8_GEOMETRY_TYPE_CAD = 5 + T8_GEOMETRY_TYPE_COUNT = 6 + T8_GEOMETRY_TYPE_INVALID = 7 + T8_GEOMETRY_TYPE_UNDEFINED = 8 end +"""This enumeration contains all possible geometries.""" +const t8_geometry_type_t = t8_geometry_type + +mutable struct t8_geometry end + +"""This typedef holds virtual functions for a particular geometry. We need it so that we can use [`t8_geometry_c`](@ref) pointers in .c files without them seeing the actual C++ code (and then not compiling)""" +const t8_geometry_c = t8_geometry + +mutable struct t8_geometry_handler end + +"""This typedef holds virtual functions for the geometry handler. We need it so that we can use [`t8_geometry_handler_c`](@ref) pointers in .c files without them seeing the actual C++ code (and then not compiling) TODO: Delete this when the cmesh is a proper cpp class.""" +const t8_geometry_handler_c = t8_geometry_handler + """ - sc_vtk_write_compressed(vtkfile, numeric_data, byte_length) + t8_geometry_evaluate(cmesh, gtreeid, ref_coords, num_coords, out_coords) -This function writes numeric binary data in VTK compressed format. +Evaluates the geometry of a tree at a given reference point. # Arguments -* `vtkfile`: Stream opened for writing. -* `numeric_data`: A pointer to a numeric data array. -* `byte_length`: The length of the data array in bytes. -# Returns -Returns 0 on success, -1 on file error. +* `cmesh`:\\[in\\] The cmesh +* `gtreeid`:\\[in\\] The global id of the tree +* `ref_coords`:\\[in\\] The reference coordinates at which to evaluate the geometry +* `num_coords`:\\[in\\] The number of reference coordinates +* `out_coords`:\\[out\\] The evaluated coordinates ### Prototype ```c -int sc_vtk_write_compressed (FILE * vtkfile, char *numeric_data, size_t byte_length); +void t8_geometry_evaluate (t8_cmesh_t cmesh, t8_gloidx_t gtreeid, const double *ref_coords, const size_t num_coords, double *out_coords); ``` """ -function sc_vtk_write_compressed(vtkfile, numeric_data, byte_length) - @ccall libsc.sc_vtk_write_compressed(vtkfile::Ptr{Libc.FILE}, numeric_data::Cstring, byte_length::Csize_t)::Cint +function t8_geometry_evaluate(cmesh, gtreeid, ref_coords, num_coords, out_coords) + @ccall libt8.t8_geometry_evaluate(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid end """ - sc_fopen(filename, mode, errmsg) + t8_geometry_jacobian(cmesh, gtreeid, ref_coords, num_coords, jacobian) -Wrapper for fopen(3). We provide an additional argument that contains the error message. +Evaluates the jacobian of a tree at a given reference point. +# Arguments +* `cmesh`:\\[in\\] The cmesh +* `gtreeid`:\\[in\\] The global id of the tree +* `ref_coords`:\\[in\\] The reference coordinates at which to evaluate the jacobian +* `num_coords`:\\[in\\] The number of reference coordinates +* `jacobian`:\\[out\\] The jacobian at the reference coordinates ### Prototype ```c -FILE *sc_fopen (const char *filename, const char *mode, const char *errmsg); +void t8_geometry_jacobian (t8_cmesh_t cmesh, t8_gloidx_t gtreeid, const double *ref_coords, const size_t num_coords, double *jacobian); ``` """ -function sc_fopen(filename, mode, errmsg) - @ccall libsc.sc_fopen(filename::Cstring, mode::Cstring, errmsg::Cstring)::Ptr{Libc.FILE} +function t8_geometry_jacobian(cmesh, gtreeid, ref_coords, num_coords, jacobian) + @ccall libt8.t8_geometry_jacobian(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, jacobian::Ptr{Cdouble})::Cvoid end """ - sc_fwrite(ptr, size, nmemb, file, errmsg) - -Write memory content to a file. - -!!! note + t8_geometry_get_type(cmesh, gtreeid) - This function aborts on file errors. +This function returns the geometry type of a tree. # Arguments -* `ptr`:\\[in\\] Data array to write to disk. -* `size`:\\[in\\] Size of one array member. -* `nmemb`:\\[in\\] Number of array members. -* `file`:\\[in,out\\] File pointer, must be opened for writing. -* `errmsg`:\\[in\\] Error message passed to [`SC_CHECK_ABORT`](@ref). +* `cmesh`:\\[in\\] The cmesh +* `gtreeid`:\\[in\\] The global id of the tree +# Returns +The geometry type of the tree with id *gtreeid* ### Prototype ```c -void sc_fwrite (const void *ptr, size_t size, size_t nmemb, FILE * file, const char *errmsg); +t8_geometry_type_t t8_geometry_get_type (t8_cmesh_t cmesh, t8_gloidx_t gtreeid); ``` """ -function sc_fwrite(ptr, size, nmemb, file, errmsg) - @ccall libsc.sc_fwrite(ptr::Ptr{Cvoid}, size::Csize_t, nmemb::Csize_t, file::Ptr{Libc.FILE}, errmsg::Cstring)::Cvoid +function t8_geometry_get_type(cmesh, gtreeid) + @ccall libt8.t8_geometry_get_type(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t)::t8_geometry_type_t end """ - sc_fread(ptr, size, nmemb, file, errmsg) - -Read file content into memory. - -!!! note + t8_geometry_tree_negative_volume(cmesh, gtreeid) - This function aborts on file errors. +Check if a tree has a negative volume # Arguments -* `ptr`:\\[out\\] Data array to read from disk. -* `size`:\\[in\\] Size of one array member. -* `nmemb`:\\[in\\] Number of array members. -* `file`:\\[in,out\\] File pointer, must be opened for reading. -* `errmsg`:\\[in\\] Error message passed to [`SC_CHECK_ABORT`](@ref). +* `cmesh`:\\[in\\] The cmesh to check +* `gtreeid`:\\[in\\] The global id of the tree +# Returns +True if the tree with id *gtreeid* has a negative volume. False otherwise. ### Prototype ```c -void sc_fread (void *ptr, size_t size, size_t nmemb, FILE * file, const char *errmsg); +int t8_geometry_tree_negative_volume (const t8_cmesh_t cmesh, const t8_gloidx_t gtreeid); ``` """ -function sc_fread(ptr, size, nmemb, file, errmsg) - @ccall libsc.sc_fread(ptr::Ptr{Cvoid}, size::Csize_t, nmemb::Csize_t, file::Ptr{Libc.FILE}, errmsg::Cstring)::Cvoid +function t8_geometry_tree_negative_volume(cmesh, gtreeid) + @ccall libt8.t8_geometry_tree_negative_volume(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t)::Cint end +mutable struct t8_ctree end + +"""Forward pointer references to hidden implementations of tree.""" +const t8_ctree_t = Ptr{t8_ctree} + +mutable struct t8_cghost end + +"""Forward pointer references to hidden implementations of ghost tree.""" +const t8_cghost_t = Ptr{t8_cghost} + """ - sc_fflush_fsync_fclose(file) + t8_cmesh_init(pcmesh) -Best effort to flush a file's data to disc and close it. +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. # Arguments -* `file`:\\[in,out\\] File open for writing. +* `pcmesh`:\\[in,out\\] On input, this pointer must be non-NULL. On return, this pointer set to the new cmesh. ### Prototype ```c -void sc_fflush_fsync_fclose (FILE * file); +void t8_cmesh_init (t8_cmesh_t *pcmesh); ``` """ -function sc_fflush_fsync_fclose(file) - @ccall libsc.sc_fflush_fsync_fclose(file::Ptr{Libc.FILE})::Cvoid +function t8_cmesh_init(pcmesh) + @ccall libt8.t8_cmesh_init(pcmesh::Ptr{t8_cmesh_t})::Cvoid end +# no prototype is found for this function at t8_cmesh.h:79:1, please use with caution """ - sc_io_open(mpicomm, filename, amode, mpiinfo, mpifile) + t8_cmesh_new() + +Allocate a new un-committed cmesh. +# Returns +A pointer to an un-committed [`t8_cmesh`](@ref) structure. ### Prototype ```c -int sc_io_open (sc_MPI_Comm mpicomm, const char *filename, sc_io_open_mode_t amode, sc_MPI_Info mpiinfo, sc_MPI_File * mpifile); +t8_cmesh_t t8_cmesh_new (); ``` """ -function sc_io_open(mpicomm, filename, amode, mpiinfo, mpifile) - @ccall libsc.sc_io_open(mpicomm::MPI_Comm, filename::Cstring, amode::sc_io_open_mode_t, mpiinfo::Cint, mpifile::Ptr{Cint})::Cint +function t8_cmesh_new() + @ccall libt8.t8_cmesh_new()::t8_cmesh_t end """ - sc_io_read_at(mpifile, offset, ptr, count, t, ocount) + t8_cmesh_is_initialized(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. +# Arguments +* `cmesh`:\\[in\\] 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. ### Prototype ```c -int sc_io_read_at (sc_MPI_File mpifile, sc_MPI_Offset offset, void *ptr, int count, sc_MPI_Datatype t, int *ocount); +int t8_cmesh_is_initialized (t8_cmesh_t cmesh); ``` """ -function sc_io_read_at(mpifile, offset, ptr, count, t, ocount) - @ccall libsc.sc_io_read_at(mpifile::MPI_File, offset::Cint, ptr::Ptr{Cvoid}, count::Cint, t::Cint, ocount::Ptr{Cint})::Cint +function t8_cmesh_is_initialized(cmesh) + @ccall libt8.t8_cmesh_is_initialized(cmesh::t8_cmesh_t)::Cint end """ - sc_io_read_at_all(mpifile, offset, ptr, count, t, ocount) + t8_cmesh_is_committed(cmesh) +Check whether a cmesh is not NULL, initialized and committed. In addition, it asserts that the cmesh is consistent as much as possible. + +# Arguments +* `cmesh`:\\[in\\] 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. ### Prototype ```c -int sc_io_read_at_all (sc_MPI_File mpifile, sc_MPI_Offset offset, void *ptr, int count, sc_MPI_Datatype t, int *ocount); +int t8_cmesh_is_committed (const t8_cmesh_t cmesh); ``` """ -function sc_io_read_at_all(mpifile, offset, ptr, count, t, ocount) - @ccall libsc.sc_io_read_at_all(mpifile::MPI_File, offset::Cint, ptr::Ptr{Cvoid}, count::Cint, t::Cint, ocount::Ptr{Cint})::Cint +function t8_cmesh_is_committed(cmesh) + @ccall libt8.t8_cmesh_is_committed(cmesh::t8_cmesh_t)::Cint end """ - sc_io_write_at(mpifile, offset, ptr, count, t, ocount) + t8_cmesh_disable_negative_volume_check(cmesh) + +Disable the debug check for negative volumes in trees during t8_cmesh_commit. Does nothing outside of debug mode. +# Arguments +* `cmesh`:\\[in,out\\] ### Prototype ```c -int sc_io_write_at (sc_MPI_File mpifile, sc_MPI_Offset offset, const void *ptr, int count, sc_MPI_Datatype t, int *ocount); +void t8_cmesh_disable_negative_volume_check (t8_cmesh_t cmesh); ``` """ -function sc_io_write_at(mpifile, offset, ptr, count, t, ocount) - @ccall libsc.sc_io_write_at(mpifile::MPI_File, offset::Cint, ptr::Ptr{Cvoid}, count::Cint, t::Cint, ocount::Ptr{Cint})::Cint +function t8_cmesh_disable_negative_volume_check(cmesh) + @ccall libt8.t8_cmesh_disable_negative_volume_check(cmesh::t8_cmesh_t)::Cvoid end """ - sc_io_write_at_all(mpifile, offset, ptr, count, t, ocount) + t8_cmesh_set_derive(cmesh, 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. +# Arguments +* `cmesh`:\\[in,out\\] Must be initialized, but not committed. May even be NULL to revert to standalone. +* `set_from`:\\[in,out\\] 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. ### Prototype ```c -int sc_io_write_at_all (sc_MPI_File mpifile, sc_MPI_Offset offset, const void *ptr, int count, sc_MPI_Datatype t, int *ocount); +void t8_cmesh_set_derive (t8_cmesh_t cmesh, t8_cmesh_t set_from); ``` """ -function sc_io_write_at_all(mpifile, offset, ptr, count, t, ocount) - @ccall libsc.sc_io_write_at_all(mpifile::MPI_File, offset::Cint, ptr::Ptr{Cvoid}, count::Cint, t::Cint, ocount::Ptr{Cint})::Cint +function t8_cmesh_set_derive(cmesh, set_from) + @ccall libt8.t8_cmesh_set_derive(cmesh::t8_cmesh_t, set_from::t8_cmesh_t)::Cvoid end """ - sc_io_close(file) + t8_cmesh_alloc_offsets(mpisize, comm) ### Prototype ```c -int sc_io_close (sc_MPI_File * file); +t8_shmem_array_t t8_cmesh_alloc_offsets (int mpisize, sc_MPI_Comm comm); ``` """ -function sc_io_close(file) - @ccall libsc.sc_io_close(file::Ptr{Cint})::Cint +function t8_cmesh_alloc_offsets(mpisize, comm) + @ccall libt8.t8_cmesh_alloc_offsets(mpisize::Cint, comm::MPI_Comm)::t8_shmem_array_t end """ - p4est_comm_tag + t8_cmesh_set_partition_range(cmesh, set_face_knowledge, first_local_tree, last_local_tree) -Tags for MPI messages -""" -@cenum p4est_comm_tag::UInt32 begin - P4EST_COMM_TAG_FIRST = 214 - P4EST_COMM_COUNT_PERTREE = 295 - P4EST_COMM_BALANCE_FIRST_COUNT = 296 - P4EST_COMM_BALANCE_FIRST_LOAD = 297 - P4EST_COMM_BALANCE_SECOND_COUNT = 298 - P4EST_COMM_BALANCE_SECOND_LOAD = 299 - P4EST_COMM_PARTITION_GIVEN = 300 - P4EST_COMM_PARTITION_WEIGHTED_LOW = 301 - P4EST_COMM_PARTITION_WEIGHTED_HIGH = 302 - P4EST_COMM_PARTITION_CORRECTION = 303 - P4EST_COMM_GHOST_COUNT = 304 - P4EST_COMM_GHOST_LOAD = 305 - P4EST_COMM_GHOST_EXCHANGE = 306 - P4EST_COMM_GHOST_EXPAND_COUNT = 307 - P4EST_COMM_GHOST_EXPAND_LOAD = 308 - P4EST_COMM_GHOST_SUPPORT_COUNT = 309 - P4EST_COMM_GHOST_SUPPORT_LOAD = 310 - P4EST_COMM_GHOST_CHECKSUM = 311 - P4EST_COMM_NODES_QUERY = 312 - P4EST_COMM_NODES_REPLY = 313 - P4EST_COMM_SAVE = 314 - P4EST_COMM_LNODES_TEST = 315 - P4EST_COMM_LNODES_PASS = 316 - P4EST_COMM_LNODES_OWNED = 317 - P4EST_COMM_LNODES_ALL = 318 - P4EST_COMM_TAG_LAST = 319 -end +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. -"""Tags for MPI messages""" -const p4est_comm_tag_t = p4est_comm_tag +!!! note -""" - p4est_log_indent_push() + A value of *set_face_knowledge* other than -1 or 3 is not yet supported. + +# Arguments +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `set_face_knowledge`:\\[in\\] 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: Do not change the face\\_knowledge level but keep any previously set ones. (Possibly by a previous call to t8_cmesh_set_partition_range) +* `first_local_tree`:\\[in\\] 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. +* `last_local_tree`:\\[in\\] 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`](@ref) ### Prototype ```c -static inline void p4est_log_indent_push (void); +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); ``` """ -function p4est_log_indent_push() - @ccall libp4est.p4est_log_indent_push()::Cvoid +function t8_cmesh_set_partition_range(cmesh, set_face_knowledge, first_local_tree, last_local_tree) + @ccall libt8.t8_cmesh_set_partition_range(cmesh::t8_cmesh_t, set_face_knowledge::Cint, first_local_tree::t8_gloidx_t, last_local_tree::t8_gloidx_t)::Cvoid end """ - p4est_log_indent_pop() + t8_cmesh_set_partition_offsets(cmesh, 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. + +# Arguments +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `tree_offsets`:\\[in\\] An array of global tree\\_id offsets for each process can be specified here. TODO: document flag for shared trees. ### Prototype ```c -static inline void p4est_log_indent_pop (void); +void t8_cmesh_set_partition_offsets (t8_cmesh_t cmesh, t8_shmem_array_t tree_offsets); ``` """ -function p4est_log_indent_pop() - @ccall libp4est.p4est_log_indent_pop()::Cvoid +function t8_cmesh_set_partition_offsets(cmesh, tree_offsets) + @ccall libt8.t8_cmesh_set_partition_offsets(cmesh::t8_cmesh_t, tree_offsets::t8_shmem_array_t)::Cvoid end """ - p4est_init(log_handler, log_threshold) + t8_cmesh_set_partition_uniform(cmesh, element_level, scheme) -Registers p4est with the SC Library and sets the logging behavior. This function is optional. This function must only be called before additional threads are created. If this function is not called or called with log\\_handler == NULL, the default SC log handler will be used. If this function is not called or called with log\\_threshold == [`SC_LP_DEFAULT`](@ref), the default SC log threshold will be used. The default SC log settings can be changed with [`sc_set_log_defaults`](@ref) (). +Declare if a derived cmesh should be partitioned according to a uniform refinement of a given level for the provided scheme. This call is only valid when the cmesh is not yet committed via a call to t8_cmesh_commit and when the cmesh will be derived. +# Arguments +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `element_level`:\\[in\\] The refinement\\_level. +* `scheme`:\\[in\\] The element scheme describing the refinement pattern. We take ownership. This can be prevented by referencing **scheme** before calling this function. ### Prototype ```c -void p4est_init (sc_log_handler_t log_handler, int log_threshold); +void t8_cmesh_set_partition_uniform (t8_cmesh_t cmesh, const int element_level, const t8_scheme_c *scheme); ``` """ -function p4est_init(log_handler, log_threshold) - @ccall libp4est.p4est_init(log_handler::sc_log_handler_t, log_threshold::Cint)::Cvoid +function t8_cmesh_set_partition_uniform(cmesh, element_level, scheme) + @ccall libt8.t8_cmesh_set_partition_uniform(cmesh::t8_cmesh_t, element_level::Cint, scheme::Ptr{t8_scheme_c})::Cvoid end """ - p4est_is_initialized() - -Return whether p4est has been initialized or not. Keep in mind that p4est_init is an optional function but it helps with proper parallel logging. + t8_cmesh_set_refine(cmesh, level, scheme) -Currently there is no inverse to p4est_init, and no way to deinit it. This is ok since initialization generally does no harm. Just do not call libsc's finalize function while p4est is still in use. +Refine the cmesh to a given level. Thus split each tree into x^level subtrees TODO: implement -# Returns -True if p4est has been initialized with a call to p4est_init and false otherwise. ### Prototype ```c -int p4est_is_initialized (void); +void t8_cmesh_set_refine (t8_cmesh_t cmesh, const int level, const t8_scheme_c *scheme); ``` """ -function p4est_is_initialized() - @ccall libp4est.p4est_is_initialized()::Cint +function t8_cmesh_set_refine(cmesh, level, scheme) + @ccall libt8.t8_cmesh_set_refine(cmesh::t8_cmesh_t, level::Cint, scheme::Ptr{t8_scheme_c})::Cvoid end """ - p4est_have_zlib() + t8_cmesh_set_dimension(cmesh, dim) -Check for a sufficiently recent zlib installation. +Set the dimension of a cmesh. If any tree is inserted to the cmesh via [`t8_cmesh_set_tree_class`](@ref), 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 necessary to set the dimension by hand. -# Returns -True if zlib is detected in both sc and p4est. +# Arguments +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `dim`:\\[in\\] The dimension to be set. Must satisfy 0 <= dim <= 3. The cmesh must not be committed before calling this function. ### Prototype ```c -int p4est_have_zlib (void); +void t8_cmesh_set_dimension (t8_cmesh_t cmesh, int dim); ``` """ -function p4est_have_zlib() - @ccall libp4est.p4est_have_zlib()::Cint +function t8_cmesh_set_dimension(cmesh, dim) + @ccall libt8.t8_cmesh_set_dimension(cmesh::t8_cmesh_t, dim::Cint)::Cvoid end """ - p4est_get_package_id() + t8_cmesh_set_tree_class(cmesh, gtree_id, tree_class) -Query the package identity as registered in libsc. +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. -# Returns -This is -1 before p4est_init has been called and a proper package identifier (>= 0) afterwards. +# Arguments +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `gtree_id`:\\[in\\] The global number of the tree. +* `tree_class`:\\[in\\] The element class of this tree. ### Prototype ```c -int p4est_get_package_id (void); +void t8_cmesh_set_tree_class (t8_cmesh_t cmesh, t8_gloidx_t gtree_id, t8_eclass_t tree_class); ``` """ -function p4est_get_package_id() - @ccall libp4est.p4est_get_package_id()::Cint +function t8_cmesh_set_tree_class(cmesh, gtree_id, tree_class) + @ccall libt8.t8_cmesh_set_tree_class(cmesh::t8_cmesh_t, gtree_id::t8_gloidx_t, tree_class::t8_eclass_t)::Cvoid end """ - p4est_topidx_hash2(tt) + t8_cmesh_set_attribute(cmesh, gtree_id, package_id, key, data, data_size, 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 integer key, where each application can use any integer as key. + +!!! note + + If an attribute with the given package\\_id and key already exists, then it will get overwritten. + +# Arguments +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `gtree_id`:\\[in\\] The global id of the tree. +* `package_id`:\\[in\\] Unique identifier of a valid software package. +* `key`:\\[in\\] 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. +* `data`:\\[in\\] A pointer to the attribute data. +* `data_size`:\\[in\\] The number of bytes of the attribute. +* `data_persists`:\\[in\\] 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`](@ref). +# See also +[`sc_package_register`](@ref) ### Prototype ```c -static inline unsigned p4est_topidx_hash2 (const p4est_topidx_t * tt); +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); ``` """ -function p4est_topidx_hash2(tt) - @ccall libp4est.p4est_topidx_hash2(tt::Ptr{p4est_topidx_t})::Cuint +function t8_cmesh_set_attribute(cmesh, gtree_id, package_id, key, data, data_size, data_persists) + @ccall libt8.t8_cmesh_set_attribute(cmesh::t8_cmesh_t, gtree_id::t8_gloidx_t, package_id::Cint, key::Cint, data::Ptr{Cvoid}, data_size::Csize_t, data_persists::Cint)::Cvoid end """ - p4est_topidx_hash3(tt) + t8_cmesh_set_attribute_string(cmesh, gtree_id, package_id, key, string) + +Store a string as an attribute at a tree in a cmesh. + +!!! note + + You can also use t8_cmesh_set_attribute, but we recommend using this specialized function for strings. + +!!! note + + If an attribute with the given package\\_id and key already exists, then it will get overwritten. + +# Arguments +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `gtree_id`:\\[in\\] The global id of the tree. +* `package_id`:\\[in\\] Unique identifier of a valid software package. +* `key`:\\[in\\] 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. +* `string`:\\[in\\] The string to store as attribute. +# See also +[`sc_package_register`](@ref) ### Prototype ```c -static inline unsigned p4est_topidx_hash3 (const p4est_topidx_t * tt); +void t8_cmesh_set_attribute_string (t8_cmesh_t cmesh, t8_gloidx_t gtree_id, int package_id, int key, const char *string); ``` """ -function p4est_topidx_hash3(tt) - @ccall libp4est.p4est_topidx_hash3(tt::Ptr{p4est_topidx_t})::Cuint +function t8_cmesh_set_attribute_string(cmesh, gtree_id, package_id, key, string) + @ccall libt8.t8_cmesh_set_attribute_string(cmesh::t8_cmesh_t, gtree_id::t8_gloidx_t, package_id::Cint, key::Cint, string::Cstring)::Cvoid end """ - p4est_topidx_hash4(tt) + t8_cmesh_set_attribute_gloidx_array(cmesh, gtree_id, package_id, key, data, data_count, data_persists) + +Store an array of [`t8_gloidx_t`](@ref) as an attribute at a tree in a cmesh. + +!!! note + + You can also use t8_cmesh_set_attribute, but we recommend using this specialized function for arrays. + +!!! note + + If an attribute with the given package\\_id and key already exists, then it will get overwritten. + +!!! note + + We do not store the number of data entries *data_count* of the attribute array. You can keep track of the data count yourself by using another attribute. + +# Arguments +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `gtree_id`:\\[in\\] The global id of the tree. +* `package_id`:\\[in\\] Unique identifier of a valid software package. +* `key`:\\[in\\] 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. +* `data`:\\[in\\] The array to store as attribute. +* `data_count`:\\[in\\] The number of entries in *data*. +* `data_persists`:\\[in\\] 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`](@ref). +# See also +[`sc_package_register`](@ref) ### Prototype ```c -static inline unsigned p4est_topidx_hash4 (const p4est_topidx_t * tt); +void t8_cmesh_set_attribute_gloidx_array (t8_cmesh_t cmesh, t8_gloidx_t gtree_id, int package_id, int key, const t8_gloidx_t *data, const size_t data_count, int data_persists); ``` """ -function p4est_topidx_hash4(tt) - @ccall libp4est.p4est_topidx_hash4(tt::Ptr{p4est_topidx_t})::Cuint +function t8_cmesh_set_attribute_gloidx_array(cmesh, gtree_id, package_id, key, data, data_count, data_persists) + @ccall libt8.t8_cmesh_set_attribute_gloidx_array(cmesh::t8_cmesh_t, gtree_id::t8_gloidx_t, package_id::Cint, key::Cint, data::Ptr{t8_gloidx_t}, data_count::Csize_t, data_persists::Cint)::Cvoid end """ - p4est_topidx_is_sorted(t, length) + t8_cmesh_set_join(cmesh, gtree1, gtree2, face1, face2, orientation) + +Insert a face-connection between two trees in a cmesh. + +!!! note + + The orientation is defined as: Let my\\_face and other\\_face be the two face numbers of the connecting trees. We chose a main\\_face from them as follows: Either both trees have the same element class, then the face with the lower face number is the main\\_face or the trees belong to different classes in which case the face belonging to the tree with the lower class according to the ordering triangle < quad, hex < tet < prism < pyramid, is the main\\_face. Then face corner 0 of the main\\_face connects to a face corner k in the other face. The face orientation is defined as the number k. If the classes are equal and my\\_face == other\\_face, treating either of both faces as the main\\_face leads to the same result. See https://arxiv.org/pdf/1611.02929.pdf for more details. +# Arguments +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `gtree1`:\\[in\\] The tree id of the first of the two trees. +* `gtree2`:\\[in\\] The tree id of the second of the two trees. +* `face1`:\\[in\\] The face number of the first tree. +* `face2`:\\[in\\] The face number of the second tree. +* `orientation`:\\[in\\] Specify how face1 and face2 are oriented to each other ### Prototype ```c -static inline int p4est_topidx_is_sorted (p4est_topidx_t * t, int length); +void t8_cmesh_set_join (t8_cmesh_t cmesh, t8_gloidx_t gtree1, t8_gloidx_t gtree2, int face1, int face2, int orientation); ``` """ -function p4est_topidx_is_sorted(t, length) - @ccall libp4est.p4est_topidx_is_sorted(t::Ptr{p4est_topidx_t}, length::Cint)::Cint +function t8_cmesh_set_join(cmesh, gtree1, gtree2, face1, face2, orientation) + @ccall libt8.t8_cmesh_set_join(cmesh::t8_cmesh_t, gtree1::t8_gloidx_t, gtree2::t8_gloidx_t, face1::Cint, face2::Cint, orientation::Cint)::Cvoid end """ - p4est_topidx_bsort(t, length) + t8_cmesh_set_profiling(cmesh, set_profiling) + +Enable or disable profiling for a cmesh. If profiling is enabled, runtimes and statistics are collected during cmesh\\_commit. + +Profiling is disabled by default. The cmesh must not be committed before calling this function. + +# Arguments +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `set_profiling`:\\[in\\] If true, profiling will be enabled, if false disabled. +# See also +[`t8_cmesh_print_profile`](@ref) ### Prototype ```c -static inline void p4est_topidx_bsort (p4est_topidx_t * t, int length); +void t8_cmesh_set_profiling (t8_cmesh_t cmesh, int set_profiling); ``` """ -function p4est_topidx_bsort(t, length) - @ccall libp4est.p4est_topidx_bsort(t::Ptr{p4est_topidx_t}, length::Cint)::Cvoid +function t8_cmesh_set_profiling(cmesh, set_profiling) + @ccall libt8.t8_cmesh_set_profiling(cmesh::t8_cmesh_t, set_profiling::Cint)::Cvoid end """ - p4est_partition_cut_uint64(global_num, p, num_procs) + t8_cmesh_is_equal(cmesh_a, cmesh_b) +Check whether two given cmeshes carry the same information. + +# Arguments +* `cmesh_a`:\\[in\\] The first of the two cmeshes to be checked. +* `cmesh_b`:\\[in\\] 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. ### Prototype ```c -static inline uint64_t p4est_partition_cut_uint64 (uint64_t global_num, int p, int num_procs); +int t8_cmesh_is_equal (t8_cmesh_t cmesh_a, t8_cmesh_t cmesh_b); ``` """ -function p4est_partition_cut_uint64(global_num, p, num_procs) - @ccall libp4est.p4est_partition_cut_uint64(global_num::UInt64, p::Cint, num_procs::Cint)::UInt64 -end +function t8_cmesh_is_equal(cmesh_a, cmesh_b) + @ccall libt8.t8_cmesh_is_equal(cmesh_a::t8_cmesh_t, cmesh_b::t8_cmesh_t)::Cint +end """ - p4est_partition_cut_gloidx(global_num, p, num_procs) + t8_cmesh_is_empty(cmesh) + +Check whether a cmesh is empty on all processes. +# Arguments +* `cmesh`:\\[in\\] A committed cmesh. +# Returns +True (non-zero) if and only if the cmesh has trees at all. ### Prototype ```c -static inline p4est_gloidx_t p4est_partition_cut_gloidx (p4est_gloidx_t global_num, int p, int num_procs); +int t8_cmesh_is_empty (t8_cmesh_t cmesh); ``` """ -function p4est_partition_cut_gloidx(global_num, p, num_procs) - @ccall libp4est.p4est_partition_cut_gloidx(global_num::p4est_gloidx_t, p::Cint, num_procs::Cint)::p4est_gloidx_t +function t8_cmesh_is_empty(cmesh) + @ccall libt8.t8_cmesh_is_empty(cmesh::t8_cmesh_t)::Cint end """ - p4est_version() - -Return the full version of p4est. + t8_cmesh_bcast(cmesh_in, root, comm) -# Returns -Return the version of p4est using the format `VERSION\\_MAJOR.VERSION\\_MINOR.VERSION\\_POINT`, where `VERSION_POINT` can contain dots and characters, e.g. to indicate the additional number of commits and a git commit hash. ### Prototype ```c -const char *p4est_version (void); +t8_cmesh_t t8_cmesh_bcast (t8_cmesh_t cmesh_in, int root, sc_MPI_Comm comm); ``` """ -function p4est_version() - @ccall libp4est.p4est_version()::Cstring +function t8_cmesh_bcast(cmesh_in, root, comm) + @ccall libt8.t8_cmesh_bcast(cmesh_in::t8_cmesh_t, root::Cint, comm::MPI_Comm)::t8_cmesh_t end """ - p4est_version_major() + t8_cmesh_register_geometry(cmesh, geometry) -Return the major version of p4est. +Register a geometry in the cmesh. The cmesh takes ownership of the geometry. -# Returns -Return the major version of p4est. +If no geometry is registered and cmesh is modified from another cmesh then the other cmesh's geometries are used. + +!!! note + + If you need to use t8_cmesh_bcast, then all geometries must be registered *after* the bcast operation, not before. + +# Arguments +* `cmesh`:\\[in,out\\] The cmesh. +* `geometry`:\\[in\\] The geometry to register. ### Prototype ```c -int p4est_version_major (void); +void t8_cmesh_register_geometry (t8_cmesh_t cmesh, t8_geometry_c *geometry); ``` """ -function p4est_version_major() - @ccall libp4est.p4est_version_major()::Cint +function t8_cmesh_register_geometry(cmesh, geometry) + @ccall libt8.t8_cmesh_register_geometry(cmesh::t8_cmesh_t, geometry::Ptr{t8_geometry_c})::Cvoid end """ - p4est_version_minor() + t8_cmesh_set_tree_geometry(cmesh, gtreeid, geom) -Return the minor version of p4est. +Set the geometry for a tree, thus specify which geometry to use for this tree. -# Returns -Return the minor version of p4est. +# Arguments +* `cmesh`:\\[in\\] A non-committed cmesh. +* `gtreeid`:\\[in\\] A global tree id in *cmesh*. +* `geom`:\\[in\\] The geometry to use for this tree. See also t8_cmesh_get_tree_geometry ### Prototype ```c -int p4est_version_minor (void); +void t8_cmesh_set_tree_geometry (t8_cmesh_t cmesh, t8_gloidx_t gtreeid, const t8_geometry_c *geom); ``` """ -function p4est_version_minor() - @ccall libp4est.p4est_version_minor()::Cint +function t8_cmesh_set_tree_geometry(cmesh, gtreeid, geom) + @ccall libt8.t8_cmesh_set_tree_geometry(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t, geom::Ptr{t8_geometry_c})::Cvoid end """ - p4est_connect_type_t - -Characterize a type of adjacency. - -Several functions involve relationships between neighboring trees and/or quadrants, and their behavior depends on how one defines adjacency: 1) entities are adjacent if they share a face, or 2) entities are adjacent if they share a face or corner. [`p4est_connect_type_t`](@ref) is used to choose the desired behavior. This enum must fit into an int8\\_t. + t8_cmesh_commit(cmesh, comm) -| Enumerator | Note | -| :----------------------- | :--------------------------------- | -| P4EST\\_CONNECT\\_SELF | No balance whatsoever. | -| P4EST\\_CONNECT\\_FACE | Balance across faces only. | -| P4EST\\_CONNECT\\_ALMOST | = CORNER - 1. | -| P4EST\\_CONNECT\\_CORNER | Balance across faces and corners. | -| P4EST\\_CONNECT\\_FULL | = CORNER. | +### Prototype +```c +void t8_cmesh_commit (t8_cmesh_t cmesh, sc_MPI_Comm comm); +``` """ -@cenum p4est_connect_type_t::UInt32 begin - P4EST_CONNECT_SELF = 20 - P4EST_CONNECT_FACE = 21 - P4EST_CONNECT_ALMOST = 21 - P4EST_CONNECT_CORNER = 22 - P4EST_CONNECT_FULL = 22 +function t8_cmesh_commit(cmesh, comm) + @ccall libt8.t8_cmesh_commit(cmesh::t8_cmesh_t, comm::MPI_Comm)::Cvoid end """ - p4est_connectivity_encode_t + t8_cmesh_save(cmesh, fileprefix) -Typedef for serialization method. +Save the cmesh to a file with the given fileprefix. -| Enumerator | Note | -| :--------------------------- | :-------------------------------- | -| P4EST\\_CONN\\_ENCODE\\_LAST | Invalid entry to close the list. | -""" -@cenum p4est_connectivity_encode_t::UInt32 begin - P4EST_CONN_ENCODE_NONE = 0 - P4EST_CONN_ENCODE_LAST = 1 -end +!!! note -""" - p4est_connect_type_int(btype) + IMPORTANT: Currently, this functionality is deactivated, because it is outdated. Calling it will thus result in an error. -Convert the [`p4est_connect_type_t`](@ref) into a number. +!!! note + + So far, it was only legal to save cmeshes that use the linear geometry. # Arguments -* `btype`:\\[in\\] The balance type to convert. -# Returns -Returns 1 or 2. +* `cmesh`:\\[in\\] The cmesh to save. +* `fileprefix`:\\[in\\] The prefix of the file to save the cmesh to. ### Prototype ```c -int p4est_connect_type_int (p4est_connect_type_t btype); +int t8_cmesh_save (t8_cmesh_t cmesh, const char *fileprefix); ``` """ -function p4est_connect_type_int(btype) - @ccall libp4est.p4est_connect_type_int(btype::p4est_connect_type_t)::Cint +function t8_cmesh_save(cmesh, fileprefix) + @ccall libt8.t8_cmesh_save(cmesh::t8_cmesh_t, fileprefix::Cstring)::Cint end """ - p4est_connect_type_string(btype) - -Convert the [`p4est_connect_type_t`](@ref) into a const string. + t8_cmesh_load(filename, comm) -# Arguments -* `btype`:\\[in\\] The balance type to convert. -# Returns -Returns a pointer to a constant string. ### Prototype ```c -const char *p4est_connect_type_string (p4est_connect_type_t btype); +t8_cmesh_t t8_cmesh_load (const char *filename, sc_MPI_Comm comm); ``` """ -function p4est_connect_type_string(btype) - @ccall libp4est.p4est_connect_type_string(btype::p4est_connect_type_t)::Cstring +function t8_cmesh_load(filename, comm) + @ccall libt8.t8_cmesh_load(filename::Cstring, comm::MPI_Comm)::t8_cmesh_t end """ - p4est_connectivity - -This structure holds the 2D inter-tree connectivity information. Identification of arbitrary faces and corners is possible. - -The arrays tree\\_to\\_* are stored in z ordering. For corners the order wrt. yx is 00 01 10 11. For faces the order is given by the normal directions -x +x -y +y. Each face has a natural direction by increasing face corner number. Face connections are allocated [0][0]..[0][3]..[num\\_trees-1][0]..[num\\_trees-1][3]. If a face is on the physical boundary it must connect to itself. - -The values for tree\\_to\\_face are 0..7 where ttf % 4 gives the face number and ttf / 4 the face orientation code. The orientation is 0 for faces that are mutually direction-aligned and 1 for faces that are running in opposite directions. - -It is valid to specify num\\_vertices as 0. In this case vertices and tree\\_to\\_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num\\_vertices-1][0]..[num\\_vertices-1][2]. Vertex coordinates are optional and not used for inferring topology. - -The corners are stored when they connect trees that are not already face neighbors at that specific corner. In this case tree\\_to\\_corner indexes into *ctt_offset*. Otherwise the tree\\_to\\_corner entry must be -1 and this corner is ignored. If num\\_corners == 0, tree\\_to\\_corner and corner\\_to\\_* arrays are set to NULL. - -The arrays corner\\_to\\_* store a variable number of entries per corner. For corner c these are at position [ctt\\_offset[c]]..[ctt\\_offset[c+1]-1]. Their number for corner c is ctt\\_offset[c+1] - ctt\\_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner\\_to\\_* arrays is num\\_ctt = ctt\\_offset[num\\_corners]. - -The *\\_to\\_attr arrays may have arbitrary contents defined by the user. We do not interpret them. - -!!! note - - If a connectivity implies natural connections between trees that are corner neighbors without being face neighbors, these corners shall be encoded explicitly in the connectivity. + t8_cmesh_load_and_distribute(fileprefix, num_files, comm, mode, procs_per_node) -| Field | Note | -| :------------------- | :----------------------------------------------------------------------------------- | -| num\\_vertices | the number of vertices that define the *embedding* of the forest (not the topology) | -| num\\_trees | the number of trees | -| num\\_corners | the number of corners that help define topology | -| vertices | an array of size (3 * *num_vertices*) | -| tree\\_to\\_vertex | embed each tree into ```c++ R^3 ``` for e.g. visualization (see p4est\\_vtk.h) | -| tree\\_attr\\_bytes | bytes per tree in tree\\_to\\_attr | -| tree\\_to\\_attr | not touched by p4est | -| tree\\_to\\_tree | (4 * *num_trees*) neighbors across faces | -| tree\\_to\\_face | (4 * *num_trees*) face to face+orientation (see description) | -| tree\\_to\\_corner | (4 * *num_trees*) or NULL (see description) | -| ctt\\_offset | corner to offset in *corner_to_tree* and *corner_to_corner* | -| corner\\_to\\_tree | list of trees that meet at a corner | -| corner\\_to\\_corner | list of tree-corners that meet at a corner | +### Prototype +```c +t8_cmesh_t t8_cmesh_load_and_distribute (const char *fileprefix, int num_files, sc_MPI_Comm comm, t8_load_mode_t mode, int procs_per_node); +``` """ -struct p4est_connectivity - num_vertices::p4est_topidx_t - num_trees::p4est_topidx_t - num_corners::p4est_topidx_t - vertices::Ptr{Cdouble} - tree_to_vertex::Ptr{p4est_topidx_t} - tree_attr_bytes::Csize_t - tree_to_attr::Cstring - tree_to_tree::Ptr{p4est_topidx_t} - tree_to_face::Ptr{Int8} - tree_to_corner::Ptr{p4est_topidx_t} - ctt_offset::Ptr{p4est_topidx_t} - corner_to_tree::Ptr{p4est_topidx_t} - corner_to_corner::Ptr{Int8} +function t8_cmesh_load_and_distribute(fileprefix, num_files, comm, mode, procs_per_node) + @ccall libt8.t8_cmesh_load_and_distribute(fileprefix::Cstring, num_files::Cint, comm::MPI_Comm, mode::t8_load_mode_t, procs_per_node::Cint)::t8_cmesh_t end """ -This structure holds the 2D inter-tree connectivity information. Identification of arbitrary faces and corners is possible. - -The arrays tree\\_to\\_* are stored in z ordering. For corners the order wrt. yx is 00 01 10 11. For faces the order is given by the normal directions -x +x -y +y. Each face has a natural direction by increasing face corner number. Face connections are allocated [0][0]..[0][3]..[num\\_trees-1][0]..[num\\_trees-1][3]. If a face is on the physical boundary it must connect to itself. - -The values for tree\\_to\\_face are 0..7 where ttf % 4 gives the face number and ttf / 4 the face orientation code. The orientation is 0 for faces that are mutually direction-aligned and 1 for faces that are running in opposite directions. - -It is valid to specify num\\_vertices as 0. In this case vertices and tree\\_to\\_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num\\_vertices-1][0]..[num\\_vertices-1][2]. Vertex coordinates are optional and not used for inferring topology. - -The corners are stored when they connect trees that are not already face neighbors at that specific corner. In this case tree\\_to\\_corner indexes into *ctt_offset*. Otherwise the tree\\_to\\_corner entry must be -1 and this corner is ignored. If num\\_corners == 0, tree\\_to\\_corner and corner\\_to\\_* arrays are set to NULL. - -The arrays corner\\_to\\_* store a variable number of entries per corner. For corner c these are at position [ctt\\_offset[c]]..[ctt\\_offset[c+1]-1]. Their number for corner c is ctt\\_offset[c+1] - ctt\\_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner\\_to\\_* arrays is num\\_ctt = ctt\\_offset[num\\_corners]. - -The *\\_to\\_attr arrays may have arbitrary contents defined by the user. We do not interpret them. - -!!! note - - If a connectivity implies natural connections between trees that are corner neighbors without being face neighbors, these corners shall be encoded explicitly in the connectivity. -""" -const p4est_connectivity_t = p4est_connectivity - -""" - p4est_connectivity_shared + t8_cmesh_comm_is_valid(cmesh, comm) -| Field | Note | -| :---- | :--------------------------------------------------------- | -| conn | The members of this connectivity are MPI3 shared windows. | +### Prototype +```c +int t8_cmesh_comm_is_valid (t8_cmesh_t cmesh, sc_MPI_Comm comm); +``` """ -struct p4est_connectivity_shared - conn::Ptr{p4est_connectivity_t} - win_vertices::Cint - win_tree_to_vertex::Cint - win_tree_to_attr::Cint - win_tree_to_tree::Cint - win_tree_to_face::Cint - win_tree_to_corner::Cint - win_ctt_offset::Cint - win_corner_to_tree::Cint - win_corner_to_corner::Cint +function t8_cmesh_comm_is_valid(cmesh, comm) + @ccall libt8.t8_cmesh_comm_is_valid(cmesh::t8_cmesh_t, comm::MPI_Comm)::Cint end -"""Management information for a connectivity shared by MPI3.""" -const p4est_connectivity_shared_t = p4est_connectivity_shared - """ - p4est_connectivity_memory_used(conn) + t8_cmesh_is_partitioned(cmesh) -Calculate memory usage of a connectivity structure. +Query whether a committed cmesh is partitioned or replicated. # Arguments -* `conn`:\\[in\\] Connectivity structure. +* `cmesh`:\\[in\\] A committed cmesh. # Returns -Memory used in bytes. +True if *cmesh* is partitioned. False otherwise. *cmesh* must be committed before calling this function. ### Prototype ```c -size_t p4est_connectivity_memory_used (p4est_connectivity_t * conn); +int t8_cmesh_is_partitioned (t8_cmesh_t cmesh); ``` """ -function p4est_connectivity_memory_used(conn) - @ccall libp4est.p4est_connectivity_memory_used(conn::Ptr{p4est_connectivity_t})::Csize_t +function t8_cmesh_is_partitioned(cmesh) + @ccall libt8.t8_cmesh_is_partitioned(cmesh::t8_cmesh_t)::Cint end """ - p4est_corner_transform_t + t8_cmesh_get_dimension(cmesh) -Generic interface for transformations between a tree and any of its corner +Get the dimension of a cmesh. -| Field | Note | -| :------ | :------------------------ | -| ntree | The number of the tree | -| ncorner | The number of the corner | +# Arguments +* `cmesh`:\\[in\\] The cmesh. *cmesh* must be committed before calling this function. +### Prototype +```c +int t8_cmesh_get_dimension (const t8_cmesh_t cmesh); +``` """ -struct p4est_corner_transform_t - ntree::p4est_topidx_t - ncorner::Int8 +function t8_cmesh_get_dimension(cmesh) + @ccall libt8.t8_cmesh_get_dimension(cmesh::t8_cmesh_t)::Cint end """ - p4est_corner_info_t + t8_cmesh_get_num_trees(cmesh) -Information about the neighbors of a corner +Return the global number of trees in a cmesh. -| Field | Note | -| :------------------ | :------------------------------------------------ | -| icorner | The number of the originating corner | -| corner\\_transforms | The array of neighbors of the originating corner | +# Arguments +* `cmesh`:\\[in\\] The cmesh to be considered. +# Returns +The number of trees associated to *cmesh*. *cmesh* must be committed before calling this function. +### Prototype +```c +t8_gloidx_t t8_cmesh_get_num_trees (t8_cmesh_t cmesh); +``` """ -struct p4est_corner_info_t - icorner::p4est_topidx_t - corner_transforms::sc_array_t +function t8_cmesh_get_num_trees(cmesh) + @ccall libt8.t8_cmesh_get_num_trees(cmesh::t8_cmesh_t)::t8_gloidx_t end """ - p4est_neighbor_transform_t + t8_cmesh_get_num_local_trees(cmesh) -Generic interface for transformations between a tree and any of its neighbors +Return the number of local trees of a cmesh. If the cmesh is not partitioned this is equivalent to t8_cmesh_get_num_trees. -| Field | Note | -| :---------------- | :-------------------------------------------------------------------------- | -| neighbor\\_type | type of connection to neighbor | -| neighbor | neighbor tree index | -| index\\_self | index of interface from self's perspective | -| index\\_neighbor | index of interface from neighbor's perspective | -| perm | permutation of dimensions when transforming self coords to neighbor coords | -| sign | sign changes when transforming self coords to neighbor coords | -| origin\\_self | point on the interface from self's perspective | -| origin\\_neighbor | point on the interface from neighbor's perspective | +# Arguments +* `cmesh`:\\[in\\] The cmesh to be considered. +# Returns +The number of local trees of the cmesh. *cmesh* must be committed before calling this function. +### Prototype +```c +t8_locidx_t t8_cmesh_get_num_local_trees (t8_cmesh_t cmesh); +``` """ -struct p4est_neighbor_transform_t - neighbor_type::p4est_connect_type_t - neighbor::p4est_topidx_t - index_self::Int8 - index_neighbor::Int8 - perm::NTuple{2, Int8} - sign::NTuple{2, Int8} - origin_self::NTuple{2, p4est_qcoord_t} - origin_neighbor::NTuple{2, p4est_qcoord_t} +function t8_cmesh_get_num_local_trees(cmesh) + @ccall libt8.t8_cmesh_get_num_local_trees(cmesh::t8_cmesh_t)::t8_locidx_t end """ - p4est_neighbor_transform_coordinates(nt, self_coords, neigh_coords) + t8_cmesh_get_num_ghosts(cmesh) -Transform from self's coordinate system to neighbor's coordinate system. +Return the number of ghost trees of a cmesh. If the cmesh is not partitioned this is equivalent to t8_cmesh_get_num_trees. # Arguments -* `nt`:\\[in\\] A neighbor transform. -* `self_coords`:\\[in\\] Input quadrant coordinates in self coordinates. -* `neigh_coords`:\\[out\\] Coordinates transformed into neighbor coordinates. +* `cmesh`:\\[in\\] The cmesh to be considered. +# Returns +The number of ghost trees of the cmesh. *cmesh* must be committed before calling this function. ### Prototype ```c -void p4est_neighbor_transform_coordinates (const p4est_neighbor_transform_t * nt, const p4est_qcoord_t self_coords[P4EST_DIM], p4est_qcoord_t neigh_coords[P4EST_DIM]); +t8_locidx_t t8_cmesh_get_num_ghosts (t8_cmesh_t cmesh); ``` """ -function p4est_neighbor_transform_coordinates(nt, self_coords, neigh_coords) - @ccall libp4est.p4est_neighbor_transform_coordinates(nt::Ptr{p4est_neighbor_transform_t}, self_coords::Ptr{p4est_qcoord_t}, neigh_coords::Ptr{p4est_qcoord_t})::Cvoid +function t8_cmesh_get_num_ghosts(cmesh) + @ccall libt8.t8_cmesh_get_num_ghosts(cmesh::t8_cmesh_t)::t8_locidx_t end """ - p4est_neighbor_transform_coordinates_reverse(nt, neigh_coords, self_coords) + t8_cmesh_get_first_treeid(cmesh) -Transform from neighbor's coordinate system to self's coordinate system. +Return the global index of the first local tree of a cmesh. If the cmesh is not partitioned this is always 0. # Arguments -* `nt`:\\[in\\] A neighbor transform. -* `neigh_coords`:\\[in\\] Input quadrant coordinates in self coordinates. -* `self_coords`:\\[out\\] Coordinates transformed into neighbor coordinates. +* `cmesh`:\\[in\\] The cmesh to be considered. +# Returns +The global id of the first local tree in cmesh. *cmesh* must be committed before calling this function. ### Prototype ```c -void p4est_neighbor_transform_coordinates_reverse (const p4est_neighbor_transform_t * nt, const p4est_qcoord_t neigh_coords[P4EST_DIM], p4est_qcoord_t self_coords[P4EST_DIM]); +t8_gloidx_t t8_cmesh_get_first_treeid (t8_cmesh_t cmesh); ``` """ -function p4est_neighbor_transform_coordinates_reverse(nt, neigh_coords, self_coords) - @ccall libp4est.p4est_neighbor_transform_coordinates_reverse(nt::Ptr{p4est_neighbor_transform_t}, neigh_coords::Ptr{p4est_qcoord_t}, self_coords::Ptr{p4est_qcoord_t})::Cvoid +function t8_cmesh_get_first_treeid(cmesh) + @ccall libt8.t8_cmesh_get_first_treeid(cmesh::t8_cmesh_t)::t8_gloidx_t end """ - p4est_connectivity_get_neighbor_transforms(conn, tree_id, boundary_type, boundary_index, neighbor_transform_array) + t8_cmesh_get_tree_geometry(cmesh, gtreeid) -Fill an array with the neighbor transforms based on a specific boundary type. This function generalizes all other inter-tree transformation objects +Get the geometry of a tree. # Arguments -* `conn`:\\[in\\] Connectivity structure. -* `tree_id`:\\[in\\] The number of the tree. -* `boundary_type`:\\[in\\] The type of the boundary connection (self, face, corner). -* `boundary_index`:\\[in\\] The index of the boundary. -* `neighbor_transform_array`:\\[in,out\\] Array of the neighbor transforms. +* `cmesh`:\\[in\\] The cmesh. +* `gtreeid`:\\[in\\] The global tree id of the tree for which the geometry should be returned. +# Returns +The geometry of the tree. ### Prototype ```c -void p4est_connectivity_get_neighbor_transforms (p4est_connectivity_t *conn, p4est_topidx_t tree_id, p4est_connect_type_t boundary_type, int boundary_index, sc_array_t *neighbor_transform_array); +const t8_geometry_c * t8_cmesh_get_tree_geometry (t8_cmesh_t cmesh, t8_gloidx_t gtreeid); ``` """ -function p4est_connectivity_get_neighbor_transforms(conn, tree_id, boundary_type, boundary_index, neighbor_transform_array) - @ccall libp4est.p4est_connectivity_get_neighbor_transforms(conn::Ptr{p4est_connectivity_t}, tree_id::p4est_topidx_t, boundary_type::p4est_connect_type_t, boundary_index::Cint, neighbor_transform_array::Ptr{sc_array_t})::Cvoid +function t8_cmesh_get_tree_geometry(cmesh, gtreeid) + @ccall libt8.t8_cmesh_get_tree_geometry(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t)::Ptr{t8_geometry_c} end """ - p4est_connectivity_coordinates_canonicalize(conn, treeid, coords, treeid_out, coords_out) - -Determine the owning tree for a coordinate and transform it there. - -On a boundary between trees, different coordinate systems meet. A coordinate on a tree boundary face or corner generated from the perspective of a specific tree may be transformed into any other touching tree's coordinate system and still refer to the same point in the mesh. + t8_cmesh_treeid_is_local_tree(cmesh, ltreeid) -To uniquely identify a coordinate, this function identifies the lowest numbered tree touching this coordinate and transforms the coordinates into that system. The result can be used e. g. in topology hash tables. +Query whether a given [`t8_locidx_t`](@ref) belongs to a local tree of a cmesh. # Arguments -* `conn`:\\[in\\] A valid connectivity. -* `treeid`:\\[in\\] The original tree index for this coordinate tuple. -* `coords`:\\[in\\] A valid coordinate 2-tuple relative to *treeid*. -* `treeid_out`:\\[out\\] The lowest tree index touching the coordinate. -* `coords_out`:\\[out\\] The input coordinates, if necessary after transformation into the system of the lowest numbered tree, returned in *treeid_out*. +* `cmesh`:\\[in\\] The cmesh to be considered. +* `ltreeid`:\\[in\\] 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. ### Prototype ```c -void p4est_connectivity_coordinates_canonicalize (p4est_connectivity_t *conn, p4est_topidx_t treeid, const p4est_qcoord_t coords[], p4est_topidx_t *treeid_out, p4est_qcoord_t coords_out[]); +int t8_cmesh_treeid_is_local_tree (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid); ``` """ -function p4est_connectivity_coordinates_canonicalize(conn, treeid, coords, treeid_out, coords_out) - @ccall libp4est.p4est_connectivity_coordinates_canonicalize(conn::Ptr{p4est_connectivity_t}, treeid::p4est_topidx_t, coords::Ptr{p4est_qcoord_t}, treeid_out::Ptr{p4est_topidx_t}, coords_out::Ptr{p4est_qcoord_t})::Cvoid +function t8_cmesh_treeid_is_local_tree(cmesh, ltreeid) + @ccall libt8.t8_cmesh_treeid_is_local_tree(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t)::Cint end """ - p4est_connectivity_face_neighbor_face_corner(fc, f, nf, o) + t8_cmesh_treeid_is_ghost(cmesh, ltreeid) -Transform a face corner across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. +Query whether a given [`t8_locidx_t`](@ref) belongs to a ghost of a cmesh. # Arguments -* `fc`:\\[in\\] A face corner number in 0..1. -* `f`:\\[in\\] A face that the face corner number *fc* is relative to. -* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. -* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. +* `cmesh`:\\[in\\] The cmesh to be considered. +* `ltreeid`:\\[in\\] An (possible) ghost index. # Returns -The face corner number relative to the neighbor's face. +True if *ltreeid* matches the range of ghost trees of *cmesh*. False if not. *cmesh* must be committed before calling this function. ### Prototype ```c -int p4est_connectivity_face_neighbor_face_corner (int fc, int f, int nf, int o); +int t8_cmesh_treeid_is_ghost (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid); ``` """ -function p4est_connectivity_face_neighbor_face_corner(fc, f, nf, o) - @ccall libp4est.p4est_connectivity_face_neighbor_face_corner(fc::Cint, f::Cint, nf::Cint, o::Cint)::Cint +function t8_cmesh_treeid_is_ghost(cmesh, ltreeid) + @ccall libt8.t8_cmesh_treeid_is_ghost(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t)::Cint end """ - p4est_connectivity_face_neighbor_corner(c, f, nf, o) + t8_cmesh_ltreeid_to_ghostid(cmesh, ltreeid) -Transform a corner across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. +Given a local tree id that belongs to a ghost, return the index of the ghost. # Arguments -* `c`:\\[in\\] A corner number in 0..3. -* `f`:\\[in\\] A face number that touches the corner *c*. -* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. -* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. +* `cmesh`:\\[in\\] The cmesh to be considered. +* `ltreeid`:\\[in\\] The local id of a ghost, satisfying t8_cmesh_treeid_is_ghost, thus num\\_trees <= *ltreeid* < num\\_trees + num\\_ghosts # Returns -The number of the corner seen from the neighbor tree. +The index of the ghost within all ghosts, thus an index 0 <= index < num\\_ghosts *cmesh* must be committed before calling this function. ### Prototype ```c -int p4est_connectivity_face_neighbor_corner (int c, int f, int nf, int o); +t8_locidx_t t8_cmesh_ltreeid_to_ghostid (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid); ``` """ -function p4est_connectivity_face_neighbor_corner(c, f, nf, o) - @ccall libp4est.p4est_connectivity_face_neighbor_corner(c::Cint, f::Cint, nf::Cint, o::Cint)::Cint +function t8_cmesh_ltreeid_to_ghostid(cmesh, ltreeid) + @ccall libt8.t8_cmesh_ltreeid_to_ghostid(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t)::t8_locidx_t end """ - p4est_connectivity_new(num_vertices, num_trees, num_corners, num_ctt) + t8_cmesh_get_first_tree(cmesh) -Allocate a connectivity structure. The attribute fields are initialized to NULL. +Return a pointer to the first local tree in a cmesh. # Arguments -* `num_vertices`:\\[in\\] Number of total vertices (i.e. geometric points). -* `num_trees`:\\[in\\] Number of trees in the forest. -* `num_corners`:\\[in\\] Number of tree-connecting corners. -* `num_ctt`:\\[in\\] Number of total trees in corner\\_to\\_tree array. +* `cmesh`:\\[in\\] The cmesh to be queried. # Returns -A connectivity structure with allocated arrays. +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. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new (p4est_topidx_t num_vertices, p4est_topidx_t num_trees, p4est_topidx_t num_corners, p4est_topidx_t num_ctt); +t8_ctree_t t8_cmesh_get_first_tree (t8_cmesh_t cmesh); ``` """ -function p4est_connectivity_new(num_vertices, num_trees, num_corners, num_ctt) - @ccall libp4est.p4est_connectivity_new(num_vertices::p4est_topidx_t, num_trees::p4est_topidx_t, num_corners::p4est_topidx_t, num_ctt::p4est_topidx_t)::Ptr{p4est_connectivity_t} +function t8_cmesh_get_first_tree(cmesh) + @ccall libt8.t8_cmesh_get_first_tree(cmesh::t8_cmesh_t)::t8_ctree_t end """ - p4est_connectivity_new_copy(num_vertices, num_trees, num_corners, vertices, ttv, ttt, ttf, ttc, coff, ctt, ctc) + t8_cmesh_get_next_tree(cmesh, tree) -Allocate a connectivity structure and populate from constants. The attribute fields are initialized to NULL. +Given a local tree in a cmesh return a pointer to the next local tree. # Arguments -* `num_vertices`:\\[in\\] Number of total vertices (i.e. geometric points). -* `num_trees`:\\[in\\] Number of trees in the forest. -* `num_corners`:\\[in\\] Number of tree-connecting corners. -* `vertices`:\\[in\\] Coordinates of the vertices of the trees. -* `ttv`:\\[in\\] The tree-to-vertex array. -* `ttt`:\\[in\\] The tree-to-tree array. -* `ttf`:\\[in\\] The tree-to-face array (int8\\_t). -* `ttc`:\\[in\\] The tree-to-corner array. -* `coff`:\\[in\\] Corner-to-tree offsets (num\\_corners + 1 values). This must always be non-NULL; in trivial cases it is just a pointer to a p4est\\_topix value of 0. -* `ctt`:\\[in\\] The corner-to-tree array. -* `ctc`:\\[in\\] The corner-to-corner array. +* `cmesh`:\\[in\\] The cmesh to be queried. +* `tree`:\\[in\\] A local tree in *cmesh*. # Returns -The connectivity is checked for validity. +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. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_copy (p4est_topidx_t num_vertices, p4est_topidx_t num_trees, p4est_topidx_t num_corners, const double *vertices, const p4est_topidx_t * ttv, const p4est_topidx_t * ttt, const int8_t * ttf, const p4est_topidx_t * ttc, const p4est_topidx_t * coff, const p4est_topidx_t * ctt, const int8_t * ctc); +t8_ctree_t t8_cmesh_get_next_tree (t8_cmesh_t cmesh, t8_ctree_t tree); ``` """ -function p4est_connectivity_new_copy(num_vertices, num_trees, num_corners, vertices, ttv, ttt, ttf, ttc, coff, ctt, ctc) - @ccall libp4est.p4est_connectivity_new_copy(num_vertices::p4est_topidx_t, num_trees::p4est_topidx_t, num_corners::p4est_topidx_t, vertices::Ptr{Cdouble}, ttv::Ptr{p4est_topidx_t}, ttt::Ptr{p4est_topidx_t}, ttf::Ptr{Int8}, ttc::Ptr{p4est_topidx_t}, coff::Ptr{p4est_topidx_t}, ctt::Ptr{p4est_topidx_t}, ctc::Ptr{Int8})::Ptr{p4est_connectivity_t} +function t8_cmesh_get_next_tree(cmesh, tree) + @ccall libt8.t8_cmesh_get_next_tree(cmesh::t8_cmesh_t, tree::t8_ctree_t)::t8_ctree_t end """ - p4est_connectivity_copy(input, copy_attr) + t8_cmesh_get_tree(cmesh, ltree_id) -Deep copy a connectivity structure. +Return a pointer to a given local tree. # Arguments -* `input`:\\[in\\] Valid connectivity. -* `copy_attr`:\\[in\\] If true, we copy the tree attribute data. Otherwise, the result has empty attributes. +* `cmesh`:\\[in\\] The cmesh to be queried. +* `ltree_id`:\\[in\\] The local id of the tree that is asked for. # Returns -A connectivity equal to the first one except, depending on *copy_attry*, for its attributes. +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. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_copy (p4est_connectivity_t *input, int copy_attr); +t8_ctree_t t8_cmesh_get_tree (t8_cmesh_t cmesh, t8_locidx_t ltree_id); ``` """ -function p4est_connectivity_copy(input, copy_attr) - @ccall libp4est.p4est_connectivity_copy(input::Ptr{p4est_connectivity_t}, copy_attr::Cint)::Ptr{p4est_connectivity_t} +function t8_cmesh_get_tree(cmesh, ltree_id) + @ccall libt8.t8_cmesh_get_tree(cmesh::t8_cmesh_t, ltree_id::t8_locidx_t)::t8_ctree_t end """ - p4est_connectivity_bcast(conn_in, root, comm) + t8_cmesh_get_tree_class(cmesh, ltree_id) + +Return the eclass of a given local tree. TODO: Should we refer to indices or consequently use ctree\\_t? +# Arguments +* `cmesh`:\\[in\\] The cmesh to be considered. +* `ltree_id`:\\[in\\] 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. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_bcast (p4est_connectivity_t * conn_in, int root, sc_MPI_Comm comm); +t8_eclass_t t8_cmesh_get_tree_class (t8_cmesh_t cmesh, t8_locidx_t ltree_id); ``` """ -function p4est_connectivity_bcast(conn_in, root, comm) - @ccall libp4est.p4est_connectivity_bcast(conn_in::Ptr{p4est_connectivity_t}, root::Cint, comm::MPI_Comm)::Ptr{p4est_connectivity_t} +function t8_cmesh_get_tree_class(cmesh, ltree_id) + @ccall libt8.t8_cmesh_get_tree_class(cmesh::t8_cmesh_t, ltree_id::t8_locidx_t)::t8_eclass_t end """ - p4est_connectivity_destroy(connectivity) + t8_cmesh_tree_face_is_boundary(cmesh, ltree_id, face) -Destroy a connectivity structure. Also destroy all attributes. - -### Prototype -```c -void p4est_connectivity_destroy (p4est_connectivity_t * connectivity); -``` -""" -function p4est_connectivity_destroy(connectivity) - @ccall libp4est.p4est_connectivity_destroy(connectivity::Ptr{p4est_connectivity_t})::Cvoid -end - -""" - p4est_connectivity_share(conn_in, root, comm) +Query whether a face of a local tree or ghost is at the domain boundary. +# Arguments +* `cmesh`:\\[in\\] The cmesh to be considered. +* `ltree_id`:\\[in\\] The local id of a tree. +* `face`:\\[in\\] 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. ### Prototype ```c -p4est_connectivity_shared_t *p4est_connectivity_share (p4est_connectivity_t * conn_in, int root, sc_MPI_Comm comm); +int t8_cmesh_tree_face_is_boundary (t8_cmesh_t cmesh, t8_locidx_t ltree_id, int face); ``` """ -function p4est_connectivity_share(conn_in, root, comm) - @ccall libp4est.p4est_connectivity_share(conn_in::Ptr{p4est_connectivity_t}, root::Cint, comm::MPI_Comm)::Ptr{p4est_connectivity_shared_t} +function t8_cmesh_tree_face_is_boundary(cmesh, ltree_id, face) + @ccall libt8.t8_cmesh_tree_face_is_boundary(cmesh::t8_cmesh_t, ltree_id::t8_locidx_t, face::Cint)::Cint end """ - p4est_connectivity_mission(conn_in, split_type, world_comm) + t8_cmesh_get_ghost_class(cmesh, lghost_id) + +Return the eclass of a given local ghost. TODO: Should we refer to indices or consequently use cghost\\_t? +# Arguments +* `cmesh`:\\[in\\] The cmesh to be considered. +* `lghost_id`:\\[in\\] 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. ### Prototype ```c -p4est_connectivity_shared_t * p4est_connectivity_mission (p4est_connectivity_t *conn_in, int split_type, sc_MPI_Comm world_comm); +t8_eclass_t t8_cmesh_get_ghost_class (t8_cmesh_t cmesh, t8_locidx_t lghost_id); ``` """ -function p4est_connectivity_mission(conn_in, split_type, world_comm) - @ccall libp4est.p4est_connectivity_mission(conn_in::Ptr{p4est_connectivity_t}, split_type::Cint, world_comm::Cint)::Ptr{p4est_connectivity_shared_t} +function t8_cmesh_get_ghost_class(cmesh, lghost_id) + @ccall libt8.t8_cmesh_get_ghost_class(cmesh::t8_cmesh_t, lghost_id::t8_locidx_t)::t8_eclass_t end """ - p4est_connectivity_shared_destroy(cshare) + t8_cmesh_get_global_id(cmesh, local_id) -Destroy a shared connectivity structure. Call this eventually on the result of p4est_connectivity_share or p4est_connectivity_mission (which calls the former internally). +Return the global id of a given local tree or ghost. # Arguments -* `cshare`:\\[in\\] Valid shared connectivity structure; cf. p4est_connectivity_share. +* `cmesh`:\\[in\\] The cmesh to be considered. +* `local_id`:\\[in\\] 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. + ### Prototype ```c -void p4est_connectivity_shared_destroy (p4est_connectivity_shared_t *cshare); +t8_gloidx_t t8_cmesh_get_global_id (t8_cmesh_t cmesh, t8_locidx_t local_id); ``` """ -function p4est_connectivity_shared_destroy(cshare) - @ccall libp4est.p4est_connectivity_shared_destroy(cshare::Ptr{p4est_connectivity_shared_t})::Cvoid +function t8_cmesh_get_global_id(cmesh, local_id) + @ccall libt8.t8_cmesh_get_global_id(cmesh::t8_cmesh_t, local_id::t8_locidx_t)::t8_gloidx_t end """ - p4est_connectivity_set_attr(conn, bytes_per_tree) + t8_cmesh_get_local_id(cmesh, global_id) -Allocate or free the attribute fields in a connectivity. +Return the local id of a give global tree. # Arguments -* `conn`:\\[in,out\\] The conn->*\\_to\\_attr fields must either be NULL or previously be allocated by this function. -* `bytes_per_tree`:\\[in\\] If 0, tree\\_to\\_attr is freed (being NULL is ok). If positive, requested space is allocated. +* `cmesh`:\\[in\\] The cmesh. +* `global_id`:\\[in\\] 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. + ### Prototype ```c -void p4est_connectivity_set_attr (p4est_connectivity_t * conn, size_t bytes_per_tree); +t8_locidx_t t8_cmesh_get_local_id (t8_cmesh_t cmesh, t8_gloidx_t global_id); ``` """ -function p4est_connectivity_set_attr(conn, bytes_per_tree) - @ccall libp4est.p4est_connectivity_set_attr(conn::Ptr{p4est_connectivity_t}, bytes_per_tree::Csize_t)::Cvoid +function t8_cmesh_get_local_id(cmesh, global_id) + @ccall libt8.t8_cmesh_get_local_id(cmesh::t8_cmesh_t, global_id::t8_gloidx_t)::t8_locidx_t end """ - p4est_connectivity_is_valid(connectivity) + t8_cmesh_get_face_neighbor(cmesh, ltreeid, face, dual_face, orientation) -Examine a connectivity structure. +Given a local tree id and a face number, get information about the face neighbor tree. + +!!! 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 +# Arguments +* `cmesh`:\\[in\\] The cmesh to be considered. +* `ltreeid`:\\[in\\] The local id of a tree or a ghost. +* `face`:\\[in\\] A face number of the tree/ghost. +* `dual_face`:\\[out\\] If not NULL, the face number of the neighbor tree at this connection. +* `orientation`:\\[out\\] If not NULL, the face orientation of the connection. # Returns -Returns true if structure is valid, false otherwise. +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. +# See also +[`t8_cmesh_tree_face_is_boundary`](@ref). + ### Prototype ```c -int p4est_connectivity_is_valid (p4est_connectivity_t * connectivity); +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); ``` """ -function p4est_connectivity_is_valid(connectivity) - @ccall libp4est.p4est_connectivity_is_valid(connectivity::Ptr{p4est_connectivity_t})::Cint +function t8_cmesh_get_face_neighbor(cmesh, ltreeid, face, dual_face, orientation) + @ccall libt8.t8_cmesh_get_face_neighbor(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t, face::Cint, dual_face::Ptr{Cint}, orientation::Ptr{Cint})::t8_locidx_t end """ - p4est_connectivity_is_equal(conn1, conn2) + t8_cmesh_get_tree_face_neighbor_eclass(cmesh, ltreeid, face) -Check two connectivity structures for equality. +Given a local tree id (of a local tree or ghost tree) and a face compute the eclass of the tree's face neighbor. +# Arguments +* `cmesh`:\\[in\\] The cmesh to be considered. +* `ltreeid`:\\[in\\] The local id of a tree or a ghost. +* `face`:\\[in\\] A face number of the tree/ghost. # Returns -Returns true if structures are equal, false otherwise. +The eclass of a neighbor tree of *ltreeid* across *face*. T8\\_ECLASS\\_INVALID if no neighbor exists. ### Prototype ```c -int p4est_connectivity_is_equal (p4est_connectivity_t * conn1, p4est_connectivity_t * conn2); +t8_eclass_t t8_cmesh_get_tree_face_neighbor_eclass (const t8_cmesh_t cmesh, const t8_locidx_t ltreeid, const int face); ``` """ -function p4est_connectivity_is_equal(conn1, conn2) - @ccall libp4est.p4est_connectivity_is_equal(conn1::Ptr{p4est_connectivity_t}, conn2::Ptr{p4est_connectivity_t})::Cint +function t8_cmesh_get_tree_face_neighbor_eclass(cmesh, ltreeid, face) + @ccall libt8.t8_cmesh_get_tree_face_neighbor_eclass(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t, face::Cint)::t8_eclass_t end """ - p4est_connectivity_sink(conn, sink) + t8_cmesh_print_profile(cmesh) -Write connectivity to a sink object. +Print the collected statistics from a cmesh profile. + +*cmesh* must be committed before calling this function. # Arguments -* `conn`:\\[in\\] The connectivity to be written. -* `sink`:\\[in,out\\] The connectivity is written into this sink. -# Returns -0 on success, nonzero on error. +* `cmesh`:\\[in\\] The cmesh. +# See also +[`t8_cmesh_set_profiling`](@ref) + ### Prototype ```c -int p4est_connectivity_sink (p4est_connectivity_t * conn, sc_io_sink_t * sink); +void t8_cmesh_print_profile (t8_cmesh_t cmesh); ``` """ -function p4est_connectivity_sink(conn, sink) - @ccall libp4est.p4est_connectivity_sink(conn::Ptr{p4est_connectivity_t}, sink::Ptr{sc_io_sink_t})::Cint +function t8_cmesh_print_profile(cmesh) + @ccall libt8.t8_cmesh_print_profile(cmesh::t8_cmesh_t)::Cvoid end """ - p4est_connectivity_deflate(conn, code) + t8_cmesh_get_tree_vertices(cmesh, ltreeid) -Allocate memory and store the connectivity information there. +Return a pointer to the vertex coordinates of a tree. # Arguments -* `conn`:\\[in\\] The connectivity structure to be exported to memory. -* `code`:\\[in\\] Encoding and compression method for serialization. +* `cmesh`:\\[in\\] The cmesh. +* `ltreeid`:\\[in\\] The id of a local tree. # Returns -Newly created array that contains the information. +If stored, a pointer to the vertex coordinates of *tree*. If no coordinates for this tree are found, NULL. ### Prototype ```c -sc_array_t *p4est_connectivity_deflate (p4est_connectivity_t * conn, p4est_connectivity_encode_t code); +double * t8_cmesh_get_tree_vertices (t8_cmesh_t cmesh, t8_locidx_t ltreeid); ``` """ -function p4est_connectivity_deflate(conn, code) - @ccall libp4est.p4est_connectivity_deflate(conn::Ptr{p4est_connectivity_t}, code::p4est_connectivity_encode_t)::Ptr{sc_array_t} +function t8_cmesh_get_tree_vertices(cmesh, ltreeid) + @ccall libt8.t8_cmesh_get_tree_vertices(cmesh::t8_cmesh_t, ltreeid::t8_locidx_t)::Ptr{Cdouble} end """ - p4est_connectivity_save(filename, connectivity) + t8_cmesh_get_attribute(cmesh, package_id, key, ltree_id) -Save a connectivity structure to disk. +Return the attribute pointer of a tree. + +!!! note + + *cmesh* must be committed before calling this function. # Arguments -* `filename`:\\[in\\] Name of the file to write. -* `connectivity`:\\[in\\] Valid connectivity structure. +* `cmesh`:\\[in\\] The cmesh. +* `package_id`:\\[in\\] The identifier of a valid software package. +* `key`:\\[in\\] A key used to identify the attribute under all attributes of this tree with the same *package_id*. +* `ltree_id`:\\[in\\] The local number of the tree. # Returns -Returns 0 on success, nonzero on file error. +The attribute pointer of the tree *ltree_id* or NULL if the attribute is not found. +# See also +[`sc_package_register`](@ref), [`t8_cmesh_set_attribute`](@ref) + ### Prototype ```c -int p4est_connectivity_save (const char *filename, p4est_connectivity_t * connectivity); +void * t8_cmesh_get_attribute (const t8_cmesh_t cmesh, const int package_id, const int key, const t8_locidx_t ltree_id); ``` """ -function p4est_connectivity_save(filename, connectivity) - @ccall libp4est.p4est_connectivity_save(filename::Cstring, connectivity::Ptr{p4est_connectivity_t})::Cint +function t8_cmesh_get_attribute(cmesh, package_id, key, ltree_id) + @ccall libt8.t8_cmesh_get_attribute(cmesh::t8_cmesh_t, package_id::Cint, key::Cint, ltree_id::t8_locidx_t)::Ptr{Cvoid} end """ - p4est_connectivity_source(source) + t8_cmesh_get_attribute_gloidx_array(cmesh, package_id, key, ltree_id, data_count) -Read connectivity from a source object. +Return the attribute pointer of a tree for a gloidx\\_t array. + +!!! note + + *cmesh* must be committed before calling this function. + +!!! note + + No check is performed whether the attribute actually stored *data_count* many entries since we do not store the number of data entries of the attribute array. You can keep track of the data count yourself by using another attribute. # Arguments -* `source`:\\[in,out\\] The connectivity is read from this source. +* `cmesh`:\\[in\\] The cmesh. +* `package_id`:\\[in\\] The identifier of a valid software package. +* `key`:\\[in\\] A key used to identify the attribute under all attributes of this tree with the same *package_id*. +* `ltree_id`:\\[in\\] The local number of the tree. +* `data_count`:\\[in\\] The number of entries in the array that are requested. This must be smaller or equal to the *data_count* parameter of the corresponding call to t8_cmesh_set_attribute_gloidx_array # Returns -The newly created connectivity, or NULL on error. +The attribute pointer of the tree *ltree_id* or NULL if the attribute is not found. +# See also +[`sc_package_register`](@ref), [`t8_cmesh_set_attribute_gloidx_array`](@ref) + ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_source (sc_io_source_t * source); +t8_gloidx_t * t8_cmesh_get_attribute_gloidx_array (const t8_cmesh_t cmesh, const int package_id, const int key, const t8_locidx_t ltree_id, const size_t data_count); ``` """ -function p4est_connectivity_source(source) - @ccall libp4est.p4est_connectivity_source(source::Ptr{sc_io_source_t})::Ptr{p4est_connectivity_t} +function t8_cmesh_get_attribute_gloidx_array(cmesh, package_id, key, ltree_id, data_count) + @ccall libt8.t8_cmesh_get_attribute_gloidx_array(cmesh::t8_cmesh_t, package_id::Cint, key::Cint, ltree_id::t8_locidx_t, data_count::Csize_t)::Ptr{t8_gloidx_t} end """ - p4est_connectivity_inflate(buffer) + t8_cmesh_get_partition_table(cmesh) -Create new connectivity from a memory buffer. This function aborts on malloc errors. +Return the shared memory array storing the partition table of a partitioned cmesh. # Arguments -* `buffer`:\\[in\\] The connectivity is created from this memory buffer. +* `cmesh`:\\[in\\] The cmesh. # Returns -The newly created connectivity, or NULL on format error of the buffered connectivity data. +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. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_inflate (sc_array_t * buffer); +t8_shmem_array_t t8_cmesh_get_partition_table (t8_cmesh_t cmesh); ``` """ -function p4est_connectivity_inflate(buffer) - @ccall libp4est.p4est_connectivity_inflate(buffer::Ptr{sc_array_t})::Ptr{p4est_connectivity_t} +function t8_cmesh_get_partition_table(cmesh) + @ccall libt8.t8_cmesh_get_partition_table(cmesh::t8_cmesh_t)::t8_shmem_array_t end """ - p4est_connectivity_load(filename, bytes) + t8_cmesh_uniform_bounds_equal_element_count(cmesh, level, tree_scheme, first_local_tree, child_in_tree_begin, last_local_tree, child_in_tree_end, first_tree_shared) -Load a connectivity structure from disk. +Calculate the section of a uniform forest for the current rank. # Arguments -* `filename`:\\[in\\] Name of the file to read. -* `bytes`:\\[in,out\\] Size in bytes of connectivity on disk or NULL. -# Returns -Returns valid connectivity, or NULL on file error. +* `cmesh`:\\[in\\] The cmesh to be considered. +* `level`:\\[in\\] The uniform refinement level to be created. +* `tree_scheme`:\\[in\\] The element scheme for which to compute the bounds. +* `first_local_tree`:\\[out\\] The first tree that contains elements belonging to the calling processor. +* `child_in_tree_begin`:\\[out\\] The tree-local index of the first element belonging to the calling processor. Not computed if NULL. +* `last_local_tree`:\\[out\\] The last tree that contains elements belonging to the calling processor. +* `child_in_tree_end`:\\[out\\] The tree-local index of the first element that does not belonging to the calling processor anymore. Not computed if NULL. +* `first_tree_shared`:\\[out\\] If not NULL, 1 or 0 is stored here depending on whether *first_local_tree* is the same as *last_local_tree* on the previous process. *cmesh* must be committed before calling this function. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_load (const char *filename, size_t *bytes); +void t8_cmesh_uniform_bounds_equal_element_count (t8_cmesh_t cmesh, const int level, const t8_scheme_c *tree_scheme, t8_gloidx_t *first_local_tree, t8_gloidx_t *child_in_tree_begin, t8_gloidx_t *last_local_tree, t8_gloidx_t *child_in_tree_end, int8_t *first_tree_shared); ``` """ -function p4est_connectivity_load(filename, bytes) - @ccall libp4est.p4est_connectivity_load(filename::Cstring, bytes::Ptr{Csize_t})::Ptr{p4est_connectivity_t} +function t8_cmesh_uniform_bounds_equal_element_count(cmesh, level, tree_scheme, first_local_tree, child_in_tree_begin, last_local_tree, child_in_tree_end, first_tree_shared) + @ccall libt8.t8_cmesh_uniform_bounds_equal_element_count(cmesh::t8_cmesh_t, level::Cint, tree_scheme::Ptr{t8_scheme_c}, first_local_tree::Ptr{t8_gloidx_t}, child_in_tree_begin::Ptr{t8_gloidx_t}, last_local_tree::Ptr{t8_gloidx_t}, child_in_tree_end::Ptr{t8_gloidx_t}, first_tree_shared::Ptr{Int8})::Cvoid end """ - p4est_connectivity_new_unitsquare() - -Create a connectivity structure for the unit square. + t8_cmesh_uniform_bounds_for_irregular_refinement(cmesh, level, scheme, first_local_tree, child_in_tree_begin, last_local_tree, child_in_tree_end, first_tree_shared, comm) ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_unitsquare (void); +void t8_cmesh_uniform_bounds_for_irregular_refinement (const t8_cmesh_t cmesh, const int level, const t8_scheme_c *scheme, t8_gloidx_t *first_local_tree, t8_gloidx_t *child_in_tree_begin, t8_gloidx_t *last_local_tree, t8_gloidx_t *child_in_tree_end, int8_t *first_tree_shared, sc_MPI_Comm comm); ``` """ -function p4est_connectivity_new_unitsquare() - @ccall libp4est.p4est_connectivity_new_unitsquare()::Ptr{p4est_connectivity_t} +function t8_cmesh_uniform_bounds_for_irregular_refinement(cmesh, level, scheme, first_local_tree, child_in_tree_begin, last_local_tree, child_in_tree_end, first_tree_shared, comm) + @ccall libt8.t8_cmesh_uniform_bounds_for_irregular_refinement(cmesh::t8_cmesh_t, level::Cint, scheme::Ptr{t8_scheme_c}, first_local_tree::Ptr{t8_gloidx_t}, child_in_tree_begin::Ptr{t8_gloidx_t}, last_local_tree::Ptr{t8_gloidx_t}, child_in_tree_end::Ptr{t8_gloidx_t}, first_tree_shared::Ptr{Int8}, comm::MPI_Comm)::Cvoid end """ - p4est_connectivity_new_periodic() + t8_cmesh_ref(cmesh) -Create a connectivity structure for an all-periodic unit square. +Increase the reference counter of a cmesh. +# Arguments +* `cmesh`:\\[in,out\\] On input, this cmesh must exist with positive reference count. It may be in any state. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_periodic (void); +void t8_cmesh_ref (t8_cmesh_t cmesh); ``` """ -function p4est_connectivity_new_periodic() - @ccall libp4est.p4est_connectivity_new_periodic()::Ptr{p4est_connectivity_t} +function t8_cmesh_ref(cmesh) + @ccall libt8.t8_cmesh_ref(cmesh::t8_cmesh_t)::Cvoid end """ - p4est_connectivity_new_rotwrap() + t8_cmesh_unref(pcmesh) -Create a connectivity structure for a periodic unit square. The left and right faces are identified, and bottom and top opposite. +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. +# Arguments +* `pcmesh`:\\[in,out\\] 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. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_rotwrap (void); +void t8_cmesh_unref (t8_cmesh_t *pcmesh); ``` """ -function p4est_connectivity_new_rotwrap() - @ccall libp4est.p4est_connectivity_new_rotwrap()::Ptr{p4est_connectivity_t} +function t8_cmesh_unref(pcmesh) + @ccall libt8.t8_cmesh_unref(pcmesh::Ptr{t8_cmesh_t})::Cvoid end """ - p4est_connectivity_new_circle() + t8_cmesh_destroy(pcmesh) -Create a connectivity structure for an donut-like circle. The circle consists of 6 trees connecting each other by their faces. The trees are laid out as a hexagon between [-2, 2] in the y direction and [-sqrt(3), sqrt(3)] in the x direction. The hexagon has flat sides along the y direction and pointy ends in x. +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. +# Arguments +* `pcmesh`:\\[in,out\\] 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. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_circle (void); +void t8_cmesh_destroy (t8_cmesh_t *pcmesh); ``` """ -function p4est_connectivity_new_circle() - @ccall libp4est.p4est_connectivity_new_circle()::Ptr{p4est_connectivity_t} +function t8_cmesh_destroy(pcmesh) + @ccall libt8.t8_cmesh_destroy(pcmesh::Ptr{t8_cmesh_t})::Cvoid end """ - p4est_connectivity_new_drop() + t8_cmesh_coords_axb(coords_in, coords_out, num_vertices, alpha, b) -Create a connectivity structure for a five-trees geometry with a hole. The geometry covers the square [0, 3]**2, where the hole is [1, 2]**2. +Compute y = ax + b on an array of doubles, interpreting each 3 as one vector x +# Arguments +* `coords_in`:\\[in\\] The incoming coordinates of the vectors +* `coords_out`:\\[out\\] The computed coordinates of the vectors +* `num_vertices`:\\[in\\] The number of vertices/vectors +* `alpha`:\\[in\\] Scaling factor for the vectors +* `b`:\\[in\\] Translation of the vectors. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_drop (void); +void t8_cmesh_coords_axb (const double *coords_in, double *coords_out, int num_vertices, double alpha, const double b[3]); ``` """ -function p4est_connectivity_new_drop() - @ccall libp4est.p4est_connectivity_new_drop()::Ptr{p4est_connectivity_t} +function t8_cmesh_coords_axb(coords_in, coords_out, num_vertices, alpha, b) + @ccall libt8.t8_cmesh_coords_axb(coords_in::Ptr{Cdouble}, coords_out::Ptr{Cdouble}, num_vertices::Cint, alpha::Cdouble, b::Ptr{Cdouble})::Cvoid end """ - p4est_connectivity_new_twotrees(l_face, r_face, orientation) + t8_cmesh_translate_coordinates(coords_in, coords_out, num_vertices, translate) -Create a connectivity structure for two trees being rotated w.r.t. each other in a user-defined way +Compute y = x + translate on an array of doubles, interpreting each 3 as one vector x # Arguments -* `l_face`:\\[in\\] index of left face -* `r_face`:\\[in\\] index of right face -* `orientation`:\\[in\\] orientation of trees w.r.t. each other +* `coords_in`:\\[in\\] The incoming coordinates of the vectors +* `coords_out`:\\[out\\] The computed coordinates of the vectors +* `num_vertices`:\\[in\\] The number of vertices/vectors +* `translate`:\\[in\\] Translation of the vectors. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_twotrees (int l_face, int r_face, int orientation); +void t8_cmesh_translate_coordinates (const double *coords_in, double *coords_out, const int num_vertices, const double translate[3]); ``` """ -function p4est_connectivity_new_twotrees(l_face, r_face, orientation) - @ccall libp4est.p4est_connectivity_new_twotrees(l_face::Cint, r_face::Cint, orientation::Cint)::Ptr{p4est_connectivity_t} +function t8_cmesh_translate_coordinates(coords_in, coords_out, num_vertices, translate) + @ccall libt8.t8_cmesh_translate_coordinates(coords_in::Ptr{Cdouble}, coords_out::Ptr{Cdouble}, num_vertices::Cint, translate::Ptr{Cdouble})::Cvoid end """ - p4est_connectivity_new_corner() + t8_cmesh_new_translate_vertices_to_attributes(tvertices, vertices, attr_vertices, num_vertices) -Create a connectivity structure for a three-tree mesh around a corner. +TODO: Add proper documentation ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_corner (void); +void t8_cmesh_new_translate_vertices_to_attributes (const t8_locidx_t *tvertices, const double *vertices, double *attr_vertices, const int num_vertices); ``` """ -function p4est_connectivity_new_corner() - @ccall libp4est.p4est_connectivity_new_corner()::Ptr{p4est_connectivity_t} +function t8_cmesh_new_translate_vertices_to_attributes(tvertices, vertices, attr_vertices, num_vertices) + @ccall libt8.t8_cmesh_new_translate_vertices_to_attributes(tvertices::Ptr{t8_locidx_t}, vertices::Ptr{Cdouble}, attr_vertices::Ptr{Cdouble}, num_vertices::Cint)::Cvoid end """ - p4est_connectivity_new_pillow() - -Create a connectivity structure for two trees on top of each other. + t8_cmesh_debug_print_trees(cmesh, comm) ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_pillow (void); +void t8_cmesh_debug_print_trees (const t8_cmesh_t cmesh, sc_MPI_Comm comm); ``` """ -function p4est_connectivity_new_pillow() - @ccall libp4est.p4est_connectivity_new_pillow()::Ptr{p4est_connectivity_t} +function t8_cmesh_debug_print_trees(cmesh, comm) + @ccall libt8.t8_cmesh_debug_print_trees(cmesh::t8_cmesh_t, comm::MPI_Comm)::Cvoid end """ - p4est_connectivity_new_moebius() + t8_cmesh_get_local_bounding_box(cmesh, bounds) -Create a connectivity structure for a five-tree moebius band. +Compute the process local bounding box of the cmesh. The bounding box is stored in the array *bounds* in the following order: bounds[0] = x\\_min bounds[1] = x\\_max bounds[2] = y\\_min bounds[3] = y\\_max bounds[4] = z\\_min bounds[5] = z\\_max +# Arguments +* `cmesh`:\\[in\\] The cmesh to be considered. +* `bounds`:\\[out\\] The bounding box of the cmesh. If the box is flat (for quads for example, z\\_min == z\\_max) +# Returns +True if the computation was successful, false if the cmesh is empty. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_moebius (void); +int t8_cmesh_get_local_bounding_box (const t8_cmesh_t cmesh, double bounds[6]); ``` """ -function p4est_connectivity_new_moebius() - @ccall libp4est.p4est_connectivity_new_moebius()::Ptr{p4est_connectivity_t} +function t8_cmesh_get_local_bounding_box(cmesh, bounds) + @ccall libt8.t8_cmesh_get_local_bounding_box(cmesh::t8_cmesh_t, bounds::Ptr{Cdouble})::Cint end """ - p4est_connectivity_new_star() + sc_io_error_t -Create a connectivity structure for a six-tree star. +Error values for io. -### Prototype -```c -p4est_connectivity_t *p4est_connectivity_new_star (void); -``` +| Enumerator | Note | +| :---------------------- | :--------------------------------------------------------------------------- | +| SC\\_IO\\_ERROR\\_NONE | The value of zero means no error. | +| SC\\_IO\\_ERROR\\_FATAL | The io object is now dysfunctional. | +| SC\\_IO\\_ERROR\\_AGAIN | Another io operation may resolve it. The function just returned was a noop. | """ -function p4est_connectivity_new_star() - @ccall libp4est.p4est_connectivity_new_star()::Ptr{p4est_connectivity_t} +@cenum sc_io_error_t::Int32 begin + SC_IO_ERROR_NONE = 0 + SC_IO_ERROR_FATAL = -1 + SC_IO_ERROR_AGAIN = -2 end """ - p4est_connectivity_new_cubed() - -Create a connectivity structure for the six sides of a unit cube. The ordering of the trees is as follows: - -0 1 2 3 <-- 3: axis-aligned top side 4 5 + sc_io_mode_t -This choice has been made for maximum symmetry (see tree\\_to\\_* in .c file). +The I/O mode for writing using sc_io_sink. -### Prototype -```c -p4est_connectivity_t *p4est_connectivity_new_cubed (void); -``` +| Enumerator | Note | +| :---------------------- | :--------------------------- | +| SC\\_IO\\_MODE\\_WRITE | Semantics as "w" in fopen. | +| SC\\_IO\\_MODE\\_APPEND | Semantics as "a" in fopen. | +| SC\\_IO\\_MODE\\_LAST | Invalid entry to close list | """ -function p4est_connectivity_new_cubed() - @ccall libp4est.p4est_connectivity_new_cubed()::Ptr{p4est_connectivity_t} +@cenum sc_io_mode_t::UInt32 begin + SC_IO_MODE_WRITE = 0 + SC_IO_MODE_APPEND = 1 + SC_IO_MODE_LAST = 2 end """ - p4est_connectivity_new_disk_nonperiodic() + sc_io_encode_t -Create a connectivity structure for a five-tree flat spherical disk. This disk can just as well be used as a square to test non-Cartesian maps. Without any mapping this connectivity covers the square [-3, 3]**2. +Enum to specify encoding for sc_io_sink and sc_io_source. -# Returns -Initialized and usable connectivity. -### Prototype -```c -p4est_connectivity_t *p4est_connectivity_new_disk_nonperiodic (void); -``` +| Enumerator | Note | +| :---------------------- | :--------------------------- | +| SC\\_IO\\_ENCODE\\_NONE | No encoding | +| SC\\_IO\\_ENCODE\\_LAST | Invalid entry to close list | """ -function p4est_connectivity_new_disk_nonperiodic() - @ccall libp4est.p4est_connectivity_new_disk_nonperiodic()::Ptr{p4est_connectivity_t} +@cenum sc_io_encode_t::UInt32 begin + SC_IO_ENCODE_NONE = 0 + SC_IO_ENCODE_LAST = 1 end """ - p4est_connectivity_new_disk(periodic_a, periodic_b) - -Create a connectivity structure for a five-tree flat spherical disk. This disk can just as well be used as a square to test non-Cartesian maps. Without any mapping this connectivity covers the square [-3, 3]**2. - -!!! note - - The API of this function has changed to accept two arguments. You can query the P4EST_CONN_DISK_PERIODIC to check whether the new version with the argument is in effect. - -The ordering of the trees is as follows: - -4 1 2 3 0 - -The outside x faces may be identified topologically. The outside y faces may be identified topologically. Both identifications may be specified simultaneously. The general shape and periodicity are the same as those obtained with p4est_connectivity_new_brick (1, 1, periodic\\_a, periodic\\_b). + sc_io_type_t -When setting *periodic_a* and *periodic_b* to false, the result is the same as that of p4est_connectivity_new_disk_nonperiodic. +The type of I/O operation sc_io_sink and sc_io_source. -# Arguments -* `periodic_a`:\\[in\\] Bool to make disk periodic in x direction. -* `periodic_b`:\\[in\\] Bool to make disk periodic in y direction. -# Returns -Initialized and usable connectivity. -### Prototype -```c -p4est_connectivity_t *p4est_connectivity_new_disk (int periodic_a, int periodic_b); -``` +| Enumerator | Note | +| :------------------------ | :------------------------------- | +| SC\\_IO\\_TYPE\\_BUFFER | Write to a buffer | +| SC\\_IO\\_TYPE\\_FILENAME | Write to a file to be opened | +| SC\\_IO\\_TYPE\\_FILEFILE | Write to an already opened file | +| SC\\_IO\\_TYPE\\_LAST | Invalid entry to close list | """ -function p4est_connectivity_new_disk(periodic_a, periodic_b) - @ccall libp4est.p4est_connectivity_new_disk(periodic_a::Cint, periodic_b::Cint)::Ptr{p4est_connectivity_t} +@cenum sc_io_type_t::UInt32 begin + SC_IO_TYPE_BUFFER = 0 + SC_IO_TYPE_FILENAME = 1 + SC_IO_TYPE_FILEFILE = 2 + SC_IO_TYPE_LAST = 3 end """ - p4est_connectivity_new_icosahedron() - -Create a connectivity for mapping the sphere using an icosahedron. - -The regular icosadron is a polyhedron with 20 faces, each of which is an equilateral triangle. To build the p4est connectivity, we group faces 2 by 2 to from 10 quadrangles, and thus 10 trees. - -This connectivity is meant to be used together with p4est_geometry_new_icosahedron to map the sphere. - -The flat connectivity looks like that. Vextex numbering: - -A00 A01 A02 A03 A04 / \\ / \\ / \\ / \\ / \\ A05---A06---A07---A08---A09---A10 \\ / \\ / \\ / \\ / \\ / \\ A11---A12---A13---A14---A15---A16 \\ / \\ / \\ / \\ / \\ / A17 A18 A19 A20 A21 - -Origin in A05. - -Tree numbering: + sc_io_sink -0 2 4 6 8 1 3 5 7 9 +A generic data sink. -### Prototype -```c -p4est_connectivity_t *p4est_connectivity_new_icosahedron (void); -``` +| Field | Note | +| :------------- | :---------------------------------------------------- | +| iotype | type of the I/O operation | +| mode | write semantics | +| encode | encoding of data | +| buffer | buffer for the iotype SC_IO_TYPE_BUFFER | +| buffer\\_bytes | distinguish from array elements | +| file | file pointer for iotype unequal to SC_IO_TYPE_BUFFER | +| bytes\\_in | input bytes count | +| bytes\\_out | written bytes count | +| is\\_eof | Have we reached the end of file? | """ -function p4est_connectivity_new_icosahedron() - @ccall libp4est.p4est_connectivity_new_icosahedron()::Ptr{p4est_connectivity_t} +struct sc_io_sink + iotype::sc_io_type_t + mode::sc_io_mode_t + encode::sc_io_encode_t + buffer::Ptr{sc_array_t} + buffer_bytes::Csize_t + file::Ptr{Libc.FILE} + bytes_in::Csize_t + bytes_out::Csize_t + is_eof::Cint end +"""A generic data sink.""" +const sc_io_sink_t = sc_io_sink + """ - p4est_connectivity_new_shell2d() + sc_io_source -Create a connectivity structure that builds a 2d spherical shell. p8est_connectivity_new_shell +A generic data source. -### Prototype -```c -p4est_connectivity_t *p4est_connectivity_new_shell2d (void); -``` -""" -function p4est_connectivity_new_shell2d() - @ccall libp4est.p4est_connectivity_new_shell2d()::Ptr{p4est_connectivity_t} +| Field | Note | +| :-------------- | :---------------------------------------------------- | +| iotype | type of the I/O operation | +| encode | encoding of data | +| buffer | buffer for the iotype SC_IO_TYPE_BUFFER | +| buffer\\_bytes | distinguish from array elements | +| file | file pointer for iotype unequal to SC_IO_TYPE_BUFFER | +| bytes\\_in | input bytes count | +| bytes\\_out | read bytes count | +| is\\_eof | Have we reached the end of file? | +| mirror | if activated, a sink to store the data | +| mirror\\_buffer | if activated, the buffer for the mirror | +""" +struct sc_io_source + iotype::sc_io_type_t + encode::sc_io_encode_t + buffer::Ptr{sc_array_t} + buffer_bytes::Csize_t + file::Ptr{Libc.FILE} + bytes_in::Csize_t + bytes_out::Csize_t + is_eof::Cint + mirror::Ptr{sc_io_sink_t} + mirror_buffer::Ptr{sc_array_t} end -""" - p4est_connectivity_new_disk2d() +"""A generic data source.""" +const sc_io_source_t = sc_io_source -Create a connectivity structure that maps a 2d disk. +""" + sc_io_open_mode_t -This is a 5 trees connectivity meant to be used together with p4est_geometry_new_disk2d to map the disk. +Open modes for sc_io_open -### Prototype -```c -p4est_connectivity_t *p4est_connectivity_new_disk2d (void); -``` +| Enumerator | Note | +| :----------------------- | :------------------------------------------------------------------------------------------------------------------ | +| SC\\_IO\\_READ | open a file in read-only mode | +| SC\\_IO\\_WRITE\\_CREATE | open a file in write-only mode; if the file exists, the file will be truncated to length zero and then overwritten | +| SC\\_IO\\_WRITE\\_APPEND | append to an already existing file | """ -function p4est_connectivity_new_disk2d() - @ccall libp4est.p4est_connectivity_new_disk2d()::Ptr{p4est_connectivity_t} +@cenum sc_io_open_mode_t::UInt32 begin + SC_IO_READ = 0 + SC_IO_WRITE_CREATE = 1 + SC_IO_WRITE_APPEND = 2 end -""" - p4est_connectivity_new_bowtie() - -Create a connectivity structure that maps a 2d bowtie structure. +# automatic type deduction for variadic arguments may not be what you want, please use with caution +@generated function sc_io_sink_new(iotype, iomode, ioencode, va_list...) + :(@ccall(libsc.sc_io_sink_new(iotype::Cint, iomode::Cint, ioencode::Cint; $(to_c_type_pairs(va_list)...))::Ptr{sc_io_sink_t})) + end -The 2 trees are connected by a corner connection at node A3 (0, 0). the nodes are given as: +""" + sc_io_sink_destroy(sink) -A00 A01 / \\ / \\ A02 A03 A04 \\ / \\ / A05 A06 +Free data sink. Calls [`sc_io_sink_complete`](@ref) and discards the final counts. Errors from complete lead to SC\\_IO\\_ERROR\\_FATAL returned from this function. Call [`sc_io_sink_complete`](@ref) yourself if bytes\\_out is of interest. +# Arguments +* `sink`:\\[in,out\\] The sink object to complete and free. +# Returns +0 on success, nonzero on error. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_bowtie (void); +int sc_io_sink_destroy (sc_io_sink_t * sink); ``` """ -function p4est_connectivity_new_bowtie() - @ccall libp4est.p4est_connectivity_new_bowtie()::Ptr{p4est_connectivity_t} +function sc_io_sink_destroy(sink) + @ccall libsc.sc_io_sink_destroy(sink::Ptr{sc_io_sink_t})::Cint end """ - p4est_connectivity_new_brick(mi, ni, periodic_a, periodic_b) + sc_io_sink_destroy_null(sink) -A rectangular m by n array of trees with configurable periodicity. The brick is periodic in x and y if periodic\\_a and periodic\\_b are true, respectively. +Free data sink and NULL the pointer to it. Except for the handling of the pointer argument, the behavior is the same as for sc_io_sink_destroy. +# Arguments +* `sink`:\\[in,out\\] Non-NULL pointer to sink pointer. The sink pointer may be NULL, in which case this function does nothing successfully, or a valid sc_io_sink, which is passed to sc_io_sink_destroy, and the sink pointer is set to NULL afterwards. +# Returns +0 on success, nonzero on error. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_brick (int mi, int ni, int periodic_a, int periodic_b); +int sc_io_sink_destroy_null (sc_io_sink_t ** sink); ``` """ -function p4est_connectivity_new_brick(mi, ni, periodic_a, periodic_b) - @ccall libp4est.p4est_connectivity_new_brick(mi::Cint, ni::Cint, periodic_a::Cint, periodic_b::Cint)::Ptr{p4est_connectivity_t} +function sc_io_sink_destroy_null(sink) + @ccall libsc.sc_io_sink_destroy_null(sink::Ptr{Ptr{sc_io_sink_t}})::Cint end """ - p4est_connectivity_new_byname(name) + sc_io_sink_write(sink, data, bytes_avail) -Create connectivity structure from predefined catalogue. +Write data to a sink. Data may be buffered and sunk in a later call. The internal counters sink->bytes\\_in and sink->bytes\\_out are updated. # Arguments -* `name`:\\[in\\] Invokes connectivity\\_new\\_* function. brick23 brick (2, 3, 0, 0) corner corner cubed cubed disk disk moebius moebius periodic periodic pillow pillow rotwrap rotwrap star star unit unitsquare +* `sink`:\\[in,out\\] The sink object to write to. +* `data`:\\[in\\] Data passed into sink must be non-NULL. +* `bytes_avail`:\\[in\\] Number of data bytes passed in. # Returns -An initialized connectivity if name is defined, NULL else. +0 on success, nonzero on error. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_new_byname (const char *name); +int sc_io_sink_write (sc_io_sink_t * sink, const void *data, size_t bytes_avail); ``` """ -function p4est_connectivity_new_byname(name) - @ccall libp4est.p4est_connectivity_new_byname(name::Cstring)::Ptr{p4est_connectivity_t} +function sc_io_sink_write(sink, data, bytes_avail) + @ccall libsc.sc_io_sink_write(sink::Ptr{sc_io_sink_t}, data::Ptr{Cvoid}, bytes_avail::Csize_t)::Cint end """ - p4est_connectivity_refine(conn, num_per_dim) + sc_io_sink_complete(sink, bytes_in, bytes_out) -Uniformly refine a connectivity. This is useful if you would like to uniformly refine by something other than a power of 2. +Flush all buffered output data to sink. This function may return SC\\_IO\\_ERROR\\_AGAIN if another write is required. Currently this may happen if BUFFER requires an integer multiple of bytes. If successful, the updated value of bytes read and written is returned in bytes\\_in/out, and the sink status is reset as if the sink had just been created. In particular, the bytes counters are reset to zero. The internal state of the sink is not changed otherwise. It is legal to continue writing to the sink hereafter. The sink actions taken depend on its type. BUFFER, FILEFILE: none. FILENAME: call fclose on sink->file. # Arguments -* `conn`:\\[in\\] A valid connectivity -* `num_per_dim`:\\[in\\] The number of new trees in each direction. Must use no more than P4EST_OLD_QMAXLEVEL bits. +* `sink`:\\[in,out\\] The sink object to write to. +* `bytes_in`:\\[in,out\\] Bytes received since the last new or complete call. May be NULL. +* `bytes_out`:\\[in,out\\] Bytes written since the last new or complete call. May be NULL. # Returns -a refined connectivity. +0 if completed, nonzero on error. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_refine (p4est_connectivity_t * conn, int num_per_dim); +int sc_io_sink_complete (sc_io_sink_t * sink, size_t *bytes_in, size_t *bytes_out); ``` """ -function p4est_connectivity_refine(conn, num_per_dim) - @ccall libp4est.p4est_connectivity_refine(conn::Ptr{p4est_connectivity_t}, num_per_dim::Cint)::Ptr{p4est_connectivity_t} +function sc_io_sink_complete(sink, bytes_in, bytes_out) + @ccall libsc.sc_io_sink_complete(sink::Ptr{sc_io_sink_t}, bytes_in::Ptr{Csize_t}, bytes_out::Ptr{Csize_t})::Cint end """ - p4est_expand_face_transform(iface, nface, ftransform) + sc_io_sink_align(sink, bytes_align) -Fill an array with the axis combination of a face neighbor transform. +Align sink to a byte boundary by writing zeros. # Arguments -* `iface`:\\[in\\] The number of the originating face. -* `nface`:\\[in\\] Encoded as nface = r * 4 + nf, where nf = 0..3 is the neigbbor's connecting face number and r = 0..1 is the relative orientation to the neighbor's face. This encoding matches [`p4est_connectivity_t`](@ref). -* `ftransform`:\\[out\\] This array holds 9 integers. [0,2] The coordinate axis sequence of the origin face, the first referring to the tangential and the second to the normal. A permutation of (0, 1). [3,5] The coordinate axis sequence of the target face. [6,8] Face reversal flag for tangential axis (boolean); face code in [0, 3] for the normal coordinate q: 0: q' = -q 1: q' = q + 1 2: q' = q - 1 3: q' = 2 - q [1,4,7] 0 (unused for compatibility with 3D). +* `sink`:\\[in,out\\] The sink object to align. +* `bytes_align`:\\[in\\] Byte boundary. +# Returns +0 on success, nonzero on error. ### Prototype ```c -void p4est_expand_face_transform (int iface, int nface, int ftransform[]); +int sc_io_sink_align (sc_io_sink_t * sink, size_t bytes_align); ``` """ -function p4est_expand_face_transform(iface, nface, ftransform) - @ccall libp4est.p4est_expand_face_transform(iface::Cint, nface::Cint, ftransform::Ptr{Cint})::Cvoid +function sc_io_sink_align(sink, bytes_align) + @ccall libsc.sc_io_sink_align(sink::Ptr{sc_io_sink_t}, bytes_align::Csize_t)::Cint end +# automatic type deduction for variadic arguments may not be what you want, please use with caution +@generated function sc_io_source_new(iotype, ioencode, va_list...) + :(@ccall(libsc.sc_io_source_new(iotype::Cint, ioencode::Cint; $(to_c_type_pairs(va_list)...))::Ptr{sc_io_source_t})) + end + """ - p4est_find_face_transform(connectivity, itree, iface, ftransform) + sc_io_source_destroy(source) -Fill an array with the axis combinations of a tree neighbor transform. +Free data source. Calls [`sc_io_source_complete`](@ref) and requires it to return no error. This is to avoid discarding buffered data that has not been passed to read. # Arguments -* `connectivity`:\\[in\\] Connectivity structure. -* `itree`:\\[in\\] The number of the originating tree. -* `iface`:\\[in\\] The number of the originating tree's face. -* `ftransform`:\\[out\\] This array holds 9 integers. [0,2] The coordinate axis sequence of the origin face. [3,5] The coordinate axis sequence of the target face. [6,8] Face reversal flag for axis t; face code for axis n. +* `source`:\\[in,out\\] The source object to free. # Returns -The face neighbor tree if it exists, -1 otherwise. -# See also -[`p4est_expand_face_transform`](@ref). [1,4,7] 0 (unused for compatibility with 3D). - +0 on success. Nonzero if an error is encountered or is\\_complete returns one. ### Prototype ```c -p4est_topidx_t p4est_find_face_transform (p4est_connectivity_t * connectivity, p4est_topidx_t itree, int iface, int ftransform[]); +int sc_io_source_destroy (sc_io_source_t * source); ``` """ -function p4est_find_face_transform(connectivity, itree, iface, ftransform) - @ccall libp4est.p4est_find_face_transform(connectivity::Ptr{p4est_connectivity_t}, itree::p4est_topidx_t, iface::Cint, ftransform::Ptr{Cint})::p4est_topidx_t +function sc_io_source_destroy(source) + @ccall libsc.sc_io_source_destroy(source::Ptr{sc_io_source_t})::Cint end """ - p4est_find_corner_transform(connectivity, itree, icorner, ci) + sc_io_source_destroy_null(source) -Fills an array with information about corner neighbors. +Free data source and NULL the pointer to it. Except for the handling of the pointer argument, the behavior is the same as for sc_io_source_destroy. # Arguments -* `connectivity`:\\[in\\] Connectivity structure. -* `itree`:\\[in\\] The number of the originating tree. -* `icorner`:\\[in\\] The number of the originating corner. -* `ci`:\\[in,out\\] A [`p4est_corner_info_t`](@ref) structure with initialized array. +* `source`:\\[in,out\\] Non-NULL pointer to source pointer. The source pointer may be NULL, in which case this function does nothing successfully, or a valid sc_io_source, which is passed to sc_io_source_destroy, and the source pointer is set to NULL afterwards. +# Returns +0 on success, nonzero on error. ### Prototype ```c -void p4est_find_corner_transform (p4est_connectivity_t * connectivity, p4est_topidx_t itree, int icorner, p4est_corner_info_t * ci); +int sc_io_source_destroy_null (sc_io_source_t ** source); ``` """ -function p4est_find_corner_transform(connectivity, itree, icorner, ci) - @ccall libp4est.p4est_find_corner_transform(connectivity::Ptr{p4est_connectivity_t}, itree::p4est_topidx_t, icorner::Cint, ci::Ptr{p4est_corner_info_t})::Cvoid +function sc_io_source_destroy_null(source) + @ccall libsc.sc_io_source_destroy_null(source::Ptr{Ptr{sc_io_source_t}})::Cint end """ - p4est_connectivity_complete(conn) + sc_io_source_read(source, data, bytes_avail, bytes_out) -Internally connect a connectivity based on tree\\_to\\_vertex information. Periodicity that is not inherent in the list of vertices will be lost. +Read data from a source. The internal counters source->bytes\\_in and source->bytes\\_out are updated. Data is read until the data buffer has not enough room anymore, or source becomes empty. It is possible that data already read internally remains in the source object for the next call. Call [`sc_io_source_complete`](@ref) and check its return value to find out. Returns an error if bytes\\_out is NULL and less than bytes\\_avail are read. # Arguments -* `conn`:\\[in,out\\] The connectivity needs to have proper vertices and tree\\_to\\_vertex fields. The tree\\_to\\_tree and tree\\_to\\_face fields must be allocated and satisfy [`p4est_connectivity_is_valid`](@ref) (conn) but will be overwritten. The corner fields will be freed and allocated anew. +* `source`:\\[in,out\\] The source object to read from. +* `data`:\\[in\\] Data buffer for reading from source. If NULL the output data will be ignored and we seek forward in the input. +* `bytes_avail`:\\[in\\] Number of bytes available in data buffer. +* `bytes_out`:\\[in,out\\] If not NULL, byte count read into data buffer. Otherwise, requires to read exactly bytes\\_avail. If this condition is not met, return an error. +# Returns +0 on success, nonzero on error. ### Prototype ```c -void p4est_connectivity_complete (p4est_connectivity_t * conn); +int sc_io_source_read (sc_io_source_t * source, void *data, size_t bytes_avail, size_t *bytes_out); ``` """ -function p4est_connectivity_complete(conn) - @ccall libp4est.p4est_connectivity_complete(conn::Ptr{p4est_connectivity_t})::Cvoid +function sc_io_source_read(source, data, bytes_avail, bytes_out) + @ccall libsc.sc_io_source_read(source::Ptr{sc_io_source_t}, data::Ptr{Cvoid}, bytes_avail::Csize_t, bytes_out::Ptr{Csize_t})::Cint end """ - p4est_connectivity_reduce(conn) + sc_io_source_complete(source, bytes_in, bytes_out) -Removes corner information of a connectivity such that enough information is left to run [`p4est_connectivity_complete`](@ref) successfully. The reduced connectivity still passes [`p4est_connectivity_is_valid`](@ref). +Determine whether all data buffered from source has been returned by read. If it returns SC\\_IO\\_ERROR\\_AGAIN, another [`sc_io_source_read`](@ref) is required. If the call returns no error, the internal counters source->bytes\\_in and source->bytes\\_out are returned to the caller if requested, and reset to 0. The internal state of the source is not changed otherwise. It is legal to continue reading from the source hereafter. # Arguments -* `conn`:\\[in,out\\] The connectivity to be reduced. +* `source`:\\[in,out\\] The source object to read from. +* `bytes_in`:\\[in,out\\] If not NULL and true is returned, the total size of the data sourced. +* `bytes_out`:\\[in,out\\] If not NULL and true is returned, total bytes passed out by source\\_read. +# Returns +SC\\_IO\\_ERROR\\_AGAIN if buffered data remaining. Otherwise return ERROR\\_NONE and reset counters. ### Prototype ```c -void p4est_connectivity_reduce (p4est_connectivity_t * conn); +int sc_io_source_complete (sc_io_source_t * source, size_t *bytes_in, size_t *bytes_out); ``` """ -function p4est_connectivity_reduce(conn) - @ccall libp4est.p4est_connectivity_reduce(conn::Ptr{p4est_connectivity_t})::Cvoid +function sc_io_source_complete(source, bytes_in, bytes_out) + @ccall libsc.sc_io_source_complete(source::Ptr{sc_io_source_t}, bytes_in::Ptr{Csize_t}, bytes_out::Ptr{Csize_t})::Cint end """ - p4est_connectivity_permute(conn, perm, is_current_to_new) + sc_io_source_align(source, bytes_align) -[`p4est_connectivity_permute`](@ref) Given a permutation *perm* of the trees in a connectivity *conn*, permute the trees of *conn* in place and update *conn* to match. +Align source to a byte boundary by skipping. # Arguments -* `conn`:\\[in,out\\] The connectivity whose trees are permuted. -* `perm`:\\[in\\] A permutation array, whose elements are size\\_t's. -* `is_current_to_new`:\\[in\\] if true, the jth entry of perm is the new index for the entry whose current index is j, otherwise the jth entry of perm is the current index of the tree whose index will be j after the permutation. +* `source`:\\[in,out\\] The source object to align. +* `bytes_align`:\\[in\\] Byte boundary. +# Returns +0 on success, nonzero on error. ### Prototype ```c -void p4est_connectivity_permute (p4est_connectivity_t * conn, sc_array_t * perm, int is_current_to_new); +int sc_io_source_align (sc_io_source_t * source, size_t bytes_align); ``` """ -function p4est_connectivity_permute(conn, perm, is_current_to_new) - @ccall libp4est.p4est_connectivity_permute(conn::Ptr{p4est_connectivity_t}, perm::Ptr{sc_array_t}, is_current_to_new::Cint)::Cvoid +function sc_io_source_align(source, bytes_align) + @ccall libsc.sc_io_source_align(source::Ptr{sc_io_source_t}, bytes_align::Csize_t)::Cint end """ - p4est_connectivity_join_faces(conn, tree_left, tree_right, face_left, face_right, orientation) + sc_io_source_activate_mirror(source) -[`p4est_connectivity_join_faces`](@ref) This function takes an existing valid connectivity *conn* and modifies it by joining two tree faces that are currently boundary faces. +Activate a buffer that mirrors (i.e., stores) the data that was read. # Arguments -* `conn`:\\[in,out\\] connectivity that will be altered. -* `tree_left`:\\[in\\] tree that will be on the left side of the joined faces. -* `tree_right`:\\[in\\] tree that will be on the right side of the joined faces. -* `face_left`:\\[in\\] face of *tree_left* that will be joined. -* `face_right`:\\[in\\] face of *tree_right* that will be joined. -* `orientation`:\\[in\\] the orientation of *face_left* and *face_right* once joined (see the description of [`p4est_connectivity_t`](@ref) to understand orientation). +* `source`:\\[in,out\\] The source object to activate mirror in. +# Returns +0 on success, nonzero on error. ### Prototype ```c -void p4est_connectivity_join_faces (p4est_connectivity_t * conn, p4est_topidx_t tree_left, p4est_topidx_t tree_right, int face_left, int face_right, int orientation); +int sc_io_source_activate_mirror (sc_io_source_t * source); ``` """ -function p4est_connectivity_join_faces(conn, tree_left, tree_right, face_left, face_right, orientation) - @ccall libp4est.p4est_connectivity_join_faces(conn::Ptr{p4est_connectivity_t}, tree_left::p4est_topidx_t, tree_right::p4est_topidx_t, face_left::Cint, face_right::Cint, orientation::Cint)::Cvoid +function sc_io_source_activate_mirror(source) + @ccall libsc.sc_io_source_activate_mirror(source::Ptr{sc_io_source_t})::Cint end """ - p4est_connectivity_is_equivalent(conn1, conn2) + sc_io_source_read_mirror(source, data, bytes_avail, bytes_out) -[`p4est_connectivity_is_equivalent`](@ref) This function compares two connectivities for equivalence: it returns *true* if they are the same connectivity, or if they have the same topology. The definition of topological sameness is strict: there is no attempt made to determine whether permutation and/or rotation of the trees makes the connectivities equivalent. +Read data from the source's mirror. Same behaviour as [`sc_io_source_read`](@ref). # Arguments -* `conn1`:\\[in\\] a valid connectivity -* `conn2`:\\[out\\] a valid connectivity -### Prototype -```c -int p4est_connectivity_is_equivalent (p4est_connectivity_t * conn1, p4est_connectivity_t * conn2); +* `source`:\\[in,out\\] The source object to read mirror data from. +* `data`:\\[in\\] Data buffer for reading from source's mirror. If NULL the output data will be thrown away. +* `bytes_avail`:\\[in\\] Number of bytes available in data buffer. +* `bytes_out`:\\[in,out\\] If not NULL, byte count read into data buffer. Otherwise, requires to read exactly bytes\\_avail. +# Returns +0 on success, nonzero on error. +### Prototype +```c +int sc_io_source_read_mirror (sc_io_source_t * source, void *data, size_t bytes_avail, size_t *bytes_out); ``` """ -function p4est_connectivity_is_equivalent(conn1, conn2) - @ccall libp4est.p4est_connectivity_is_equivalent(conn1::Ptr{p4est_connectivity_t}, conn2::Ptr{p4est_connectivity_t})::Cint +function sc_io_source_read_mirror(source, data, bytes_avail, bytes_out) + @ccall libsc.sc_io_source_read_mirror(source::Ptr{sc_io_source_t}, data::Ptr{Cvoid}, bytes_avail::Csize_t, bytes_out::Ptr{Csize_t})::Cint end """ - p4est_corner_array_index(array, it) + sc_io_file_save(filename, buffer) +Save a buffer to a file in one call. This function performs error checking and always returns cleanly. + +# Arguments +* `filename`:\\[in\\] Name of the file to save. +* `buffer`:\\[in\\] An array of element size 1 and arbitrary contents, which are written to the file. +# Returns +0 on success, -1 on error. ### Prototype ```c -static inline p4est_corner_transform_t * p4est_corner_array_index (sc_array_t * array, size_t it); +int sc_io_file_save (const char *filename, sc_array_t * buffer); ``` """ -function p4est_corner_array_index(array, it) - @ccall libp4est.p4est_corner_array_index(array::Ptr{sc_array_t}, it::Csize_t)::Ptr{p4est_corner_transform_t} +function sc_io_file_save(filename, buffer) + @ccall libsc.sc_io_file_save(filename::Cstring, buffer::Ptr{sc_array_t})::Cint end """ - p4est_connectivity_read_inp_stream(stream, num_vertices, num_trees, vertices, tree_to_vertex) - -Read an ABAQUS input file from a file stream. - -This utility function reads a basic ABAQUS file supporting element type with the prefix C2D4, CPS4, and S4 in 2D and of type C3D8 reading them as bilinear quadrilateral and trilinear hexahedral trees respectively. + sc_io_file_load(filename, buffer) -A basic 2D mesh is given below. The `*Node` section gives the vertex number and x, y, and z components for each vertex. The `*Element` section gives the 4 vertices in 2D (8 vertices in 3D) of each element in counter clockwise order. So in 2D the nodes are given as: +Read a file into a buffer in one call. This function performs error checking and always returns cleanly. -4 3 +-------------------+ | | | | | | | | | | | | +-------------------+ 1 2 +# Arguments +* `filename`:\\[in\\] Name of the file to load. +* `buffer`:\\[in,out\\] On input, an array (not a view) of element size 1 and arbitrary contents. On output and success, the complete file contents. On error, contents are undefined. +# Returns +0 on success, -1 on error. +### Prototype +```c +int sc_io_file_load (const char *filename, sc_array_t * buffer); +``` +""" +function sc_io_file_load(filename, buffer) + @ccall libsc.sc_io_file_load(filename::Cstring, buffer::Ptr{sc_array_t})::Cint +end -and in 3D they are given as: +""" + sc_io_encode(data, out) -8 7 +---------------------+ |\\ |\\ | \\ | \\ | \\ | \\ | \\ | \\ | 5+---------------------+6 | | | | +----|----------------+ | 4\\ | 3 \\ | \\ | \\ | \\ | \\ | \\| \\| +---------------------+ 1 2 +Encode a block of arbitrary data with the default sc\\_io format. The corresponding decoder function is sc_io_decode. This function cannot crash unless out of memory. -```c++ - *Heading - box.inp - *Node - 1, -5, -5, 0 - 2, 5, -5, 0 - 3, 5, 5, 0 - 4, -5, 5, 0 - 5, 0, -5, 0 - 6, 5, 0, 0 - 7, 0, 5, 0 - 8, -5, 0, 0 - 9, 1, -1, 0 - 10, 0, 0, 0 - 11, -2, 1, 0 - *Element, type=CPS4, ELSET=Surface1 - 1, 1, 10, 11, 8 - 2, 3, 10, 9, 6 - 3, 9, 10, 1, 5 - 4, 7, 4, 8, 11 - 5, 11, 10, 3, 7 - 6, 2, 6, 9, 5 -``` +Currently this function calls sc_io_encode_zlib with compression level Z\\_BEST\\_COMPRESSION (subject to change). Without zlib configured that function works uncompressed. -This code can be called two ways. The first, when `vertex`==NULL and `tree_to_vertex`==NULL, is used to count the number of trees and vertices in the connectivity to be generated by the `.inp` mesh in the *stream*. The second, when `vertices`!=NULL and `tree_to_vertex`!=NULL, fill `vertices` and `tree_to_vertex`. In this case `num_vertices` and `num_trees` need to be set to the maximum number of entries allocated in `vertices` and `tree_to_vertex`. +The encoding method and input data size can be retrieved, optionally, from the encoded data by sc_io_decode_info. This function decodes the method as a character, which is 'z' for sc_io_encode_zlib. We reserve the characters A-C, d-z indefinitely. # Arguments -* `stream`:\\[in,out\\] file stream to read the connectivity from -* `num_vertices`:\\[in,out\\] the number of vertices in the connectivity -* `num_trees`:\\[in,out\\] the number of trees in the connectivity -* `vertices`:\\[out\\] the list of `vertices` of the connectivity -* `tree_to_vertex`:\\[out\\] the `tree_to_vertex` map of the connectivity -# Returns -0 if successful and nonzero if not +* `data`:\\[in,out\\] If *out* is NULL, we work in place. In this case, the array must on input have an element size of 1 byte, which is preserved. After reading all data from this array, it assumes the identity of the *out* argument below. Otherwise, this is a read-only argument that may have arbitrary element size. On input, all data in the array is used. +* `out`:\\[in,out\\] If not NULL, a valid array of element size 1. It must be resizable (not a view). We resize the array to the output data, which always includes a final terminating zero. ### Prototype ```c -int p4est_connectivity_read_inp_stream (FILE * stream, p4est_topidx_t * num_vertices, p4est_topidx_t * num_trees, double *vertices, p4est_topidx_t * tree_to_vertex); +void sc_io_encode (sc_array_t *data, sc_array_t *out); ``` """ -function p4est_connectivity_read_inp_stream(stream, num_vertices, num_trees, vertices, tree_to_vertex) - @ccall libp4est.p4est_connectivity_read_inp_stream(stream::Ptr{Libc.FILE}, num_vertices::Ptr{p4est_topidx_t}, num_trees::Ptr{p4est_topidx_t}, vertices::Ptr{Cdouble}, tree_to_vertex::Ptr{p4est_topidx_t})::Cint +function sc_io_encode(data, out) + @ccall libsc.sc_io_encode(data::Ptr{sc_array_t}, out::Ptr{sc_array_t})::Cvoid end """ - p4est_connectivity_read_inp(filename) + sc_io_encode_zlib(data, out, zlib_compression_level, line_break_character) -Create a p4est connectivity from an ABAQUS input file. +Encode a block of arbitrary data, compressed, into an ASCII string. This is a two-stage process: zlib compress and then encode to base 64. The output is a NUL-terminated string of printable characters. -This utility function reads a basic ABAQUS file supporting element type with the prefix C2D4, CPS4, and S4 in 2D and of type C3D8 reading them as bilinear quadrilateral and trilinear hexahedral trees respectively. +We first compress the data into the zlib deflate format (RFC 1951). The compressor must use no preset dictionary (this is the default). If zlib is detected on configuration, we compress with the given level. If zlib is not detected, we write data equivalent to Z\\_NO\\_COMPRESSION. The status of zlib detection can be queried at compile time using #ifdef [`SC_HAVE_ZLIB`](@ref) or at run time using sc_have_zlib. Both types of result are readable by a standard zlib uncompress call. -A basic 2D mesh is given below. The `*Node` section gives the vertex number and x, y, and z components for each vertex. The `*Element` section gives the 4 vertices in 2D (8 vertices in 3D) of each element in counter clockwise order. So in 2D the nodes are given as: +Secondly, we process the input data size as an 8-byte big-endian number, then the letter 'z', and then the zlib compressed data, concatenated, with a base 64 encoder. We break lines after 76 code characters. Each line break consists of two configurable but arbitrary bytes. The line breaks are considered part of the output data specification. The last line is terminated with the same line break and then a NUL. -4 3 +-------------------+ | | | | | | | | | | | | +-------------------+ 1 2 +This routine can work in place or write to an output array. The corresponding decoder function is sc_io_decode. This function cannot crash unless out of memory. -and in 3D they are given as: +# Arguments +* `data`:\\[in,out\\] If *out* is NULL, we work in place. In this case, the array must on input have an element size of 1 byte, which is preserved. After reading all data from this array, it assumes the identity of the *out* argument below. Otherwise, this is a read-only argument that may have arbitrary element size. On input, all data in the array is used. +* `out`:\\[in,out\\] If not NULL, a valid array of element size 1. It must be resizable (not a view). We resize the array to the output data, which always includes a final terminating zero. +* `zlib_compression_level`:\\[in\\] Compression level between 0 (no compression) and 9 (best compression). The value -1 indicates some default level. +* `line_break_character`:\\[in\\] This character is arbitrary and specifies the first of two line break bytes. The second byte is always ''. +### Prototype +```c +void sc_io_encode_zlib (sc_array_t *data, sc_array_t *out, int zlib_compression_level, int line_break_character); +``` +""" +function sc_io_encode_zlib(data, out, zlib_compression_level, line_break_character) + @ccall libsc.sc_io_encode_zlib(data::Ptr{sc_array_t}, out::Ptr{sc_array_t}, zlib_compression_level::Cint, line_break_character::Cint)::Cvoid +end -8 7 +---------------------+ |\\ |\\ | \\ | \\ | \\ | \\ | \\ | \\ | 5+---------------------+6 | | | | +----|----------------+ | 4\\ | 3 \\ | \\ | \\ | \\ | \\ | \\| \\| +---------------------+ 1 2 +""" + sc_io_decode_info(data, original_size, format_char, re) -```c++ - *Heading - box.inp - *Node - 1, -5, -5, 0 - 2, 5, -5, 0 - 3, 5, 5, 0 - 4, -5, 5, 0 - 5, 0, -5, 0 - 6, 5, 0, 0 - 7, 0, 5, 0 - 8, -5, 0, 0 - 9, 1, -1, 0 - 10, 0, 0, 0 - 11, -2, 1, 0 - *Element, type=CPS4, ELSET=Surface1 - 1, 1, 10, 11, 8 - 2, 3, 10, 9, 6 - 3, 9, 10, 1, 5 - 4, 7, 4, 8, 11 - 5, 11, 10, 3, 7 - 6, 2, 6, 9, 5 -``` +Decode length and format of original input from encoded data. We expect at least 12 bytes of the format produced by sc_io_encode. No matter how much data has been encoded by it, this much is available. We decode the original data size and the character indicating the format. -This function reads a mesh from *filename* and returns an associated p4est connectivity. +This function does not require zlib. It works with any well-defined data. + +Note that this function is not required before sc_io_decode. Calling this function on any result produced by sc_io_encode will succeed and report a legal format. This function cannot crash. # Arguments -* `filename`:\\[in\\] file to read the connectivity from +* `data`:\\[in\\] This must be an array with element size 1. If it contains less than 12 code bytes we error out. It its first 12 bytes do not base 64 decode to 9 bytes we error out. We generally ignore the remaining data. +* `original_size`:\\[out\\] If not NULL and we do not error out, set to the original size as encoded in the data. +* `format_char`:\\[out\\] If not NULL and we do not error out, the ninth character of decoded data indicating the format. +* `re`:\\[in,out\\] Provided for error reporting, presently must be NULL. # Returns -an allocated connectivity associated with the mesh in *filename* or NULL if an error occurred. +0 on success, negative value on error. ### Prototype ```c -p4est_connectivity_t *p4est_connectivity_read_inp (const char *filename); +int sc_io_decode_info (sc_array_t *data, size_t *original_size, char *format_char, void *re); ``` """ -function p4est_connectivity_read_inp(filename) - @ccall libp4est.p4est_connectivity_read_inp(filename::Cstring)::Ptr{p4est_connectivity_t} +function sc_io_decode_info(data, original_size, format_char, re) + @ccall libsc.sc_io_decode_info(data::Ptr{sc_array_t}, original_size::Ptr{Csize_t}, format_char::Cstring, re::Ptr{Cvoid})::Cint end """ - p8est_connect_type_t + sc_io_decode(data, out, max_original_size, re) -Characterize a type of adjacency. +Decode a block of base 64 encoded compressed data. The base 64 data must contain two arbitrary bytes after every 76 code characters and also at the end of the last line if it is short, and then a final NUL character. This function does not require zlib but benefits for speed. -Several functions involve relationships between neighboring trees and/or quadrants, and their behavior depends on how one defines adjacency: 1) entities are adjacent if they share a face, or 2) entities are adjacent if they share a face or corner, or 3) entities are adjacent if they share a face, corner or edge. [`p8est_connect_type_t`](@ref) is used to choose the desired behavior. This enum must fit into an int8\\_t. +This is a two-stage process: we decode the input from base 64 first. Then we extract the 8-byte big-endian original data size, the character 'z', and execute a zlib decompression on the remaining decoded data. This function detects malformed input by erroring out. -| Enumerator | Note | -| :----------------------- | :------------------------------- | -| P8EST\\_CONNECT\\_SELF | No balance whatsoever. | -| P8EST\\_CONNECT\\_FACE | Balance across faces only. | -| P8EST\\_CONNECT\\_EDGE | Balance across faces and edges. | -| P8EST\\_CONNECT\\_ALMOST | = CORNER - 1. | -| P8EST\\_CONNECT\\_CORNER | Balance faces, edges, corners. | -| P8EST\\_CONNECT\\_FULL | = CORNER. | -""" -@cenum p8est_connect_type_t::UInt32 begin - P8EST_CONNECT_SELF = 30 - P8EST_CONNECT_FACE = 31 - P8EST_CONNECT_EDGE = 32 - P8EST_CONNECT_ALMOST = 32 - P8EST_CONNECT_CORNER = 33 - P8EST_CONNECT_FULL = 33 -end +If we should add another format in the future, the format character may be something else than 'z', as permitted by our specification. To this end, we reserve the characters A-C and d-z indefinitely. -""" - p8est_connectivity_encode_t +Any error condition is indicated by a negative return value. Possible causes for error are: -Typedef for serialization method. +- the input data string is not NUL-terminated - the first 12 characters of input do not decode properly - the input data is corrupt for decoding or decompression - the output data array has non-unit element size and the length of the output data is not divisible by the size - the output data would exceed the specified threshold - the output array is a view of insufficient length -| Enumerator | Note | -| :--------------------------- | :-------------------------------- | -| P8EST\\_CONN\\_ENCODE\\_LAST | Invalid entry to close the list. | +We also error out if the data requires a compression dictionary, which would be a violation of above encode format specification. + +The corresponding encode function is sc_io_encode. When passing an array as output, we resize it properly. This function cannot crash unless out of memory. + +# Arguments +* `data`:\\[in,out\\] If *out* is NULL, we work in place. In that case, output is written into this array after a suitable resize. Either way, we expect a NUL-terminated base 64 encoded string on input that has in turn been obtained by zlib compression. It must be in the exact format produced by sc_io_encode; please see documentation. The element size of the input array must be 1. +* `out`:\\[in,out\\] If not NULL, a valid array (may be a view). If NULL, the input array becomes the output. If the output array is a view and the output data larger than its view size, we error out. We expect commensurable element and data size and resize the output to fit exactly, which restores the original input passed to encoding. An output view array of matching size may be constructed using sc_io_decode_info. +* `max_original_size`:\\[in\\] If nonzero, this is the maximal data size that we will accept after uncompression. If exceeded, return a negative value. +* `re`:\\[in,out\\] Provided for error reporting, presently must be NULL. +# Returns +0 on success, negative on malformed input data or insufficient output space. +### Prototype +```c +int sc_io_decode (sc_array_t *data, sc_array_t *out, size_t max_original_size, void *re); +``` """ -@cenum p8est_connectivity_encode_t::UInt32 begin - P8EST_CONN_ENCODE_NONE = 0 - P8EST_CONN_ENCODE_LAST = 1 +function sc_io_decode(data, out, max_original_size, re) + @ccall libsc.sc_io_decode(data::Ptr{sc_array_t}, out::Ptr{sc_array_t}, max_original_size::Csize_t, re::Ptr{Cvoid})::Cint end """ - p8est_connect_type_int(btype) + sc_vtk_write_binary(vtkfile, numeric_data, byte_length) -Convert the [`p8est_connect_type_t`](@ref) into a number. +This function writes numeric binary data in VTK base64 encoding. # Arguments -* `btype`:\\[in\\] The balance type to convert. +* `vtkfile`: Stream opened for writing. +* `numeric_data`: A pointer to a numeric data array. +* `byte_length`: The length of the data array in bytes. # Returns -Returns 1, 2 or 3. +Returns 0 on success, -1 on file error. ### Prototype ```c -int p8est_connect_type_int (p8est_connect_type_t btype); +int sc_vtk_write_binary (FILE * vtkfile, char *numeric_data, size_t byte_length); ``` """ -function p8est_connect_type_int(btype) - @ccall libp4est.p8est_connect_type_int(btype::p8est_connect_type_t)::Cint +function sc_vtk_write_binary(vtkfile, numeric_data, byte_length) + @ccall libsc.sc_vtk_write_binary(vtkfile::Ptr{Libc.FILE}, numeric_data::Cstring, byte_length::Csize_t)::Cint end """ - p8est_connect_type_string(btype) + sc_vtk_write_compressed(vtkfile, numeric_data, byte_length) -Convert the [`p8est_connect_type_t`](@ref) into a const string. +This function writes numeric binary data in VTK compressed format. # Arguments -* `btype`:\\[in\\] The balance type to convert. +* `vtkfile`: Stream opened for writing. +* `numeric_data`: A pointer to a numeric data array. +* `byte_length`: The length of the data array in bytes. # Returns -Returns a pointer to a constant string. +Returns 0 on success, -1 on file error. ### Prototype ```c -const char *p8est_connect_type_string (p8est_connect_type_t btype); +int sc_vtk_write_compressed (FILE * vtkfile, char *numeric_data, size_t byte_length); ``` """ -function p8est_connect_type_string(btype) - @ccall libp4est.p8est_connect_type_string(btype::p8est_connect_type_t)::Cstring +function sc_vtk_write_compressed(vtkfile, numeric_data, byte_length) + @ccall libsc.sc_vtk_write_compressed(vtkfile::Ptr{Libc.FILE}, numeric_data::Cstring, byte_length::Csize_t)::Cint end """ - p8est_connectivity - -This structure holds the 3D inter-tree connectivity information. Identification of arbitrary faces, edges and corners is possible. + sc_fopen(filename, mode, errmsg) -The arrays tree\\_to\\_* are stored in z ordering. For corners the order wrt. zyx is 000 001 010 011 100 101 110 111. For faces the order is -x +x -y +y -z +z. They are allocated [0][0]..[0][N-1]..[num\\_trees-1][0]..[num\\_trees-1][N-1]. where N is 6 for tree and face, 8 for corner, 12 for edge. If a face is on the physical boundary it must connect to itself. +Wrapper for fopen(3). We provide an additional argument that contains the error message. -The values for tree\\_to\\_face are in 0..23 where ttf % 6 gives the face number and ttf / 6 the face orientation code. The orientation is determined as follows. Let my\\_face and other\\_face be the two face numbers of the connecting trees in 0..5. Then the first face corner of the lower of my\\_face and other\\_face connects to a face corner numbered 0..3 in the higher of my\\_face and other\\_face. The face orientation is defined as this number. If my\\_face == other\\_face, treating either of both faces as the lower one leads to the same result. - -It is valid to specify num\\_vertices as 0. In this case vertices and tree\\_to\\_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num\\_vertices-1][0]..[num\\_vertices-1][2]. Vertex coordinates are optional and not used for inferring topology. - -The edges are stored when they connect trees that are not already face neighbors at that specific edge. In this case tree\\_to\\_edge indexes into *ett_offset*. Otherwise the tree\\_to\\_edge entry must be -1 and this edge is ignored. If num\\_edges == 0, tree\\_to\\_edge and edge\\_to\\_* arrays are set to NULL. - -The arrays edge\\_to\\_* store a variable number of entries per edge. For edge e these are at position [ett\\_offset[e]]..[ett\\_offset[e+1]-1]. Their number for edge e is ett\\_offset[e+1] - ett\\_offset[e]. The entries encode all trees adjacent to edge e. The size of the edge\\_to\\_* arrays is num\\_ett = ett\\_offset[num\\_edges]. The edge\\_to\\_edge array holds values in 0..23, where the lower 12 indicate one edge orientation and the higher 12 the opposite edge orientation. - -The corners are stored when they connect trees that are not already edge or face neighbors at that specific corner. In this case tree\\_to\\_corner indexes into *ctt_offset*. Otherwise the tree\\_to\\_corner entry must be -1 and this corner is ignored. If num\\_corners == 0, tree\\_to\\_corner and corner\\_to\\_* arrays are set to NULL. - -The arrays corner\\_to\\_* store a variable number of entries per corner. For corner c these are at position [ctt\\_offset[c]]..[ctt\\_offset[c+1]-1]. Their number for corner c is ctt\\_offset[c+1] - ctt\\_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner\\_to\\_* arrays is num\\_ctt = ctt\\_offset[num\\_corners]. - -The *\\_to\\_attr arrays may have arbitrary contents defined by the user. - -!!! note - - If a connectivity implies natural connections between trees that are edge neighbors without being face neighbors, these edges shall be encoded explicitly in the connectivity. If a connectivity implies natural connections between trees that are corner neighbors without being edge or face neighbors, these corners shall be encoded explicitly in the connectivity. - -| Field | Note | -| :------------------- | :----------------------------------------------------------------------------------- | -| num\\_vertices | the number of vertices that define the *embedding* of the forest (not the topology) | -| num\\_trees | the number of trees | -| num\\_edges | the number of edges that help define the topology | -| num\\_corners | the number of corners that help define the topology | -| vertices | an array of size (3 * *num_vertices*) | -| tree\\_to\\_vertex | embed each tree into ```c++ R^3 ``` for e.g. visualization (see p8est\\_vtk.h) | -| tree\\_attr\\_bytes | bytes per tree in tree\\_to\\_attr | -| tree\\_to\\_attr | not touched by p4est | -| tree\\_to\\_tree | (6 * *num_trees*) neighbors across faces | -| tree\\_to\\_face | (6 * *num_trees*) face to face+orientation (see description) | -| tree\\_to\\_edge | (12 * *num_trees*) or NULL (see description) | -| ett\\_offset | edge to offset in *edge_to_tree* and *edge_to_edge* | -| edge\\_to\\_tree | list of trees that meet at an edge | -| edge\\_to\\_edge | list of tree-edges+orientations that meet at an edge (see description) | -| tree\\_to\\_corner | (8 * *num_trees*) or NULL (see description) | -| ctt\\_offset | corner to offset in *corner_to_tree* and *corner_to_corner* | -| corner\\_to\\_tree | list of trees that meet at a corner | -| corner\\_to\\_corner | list of tree-corners that meet at a corner | +### Prototype +```c +FILE *sc_fopen (const char *filename, const char *mode, const char *errmsg); +``` """ -struct p8est_connectivity - num_vertices::p4est_topidx_t - num_trees::p4est_topidx_t - num_edges::p4est_topidx_t - num_corners::p4est_topidx_t - vertices::Ptr{Cdouble} - tree_to_vertex::Ptr{p4est_topidx_t} - tree_attr_bytes::Csize_t - tree_to_attr::Cstring - tree_to_tree::Ptr{p4est_topidx_t} - tree_to_face::Ptr{Int8} - tree_to_edge::Ptr{p4est_topidx_t} - ett_offset::Ptr{p4est_topidx_t} - edge_to_tree::Ptr{p4est_topidx_t} - edge_to_edge::Ptr{Int8} - tree_to_corner::Ptr{p4est_topidx_t} - ctt_offset::Ptr{p4est_topidx_t} - corner_to_tree::Ptr{p4est_topidx_t} - corner_to_corner::Ptr{Int8} +function sc_fopen(filename, mode, errmsg) + @ccall libsc.sc_fopen(filename::Cstring, mode::Cstring, errmsg::Cstring)::Ptr{Libc.FILE} end """ -This structure holds the 3D inter-tree connectivity information. Identification of arbitrary faces, edges and corners is possible. - -The arrays tree\\_to\\_* are stored in z ordering. For corners the order wrt. zyx is 000 001 010 011 100 101 110 111. For faces the order is -x +x -y +y -z +z. They are allocated [0][0]..[0][N-1]..[num\\_trees-1][0]..[num\\_trees-1][N-1]. where N is 6 for tree and face, 8 for corner, 12 for edge. If a face is on the physical boundary it must connect to itself. - -The values for tree\\_to\\_face are in 0..23 where ttf % 6 gives the face number and ttf / 6 the face orientation code. The orientation is determined as follows. Let my\\_face and other\\_face be the two face numbers of the connecting trees in 0..5. Then the first face corner of the lower of my\\_face and other\\_face connects to a face corner numbered 0..3 in the higher of my\\_face and other\\_face. The face orientation is defined as this number. If my\\_face == other\\_face, treating either of both faces as the lower one leads to the same result. - -It is valid to specify num\\_vertices as 0. In this case vertices and tree\\_to\\_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num\\_vertices-1][0]..[num\\_vertices-1][2]. Vertex coordinates are optional and not used for inferring topology. - -The edges are stored when they connect trees that are not already face neighbors at that specific edge. In this case tree\\_to\\_edge indexes into *ett_offset*. Otherwise the tree\\_to\\_edge entry must be -1 and this edge is ignored. If num\\_edges == 0, tree\\_to\\_edge and edge\\_to\\_* arrays are set to NULL. - -The arrays edge\\_to\\_* store a variable number of entries per edge. For edge e these are at position [ett\\_offset[e]]..[ett\\_offset[e+1]-1]. Their number for edge e is ett\\_offset[e+1] - ett\\_offset[e]. The entries encode all trees adjacent to edge e. The size of the edge\\_to\\_* arrays is num\\_ett = ett\\_offset[num\\_edges]. The edge\\_to\\_edge array holds values in 0..23, where the lower 12 indicate one edge orientation and the higher 12 the opposite edge orientation. - -The corners are stored when they connect trees that are not already edge or face neighbors at that specific corner. In this case tree\\_to\\_corner indexes into *ctt_offset*. Otherwise the tree\\_to\\_corner entry must be -1 and this corner is ignored. If num\\_corners == 0, tree\\_to\\_corner and corner\\_to\\_* arrays are set to NULL. - -The arrays corner\\_to\\_* store a variable number of entries per corner. For corner c these are at position [ctt\\_offset[c]]..[ctt\\_offset[c+1]-1]. Their number for corner c is ctt\\_offset[c+1] - ctt\\_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner\\_to\\_* arrays is num\\_ctt = ctt\\_offset[num\\_corners]. + sc_fwrite(ptr, size, nmemb, file, errmsg) -The *\\_to\\_attr arrays may have arbitrary contents defined by the user. +Write memory content to a file. !!! note - If a connectivity implies natural connections between trees that are edge neighbors without being face neighbors, these edges shall be encoded explicitly in the connectivity. If a connectivity implies natural connections between trees that are corner neighbors without being edge or face neighbors, these corners shall be encoded explicitly in the connectivity. -""" -const p8est_connectivity_t = p8est_connectivity + This function aborts on file errors. +# Arguments +* `ptr`:\\[in\\] Data array to write to disk. +* `size`:\\[in\\] Size of one array member. +* `nmemb`:\\[in\\] Number of array members. +* `file`:\\[in,out\\] File pointer, must be opened for writing. +* `errmsg`:\\[in\\] Error message passed to [`SC_CHECK_ABORT`](@ref). +### Prototype +```c +void sc_fwrite (const void *ptr, size_t size, size_t nmemb, FILE * file, const char *errmsg); +``` """ - p8est_connectivity_shared +function sc_fwrite(ptr, size, nmemb, file, errmsg) + @ccall libsc.sc_fwrite(ptr::Ptr{Cvoid}, size::Csize_t, nmemb::Csize_t, file::Ptr{Libc.FILE}, errmsg::Cstring)::Cvoid +end -| Field | Note | -| :---- | :--------------------------------------------------------- | -| conn | The members of this connectivity are MPI3 shared windows. | """ -struct p8est_connectivity_shared - conn::Ptr{p8est_connectivity_t} - win_vertices::Cint - win_tree_to_vertex::Cint - win_tree_to_attr::Cint - win_tree_to_tree::Cint - win_tree_to_face::Cint - win_tree_to_edge::Cint - win_ett_offset::Cint - win_edge_to_tree::Cint - win_edge_to_edge::Cint - win_tree_to_corner::Cint - win_ctt_offset::Cint - win_corner_to_tree::Cint - win_corner_to_corner::Cint -end + sc_fread(ptr, size, nmemb, file, errmsg) -"""Management information for a connectivity shared by MPI3.""" -const p8est_connectivity_shared_t = p8est_connectivity_shared +Read file content into memory. -""" - p8est_connectivity_memory_used(conn) +!!! note -Calculate memory usage of a connectivity structure. + This function aborts on file errors. # Arguments -* `conn`:\\[in\\] Connectivity structure. -# Returns -Memory used in bytes. +* `ptr`:\\[out\\] Data array to read from disk. +* `size`:\\[in\\] Size of one array member. +* `nmemb`:\\[in\\] Number of array members. +* `file`:\\[in,out\\] File pointer, must be opened for reading. +* `errmsg`:\\[in\\] Error message passed to [`SC_CHECK_ABORT`](@ref). ### Prototype ```c -size_t p8est_connectivity_memory_used (p8est_connectivity_t * conn); +void sc_fread (void *ptr, size_t size, size_t nmemb, FILE * file, const char *errmsg); ``` """ -function p8est_connectivity_memory_used(conn) - @ccall libp4est.p8est_connectivity_memory_used(conn::Ptr{p8est_connectivity_t})::Csize_t +function sc_fread(ptr, size, nmemb, file, errmsg) + @ccall libsc.sc_fread(ptr::Ptr{Cvoid}, size::Csize_t, nmemb::Csize_t, file::Ptr{Libc.FILE}, errmsg::Cstring)::Cvoid end """ - p8est_edge_transform_t + sc_fflush_fsync_fclose(file) -Generic interface for transformations between a tree and any of its edge +Best effort to flush a file's data to disc and close it. -| Field | Note | -| :------ | :--------------------------------- | -| ntree | The number of the tree | -| nedge | The number of the edge | -| naxis | The 3 edge coordinate axes | -| nflip | The orientation of the edge | -| corners | The corners connected to the edge | +# Arguments +* `file`:\\[in,out\\] File open for writing. +### Prototype +```c +void sc_fflush_fsync_fclose (FILE * file); +``` """ -struct p8est_edge_transform_t - ntree::p4est_topidx_t - nedge::Int8 - naxis::NTuple{3, Int8} - nflip::Int8 - corners::Int8 +function sc_fflush_fsync_fclose(file) + @ccall libsc.sc_fflush_fsync_fclose(file::Ptr{Libc.FILE})::Cvoid end """ - p8est_edge_info_t - -Information about the neighbors of an edge + sc_io_open(mpicomm, filename, amode, mpiinfo, mpifile) -| Field | Note | -| :---------------- | :---------------------------------------------- | -| iedge | The information of the edge | -| edge\\_transforms | The array of neighbors of the originating edge | +### Prototype +```c +int sc_io_open (sc_MPI_Comm mpicomm, const char *filename, sc_io_open_mode_t amode, sc_MPI_Info mpiinfo, sc_MPI_File * mpifile); +``` """ -struct p8est_edge_info_t - iedge::Int8 - edge_transforms::sc_array_t +function sc_io_open(mpicomm, filename, amode, mpiinfo, mpifile) + @ccall libsc.sc_io_open(mpicomm::MPI_Comm, filename::Cstring, amode::sc_io_open_mode_t, mpiinfo::Cint, mpifile::Ptr{Cint})::Cint end """ - p8est_corner_transform_t - -Generic interface for transformations between a tree and any of its corner + sc_io_read_at(mpifile, offset, ptr, count, t, ocount) -| Field | Note | -| :------ | :------------------------ | -| ntree | The number of the tree | -| ncorner | The number of the corner | +### Prototype +```c +int sc_io_read_at (sc_MPI_File mpifile, sc_MPI_Offset offset, void *ptr, int count, sc_MPI_Datatype t, int *ocount); +``` """ -struct p8est_corner_transform_t - ntree::p4est_topidx_t - ncorner::Int8 +function sc_io_read_at(mpifile, offset, ptr, count, t, ocount) + @ccall libsc.sc_io_read_at(mpifile::MPI_File, offset::Cint, ptr::Ptr{Cvoid}, count::Cint, t::Cint, ocount::Ptr{Cint})::Cint end """ - p8est_corner_info_t - -Information about the neighbors of a corner + sc_io_read_at_all(mpifile, offset, ptr, count, t, ocount) -| Field | Note | -| :------------------ | :------------------------------------------------ | -| icorner | The number of the originating corner | -| corner\\_transforms | The array of neighbors of the originating corner | +### Prototype +```c +int sc_io_read_at_all (sc_MPI_File mpifile, sc_MPI_Offset offset, void *ptr, int count, sc_MPI_Datatype t, int *ocount); +``` """ -struct p8est_corner_info_t - icorner::p4est_topidx_t - corner_transforms::sc_array_t +function sc_io_read_at_all(mpifile, offset, ptr, count, t, ocount) + @ccall libsc.sc_io_read_at_all(mpifile::MPI_File, offset::Cint, ptr::Ptr{Cvoid}, count::Cint, t::Cint, ocount::Ptr{Cint})::Cint end """ - p8est_neighbor_transform_t - -Generic interface for transformations between a tree and any of its neighbors + sc_io_write_at(mpifile, offset, ptr, count, t, ocount) -| Field | Note | -| :---------------- | :-------------------------------------------------------------------------- | -| neighbor\\_type | type of connection to neighbor | -| neighbor | neighbor tree index | -| index\\_self | index of interface from self's perspective | -| index\\_neighbor | index of interface from neighbor's perspective | -| perm | permutation of dimensions when transforming self coords to neighbor coords | -| sign | sign changes when transforming self coords to neighbor coords | -| origin\\_self | point on the interface from self's perspective | -| origin\\_neighbor | point on the interface from neighbor's perspective | +### Prototype +```c +int sc_io_write_at (sc_MPI_File mpifile, sc_MPI_Offset offset, const void *ptr, int count, sc_MPI_Datatype t, int *ocount); +``` """ -struct p8est_neighbor_transform_t - neighbor_type::p8est_connect_type_t - neighbor::p4est_topidx_t - index_self::Int8 - index_neighbor::Int8 - perm::NTuple{3, Int8} - sign::NTuple{3, Int8} - origin_self::NTuple{3, p4est_qcoord_t} - origin_neighbor::NTuple{3, p4est_qcoord_t} +function sc_io_write_at(mpifile, offset, ptr, count, t, ocount) + @ccall libsc.sc_io_write_at(mpifile::MPI_File, offset::Cint, ptr::Ptr{Cvoid}, count::Cint, t::Cint, ocount::Ptr{Cint})::Cint end """ - p8est_neighbor_transform_coordinates(nt, self_coords, neigh_coords) - -Transform from self's coordinate system to neighbor's coordinate system. + sc_io_write_at_all(mpifile, offset, ptr, count, t, ocount) -# Arguments -* `nt`:\\[in\\] A neighbor transform. -* `self_coords`:\\[in\\] Input quadrant coordinates in self coordinates. -* `neigh_coords`:\\[out\\] Coordinates transformed into neighbor coordinates. ### Prototype ```c -void p8est_neighbor_transform_coordinates (const p8est_neighbor_transform_t * nt, const p4est_qcoord_t self_coords[P8EST_DIM], p4est_qcoord_t neigh_coords[P8EST_DIM]); +int sc_io_write_at_all (sc_MPI_File mpifile, sc_MPI_Offset offset, const void *ptr, int count, sc_MPI_Datatype t, int *ocount); ``` """ -function p8est_neighbor_transform_coordinates(nt, self_coords, neigh_coords) - @ccall libp4est.p8est_neighbor_transform_coordinates(nt::Ptr{p8est_neighbor_transform_t}, self_coords::Ptr{p4est_qcoord_t}, neigh_coords::Ptr{p4est_qcoord_t})::Cvoid +function sc_io_write_at_all(mpifile, offset, ptr, count, t, ocount) + @ccall libsc.sc_io_write_at_all(mpifile::MPI_File, offset::Cint, ptr::Ptr{Cvoid}, count::Cint, t::Cint, ocount::Ptr{Cint})::Cint end """ - p8est_neighbor_transform_coordinates_reverse(nt, neigh_coords, self_coords) - -Transform from neighbor's coordinate system to self's coordinate system. + sc_io_close(file) -# Arguments -* `nt`:\\[in\\] A neighbor transform. -* `neigh_coords`:\\[in\\] Input quadrant coordinates in self coordinates. -* `self_coords`:\\[out\\] Coordinates transformed into neighbor coordinates. ### Prototype ```c -void p8est_neighbor_transform_coordinates_reverse (const p8est_neighbor_transform_t * nt, const p4est_qcoord_t neigh_coords[P8EST_DIM], p4est_qcoord_t self_coords[P8EST_DIM]); +int sc_io_close (sc_MPI_File * file); ``` """ -function p8est_neighbor_transform_coordinates_reverse(nt, neigh_coords, self_coords) - @ccall libp4est.p8est_neighbor_transform_coordinates_reverse(nt::Ptr{p8est_neighbor_transform_t}, neigh_coords::Ptr{p4est_qcoord_t}, self_coords::Ptr{p4est_qcoord_t})::Cvoid +function sc_io_close(file) + @ccall libsc.sc_io_close(file::Ptr{Cint})::Cint end """ - p8est_connectivity_get_neighbor_transforms(conn, tree_id, boundary_type, boundary_index, neighbor_transform_array) + p4est_comm_tag -Fill an array with the neighbor transforms based on a specific boundary type. This function generalizes all other inter-tree transformation objects +Tags for MPI messages +""" +@cenum p4est_comm_tag::UInt32 begin + P4EST_COMM_TAG_FIRST = 214 + P4EST_COMM_COUNT_PERTREE = 295 + P4EST_COMM_BALANCE_FIRST_COUNT = 296 + P4EST_COMM_BALANCE_FIRST_LOAD = 297 + P4EST_COMM_BALANCE_SECOND_COUNT = 298 + P4EST_COMM_BALANCE_SECOND_LOAD = 299 + P4EST_COMM_PARTITION_GIVEN = 300 + P4EST_COMM_PARTITION_WEIGHTED_LOW = 301 + P4EST_COMM_PARTITION_WEIGHTED_HIGH = 302 + P4EST_COMM_PARTITION_CORRECTION = 303 + P4EST_COMM_GHOST_COUNT = 304 + P4EST_COMM_GHOST_LOAD = 305 + P4EST_COMM_GHOST_EXCHANGE = 306 + P4EST_COMM_GHOST_EXPAND_COUNT = 307 + P4EST_COMM_GHOST_EXPAND_LOAD = 308 + P4EST_COMM_GHOST_SUPPORT_COUNT = 309 + P4EST_COMM_GHOST_SUPPORT_LOAD = 310 + P4EST_COMM_GHOST_CHECKSUM = 311 + P4EST_COMM_NODES_QUERY = 312 + P4EST_COMM_NODES_REPLY = 313 + P4EST_COMM_SAVE = 314 + P4EST_COMM_LNODES_TEST = 315 + P4EST_COMM_LNODES_PASS = 316 + P4EST_COMM_LNODES_OWNED = 317 + P4EST_COMM_LNODES_ALL = 318 + P4EST_COMM_TAG_LAST = 319 +end + +"""Tags for MPI messages""" +const p4est_comm_tag_t = p4est_comm_tag + +""" + p4est_log_indent_push() -# Arguments -* `conn`:\\[in\\] Connectivity structure. -* `tree_id`:\\[in\\] The number of the tree. -* `boundary_type`:\\[in\\] Type of boundary connection (self, face, edge, corner). -* `boundary_index`:\\[in\\] The index of the boundary. -* `neighbor_transform_array`:\\[in,out\\] Array of the neighbor transforms. ### Prototype ```c -void p8est_connectivity_get_neighbor_transforms (p8est_connectivity_t *conn, p4est_topidx_t tree_id, p8est_connect_type_t boundary_type, int boundary_index, sc_array_t *neighbor_transform_array); +static inline void p4est_log_indent_push (void); ``` """ -function p8est_connectivity_get_neighbor_transforms(conn, tree_id, boundary_type, boundary_index, neighbor_transform_array) - @ccall libp4est.p8est_connectivity_get_neighbor_transforms(conn::Ptr{p8est_connectivity_t}, tree_id::p4est_topidx_t, boundary_type::p8est_connect_type_t, boundary_index::Cint, neighbor_transform_array::Ptr{sc_array_t})::Cvoid +function p4est_log_indent_push() + @ccall libp4est.p4est_log_indent_push()::Cvoid end """ - p8est_connectivity_coordinates_canonicalize(conn, treeid, coords, treeid_out, coords_out) - -Determine the owning tree for a coordinate and transform it there. - -On a boundary between trees, different coordinate systems meet. A coordinate on a tree boundary face, edge, or corner generated from the perspective of a specific tree may be transformed into any other touching tree's coordinate system and still refer to the same point in the mesh. - -To uniquely identify a coordinate, this function identifies the lowest numbered tree touching this coordinate and transforms the coordinate into that system. The result can be used e. g. in topology hash tables. + p4est_log_indent_pop() -# Arguments -* `conn`:\\[in\\] A valid connectivity. -* `treeid`:\\[in\\] The original tree index for this coordinate tuple. -* `coords`:\\[in\\] A valid coordinate 2-tuple relative to *treeid*. -* `treeid_out`:\\[out\\] The lowest tree index touching the coordinate. -* `coords_out`:\\[out\\] The input coordinates, if necessary after transformation into the system of the lowest numbered tree, returned in *treeid_out*. ### Prototype ```c -void p8est_connectivity_coordinates_canonicalize (p8est_connectivity_t *conn, p4est_topidx_t treeid, const p4est_qcoord_t coords[], p4est_topidx_t *treeid_out, p4est_qcoord_t coords_out[]); +static inline void p4est_log_indent_pop (void); ``` """ -function p8est_connectivity_coordinates_canonicalize(conn, treeid, coords, treeid_out, coords_out) - @ccall libp4est.p8est_connectivity_coordinates_canonicalize(conn::Ptr{p8est_connectivity_t}, treeid::p4est_topidx_t, coords::Ptr{p4est_qcoord_t}, treeid_out::Ptr{p4est_topidx_t}, coords_out::Ptr{p4est_qcoord_t})::Cvoid +function p4est_log_indent_pop() + @ccall libp4est.p4est_log_indent_pop()::Cvoid end """ - p8est_connectivity_face_neighbor_corner_set(c, f, nf, set) + p4est_init(log_handler, log_threshold) -Transform a corner across one of the adjacent faces into a neighbor tree. It expects a face permutation index that has been precomputed. +Registers p4est with the SC Library and sets the logging behavior. This function is optional. This function must only be called before additional threads are created. If this function is not called or called with log\\_handler == NULL, the default SC log handler will be used. If this function is not called or called with log\\_threshold == [`SC_LP_DEFAULT`](@ref), the default SC log threshold will be used. The default SC log settings can be changed with [`sc_set_log_defaults`](@ref) (). -# Arguments -* `c`:\\[in\\] A corner number in 0..7. -* `f`:\\[in\\] A face number that touches the corner *c*. -* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. -* `set`:\\[in\\] A value from *p8est_face_permutation_sets* that is obtained using *f*, *nf*, and a valid orientation: ref = p8est\\_face\\_permutation\\_refs[f][nf]; set = p8est\\_face\\_permutation\\_sets[ref][orientation]; -# Returns -The corner number in 0..7 seen from the other face. ### Prototype ```c -int p8est_connectivity_face_neighbor_corner_set (int c, int f, int nf, int set); +void p4est_init (sc_log_handler_t log_handler, int log_threshold); ``` """ -function p8est_connectivity_face_neighbor_corner_set(c, f, nf, set) - @ccall libp4est.p8est_connectivity_face_neighbor_corner_set(c::Cint, f::Cint, nf::Cint, set::Cint)::Cint +function p4est_init(log_handler, log_threshold) + @ccall libp4est.p4est_init(log_handler::sc_log_handler_t, log_threshold::Cint)::Cvoid end """ - p8est_connectivity_face_neighbor_face_corner(fc, f, nf, o) + p4est_is_initialized() -Transform a face corner across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. +Return whether p4est has been initialized or not. Keep in mind that p4est_init is an optional function but it helps with proper parallel logging. + +Currently there is no inverse to p4est_init, and no way to deinit it. This is ok since initialization generally does no harm. Just do not call libsc's finalize function while p4est is still in use. -# Arguments -* `fc`:\\[in\\] A face corner number in 0..3. -* `f`:\\[in\\] A face that the face corner *fc* is relative to. -* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. -* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. # Returns -The face corner number relative to the neighbor's face. +True if p4est has been initialized with a call to p4est_init and false otherwise. ### Prototype ```c -int p8est_connectivity_face_neighbor_face_corner (int fc, int f, int nf, int o); +int p4est_is_initialized (void); ``` """ -function p8est_connectivity_face_neighbor_face_corner(fc, f, nf, o) - @ccall libp4est.p8est_connectivity_face_neighbor_face_corner(fc::Cint, f::Cint, nf::Cint, o::Cint)::Cint +function p4est_is_initialized() + @ccall libp4est.p4est_is_initialized()::Cint end """ - p8est_connectivity_face_neighbor_corner(c, f, nf, o) + p4est_have_zlib() -Transform a corner across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. +Check for a sufficiently recent zlib installation. -# Arguments -* `c`:\\[in\\] A corner number in 0..7. -* `f`:\\[in\\] A face number that touches the corner *c*. -* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. -* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. # Returns -The number of the corner seen from the neighbor tree. +True if zlib is detected in both sc and p4est. ### Prototype ```c -int p8est_connectivity_face_neighbor_corner (int c, int f, int nf, int o); +int p4est_have_zlib (void); ``` """ -function p8est_connectivity_face_neighbor_corner(c, f, nf, o) - @ccall libp4est.p8est_connectivity_face_neighbor_corner(c::Cint, f::Cint, nf::Cint, o::Cint)::Cint +function p4est_have_zlib() + @ccall libp4est.p4est_have_zlib()::Cint end """ - p8est_connectivity_face_neighbor_face_edge(fe, f, nf, o) + p4est_get_package_id() -Transform a face-edge across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. +Query the package identity as registered in libsc. -# Arguments -* `fe`:\\[in\\] A face edge number in 0..3. -* `f`:\\[in\\] A face number that touches the edge *e*. -* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. -* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. # Returns -The face edge number seen from the neighbor tree. +This is -1 before p4est_init has been called and a proper package identifier (>= 0) afterwards. ### Prototype ```c -int p8est_connectivity_face_neighbor_face_edge (int fe, int f, int nf, int o); +int p4est_get_package_id (void); ``` """ -function p8est_connectivity_face_neighbor_face_edge(fe, f, nf, o) - @ccall libp4est.p8est_connectivity_face_neighbor_face_edge(fe::Cint, f::Cint, nf::Cint, o::Cint)::Cint +function p4est_get_package_id() + @ccall libp4est.p4est_get_package_id()::Cint end """ - p8est_connectivity_face_neighbor_edge(e, f, nf, o) - -Transform an edge across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. + p4est_topidx_hash2(tt) -# Arguments -* `e`:\\[in\\] A edge number in 0..11. -* `f`:\\[in\\] A face 0..5 that touches the edge *e*. -* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. -* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. -# Returns -The edge's number seen from the neighbor. ### Prototype ```c -int p8est_connectivity_face_neighbor_edge (int e, int f, int nf, int o); +static inline unsigned p4est_topidx_hash2 (const p4est_topidx_t * tt); ``` """ -function p8est_connectivity_face_neighbor_edge(e, f, nf, o) - @ccall libp4est.p8est_connectivity_face_neighbor_edge(e::Cint, f::Cint, nf::Cint, o::Cint)::Cint +function p4est_topidx_hash2(tt) + @ccall libp4est.p4est_topidx_hash2(tt::Ptr{p4est_topidx_t})::Cuint end """ - p8est_connectivity_edge_neighbor_edge_corner(ec, o) - -Transform an edge corner across one of the adjacent edges into a neighbor tree. + p4est_topidx_hash3(tt) -# Arguments -* `ec`:\\[in\\] An edge corner number in 0..1. -* `o`:\\[in\\] The orientation of a tree boundary edge connection. -# Returns -The edge corner number seen from the other tree. ### Prototype ```c -int p8est_connectivity_edge_neighbor_edge_corner (int ec, int o); +static inline unsigned p4est_topidx_hash3 (const p4est_topidx_t * tt); ``` """ -function p8est_connectivity_edge_neighbor_edge_corner(ec, o) - @ccall libp4est.p8est_connectivity_edge_neighbor_edge_corner(ec::Cint, o::Cint)::Cint +function p4est_topidx_hash3(tt) + @ccall libp4est.p4est_topidx_hash3(tt::Ptr{p4est_topidx_t})::Cuint end """ - p8est_connectivity_edge_neighbor_corner(c, e, ne, o) - -Transform a corner across one of the adjacent edges into a neighbor tree. This version expects the neighbor edge and orientation separately. + p4est_topidx_hash4(tt) -# Arguments -* `c`:\\[in\\] A corner number in 0..7. -* `e`:\\[in\\] An edge 0..11 that touches the corner *c*. -* `ne`:\\[in\\] A neighbor edge that is on the other side of *e*. -* `o`:\\[in\\] The orientation between tree boundary edges *e* and *ne*. -# Returns -Corner number seen from the neighbor. ### Prototype ```c -int p8est_connectivity_edge_neighbor_corner (int c, int e, int ne, int o); +static inline unsigned p4est_topidx_hash4 (const p4est_topidx_t * tt); ``` """ -function p8est_connectivity_edge_neighbor_corner(c, e, ne, o) - @ccall libp4est.p8est_connectivity_edge_neighbor_corner(c::Cint, e::Cint, ne::Cint, o::Cint)::Cint +function p4est_topidx_hash4(tt) + @ccall libp4est.p4est_topidx_hash4(tt::Ptr{p4est_topidx_t})::Cuint end """ - p8est_connectivity_new(num_vertices, num_trees, num_edges, num_ett, num_corners, num_ctt) - -Allocate a connectivity structure. The attribute fields are initialized to NULL. + p4est_topidx_is_sorted(t, length) -# Arguments -* `num_vertices`:\\[in\\] Number of total vertices (i.e. geometric points). -* `num_trees`:\\[in\\] Number of trees in the forest. -* `num_edges`:\\[in\\] Number of tree-connecting edges. -* `num_ett`:\\[in\\] Number of total trees in edge\\_to\\_tree array. -* `num_corners`:\\[in\\] Number of tree-connecting corners. -* `num_ctt`:\\[in\\] Number of total trees in corner\\_to\\_tree array. -# Returns -A connectivity structure with allocated arrays. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new (p4est_topidx_t num_vertices, p4est_topidx_t num_trees, p4est_topidx_t num_edges, p4est_topidx_t num_ett, p4est_topidx_t num_corners, p4est_topidx_t num_ctt); +static inline int p4est_topidx_is_sorted (p4est_topidx_t * t, int length); ``` """ -function p8est_connectivity_new(num_vertices, num_trees, num_edges, num_ett, num_corners, num_ctt) - @ccall libp4est.p8est_connectivity_new(num_vertices::p4est_topidx_t, num_trees::p4est_topidx_t, num_edges::p4est_topidx_t, num_ett::p4est_topidx_t, num_corners::p4est_topidx_t, num_ctt::p4est_topidx_t)::Ptr{p8est_connectivity_t} +function p4est_topidx_is_sorted(t, length) + @ccall libp4est.p4est_topidx_is_sorted(t::Ptr{p4est_topidx_t}, length::Cint)::Cint end """ - p8est_connectivity_new_copy(num_vertices, num_trees, num_edges, num_corners, vertices, ttv, ttt, ttf, tte, eoff, ett, ete, ttc, coff, ctt, ctc) - -Allocate a connectivity structure and populate from constants. The attribute fields are initialized to NULL. + p4est_topidx_bsort(t, length) -# Arguments -* `num_vertices`:\\[in\\] Number of total vertices (i.e. geometric points). -* `num_trees`:\\[in\\] Number of trees in the forest. -* `num_edges`:\\[in\\] Number of tree-connecting edges. -* `num_corners`:\\[in\\] Number of tree-connecting corners. -* `vertices`:\\[in\\] Coordinates of the vertices of the trees. -* `ttv`:\\[in\\] The tree-to-vertex array. -* `ttt`:\\[in\\] The tree-to-tree array. -* `ttf`:\\[in\\] The tree-to-face array (int8\\_t). -* `tte`:\\[in\\] The tree-to-edge array. -* `eoff`:\\[in\\] Edge-to-tree offsets (num\\_edges + 1 values). This must always be non-NULL; in trivial cases it is just a pointer to a p4est\\_topix value of 0. -* `ett`:\\[in\\] The edge-to-tree array. -* `ete`:\\[in\\] The edge-to-edge array. -* `ttc`:\\[in\\] The tree-to-corner array. -* `coff`:\\[in\\] Corner-to-tree offsets (num\\_corners + 1 values). This must always be non-NULL; in trivial cases it is just a pointer to a p4est\\_topix value of 0. -* `ctt`:\\[in\\] The corner-to-tree array. -* `ctc`:\\[in\\] The corner-to-corner array. -# Returns -The connectivity is checked for validity. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_copy (p4est_topidx_t num_vertices, p4est_topidx_t num_trees, p4est_topidx_t num_edges, p4est_topidx_t num_corners, const double *vertices, const p4est_topidx_t * ttv, const p4est_topidx_t * ttt, const int8_t * ttf, const p4est_topidx_t * tte, const p4est_topidx_t * eoff, const p4est_topidx_t * ett, const int8_t * ete, const p4est_topidx_t * ttc, const p4est_topidx_t * coff, const p4est_topidx_t * ctt, const int8_t * ctc); +static inline void p4est_topidx_bsort (p4est_topidx_t * t, int length); ``` """ -function p8est_connectivity_new_copy(num_vertices, num_trees, num_edges, num_corners, vertices, ttv, ttt, ttf, tte, eoff, ett, ete, ttc, coff, ctt, ctc) - @ccall libp4est.p8est_connectivity_new_copy(num_vertices::p4est_topidx_t, num_trees::p4est_topidx_t, num_edges::p4est_topidx_t, num_corners::p4est_topidx_t, vertices::Ptr{Cdouble}, ttv::Ptr{p4est_topidx_t}, ttt::Ptr{p4est_topidx_t}, ttf::Ptr{Int8}, tte::Ptr{p4est_topidx_t}, eoff::Ptr{p4est_topidx_t}, ett::Ptr{p4est_topidx_t}, ete::Ptr{Int8}, ttc::Ptr{p4est_topidx_t}, coff::Ptr{p4est_topidx_t}, ctt::Ptr{p4est_topidx_t}, ctc::Ptr{Int8})::Ptr{p8est_connectivity_t} +function p4est_topidx_bsort(t, length) + @ccall libp4est.p4est_topidx_bsort(t::Ptr{p4est_topidx_t}, length::Cint)::Cvoid end """ - p8est_connectivity_copy(input, copy_attr) - -Deep copy a connectivity structure. + p4est_partition_cut_uint64(global_num, p, num_procs) -# Arguments -* `input`:\\[in\\] Valid connectivity. -* `copy_attr`:\\[in\\] If true, we copy the tree attribute data. Otherwise, the result has empty attributes. -# Returns -A connectivity equal to the first one except, depending on *copy_attry*, for its attributes. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_copy (p8est_connectivity_t *input, int copy_attr); +static inline uint64_t p4est_partition_cut_uint64 (uint64_t global_num, int p, int num_procs); ``` """ -function p8est_connectivity_copy(input, copy_attr) - @ccall libp4est.p8est_connectivity_copy(input::Ptr{p8est_connectivity_t}, copy_attr::Cint)::Ptr{p8est_connectivity_t} +function p4est_partition_cut_uint64(global_num, p, num_procs) + @ccall libp4est.p4est_partition_cut_uint64(global_num::UInt64, p::Cint, num_procs::Cint)::UInt64 end """ - p8est_connectivity_bcast(conn_in, root, comm) + p4est_partition_cut_gloidx(global_num, p, num_procs) ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_bcast (p8est_connectivity_t * conn_in, int root, sc_MPI_Comm comm); +static inline p4est_gloidx_t p4est_partition_cut_gloidx (p4est_gloidx_t global_num, int p, int num_procs); ``` """ -function p8est_connectivity_bcast(conn_in, root, comm) - @ccall libp4est.p8est_connectivity_bcast(conn_in::Ptr{p8est_connectivity_t}, root::Cint, comm::MPI_Comm)::Ptr{p8est_connectivity_t} +function p4est_partition_cut_gloidx(global_num, p, num_procs) + @ccall libp4est.p4est_partition_cut_gloidx(global_num::p4est_gloidx_t, p::Cint, num_procs::Cint)::p4est_gloidx_t end """ - p8est_connectivity_destroy(connectivity) + p4est_version() -Destroy a connectivity structure. Also destroy all attributes. +Return the full version of p4est. +# Returns +Return the version of p4est using the format `VERSION\\_MAJOR.VERSION\\_MINOR.VERSION\\_POINT`, where `VERSION_POINT` can contain dots and characters, e.g. to indicate the additional number of commits and a git commit hash. ### Prototype ```c -void p8est_connectivity_destroy (p8est_connectivity_t * connectivity); +const char *p4est_version (void); ``` """ -function p8est_connectivity_destroy(connectivity) - @ccall libp4est.p8est_connectivity_destroy(connectivity::Ptr{p8est_connectivity_t})::Cvoid +function p4est_version() + @ccall libp4est.p4est_version()::Cstring end """ - p8est_connectivity_share(conn_in, root, comm) - -### Prototype -```c -p8est_connectivity_shared_t *p8est_connectivity_share (p8est_connectivity_t * conn_in, int root, sc_MPI_Comm comm); -``` -""" -function p8est_connectivity_share(conn_in, root, comm) - @ccall libp4est.p8est_connectivity_share(conn_in::Ptr{p8est_connectivity_t}, root::Cint, comm::MPI_Comm)::Ptr{p8est_connectivity_shared_t} -end + p4est_version_major() -""" - p8est_connectivity_mission(conn_in, split_type, world_comm) +Return the major version of p4est. +# Returns +Return the major version of p4est. ### Prototype ```c -p8est_connectivity_shared_t * p8est_connectivity_mission (p8est_connectivity_t *conn_in, int split_type, sc_MPI_Comm world_comm); +int p4est_version_major (void); ``` """ -function p8est_connectivity_mission(conn_in, split_type, world_comm) - @ccall libp4est.p8est_connectivity_mission(conn_in::Ptr{p8est_connectivity_t}, split_type::Cint, world_comm::Cint)::Ptr{p8est_connectivity_shared_t} +function p4est_version_major() + @ccall libp4est.p4est_version_major()::Cint end """ - p8est_connectivity_shared_destroy(cshare) + p4est_version_minor() -Destroy a shared connectivity structure. Call this eventually on the result of p8est_connectivity_share or p8est_connectivity_mission (which calls the former internally). +Return the minor version of p4est. -# Arguments -* `cshare`:\\[in\\] Valid shared connectivity structure; cf. p8est_connectivity_share. +# Returns +Return the minor version of p4est. ### Prototype ```c -void p8est_connectivity_shared_destroy (p8est_connectivity_shared_t *cshare); +int p4est_version_minor (void); ``` """ -function p8est_connectivity_shared_destroy(cshare) - @ccall libp4est.p8est_connectivity_shared_destroy(cshare::Ptr{p8est_connectivity_shared_t})::Cvoid +function p4est_version_minor() + @ccall libp4est.p4est_version_minor()::Cint end """ - p8est_connectivity_set_attr(conn, bytes_per_tree) + p4est_connect_type_t -Allocate or free the attribute fields in a connectivity. +Characterize a type of adjacency. -# Arguments -* `conn`:\\[in,out\\] The conn->*\\_to\\_attr fields must either be NULL or previously be allocated by this function. -* `bytes_per_tree`:\\[in\\] If 0, tree\\_to\\_attr is freed (being NULL is ok). If positive, requested space is allocated. -### Prototype -```c -void p8est_connectivity_set_attr (p8est_connectivity_t * conn, size_t bytes_per_tree); -``` +Several functions involve relationships between neighboring trees and/or quadrants, and their behavior depends on how one defines adjacency: 1) entities are adjacent if they share a face, or 2) entities are adjacent if they share a face or corner. [`p4est_connect_type_t`](@ref) is used to choose the desired behavior. This enum must fit into an int8\\_t. + +| Enumerator | Note | +| :----------------------- | :--------------------------------- | +| P4EST\\_CONNECT\\_SELF | No balance whatsoever. | +| P4EST\\_CONNECT\\_FACE | Balance across faces only. | +| P4EST\\_CONNECT\\_ALMOST | = CORNER - 1. | +| P4EST\\_CONNECT\\_CORNER | Balance across faces and corners. | +| P4EST\\_CONNECT\\_FULL | = CORNER. | """ -function p8est_connectivity_set_attr(conn, bytes_per_tree) - @ccall libp4est.p8est_connectivity_set_attr(conn::Ptr{p8est_connectivity_t}, bytes_per_tree::Csize_t)::Cvoid +@cenum p4est_connect_type_t::UInt32 begin + P4EST_CONNECT_SELF = 20 + P4EST_CONNECT_FACE = 21 + P4EST_CONNECT_ALMOST = 21 + P4EST_CONNECT_CORNER = 22 + P4EST_CONNECT_FULL = 22 end """ - p8est_connectivity_is_valid(connectivity) + p4est_connectivity_encode_t -Examine a connectivity structure. +Typedef for serialization method. -# Returns -Returns true if structure is valid, false otherwise. -### Prototype -```c -int p8est_connectivity_is_valid (p8est_connectivity_t * connectivity); -``` +| Enumerator | Note | +| :--------------------------- | :-------------------------------- | +| P4EST\\_CONN\\_ENCODE\\_LAST | Invalid entry to close the list. | """ -function p8est_connectivity_is_valid(connectivity) - @ccall libp4est.p8est_connectivity_is_valid(connectivity::Ptr{p8est_connectivity_t})::Cint +@cenum p4est_connectivity_encode_t::UInt32 begin + P4EST_CONN_ENCODE_NONE = 0 + P4EST_CONN_ENCODE_LAST = 1 end """ - p8est_connectivity_is_equal(conn1, conn2) + p4est_connect_type_int(btype) -Check two connectivity structures for equality. +Convert the [`p4est_connect_type_t`](@ref) into a number. +# Arguments +* `btype`:\\[in\\] The balance type to convert. # Returns -Returns true if structures are equal, false otherwise. +Returns 1 or 2. ### Prototype ```c -int p8est_connectivity_is_equal (p8est_connectivity_t * conn1, p8est_connectivity_t * conn2); +int p4est_connect_type_int (p4est_connect_type_t btype); ``` """ -function p8est_connectivity_is_equal(conn1, conn2) - @ccall libp4est.p8est_connectivity_is_equal(conn1::Ptr{p8est_connectivity_t}, conn2::Ptr{p8est_connectivity_t})::Cint +function p4est_connect_type_int(btype) + @ccall libp4est.p4est_connect_type_int(btype::p4est_connect_type_t)::Cint end """ - p8est_connectivity_sink(conn, sink) + p4est_connect_type_string(btype) -Write connectivity to a sink object. +Convert the [`p4est_connect_type_t`](@ref) into a const string. # Arguments -* `conn`:\\[in\\] The connectivity to be written. -* `sink`:\\[in,out\\] The connectivity is written into this sink. +* `btype`:\\[in\\] The balance type to convert. # Returns -0 on success, nonzero on error. +Returns a pointer to a constant string. ### Prototype ```c -int p8est_connectivity_sink (p8est_connectivity_t * conn, sc_io_sink_t * sink); +const char *p4est_connect_type_string (p4est_connect_type_t btype); ``` """ -function p8est_connectivity_sink(conn, sink) - @ccall libp4est.p8est_connectivity_sink(conn::Ptr{p8est_connectivity_t}, sink::Ptr{sc_io_sink_t})::Cint +function p4est_connect_type_string(btype) + @ccall libp4est.p4est_connect_type_string(btype::p4est_connect_type_t)::Cstring end """ - p8est_connectivity_deflate(conn, code) + p4est_connectivity -Allocate memory and store the connectivity information there. +This structure holds the 2D inter-tree connectivity information. Identification of arbitrary faces and corners is possible. -# Arguments -* `conn`:\\[in\\] The connectivity structure to be exported to memory. -* `code`:\\[in\\] Encoding and compression method for serialization. -# Returns -Newly created array that contains the information. -### Prototype -```c -sc_array_t *p8est_connectivity_deflate (p8est_connectivity_t * conn, p8est_connectivity_encode_t code); -``` -""" -function p8est_connectivity_deflate(conn, code) - @ccall libp4est.p8est_connectivity_deflate(conn::Ptr{p8est_connectivity_t}, code::p8est_connectivity_encode_t)::Ptr{sc_array_t} -end +The arrays tree\\_to\\_* are stored in z ordering. For corners the order wrt. yx is 00 01 10 11. For faces the order is given by the normal directions -x +x -y +y. Each face has a natural direction by increasing face corner number. Face connections are allocated [0][0]..[0][3]..[num\\_trees-1][0]..[num\\_trees-1][3]. If a face is on the physical boundary it must connect to itself. -""" - p8est_connectivity_save(filename, connectivity) +The values for tree\\_to\\_face are 0..7 where ttf % 4 gives the face number and ttf / 4 the face orientation code. The orientation is 0 for faces that are mutually direction-aligned and 1 for faces that are running in opposite directions. -Save a connectivity structure to disk. +It is valid to specify num\\_vertices as 0. In this case vertices and tree\\_to\\_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num\\_vertices-1][0]..[num\\_vertices-1][2]. Vertex coordinates are optional and not used for inferring topology. -# Arguments -* `filename`:\\[in\\] Name of the file to write. -* `connectivity`:\\[in\\] Valid connectivity structure. -# Returns -Returns 0 on success, nonzero on file error. -### Prototype -```c -int p8est_connectivity_save (const char *filename, p8est_connectivity_t * connectivity); -``` -""" -function p8est_connectivity_save(filename, connectivity) - @ccall libp4est.p8est_connectivity_save(filename::Cstring, connectivity::Ptr{p8est_connectivity_t})::Cint -end +The corners are stored when they connect trees that are not already face neighbors at that specific corner. In this case tree\\_to\\_corner indexes into *ctt_offset*. Otherwise the tree\\_to\\_corner entry must be -1 and this corner is ignored. If num\\_corners == 0, tree\\_to\\_corner and corner\\_to\\_* arrays are set to NULL. -""" - p8est_connectivity_source(source) +The arrays corner\\_to\\_* store a variable number of entries per corner. For corner c these are at position [ctt\\_offset[c]]..[ctt\\_offset[c+1]-1]. Their number for corner c is ctt\\_offset[c+1] - ctt\\_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner\\_to\\_* arrays is num\\_ctt = ctt\\_offset[num\\_corners]. -Read connectivity from a source object. +The *\\_to\\_attr arrays may have arbitrary contents defined by the user. We do not interpret them. -# Arguments -* `source`:\\[in,out\\] The connectivity is read from this source. -# Returns -The newly created connectivity, or NULL on error. -### Prototype -```c -p8est_connectivity_t *p8est_connectivity_source (sc_io_source_t * source); -``` +!!! note + + If a connectivity implies natural connections between trees that are corner neighbors without being face neighbors, these corners shall be encoded explicitly in the connectivity. + +| Field | Note | +| :------------------- | :----------------------------------------------------------------------------------- | +| num\\_vertices | the number of vertices that define the *embedding* of the forest (not the topology) | +| num\\_trees | the number of trees | +| num\\_corners | the number of corners that help define topology | +| vertices | an array of size (3 * *num_vertices*) | +| tree\\_to\\_vertex | embed each tree into ```c++ R^3 ``` for e.g. visualization (see p4est\\_vtk.h) | +| tree\\_attr\\_bytes | bytes per tree in tree\\_to\\_attr | +| tree\\_to\\_attr | not touched by p4est | +| tree\\_to\\_tree | (4 * *num_trees*) neighbors across faces | +| tree\\_to\\_face | (4 * *num_trees*) face to face+orientation (see description) | +| tree\\_to\\_corner | (4 * *num_trees*) or NULL (see description) | +| ctt\\_offset | corner to offset in *corner_to_tree* and *corner_to_corner* | +| corner\\_to\\_tree | list of trees that meet at a corner | +| corner\\_to\\_corner | list of tree-corners that meet at a corner | """ -function p8est_connectivity_source(source) - @ccall libp4est.p8est_connectivity_source(source::Ptr{sc_io_source_t})::Ptr{p8est_connectivity_t} +struct p4est_connectivity + num_vertices::p4est_topidx_t + num_trees::p4est_topidx_t + num_corners::p4est_topidx_t + vertices::Ptr{Cdouble} + tree_to_vertex::Ptr{p4est_topidx_t} + tree_attr_bytes::Csize_t + tree_to_attr::Cstring + tree_to_tree::Ptr{p4est_topidx_t} + tree_to_face::Ptr{Int8} + tree_to_corner::Ptr{p4est_topidx_t} + ctt_offset::Ptr{p4est_topidx_t} + corner_to_tree::Ptr{p4est_topidx_t} + corner_to_corner::Ptr{Int8} end """ - p8est_connectivity_inflate(buffer) +This structure holds the 2D inter-tree connectivity information. Identification of arbitrary faces and corners is possible. -Create new connectivity from a memory buffer. This function aborts on malloc errors. +The arrays tree\\_to\\_* are stored in z ordering. For corners the order wrt. yx is 00 01 10 11. For faces the order is given by the normal directions -x +x -y +y. Each face has a natural direction by increasing face corner number. Face connections are allocated [0][0]..[0][3]..[num\\_trees-1][0]..[num\\_trees-1][3]. If a face is on the physical boundary it must connect to itself. -# Arguments -* `buffer`:\\[in\\] The connectivity is created from this memory buffer. -# Returns -The newly created connectivity, or NULL on format error of the buffered connectivity data. -### Prototype -```c -p8est_connectivity_t *p8est_connectivity_inflate (sc_array_t * buffer); -``` -""" -function p8est_connectivity_inflate(buffer) - @ccall libp4est.p8est_connectivity_inflate(buffer::Ptr{sc_array_t})::Ptr{p8est_connectivity_t} -end +The values for tree\\_to\\_face are 0..7 where ttf % 4 gives the face number and ttf / 4 the face orientation code. The orientation is 0 for faces that are mutually direction-aligned and 1 for faces that are running in opposite directions. -""" - p8est_connectivity_load(filename, bytes) +It is valid to specify num\\_vertices as 0. In this case vertices and tree\\_to\\_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num\\_vertices-1][0]..[num\\_vertices-1][2]. Vertex coordinates are optional and not used for inferring topology. -Load a connectivity structure from disk. +The corners are stored when they connect trees that are not already face neighbors at that specific corner. In this case tree\\_to\\_corner indexes into *ctt_offset*. Otherwise the tree\\_to\\_corner entry must be -1 and this corner is ignored. If num\\_corners == 0, tree\\_to\\_corner and corner\\_to\\_* arrays are set to NULL. -# Arguments -* `filename`:\\[in\\] Name of the file to read. -* `bytes`:\\[out\\] Size in bytes of connectivity on disk or NULL. -# Returns -Returns valid connectivity, or NULL on file error. -### Prototype -```c -p8est_connectivity_t *p8est_connectivity_load (const char *filename, size_t *bytes); -``` +The arrays corner\\_to\\_* store a variable number of entries per corner. For corner c these are at position [ctt\\_offset[c]]..[ctt\\_offset[c+1]-1]. Their number for corner c is ctt\\_offset[c+1] - ctt\\_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner\\_to\\_* arrays is num\\_ctt = ctt\\_offset[num\\_corners]. + +The *\\_to\\_attr arrays may have arbitrary contents defined by the user. We do not interpret them. + +!!! note + + If a connectivity implies natural connections between trees that are corner neighbors without being face neighbors, these corners shall be encoded explicitly in the connectivity. """ -function p8est_connectivity_load(filename, bytes) - @ccall libp4est.p8est_connectivity_load(filename::Cstring, bytes::Ptr{Csize_t})::Ptr{p8est_connectivity_t} +const p4est_connectivity_t = p4est_connectivity + +""" + p4est_connectivity_shared + +| Field | Note | +| :---- | :--------------------------------------------------------- | +| conn | The members of this connectivity are MPI3 shared windows. | +""" +struct p4est_connectivity_shared + conn::Ptr{p4est_connectivity_t} + win_vertices::Cint + win_tree_to_vertex::Cint + win_tree_to_attr::Cint + win_tree_to_tree::Cint + win_tree_to_face::Cint + win_tree_to_corner::Cint + win_ctt_offset::Cint + win_corner_to_tree::Cint + win_corner_to_corner::Cint end +"""Management information for a connectivity shared by MPI3.""" +const p4est_connectivity_shared_t = p4est_connectivity_shared + """ - p8est_connectivity_new_unitcube() + p4est_connectivity_memory_used(conn) -Create a connectivity structure for the unit cube. +Calculate memory usage of a connectivity structure. +# Arguments +* `conn`:\\[in\\] Connectivity structure. +# Returns +Memory used in bytes. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_unitcube (void); +size_t p4est_connectivity_memory_used (p4est_connectivity_t * conn); ``` """ -function p8est_connectivity_new_unitcube() - @ccall libp4est.p8est_connectivity_new_unitcube()::Ptr{p8est_connectivity_t} +function p4est_connectivity_memory_used(conn) + @ccall libp4est.p4est_connectivity_memory_used(conn::Ptr{p4est_connectivity_t})::Csize_t end """ - p8est_connectivity_new_periodic() + p4est_corner_transform_t -Create a connectivity structure for an all-periodic unit cube. +Generic interface for transformations between a tree and any of its corner -### Prototype -```c -p8est_connectivity_t *p8est_connectivity_new_periodic (void); -``` +| Field | Note | +| :------ | :------------------------ | +| ntree | The number of the tree | +| ncorner | The number of the corner | """ -function p8est_connectivity_new_periodic() - @ccall libp4est.p8est_connectivity_new_periodic()::Ptr{p8est_connectivity_t} +struct p4est_corner_transform_t + ntree::p4est_topidx_t + ncorner::Int8 end """ - p8est_connectivity_new_rotwrap() + p4est_corner_info_t -Create a connectivity structure for a mostly periodic unit cube. The left and right faces are identified, and bottom and top rotated. Front and back are not identified. +Information about the neighbors of a corner -### Prototype -```c -p8est_connectivity_t *p8est_connectivity_new_rotwrap (void); -``` +| Field | Note | +| :------------------ | :------------------------------------------------ | +| icorner | The number of the originating corner | +| corner\\_transforms | The array of neighbors of the originating corner | """ -function p8est_connectivity_new_rotwrap() - @ccall libp4est.p8est_connectivity_new_rotwrap()::Ptr{p8est_connectivity_t} +struct p4est_corner_info_t + icorner::p4est_topidx_t + corner_transforms::sc_array_t end """ - p8est_connectivity_new_drop() + p4est_neighbor_transform_t -Create a connectivity structure for a five-trees geometry with a hole. The geometry is a 3D extrusion of the two drop example, and covers [0, 3]*[0, 2]*[0, 3]. The additional dimension is Y. +Generic interface for transformations between a tree and any of its neighbors -### Prototype -```c -p8est_connectivity_t *p8est_connectivity_new_drop (void); -``` +| Field | Note | +| :---------------- | :-------------------------------------------------------------------------- | +| neighbor\\_type | type of connection to neighbor | +| neighbor | neighbor tree index | +| index\\_self | index of interface from self's perspective | +| index\\_neighbor | index of interface from neighbor's perspective | +| perm | permutation of dimensions when transforming self coords to neighbor coords | +| sign | sign changes when transforming self coords to neighbor coords | +| origin\\_self | point on the interface from self's perspective | +| origin\\_neighbor | point on the interface from neighbor's perspective | """ -function p8est_connectivity_new_drop() - @ccall libp4est.p8est_connectivity_new_drop()::Ptr{p8est_connectivity_t} +struct p4est_neighbor_transform_t + neighbor_type::p4est_connect_type_t + neighbor::p4est_topidx_t + index_self::Int8 + index_neighbor::Int8 + perm::NTuple{2, Int8} + sign::NTuple{2, Int8} + origin_self::NTuple{2, p4est_qcoord_t} + origin_neighbor::NTuple{2, p4est_qcoord_t} end """ - p8est_connectivity_new_twocubes() + p4est_neighbor_transform_coordinates(nt, self_coords, neigh_coords) -Create a connectivity structure that contains two cubes. +Transform from self's coordinate system to neighbor's coordinate system. +# Arguments +* `nt`:\\[in\\] A neighbor transform. +* `self_coords`:\\[in\\] Input quadrant coordinates in self coordinates. +* `neigh_coords`:\\[out\\] Coordinates transformed into neighbor coordinates. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_twocubes (void); +void p4est_neighbor_transform_coordinates (const p4est_neighbor_transform_t * nt, const p4est_qcoord_t self_coords[P4EST_DIM], p4est_qcoord_t neigh_coords[P4EST_DIM]); ``` """ -function p8est_connectivity_new_twocubes() - @ccall libp4est.p8est_connectivity_new_twocubes()::Ptr{p8est_connectivity_t} +function p4est_neighbor_transform_coordinates(nt, self_coords, neigh_coords) + @ccall libp4est.p4est_neighbor_transform_coordinates(nt::Ptr{p4est_neighbor_transform_t}, self_coords::Ptr{p4est_qcoord_t}, neigh_coords::Ptr{p4est_qcoord_t})::Cvoid end """ - p8est_connectivity_new_twotrees(l_face, r_face, orientation) + p4est_neighbor_transform_coordinates_reverse(nt, neigh_coords, self_coords) -Create a connectivity structure for two trees being rotated w.r.t. each other in a user-defined way. +Transform from neighbor's coordinate system to self's coordinate system. # Arguments -* `l_face`:\\[in\\] index of left face -* `r_face`:\\[in\\] index of right face -* `orientation`:\\[in\\] orientation of trees w.r.t. each other +* `nt`:\\[in\\] A neighbor transform. +* `neigh_coords`:\\[in\\] Input quadrant coordinates in self coordinates. +* `self_coords`:\\[out\\] Coordinates transformed into neighbor coordinates. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_twotrees (int l_face, int r_face, int orientation); +void p4est_neighbor_transform_coordinates_reverse (const p4est_neighbor_transform_t * nt, const p4est_qcoord_t neigh_coords[P4EST_DIM], p4est_qcoord_t self_coords[P4EST_DIM]); ``` """ -function p8est_connectivity_new_twotrees(l_face, r_face, orientation) - @ccall libp4est.p8est_connectivity_new_twotrees(l_face::Cint, r_face::Cint, orientation::Cint)::Ptr{p8est_connectivity_t} +function p4est_neighbor_transform_coordinates_reverse(nt, neigh_coords, self_coords) + @ccall libp4est.p4est_neighbor_transform_coordinates_reverse(nt::Ptr{p4est_neighbor_transform_t}, neigh_coords::Ptr{p4est_qcoord_t}, self_coords::Ptr{p4est_qcoord_t})::Cvoid end """ - p8est_connectivity_new_twowrap() + p4est_connectivity_get_neighbor_transforms(conn, tree_id, boundary_type, boundary_index, neighbor_transform_array) -Create a connectivity structure that contains two cubes where the two far ends are identified periodically. +Fill an array with the neighbor transforms based on a specific boundary type. This function generalizes all other inter-tree transformation objects +# Arguments +* `conn`:\\[in\\] Connectivity structure. +* `tree_id`:\\[in\\] The number of the tree. +* `boundary_type`:\\[in\\] The type of the boundary connection (self, face, corner). +* `boundary_index`:\\[in\\] The index of the boundary. +* `neighbor_transform_array`:\\[in,out\\] Array of the neighbor transforms. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_twowrap (void); +void p4est_connectivity_get_neighbor_transforms (p4est_connectivity_t *conn, p4est_topidx_t tree_id, p4est_connect_type_t boundary_type, int boundary_index, sc_array_t *neighbor_transform_array); ``` """ -function p8est_connectivity_new_twowrap() - @ccall libp4est.p8est_connectivity_new_twowrap()::Ptr{p8est_connectivity_t} +function p4est_connectivity_get_neighbor_transforms(conn, tree_id, boundary_type, boundary_index, neighbor_transform_array) + @ccall libp4est.p4est_connectivity_get_neighbor_transforms(conn::Ptr{p4est_connectivity_t}, tree_id::p4est_topidx_t, boundary_type::p4est_connect_type_t, boundary_index::Cint, neighbor_transform_array::Ptr{sc_array_t})::Cvoid end """ - p8est_connectivity_new_rotcubes() + p4est_connectivity_coordinates_canonicalize(conn, treeid, coords, treeid_out, coords_out) -Create a connectivity structure that contains a few cubes. These are rotated against each other to stress the topology routines. +Determine the owning tree for a coordinate and transform it there. + +On a boundary between trees, different coordinate systems meet. A coordinate on a tree boundary face or corner generated from the perspective of a specific tree may be transformed into any other touching tree's coordinate system and still refer to the same point in the mesh. + +To uniquely identify a coordinate, this function identifies the lowest numbered tree touching this coordinate and transforms the coordinates into that system. The result can be used e. g. in topology hash tables. +# Arguments +* `conn`:\\[in\\] A valid connectivity. +* `treeid`:\\[in\\] The original tree index for this coordinate tuple. +* `coords`:\\[in\\] A valid coordinate 2-tuple relative to *treeid*. +* `treeid_out`:\\[out\\] The lowest tree index touching the coordinate. +* `coords_out`:\\[out\\] The input coordinates, if necessary after transformation into the system of the lowest numbered tree, returned in *treeid_out*. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_rotcubes (void); +void p4est_connectivity_coordinates_canonicalize (p4est_connectivity_t *conn, p4est_topidx_t treeid, const p4est_qcoord_t coords[], p4est_topidx_t *treeid_out, p4est_qcoord_t coords_out[]); ``` """ -function p8est_connectivity_new_rotcubes() - @ccall libp4est.p8est_connectivity_new_rotcubes()::Ptr{p8est_connectivity_t} +function p4est_connectivity_coordinates_canonicalize(conn, treeid, coords, treeid_out, coords_out) + @ccall libp4est.p4est_connectivity_coordinates_canonicalize(conn::Ptr{p4est_connectivity_t}, treeid::p4est_topidx_t, coords::Ptr{p4est_qcoord_t}, treeid_out::Ptr{p4est_topidx_t}, coords_out::Ptr{p4est_qcoord_t})::Cvoid end """ - p8est_connectivity_new_pillow() + p4est_connectivity_face_neighbor_face_corner(fc, f, nf, o) -Create a connectivity structure for two trees on top of each other. This connectivity is meant to be used with p8est_geometry_new_pillow to map a spherical shell. +Transform a face corner across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. +# Arguments +* `fc`:\\[in\\] A face corner number in 0..1. +* `f`:\\[in\\] A face that the face corner number *fc* is relative to. +* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. +* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. +# Returns +The face corner number relative to the neighbor's face. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_pillow (void); +int p4est_connectivity_face_neighbor_face_corner (int fc, int f, int nf, int o); ``` """ -function p8est_connectivity_new_pillow() - @ccall libp4est.p8est_connectivity_new_pillow()::Ptr{p8est_connectivity_t} +function p4est_connectivity_face_neighbor_face_corner(fc, f, nf, o) + @ccall libp4est.p4est_connectivity_face_neighbor_face_corner(fc::Cint, f::Cint, nf::Cint, o::Cint)::Cint end """ - p8est_connectivity_new_brick(m, n, p, periodic_a, periodic_b, periodic_c) + p4est_connectivity_face_neighbor_corner(c, f, nf, o) -An m by n by p array with periodicity in x, y, and z if periodic\\_a, periodic\\_b, and periodic\\_c are true, respectively. +Transform a corner across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. +# Arguments +* `c`:\\[in\\] A corner number in 0..3. +* `f`:\\[in\\] A face number that touches the corner *c*. +* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. +* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. +# Returns +The number of the corner seen from the neighbor tree. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_brick (int m, int n, int p, int periodic_a, int periodic_b, int periodic_c); +int p4est_connectivity_face_neighbor_corner (int c, int f, int nf, int o); ``` """ -function p8est_connectivity_new_brick(m, n, p, periodic_a, periodic_b, periodic_c) - @ccall libp4est.p8est_connectivity_new_brick(m::Cint, n::Cint, p::Cint, periodic_a::Cint, periodic_b::Cint, periodic_c::Cint)::Ptr{p8est_connectivity_t} +function p4est_connectivity_face_neighbor_corner(c, f, nf, o) + @ccall libp4est.p4est_connectivity_face_neighbor_corner(c::Cint, f::Cint, nf::Cint, o::Cint)::Cint end """ - p8est_connectivity_new_shell() + p4est_connectivity_new(num_vertices, num_trees, num_corners, num_ctt) -Create a connectivity structure that builds a spherical shell. It is made up of six connected parts [-1,1]x[-1,1]x[1,2]. This connectivity reuses vertices and relies on a geometry transformation. It is thus not suitable for [`p8est_connectivity_complete`](@ref). +Allocate a connectivity structure. The attribute fields are initialized to NULL. +# Arguments +* `num_vertices`:\\[in\\] Number of total vertices (i.e. geometric points). +* `num_trees`:\\[in\\] Number of trees in the forest. +* `num_corners`:\\[in\\] Number of tree-connecting corners. +* `num_ctt`:\\[in\\] Number of total trees in corner\\_to\\_tree array. +# Returns +A connectivity structure with allocated arrays. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_shell (void); +p4est_connectivity_t *p4est_connectivity_new (p4est_topidx_t num_vertices, p4est_topidx_t num_trees, p4est_topidx_t num_corners, p4est_topidx_t num_ctt); ``` """ -function p8est_connectivity_new_shell() - @ccall libp4est.p8est_connectivity_new_shell()::Ptr{p8est_connectivity_t} +function p4est_connectivity_new(num_vertices, num_trees, num_corners, num_ctt) + @ccall libp4est.p4est_connectivity_new(num_vertices::p4est_topidx_t, num_trees::p4est_topidx_t, num_corners::p4est_topidx_t, num_ctt::p4est_topidx_t)::Ptr{p4est_connectivity_t} end """ - p8est_connectivity_new_sphere() + p4est_connectivity_new_copy(num_vertices, num_trees, num_corners, vertices, ttv, ttt, ttf, ttc, coff, ctt, ctc) -Create a connectivity structure that builds a solid sphere. It is made up of two layers and a cube in the center. This connectivity reuses vertices and relies on a geometry transformation. It is thus not suitable for [`p8est_connectivity_complete`](@ref). +Allocate a connectivity structure and populate from constants. The attribute fields are initialized to NULL. +# Arguments +* `num_vertices`:\\[in\\] Number of total vertices (i.e. geometric points). +* `num_trees`:\\[in\\] Number of trees in the forest. +* `num_corners`:\\[in\\] Number of tree-connecting corners. +* `vertices`:\\[in\\] Coordinates of the vertices of the trees. +* `ttv`:\\[in\\] The tree-to-vertex array. +* `ttt`:\\[in\\] The tree-to-tree array. +* `ttf`:\\[in\\] The tree-to-face array (int8\\_t). +* `ttc`:\\[in\\] The tree-to-corner array. +* `coff`:\\[in\\] Corner-to-tree offsets (num\\_corners + 1 values). This must always be non-NULL; in trivial cases it is just a pointer to a p4est\\_topix value of 0. +* `ctt`:\\[in\\] The corner-to-tree array. +* `ctc`:\\[in\\] The corner-to-corner array. +# Returns +The connectivity is checked for validity. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_sphere (void); +p4est_connectivity_t *p4est_connectivity_new_copy (p4est_topidx_t num_vertices, p4est_topidx_t num_trees, p4est_topidx_t num_corners, const double *vertices, const p4est_topidx_t * ttv, const p4est_topidx_t * ttt, const int8_t * ttf, const p4est_topidx_t * ttc, const p4est_topidx_t * coff, const p4est_topidx_t * ctt, const int8_t * ctc); ``` """ -function p8est_connectivity_new_sphere() - @ccall libp4est.p8est_connectivity_new_sphere()::Ptr{p8est_connectivity_t} +function p4est_connectivity_new_copy(num_vertices, num_trees, num_corners, vertices, ttv, ttt, ttf, ttc, coff, ctt, ctc) + @ccall libp4est.p4est_connectivity_new_copy(num_vertices::p4est_topidx_t, num_trees::p4est_topidx_t, num_corners::p4est_topidx_t, vertices::Ptr{Cdouble}, ttv::Ptr{p4est_topidx_t}, ttt::Ptr{p4est_topidx_t}, ttf::Ptr{Int8}, ttc::Ptr{p4est_topidx_t}, coff::Ptr{p4est_topidx_t}, ctt::Ptr{p4est_topidx_t}, ctc::Ptr{Int8})::Ptr{p4est_connectivity_t} end """ - p8est_connectivity_new_torus(nSegments) + p4est_connectivity_copy(input, copy_attr) -Create a connectivity structure that builds a revolution torus. +Deep copy a connectivity structure. -This connectivity reuses vertices and relies on a geometry transformation. It is thus not suitable for [`p8est_connectivity_complete`](@ref). +# Arguments +* `input`:\\[in\\] Valid connectivity. +* `copy_attr`:\\[in\\] If true, we copy the tree attribute data. Otherwise, the result has empty attributes. +# Returns +A connectivity equal to the first one except, depending on *copy_attry*, for its attributes. +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_copy (p4est_connectivity_t *input, int copy_attr); +``` +""" +function p4est_connectivity_copy(input, copy_attr) + @ccall libp4est.p4est_connectivity_copy(input::Ptr{p4est_connectivity_t}, copy_attr::Cint)::Ptr{p4est_connectivity_t} +end -This connectivity reuses ideas from disk2d connectivity. More precisely the torus is divided into segments around the revolution axis, each segments is made of 5 trees (à la disk2d). The total number of trees if 5 times the number of segments. +""" + p4est_connectivity_bcast(conn_in, root, comm) -This connectivity is meant to be used with p8est_geometry_new_torus +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_bcast (p4est_connectivity_t * conn_in, int root, sc_MPI_Comm comm); +``` +""" +function p4est_connectivity_bcast(conn_in, root, comm) + @ccall libp4est.p4est_connectivity_bcast(conn_in::Ptr{p4est_connectivity_t}, root::Cint, comm::MPI_Comm)::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_destroy(connectivity) + +Destroy a connectivity structure. Also destroy all attributes. -# Arguments -* `nSegments`:\\[in\\] number of trees along the great circle ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_torus (int nSegments); +void p4est_connectivity_destroy (p4est_connectivity_t * connectivity); ``` """ -function p8est_connectivity_new_torus(nSegments) - @ccall libp4est.p8est_connectivity_new_torus(nSegments::Cint)::Ptr{p8est_connectivity_t} +function p4est_connectivity_destroy(connectivity) + @ccall libp4est.p4est_connectivity_destroy(connectivity::Ptr{p4est_connectivity_t})::Cvoid end """ - p8est_connectivity_new_byname(name) + p4est_connectivity_share(conn_in, root, comm) -Create connectivity structure from predefined catalogue. +### Prototype +```c +p4est_connectivity_shared_t *p4est_connectivity_share (p4est_connectivity_t * conn_in, int root, sc_MPI_Comm comm); +``` +""" +function p4est_connectivity_share(conn_in, root, comm) + @ccall libp4est.p4est_connectivity_share(conn_in::Ptr{p4est_connectivity_t}, root::Cint, comm::MPI_Comm)::Ptr{p4est_connectivity_shared_t} +end + +""" + p4est_connectivity_mission(conn_in, split_type, world_comm) -# Arguments -* `name`:\\[in\\] Invokes connectivity\\_new\\_* function. brick235 brick (2, 3, 5, 0, 0, 0) periodic periodic rotcubes rotcubes rotwrap rotwrap shell shell sphere sphere twocubes twocubes twowrap twowrap unit unitcube -# Returns -An initialized connectivity if name is defined, NULL else. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_new_byname (const char *name); +p4est_connectivity_shared_t * p4est_connectivity_mission (p4est_connectivity_t *conn_in, int split_type, sc_MPI_Comm world_comm); ``` """ -function p8est_connectivity_new_byname(name) - @ccall libp4est.p8est_connectivity_new_byname(name::Cstring)::Ptr{p8est_connectivity_t} +function p4est_connectivity_mission(conn_in, split_type, world_comm) + @ccall libp4est.p4est_connectivity_mission(conn_in::Ptr{p4est_connectivity_t}, split_type::Cint, world_comm::Cint)::Ptr{p4est_connectivity_shared_t} end """ - p8est_connectivity_refine(conn, num_per_dim) + p4est_connectivity_shared_destroy(cshare) -Uniformly refine a connectivity. This is useful if you would like to uniformly refine by something other than a power of 2. +Destroy a shared connectivity structure. Call this eventually on the result of p4est_connectivity_share or p4est_connectivity_mission (which calls the former internally). # Arguments -* `conn`:\\[in\\] A valid connectivity -* `num_per_dim`:\\[in\\] The number of new trees in each direction. Must use no more than P8EST_OLD_QMAXLEVEL bits. -# Returns -a refined connectivity. +* `cshare`:\\[in\\] Valid shared connectivity structure; cf. p4est_connectivity_share. ### Prototype ```c -p8est_connectivity_t *p8est_connectivity_refine (p8est_connectivity_t * conn, int num_per_dim); +void p4est_connectivity_shared_destroy (p4est_connectivity_shared_t *cshare); ``` """ -function p8est_connectivity_refine(conn, num_per_dim) - @ccall libp4est.p8est_connectivity_refine(conn::Ptr{p8est_connectivity_t}, num_per_dim::Cint)::Ptr{p8est_connectivity_t} +function p4est_connectivity_shared_destroy(cshare) + @ccall libp4est.p4est_connectivity_shared_destroy(cshare::Ptr{p4est_connectivity_shared_t})::Cvoid end """ - p8est_expand_face_transform(iface, nface, ftransform) + p4est_connectivity_set_attr(conn, bytes_per_tree) -Fill an array with the axis combination of a face neighbor transform. +Allocate or free the attribute fields in a connectivity. # Arguments -* `iface`:\\[in\\] The number of the originating face. -* `nface`:\\[in\\] Encoded as nface = r * 6 + nf, where nf = 0..5 is the neigbbor's connecting face number and r = 0..3 is the relative orientation to the neighbor's face. This encoding matches [`p8est_connectivity_t`](@ref). -* `ftransform`:\\[out\\] This array holds 9 integers. [0]..[2] The coordinate axis sequence of the origin face, the first two referring to the tangentials and the third to the normal. A permutation of (0, 1, 2). [3]..[5] The coordinate axis sequence of the target face. [6]..[8] Edge reversal flags for tangential axes (boolean); face code in [0, 3] for the normal coordinate q: 0: q' = -q 1: q' = q + 1 2: q' = q - 1 3: q' = 2 - q +* `conn`:\\[in,out\\] The conn->*\\_to\\_attr fields must either be NULL or previously be allocated by this function. +* `bytes_per_tree`:\\[in\\] If 0, tree\\_to\\_attr is freed (being NULL is ok). If positive, requested space is allocated. ### Prototype ```c -void p8est_expand_face_transform (int iface, int nface, int ftransform[]); +void p4est_connectivity_set_attr (p4est_connectivity_t * conn, size_t bytes_per_tree); ``` """ -function p8est_expand_face_transform(iface, nface, ftransform) - @ccall libp4est.p8est_expand_face_transform(iface::Cint, nface::Cint, ftransform::Ptr{Cint})::Cvoid +function p4est_connectivity_set_attr(conn, bytes_per_tree) + @ccall libp4est.p4est_connectivity_set_attr(conn::Ptr{p4est_connectivity_t}, bytes_per_tree::Csize_t)::Cvoid end """ - p8est_find_face_transform(connectivity, itree, iface, ftransform) + p4est_connectivity_is_valid(connectivity) -Fill an array with the axis combination of a face neighbor transform. +Examine a connectivity structure. -# Arguments -* `connectivity`:\\[in\\] Connectivity structure. -* `itree`:\\[in\\] The number of the originating tree. -* `iface`:\\[in\\] The number of the originating tree's face. -* `ftransform`:\\[out\\] This array holds 9 integers. [0]..[2] The coordinate axis sequence of the origin face. [3]..[5] The coordinate axis sequence of the target face. [6]..[8] Edge reversal flag for axes t1, t2; face code for n; # Returns -The face neighbor tree if it exists, -1 otherwise. -# See also -[`p8est_expand_face_transform`](@ref). - +Returns true if structure is valid, false otherwise. ### Prototype ```c -p4est_topidx_t p8est_find_face_transform (p8est_connectivity_t * connectivity, p4est_topidx_t itree, int iface, int ftransform[]); +int p4est_connectivity_is_valid (p4est_connectivity_t * connectivity); ``` """ -function p8est_find_face_transform(connectivity, itree, iface, ftransform) - @ccall libp4est.p8est_find_face_transform(connectivity::Ptr{p8est_connectivity_t}, itree::p4est_topidx_t, iface::Cint, ftransform::Ptr{Cint})::p4est_topidx_t +function p4est_connectivity_is_valid(connectivity) + @ccall libp4est.p4est_connectivity_is_valid(connectivity::Ptr{p4est_connectivity_t})::Cint end """ - p8est_find_edge_transform(connectivity, itree, iedge, ei) + p4est_connectivity_is_equal(conn1, conn2) -Fills an array with information about edge neighbors. +Check two connectivity structures for equality. -# Arguments -* `connectivity`:\\[in\\] Connectivity structure. -* `itree`:\\[in\\] The number of the originating tree. -* `iedge`:\\[in\\] The number of the originating edge. -* `ei`:\\[in,out\\] A [`p8est_edge_info_t`](@ref) structure with initialized array. +# Returns +Returns true if structures are equal, false otherwise. ### Prototype ```c -void p8est_find_edge_transform (p8est_connectivity_t * connectivity, p4est_topidx_t itree, int iedge, p8est_edge_info_t * ei); +int p4est_connectivity_is_equal (p4est_connectivity_t * conn1, p4est_connectivity_t * conn2); ``` """ -function p8est_find_edge_transform(connectivity, itree, iedge, ei) - @ccall libp4est.p8est_find_edge_transform(connectivity::Ptr{p8est_connectivity_t}, itree::p4est_topidx_t, iedge::Cint, ei::Ptr{p8est_edge_info_t})::Cvoid +function p4est_connectivity_is_equal(conn1, conn2) + @ccall libp4est.p4est_connectivity_is_equal(conn1::Ptr{p4est_connectivity_t}, conn2::Ptr{p4est_connectivity_t})::Cint end """ - p8est_find_corner_transform(connectivity, itree, icorner, ci) + p4est_connectivity_sink(conn, sink) -Fills an array with information about corner neighbors. +Write connectivity to a sink object. # Arguments -* `connectivity`:\\[in\\] Connectivity structure. -* `itree`:\\[in\\] The number of the originating tree. -* `icorner`:\\[in\\] The number of the originating corner. -* `ci`:\\[in,out\\] A [`p8est_corner_info_t`](@ref) structure with initialized array. +* `conn`:\\[in\\] The connectivity to be written. +* `sink`:\\[in,out\\] The connectivity is written into this sink. +# Returns +0 on success, nonzero on error. ### Prototype ```c -void p8est_find_corner_transform (p8est_connectivity_t * connectivity, p4est_topidx_t itree, int icorner, p8est_corner_info_t * ci); +int p4est_connectivity_sink (p4est_connectivity_t * conn, sc_io_sink_t * sink); ``` """ -function p8est_find_corner_transform(connectivity, itree, icorner, ci) - @ccall libp4est.p8est_find_corner_transform(connectivity::Ptr{p8est_connectivity_t}, itree::p4est_topidx_t, icorner::Cint, ci::Ptr{p8est_corner_info_t})::Cvoid +function p4est_connectivity_sink(conn, sink) + @ccall libp4est.p4est_connectivity_sink(conn::Ptr{p4est_connectivity_t}, sink::Ptr{sc_io_sink_t})::Cint end """ - p8est_connectivity_complete(conn) + p4est_connectivity_deflate(conn, code) -Internally connect a connectivity based on tree\\_to\\_vertex information. Periodicity that is not inherent in the list of vertices will be lost. +Allocate memory and store the connectivity information there. # Arguments -* `conn`:\\[in,out\\] The connectivity needs to have proper vertices and tree\\_to\\_vertex fields. The tree\\_to\\_tree and tree\\_to\\_face fields must be allocated and satisfy [`p8est_connectivity_is_valid`](@ref) (conn) but will be overwritten. The edge and corner fields will be freed and allocated anew. +* `conn`:\\[in\\] The connectivity structure to be exported to memory. +* `code`:\\[in\\] Encoding and compression method for serialization. +# Returns +Newly created array that contains the information. ### Prototype ```c -void p8est_connectivity_complete (p8est_connectivity_t * conn); +sc_array_t *p4est_connectivity_deflate (p4est_connectivity_t * conn, p4est_connectivity_encode_t code); ``` """ -function p8est_connectivity_complete(conn) - @ccall libp4est.p8est_connectivity_complete(conn::Ptr{p8est_connectivity_t})::Cvoid +function p4est_connectivity_deflate(conn, code) + @ccall libp4est.p4est_connectivity_deflate(conn::Ptr{p4est_connectivity_t}, code::p4est_connectivity_encode_t)::Ptr{sc_array_t} end """ - p8est_connectivity_reduce(conn) + p4est_connectivity_save(filename, connectivity) -Removes corner and edge information of a connectivity such that enough information is left to run [`p8est_connectivity_complete`](@ref) successfully. The reduced connectivity still passes [`p8est_connectivity_is_valid`](@ref). +Save a connectivity structure to disk. # Arguments -* `conn`:\\[in,out\\] The connectivity to be reduced. +* `filename`:\\[in\\] Name of the file to write. +* `connectivity`:\\[in\\] Valid connectivity structure. +# Returns +Returns 0 on success, nonzero on file error. ### Prototype ```c -void p8est_connectivity_reduce (p8est_connectivity_t * conn); +int p4est_connectivity_save (const char *filename, p4est_connectivity_t * connectivity); ``` """ -function p8est_connectivity_reduce(conn) - @ccall libp4est.p8est_connectivity_reduce(conn::Ptr{p8est_connectivity_t})::Cvoid +function p4est_connectivity_save(filename, connectivity) + @ccall libp4est.p4est_connectivity_save(filename::Cstring, connectivity::Ptr{p4est_connectivity_t})::Cint end """ - p8est_connectivity_permute(conn, perm, is_current_to_new) + p4est_connectivity_source(source) -[`p8est_connectivity_permute`](@ref) Given a permutation *perm* of the trees in a connectivity *conn*, permute the trees of *conn* in place and update *conn* to match. +Read connectivity from a source object. # Arguments -* `conn`:\\[in,out\\] The connectivity whose trees are permuted. -* `perm`:\\[in\\] A permutation array, whose elements are size\\_t's. -* `is_current_to_new`:\\[in\\] if true, the jth entry of perm is the new index for the entry whose current index is j, otherwise the jth entry of perm is the current index of the tree whose index will be j after the permutation. +* `source`:\\[in,out\\] The connectivity is read from this source. +# Returns +The newly created connectivity, or NULL on error. ### Prototype ```c -void p8est_connectivity_permute (p8est_connectivity_t * conn, sc_array_t * perm, int is_current_to_new); +p4est_connectivity_t *p4est_connectivity_source (sc_io_source_t * source); ``` """ -function p8est_connectivity_permute(conn, perm, is_current_to_new) - @ccall libp4est.p8est_connectivity_permute(conn::Ptr{p8est_connectivity_t}, perm::Ptr{sc_array_t}, is_current_to_new::Cint)::Cvoid +function p4est_connectivity_source(source) + @ccall libp4est.p4est_connectivity_source(source::Ptr{sc_io_source_t})::Ptr{p4est_connectivity_t} end """ - p8est_connectivity_join_faces(conn, tree_left, tree_right, face_left, face_right, orientation) + p4est_connectivity_inflate(buffer) -[`p8est_connectivity_join_faces`](@ref) This function takes an existing valid connectivity *conn* and modifies it by joining two tree faces that are currently boundary faces. +Create new connectivity from a memory buffer. This function aborts on malloc errors. # Arguments -* `conn`:\\[in,out\\] connectivity that will be altered. -* `tree_left`:\\[in\\] tree that will be on the left side of the joined faces. -* `tree_right`:\\[in\\] tree that will be on the right side of the joined faces. -* `face_left`:\\[in\\] face of *tree_left* that will be joined. -* `face_right`:\\[in\\] face of *tree_right* that will be joined. -* `orientation`:\\[in\\] the orientation of *face_left* and *face_right* once joined (see the description of [`p8est_connectivity_t`](@ref) to understand orientation). +* `buffer`:\\[in\\] The connectivity is created from this memory buffer. +# Returns +The newly created connectivity, or NULL on format error of the buffered connectivity data. ### Prototype ```c -void p8est_connectivity_join_faces (p8est_connectivity_t * conn, p4est_topidx_t tree_left, p4est_topidx_t tree_right, int face_left, int face_right, int orientation); +p4est_connectivity_t *p4est_connectivity_inflate (sc_array_t * buffer); ``` """ -function p8est_connectivity_join_faces(conn, tree_left, tree_right, face_left, face_right, orientation) - @ccall libp4est.p8est_connectivity_join_faces(conn::Ptr{p8est_connectivity_t}, tree_left::p4est_topidx_t, tree_right::p4est_topidx_t, face_left::Cint, face_right::Cint, orientation::Cint)::Cvoid +function p4est_connectivity_inflate(buffer) + @ccall libp4est.p4est_connectivity_inflate(buffer::Ptr{sc_array_t})::Ptr{p4est_connectivity_t} end """ - p8est_connectivity_is_equivalent(conn1, conn2) + p4est_connectivity_load(filename, bytes) -[`p8est_connectivity_is_equivalent`](@ref) This function compares two connectivities for equivalence: it returns *true* if they are the same connectivity, or if they have the same topology. The definition of topological sameness is strict: there is no attempt made to determine whether permutation and/or rotation of the trees makes the connectivities equivalent. +Load a connectivity structure from disk. # Arguments -* `conn1`:\\[in\\] a valid connectivity -* `conn2`:\\[out\\] a valid connectivity +* `filename`:\\[in\\] Name of the file to read. +* `bytes`:\\[in,out\\] Size in bytes of connectivity on disk or NULL. +# Returns +Returns valid connectivity, or NULL on file error. ### Prototype ```c -int p8est_connectivity_is_equivalent (p8est_connectivity_t * conn1, p8est_connectivity_t * conn2); +p4est_connectivity_t *p4est_connectivity_load (const char *filename, size_t *bytes); ``` """ -function p8est_connectivity_is_equivalent(conn1, conn2) - @ccall libp4est.p8est_connectivity_is_equivalent(conn1::Ptr{p8est_connectivity_t}, conn2::Ptr{p8est_connectivity_t})::Cint +function p4est_connectivity_load(filename, bytes) + @ccall libp4est.p4est_connectivity_load(filename::Cstring, bytes::Ptr{Csize_t})::Ptr{p4est_connectivity_t} end """ - p8est_edge_array_index(array, it) + p4est_connectivity_new_unitsquare() + +Create a connectivity structure for the unit square. ### Prototype ```c -static inline p8est_edge_transform_t * p8est_edge_array_index (sc_array_t *array, size_t it); +p4est_connectivity_t *p4est_connectivity_new_unitsquare (void); ``` """ -function p8est_edge_array_index(array, it) - @ccall libp4est.p8est_edge_array_index(array::Ptr{sc_array_t}, it::Csize_t)::Ptr{p8est_edge_transform_t} +function p4est_connectivity_new_unitsquare() + @ccall libp4est.p4est_connectivity_new_unitsquare()::Ptr{p4est_connectivity_t} end """ - p8est_corner_array_index(array, it) + p4est_connectivity_new_periodic() + +Create a connectivity structure for an all-periodic unit square. ### Prototype ```c -static inline p8est_corner_transform_t * p8est_corner_array_index (sc_array_t *array, size_t it); +p4est_connectivity_t *p4est_connectivity_new_periodic (void); ``` """ -function p8est_corner_array_index(array, it) - @ccall libp4est.p8est_corner_array_index(array::Ptr{sc_array_t}, it::Csize_t)::Ptr{p8est_corner_transform_t} +function p4est_connectivity_new_periodic() + @ccall libp4est.p4est_connectivity_new_periodic()::Ptr{p4est_connectivity_t} end """ - p8est_connectivity_read_inp_stream(stream, num_vertices, num_trees, vertices, tree_to_vertex) + p4est_connectivity_new_rotwrap() -Read an ABAQUS input file from a file stream. +Create a connectivity structure for a periodic unit square. The left and right faces are identified, and bottom and top opposite. -This utility function reads a basic ABAQUS file supporting element type with the prefix C2D4, CPS4, and S4 in 2D and of type C3D8 reading them as bilinear quadrilateral and trilinear hexahedral trees respectively. +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_rotwrap (void); +``` +""" +function p4est_connectivity_new_rotwrap() + @ccall libp4est.p4est_connectivity_new_rotwrap()::Ptr{p4est_connectivity_t} +end -A basic 2D mesh is given below. The `*Node` section gives the vertex number and x, y, and z components for each vertex. The `*Element` section gives the 4 vertices in 2D (8 vertices in 3D) of each element in counter clockwise order. So in 2D the nodes are given as: +""" + p4est_connectivity_new_circle() -4 3 +-------------------+ | | | | | | | | | | | | +-------------------+ 1 2 +Create a connectivity structure for an donut-like circle. The circle consists of 6 trees connecting each other by their faces. The trees are laid out as a hexagon between [-2, 2] in the y direction and [-sqrt(3), sqrt(3)] in the x direction. The hexagon has flat sides along the y direction and pointy ends in x. -and in 3D they are given as: +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_circle (void); +``` +""" +function p4est_connectivity_new_circle() + @ccall libp4est.p4est_connectivity_new_circle()::Ptr{p4est_connectivity_t} +end -8 7 +---------------------+ |\\ |\\ | \\ | \\ | \\ | \\ | \\ | \\ | 5+---------------------+6 | | | | +----|----------------+ | 4\\ | 3 \\ | \\ | \\ | \\ | \\ | \\| \\| +---------------------+ 1 2 +""" + p4est_connectivity_new_drop() -```c++ - *Heading - box.inp - *Node - 1, 5, -5, 5 - 2, 5, 5, 5 - 3, 5, 0, 5 - 4, -5, 5, 5 - 5, 0, 5, 5 - 6, -5, -5, 5 - 7, -5, 0, 5 - 8, 0, -5, 5 - 9, 0, 0, 5 - 10, 5, 5, -5 - 11, 5, -5, -5 - 12, 5, 0, -5 - 13, -5, -5, -5 - 14, 0, -5, -5 - 15, -5, 5, -5 - 16, -5, 0, -5 - 17, 0, 5, -5 - 18, 0, 0, -5 - 19, -5, -5, 0 - 20, 5, -5, 0 - 21, 0, -5, 0 - 22, -5, 5, 0 - 23, -5, 0, 0 - 24, 5, 5, 0 - 25, 0, 5, 0 - 26, 5, 0, 0 - 27, 0, 0, 0 - *Element, type=C3D8, ELSET=EB1 - 1, 6, 19, 23, 7, 8, 21, 27, 9 - 2, 19, 13, 16, 23, 21, 14, 18, 27 - 3, 7, 23, 22, 4, 9, 27, 25, 5 - 4, 23, 16, 15, 22, 27, 18, 17, 25 - 5, 8, 21, 27, 9, 1, 20, 26, 3 - 6, 21, 14, 18, 27, 20, 11, 12, 26 - 7, 9, 27, 25, 5, 3, 26, 24, 2 - 8, 27, 18, 17, 25, 26, 12, 10, 24 +Create a connectivity structure for a five-trees geometry with a hole. The geometry covers the square [0, 3]**2, where the hole is [1, 2]**2. + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_drop (void); ``` +""" +function p4est_connectivity_new_drop() + @ccall libp4est.p4est_connectivity_new_drop()::Ptr{p4est_connectivity_t} +end -This code can be called two ways. The first, when `vertex`==NULL and `tree_to_vertex`==NULL, is used to count the number of trees and vertices in the connectivity to be generated by the `.inp` mesh in the *stream*. The second, when `vertices`!=NULL and `tree_to_vertex`!=NULL, fill `vertices` and `tree_to_vertex`. In this case `num_vertices` and `num_trees` need to be set to the maximum number of entries allocated in `vertices` and `tree_to_vertex`. +""" + p4est_connectivity_new_twotrees(l_face, r_face, orientation) + +Create a connectivity structure for two trees being rotated w.r.t. each other in a user-defined way # Arguments -* `stream`:\\[in,out\\] file stream to read the connectivity from -* `num_vertices`:\\[in,out\\] the number of vertices in the connectivity -* `num_trees`:\\[in,out\\] the number of trees in the connectivity -* `vertices`:\\[out\\] the list of `vertices` of the connectivity -* `tree_to_vertex`:\\[out\\] the `tree_to_vertex` map of the connectivity +* `l_face`:\\[in\\] index of left face +* `r_face`:\\[in\\] index of right face +* `orientation`:\\[in\\] orientation of trees w.r.t. each other +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_twotrees (int l_face, int r_face, int orientation); +``` +""" +function p4est_connectivity_new_twotrees(l_face, r_face, orientation) + @ccall libp4est.p4est_connectivity_new_twotrees(l_face::Cint, r_face::Cint, orientation::Cint)::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_corner() + +Create a connectivity structure for a three-tree mesh around a corner. + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_corner (void); +``` +""" +function p4est_connectivity_new_corner() + @ccall libp4est.p4est_connectivity_new_corner()::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_pillow() + +Create a connectivity structure for two trees on top of each other. + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_pillow (void); +``` +""" +function p4est_connectivity_new_pillow() + @ccall libp4est.p4est_connectivity_new_pillow()::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_moebius() + +Create a connectivity structure for a five-tree moebius band. + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_moebius (void); +``` +""" +function p4est_connectivity_new_moebius() + @ccall libp4est.p4est_connectivity_new_moebius()::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_star() + +Create a connectivity structure for a six-tree star. + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_star (void); +``` +""" +function p4est_connectivity_new_star() + @ccall libp4est.p4est_connectivity_new_star()::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_cubed() + +Create a connectivity structure for the six sides of a unit cube. The ordering of the trees is as follows: + +0 1 2 3 <-- 3: axis-aligned top side 4 5 + +This choice has been made for maximum symmetry (see tree\\_to\\_* in .c file). + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_cubed (void); +``` +""" +function p4est_connectivity_new_cubed() + @ccall libp4est.p4est_connectivity_new_cubed()::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_disk_nonperiodic() + +Create a connectivity structure for a five-tree flat spherical disk. This disk can just as well be used as a square to test non-Cartesian maps. Without any mapping this connectivity covers the square [-3, 3]**2. + # Returns -0 if successful and nonzero if not +Initialized and usable connectivity. ### Prototype ```c -int p8est_connectivity_read_inp_stream (FILE * stream, p4est_topidx_t * num_vertices, p4est_topidx_t * num_trees, double *vertices, p4est_topidx_t * tree_to_vertex); +p4est_connectivity_t *p4est_connectivity_new_disk_nonperiodic (void); ``` """ -function p8est_connectivity_read_inp_stream(stream, num_vertices, num_trees, vertices, tree_to_vertex) - @ccall libp4est.p8est_connectivity_read_inp_stream(stream::Ptr{Libc.FILE}, num_vertices::Ptr{p4est_topidx_t}, num_trees::Ptr{p4est_topidx_t}, vertices::Ptr{Cdouble}, tree_to_vertex::Ptr{p4est_topidx_t})::Cint +function p4est_connectivity_new_disk_nonperiodic() + @ccall libp4est.p4est_connectivity_new_disk_nonperiodic()::Ptr{p4est_connectivity_t} end """ - p8est_connectivity_read_inp(filename) + p4est_connectivity_new_disk(periodic_a, periodic_b) -Create a p4est connectivity from an ABAQUS input file. +Create a connectivity structure for a five-tree flat spherical disk. This disk can just as well be used as a square to test non-Cartesian maps. Without any mapping this connectivity covers the square [-3, 3]**2. -This utility function reads a basic ABAQUS file supporting element type with the prefix C2D4, CPS4, and S4 in 2D and of type C3D8 reading them as bilinear quadrilateral and trilinear hexahedral trees respectively. +!!! note -A basic 2D mesh is given below. The `*Node` section gives the vertex number and x, y, and z components for each vertex. The `*Element` section gives the 4 vertices in 2D (8 vertices in 3D) of each element in counter clockwise order. So in 2D the nodes are given as: + The API of this function has changed to accept two arguments. You can query the P4EST_CONN_DISK_PERIODIC to check whether the new version with the argument is in effect. -4 3 +-------------------+ | | | | | | | | | | | | +-------------------+ 1 2 +The ordering of the trees is as follows: -and in 3D they are given as: +4 1 2 3 0 -8 7 +---------------------+ |\\ |\\ | \\ | \\ | \\ | \\ | \\ | \\ | 5+---------------------+6 | | | | +----|----------------+ | 4\\ | 3 \\ | \\ | \\ | \\ | \\ | \\| \\| +---------------------+ 1 2 +The outside x faces may be identified topologically. The outside y faces may be identified topologically. Both identifications may be specified simultaneously. The general shape and periodicity are the same as those obtained with p4est_connectivity_new_brick (1, 1, periodic\\_a, periodic\\_b). -```c++ - *Heading - box.inp - *Node - 1, 5, -5, 5 - 2, 5, 5, 5 - 3, 5, 0, 5 - 4, -5, 5, 5 - 5, 0, 5, 5 - 6, -5, -5, 5 - 7, -5, 0, 5 - 8, 0, -5, 5 - 9, 0, 0, 5 - 10, 5, 5, -5 - 11, 5, -5, -5 - 12, 5, 0, -5 - 13, -5, -5, -5 - 14, 0, -5, -5 - 15, -5, 5, -5 - 16, -5, 0, -5 - 17, 0, 5, -5 - 18, 0, 0, -5 - 19, -5, -5, 0 - 20, 5, -5, 0 - 21, 0, -5, 0 - 22, -5, 5, 0 - 23, -5, 0, 0 - 24, 5, 5, 0 - 25, 0, 5, 0 - 26, 5, 0, 0 - 27, 0, 0, 0 - *Element, type=C3D8, ELSET=EB1 - 1, 6, 19, 23, 7, 8, 21, 27, 9 - 2, 19, 13, 16, 23, 21, 14, 18, 27 - 3, 7, 23, 22, 4, 9, 27, 25, 5 - 4, 23, 16, 15, 22, 27, 18, 17, 25 - 5, 8, 21, 27, 9, 1, 20, 26, 3 - 6, 21, 14, 18, 27, 20, 11, 12, 26 - 7, 9, 27, 25, 5, 3, 26, 24, 2 - 8, 27, 18, 17, 25, 26, 12, 10, 24 +When setting *periodic_a* and *periodic_b* to false, the result is the same as that of p4est_connectivity_new_disk_nonperiodic. + +# Arguments +* `periodic_a`:\\[in\\] Bool to make disk periodic in x direction. +* `periodic_b`:\\[in\\] Bool to make disk periodic in y direction. +# Returns +Initialized and usable connectivity. +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_disk (int periodic_a, int periodic_b); ``` +""" +function p4est_connectivity_new_disk(periodic_a, periodic_b) + @ccall libp4est.p4est_connectivity_new_disk(periodic_a::Cint, periodic_b::Cint)::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_icosahedron() + +Create a connectivity for mapping the sphere using an icosahedron. + +The regular icosadron is a polyhedron with 20 faces, each of which is an equilateral triangle. To build the p4est connectivity, we group faces 2 by 2 to from 10 quadrangles, and thus 10 trees. + +This connectivity is meant to be used together with p4est_geometry_new_icosahedron to map the sphere. + +The flat connectivity looks like that. Vextex numbering: + +A00 A01 A02 A03 A04 / \\ / \\ / \\ / \\ / \\ A05---A06---A07---A08---A09---A10 \\ / \\ / \\ / \\ / \\ / \\ A11---A12---A13---A14---A15---A16 \\ / \\ / \\ / \\ / \\ / A17 A18 A19 A20 A21 + +Origin in A05. + +Tree numbering: + +0 2 4 6 8 1 3 5 7 9 + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_icosahedron (void); +``` +""" +function p4est_connectivity_new_icosahedron() + @ccall libp4est.p4est_connectivity_new_icosahedron()::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_shell2d() + +Create a connectivity structure that builds a 2d spherical shell. p8est_connectivity_new_shell + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_shell2d (void); +``` +""" +function p4est_connectivity_new_shell2d() + @ccall libp4est.p4est_connectivity_new_shell2d()::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_disk2d() + +Create a connectivity structure that maps a 2d disk. + +This is a 5 trees connectivity meant to be used together with p4est_geometry_new_disk2d to map the disk. + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_disk2d (void); +``` +""" +function p4est_connectivity_new_disk2d() + @ccall libp4est.p4est_connectivity_new_disk2d()::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_bowtie() + +Create a connectivity structure that maps a 2d bowtie structure. + +The 2 trees are connected by a corner connection at node A3 (0, 0). the nodes are given as: + +A00 A01 / \\ / \\ A02 A03 A04 \\ / \\ / A05 A06 + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_bowtie (void); +``` +""" +function p4est_connectivity_new_bowtie() + @ccall libp4est.p4est_connectivity_new_bowtie()::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_brick(mi, ni, periodic_a, periodic_b) + +A rectangular m by n array of trees with configurable periodicity. The brick is periodic in x and y if periodic\\_a and periodic\\_b are true, respectively. + +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_brick (int mi, int ni, int periodic_a, int periodic_b); +``` +""" +function p4est_connectivity_new_brick(mi, ni, periodic_a, periodic_b) + @ccall libp4est.p4est_connectivity_new_brick(mi::Cint, ni::Cint, periodic_a::Cint, periodic_b::Cint)::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_new_byname(name) + +Create connectivity structure from predefined catalogue. + +# Arguments +* `name`:\\[in\\] Invokes connectivity\\_new\\_* function. brick23 brick (2, 3, 0, 0) corner corner cubed cubed disk disk moebius moebius periodic periodic pillow pillow rotwrap rotwrap star star unit unitsquare +# Returns +An initialized connectivity if name is defined, NULL else. +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_new_byname (const char *name); +``` +""" +function p4est_connectivity_new_byname(name) + @ccall libp4est.p4est_connectivity_new_byname(name::Cstring)::Ptr{p4est_connectivity_t} +end + +""" + p4est_connectivity_refine(conn, num_per_dim) + +Uniformly refine a connectivity. This is useful if you would like to uniformly refine by something other than a power of 2. + +# Arguments +* `conn`:\\[in\\] A valid connectivity +* `num_per_dim`:\\[in\\] The number of new trees in each direction. Must use no more than P4EST_OLD_QMAXLEVEL bits. +# Returns +a refined connectivity. +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_refine (p4est_connectivity_t * conn, int num_per_dim); +``` +""" +function p4est_connectivity_refine(conn, num_per_dim) + @ccall libp4est.p4est_connectivity_refine(conn::Ptr{p4est_connectivity_t}, num_per_dim::Cint)::Ptr{p4est_connectivity_t} +end + +""" + p4est_expand_face_transform(iface, nface, ftransform) + +Fill an array with the axis combination of a face neighbor transform. + +# Arguments +* `iface`:\\[in\\] The number of the originating face. +* `nface`:\\[in\\] Encoded as nface = r * 4 + nf, where nf = 0..3 is the neigbbor's connecting face number and r = 0..1 is the relative orientation to the neighbor's face. This encoding matches [`p4est_connectivity_t`](@ref). +* `ftransform`:\\[out\\] This array holds 9 integers. [0,2] The coordinate axis sequence of the origin face, the first referring to the tangential and the second to the normal. A permutation of (0, 1). [3,5] The coordinate axis sequence of the target face. [6,8] Face reversal flag for tangential axis (boolean); face code in [0, 3] for the normal coordinate q: 0: q' = -q 1: q' = q + 1 2: q' = q - 1 3: q' = 2 - q [1,4,7] 0 (unused for compatibility with 3D). +### Prototype +```c +void p4est_expand_face_transform (int iface, int nface, int ftransform[]); +``` +""" +function p4est_expand_face_transform(iface, nface, ftransform) + @ccall libp4est.p4est_expand_face_transform(iface::Cint, nface::Cint, ftransform::Ptr{Cint})::Cvoid +end + +""" + p4est_find_face_transform(connectivity, itree, iface, ftransform) + +Fill an array with the axis combinations of a tree neighbor transform. + +# Arguments +* `connectivity`:\\[in\\] Connectivity structure. +* `itree`:\\[in\\] The number of the originating tree. +* `iface`:\\[in\\] The number of the originating tree's face. +* `ftransform`:\\[out\\] This array holds 9 integers. [0,2] The coordinate axis sequence of the origin face. [3,5] The coordinate axis sequence of the target face. [6,8] Face reversal flag for axis t; face code for axis n. +# Returns +The face neighbor tree if it exists, -1 otherwise. +# See also +[`p4est_expand_face_transform`](@ref). [1,4,7] 0 (unused for compatibility with 3D). + +### Prototype +```c +p4est_topidx_t p4est_find_face_transform (p4est_connectivity_t * connectivity, p4est_topidx_t itree, int iface, int ftransform[]); +``` +""" +function p4est_find_face_transform(connectivity, itree, iface, ftransform) + @ccall libp4est.p4est_find_face_transform(connectivity::Ptr{p4est_connectivity_t}, itree::p4est_topidx_t, iface::Cint, ftransform::Ptr{Cint})::p4est_topidx_t +end + +""" + p4est_find_corner_transform(connectivity, itree, icorner, ci) + +Fills an array with information about corner neighbors. + +# Arguments +* `connectivity`:\\[in\\] Connectivity structure. +* `itree`:\\[in\\] The number of the originating tree. +* `icorner`:\\[in\\] The number of the originating corner. +* `ci`:\\[in,out\\] A [`p4est_corner_info_t`](@ref) structure with initialized array. +### Prototype +```c +void p4est_find_corner_transform (p4est_connectivity_t * connectivity, p4est_topidx_t itree, int icorner, p4est_corner_info_t * ci); +``` +""" +function p4est_find_corner_transform(connectivity, itree, icorner, ci) + @ccall libp4est.p4est_find_corner_transform(connectivity::Ptr{p4est_connectivity_t}, itree::p4est_topidx_t, icorner::Cint, ci::Ptr{p4est_corner_info_t})::Cvoid +end + +""" + p4est_connectivity_complete(conn) + +Internally connect a connectivity based on tree\\_to\\_vertex information. Periodicity that is not inherent in the list of vertices will be lost. + +# Arguments +* `conn`:\\[in,out\\] The connectivity needs to have proper vertices and tree\\_to\\_vertex fields. The tree\\_to\\_tree and tree\\_to\\_face fields must be allocated and satisfy [`p4est_connectivity_is_valid`](@ref) (conn) but will be overwritten. The corner fields will be freed and allocated anew. +### Prototype +```c +void p4est_connectivity_complete (p4est_connectivity_t * conn); +``` +""" +function p4est_connectivity_complete(conn) + @ccall libp4est.p4est_connectivity_complete(conn::Ptr{p4est_connectivity_t})::Cvoid +end + +""" + p4est_connectivity_reduce(conn) + +Removes corner information of a connectivity such that enough information is left to run [`p4est_connectivity_complete`](@ref) successfully. The reduced connectivity still passes [`p4est_connectivity_is_valid`](@ref). + +# Arguments +* `conn`:\\[in,out\\] The connectivity to be reduced. +### Prototype +```c +void p4est_connectivity_reduce (p4est_connectivity_t * conn); +``` +""" +function p4est_connectivity_reduce(conn) + @ccall libp4est.p4est_connectivity_reduce(conn::Ptr{p4est_connectivity_t})::Cvoid +end + +""" + p4est_connectivity_permute(conn, perm, is_current_to_new) + +[`p4est_connectivity_permute`](@ref) Given a permutation *perm* of the trees in a connectivity *conn*, permute the trees of *conn* in place and update *conn* to match. + +# Arguments +* `conn`:\\[in,out\\] The connectivity whose trees are permuted. +* `perm`:\\[in\\] A permutation array, whose elements are size\\_t's. +* `is_current_to_new`:\\[in\\] if true, the jth entry of perm is the new index for the entry whose current index is j, otherwise the jth entry of perm is the current index of the tree whose index will be j after the permutation. +### Prototype +```c +void p4est_connectivity_permute (p4est_connectivity_t * conn, sc_array_t * perm, int is_current_to_new); +``` +""" +function p4est_connectivity_permute(conn, perm, is_current_to_new) + @ccall libp4est.p4est_connectivity_permute(conn::Ptr{p4est_connectivity_t}, perm::Ptr{sc_array_t}, is_current_to_new::Cint)::Cvoid +end + +""" + p4est_connectivity_join_faces(conn, tree_left, tree_right, face_left, face_right, orientation) + +[`p4est_connectivity_join_faces`](@ref) This function takes an existing valid connectivity *conn* and modifies it by joining two tree faces that are currently boundary faces. + +# Arguments +* `conn`:\\[in,out\\] connectivity that will be altered. +* `tree_left`:\\[in\\] tree that will be on the left side of the joined faces. +* `tree_right`:\\[in\\] tree that will be on the right side of the joined faces. +* `face_left`:\\[in\\] face of *tree_left* that will be joined. +* `face_right`:\\[in\\] face of *tree_right* that will be joined. +* `orientation`:\\[in\\] the orientation of *face_left* and *face_right* once joined (see the description of [`p4est_connectivity_t`](@ref) to understand orientation). +### Prototype +```c +void p4est_connectivity_join_faces (p4est_connectivity_t * conn, p4est_topidx_t tree_left, p4est_topidx_t tree_right, int face_left, int face_right, int orientation); +``` +""" +function p4est_connectivity_join_faces(conn, tree_left, tree_right, face_left, face_right, orientation) + @ccall libp4est.p4est_connectivity_join_faces(conn::Ptr{p4est_connectivity_t}, tree_left::p4est_topidx_t, tree_right::p4est_topidx_t, face_left::Cint, face_right::Cint, orientation::Cint)::Cvoid +end + +""" + p4est_connectivity_is_equivalent(conn1, conn2) + +[`p4est_connectivity_is_equivalent`](@ref) This function compares two connectivities for equivalence: it returns *true* if they are the same connectivity, or if they have the same topology. The definition of topological sameness is strict: there is no attempt made to determine whether permutation and/or rotation of the trees makes the connectivities equivalent. + +# Arguments +* `conn1`:\\[in\\] a valid connectivity +* `conn2`:\\[out\\] a valid connectivity +### Prototype +```c +int p4est_connectivity_is_equivalent (p4est_connectivity_t * conn1, p4est_connectivity_t * conn2); +``` +""" +function p4est_connectivity_is_equivalent(conn1, conn2) + @ccall libp4est.p4est_connectivity_is_equivalent(conn1::Ptr{p4est_connectivity_t}, conn2::Ptr{p4est_connectivity_t})::Cint +end + +""" + p4est_corner_array_index(array, it) + +### Prototype +```c +static inline p4est_corner_transform_t * p4est_corner_array_index (sc_array_t * array, size_t it); +``` +""" +function p4est_corner_array_index(array, it) + @ccall libp4est.p4est_corner_array_index(array::Ptr{sc_array_t}, it::Csize_t)::Ptr{p4est_corner_transform_t} +end + +""" + p4est_connectivity_read_inp_stream(stream, num_vertices, num_trees, vertices, tree_to_vertex) + +Read an ABAQUS input file from a file stream. + +This utility function reads a basic ABAQUS file supporting element type with the prefix C2D4, CPS4, and S4 in 2D and of type C3D8 reading them as bilinear quadrilateral and trilinear hexahedral trees respectively. + +A basic 2D mesh is given below. The `*Node` section gives the vertex number and x, y, and z components for each vertex. The `*Element` section gives the 4 vertices in 2D (8 vertices in 3D) of each element in counter clockwise order. So in 2D the nodes are given as: + +4 3 +-------------------+ | | | | | | | | | | | | +-------------------+ 1 2 + +and in 3D they are given as: + +8 7 +---------------------+ |\\ |\\ | \\ | \\ | \\ | \\ | \\ | \\ | 5+---------------------+6 | | | | +----|----------------+ | 4\\ | 3 \\ | \\ | \\ | \\ | \\ | \\| \\| +---------------------+ 1 2 + +```c++ + *Heading + box.inp + *Node + 1, -5, -5, 0 + 2, 5, -5, 0 + 3, 5, 5, 0 + 4, -5, 5, 0 + 5, 0, -5, 0 + 6, 5, 0, 0 + 7, 0, 5, 0 + 8, -5, 0, 0 + 9, 1, -1, 0 + 10, 0, 0, 0 + 11, -2, 1, 0 + *Element, type=CPS4, ELSET=Surface1 + 1, 1, 10, 11, 8 + 2, 3, 10, 9, 6 + 3, 9, 10, 1, 5 + 4, 7, 4, 8, 11 + 5, 11, 10, 3, 7 + 6, 2, 6, 9, 5 +``` + +This code can be called two ways. The first, when `vertex`==NULL and `tree_to_vertex`==NULL, is used to count the number of trees and vertices in the connectivity to be generated by the `.inp` mesh in the *stream*. The second, when `vertices`!=NULL and `tree_to_vertex`!=NULL, fill `vertices` and `tree_to_vertex`. In this case `num_vertices` and `num_trees` need to be set to the maximum number of entries allocated in `vertices` and `tree_to_vertex`. + +# Arguments +* `stream`:\\[in,out\\] file stream to read the connectivity from +* `num_vertices`:\\[in,out\\] the number of vertices in the connectivity +* `num_trees`:\\[in,out\\] the number of trees in the connectivity +* `vertices`:\\[out\\] the list of `vertices` of the connectivity +* `tree_to_vertex`:\\[out\\] the `tree_to_vertex` map of the connectivity +# Returns +0 if successful and nonzero if not +### Prototype +```c +int p4est_connectivity_read_inp_stream (FILE * stream, p4est_topidx_t * num_vertices, p4est_topidx_t * num_trees, double *vertices, p4est_topidx_t * tree_to_vertex); +``` +""" +function p4est_connectivity_read_inp_stream(stream, num_vertices, num_trees, vertices, tree_to_vertex) + @ccall libp4est.p4est_connectivity_read_inp_stream(stream::Ptr{Libc.FILE}, num_vertices::Ptr{p4est_topidx_t}, num_trees::Ptr{p4est_topidx_t}, vertices::Ptr{Cdouble}, tree_to_vertex::Ptr{p4est_topidx_t})::Cint +end + +""" + p4est_connectivity_read_inp(filename) + +Create a p4est connectivity from an ABAQUS input file. + +This utility function reads a basic ABAQUS file supporting element type with the prefix C2D4, CPS4, and S4 in 2D and of type C3D8 reading them as bilinear quadrilateral and trilinear hexahedral trees respectively. + +A basic 2D mesh is given below. The `*Node` section gives the vertex number and x, y, and z components for each vertex. The `*Element` section gives the 4 vertices in 2D (8 vertices in 3D) of each element in counter clockwise order. So in 2D the nodes are given as: + +4 3 +-------------------+ | | | | | | | | | | | | +-------------------+ 1 2 + +and in 3D they are given as: + +8 7 +---------------------+ |\\ |\\ | \\ | \\ | \\ | \\ | \\ | \\ | 5+---------------------+6 | | | | +----|----------------+ | 4\\ | 3 \\ | \\ | \\ | \\ | \\ | \\| \\| +---------------------+ 1 2 + +```c++ + *Heading + box.inp + *Node + 1, -5, -5, 0 + 2, 5, -5, 0 + 3, 5, 5, 0 + 4, -5, 5, 0 + 5, 0, -5, 0 + 6, 5, 0, 0 + 7, 0, 5, 0 + 8, -5, 0, 0 + 9, 1, -1, 0 + 10, 0, 0, 0 + 11, -2, 1, 0 + *Element, type=CPS4, ELSET=Surface1 + 1, 1, 10, 11, 8 + 2, 3, 10, 9, 6 + 3, 9, 10, 1, 5 + 4, 7, 4, 8, 11 + 5, 11, 10, 3, 7 + 6, 2, 6, 9, 5 +``` + +This function reads a mesh from *filename* and returns an associated p4est connectivity. + +# Arguments +* `filename`:\\[in\\] file to read the connectivity from +# Returns +an allocated connectivity associated with the mesh in *filename* or NULL if an error occurred. +### Prototype +```c +p4est_connectivity_t *p4est_connectivity_read_inp (const char *filename); +``` +""" +function p4est_connectivity_read_inp(filename) + @ccall libp4est.p4est_connectivity_read_inp(filename::Cstring)::Ptr{p4est_connectivity_t} +end + +""" + p8est_connect_type_t + +Characterize a type of adjacency. + +Several functions involve relationships between neighboring trees and/or quadrants, and their behavior depends on how one defines adjacency: 1) entities are adjacent if they share a face, or 2) entities are adjacent if they share a face or corner, or 3) entities are adjacent if they share a face, corner or edge. [`p8est_connect_type_t`](@ref) is used to choose the desired behavior. This enum must fit into an int8\\_t. + +| Enumerator | Note | +| :----------------------- | :------------------------------- | +| P8EST\\_CONNECT\\_SELF | No balance whatsoever. | +| P8EST\\_CONNECT\\_FACE | Balance across faces only. | +| P8EST\\_CONNECT\\_EDGE | Balance across faces and edges. | +| P8EST\\_CONNECT\\_ALMOST | = CORNER - 1. | +| P8EST\\_CONNECT\\_CORNER | Balance faces, edges, corners. | +| P8EST\\_CONNECT\\_FULL | = CORNER. | +""" +@cenum p8est_connect_type_t::UInt32 begin + P8EST_CONNECT_SELF = 30 + P8EST_CONNECT_FACE = 31 + P8EST_CONNECT_EDGE = 32 + P8EST_CONNECT_ALMOST = 32 + P8EST_CONNECT_CORNER = 33 + P8EST_CONNECT_FULL = 33 +end + +""" + p8est_connectivity_encode_t + +Typedef for serialization method. + +| Enumerator | Note | +| :--------------------------- | :-------------------------------- | +| P8EST\\_CONN\\_ENCODE\\_LAST | Invalid entry to close the list. | +""" +@cenum p8est_connectivity_encode_t::UInt32 begin + P8EST_CONN_ENCODE_NONE = 0 + P8EST_CONN_ENCODE_LAST = 1 +end + +""" + p8est_connect_type_int(btype) + +Convert the [`p8est_connect_type_t`](@ref) into a number. + +# Arguments +* `btype`:\\[in\\] The balance type to convert. +# Returns +Returns 1, 2 or 3. +### Prototype +```c +int p8est_connect_type_int (p8est_connect_type_t btype); +``` +""" +function p8est_connect_type_int(btype) + @ccall libp4est.p8est_connect_type_int(btype::p8est_connect_type_t)::Cint +end + +""" + p8est_connect_type_string(btype) + +Convert the [`p8est_connect_type_t`](@ref) into a const string. + +# Arguments +* `btype`:\\[in\\] The balance type to convert. +# Returns +Returns a pointer to a constant string. +### Prototype +```c +const char *p8est_connect_type_string (p8est_connect_type_t btype); +``` +""" +function p8est_connect_type_string(btype) + @ccall libp4est.p8est_connect_type_string(btype::p8est_connect_type_t)::Cstring +end + +""" + p8est_connectivity + +This structure holds the 3D inter-tree connectivity information. Identification of arbitrary faces, edges and corners is possible. + +The arrays tree\\_to\\_* are stored in z ordering. For corners the order wrt. zyx is 000 001 010 011 100 101 110 111. For faces the order is -x +x -y +y -z +z. They are allocated [0][0]..[0][N-1]..[num\\_trees-1][0]..[num\\_trees-1][N-1]. where N is 6 for tree and face, 8 for corner, 12 for edge. If a face is on the physical boundary it must connect to itself. + +The values for tree\\_to\\_face are in 0..23 where ttf % 6 gives the face number and ttf / 6 the face orientation code. The orientation is determined as follows. Let my\\_face and other\\_face be the two face numbers of the connecting trees in 0..5. Then the first face corner of the lower of my\\_face and other\\_face connects to a face corner numbered 0..3 in the higher of my\\_face and other\\_face. The face orientation is defined as this number. If my\\_face == other\\_face, treating either of both faces as the lower one leads to the same result. + +It is valid to specify num\\_vertices as 0. In this case vertices and tree\\_to\\_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num\\_vertices-1][0]..[num\\_vertices-1][2]. Vertex coordinates are optional and not used for inferring topology. + +The edges are stored when they connect trees that are not already face neighbors at that specific edge. In this case tree\\_to\\_edge indexes into *ett_offset*. Otherwise the tree\\_to\\_edge entry must be -1 and this edge is ignored. If num\\_edges == 0, tree\\_to\\_edge and edge\\_to\\_* arrays are set to NULL. + +The arrays edge\\_to\\_* store a variable number of entries per edge. For edge e these are at position [ett\\_offset[e]]..[ett\\_offset[e+1]-1]. Their number for edge e is ett\\_offset[e+1] - ett\\_offset[e]. The entries encode all trees adjacent to edge e. The size of the edge\\_to\\_* arrays is num\\_ett = ett\\_offset[num\\_edges]. The edge\\_to\\_edge array holds values in 0..23, where the lower 12 indicate one edge orientation and the higher 12 the opposite edge orientation. + +The corners are stored when they connect trees that are not already edge or face neighbors at that specific corner. In this case tree\\_to\\_corner indexes into *ctt_offset*. Otherwise the tree\\_to\\_corner entry must be -1 and this corner is ignored. If num\\_corners == 0, tree\\_to\\_corner and corner\\_to\\_* arrays are set to NULL. + +The arrays corner\\_to\\_* store a variable number of entries per corner. For corner c these are at position [ctt\\_offset[c]]..[ctt\\_offset[c+1]-1]. Their number for corner c is ctt\\_offset[c+1] - ctt\\_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner\\_to\\_* arrays is num\\_ctt = ctt\\_offset[num\\_corners]. + +The *\\_to\\_attr arrays may have arbitrary contents defined by the user. + +!!! note + + If a connectivity implies natural connections between trees that are edge neighbors without being face neighbors, these edges shall be encoded explicitly in the connectivity. If a connectivity implies natural connections between trees that are corner neighbors without being edge or face neighbors, these corners shall be encoded explicitly in the connectivity. + +| Field | Note | +| :------------------- | :----------------------------------------------------------------------------------- | +| num\\_vertices | the number of vertices that define the *embedding* of the forest (not the topology) | +| num\\_trees | the number of trees | +| num\\_edges | the number of edges that help define the topology | +| num\\_corners | the number of corners that help define the topology | +| vertices | an array of size (3 * *num_vertices*) | +| tree\\_to\\_vertex | embed each tree into ```c++ R^3 ``` for e.g. visualization (see p8est\\_vtk.h) | +| tree\\_attr\\_bytes | bytes per tree in tree\\_to\\_attr | +| tree\\_to\\_attr | not touched by p4est | +| tree\\_to\\_tree | (6 * *num_trees*) neighbors across faces | +| tree\\_to\\_face | (6 * *num_trees*) face to face+orientation (see description) | +| tree\\_to\\_edge | (12 * *num_trees*) or NULL (see description) | +| ett\\_offset | edge to offset in *edge_to_tree* and *edge_to_edge* | +| edge\\_to\\_tree | list of trees that meet at an edge | +| edge\\_to\\_edge | list of tree-edges+orientations that meet at an edge (see description) | +| tree\\_to\\_corner | (8 * *num_trees*) or NULL (see description) | +| ctt\\_offset | corner to offset in *corner_to_tree* and *corner_to_corner* | +| corner\\_to\\_tree | list of trees that meet at a corner | +| corner\\_to\\_corner | list of tree-corners that meet at a corner | +""" +struct p8est_connectivity + num_vertices::p4est_topidx_t + num_trees::p4est_topidx_t + num_edges::p4est_topidx_t + num_corners::p4est_topidx_t + vertices::Ptr{Cdouble} + tree_to_vertex::Ptr{p4est_topidx_t} + tree_attr_bytes::Csize_t + tree_to_attr::Cstring + tree_to_tree::Ptr{p4est_topidx_t} + tree_to_face::Ptr{Int8} + tree_to_edge::Ptr{p4est_topidx_t} + ett_offset::Ptr{p4est_topidx_t} + edge_to_tree::Ptr{p4est_topidx_t} + edge_to_edge::Ptr{Int8} + tree_to_corner::Ptr{p4est_topidx_t} + ctt_offset::Ptr{p4est_topidx_t} + corner_to_tree::Ptr{p4est_topidx_t} + corner_to_corner::Ptr{Int8} +end + +""" +This structure holds the 3D inter-tree connectivity information. Identification of arbitrary faces, edges and corners is possible. + +The arrays tree\\_to\\_* are stored in z ordering. For corners the order wrt. zyx is 000 001 010 011 100 101 110 111. For faces the order is -x +x -y +y -z +z. They are allocated [0][0]..[0][N-1]..[num\\_trees-1][0]..[num\\_trees-1][N-1]. where N is 6 for tree and face, 8 for corner, 12 for edge. If a face is on the physical boundary it must connect to itself. + +The values for tree\\_to\\_face are in 0..23 where ttf % 6 gives the face number and ttf / 6 the face orientation code. The orientation is determined as follows. Let my\\_face and other\\_face be the two face numbers of the connecting trees in 0..5. Then the first face corner of the lower of my\\_face and other\\_face connects to a face corner numbered 0..3 in the higher of my\\_face and other\\_face. The face orientation is defined as this number. If my\\_face == other\\_face, treating either of both faces as the lower one leads to the same result. + +It is valid to specify num\\_vertices as 0. In this case vertices and tree\\_to\\_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num\\_vertices-1][0]..[num\\_vertices-1][2]. Vertex coordinates are optional and not used for inferring topology. + +The edges are stored when they connect trees that are not already face neighbors at that specific edge. In this case tree\\_to\\_edge indexes into *ett_offset*. Otherwise the tree\\_to\\_edge entry must be -1 and this edge is ignored. If num\\_edges == 0, tree\\_to\\_edge and edge\\_to\\_* arrays are set to NULL. + +The arrays edge\\_to\\_* store a variable number of entries per edge. For edge e these are at position [ett\\_offset[e]]..[ett\\_offset[e+1]-1]. Their number for edge e is ett\\_offset[e+1] - ett\\_offset[e]. The entries encode all trees adjacent to edge e. The size of the edge\\_to\\_* arrays is num\\_ett = ett\\_offset[num\\_edges]. The edge\\_to\\_edge array holds values in 0..23, where the lower 12 indicate one edge orientation and the higher 12 the opposite edge orientation. + +The corners are stored when they connect trees that are not already edge or face neighbors at that specific corner. In this case tree\\_to\\_corner indexes into *ctt_offset*. Otherwise the tree\\_to\\_corner entry must be -1 and this corner is ignored. If num\\_corners == 0, tree\\_to\\_corner and corner\\_to\\_* arrays are set to NULL. + +The arrays corner\\_to\\_* store a variable number of entries per corner. For corner c these are at position [ctt\\_offset[c]]..[ctt\\_offset[c+1]-1]. Their number for corner c is ctt\\_offset[c+1] - ctt\\_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner\\_to\\_* arrays is num\\_ctt = ctt\\_offset[num\\_corners]. + +The *\\_to\\_attr arrays may have arbitrary contents defined by the user. + +!!! note + + If a connectivity implies natural connections between trees that are edge neighbors without being face neighbors, these edges shall be encoded explicitly in the connectivity. If a connectivity implies natural connections between trees that are corner neighbors without being edge or face neighbors, these corners shall be encoded explicitly in the connectivity. +""" +const p8est_connectivity_t = p8est_connectivity + +""" + p8est_connectivity_shared + +| Field | Note | +| :---- | :--------------------------------------------------------- | +| conn | The members of this connectivity are MPI3 shared windows. | +""" +struct p8est_connectivity_shared + conn::Ptr{p8est_connectivity_t} + win_vertices::Cint + win_tree_to_vertex::Cint + win_tree_to_attr::Cint + win_tree_to_tree::Cint + win_tree_to_face::Cint + win_tree_to_edge::Cint + win_ett_offset::Cint + win_edge_to_tree::Cint + win_edge_to_edge::Cint + win_tree_to_corner::Cint + win_ctt_offset::Cint + win_corner_to_tree::Cint + win_corner_to_corner::Cint +end + +"""Management information for a connectivity shared by MPI3.""" +const p8est_connectivity_shared_t = p8est_connectivity_shared + +""" + p8est_connectivity_memory_used(conn) + +Calculate memory usage of a connectivity structure. + +# Arguments +* `conn`:\\[in\\] Connectivity structure. +# Returns +Memory used in bytes. +### Prototype +```c +size_t p8est_connectivity_memory_used (p8est_connectivity_t * conn); +``` +""" +function p8est_connectivity_memory_used(conn) + @ccall libp4est.p8est_connectivity_memory_used(conn::Ptr{p8est_connectivity_t})::Csize_t +end + +""" + p8est_edge_transform_t + +Generic interface for transformations between a tree and any of its edge + +| Field | Note | +| :------ | :--------------------------------- | +| ntree | The number of the tree | +| nedge | The number of the edge | +| naxis | The 3 edge coordinate axes | +| nflip | The orientation of the edge | +| corners | The corners connected to the edge | +""" +struct p8est_edge_transform_t + ntree::p4est_topidx_t + nedge::Int8 + naxis::NTuple{3, Int8} + nflip::Int8 + corners::Int8 +end + +""" + p8est_edge_info_t + +Information about the neighbors of an edge + +| Field | Note | +| :---------------- | :---------------------------------------------- | +| iedge | The information of the edge | +| edge\\_transforms | The array of neighbors of the originating edge | +""" +struct p8est_edge_info_t + iedge::Int8 + edge_transforms::sc_array_t +end + +""" + p8est_corner_transform_t + +Generic interface for transformations between a tree and any of its corner + +| Field | Note | +| :------ | :------------------------ | +| ntree | The number of the tree | +| ncorner | The number of the corner | +""" +struct p8est_corner_transform_t + ntree::p4est_topidx_t + ncorner::Int8 +end + +""" + p8est_corner_info_t + +Information about the neighbors of a corner + +| Field | Note | +| :------------------ | :------------------------------------------------ | +| icorner | The number of the originating corner | +| corner\\_transforms | The array of neighbors of the originating corner | +""" +struct p8est_corner_info_t + icorner::p4est_topidx_t + corner_transforms::sc_array_t +end + +""" + p8est_neighbor_transform_t + +Generic interface for transformations between a tree and any of its neighbors + +| Field | Note | +| :---------------- | :-------------------------------------------------------------------------- | +| neighbor\\_type | type of connection to neighbor | +| neighbor | neighbor tree index | +| index\\_self | index of interface from self's perspective | +| index\\_neighbor | index of interface from neighbor's perspective | +| perm | permutation of dimensions when transforming self coords to neighbor coords | +| sign | sign changes when transforming self coords to neighbor coords | +| origin\\_self | point on the interface from self's perspective | +| origin\\_neighbor | point on the interface from neighbor's perspective | +""" +struct p8est_neighbor_transform_t + neighbor_type::p8est_connect_type_t + neighbor::p4est_topidx_t + index_self::Int8 + index_neighbor::Int8 + perm::NTuple{3, Int8} + sign::NTuple{3, Int8} + origin_self::NTuple{3, p4est_qcoord_t} + origin_neighbor::NTuple{3, p4est_qcoord_t} +end + +""" + p8est_neighbor_transform_coordinates(nt, self_coords, neigh_coords) + +Transform from self's coordinate system to neighbor's coordinate system. + +# Arguments +* `nt`:\\[in\\] A neighbor transform. +* `self_coords`:\\[in\\] Input quadrant coordinates in self coordinates. +* `neigh_coords`:\\[out\\] Coordinates transformed into neighbor coordinates. +### Prototype +```c +void p8est_neighbor_transform_coordinates (const p8est_neighbor_transform_t * nt, const p4est_qcoord_t self_coords[P8EST_DIM], p4est_qcoord_t neigh_coords[P8EST_DIM]); +``` +""" +function p8est_neighbor_transform_coordinates(nt, self_coords, neigh_coords) + @ccall libp4est.p8est_neighbor_transform_coordinates(nt::Ptr{p8est_neighbor_transform_t}, self_coords::Ptr{p4est_qcoord_t}, neigh_coords::Ptr{p4est_qcoord_t})::Cvoid +end + +""" + p8est_neighbor_transform_coordinates_reverse(nt, neigh_coords, self_coords) + +Transform from neighbor's coordinate system to self's coordinate system. + +# Arguments +* `nt`:\\[in\\] A neighbor transform. +* `neigh_coords`:\\[in\\] Input quadrant coordinates in self coordinates. +* `self_coords`:\\[out\\] Coordinates transformed into neighbor coordinates. +### Prototype +```c +void p8est_neighbor_transform_coordinates_reverse (const p8est_neighbor_transform_t * nt, const p4est_qcoord_t neigh_coords[P8EST_DIM], p4est_qcoord_t self_coords[P8EST_DIM]); +``` +""" +function p8est_neighbor_transform_coordinates_reverse(nt, neigh_coords, self_coords) + @ccall libp4est.p8est_neighbor_transform_coordinates_reverse(nt::Ptr{p8est_neighbor_transform_t}, neigh_coords::Ptr{p4est_qcoord_t}, self_coords::Ptr{p4est_qcoord_t})::Cvoid +end + +""" + p8est_connectivity_get_neighbor_transforms(conn, tree_id, boundary_type, boundary_index, neighbor_transform_array) + +Fill an array with the neighbor transforms based on a specific boundary type. This function generalizes all other inter-tree transformation objects + +# Arguments +* `conn`:\\[in\\] Connectivity structure. +* `tree_id`:\\[in\\] The number of the tree. +* `boundary_type`:\\[in\\] Type of boundary connection (self, face, edge, corner). +* `boundary_index`:\\[in\\] The index of the boundary. +* `neighbor_transform_array`:\\[in,out\\] Array of the neighbor transforms. +### Prototype +```c +void p8est_connectivity_get_neighbor_transforms (p8est_connectivity_t *conn, p4est_topidx_t tree_id, p8est_connect_type_t boundary_type, int boundary_index, sc_array_t *neighbor_transform_array); +``` +""" +function p8est_connectivity_get_neighbor_transforms(conn, tree_id, boundary_type, boundary_index, neighbor_transform_array) + @ccall libp4est.p8est_connectivity_get_neighbor_transforms(conn::Ptr{p8est_connectivity_t}, tree_id::p4est_topidx_t, boundary_type::p8est_connect_type_t, boundary_index::Cint, neighbor_transform_array::Ptr{sc_array_t})::Cvoid +end + +""" + p8est_connectivity_coordinates_canonicalize(conn, treeid, coords, treeid_out, coords_out) + +Determine the owning tree for a coordinate and transform it there. + +On a boundary between trees, different coordinate systems meet. A coordinate on a tree boundary face, edge, or corner generated from the perspective of a specific tree may be transformed into any other touching tree's coordinate system and still refer to the same point in the mesh. + +To uniquely identify a coordinate, this function identifies the lowest numbered tree touching this coordinate and transforms the coordinate into that system. The result can be used e. g. in topology hash tables. + +# Arguments +* `conn`:\\[in\\] A valid connectivity. +* `treeid`:\\[in\\] The original tree index for this coordinate tuple. +* `coords`:\\[in\\] A valid coordinate 2-tuple relative to *treeid*. +* `treeid_out`:\\[out\\] The lowest tree index touching the coordinate. +* `coords_out`:\\[out\\] The input coordinates, if necessary after transformation into the system of the lowest numbered tree, returned in *treeid_out*. +### Prototype +```c +void p8est_connectivity_coordinates_canonicalize (p8est_connectivity_t *conn, p4est_topidx_t treeid, const p4est_qcoord_t coords[], p4est_topidx_t *treeid_out, p4est_qcoord_t coords_out[]); +``` +""" +function p8est_connectivity_coordinates_canonicalize(conn, treeid, coords, treeid_out, coords_out) + @ccall libp4est.p8est_connectivity_coordinates_canonicalize(conn::Ptr{p8est_connectivity_t}, treeid::p4est_topidx_t, coords::Ptr{p4est_qcoord_t}, treeid_out::Ptr{p4est_topidx_t}, coords_out::Ptr{p4est_qcoord_t})::Cvoid +end + +""" + p8est_connectivity_face_neighbor_corner_set(c, f, nf, set) + +Transform a corner across one of the adjacent faces into a neighbor tree. It expects a face permutation index that has been precomputed. + +# Arguments +* `c`:\\[in\\] A corner number in 0..7. +* `f`:\\[in\\] A face number that touches the corner *c*. +* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. +* `set`:\\[in\\] A value from *p8est_face_permutation_sets* that is obtained using *f*, *nf*, and a valid orientation: ref = p8est\\_face\\_permutation\\_refs[f][nf]; set = p8est\\_face\\_permutation\\_sets[ref][orientation]; +# Returns +The corner number in 0..7 seen from the other face. +### Prototype +```c +int p8est_connectivity_face_neighbor_corner_set (int c, int f, int nf, int set); +``` +""" +function p8est_connectivity_face_neighbor_corner_set(c, f, nf, set) + @ccall libp4est.p8est_connectivity_face_neighbor_corner_set(c::Cint, f::Cint, nf::Cint, set::Cint)::Cint +end + +""" + p8est_connectivity_face_neighbor_face_corner(fc, f, nf, o) + +Transform a face corner across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. + +# Arguments +* `fc`:\\[in\\] A face corner number in 0..3. +* `f`:\\[in\\] A face that the face corner *fc* is relative to. +* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. +* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. +# Returns +The face corner number relative to the neighbor's face. +### Prototype +```c +int p8est_connectivity_face_neighbor_face_corner (int fc, int f, int nf, int o); +``` +""" +function p8est_connectivity_face_neighbor_face_corner(fc, f, nf, o) + @ccall libp4est.p8est_connectivity_face_neighbor_face_corner(fc::Cint, f::Cint, nf::Cint, o::Cint)::Cint +end + +""" + p8est_connectivity_face_neighbor_corner(c, f, nf, o) + +Transform a corner across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. + +# Arguments +* `c`:\\[in\\] A corner number in 0..7. +* `f`:\\[in\\] A face number that touches the corner *c*. +* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. +* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. +# Returns +The number of the corner seen from the neighbor tree. +### Prototype +```c +int p8est_connectivity_face_neighbor_corner (int c, int f, int nf, int o); +``` +""" +function p8est_connectivity_face_neighbor_corner(c, f, nf, o) + @ccall libp4est.p8est_connectivity_face_neighbor_corner(c::Cint, f::Cint, nf::Cint, o::Cint)::Cint +end + +""" + p8est_connectivity_face_neighbor_face_edge(fe, f, nf, o) + +Transform a face-edge across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. + +# Arguments +* `fe`:\\[in\\] A face edge number in 0..3. +* `f`:\\[in\\] A face number that touches the edge *e*. +* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. +* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. +# Returns +The face edge number seen from the neighbor tree. +### Prototype +```c +int p8est_connectivity_face_neighbor_face_edge (int fe, int f, int nf, int o); +``` +""" +function p8est_connectivity_face_neighbor_face_edge(fe, f, nf, o) + @ccall libp4est.p8est_connectivity_face_neighbor_face_edge(fe::Cint, f::Cint, nf::Cint, o::Cint)::Cint +end + +""" + p8est_connectivity_face_neighbor_edge(e, f, nf, o) + +Transform an edge across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately. + +# Arguments +* `e`:\\[in\\] A edge number in 0..11. +* `f`:\\[in\\] A face 0..5 that touches the edge *e*. +* `nf`:\\[in\\] A neighbor face that is on the other side of *f*. +* `o`:\\[in\\] The orientation between tree boundary faces *f* and *nf*. +# Returns +The edge's number seen from the neighbor. +### Prototype +```c +int p8est_connectivity_face_neighbor_edge (int e, int f, int nf, int o); +``` +""" +function p8est_connectivity_face_neighbor_edge(e, f, nf, o) + @ccall libp4est.p8est_connectivity_face_neighbor_edge(e::Cint, f::Cint, nf::Cint, o::Cint)::Cint +end + +""" + p8est_connectivity_edge_neighbor_edge_corner(ec, o) + +Transform an edge corner across one of the adjacent edges into a neighbor tree. + +# Arguments +* `ec`:\\[in\\] An edge corner number in 0..1. +* `o`:\\[in\\] The orientation of a tree boundary edge connection. +# Returns +The edge corner number seen from the other tree. +### Prototype +```c +int p8est_connectivity_edge_neighbor_edge_corner (int ec, int o); +``` +""" +function p8est_connectivity_edge_neighbor_edge_corner(ec, o) + @ccall libp4est.p8est_connectivity_edge_neighbor_edge_corner(ec::Cint, o::Cint)::Cint +end + +""" + p8est_connectivity_edge_neighbor_corner(c, e, ne, o) + +Transform a corner across one of the adjacent edges into a neighbor tree. This version expects the neighbor edge and orientation separately. + +# Arguments +* `c`:\\[in\\] A corner number in 0..7. +* `e`:\\[in\\] An edge 0..11 that touches the corner *c*. +* `ne`:\\[in\\] A neighbor edge that is on the other side of *e*. +* `o`:\\[in\\] The orientation between tree boundary edges *e* and *ne*. +# Returns +Corner number seen from the neighbor. +### Prototype +```c +int p8est_connectivity_edge_neighbor_corner (int c, int e, int ne, int o); +``` +""" +function p8est_connectivity_edge_neighbor_corner(c, e, ne, o) + @ccall libp4est.p8est_connectivity_edge_neighbor_corner(c::Cint, e::Cint, ne::Cint, o::Cint)::Cint +end + +""" + p8est_connectivity_new(num_vertices, num_trees, num_edges, num_ett, num_corners, num_ctt) + +Allocate a connectivity structure. The attribute fields are initialized to NULL. + +# Arguments +* `num_vertices`:\\[in\\] Number of total vertices (i.e. geometric points). +* `num_trees`:\\[in\\] Number of trees in the forest. +* `num_edges`:\\[in\\] Number of tree-connecting edges. +* `num_ett`:\\[in\\] Number of total trees in edge\\_to\\_tree array. +* `num_corners`:\\[in\\] Number of tree-connecting corners. +* `num_ctt`:\\[in\\] Number of total trees in corner\\_to\\_tree array. +# Returns +A connectivity structure with allocated arrays. +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new (p4est_topidx_t num_vertices, p4est_topidx_t num_trees, p4est_topidx_t num_edges, p4est_topidx_t num_ett, p4est_topidx_t num_corners, p4est_topidx_t num_ctt); +``` +""" +function p8est_connectivity_new(num_vertices, num_trees, num_edges, num_ett, num_corners, num_ctt) + @ccall libp4est.p8est_connectivity_new(num_vertices::p4est_topidx_t, num_trees::p4est_topidx_t, num_edges::p4est_topidx_t, num_ett::p4est_topidx_t, num_corners::p4est_topidx_t, num_ctt::p4est_topidx_t)::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_copy(num_vertices, num_trees, num_edges, num_corners, vertices, ttv, ttt, ttf, tte, eoff, ett, ete, ttc, coff, ctt, ctc) + +Allocate a connectivity structure and populate from constants. The attribute fields are initialized to NULL. + +# Arguments +* `num_vertices`:\\[in\\] Number of total vertices (i.e. geometric points). +* `num_trees`:\\[in\\] Number of trees in the forest. +* `num_edges`:\\[in\\] Number of tree-connecting edges. +* `num_corners`:\\[in\\] Number of tree-connecting corners. +* `vertices`:\\[in\\] Coordinates of the vertices of the trees. +* `ttv`:\\[in\\] The tree-to-vertex array. +* `ttt`:\\[in\\] The tree-to-tree array. +* `ttf`:\\[in\\] The tree-to-face array (int8\\_t). +* `tte`:\\[in\\] The tree-to-edge array. +* `eoff`:\\[in\\] Edge-to-tree offsets (num\\_edges + 1 values). This must always be non-NULL; in trivial cases it is just a pointer to a p4est\\_topix value of 0. +* `ett`:\\[in\\] The edge-to-tree array. +* `ete`:\\[in\\] The edge-to-edge array. +* `ttc`:\\[in\\] The tree-to-corner array. +* `coff`:\\[in\\] Corner-to-tree offsets (num\\_corners + 1 values). This must always be non-NULL; in trivial cases it is just a pointer to a p4est\\_topix value of 0. +* `ctt`:\\[in\\] The corner-to-tree array. +* `ctc`:\\[in\\] The corner-to-corner array. +# Returns +The connectivity is checked for validity. +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_copy (p4est_topidx_t num_vertices, p4est_topidx_t num_trees, p4est_topidx_t num_edges, p4est_topidx_t num_corners, const double *vertices, const p4est_topidx_t * ttv, const p4est_topidx_t * ttt, const int8_t * ttf, const p4est_topidx_t * tte, const p4est_topidx_t * eoff, const p4est_topidx_t * ett, const int8_t * ete, const p4est_topidx_t * ttc, const p4est_topidx_t * coff, const p4est_topidx_t * ctt, const int8_t * ctc); +``` +""" +function p8est_connectivity_new_copy(num_vertices, num_trees, num_edges, num_corners, vertices, ttv, ttt, ttf, tte, eoff, ett, ete, ttc, coff, ctt, ctc) + @ccall libp4est.p8est_connectivity_new_copy(num_vertices::p4est_topidx_t, num_trees::p4est_topidx_t, num_edges::p4est_topidx_t, num_corners::p4est_topidx_t, vertices::Ptr{Cdouble}, ttv::Ptr{p4est_topidx_t}, ttt::Ptr{p4est_topidx_t}, ttf::Ptr{Int8}, tte::Ptr{p4est_topidx_t}, eoff::Ptr{p4est_topidx_t}, ett::Ptr{p4est_topidx_t}, ete::Ptr{Int8}, ttc::Ptr{p4est_topidx_t}, coff::Ptr{p4est_topidx_t}, ctt::Ptr{p4est_topidx_t}, ctc::Ptr{Int8})::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_copy(input, copy_attr) + +Deep copy a connectivity structure. + +# Arguments +* `input`:\\[in\\] Valid connectivity. +* `copy_attr`:\\[in\\] If true, we copy the tree attribute data. Otherwise, the result has empty attributes. +# Returns +A connectivity equal to the first one except, depending on *copy_attry*, for its attributes. +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_copy (p8est_connectivity_t *input, int copy_attr); +``` +""" +function p8est_connectivity_copy(input, copy_attr) + @ccall libp4est.p8est_connectivity_copy(input::Ptr{p8est_connectivity_t}, copy_attr::Cint)::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_bcast(conn_in, root, comm) + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_bcast (p8est_connectivity_t * conn_in, int root, sc_MPI_Comm comm); +``` +""" +function p8est_connectivity_bcast(conn_in, root, comm) + @ccall libp4est.p8est_connectivity_bcast(conn_in::Ptr{p8est_connectivity_t}, root::Cint, comm::MPI_Comm)::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_destroy(connectivity) + +Destroy a connectivity structure. Also destroy all attributes. + +### Prototype +```c +void p8est_connectivity_destroy (p8est_connectivity_t * connectivity); +``` +""" +function p8est_connectivity_destroy(connectivity) + @ccall libp4est.p8est_connectivity_destroy(connectivity::Ptr{p8est_connectivity_t})::Cvoid +end + +""" + p8est_connectivity_share(conn_in, root, comm) + +### Prototype +```c +p8est_connectivity_shared_t *p8est_connectivity_share (p8est_connectivity_t * conn_in, int root, sc_MPI_Comm comm); +``` +""" +function p8est_connectivity_share(conn_in, root, comm) + @ccall libp4est.p8est_connectivity_share(conn_in::Ptr{p8est_connectivity_t}, root::Cint, comm::MPI_Comm)::Ptr{p8est_connectivity_shared_t} +end + +""" + p8est_connectivity_mission(conn_in, split_type, world_comm) + +### Prototype +```c +p8est_connectivity_shared_t * p8est_connectivity_mission (p8est_connectivity_t *conn_in, int split_type, sc_MPI_Comm world_comm); +``` +""" +function p8est_connectivity_mission(conn_in, split_type, world_comm) + @ccall libp4est.p8est_connectivity_mission(conn_in::Ptr{p8est_connectivity_t}, split_type::Cint, world_comm::Cint)::Ptr{p8est_connectivity_shared_t} +end + +""" + p8est_connectivity_shared_destroy(cshare) + +Destroy a shared connectivity structure. Call this eventually on the result of p8est_connectivity_share or p8est_connectivity_mission (which calls the former internally). + +# Arguments +* `cshare`:\\[in\\] Valid shared connectivity structure; cf. p8est_connectivity_share. +### Prototype +```c +void p8est_connectivity_shared_destroy (p8est_connectivity_shared_t *cshare); +``` +""" +function p8est_connectivity_shared_destroy(cshare) + @ccall libp4est.p8est_connectivity_shared_destroy(cshare::Ptr{p8est_connectivity_shared_t})::Cvoid +end + +""" + p8est_connectivity_set_attr(conn, bytes_per_tree) + +Allocate or free the attribute fields in a connectivity. + +# Arguments +* `conn`:\\[in,out\\] The conn->*\\_to\\_attr fields must either be NULL or previously be allocated by this function. +* `bytes_per_tree`:\\[in\\] If 0, tree\\_to\\_attr is freed (being NULL is ok). If positive, requested space is allocated. +### Prototype +```c +void p8est_connectivity_set_attr (p8est_connectivity_t * conn, size_t bytes_per_tree); +``` +""" +function p8est_connectivity_set_attr(conn, bytes_per_tree) + @ccall libp4est.p8est_connectivity_set_attr(conn::Ptr{p8est_connectivity_t}, bytes_per_tree::Csize_t)::Cvoid +end + +""" + p8est_connectivity_is_valid(connectivity) + +Examine a connectivity structure. + +# Returns +Returns true if structure is valid, false otherwise. +### Prototype +```c +int p8est_connectivity_is_valid (p8est_connectivity_t * connectivity); +``` +""" +function p8est_connectivity_is_valid(connectivity) + @ccall libp4est.p8est_connectivity_is_valid(connectivity::Ptr{p8est_connectivity_t})::Cint +end + +""" + p8est_connectivity_is_equal(conn1, conn2) + +Check two connectivity structures for equality. + +# Returns +Returns true if structures are equal, false otherwise. +### Prototype +```c +int p8est_connectivity_is_equal (p8est_connectivity_t * conn1, p8est_connectivity_t * conn2); +``` +""" +function p8est_connectivity_is_equal(conn1, conn2) + @ccall libp4est.p8est_connectivity_is_equal(conn1::Ptr{p8est_connectivity_t}, conn2::Ptr{p8est_connectivity_t})::Cint +end + +""" + p8est_connectivity_sink(conn, sink) + +Write connectivity to a sink object. + +# Arguments +* `conn`:\\[in\\] The connectivity to be written. +* `sink`:\\[in,out\\] The connectivity is written into this sink. +# Returns +0 on success, nonzero on error. +### Prototype +```c +int p8est_connectivity_sink (p8est_connectivity_t * conn, sc_io_sink_t * sink); +``` +""" +function p8est_connectivity_sink(conn, sink) + @ccall libp4est.p8est_connectivity_sink(conn::Ptr{p8est_connectivity_t}, sink::Ptr{sc_io_sink_t})::Cint +end + +""" + p8est_connectivity_deflate(conn, code) + +Allocate memory and store the connectivity information there. + +# Arguments +* `conn`:\\[in\\] The connectivity structure to be exported to memory. +* `code`:\\[in\\] Encoding and compression method for serialization. +# Returns +Newly created array that contains the information. +### Prototype +```c +sc_array_t *p8est_connectivity_deflate (p8est_connectivity_t * conn, p8est_connectivity_encode_t code); +``` +""" +function p8est_connectivity_deflate(conn, code) + @ccall libp4est.p8est_connectivity_deflate(conn::Ptr{p8est_connectivity_t}, code::p8est_connectivity_encode_t)::Ptr{sc_array_t} +end + +""" + p8est_connectivity_save(filename, connectivity) + +Save a connectivity structure to disk. + +# Arguments +* `filename`:\\[in\\] Name of the file to write. +* `connectivity`:\\[in\\] Valid connectivity structure. +# Returns +Returns 0 on success, nonzero on file error. +### Prototype +```c +int p8est_connectivity_save (const char *filename, p8est_connectivity_t * connectivity); +``` +""" +function p8est_connectivity_save(filename, connectivity) + @ccall libp4est.p8est_connectivity_save(filename::Cstring, connectivity::Ptr{p8est_connectivity_t})::Cint +end + +""" + p8est_connectivity_source(source) + +Read connectivity from a source object. + +# Arguments +* `source`:\\[in,out\\] The connectivity is read from this source. +# Returns +The newly created connectivity, or NULL on error. +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_source (sc_io_source_t * source); +``` +""" +function p8est_connectivity_source(source) + @ccall libp4est.p8est_connectivity_source(source::Ptr{sc_io_source_t})::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_inflate(buffer) + +Create new connectivity from a memory buffer. This function aborts on malloc errors. + +# Arguments +* `buffer`:\\[in\\] The connectivity is created from this memory buffer. +# Returns +The newly created connectivity, or NULL on format error of the buffered connectivity data. +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_inflate (sc_array_t * buffer); +``` +""" +function p8est_connectivity_inflate(buffer) + @ccall libp4est.p8est_connectivity_inflate(buffer::Ptr{sc_array_t})::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_load(filename, bytes) + +Load a connectivity structure from disk. + +# Arguments +* `filename`:\\[in\\] Name of the file to read. +* `bytes`:\\[out\\] Size in bytes of connectivity on disk or NULL. +# Returns +Returns valid connectivity, or NULL on file error. +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_load (const char *filename, size_t *bytes); +``` +""" +function p8est_connectivity_load(filename, bytes) + @ccall libp4est.p8est_connectivity_load(filename::Cstring, bytes::Ptr{Csize_t})::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_unitcube() + +Create a connectivity structure for the unit cube. + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_unitcube (void); +``` +""" +function p8est_connectivity_new_unitcube() + @ccall libp4est.p8est_connectivity_new_unitcube()::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_periodic() + +Create a connectivity structure for an all-periodic unit cube. + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_periodic (void); +``` +""" +function p8est_connectivity_new_periodic() + @ccall libp4est.p8est_connectivity_new_periodic()::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_rotwrap() + +Create a connectivity structure for a mostly periodic unit cube. The left and right faces are identified, and bottom and top rotated. Front and back are not identified. + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_rotwrap (void); +``` +""" +function p8est_connectivity_new_rotwrap() + @ccall libp4est.p8est_connectivity_new_rotwrap()::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_drop() + +Create a connectivity structure for a five-trees geometry with a hole. The geometry is a 3D extrusion of the two drop example, and covers [0, 3]*[0, 2]*[0, 3]. The additional dimension is Y. + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_drop (void); +``` +""" +function p8est_connectivity_new_drop() + @ccall libp4est.p8est_connectivity_new_drop()::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_twocubes() + +Create a connectivity structure that contains two cubes. + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_twocubes (void); +``` +""" +function p8est_connectivity_new_twocubes() + @ccall libp4est.p8est_connectivity_new_twocubes()::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_twotrees(l_face, r_face, orientation) + +Create a connectivity structure for two trees being rotated w.r.t. each other in a user-defined way. + +# Arguments +* `l_face`:\\[in\\] index of left face +* `r_face`:\\[in\\] index of right face +* `orientation`:\\[in\\] orientation of trees w.r.t. each other +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_twotrees (int l_face, int r_face, int orientation); +``` +""" +function p8est_connectivity_new_twotrees(l_face, r_face, orientation) + @ccall libp4est.p8est_connectivity_new_twotrees(l_face::Cint, r_face::Cint, orientation::Cint)::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_twowrap() + +Create a connectivity structure that contains two cubes where the two far ends are identified periodically. + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_twowrap (void); +``` +""" +function p8est_connectivity_new_twowrap() + @ccall libp4est.p8est_connectivity_new_twowrap()::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_rotcubes() + +Create a connectivity structure that contains a few cubes. These are rotated against each other to stress the topology routines. + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_rotcubes (void); +``` +""" +function p8est_connectivity_new_rotcubes() + @ccall libp4est.p8est_connectivity_new_rotcubes()::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_pillow() + +Create a connectivity structure for two trees on top of each other. This connectivity is meant to be used with p8est_geometry_new_pillow to map a spherical shell. + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_pillow (void); +``` +""" +function p8est_connectivity_new_pillow() + @ccall libp4est.p8est_connectivity_new_pillow()::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_brick(m, n, p, periodic_a, periodic_b, periodic_c) + +An m by n by p array with periodicity in x, y, and z if periodic\\_a, periodic\\_b, and periodic\\_c are true, respectively. + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_brick (int m, int n, int p, int periodic_a, int periodic_b, int periodic_c); +``` +""" +function p8est_connectivity_new_brick(m, n, p, periodic_a, periodic_b, periodic_c) + @ccall libp4est.p8est_connectivity_new_brick(m::Cint, n::Cint, p::Cint, periodic_a::Cint, periodic_b::Cint, periodic_c::Cint)::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_shell() + +Create a connectivity structure that builds a spherical shell. It is made up of six connected parts [-1,1]x[-1,1]x[1,2]. This connectivity reuses vertices and relies on a geometry transformation. It is thus not suitable for [`p8est_connectivity_complete`](@ref). + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_shell (void); +``` +""" +function p8est_connectivity_new_shell() + @ccall libp4est.p8est_connectivity_new_shell()::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_sphere() + +Create a connectivity structure that builds a solid sphere. It is made up of two layers and a cube in the center. This connectivity reuses vertices and relies on a geometry transformation. It is thus not suitable for [`p8est_connectivity_complete`](@ref). + +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_sphere (void); +``` +""" +function p8est_connectivity_new_sphere() + @ccall libp4est.p8est_connectivity_new_sphere()::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_torus(nSegments) + +Create a connectivity structure that builds a revolution torus. + +This connectivity reuses vertices and relies on a geometry transformation. It is thus not suitable for [`p8est_connectivity_complete`](@ref). + +This connectivity reuses ideas from disk2d connectivity. More precisely the torus is divided into segments around the revolution axis, each segments is made of 5 trees (à la disk2d). The total number of trees if 5 times the number of segments. + +This connectivity is meant to be used with p8est_geometry_new_torus + +# Arguments +* `nSegments`:\\[in\\] number of trees along the great circle +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_torus (int nSegments); +``` +""" +function p8est_connectivity_new_torus(nSegments) + @ccall libp4est.p8est_connectivity_new_torus(nSegments::Cint)::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_new_byname(name) + +Create connectivity structure from predefined catalogue. + +# Arguments +* `name`:\\[in\\] Invokes connectivity\\_new\\_* function. brick235 brick (2, 3, 5, 0, 0, 0) periodic periodic rotcubes rotcubes rotwrap rotwrap shell shell sphere sphere twocubes twocubes twowrap twowrap unit unitcube +# Returns +An initialized connectivity if name is defined, NULL else. +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_new_byname (const char *name); +``` +""" +function p8est_connectivity_new_byname(name) + @ccall libp4est.p8est_connectivity_new_byname(name::Cstring)::Ptr{p8est_connectivity_t} +end + +""" + p8est_connectivity_refine(conn, num_per_dim) + +Uniformly refine a connectivity. This is useful if you would like to uniformly refine by something other than a power of 2. + +# Arguments +* `conn`:\\[in\\] A valid connectivity +* `num_per_dim`:\\[in\\] The number of new trees in each direction. Must use no more than P8EST_OLD_QMAXLEVEL bits. +# Returns +a refined connectivity. +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_refine (p8est_connectivity_t * conn, int num_per_dim); +``` +""" +function p8est_connectivity_refine(conn, num_per_dim) + @ccall libp4est.p8est_connectivity_refine(conn::Ptr{p8est_connectivity_t}, num_per_dim::Cint)::Ptr{p8est_connectivity_t} +end + +""" + p8est_expand_face_transform(iface, nface, ftransform) + +Fill an array with the axis combination of a face neighbor transform. + +# Arguments +* `iface`:\\[in\\] The number of the originating face. +* `nface`:\\[in\\] Encoded as nface = r * 6 + nf, where nf = 0..5 is the neigbbor's connecting face number and r = 0..3 is the relative orientation to the neighbor's face. This encoding matches [`p8est_connectivity_t`](@ref). +* `ftransform`:\\[out\\] This array holds 9 integers. [0]..[2] The coordinate axis sequence of the origin face, the first two referring to the tangentials and the third to the normal. A permutation of (0, 1, 2). [3]..[5] The coordinate axis sequence of the target face. [6]..[8] Edge reversal flags for tangential axes (boolean); face code in [0, 3] for the normal coordinate q: 0: q' = -q 1: q' = q + 1 2: q' = q - 1 3: q' = 2 - q +### Prototype +```c +void p8est_expand_face_transform (int iface, int nface, int ftransform[]); +``` +""" +function p8est_expand_face_transform(iface, nface, ftransform) + @ccall libp4est.p8est_expand_face_transform(iface::Cint, nface::Cint, ftransform::Ptr{Cint})::Cvoid +end + +""" + p8est_find_face_transform(connectivity, itree, iface, ftransform) + +Fill an array with the axis combination of a face neighbor transform. + +# Arguments +* `connectivity`:\\[in\\] Connectivity structure. +* `itree`:\\[in\\] The number of the originating tree. +* `iface`:\\[in\\] The number of the originating tree's face. +* `ftransform`:\\[out\\] This array holds 9 integers. [0]..[2] The coordinate axis sequence of the origin face. [3]..[5] The coordinate axis sequence of the target face. [6]..[8] Edge reversal flag for axes t1, t2; face code for n; +# Returns +The face neighbor tree if it exists, -1 otherwise. +# See also +[`p8est_expand_face_transform`](@ref). + +### Prototype +```c +p4est_topidx_t p8est_find_face_transform (p8est_connectivity_t * connectivity, p4est_topidx_t itree, int iface, int ftransform[]); +``` +""" +function p8est_find_face_transform(connectivity, itree, iface, ftransform) + @ccall libp4est.p8est_find_face_transform(connectivity::Ptr{p8est_connectivity_t}, itree::p4est_topidx_t, iface::Cint, ftransform::Ptr{Cint})::p4est_topidx_t +end + +""" + p8est_find_edge_transform(connectivity, itree, iedge, ei) + +Fills an array with information about edge neighbors. + +# Arguments +* `connectivity`:\\[in\\] Connectivity structure. +* `itree`:\\[in\\] The number of the originating tree. +* `iedge`:\\[in\\] The number of the originating edge. +* `ei`:\\[in,out\\] A [`p8est_edge_info_t`](@ref) structure with initialized array. +### Prototype +```c +void p8est_find_edge_transform (p8est_connectivity_t * connectivity, p4est_topidx_t itree, int iedge, p8est_edge_info_t * ei); +``` +""" +function p8est_find_edge_transform(connectivity, itree, iedge, ei) + @ccall libp4est.p8est_find_edge_transform(connectivity::Ptr{p8est_connectivity_t}, itree::p4est_topidx_t, iedge::Cint, ei::Ptr{p8est_edge_info_t})::Cvoid +end + +""" + p8est_find_corner_transform(connectivity, itree, icorner, ci) + +Fills an array with information about corner neighbors. + +# Arguments +* `connectivity`:\\[in\\] Connectivity structure. +* `itree`:\\[in\\] The number of the originating tree. +* `icorner`:\\[in\\] The number of the originating corner. +* `ci`:\\[in,out\\] A [`p8est_corner_info_t`](@ref) structure with initialized array. +### Prototype +```c +void p8est_find_corner_transform (p8est_connectivity_t * connectivity, p4est_topidx_t itree, int icorner, p8est_corner_info_t * ci); +``` +""" +function p8est_find_corner_transform(connectivity, itree, icorner, ci) + @ccall libp4est.p8est_find_corner_transform(connectivity::Ptr{p8est_connectivity_t}, itree::p4est_topidx_t, icorner::Cint, ci::Ptr{p8est_corner_info_t})::Cvoid +end + +""" + p8est_connectivity_complete(conn) + +Internally connect a connectivity based on tree\\_to\\_vertex information. Periodicity that is not inherent in the list of vertices will be lost. + +# Arguments +* `conn`:\\[in,out\\] The connectivity needs to have proper vertices and tree\\_to\\_vertex fields. The tree\\_to\\_tree and tree\\_to\\_face fields must be allocated and satisfy [`p8est_connectivity_is_valid`](@ref) (conn) but will be overwritten. The edge and corner fields will be freed and allocated anew. +### Prototype +```c +void p8est_connectivity_complete (p8est_connectivity_t * conn); +``` +""" +function p8est_connectivity_complete(conn) + @ccall libp4est.p8est_connectivity_complete(conn::Ptr{p8est_connectivity_t})::Cvoid +end + +""" + p8est_connectivity_reduce(conn) + +Removes corner and edge information of a connectivity such that enough information is left to run [`p8est_connectivity_complete`](@ref) successfully. The reduced connectivity still passes [`p8est_connectivity_is_valid`](@ref). + +# Arguments +* `conn`:\\[in,out\\] The connectivity to be reduced. +### Prototype +```c +void p8est_connectivity_reduce (p8est_connectivity_t * conn); +``` +""" +function p8est_connectivity_reduce(conn) + @ccall libp4est.p8est_connectivity_reduce(conn::Ptr{p8est_connectivity_t})::Cvoid +end + +""" + p8est_connectivity_permute(conn, perm, is_current_to_new) + +[`p8est_connectivity_permute`](@ref) Given a permutation *perm* of the trees in a connectivity *conn*, permute the trees of *conn* in place and update *conn* to match. + +# Arguments +* `conn`:\\[in,out\\] The connectivity whose trees are permuted. +* `perm`:\\[in\\] A permutation array, whose elements are size\\_t's. +* `is_current_to_new`:\\[in\\] if true, the jth entry of perm is the new index for the entry whose current index is j, otherwise the jth entry of perm is the current index of the tree whose index will be j after the permutation. +### Prototype +```c +void p8est_connectivity_permute (p8est_connectivity_t * conn, sc_array_t * perm, int is_current_to_new); +``` +""" +function p8est_connectivity_permute(conn, perm, is_current_to_new) + @ccall libp4est.p8est_connectivity_permute(conn::Ptr{p8est_connectivity_t}, perm::Ptr{sc_array_t}, is_current_to_new::Cint)::Cvoid +end + +""" + p8est_connectivity_join_faces(conn, tree_left, tree_right, face_left, face_right, orientation) + +[`p8est_connectivity_join_faces`](@ref) This function takes an existing valid connectivity *conn* and modifies it by joining two tree faces that are currently boundary faces. + +# Arguments +* `conn`:\\[in,out\\] connectivity that will be altered. +* `tree_left`:\\[in\\] tree that will be on the left side of the joined faces. +* `tree_right`:\\[in\\] tree that will be on the right side of the joined faces. +* `face_left`:\\[in\\] face of *tree_left* that will be joined. +* `face_right`:\\[in\\] face of *tree_right* that will be joined. +* `orientation`:\\[in\\] the orientation of *face_left* and *face_right* once joined (see the description of [`p8est_connectivity_t`](@ref) to understand orientation). +### Prototype +```c +void p8est_connectivity_join_faces (p8est_connectivity_t * conn, p4est_topidx_t tree_left, p4est_topidx_t tree_right, int face_left, int face_right, int orientation); +``` +""" +function p8est_connectivity_join_faces(conn, tree_left, tree_right, face_left, face_right, orientation) + @ccall libp4est.p8est_connectivity_join_faces(conn::Ptr{p8est_connectivity_t}, tree_left::p4est_topidx_t, tree_right::p4est_topidx_t, face_left::Cint, face_right::Cint, orientation::Cint)::Cvoid +end + +""" + p8est_connectivity_is_equivalent(conn1, conn2) + +[`p8est_connectivity_is_equivalent`](@ref) This function compares two connectivities for equivalence: it returns *true* if they are the same connectivity, or if they have the same topology. The definition of topological sameness is strict: there is no attempt made to determine whether permutation and/or rotation of the trees makes the connectivities equivalent. + +# Arguments +* `conn1`:\\[in\\] a valid connectivity +* `conn2`:\\[out\\] a valid connectivity +### Prototype +```c +int p8est_connectivity_is_equivalent (p8est_connectivity_t * conn1, p8est_connectivity_t * conn2); +``` +""" +function p8est_connectivity_is_equivalent(conn1, conn2) + @ccall libp4est.p8est_connectivity_is_equivalent(conn1::Ptr{p8est_connectivity_t}, conn2::Ptr{p8est_connectivity_t})::Cint +end + +""" + p8est_edge_array_index(array, it) + +### Prototype +```c +static inline p8est_edge_transform_t * p8est_edge_array_index (sc_array_t *array, size_t it); +``` +""" +function p8est_edge_array_index(array, it) + @ccall libp4est.p8est_edge_array_index(array::Ptr{sc_array_t}, it::Csize_t)::Ptr{p8est_edge_transform_t} +end + +""" + p8est_corner_array_index(array, it) + +### Prototype +```c +static inline p8est_corner_transform_t * p8est_corner_array_index (sc_array_t *array, size_t it); +``` +""" +function p8est_corner_array_index(array, it) + @ccall libp4est.p8est_corner_array_index(array::Ptr{sc_array_t}, it::Csize_t)::Ptr{p8est_corner_transform_t} +end + +""" + p8est_connectivity_read_inp_stream(stream, num_vertices, num_trees, vertices, tree_to_vertex) + +Read an ABAQUS input file from a file stream. + +This utility function reads a basic ABAQUS file supporting element type with the prefix C2D4, CPS4, and S4 in 2D and of type C3D8 reading them as bilinear quadrilateral and trilinear hexahedral trees respectively. + +A basic 2D mesh is given below. The `*Node` section gives the vertex number and x, y, and z components for each vertex. The `*Element` section gives the 4 vertices in 2D (8 vertices in 3D) of each element in counter clockwise order. So in 2D the nodes are given as: + +4 3 +-------------------+ | | | | | | | | | | | | +-------------------+ 1 2 + +and in 3D they are given as: + +8 7 +---------------------+ |\\ |\\ | \\ | \\ | \\ | \\ | \\ | \\ | 5+---------------------+6 | | | | +----|----------------+ | 4\\ | 3 \\ | \\ | \\ | \\ | \\ | \\| \\| +---------------------+ 1 2 + +```c++ + *Heading + box.inp + *Node + 1, 5, -5, 5 + 2, 5, 5, 5 + 3, 5, 0, 5 + 4, -5, 5, 5 + 5, 0, 5, 5 + 6, -5, -5, 5 + 7, -5, 0, 5 + 8, 0, -5, 5 + 9, 0, 0, 5 + 10, 5, 5, -5 + 11, 5, -5, -5 + 12, 5, 0, -5 + 13, -5, -5, -5 + 14, 0, -5, -5 + 15, -5, 5, -5 + 16, -5, 0, -5 + 17, 0, 5, -5 + 18, 0, 0, -5 + 19, -5, -5, 0 + 20, 5, -5, 0 + 21, 0, -5, 0 + 22, -5, 5, 0 + 23, -5, 0, 0 + 24, 5, 5, 0 + 25, 0, 5, 0 + 26, 5, 0, 0 + 27, 0, 0, 0 + *Element, type=C3D8, ELSET=EB1 + 1, 6, 19, 23, 7, 8, 21, 27, 9 + 2, 19, 13, 16, 23, 21, 14, 18, 27 + 3, 7, 23, 22, 4, 9, 27, 25, 5 + 4, 23, 16, 15, 22, 27, 18, 17, 25 + 5, 8, 21, 27, 9, 1, 20, 26, 3 + 6, 21, 14, 18, 27, 20, 11, 12, 26 + 7, 9, 27, 25, 5, 3, 26, 24, 2 + 8, 27, 18, 17, 25, 26, 12, 10, 24 +``` + +This code can be called two ways. The first, when `vertex`==NULL and `tree_to_vertex`==NULL, is used to count the number of trees and vertices in the connectivity to be generated by the `.inp` mesh in the *stream*. The second, when `vertices`!=NULL and `tree_to_vertex`!=NULL, fill `vertices` and `tree_to_vertex`. In this case `num_vertices` and `num_trees` need to be set to the maximum number of entries allocated in `vertices` and `tree_to_vertex`. + +# Arguments +* `stream`:\\[in,out\\] file stream to read the connectivity from +* `num_vertices`:\\[in,out\\] the number of vertices in the connectivity +* `num_trees`:\\[in,out\\] the number of trees in the connectivity +* `vertices`:\\[out\\] the list of `vertices` of the connectivity +* `tree_to_vertex`:\\[out\\] the `tree_to_vertex` map of the connectivity +# Returns +0 if successful and nonzero if not +### Prototype +```c +int p8est_connectivity_read_inp_stream (FILE * stream, p4est_topidx_t * num_vertices, p4est_topidx_t * num_trees, double *vertices, p4est_topidx_t * tree_to_vertex); +``` +""" +function p8est_connectivity_read_inp_stream(stream, num_vertices, num_trees, vertices, tree_to_vertex) + @ccall libp4est.p8est_connectivity_read_inp_stream(stream::Ptr{Libc.FILE}, num_vertices::Ptr{p4est_topidx_t}, num_trees::Ptr{p4est_topidx_t}, vertices::Ptr{Cdouble}, tree_to_vertex::Ptr{p4est_topidx_t})::Cint +end + +""" + p8est_connectivity_read_inp(filename) + +Create a p4est connectivity from an ABAQUS input file. + +This utility function reads a basic ABAQUS file supporting element type with the prefix C2D4, CPS4, and S4 in 2D and of type C3D8 reading them as bilinear quadrilateral and trilinear hexahedral trees respectively. + +A basic 2D mesh is given below. The `*Node` section gives the vertex number and x, y, and z components for each vertex. The `*Element` section gives the 4 vertices in 2D (8 vertices in 3D) of each element in counter clockwise order. So in 2D the nodes are given as: + +4 3 +-------------------+ | | | | | | | | | | | | +-------------------+ 1 2 + +and in 3D they are given as: + +8 7 +---------------------+ |\\ |\\ | \\ | \\ | \\ | \\ | \\ | \\ | 5+---------------------+6 | | | | +----|----------------+ | 4\\ | 3 \\ | \\ | \\ | \\ | \\ | \\| \\| +---------------------+ 1 2 + +```c++ + *Heading + box.inp + *Node + 1, 5, -5, 5 + 2, 5, 5, 5 + 3, 5, 0, 5 + 4, -5, 5, 5 + 5, 0, 5, 5 + 6, -5, -5, 5 + 7, -5, 0, 5 + 8, 0, -5, 5 + 9, 0, 0, 5 + 10, 5, 5, -5 + 11, 5, -5, -5 + 12, 5, 0, -5 + 13, -5, -5, -5 + 14, 0, -5, -5 + 15, -5, 5, -5 + 16, -5, 0, -5 + 17, 0, 5, -5 + 18, 0, 0, -5 + 19, -5, -5, 0 + 20, 5, -5, 0 + 21, 0, -5, 0 + 22, -5, 5, 0 + 23, -5, 0, 0 + 24, 5, 5, 0 + 25, 0, 5, 0 + 26, 5, 0, 0 + 27, 0, 0, 0 + *Element, type=C3D8, ELSET=EB1 + 1, 6, 19, 23, 7, 8, 21, 27, 9 + 2, 19, 13, 16, 23, 21, 14, 18, 27 + 3, 7, 23, 22, 4, 9, 27, 25, 5 + 4, 23, 16, 15, 22, 27, 18, 17, 25 + 5, 8, 21, 27, 9, 1, 20, 26, 3 + 6, 21, 14, 18, 27, 20, 11, 12, 26 + 7, 9, 27, 25, 5, 3, 26, 24, 2 + 8, 27, 18, 17, 25, 26, 12, 10, 24 +``` + +This function reads a mesh from *filename* and returns an associated p4est connectivity. + +# Arguments +* `filename`:\\[in\\] file to read the connectivity from +# Returns +an allocated connectivity associated with the mesh in *filename* +### Prototype +```c +p8est_connectivity_t *p8est_connectivity_read_inp (const char *filename); +``` +""" +function p8est_connectivity_read_inp(filename) + @ccall libp4est.p8est_connectivity_read_inp(filename::Cstring)::Ptr{p8est_connectivity_t} +end + +""" + t8_cmesh_new_from_p4est(conn, comm, do_partition) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_from_p4est (p4est_connectivity_t *conn, sc_MPI_Comm comm, int do_partition); +``` +""" +function t8_cmesh_new_from_p4est(conn, comm, do_partition) + @ccall libt8.t8_cmesh_new_from_p4est(conn::Ptr{p4est_connectivity_t}, comm::MPI_Comm, do_partition::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_from_p8est(conn, comm, do_partition) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_from_p8est (p8est_connectivity_t *conn, sc_MPI_Comm comm, int do_partition); +``` +""" +function t8_cmesh_new_from_p8est(conn, comm, do_partition) + @ccall libt8.t8_cmesh_new_from_p8est(conn::Ptr{p8est_connectivity_t}, comm::MPI_Comm, do_partition::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_empty(comm, do_partition, dimension) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_empty (sc_MPI_Comm comm, const int do_partition, const int dimension); +``` +""" +function t8_cmesh_new_empty(comm, do_partition, dimension) + @ccall libt8.t8_cmesh_new_empty(comm::MPI_Comm, do_partition::Cint, dimension::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_from_class(eclass, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_from_class (t8_eclass_t eclass, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_from_class(eclass, comm) + @ccall libt8.t8_cmesh_new_from_class(eclass::t8_eclass_t, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_hypercube(eclass, comm, do_bcast, do_partition, periodic) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_hypercube (t8_eclass_t eclass, sc_MPI_Comm comm, int do_bcast, int do_partition, int periodic); +``` +""" +function t8_cmesh_new_hypercube(eclass, comm, do_bcast, do_partition, periodic) + @ccall libt8.t8_cmesh_new_hypercube(eclass::t8_eclass_t, comm::MPI_Comm, do_bcast::Cint, do_partition::Cint, periodic::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_hypercube_pad(eclass, comm, boundary, polygons_x, polygons_y, polygons_z, use_axis_aligned) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_hypercube_pad (const t8_eclass_t eclass, sc_MPI_Comm comm, const double *boundary, t8_locidx_t polygons_x, t8_locidx_t polygons_y, t8_locidx_t polygons_z, const int use_axis_aligned); +``` +""" +function t8_cmesh_new_hypercube_pad(eclass, comm, boundary, polygons_x, polygons_y, polygons_z, use_axis_aligned) + @ccall libt8.t8_cmesh_new_hypercube_pad(eclass::t8_eclass_t, comm::MPI_Comm, boundary::Ptr{Cdouble}, polygons_x::t8_locidx_t, polygons_y::t8_locidx_t, polygons_z::t8_locidx_t, use_axis_aligned::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_hypercube_pad_ext(eclass, comm, boundary, polygons_x, polygons_y, polygons_z, periodic_x, periodic_y, periodic_z, use_axis_aligned, set_partition, offset) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_hypercube_pad_ext (const t8_eclass_t eclass, sc_MPI_Comm comm, const double *boundary, t8_locidx_t polygons_x, t8_locidx_t polygons_y, t8_locidx_t polygons_z, const int periodic_x, const int periodic_y, const int periodic_z, const int use_axis_aligned, const int set_partition, t8_gloidx_t offset); +``` +""" +function t8_cmesh_new_hypercube_pad_ext(eclass, comm, boundary, polygons_x, polygons_y, polygons_z, periodic_x, periodic_y, periodic_z, use_axis_aligned, set_partition, offset) + @ccall libt8.t8_cmesh_new_hypercube_pad_ext(eclass::t8_eclass_t, comm::MPI_Comm, boundary::Ptr{Cdouble}, polygons_x::t8_locidx_t, polygons_y::t8_locidx_t, polygons_z::t8_locidx_t, periodic_x::Cint, periodic_y::Cint, periodic_z::Cint, use_axis_aligned::Cint, set_partition::Cint, offset::t8_gloidx_t)::t8_cmesh_t +end + +""" + t8_cmesh_new_hypercube_hybrid(comm, do_partition, periodic) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_hypercube_hybrid (sc_MPI_Comm comm, int do_partition, int periodic); +``` +""" +function t8_cmesh_new_hypercube_hybrid(comm, do_partition, periodic) + @ccall libt8.t8_cmesh_new_hypercube_hybrid(comm::MPI_Comm, do_partition::Cint, periodic::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_periodic(comm, dim) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_periodic (sc_MPI_Comm comm, int dim); +``` +""" +function t8_cmesh_new_periodic(comm, dim) + @ccall libt8.t8_cmesh_new_periodic(comm::MPI_Comm, dim::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_periodic_tri(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_periodic_tri (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_periodic_tri(comm) + @ccall libt8.t8_cmesh_new_periodic_tri(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_periodic_hybrid(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_periodic_hybrid (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_periodic_hybrid(comm) + @ccall libt8.t8_cmesh_new_periodic_hybrid(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_periodic_line_more_trees(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_periodic_line_more_trees (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_periodic_line_more_trees(comm) + @ccall libt8.t8_cmesh_new_periodic_line_more_trees(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_bigmesh(eclass, num_trees, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_bigmesh (t8_eclass_t eclass, int num_trees, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_bigmesh(eclass, num_trees, comm) + @ccall libt8.t8_cmesh_new_bigmesh(eclass::t8_eclass_t, num_trees::Cint, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_line_zigzag(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_line_zigzag (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_line_zigzag(comm) + @ccall libt8.t8_cmesh_new_line_zigzag(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_prism_cake(comm, num_of_prisms) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_prism_cake (sc_MPI_Comm comm, int num_of_prisms); +``` +""" +function t8_cmesh_new_prism_cake(comm, num_of_prisms) + @ccall libt8.t8_cmesh_new_prism_cake(comm::MPI_Comm, num_of_prisms::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_prism_deformed(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_prism_deformed (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_prism_deformed(comm) + @ccall libt8.t8_cmesh_new_prism_deformed(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_pyramid_deformed(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_pyramid_deformed (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_pyramid_deformed(comm) + @ccall libt8.t8_cmesh_new_pyramid_deformed(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_prism_cake_funny_oriented(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_prism_cake_funny_oriented (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_prism_cake_funny_oriented(comm) + @ccall libt8.t8_cmesh_new_prism_cake_funny_oriented(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_prism_geometry(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_prism_geometry (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_prism_geometry(comm) + @ccall libt8.t8_cmesh_new_prism_geometry(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_brick_2d(num_x, num_y, x_periodic, y_periodic, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_brick_2d (t8_gloidx_t num_x, t8_gloidx_t num_y, int x_periodic, int y_periodic, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_brick_2d(num_x, num_y, x_periodic, y_periodic, comm) + @ccall libt8.t8_cmesh_new_brick_2d(num_x::t8_gloidx_t, num_y::t8_gloidx_t, x_periodic::Cint, y_periodic::Cint, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_brick_3d(num_x, num_y, num_z, x_periodic, y_periodic, z_periodic, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_brick_3d (t8_gloidx_t num_x, t8_gloidx_t num_y, t8_gloidx_t num_z, int x_periodic, int y_periodic, int z_periodic, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_brick_3d(num_x, num_y, num_z, x_periodic, y_periodic, z_periodic, comm) + @ccall libt8.t8_cmesh_new_brick_3d(num_x::t8_gloidx_t, num_y::t8_gloidx_t, num_z::t8_gloidx_t, x_periodic::Cint, y_periodic::Cint, z_periodic::Cint, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_disjoint_bricks(num_x, num_y, num_z, x_periodic, y_periodic, z_periodic, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_disjoint_bricks (t8_gloidx_t num_x, t8_gloidx_t num_y, t8_gloidx_t num_z, int x_periodic, int y_periodic, int z_periodic, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_disjoint_bricks(num_x, num_y, num_z, x_periodic, y_periodic, z_periodic, comm) + @ccall libt8.t8_cmesh_new_disjoint_bricks(num_x::t8_gloidx_t, num_y::t8_gloidx_t, num_z::t8_gloidx_t, x_periodic::Cint, y_periodic::Cint, z_periodic::Cint, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_tet_orientation_test(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_tet_orientation_test (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_tet_orientation_test(comm) + @ccall libt8.t8_cmesh_new_tet_orientation_test(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_hybrid_gate(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_hybrid_gate (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_hybrid_gate(comm) + @ccall libt8.t8_cmesh_new_hybrid_gate(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_hybrid_gate_deformed(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_hybrid_gate_deformed (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_hybrid_gate_deformed(comm) + @ccall libt8.t8_cmesh_new_hybrid_gate_deformed(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_full_hybrid(comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_full_hybrid (sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_full_hybrid(comm) + @ccall libt8.t8_cmesh_new_full_hybrid(comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_pyramid_cake(comm, num_of_pyra) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_pyramid_cake (sc_MPI_Comm comm, int num_of_pyra); +``` +""" +function t8_cmesh_new_pyramid_cake(comm, num_of_pyra) + @ccall libt8.t8_cmesh_new_pyramid_cake(comm::MPI_Comm, num_of_pyra::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_long_brick_pyramid(comm, num_cubes) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_long_brick_pyramid (sc_MPI_Comm comm, int num_cubes); +``` +""" +function t8_cmesh_new_long_brick_pyramid(comm, num_cubes) + @ccall libt8.t8_cmesh_new_long_brick_pyramid(comm::MPI_Comm, num_cubes::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_row_of_cubes(num_trees, set_attributes, do_partition, comm, package_id) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_row_of_cubes (t8_locidx_t num_trees, const int set_attributes, const int do_partition, sc_MPI_Comm comm, const int package_id); +``` +""" +function t8_cmesh_new_row_of_cubes(num_trees, set_attributes, do_partition, comm, package_id) + @ccall libt8.t8_cmesh_new_row_of_cubes(num_trees::t8_locidx_t, set_attributes::Cint, do_partition::Cint, comm::MPI_Comm, package_id::Cint)::t8_cmesh_t +end + +""" + t8_cmesh_new_quadrangulated_disk(radius, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_quadrangulated_disk (const double radius, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_quadrangulated_disk(radius, comm) + @ccall libt8.t8_cmesh_new_quadrangulated_disk(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_triangulated_spherical_surface_octahedron(radius, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_triangulated_spherical_surface_octahedron (const double radius, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_triangulated_spherical_surface_octahedron(radius, comm) + @ccall libt8.t8_cmesh_new_triangulated_spherical_surface_octahedron(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_triangulated_spherical_surface_icosahedron(radius, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_triangulated_spherical_surface_icosahedron (const double radius, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_triangulated_spherical_surface_icosahedron(radius, comm) + @ccall libt8.t8_cmesh_new_triangulated_spherical_surface_icosahedron(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_triangulated_spherical_surface_cube(radius, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_triangulated_spherical_surface_cube (const double radius, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_triangulated_spherical_surface_cube(radius, comm) + @ccall libt8.t8_cmesh_new_triangulated_spherical_surface_cube(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_quadrangulated_spherical_surface(radius, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_quadrangulated_spherical_surface (const double radius, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_quadrangulated_spherical_surface(radius, comm) + @ccall libt8.t8_cmesh_new_quadrangulated_spherical_surface(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_prismed_spherical_shell_octahedron(inner_radius, shell_thickness, num_levels, num_layers, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_prismed_spherical_shell_octahedron (const double inner_radius, const double shell_thickness, const int num_levels, const int num_layers, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_prismed_spherical_shell_octahedron(inner_radius, shell_thickness, num_levels, num_layers, comm) + @ccall libt8.t8_cmesh_new_prismed_spherical_shell_octahedron(inner_radius::Cdouble, shell_thickness::Cdouble, num_levels::Cint, num_layers::Cint, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_prismed_spherical_shell_icosahedron(inner_radius, shell_thickness, num_levels, num_layers, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_prismed_spherical_shell_icosahedron (const double inner_radius, const double shell_thickness, const int num_levels, const int num_layers, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_prismed_spherical_shell_icosahedron(inner_radius, shell_thickness, num_levels, num_layers, comm) + @ccall libt8.t8_cmesh_new_prismed_spherical_shell_icosahedron(inner_radius::Cdouble, shell_thickness::Cdouble, num_levels::Cint, num_layers::Cint, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_cubed_spherical_shell(inner_radius, shell_thickness, num_trees, num_layers, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_cubed_spherical_shell (const double inner_radius, const double shell_thickness, const int num_trees, const int num_layers, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_cubed_spherical_shell(inner_radius, shell_thickness, num_trees, num_layers, comm) + @ccall libt8.t8_cmesh_new_cubed_spherical_shell(inner_radius::Cdouble, shell_thickness::Cdouble, num_trees::Cint, num_layers::Cint, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_new_cubed_sphere(radius, comm) + +### Prototype +```c +t8_cmesh_t t8_cmesh_new_cubed_sphere (const double radius, sc_MPI_Comm comm); +``` +""" +function t8_cmesh_new_cubed_sphere(radius, comm) + @ccall libt8.t8_cmesh_new_cubed_sphere(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +end + +""" + t8_cmesh_set_join_by_vertices(cmesh, ntrees, eclasses, vertices, connectivity, do_both_directions) + +Sets the face connectivity information of an un-committed cmesh based on a list of tree vertices. + +!!! warning + + This routine might be too expensive for very large meshes. In this case, consider to use a fully featured mesh generator. + +!!! note + + This routine does not detect periodic boundaries. + +# Arguments +* `cmesh`:\\[in,out\\] Pointer to a t8code cmesh object. If set to NULL this argument is ignored. +* `ntrees`:\\[in\\] Number of coarse mesh elements resp. trees. +* `vertices`:\\[in\\] List of per element vertices with dimensions [ntrees,[`T8_ECLASS_MAX_CORNERS`](@ref),[`T8_ECLASS_MAX_DIM`](@ref)]. +* `eclasses`:\\[in\\] List of element classes of length [ntrees]. +* `connectivity`:\\[in,out\\] If connectivity is not NULL the variable is filled with a pointer to an allocated face connectivity array. The ownership of this array goes to the caller. This argument is mainly used for debugging and testing purposes. The dimension of *connectivity* are [ntrees,[`T8_ECLASS_MAX_FACES`](@ref),3]. For each element and each face the following is stored: neighbor\\_tree\\_id, neighbor\\_dual\\_face\\_id, orientation +* `do_both_directions`:\\[in\\] Compute the connectivity from both neighboring sides. Takes much longer to compute. +### Prototype +```c +void t8_cmesh_set_join_by_vertices (t8_cmesh_t cmesh, const t8_gloidx_t ntrees, const t8_eclass_t *eclasses, const double *vertices, int **connectivity, const int do_both_directions); +``` +""" +function t8_cmesh_set_join_by_vertices(cmesh, ntrees, eclasses, vertices, connectivity, do_both_directions) + @ccall libt8.t8_cmesh_set_join_by_vertices(cmesh::t8_cmesh_t, ntrees::t8_gloidx_t, eclasses::Ptr{t8_eclass_t}, vertices::Ptr{Cdouble}, connectivity::Ptr{Ptr{Cint}}, do_both_directions::Cint)::Cvoid +end + +""" + t8_cmesh_set_join_by_stash(cmesh, connectivity, do_both_directions) + +Sets the face connectivity information of an un-committed cmesh based on the cmesh stash. + +!!! warning + + This routine might be too expensive for very large meshes. In this case, consider to use a fully featured mesh generator. + +!!! note + + This routine does not detect periodic boundaries. + +# Arguments +* `cmesh`:\\[in,out\\] An uncommitted cmesh. The trees eclasses and vertices do need to be set. +* `connectivity`:\\[in,out\\] If connectivity is not NULL the variable is filled with a pointer to an allocated face connectivity array. The ownership of this array goes to the caller. This argument is mainly used for debugging and testing purposes. The dimension of *connectivity* are [ntrees,[`T8_ECLASS_MAX_FACES`](@ref),3]. For each element and each face the following is stored: neighbor\\_tree\\_id, neighbor\\_dual\\_face\\_id, orientation +* `do_both_directions`:\\[in\\] Compute the connectivity from both neighboring sides. Takes much longer to compute. +### Prototype +```c +void t8_cmesh_set_join_by_stash (t8_cmesh_t cmesh, int **connectivity, const int do_both_directions); +``` +""" +function t8_cmesh_set_join_by_stash(cmesh, connectivity, do_both_directions) + @ccall libt8.t8_cmesh_set_join_by_stash(cmesh::t8_cmesh_t, connectivity::Ptr{Ptr{Cint}}, do_both_directions::Cint)::Cvoid +end + +""" + t8_cmesh_from_msh_file(fileprefix, partition, comm, dim, master, use_cad_geometry) + +### Prototype +```c +t8_cmesh_t t8_cmesh_from_msh_file (const char *fileprefix, int partition, sc_MPI_Comm comm, int dim, int master, int use_cad_geometry); +``` +""" +function t8_cmesh_from_msh_file(fileprefix, partition, comm, dim, master, use_cad_geometry) + @ccall libt8.t8_cmesh_from_msh_file(fileprefix::Cstring, partition::Cint, comm::MPI_Comm, dim::Cint, master::Cint, use_cad_geometry::Cint)::t8_cmesh_t +end + +mutable struct t8_cmesh_vertex_connectivity end + +""" +[`t8_cmesh_vertex_connectivity_c`](@ref) + +Opaque pointer to the cmesh vertex connectivity structure. +""" +const t8_cmesh_vertex_connectivity_c = Ptr{t8_cmesh_vertex_connectivity} + +""" + t8_cmesh_set_global_vertices_of_tree(cmesh, global_tree, global_tree_vertices, num_vertices) + +### Prototype +```c +void t8_cmesh_set_global_vertices_of_tree (const t8_cmesh_t cmesh, const t8_gloidx_t global_tree, const t8_gloidx_t *global_tree_vertices, const int num_vertices); +``` +""" +function t8_cmesh_set_global_vertices_of_tree(cmesh, global_tree, global_tree_vertices, num_vertices) + @ccall libt8.t8_cmesh_set_global_vertices_of_tree(cmesh::Cint, global_tree::Cint, global_tree_vertices::Ptr{Cint}, num_vertices::Cint)::Cvoid +end + +""" + t8_cmesh_get_num_global_vertices(cmesh) + +### Prototype +```c +t8_gloidx_t t8_cmesh_get_num_global_vertices (const t8_cmesh_t cmesh); +``` +""" +function t8_cmesh_get_num_global_vertices(cmesh) + @ccall libt8.t8_cmesh_get_num_global_vertices(cmesh::Cint)::Cint +end + +""" + t8_cmesh_get_num_local_vertices(cmesh) + +### Prototype +```c +t8_locidx_t t8_cmesh_get_num_local_vertices (const t8_cmesh_t cmesh); +``` +""" +function t8_cmesh_get_num_local_vertices(cmesh) + @ccall libt8.t8_cmesh_get_num_local_vertices(cmesh::Cint)::Cint +end + +""" + t8_cmesh_get_global_vertices_of_tree(cmesh, local_tree, num_vertices) + +### Prototype +```c +const t8_gloidx_t * t8_cmesh_get_global_vertices_of_tree (const t8_cmesh_t cmesh, const t8_locidx_t local_tree, int *num_vertices); +``` +""" +function t8_cmesh_get_global_vertices_of_tree(cmesh, local_tree, num_vertices) + @ccall libt8.t8_cmesh_get_global_vertices_of_tree(cmesh::Cint, local_tree::Cint, num_vertices::Ptr{Cint})::Ptr{Cint} +end + +""" + t8_cmesh_get_global_vertex_of_tree(cmesh, local_tree, local_tree_vertex) + +### Prototype +```c +t8_gloidx_t t8_cmesh_get_global_vertex_of_tree (const t8_cmesh_t cmesh, const t8_locidx_t local_tree, const int local_tree_vertex); +``` +""" +function t8_cmesh_get_global_vertex_of_tree(cmesh, local_tree, local_tree_vertex) + @ccall libt8.t8_cmesh_get_global_vertex_of_tree(cmesh::Cint, local_tree::Cint, local_tree_vertex::Cint)::Cint +end + +""" + t8_cmesh_get_num_trees_at_vertex(cmesh, global_vertex) + +### Prototype +```c +int t8_cmesh_get_num_trees_at_vertex (const t8_cmesh_t cmesh, t8_gloidx_t global_vertex); +``` +""" +function t8_cmesh_get_num_trees_at_vertex(cmesh, global_vertex) + @ccall libt8.t8_cmesh_get_num_trees_at_vertex(cmesh::Cint, global_vertex::Cint)::Cint +end + +""" + t8_cmesh_uses_vertex_connectivity(cmesh) + +### Prototype +```c +int t8_cmesh_uses_vertex_connectivity (const t8_cmesh_t cmesh); +``` +""" +function t8_cmesh_uses_vertex_connectivity(cmesh) + @ccall libt8.t8_cmesh_uses_vertex_connectivity(cmesh::Cint)::Cint +end + +""" + t8_element_array_t + +The [`t8_element_array_t`](@ref) is an array to store [`t8_element_t`](@ref) * of a given eclass\\_scheme implementation. It is a wrapper around [`sc_array_t`](@ref). Each time, a new element is created by the functions for t8_element_array_t, the eclass function either t8_element_new or t8_element_init is called for the element. Thus, each element in a t8_element_array_t is automatically initialized properly. + +| Field | Note | +| :----------- | :----------------------------------------------------- | +| scheme | The scheme of which elements should be stored. | +| tree\\_class | !< A scheme of which elements should be stored | +| array | !< The tree class of the elements stored in the array | +""" +struct t8_element_array_t + scheme::Ptr{t8_scheme_c} + tree_class::t8_eclass_t + array::sc_array_t +end + +""" + t8_element_array_new(scheme, tree_class) + +Creates a new array structure with 0 elements. + +# Arguments +* `scheme`:\\[in\\] The eclass scheme of which elements should be stored. +* `tree_class`:\\[in\\] The tree class of the elements stored in the array. +# Returns +Return an allocated array of zero length. +### Prototype +```c +t8_element_array_t * t8_element_array_new (const t8_scheme_c *scheme, const t8_eclass_t tree_class); +``` +""" +function t8_element_array_new(scheme, tree_class) + @ccall libt8.t8_element_array_new(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Ptr{t8_element_array_t} +end + +""" + t8_element_array_new_count(scheme, tree_class, num_elements) + +Creates a new array structure with a given length (number of elements) and calls t8_element_new for those elements. + +# Arguments +* `scheme`:\\[in\\] The eclass scheme of which elements should be stored. +* `tree_class`:\\[in\\] The tree class of the elements stored in the array. +* `num_elements`:\\[in\\] Initial number of array elements. +# Returns +Return an allocated array with allocated and initialized elements for which t8_element_new was called. +### Prototype +```c +t8_element_array_t * t8_element_array_new_count (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const size_t num_elements); +``` +""" +function t8_element_array_new_count(scheme, tree_class, num_elements) + @ccall libt8.t8_element_array_new_count(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, num_elements::Csize_t)::Ptr{t8_element_array_t} +end + +""" + t8_element_array_init(element_array, scheme, tree_class) + +Initializes an already allocated (or static) array structure. + +# Arguments +* `element_array`:\\[in,out\\] Array structure to be initialized. +* `scheme`:\\[in\\] The eclass scheme of which elements should be stored. +* `tree_class`:\\[in\\] The tree class of the elements stored in the array. +### Prototype +```c +void t8_element_array_init (t8_element_array_t *element_array, const t8_scheme_c *scheme, const t8_eclass_t tree_class); +``` +""" +function t8_element_array_init(element_array, scheme, tree_class) + @ccall libt8.t8_element_array_init(element_array::Ptr{t8_element_array_t}, scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Cvoid +end + +""" + t8_element_array_init_size(element_array, scheme, tree_class, num_elements) + +Initializes an already allocated (or static) array structure and allocates a given number of elements and initializes them with t8_element_init. + +# Arguments +* `element_array`:\\[in,out\\] Array structure to be initialized. +* `scheme`:\\[in\\] The eclass scheme of which elements should be stored. +* `tree_class`:\\[in\\] The tree class of the elements stored in the array. +* `num_elements`:\\[in\\] Number of initial array elements. +### Prototype +```c +void t8_element_array_init_size (t8_element_array_t *element_array, const t8_scheme_c *scheme, const t8_eclass_t tree_class, const size_t num_elements); +``` +""" +function t8_element_array_init_size(element_array, scheme, tree_class, num_elements) + @ccall libt8.t8_element_array_init_size(element_array::Ptr{t8_element_array_t}, scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, num_elements::Csize_t)::Cvoid +end + +""" + t8_element_array_init_view(view, array, offset, length) + +Initializes an already allocated (or static) view from existing t8\\_element\\_array. The array view returned does not require [`t8_element_array_reset`](@ref) (doesn't hurt though). + +# Arguments +* `view`:\\[in,out\\] Array structure to be initialized. +* `array`:\\[in\\] The array must not be resized while view is alive. +* `offset`:\\[in\\] The offset of the viewed section in element units. This offset cannot be changed until the view is reset. +* `length`:\\[in\\] The length of the view in element units. The view cannot be resized to exceed this length. It is not necessary to call [`sc_array_reset`](@ref) later. +### Prototype +```c +void t8_element_array_init_view (t8_element_array_t *view, const t8_element_array_t *array, const size_t offset, const size_t length); +``` +""" +function t8_element_array_init_view(view, array, offset, length) + @ccall libt8.t8_element_array_init_view(view::Ptr{t8_element_array_t}, array::Ptr{t8_element_array_t}, offset::Csize_t, length::Csize_t)::Cvoid +end + +""" + t8_element_array_init_data(view, base, scheme, tree_class, elem_count) + +Initializes an already allocated (or static) view from given plain C data (array of [`t8_element_t`](@ref)). The array view returned does not require [`t8_element_array_reset`](@ref) (doesn't hurt though). + +# Arguments +* `view`:\\[in,out\\] Array structure to be initialized. +* `base`:\\[in\\] The data must not be moved while view is alive. Must be an array of [`t8_element_t`](@ref) corresponding to *scheme*. +* `scheme`:\\[in\\] The scheme of the elements stored in *base*. +* `tree_class`:\\[in\\] The tree class of the elements stored in *base*. +* `elem_count`:\\[in\\] The length of the view in element units. The view cannot be resized to exceed this length. It is not necessary to call [`t8_element_array_reset`](@ref) later. +### Prototype +```c +void t8_element_array_init_data (t8_element_array_t *view, const t8_element_t *base, const t8_scheme_c *scheme, const t8_eclass_t tree_class, const size_t elem_count); +``` +""" +function t8_element_array_init_data(view, base, scheme, tree_class, elem_count) + @ccall libt8.t8_element_array_init_data(view::Ptr{t8_element_array_t}, base::Ptr{t8_element_t}, scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem_count::Csize_t)::Cvoid +end + +""" + t8_element_array_init_copy(element_array, scheme, tree_class, data, num_elements) + +Initializes an already allocated (or static) array structure and copy an existing array of [`t8_element_t`](@ref) into it. + +# Arguments +* `element_array`:\\[in,out\\] Array structure to be initialized. +* `scheme`:\\[in\\] The eclass scheme of which elements should be stored. +* `tree_class`:\\[in\\] The tree class of the elements stored in the array. +* `data`:\\[in\\] An array of [`t8_element_t`](@ref) which will be copied into *element_array*. The elements in *data* must belong to *scheme* and must be properly initialized with either t8_element_new or t8_element_init. +* `num_elements`:\\[in\\] Number of elements in *data* to be copied. +### Prototype +```c +void t8_element_array_init_copy (t8_element_array_t *element_array, const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *data, const size_t num_elements); +``` +""" +function t8_element_array_init_copy(element_array, scheme, tree_class, data, num_elements) + @ccall libt8.t8_element_array_init_copy(element_array::Ptr{t8_element_array_t}, scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, data::Ptr{t8_element_t}, num_elements::Csize_t)::Cvoid +end + +""" + t8_element_array_resize(element_array, new_count) + +Change the number of elements stored in an element array. + +!!! note + + If *new_count* is larger than the number of current elements on *element_array*, then t8_element_init is called for the new elements. + +# Arguments +* `element_array`:\\[in,out\\] The element array to be modified. +* `new_count`:\\[in\\] The new element count of the array. If it is zero the effect equals t8_element_array_reset. +### Prototype +```c +void t8_element_array_resize (t8_element_array_t *element_array, const size_t new_count); +``` +""" +function t8_element_array_resize(element_array, new_count) + @ccall libt8.t8_element_array_resize(element_array::Ptr{t8_element_array_t}, new_count::Csize_t)::Cvoid +end + +""" + t8_element_array_copy(dest, src) + +Copy the contents of an array into another. Both arrays must have the same eclass\\_scheme. + +# Arguments +* `dest`:\\[in\\] Array will be resized and get new data. +* `src`:\\[in\\] Array used as source of new data, will not be changed. +### Prototype +```c +void t8_element_array_copy (t8_element_array_t *dest, const t8_element_array_t *src); +``` +""" +function t8_element_array_copy(dest, src) + @ccall libt8.t8_element_array_copy(dest::Ptr{t8_element_array_t}, src::Ptr{t8_element_array_t})::Cvoid +end + +""" + t8_element_array_push(element_array) + +Enlarge an array by one element. + +# Arguments +* `element_array`:\\[in,out\\] Array structure to be modified. +# Returns +Returns a pointer to a newly added element for which t8_element_init was called. +### Prototype +```c +t8_element_t * t8_element_array_push (t8_element_array_t *element_array); +``` +""" +function t8_element_array_push(element_array) + @ccall libt8.t8_element_array_push(element_array::Ptr{t8_element_array_t})::Ptr{t8_element_t} +end + +""" + t8_element_array_push_count(element_array, count) + +Enlarge an array by a number of elements. + +# Arguments +* `element_array`:\\[in,out\\] Array structure to be modified. +* `count`:\\[in\\] The number of elements to add. +# Returns +Returns a pointer to the newly added elements for which t8_element_init was called. +### Prototype +```c +t8_element_t * t8_element_array_push_count (t8_element_array_t *element_array, size_t count); +``` +""" +function t8_element_array_push_count(element_array, count) + @ccall libt8.t8_element_array_push_count(element_array::Ptr{t8_element_array_t}, count::Csize_t)::Ptr{t8_element_t} +end + +""" + t8_element_array_index_locidx(element_array, index) + +Return a given element in an array. Const version. + +# Arguments +* `element_array`:\\[in\\] Array of elements. +* `index`:\\[in\\] The index of an element within the array. +# Returns +A pointer to the element stored at position *index* in *element_array*. +### Prototype +```c +const t8_element_t * t8_element_array_index_locidx (const t8_element_array_t *element_array, const t8_locidx_t index); +``` +""" +function t8_element_array_index_locidx(element_array, index) + @ccall libt8.t8_element_array_index_locidx(element_array::Ptr{t8_element_array_t}, index::t8_locidx_t)::Ptr{t8_element_t} +end + +""" + t8_element_array_index_int(element_array, index) + +Return a given element in an array. Const version. + +# Arguments +* `element_array`:\\[in\\] Array of elements. +* `index`:\\[in\\] The index of an element within the array. +# Returns +A pointer to the element stored at position *index* in *element_array*. +### Prototype +```c +const t8_element_t * t8_element_array_index_int (const t8_element_array_t *element_array, const int index); +``` +""" +function t8_element_array_index_int(element_array, index) + @ccall libt8.t8_element_array_index_int(element_array::Ptr{t8_element_array_t}, index::Cint)::Ptr{t8_element_t} +end + +""" + t8_element_array_index_locidx_mutable(element_array, index) + +Return a given element in an array. Mutable version. + +# Arguments +* `element_array`:\\[in\\] Array of elements. +* `index`:\\[in\\] The index of an element within the array. +# Returns +A pointer to the element stored at position *index* in *element_array*. +### Prototype +```c +t8_element_t * t8_element_array_index_locidx_mutable (t8_element_array_t *element_array, const t8_locidx_t index); +``` +""" +function t8_element_array_index_locidx_mutable(element_array, index) + @ccall libt8.t8_element_array_index_locidx_mutable(element_array::Ptr{t8_element_array_t}, index::t8_locidx_t)::Ptr{t8_element_t} +end + +""" + t8_element_array_index_int_mutable(element_array, index) + +Return a given element in an array. Mutable version. + +# Arguments +* `element_array`:\\[in\\] Array of elements. +* `index`:\\[in\\] The index of an element within the array. +# Returns +A pointer to the element stored at position *index* in *element_array*. +### Prototype +```c +t8_element_t * t8_element_array_index_int_mutable (t8_element_array_t *element_array, const int index); +``` +""" +function t8_element_array_index_int_mutable(element_array, index) + @ccall libt8.t8_element_array_index_int_mutable(element_array::Ptr{t8_element_array_t}, index::Cint)::Ptr{t8_element_t} +end + +""" + t8_element_array_get_scheme(element_array) + +Return the eclass scheme associated to a t8\\_element\\_array. + +# Arguments +* `element_array`:\\[in\\] Array of elements. +# Returns +The eclass scheme stored at *element_array*. +### Prototype +```c +const t8_scheme_c * t8_element_array_get_scheme (const t8_element_array_t *element_array); +``` +""" +function t8_element_array_get_scheme(element_array) + @ccall libt8.t8_element_array_get_scheme(element_array::Ptr{t8_element_array_t})::Ptr{t8_scheme_c} +end + +""" + t8_element_array_get_tree_class(element_array) + +Return the tree class of the t8\\_element\\_array . + +# Arguments +* `element_array`:\\[in\\] Array of elements. +# Returns +The tree class stored at *element_array*. +### Prototype +```c +t8_eclass_t t8_element_array_get_tree_class (const t8_element_array_t *element_array); +``` +""" +function t8_element_array_get_tree_class(element_array) + @ccall libt8.t8_element_array_get_tree_class(element_array::Ptr{t8_element_array_t})::t8_eclass_t +end + +""" + t8_element_array_get_count(element_array) + +Return the number of elements stored in a [`t8_element_array_t`](@ref). + +# Arguments +* `element_array`:\\[in\\] Array structure. +# Returns +The number of elements stored in *element_array*. +### Prototype +```c +size_t t8_element_array_get_count (const t8_element_array_t *element_array); +``` +""" +function t8_element_array_get_count(element_array) + @ccall libt8.t8_element_array_get_count(element_array::Ptr{t8_element_array_t})::Csize_t +end + +""" + t8_element_array_get_size(element_array) + +Return the data size of elements stored in a [`t8_element_array_t`](@ref). + +# Arguments +* `element_array`:\\[in\\] Array structure. +# Returns +The size (in bytes) of a single element in *element_array*. +### Prototype +```c +size_t t8_element_array_get_size (const t8_element_array_t *element_array); +``` +""" +function t8_element_array_get_size(element_array) + @ccall libt8.t8_element_array_get_size(element_array::Ptr{t8_element_array_t})::Csize_t +end + +""" + t8_element_array_get_data(element_array) + +Return a const pointer to the real data array stored in a t8\\_element\\_array. + +# Arguments +* `element_array`:\\[in\\] Array structure. +# Returns +A pointer to the stored data. If the number of stored elements is 0, then NULL is returned. +### Prototype +```c +const t8_element_t * t8_element_array_get_data (const t8_element_array_t *element_array); +``` +""" +function t8_element_array_get_data(element_array) + @ccall libt8.t8_element_array_get_data(element_array::Ptr{t8_element_array_t})::Ptr{t8_element_t} +end + +""" + t8_element_array_get_data_mutable(element_array) + +Return a pointer to the real data array stored in a t8\\_element\\_array. + +# Arguments +* `element_array`:\\[in\\] Array structure. +# Returns +A pointer to the stored data. If the number of stored elements is 0, then NULL is returned. +### Prototype +```c +t8_element_t * t8_element_array_get_data_mutable (t8_element_array_t *element_array); +``` +""" +function t8_element_array_get_data_mutable(element_array) + @ccall libt8.t8_element_array_get_data_mutable(element_array::Ptr{t8_element_array_t})::Ptr{t8_element_t} +end + +""" + t8_element_array_get_array(element_array) + +Return a const pointer to the [`sc_array`](@ref) stored in a t8\\_element\\_array. + +!!! note + + The data cannot be modified. + +# Arguments +* `element_array`:\\[in\\] Array structure. +# Returns +A const pointer to the [`sc_array`](@ref) storing the data. +### Prototype +```c +const sc_array_t * t8_element_array_get_array (const t8_element_array_t *element_array); +``` +""" +function t8_element_array_get_array(element_array) + @ccall libt8.t8_element_array_get_array(element_array::Ptr{t8_element_array_t})::Ptr{sc_array_t} +end + +""" + t8_element_array_get_array_mutable(element_array) + +Return a mutable pointer to the [`sc_array`](@ref) stored in a t8\\_element\\_array. + +!!! note + + The data can be modified. + +# Arguments +* `element_array`:\\[in\\] Array structure. +# Returns +A pointer to the [`sc_array`](@ref) storing the data. +### Prototype +```c +sc_array_t * t8_element_array_get_array_mutable (t8_element_array_t *element_array); +``` +""" +function t8_element_array_get_array_mutable(element_array) + @ccall libt8.t8_element_array_get_array_mutable(element_array::Ptr{t8_element_array_t})::Ptr{sc_array_t} +end + +""" + t8_element_array_find(element_array, element) + +Search for an element in an array. + +# Arguments +* `element_array`:\\[in\\] Array structure. +* `element`:\\[in\\] Element to be found in *element_array*. The element must have been created with the scheme used in *element_array*. +# Returns +If *element* was found in *element_array* then the position in the array is returned. If the element is not found, -1 is returned. +### Prototype +```c +t8_locidx_t t8_element_array_find (const t8_element_array_t *element_array, const t8_element_t *element); +``` +""" +function t8_element_array_find(element_array, element) + @ccall libt8.t8_element_array_find(element_array::Ptr{t8_element_array_t}, element::Ptr{t8_element_t})::t8_locidx_t +end + +""" + t8_element_array_reset(element_array) + +Sets the array count to zero and frees all elements. + +!!! note + + Calling [`t8_element_array_init`](@ref), then any array operations, then [`t8_element_array_reset`](@ref) is memory neutral. + +# Arguments +* `element_array`:\\[in,out\\] Array structure to be reset. +### Prototype +```c +void t8_element_array_reset (t8_element_array_t *element_array); +``` +""" +function t8_element_array_reset(element_array) + @ccall libt8.t8_element_array_reset(element_array::Ptr{t8_element_array_t})::Cvoid +end + +""" + t8_element_array_truncate(element_array) + +Sets the array count to zero, but does not free elements. + +!!! note + + This is intended to allow an t8\\_element\\_array to be used as a reusable buffer, where the "high water mark" of the buffer is preserved, so that O(log (max n)) reallocs occur over the life of the buffer. + +# Arguments +* `element_array`:\\[in,out\\] Element array structure to be truncated. +### Prototype +```c +void t8_element_array_truncate (t8_element_array_t *element_array); +``` +""" +function t8_element_array_truncate(element_array) + @ccall libt8.t8_element_array_truncate(element_array::Ptr{t8_element_array_t})::Cvoid +end + +""" + t8_forest + +| Field | Note | +| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| rc | Reference counter. | +| set\\_partition\\_offset | Flag indicating whether the partition range was set manually. | +| set\\_first\\_global\\_element | If set\\_partition\\_offset is true, the global ID of the first local element after partitioning. | +| set\\_level | Level to use in new construction. | +| set\\_for\\_coarsening | Change partition to allow for one round of coarsening | +| weight\\_function | Pointer to user defined element weight function. Nullptr for standard, element-based partitioning. | +| cmesh | Coarse mesh to use. | +| scheme | Scheme for element types. | +| maxlevel | The maximum allowed refinement level for elements in this forest. | +| maxlevel\\_existing | If >= 0, the maximum occurring refinement level of a forest element. | +| do\\_dup | Communicator shall be duped. | +| dimension | Dimension inferred from **cmesh**. | +| incomplete\\_trees | Flag to check whether the forest has (potential) incomplete trees. A tree is incomplete if an element has been removed from it. Once an element got removed, the flag sets to 1 (true) and stays. For a committed forest this flag is either true on all ranks or false on all ranks. | +| set\\_from | Temporarily store source forest. | +| from\\_method | Method to derive from **set_from**. | +| set\\_adapt\\_fn | refinement and coarsen function. Called when **from_method** is set to [`T8_FOREST_FROM_ADAPT`](@ref). | +| set\\_adapt\\_recursive | Flag to decide whether coarsen and refine are carried out recursive | +| set\\_balance | Flag to decide whether to forest will be balance in t8_forest_commit. See t8_forest_set_balance. If 0, no balance. If 1 balance with repartitioning, if 2 balance without repartitioning, # See also t8\\_forest\\_balance | +| do\\_ghost | If True, a ghost layer will be created when the forest is committed. | +| ghost\\_type | If a ghost layer will be created, the type of neighbors that count as ghost. | +| ghost\\_algorithm | Controls the algorithm used for ghost. 1 = balanced only. 2 = also unbalanced 3 = top-down search and unbalanced. | +| user\\_data | Pointer for arbitrary user data. # See also [`t8_forest_set_user_data`](@ref). | +| user\\_function | Pointer for arbitrary user function. # See also [`t8_forest_set_user_function`](@ref). | +| t8code\\_data | Pointer for arbitrary data that is used internally. | +| committed | t8_forest_commit called? | +| mpisize | Number of MPI processes. | +| mpirank | Number of this MPI process. | +| first\\_local\\_tree | The global index of the first local tree on this process. If first\\_local\\_tree is larger than last\\_local\\_tree then this processor/forest is empty. See https://github.com/DLR-AMR/t8code/wiki/Tree-indexing | +| last\\_local\\_tree | The global index of the last local tree on this process. -1 if this processor is empty. | +| global\\_num\\_trees | The total number of global trees. | +| trees | The array of trees. | +| ghosts | If not NULL, the ghost elements. # See also [`t8_forest_ghost`](@ref).h | +| element\\_offsets | If partitioned, for each process the global index of its first element. Since it is memory consuming, it is usually only constructed when needed and otherwise unallocated. | +| global\\_first\\_desc | If partitioned, for each process the linear id (at maxlevel) of its first element's first descendant. t8_element_set_linear_id. Stores 0 for empty processes. Since it is memory consuming, it is usually only constructed when needed and otherwise unallocated. | +| tree\\_offsets | If partitioned for each process the global index of its first local tree or -(first local tree) - 1 if the first tree on that process is shared. Since this is memory consuming we only construct it when needed. This array follows the same logic as *tree_offsets* in [`t8_cmesh_t`](@ref) | +| local\\_num\\_leaf\\_elements | Number of leaf elements on this processor. | +| global\\_num\\_leaf\\_elements | Number of leaf elements on all processors. | +| profile | If not NULL, runtimes and statistics about forest\\_commit are stored here. | +| stats | The SC profiling stats of the forest. | +| stats\\_computed | Switch indicating whether the profiling stats have been compute (1) or not (0) | +""" +# This struct is not supposed to be read and modified directly. +# Besides, there is a circular dependency with `t8_forest_t` +# leading to an error output by Julia. +mutable struct t8_forest end + +"""Opaque pointer to a forest implementation.""" +const t8_forest_t = Ptr{t8_forest} + +""" + t8_tree + +The t8 tree datatype + +| Field | Note | +| :---------------- | :----------------------------------------------------------------- | +| leaf\\_elements | locally stored leaf elements | +| eclass | The element class of this tree | +| first\\_desc | first local descendant | +| last\\_desc | last local descendant | +| elements\\_offset | cumulative sum over earlier trees on this processor (locals only) | +""" +struct t8_tree + leaf_elements::t8_element_array_t + eclass::t8_eclass_t + first_desc::Ptr{t8_element_t} + last_desc::Ptr{t8_element_t} + elements_offset::t8_locidx_t +end + +"""Opaque pointer to a tree implementation.""" +const t8_tree_t = Ptr{t8_tree} + +""" + t8_ghost_type_t + +This type controls, which neighbors count as ghost elements. Currently, we support face-neighbors. Vertex and edge neighbors will eventually be added. + +| Enumerator | Note | +| :-------------------- | :---------------------------------------------------------------- | +| T8\\_GHOST\\_NONE | Do not create ghost layer. | +| T8\\_GHOST\\_FACES | Consider all face (codimension 1) neighbors. | +| T8\\_GHOST\\_EDGES | Consider all edge (codimension 2) and face neighbors. | +| T8\\_GHOST\\_VERTICES | Consider all vertex (codimension 3) and edge and face neighbors. | +""" +@cenum t8_ghost_type_t::UInt32 begin + T8_GHOST_NONE = 0 + T8_GHOST_FACES = 1 + T8_GHOST_EDGES = 2 + T8_GHOST_VERTICES = 3 +end + +# typedef void ( * t8_generic_function_pointer ) ( void ) +""" +This typedef is needed as a helper construct to properly be able to define a function that returns a pointer to a void fun(void) function. + +# See also +[`t8_forest_get_user_function`](@ref). +""" +const t8_generic_function_pointer = Ptr{Cvoid} + +# typedef double ( t8_weight_fcn_t ) ( t8_forest_t , t8_locidx_t , t8_locidx_t ) +"""The prototype of a weight function for the partition algorithm. The function should be pure, and return a positive weight given a forest, a local tree index and an element index within the local tree""" +const t8_weight_fcn_t = Cvoid + +# typedef void ( * t8_forest_replace_t ) ( t8_forest_t forest_old , t8_forest_t forest_new , t8_locidx_t which_tree , const t8_eclass_t tree_class , const t8_scheme_c * scheme , const int refine , const int num_outgoing , const t8_locidx_t first_outgoing , const int num_incoming , const t8_locidx_t first_incoming ) +""" +Callback function prototype to replace one set of elements with another. + +This is used by the replace routine which can be called after adapt, when the elements of an existing, valid forest are changed. The callback allows the user to make changes to the elements of the new forest that are either refined, coarsened or the same as elements in the old forest. + +If an element is being refined, *refine* and *num_outgoing* will be 1 and *num_incoming* will be the number of children. If a family is being coarsened, *refine* will be -1, *num_outgoing* will be the number of family members and *num_incoming* will be 1. If an element is being removed, *refine* and *num_outgoing* will be 1 and *num_incoming* will be 0. Else *refine* will be 0 and *num_outgoing* and *num_incoming* will both be 1. + +# Arguments +* `forest_old`:\\[in\\] The forest that is adapted +* `forest_new`:\\[in,out\\] The forest that is newly constructed from *forest_old* +* `which_tree`:\\[in\\] The local tree containing *first_outgoing* and *first_incoming* +* `tree_class`:\\[in\\] The eclass of the local tree containing *first_outgoing* and *first_incoming* +* `scheme`:\\[in\\] The scheme of the forest +* `refine`:\\[in\\] -1 if family in *forest_old* got coarsened, 0 if element has not been touched, 1 if element got refined and -2 if element got removed. See return of [`t8_forest_adapt_t`](@ref). +* `num_outgoing`:\\[in\\] The number of outgoing elements. +* `first_outgoing`:\\[in\\] The tree local index of the first outgoing element. 0 <= first\\_outgoing < which\\_tree->num\\_elements +* `num_incoming`:\\[in\\] The number of incoming elements. +* `first_incoming`:\\[in\\] The tree local index of the first incoming element. 0 <= first\\_incom < new\\_which\\_tree->num\\_elements +# See also +[`t8_forest_iterate_replace`](@ref) +""" +const t8_forest_replace_t = Ptr{Cvoid} -This function reads a mesh from *filename* and returns an associated p4est connectivity. +# typedef int ( * t8_forest_adapt_t ) ( t8_forest_t forest , t8_forest_t forest_from , t8_locidx_t which_tree , const t8_eclass_t tree_class , t8_locidx_t lelement_id , const t8_scheme_c * scheme , const int is_family , const int num_elements , t8_element_t * elements [ ] ) +""" +Callback function prototype to decide for refining and coarsening. If *is_family* equals 1, the first *num_elements* in *elements* form a family and we decide whether this family should be coarsened or only the first element should be refined. Otherwise *is_family* must equal zero and we consider the first entry of the element array for refinement. Entries of the element array beyond the first *num_elements* are undefined. # Arguments -* `filename`:\\[in\\] file to read the connectivity from +* `forest`:\\[in\\] The forest to which the new elements belong. +* `forest_from`:\\[in\\] The forest that is adapted. +* `which_tree`:\\[in\\] The local tree containing *elements*. +* `tree_class`:\\[in\\] The eclass of *which_tree*. +* `lelement_id`:\\[in\\] The local element id in *forest_from* in the tree of the current element. +* `scheme`:\\[in\\] The scheme of the forest. +* `is_family`:\\[in\\] If 1, the first *num_elements* entries in *elements* form a family. If 0, they do not. +* `num_elements`:\\[in\\] The number of entries in *elements* that are defined +* `elements`:\\[in\\] Pointers to a family or, if *is_family* is zero, pointer to one element. # Returns -an allocated connectivity associated with the mesh in *filename* -### Prototype -```c -p8est_connectivity_t *p8est_connectivity_read_inp (const char *filename); -``` +1 if the first entry in *elements* should be refined, -1 if the family *elements* shall be coarsened, -2 if the first entry in *elements* should be removed, 0 else. """ -function p8est_connectivity_read_inp(filename) - @ccall libp4est.p8est_connectivity_read_inp(filename::Cstring)::Ptr{p8est_connectivity_t} -end +const t8_forest_adapt_t = Ptr{Cvoid} """ - t8_cmesh_new_from_p4est(conn, comm, do_partition) + t8_forest_init(pforest) -### Prototype -```c -t8_cmesh_t t8_cmesh_new_from_p4est (p4est_connectivity_t *conn, sc_MPI_Comm comm, int do_partition); -``` -""" -function t8_cmesh_new_from_p4est(conn, comm, do_partition) - @ccall libt8.t8_cmesh_new_from_p4est(conn::Ptr{p4est_connectivity_t}, comm::MPI_Comm, do_partition::Cint)::t8_cmesh_t -end +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 -""" - t8_cmesh_new_from_p8est(conn, comm, do_partition) +# Arguments +* `pforest`:\\[in,out\\] On input, this pointer must be non-NULL. On return, this pointer set to the new forest. +# See also +t8\\_forest\\_set\\_mpicomm, t8_forest_set_cmesh, and t8_forest_set_scheme, or to call one of t8_forest_set_copy, t8_forest_set_adapt, or t8_forest_set_partition. It is illegal to mix these calls, or to call more than one of the three latter functions Then it needs to be set up with t8_forest_commit. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_from_p8est (p8est_connectivity_t *conn, sc_MPI_Comm comm, int do_partition); +void t8_forest_init (t8_forest_t *pforest); ``` """ -function t8_cmesh_new_from_p8est(conn, comm, do_partition) - @ccall libt8.t8_cmesh_new_from_p8est(conn::Ptr{p8est_connectivity_t}, comm::MPI_Comm, do_partition::Cint)::t8_cmesh_t +function t8_forest_init(pforest) + @ccall libt8.t8_forest_init(pforest::Ptr{t8_forest_t})::Cvoid end """ - t8_cmesh_new_empty(comm, do_partition, dimension) + t8_forest_is_initialized(forest) + +Check whether a forest is not NULL, initialized and not committed. In addition, it asserts that the forest is consistent as much as possible. +# Arguments +* `forest`:\\[in\\] This forest is examined. May be NULL. +# Returns +True if forest is not NULL, t8_forest_init has been called on it, but not t8_forest_commit. False otherwise. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_empty (sc_MPI_Comm comm, const int do_partition, const int dimension); +int t8_forest_is_initialized (t8_forest_t forest); ``` """ -function t8_cmesh_new_empty(comm, do_partition, dimension) - @ccall libt8.t8_cmesh_new_empty(comm::MPI_Comm, do_partition::Cint, dimension::Cint)::t8_cmesh_t +function t8_forest_is_initialized(forest) + @ccall libt8.t8_forest_is_initialized(forest::t8_forest_t)::Cint end """ - t8_cmesh_new_from_class(eclass, comm) + t8_forest_is_committed(forest) + +Check whether a forest is not NULL, initialized and committed. In addition, it asserts that the forest is consistent as much as possible. +# Arguments +* `forest`:\\[in\\] This forest is examined. May be NULL. +# Returns +True if forest is not NULL and t8_forest_init has been called on it as well as t8_forest_commit. False otherwise. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_from_class (t8_eclass_t eclass, sc_MPI_Comm comm); +int t8_forest_is_committed (t8_forest_t forest); ``` """ -function t8_cmesh_new_from_class(eclass, comm) - @ccall libt8.t8_cmesh_new_from_class(eclass::t8_eclass_t, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_is_committed(forest) + @ccall libt8.t8_forest_is_committed(forest::t8_forest_t)::Cint end """ - t8_cmesh_new_hypercube(eclass, comm, do_bcast, do_partition, periodic) + t8_forest_no_overlap(forest) -### Prototype -```c -t8_cmesh_t t8_cmesh_new_hypercube (t8_eclass_t eclass, sc_MPI_Comm comm, int do_bcast, int do_partition, int periodic); -``` -""" -function t8_cmesh_new_hypercube(eclass, comm, do_bcast, do_partition, periodic) - @ccall libt8.t8_cmesh_new_hypercube(eclass::t8_eclass_t, comm::MPI_Comm, do_bcast::Cint, do_partition::Cint, periodic::Cint)::t8_cmesh_t -end +Check whether the forest has local overlapping elements. -""" - t8_cmesh_new_hypercube_pad(eclass, comm, boundary, polygons_x, polygons_y, polygons_z, use_axis_aligned) +!!! note + + This function is collective, but only checks local overlapping on each process. + +# Arguments +* `forest`:\\[in\\] The forest to consider. +# Returns +True if *forest* has no elements which are inside each other. +# See also +[`t8_forest_partition_test_boundary_element`](@ref) if you also want to test for global overlap across the process boundaries. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_hypercube_pad (const t8_eclass_t eclass, sc_MPI_Comm comm, const double *boundary, t8_locidx_t polygons_x, t8_locidx_t polygons_y, t8_locidx_t polygons_z, const int use_axis_aligned); +int t8_forest_no_overlap (t8_forest_t forest); ``` """ -function t8_cmesh_new_hypercube_pad(eclass, comm, boundary, polygons_x, polygons_y, polygons_z, use_axis_aligned) - @ccall libt8.t8_cmesh_new_hypercube_pad(eclass::t8_eclass_t, comm::MPI_Comm, boundary::Ptr{Cdouble}, polygons_x::t8_locidx_t, polygons_y::t8_locidx_t, polygons_z::t8_locidx_t, use_axis_aligned::Cint)::t8_cmesh_t +function t8_forest_no_overlap(forest) + @ccall libt8.t8_forest_no_overlap(forest::t8_forest_t)::Cint end """ - t8_cmesh_new_hypercube_pad_ext(eclass, comm, boundary, polygons_x, polygons_y, polygons_z, periodic_x, periodic_y, periodic_z, use_axis_aligned, set_partition, offset) + t8_forest_is_equal(forest_a, forest_b) + +Check whether two committed forests have the same local elements. +!!! note + + This function is not collective. It only returns the state on the current rank. + +# Arguments +* `forest_a`:\\[in\\] The first forest. +* `forest_b`:\\[in\\] The second forest. +# Returns +True if *forest_a* and *forest_b* do have the same number of local trees and each local tree has the same elements, that is t8_element_is_equal returns true for each pair of elements of *forest_a* and *forest_b*. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_hypercube_pad_ext (const t8_eclass_t eclass, sc_MPI_Comm comm, const double *boundary, t8_locidx_t polygons_x, t8_locidx_t polygons_y, t8_locidx_t polygons_z, const int periodic_x, const int periodic_y, const int periodic_z, const int use_axis_aligned, const int set_partition, t8_gloidx_t offset); +int t8_forest_is_equal (t8_forest_t forest_a, t8_forest_t forest_b); ``` """ -function t8_cmesh_new_hypercube_pad_ext(eclass, comm, boundary, polygons_x, polygons_y, polygons_z, periodic_x, periodic_y, periodic_z, use_axis_aligned, set_partition, offset) - @ccall libt8.t8_cmesh_new_hypercube_pad_ext(eclass::t8_eclass_t, comm::MPI_Comm, boundary::Ptr{Cdouble}, polygons_x::t8_locidx_t, polygons_y::t8_locidx_t, polygons_z::t8_locidx_t, periodic_x::Cint, periodic_y::Cint, periodic_z::Cint, use_axis_aligned::Cint, set_partition::Cint, offset::t8_gloidx_t)::t8_cmesh_t +function t8_forest_is_equal(forest_a, forest_b) + @ccall libt8.t8_forest_is_equal(forest_a::t8_forest_t, forest_b::t8_forest_t)::Cint end """ - t8_cmesh_new_hypercube_hybrid(comm, do_partition, periodic) + t8_forest_set_cmesh(forest, cmesh, comm) ### Prototype ```c -t8_cmesh_t t8_cmesh_new_hypercube_hybrid (sc_MPI_Comm comm, int do_partition, int periodic); +void t8_forest_set_cmesh (t8_forest_t forest, t8_cmesh_t cmesh, sc_MPI_Comm comm); ``` """ -function t8_cmesh_new_hypercube_hybrid(comm, do_partition, periodic) - @ccall libt8.t8_cmesh_new_hypercube_hybrid(comm::MPI_Comm, do_partition::Cint, periodic::Cint)::t8_cmesh_t +function t8_forest_set_cmesh(forest, cmesh, comm) + @ccall libt8.t8_forest_set_cmesh(forest::t8_forest_t, cmesh::t8_cmesh_t, comm::MPI_Comm)::Cvoid end """ - t8_cmesh_new_periodic(comm, dim) + t8_forest_set_scheme(forest, scheme) + +Set the element scheme associated to a forest. By default, the forest takes ownership of the scheme such that it will be destroyed when the forest is destroyed. To keep ownership of the scheme, call t8_scheme_ref before passing it to t8_forest_set_scheme. This means that it is ILLEGAL to continue using scheme or dereferencing it UNLESS it is referenced directly before passing it into this function. +# Arguments +* `forest`:\\[in,out\\] The forest whose scheme variable will be set. +* `scheme`:\\[in\\] The scheme to be set. We take ownership. This can be prevented by referencing **scheme**. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_periodic (sc_MPI_Comm comm, int dim); +void t8_forest_set_scheme (t8_forest_t forest, const t8_scheme_c *scheme); ``` """ -function t8_cmesh_new_periodic(comm, dim) - @ccall libt8.t8_cmesh_new_periodic(comm::MPI_Comm, dim::Cint)::t8_cmesh_t +function t8_forest_set_scheme(forest, scheme) + @ccall libt8.t8_forest_set_scheme(forest::t8_forest_t, scheme::Ptr{t8_scheme_c})::Cvoid end """ - t8_cmesh_new_periodic_tri(comm) + t8_forest_set_level(forest, level) + +Set the initial refinement level to be used when **forest** is committed. +!!! note + + This setting cannot be combined with any of the derived forest methods (t8_forest_set_copy, t8_forest_set_adapt, t8_forest_set_partition, and t8_forest_set_balance) and overwrites any of these settings. If this function is used, then the forest is created from scratch as a uniform refinement of the specified cmesh (t8_forest_set_cmesh, t8_forest_set_scheme). + +# Arguments +* `forest`:\\[in,out\\] The forest whose level will be set. +* `level`:\\[in\\] The initial refinement level of **forest**, when it is committed. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_periodic_tri (sc_MPI_Comm comm); +void t8_forest_set_level (t8_forest_t forest, int level); ``` """ -function t8_cmesh_new_periodic_tri(comm) - @ccall libt8.t8_cmesh_new_periodic_tri(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_set_level(forest, level) + @ccall libt8.t8_forest_set_level(forest::t8_forest_t, level::Cint)::Cvoid end """ - t8_cmesh_new_periodic_hybrid(comm) + t8_forest_set_copy(forest, from) + +Set a forest as source for copying on committing. By default, the forest takes ownership of the source **from** such that it will be destroyed on calling t8_forest_commit. To keep ownership of **from**, call t8_forest_ref before passing it into this function. This means that it is ILLEGAL to continue using **from** or dereferencing it UNLESS it is referenced directly before passing it into this function. + +!!! note + + This setting cannot be combined with t8_forest_set_adapt, t8_forest_set_partition, or t8_forest_set_balance and overwrites these settings. +# Arguments +* `forest`:\\[in,out\\] The forest. +* `from`:\\[in\\] A second forest from which *forest* will be copied in t8_forest_commit. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_periodic_hybrid (sc_MPI_Comm comm); +void t8_forest_set_copy (t8_forest_t forest, const t8_forest_t from); ``` """ -function t8_cmesh_new_periodic_hybrid(comm) - @ccall libt8.t8_cmesh_new_periodic_hybrid(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_set_copy(forest, from) + @ccall libt8.t8_forest_set_copy(forest::t8_forest_t, from::t8_forest_t)::Cvoid end """ - t8_cmesh_new_periodic_line_more_trees(comm) + t8_forest_set_adapt(forest, set_from, adapt_fn, recursive) +Set a source forest with an adapt function to be adapted on committing. By default, the forest takes ownership of the source **set_from** such that it will be destroyed on calling t8_forest_commit. To keep ownership of **set_from**, call t8_forest_ref before passing it into this function. This means that it is ILLEGAL to continue using **set_from** or dereferencing it UNLESS it is referenced directly before passing it into this function. + +!!! note + + This setting can be combined with t8_forest_set_partition and t8_forest_set_balance. The order in which these operations are executed is always 1) Adapt 2) Partition 3) Balance. + +!!! note + + This setting may not be combined with t8_forest_set_copy and overwrites this setting. + +# Arguments +* `forest`:\\[in,out\\] The forest +* `set_from`:\\[in\\] The source forest from which **forest** will be adapted. We take ownership. This can be prevented by referencing **set_from**. If NULL, a previously (or later) set forest will be taken (t8_forest_set_partition, t8_forest_set_balance). +* `adapt_fn`:\\[in\\] The adapt function used on committing. +* `recursive`:\\[in\\] A flag specifying whether adaptation is to be done recursively or not. If the value is zero, adaptation is not recursive and it is recursive otherwise. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_periodic_line_more_trees (sc_MPI_Comm comm); +void t8_forest_set_adapt (t8_forest_t forest, const t8_forest_t set_from, t8_forest_adapt_t adapt_fn, const int recursive); ``` """ -function t8_cmesh_new_periodic_line_more_trees(comm) - @ccall libt8.t8_cmesh_new_periodic_line_more_trees(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_set_adapt(forest, set_from, adapt_fn, recursive) + @ccall libt8.t8_forest_set_adapt(forest::t8_forest_t, set_from::t8_forest_t, adapt_fn::t8_forest_adapt_t, recursive::Cint)::Cvoid end """ - t8_cmesh_new_bigmesh(eclass, num_trees, comm) + t8_forest_set_user_data(forest, data) + +Set the user data of a forest. This can i.e. be used to pass user defined arguments to the adapt routine. + +# Arguments +* `forest`:\\[in,out\\] The forest +* `data`:\\[in\\] A pointer to user data. t8code will never touch the data. The forest does not need be committed before calling this function. +# See also +[`t8_forest_get_user_data`](@ref) ### Prototype ```c -t8_cmesh_t t8_cmesh_new_bigmesh (t8_eclass_t eclass, int num_trees, sc_MPI_Comm comm); +void t8_forest_set_user_data (t8_forest_t forest, void *data); ``` """ -function t8_cmesh_new_bigmesh(eclass, num_trees, comm) - @ccall libt8.t8_cmesh_new_bigmesh(eclass::t8_eclass_t, num_trees::Cint, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_set_user_data(forest, data) + @ccall libt8.t8_forest_set_user_data(forest::t8_forest_t, data::Ptr{Cvoid})::Cvoid end """ - t8_cmesh_new_line_zigzag(comm) + t8_forest_get_user_data(forest) + +Return the user data pointer associated with a forest. + +# Arguments +* `forest`:\\[in\\] The forest. +# Returns +The user data pointer of *forest*. The forest does not need be committed before calling this function. +# See also +[`t8_forest_set_user_data`](@ref) ### Prototype ```c -t8_cmesh_t t8_cmesh_new_line_zigzag (sc_MPI_Comm comm); +void * t8_forest_get_user_data (const t8_forest_t forest); ``` """ -function t8_cmesh_new_line_zigzag(comm) - @ccall libt8.t8_cmesh_new_line_zigzag(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_get_user_data(forest) + @ccall libt8.t8_forest_get_user_data(forest::t8_forest_t)::Ptr{Cvoid} end """ - t8_cmesh_new_prism_cake(comm, num_of_prisms) + t8_forest_set_user_function(forest, _function) + +Set the user function pointer of a forest. This can i.e. be used to pass user defined functions to the adapt routine. + +!!! note + + *function* can be an arbitrary function with return value and parameters of your choice. When accessing it with t8_forest_get_user_function you should cast it into the proper type. + +# Arguments +* `forest`:\\[in,out\\] The forest +* `function`:\\[in\\] A pointer to a user defined function. t8code will never touch the function. The forest does not need be committed before calling this function. +# See also +[`t8_forest_get_user_function`](@ref) ### Prototype ```c -t8_cmesh_t t8_cmesh_new_prism_cake (sc_MPI_Comm comm, int num_of_prisms); +void t8_forest_set_user_function (t8_forest_t forest, t8_generic_function_pointer function); ``` """ -function t8_cmesh_new_prism_cake(comm, num_of_prisms) - @ccall libt8.t8_cmesh_new_prism_cake(comm::MPI_Comm, num_of_prisms::Cint)::t8_cmesh_t +function t8_forest_set_user_function(forest, _function) + @ccall libt8.t8_forest_set_user_function(forest::t8_forest_t, _function::t8_generic_function_pointer)::Cvoid end """ - t8_cmesh_new_prism_deformed(comm) + t8_forest_get_user_function(forest) + +Return the user function pointer associated with a forest. + +# Arguments +* `forest`:\\[in\\] The forest. +# Returns +The user function pointer of *forest*. The forest does not need be committed before calling this function. +# See also +[`t8_forest_set_user_function`](@ref) ### Prototype ```c -t8_cmesh_t t8_cmesh_new_prism_deformed (sc_MPI_Comm comm); +t8_generic_function_pointer t8_forest_get_user_function (const t8_forest_t forest); ``` """ -function t8_cmesh_new_prism_deformed(comm) - @ccall libt8.t8_cmesh_new_prism_deformed(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_get_user_function(forest) + @ccall libt8.t8_forest_get_user_function(forest::t8_forest_t)::t8_generic_function_pointer end """ - t8_cmesh_new_pyramid_deformed(comm) + t8_forest_set_partition(forest, set_from, set_for_coarsening) + +Set a source forest to be partitioned during commit. The partitioning is done according to the SFC and each rank is assigned the same (maybe +1) number of elements. + +!!! note + + This setting can be combined with t8_forest_set_adapt and t8_forest_set_balance. The order in which these operations are executed is always 1) Adapt 2) Partition 3) Balance. If t8_forest_set_balance is called with the *no_repartition* parameter set as false, it is not necessary to call t8_forest_set_partition additionally. + +!!! note + + This setting may not be combined with t8_forest_set_copy and overwrites this setting. +# Arguments +* `forest`:\\[in,out\\] The forest. +* `set_from`:\\[in\\] A second forest that should be partitioned. We take ownership. This can be prevented by referencing **set_from**. If NULL, a previously (or later) set forest will be taken (t8_forest_set_adapt, t8_forest_set_balance). +* `set_for_coarsening`:\\[in\\] If true, the partition will be such that coarsening a family of elements into their parent once is a process-local operation. This is ensured by a post-processing step that slightly shifts the newly determined process boundaries such that no full family of (same-level) siblings is split between processes. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_pyramid_deformed (sc_MPI_Comm comm); +void t8_forest_set_partition (t8_forest_t forest, const t8_forest_t set_from, int set_for_coarsening); ``` """ -function t8_cmesh_new_pyramid_deformed(comm) - @ccall libt8.t8_cmesh_new_pyramid_deformed(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_set_partition(forest, set_from, set_for_coarsening) + @ccall libt8.t8_forest_set_partition(forest::t8_forest_t, set_from::t8_forest_t, set_for_coarsening::Cint)::Cvoid end """ - t8_cmesh_new_prism_cake_funny_oriented(comm) + t8_forest_set_partition_weight_function(forest, weight_callback) + +Set a user-defined weight function to guide the partitioning. + +\\pre *weight_callback* must be free of side effects (like changing the forest, some global state, etc.), the behavior is undefined otherwise. + +!!! note + + If *weight_callback* is null, then all the elements are assumed to have the same weight +# Arguments +* `forest`:\\[in,out\\] The forest. +* `weight_callback`:\\[in\\] A callback function defining element weights for the partitioning. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_prism_cake_funny_oriented (sc_MPI_Comm comm); +void t8_forest_set_partition_weight_function (t8_forest_t forest, t8_weight_fcn_t *weight_callback); ``` """ -function t8_cmesh_new_prism_cake_funny_oriented(comm) - @ccall libt8.t8_cmesh_new_prism_cake_funny_oriented(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_set_partition_weight_function(forest, weight_callback) + @ccall libt8.t8_forest_set_partition_weight_function(forest::t8_forest_t, weight_callback::Ptr{t8_weight_fcn_t})::Cvoid end """ - t8_cmesh_new_prism_geometry(comm) + t8_forest_set_balance(forest, set_from, no_repartition) + +Set a source forest to be balanced during commit. A forest is said to be balanced if each element has face neighbors of level at most +1 or -1 of the element's level. + +!!! note + + This setting can be combined with t8_forest_set_adapt and t8_forest_set_partition. The order in which these operations are executed is always 1) Adapt 2) Partition 3) Balance. + +!!! note + + This setting may not be combined with t8_forest_set_copy and overwrites this setting. +# Arguments +* `forest`:\\[in,out\\] The forest. +* `set_from`:\\[in\\] A second forest that should be balanced. We take ownership. This can be prevented by referencing **set_from**. If NULL, a previously (or later) set forest will be taken (t8_forest_set_adapt, t8_forest_set_partition) +* `no_repartition`:\\[in\\] Balance constructs several intermediate forest that are refined from each other. In order to maintain a balanced load these forest are repartitioned in each round and the resulting forest is load-balanced per default. If this behaviour is not desired, *no_repartition* should be set to true. If *no_repartition* is false, an additional call of t8_forest_set_partition is not necessary. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_prism_geometry (sc_MPI_Comm comm); +void t8_forest_set_balance (t8_forest_t forest, const t8_forest_t set_from, int no_repartition); ``` """ -function t8_cmesh_new_prism_geometry(comm) - @ccall libt8.t8_cmesh_new_prism_geometry(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_set_balance(forest, set_from, no_repartition) + @ccall libt8.t8_forest_set_balance(forest::t8_forest_t, set_from::t8_forest_t, no_repartition::Cint)::Cvoid end """ - t8_cmesh_new_brick_2d(num_x, num_y, x_periodic, y_periodic, comm) + t8_forest_set_ghost(forest, do_ghost, ghost_type) +Enable or disable the creation of a layer of ghost elements. On default no ghosts are created. + +# Arguments +* `forest`:\\[in\\] The forest. +* `do_ghost`:\\[in\\] If non-zero a ghost layer will be created. +* `ghost_type`:\\[in\\] Controls which neighbors count as ghost elements, currently only T8\\_GHOST\\_FACES is supported. This value is ignored if *do_ghost* = 0. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_brick_2d (t8_gloidx_t num_x, t8_gloidx_t num_y, int x_periodic, int y_periodic, sc_MPI_Comm comm); +void t8_forest_set_ghost (t8_forest_t forest, int do_ghost, t8_ghost_type_t ghost_type); ``` """ -function t8_cmesh_new_brick_2d(num_x, num_y, x_periodic, y_periodic, comm) - @ccall libt8.t8_cmesh_new_brick_2d(num_x::t8_gloidx_t, num_y::t8_gloidx_t, x_periodic::Cint, y_periodic::Cint, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_set_ghost(forest, do_ghost, ghost_type) + @ccall libt8.t8_forest_set_ghost(forest::t8_forest_t, do_ghost::Cint, ghost_type::t8_ghost_type_t)::Cvoid end """ - t8_cmesh_new_brick_3d(num_x, num_y, num_z, x_periodic, y_periodic, z_periodic, comm) + t8_forest_set_ghost_ext(forest, do_ghost, ghost_type, ghost_version) + +Like 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 t8_forest_set_ghost. + +# Arguments +* `forest`:\\[in\\] The forest. +* `do_ghost`:\\[in\\] If non-zero a ghost layer will be created. +* `ghost_type`:\\[in\\] Controls which neighbors count as ghost elements, currently only T8\\_GHOST\\_FACES is supported. This value is ignored if *do_ghost* = 0. +* `ghost_version`:\\[in\\] 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. +# See also +[`t8_forest_set_ghost`](@ref) ### Prototype ```c -t8_cmesh_t t8_cmesh_new_brick_3d (t8_gloidx_t num_x, t8_gloidx_t num_y, t8_gloidx_t num_z, int x_periodic, int y_periodic, int z_periodic, sc_MPI_Comm comm); +void t8_forest_set_ghost_ext (t8_forest_t forest, int do_ghost, t8_ghost_type_t ghost_type, int ghost_version); ``` """ -function t8_cmesh_new_brick_3d(num_x, num_y, num_z, x_periodic, y_periodic, z_periodic, comm) - @ccall libt8.t8_cmesh_new_brick_3d(num_x::t8_gloidx_t, num_y::t8_gloidx_t, num_z::t8_gloidx_t, x_periodic::Cint, y_periodic::Cint, z_periodic::Cint, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_set_ghost_ext(forest, do_ghost, ghost_type, ghost_version) + @ccall libt8.t8_forest_set_ghost_ext(forest::t8_forest_t, do_ghost::Cint, ghost_type::t8_ghost_type_t, ghost_version::Cint)::Cvoid end """ - t8_cmesh_new_disjoint_bricks(num_x, num_y, num_z, x_periodic, y_periodic, z_periodic, comm) + t8_forest_set_load(forest, filename) + +Use assertions and document that the forest\\_set (..., from) and set\\_load are mutually exclusive. + +TODO: Unused function -> remove? ### Prototype ```c -t8_cmesh_t t8_cmesh_new_disjoint_bricks (t8_gloidx_t num_x, t8_gloidx_t num_y, t8_gloidx_t num_z, int x_periodic, int y_periodic, int z_periodic, sc_MPI_Comm comm); +void t8_forest_set_load (t8_forest_t forest, const char *filename); ``` """ -function t8_cmesh_new_disjoint_bricks(num_x, num_y, num_z, x_periodic, y_periodic, z_periodic, comm) - @ccall libt8.t8_cmesh_new_disjoint_bricks(num_x::t8_gloidx_t, num_y::t8_gloidx_t, num_z::t8_gloidx_t, x_periodic::Cint, y_periodic::Cint, z_periodic::Cint, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_set_load(forest, filename) + @ccall libt8.t8_forest_set_load(forest::t8_forest_t, filename::Cstring)::Cvoid end """ - t8_cmesh_new_tet_orientation_test(comm) + t8_forest_comm_global_num_leaf_elements(forest) +Compute the global number of leaf elements in a forest as the sum of the local leaf element counts. + +# Arguments +* `forest`:\\[in\\] The forest. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_tet_orientation_test (sc_MPI_Comm comm); +void t8_forest_comm_global_num_leaf_elements (t8_forest_t forest); ``` """ -function t8_cmesh_new_tet_orientation_test(comm) - @ccall libt8.t8_cmesh_new_tet_orientation_test(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_comm_global_num_leaf_elements(forest) + @ccall libt8.t8_forest_comm_global_num_leaf_elements(forest::t8_forest_t)::Cvoid end """ - t8_cmesh_new_hybrid_gate(comm) + t8_forest_commit(forest) +After allocating and adding properties to a forest, commit the changes. This call sets up the internal state of the forest. + +# Arguments +* `forest`:\\[in,out\\] Must be created with t8_forest_init and specialized with t8\\_forest\\_set\\_* calls first. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_hybrid_gate (sc_MPI_Comm comm); +void t8_forest_commit (t8_forest_t forest); ``` """ -function t8_cmesh_new_hybrid_gate(comm) - @ccall libt8.t8_cmesh_new_hybrid_gate(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_commit(forest) + @ccall libt8.t8_forest_commit(forest::t8_forest_t)::Cvoid end """ - t8_cmesh_new_hybrid_gate_deformed(comm) + t8_forest_get_maxlevel(forest) +Return the maximum allowed refinement level for any element in a forest. + +# Arguments +* `forest`:\\[in\\] A forest. +# Returns +The maximum level of refinement that is allowed for an element in this forest. It is guaranteed that any tree in *forest* can be refined this many times and it is not allowed to refine further. *forest* must be committed before calling this function. For forest with a single element class (non-hybrid) maxlevel is the maximum refinement level of this element class, whilst for hybrid forests the maxlevel is the minimum of all maxlevels of the element classes in this forest. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_hybrid_gate_deformed (sc_MPI_Comm comm); +int t8_forest_get_maxlevel (const t8_forest_t forest); ``` """ -function t8_cmesh_new_hybrid_gate_deformed(comm) - @ccall libt8.t8_cmesh_new_hybrid_gate_deformed(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_get_maxlevel(forest) + @ccall libt8.t8_forest_get_maxlevel(forest::t8_forest_t)::Cint end """ - t8_cmesh_new_full_hybrid(comm) + t8_forest_get_local_num_leaf_elements(forest) + +Return the number of process local leaf elements in the forest. +# Arguments +* `forest`:\\[in\\] A forest. +# Returns +The number of leaf elements on this process in *forest*. *forest* must be committed before calling this function. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_full_hybrid (sc_MPI_Comm comm); +t8_locidx_t t8_forest_get_local_num_leaf_elements (const t8_forest_t forest); ``` """ -function t8_cmesh_new_full_hybrid(comm) - @ccall libt8.t8_cmesh_new_full_hybrid(comm::MPI_Comm)::t8_cmesh_t +function t8_forest_get_local_num_leaf_elements(forest) + @ccall libt8.t8_forest_get_local_num_leaf_elements(forest::t8_forest_t)::t8_locidx_t end """ - t8_cmesh_new_pyramid_cake(comm, num_of_pyra) + t8_forest_get_global_num_leaf_elements(forest) +Return the number of global leaf elements in the forest. + +# Arguments +* `forest`:\\[in\\] A forest. +# Returns +The number of leaf elements (summed over all processes) in *forest*. *forest* must be committed before calling this function. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_pyramid_cake (sc_MPI_Comm comm, int num_of_pyra); +t8_gloidx_t t8_forest_get_global_num_leaf_elements (const t8_forest_t forest); ``` """ -function t8_cmesh_new_pyramid_cake(comm, num_of_pyra) - @ccall libt8.t8_cmesh_new_pyramid_cake(comm::MPI_Comm, num_of_pyra::Cint)::t8_cmesh_t +function t8_forest_get_global_num_leaf_elements(forest) + @ccall libt8.t8_forest_get_global_num_leaf_elements(forest::t8_forest_t)::t8_gloidx_t end """ - t8_cmesh_new_long_brick_pyramid(comm, num_cubes) + t8_forest_get_num_ghosts(forest) + +Return the number of ghost elements of a forest. + +# Arguments +* `forest`:\\[in\\] The forest. +# Returns +The number of ghost elements stored in the ghost structure of *forest*. 0 if no ghosts were constructed. +# See also +[`t8_forest_set_ghost`](@ref) *forest* must be committed before calling this function. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_long_brick_pyramid (sc_MPI_Comm comm, int num_cubes); +t8_locidx_t t8_forest_get_num_ghosts (const t8_forest_t forest); ``` """ -function t8_cmesh_new_long_brick_pyramid(comm, num_cubes) - @ccall libt8.t8_cmesh_new_long_brick_pyramid(comm::MPI_Comm, num_cubes::Cint)::t8_cmesh_t +function t8_forest_get_num_ghosts(forest) + @ccall libt8.t8_forest_get_num_ghosts(forest::t8_forest_t)::t8_locidx_t end """ - t8_cmesh_new_row_of_cubes(num_trees, set_attributes, do_partition, comm, package_id) + t8_forest_get_eclass(forest, ltreeid) + +Return the element class of a forest local tree. +# Arguments +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The local id of a tree in *forest*. +# Returns +The element class of the tree *ltreeid*. *forest* must be committed before calling this function. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_row_of_cubes (t8_locidx_t num_trees, const int set_attributes, const int do_partition, sc_MPI_Comm comm, const int package_id); +t8_eclass_t t8_forest_get_eclass (const t8_forest_t forest, const t8_locidx_t ltreeid); ``` """ -function t8_cmesh_new_row_of_cubes(num_trees, set_attributes, do_partition, comm, package_id) - @ccall libt8.t8_cmesh_new_row_of_cubes(num_trees::t8_locidx_t, set_attributes::Cint, do_partition::Cint, comm::MPI_Comm, package_id::Cint)::t8_cmesh_t +function t8_forest_get_eclass(forest, ltreeid) + @ccall libt8.t8_forest_get_eclass(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_eclass_t end """ - t8_cmesh_new_quadrangulated_disk(radius, comm) + t8_forest_tree_is_local(forest, local_tree) + +Check whether a given tree id belongs to a local tree in a forest. +# Arguments +* `forest`:\\[in\\] The forest. +* `local_tree`:\\[in\\] A tree id. +# Returns +True if and only if the id *local_tree* belongs to a local tree of *forest*. *forest* must be committed before calling this function. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_quadrangulated_disk (const double radius, sc_MPI_Comm comm); +int t8_forest_tree_is_local (const t8_forest_t forest, const t8_locidx_t local_tree); ``` """ -function t8_cmesh_new_quadrangulated_disk(radius, comm) - @ccall libt8.t8_cmesh_new_quadrangulated_disk(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_tree_is_local(forest, local_tree) + @ccall libt8.t8_forest_tree_is_local(forest::t8_forest_t, local_tree::t8_locidx_t)::Cint end """ - t8_cmesh_new_triangulated_spherical_surface_octahedron(radius, comm) + t8_forest_get_local_id(forest, gtreeid) + +Given a global tree id compute the forest local id of this tree. If the tree is a local tree, then the local id is between 0 and the number of local trees. If the tree is not a local tree, a negative number is returned. + +# Arguments +* `forest`:\\[in\\] The forest. +* `gtreeid`:\\[in\\] The global id of a tree. +# Returns +The tree's local id in *forest*, if it is a local tree. A negative number if not. Ghosts trees are not considered as local. +# See also +[`t8_forest_get_local_or_ghost_id`](@ref) for ghost trees., https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_triangulated_spherical_surface_octahedron (const double radius, sc_MPI_Comm comm); +t8_locidx_t t8_forest_get_local_id (const t8_forest_t forest, const t8_gloidx_t gtreeid); ``` """ -function t8_cmesh_new_triangulated_spherical_surface_octahedron(radius, comm) - @ccall libt8.t8_cmesh_new_triangulated_spherical_surface_octahedron(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_get_local_id(forest, gtreeid) + @ccall libt8.t8_forest_get_local_id(forest::t8_forest_t, gtreeid::t8_gloidx_t)::t8_locidx_t end """ - t8_cmesh_new_triangulated_spherical_surface_icosahedron(radius, comm) + t8_forest_get_local_or_ghost_id(forest, gtreeid) + +Given a global tree id compute the forest local id of this tree. If the tree is a local tree, then the local id is between 0 and the number of local trees. If the tree is a ghost, then the local id is between num\\_local\\_trees and num\\_local\\_trees + num\\_ghost\\_trees. If the tree is neither a local tree nor a ghost tree, a negative number is returned. + +# Arguments +* `forest`:\\[in\\] The forest. +* `gtreeid`:\\[in\\] The global id of a tree. +# Returns +The tree's local id in *forest*, if it is a local tree. num\\_local\\_trees + the ghosts id, if it is a ghost tree. A negative number if not. +# See also +https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing ### Prototype ```c -t8_cmesh_t t8_cmesh_new_triangulated_spherical_surface_icosahedron (const double radius, sc_MPI_Comm comm); +t8_locidx_t t8_forest_get_local_or_ghost_id (const t8_forest_t forest, const t8_gloidx_t gtreeid); ``` """ -function t8_cmesh_new_triangulated_spherical_surface_icosahedron(radius, comm) - @ccall libt8.t8_cmesh_new_triangulated_spherical_surface_icosahedron(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_get_local_or_ghost_id(forest, gtreeid) + @ccall libt8.t8_forest_get_local_or_ghost_id(forest::t8_forest_t, gtreeid::t8_gloidx_t)::t8_locidx_t end """ - t8_cmesh_new_triangulated_spherical_surface_cube(radius, comm) + t8_forest_ltreeid_to_cmesh_ltreeid(forest, ltreeid) + +Given the local id of a tree in a forest, compute the tree's local id in the associated cmesh. + +!!! note + + For forest local trees, this is the inverse function of t8_forest_cmesh_ltreeid_to_ltreeid. + +# Arguments +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The local id of a tree or ghost in the forest. +# Returns +The local id of the tree in the cmesh associated with the forest. *forest* must be committed before calling this function. +# See also +https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_triangulated_spherical_surface_cube (const double radius, sc_MPI_Comm comm); +t8_locidx_t t8_forest_ltreeid_to_cmesh_ltreeid (t8_forest_t forest, t8_locidx_t ltreeid); ``` """ -function t8_cmesh_new_triangulated_spherical_surface_cube(radius, comm) - @ccall libt8.t8_cmesh_new_triangulated_spherical_surface_cube(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_ltreeid_to_cmesh_ltreeid(forest, ltreeid) + @ccall libt8.t8_forest_ltreeid_to_cmesh_ltreeid(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_locidx_t end """ - t8_cmesh_new_quadrangulated_spherical_surface(radius, comm) + t8_forest_cmesh_ltreeid_to_ltreeid(forest, lctreeid) + +Given the local id of a tree in the coarse mesh of a forest, compute the tree's local id in the forest. + +!!! note + + For forest local trees, this is the inverse function of t8_forest_ltreeid_to_cmesh_ltreeid. + +# Arguments +* `forest`:\\[in\\] The forest. +* `lctreeid`:\\[in\\] The local id of a tree in the coarse mesh of *forest*. +# Returns +The local id of the tree in the forest. -1 if the tree is not forest local. *forest* must be committed before calling this function. +# See also +https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_quadrangulated_spherical_surface (const double radius, sc_MPI_Comm comm); +t8_locidx_t t8_forest_cmesh_ltreeid_to_ltreeid (t8_forest_t forest, t8_locidx_t lctreeid); ``` """ -function t8_cmesh_new_quadrangulated_spherical_surface(radius, comm) - @ccall libt8.t8_cmesh_new_quadrangulated_spherical_surface(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_cmesh_ltreeid_to_ltreeid(forest, lctreeid) + @ccall libt8.t8_forest_cmesh_ltreeid_to_ltreeid(forest::t8_forest_t, lctreeid::t8_locidx_t)::t8_locidx_t end """ - t8_cmesh_new_prismed_spherical_shell_octahedron(inner_radius, shell_thickness, num_levels, num_layers, comm) + t8_forest_get_coarse_tree(forest, ltreeid) + +Given the local id of a tree in a forest, return the coarse tree of the cmesh that corresponds to this tree. +# Arguments +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The local id of a tree in the forest. +# Returns +The coarse tree that matches the forest tree with local id *ltreeid*. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_prismed_spherical_shell_octahedron (const double inner_radius, const double shell_thickness, const int num_levels, const int num_layers, sc_MPI_Comm comm); +t8_ctree_t t8_forest_get_coarse_tree (t8_forest_t forest, t8_locidx_t ltreeid); ``` """ -function t8_cmesh_new_prismed_spherical_shell_octahedron(inner_radius, shell_thickness, num_levels, num_layers, comm) - @ccall libt8.t8_cmesh_new_prismed_spherical_shell_octahedron(inner_radius::Cdouble, shell_thickness::Cdouble, num_levels::Cint, num_layers::Cint, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_get_coarse_tree(forest, ltreeid) + @ccall libt8.t8_forest_get_coarse_tree(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_ctree_t end """ - t8_cmesh_new_prismed_spherical_shell_icosahedron(inner_radius, shell_thickness, num_levels, num_layers, comm) + t8_forest_element_is_leaf(forest, element, local_tree) + +Query whether a given element is a leaf in a forest. + +!!! note + + This does not query for ghost leaves. + +!!! note + *forest* must be committed before calling this function. + +# Arguments +* `forest`:\\[in\\] The forest. +* `element`:\\[in\\] An element of a local tree in *forest*. +* `local_tree`:\\[in\\] A local tree id of *forest*. +# Returns +True (non-zero) if and only if *element* is a leaf in *local_tree* of *forest*. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_prismed_spherical_shell_icosahedron (const double inner_radius, const double shell_thickness, const int num_levels, const int num_layers, sc_MPI_Comm comm); +int t8_forest_element_is_leaf (const t8_forest_t forest, const t8_element_t *element, const t8_locidx_t local_tree); ``` """ -function t8_cmesh_new_prismed_spherical_shell_icosahedron(inner_radius, shell_thickness, num_levels, num_layers, comm) - @ccall libt8.t8_cmesh_new_prismed_spherical_shell_icosahedron(inner_radius::Cdouble, shell_thickness::Cdouble, num_levels::Cint, num_layers::Cint, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_element_is_leaf(forest, element, local_tree) + @ccall libt8.t8_forest_element_is_leaf(forest::t8_forest_t, element::Ptr{t8_element_t}, local_tree::t8_locidx_t)::Cint end """ - t8_cmesh_new_cubed_spherical_shell(inner_radius, shell_thickness, num_trees, num_layers, comm) + t8_forest_element_is_leaf_or_ghost(forest, element, local_tree, check_ghost) +Query whether a given element or a ghost is a leaf of a local or ghost tree in a forest. + +!!! note + + *forest* must be committed before calling this function. t8_forest_element_is_leaf t8_forest_element_is_ghost + +# Arguments +* `forest`:\\[in\\] The forest. +* `element`:\\[in\\] An element of a local tree in *forest*. +* `local_tree`:\\[in\\] A local tree id of *forest* or a ghost tree id +* `check_ghost`:\\[in\\] If true *element* is interpreted as a ghost element and *local_tree* as the id of a ghost tree (0 <= *local_tree* < num\\_ghost\\_trees). If false *element* is interpreted as an element and *local_tree* as the id of a local tree (0 <= *local_tree* < num\\_local\\_trees). +# Returns +True (non-zero) if and only if *element* is a leaf (or ghost) in *local_tree* of *forest*. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_cubed_spherical_shell (const double inner_radius, const double shell_thickness, const int num_trees, const int num_layers, sc_MPI_Comm comm); +int t8_forest_element_is_leaf_or_ghost (const t8_forest_t forest, const t8_element_t *element, const t8_locidx_t local_tree, const int check_ghost); ``` """ -function t8_cmesh_new_cubed_spherical_shell(inner_radius, shell_thickness, num_trees, num_layers, comm) - @ccall libt8.t8_cmesh_new_cubed_spherical_shell(inner_radius::Cdouble, shell_thickness::Cdouble, num_trees::Cint, num_layers::Cint, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_element_is_leaf_or_ghost(forest, element, local_tree, check_ghost) + @ccall libt8.t8_forest_element_is_leaf_or_ghost(forest::t8_forest_t, element::Ptr{t8_element_t}, local_tree::t8_locidx_t, check_ghost::Cint)::Cint end """ - t8_cmesh_new_cubed_sphere(radius, comm) + t8_forest_leaf_face_orientation(forest, ltreeid, scheme, leaf, face) + +Compute the leaf face orientation at given face in a forest. + +For more information about the encoding of face orientation refer to t8_cmesh_get_face_neighbor. +# Arguments +* `forest`:\\[in\\] The forest. Must have a valid ghost layer. +* `ltreeid`:\\[in\\] A local tree id. +* `scheme`:\\[in\\] The eclass scheme of the element. +* `leaf`:\\[in\\] A leaf in tree *ltreeid* of *forest*. +* `face`:\\[in\\] The index of the face across which the face neighbors are searched. +# Returns +Face orientation encoded as integer. ### Prototype ```c -t8_cmesh_t t8_cmesh_new_cubed_sphere (const double radius, sc_MPI_Comm comm); +int t8_forest_leaf_face_orientation (t8_forest_t forest, const t8_locidx_t ltreeid, const t8_scheme_c *scheme, const t8_element_t *leaf, const int face); ``` """ -function t8_cmesh_new_cubed_sphere(radius, comm) - @ccall libt8.t8_cmesh_new_cubed_sphere(radius::Cdouble, comm::MPI_Comm)::t8_cmesh_t +function t8_forest_leaf_face_orientation(forest, ltreeid, scheme, leaf, face) + @ccall libt8.t8_forest_leaf_face_orientation(forest::t8_forest_t, ltreeid::t8_locidx_t, scheme::Ptr{t8_scheme_c}, leaf::Ptr{t8_element_t}, face::Cint)::Cint end """ - t8_cmesh_set_join_by_vertices(cmesh, ntrees, eclasses, vertices, connectivity, do_both_directions) + t8_forest_leaf_face_neighbors(forest, ltreeid, leaf, pneighbor_leaves, face, dual_faces, num_neighbors, pelement_indices, pneigh_eclass) -Sets the face connectivity information of an un-committed cmesh based on a list of tree vertices. +Compute the leaf face neighbors of a forest leaf element or ghost leaf. -!!! warning +!!! note - This routine might be too expensive for very large meshes. In this case, consider to use a fully featured mesh generator. + If there are no face neighbors, then *pneighbor\\_leaves = NULL, num\\_neighbors = 0, and *pelement\\_indices = NULL on output. !!! note - This routine does not detect periodic boundaries. + *forest* must be committed before calling this function. + +!!! note + + If *forest* does not have a ghost layer then leaf elements at the process boundaries have 0 neighbors along the boundary face. (The function output for leaf elements then depends on the parallel partition.) + +!!! note + + Important! This routine allocates memory which must be freed. Do it like this: + +if (num\\_neighbors > 0) { [`T8_FREE`](@ref) (pneighbor\\_leaves); [`T8_FREE`](@ref) (pelement\\_indices); [`T8_FREE`](@ref) (dual\\_faces); } # Arguments -* `cmesh`:\\[in,out\\] Pointer to a t8code cmesh object. If set to NULL this argument is ignored. -* `ntrees`:\\[in\\] Number of coarse mesh elements resp. trees. -* `vertices`:\\[in\\] List of per element vertices with dimensions [ntrees,[`T8_ECLASS_MAX_CORNERS`](@ref),[`T8_ECLASS_MAX_DIM`](@ref)]. -* `eclasses`:\\[in\\] List of element classes of length [ntrees]. -* `connectivity`:\\[in,out\\] If connectivity is not NULL the variable is filled with a pointer to an allocated face connectivity array. The ownership of this array goes to the caller. This argument is mainly used for debugging and testing purposes. The dimension of *connectivity* are [ntrees,[`T8_ECLASS_MAX_FACES`](@ref),3]. For each element and each face the following is stored: neighbor\\_tree\\_id, neighbor\\_dual\\_face\\_id, orientation -* `do_both_directions`:\\[in\\] Compute the connectivity from both neighboring sides. Takes much longer to compute. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] A local tree id (could also be a ghost tree). 0 <= *ltreeid* < num\\_local trees+num\\_ghost\\_trees +* `leaf`:\\[in\\] A leaf in tree *ltreeid* of *forest*. +* `pneighbor_leaves`:\\[out\\] Unallocated on input. On output the neighbor leaves are stored here. +* `face`:\\[in\\] The index of the face across which the face neighbors are searched. +* `dual_faces`:\\[out\\] On output the face id's of the neighboring elements' faces. +* `num_neighbors`:\\[out\\] On output the number of neighbor leaves. +* `pelement_indices`:\\[out\\] Unallocated on input. On output the element indices of the neighbor leaves are stored here. 0, 1, ... num\\_local\\_el - 1 for local leaves and num\\_local\\_el , ... , num\\_local\\_el + num\\_ghosts - 1 for ghosts. +* `pneigh_eclass`:\\[out\\] On output the eclass of the neighbor elements. ### Prototype ```c -void t8_cmesh_set_join_by_vertices (t8_cmesh_t cmesh, const t8_gloidx_t ntrees, const t8_eclass_t *eclasses, const double *vertices, int **connectivity, const int do_both_directions); +void t8_forest_leaf_face_neighbors (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *leaf, const t8_element_t **pneighbor_leaves[], const int face, int *dual_faces[], int *num_neighbors, t8_locidx_t **pelement_indices, t8_eclass_t *pneigh_eclass); ``` """ -function t8_cmesh_set_join_by_vertices(cmesh, ntrees, eclasses, vertices, connectivity, do_both_directions) - @ccall libt8.t8_cmesh_set_join_by_vertices(cmesh::t8_cmesh_t, ntrees::t8_gloidx_t, eclasses::Ptr{t8_eclass_t}, vertices::Ptr{Cdouble}, connectivity::Ptr{Ptr{Cint}}, do_both_directions::Cint)::Cvoid +function t8_forest_leaf_face_neighbors(forest, ltreeid, leaf, pneighbor_leaves, face, dual_faces, num_neighbors, pelement_indices, pneigh_eclass) + @ccall libt8.t8_forest_leaf_face_neighbors(forest::t8_forest_t, ltreeid::t8_locidx_t, leaf::Ptr{t8_element_t}, pneighbor_leaves::Ptr{Ptr{Ptr{t8_element_t}}}, face::Cint, dual_faces::Ptr{Ptr{Cint}}, num_neighbors::Ptr{Cint}, pelement_indices::Ptr{Ptr{t8_locidx_t}}, pneigh_eclass::Ptr{t8_eclass_t})::Cvoid end """ - t8_cmesh_set_join_by_stash(cmesh, connectivity, do_both_directions) + t8_forest_leaf_face_neighbors_ext(forest, ltreeid, leaf_or_ghost, pneighbor_leaves, face, dual_faces, num_neighbors, pelement_indices, pneigh_eclass, gneigh_tree, orientation) -Sets the face connectivity information of an un-committed cmesh based on the cmesh stash. +Like t8_forest_leaf_face_neighbors but also provides information about the global neighbors and the orientation. -!!! warning +!!! note - This routine might be too expensive for very large meshes. In this case, consider to use a fully featured mesh generator. + If there are no face neighbors, then *pneighbor\\_leaves = NULL, num\\_neighbors = 0, and *pelement\\_indices = NULL on output. !!! note - This routine does not detect periodic boundaries. + *forest* must be committed before calling this function. + +!!! note + + Important! This routine allocates memory which must be freed. Do it like this: + +if (num\\_neighbors > 0) { [`T8_FREE`](@ref) (pneighbor\\_leaves); [`T8_FREE`](@ref) (pelement\\_indices); [`T8_FREE`](@ref) (dual\\_faces); } # Arguments -* `cmesh`:\\[in,out\\] An uncommitted cmesh. The trees eclasses and vertices do need to be set. -* `connectivity`:\\[in,out\\] If connectivity is not NULL the variable is filled with a pointer to an allocated face connectivity array. The ownership of this array goes to the caller. This argument is mainly used for debugging and testing purposes. The dimension of *connectivity* are [ntrees,[`T8_ECLASS_MAX_FACES`](@ref),3]. For each element and each face the following is stored: neighbor\\_tree\\_id, neighbor\\_dual\\_face\\_id, orientation -* `do_both_directions`:\\[in\\] Compute the connectivity from both neighboring sides. Takes much longer to compute. +* `forest`:\\[in\\] The forest. Must have a valid ghost layer. +* `ltreeid`:\\[in\\] A local tree id (could also be a ghost tree). 0 <= *ltreeid* < num\\_local trees+num\\_ghost\\_trees +* `leaf_or_ghost`:\\[in\\] A leaf or ghost leaf element in tree *ltreeid* of *forest*. +* `pneighbor_leaves`:\\[out\\] Unallocated on input. On output the neighbor leaves are stored here. +* `face`:\\[in\\] The index of the face across which the face neighbors are searched. +* `dual_faces`:\\[out\\] On output the face id's of the neighboring elements' faces. +* `num_neighbors`:\\[out\\] On output the number of neighbor leaves. +* `pelement_indices`:\\[out\\] Unallocated on input. On output the element indices of the neighbor leaves are stored here. 0, 1, ... num\\_local\\_el - 1 for local leaves and num\\_local\\_el , ... , num\\_local\\_el + num\\_ghosts - 1 for ghosts. +* `pneigh_eclass`:\\[out\\] On output the eclass of the neighbor elements. +* `gneigh_tree`:\\[out\\] The global tree IDs of the neighbor trees. +* `orientation`:\\[out\\] 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 t8_forest_leaf_face_neighbors. ### Prototype ```c -void t8_cmesh_set_join_by_stash (t8_cmesh_t cmesh, int **connectivity, const int do_both_directions); +void t8_forest_leaf_face_neighbors_ext (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *leaf_or_ghost, const t8_element_t **pneighbor_leaves[], const int face, int *dual_faces[], int *num_neighbors, t8_locidx_t **pelement_indices, t8_eclass_t *pneigh_eclass, t8_gloidx_t *gneigh_tree, int *orientation); ``` """ -function t8_cmesh_set_join_by_stash(cmesh, connectivity, do_both_directions) - @ccall libt8.t8_cmesh_set_join_by_stash(cmesh::t8_cmesh_t, connectivity::Ptr{Ptr{Cint}}, do_both_directions::Cint)::Cvoid +function t8_forest_leaf_face_neighbors_ext(forest, ltreeid, leaf_or_ghost, pneighbor_leaves, face, dual_faces, num_neighbors, pelement_indices, pneigh_eclass, gneigh_tree, orientation) + @ccall libt8.t8_forest_leaf_face_neighbors_ext(forest::t8_forest_t, ltreeid::t8_locidx_t, leaf_or_ghost::Ptr{t8_element_t}, pneighbor_leaves::Ptr{Ptr{Ptr{t8_element_t}}}, face::Cint, dual_faces::Ptr{Ptr{Cint}}, num_neighbors::Ptr{Cint}, pelement_indices::Ptr{Ptr{t8_locidx_t}}, pneigh_eclass::Ptr{t8_eclass_t}, gneigh_tree::Ptr{t8_gloidx_t}, orientation::Ptr{Cint})::Cvoid end """ - t8_element_array_t + t8_forest_same_level_leaf_face_neighbor_index(forest, element_index, face_index, global_treeid, dual_face) -The [`t8_element_array_t`](@ref) is an array to store [`t8_element_t`](@ref) * of a given eclass\\_scheme implementation. It is a wrapper around [`sc_array_t`](@ref). Each time, a new element is created by the functions for t8_element_array_t, the eclass function either t8_element_new or t8_element_init is called for the element. Thus, each element in a t8_element_array_t is automatically initialized properly. +Given a leaf element or ghost index in "all local elements + ghosts" enumeration compute the index of the face neighbor of the element - provided that only one or no face neighbors exists. HANDLE WITH CARE. DO NOT CALL IF THE FOREST IS NOT UNIFORM. -| Field | Note | -| :----------- | :----------------------------------------------------- | -| scheme | The scheme of which elements should be stored. | -| tree\\_class | !< A scheme of which elements should be stored | -| array | !< The tree class of the elements stored in the array | -""" -struct t8_element_array_t - scheme::Ptr{t8_scheme_c} - tree_class::t8_eclass_t - array::sc_array_t +!!! note + + Do not call if you are unsure about the number of face neighbors. In particular if the forest is not uniform. + +# Arguments +* `forest`:\\[in\\] The forest. Must be committed. +* `element_index`:\\[in\\] Index of an element in *forest*. Must have only one or no facen neighbors across the given face. 0 <= *element_index* < num\\_local\\_elements + num\\_ghosts +* `face_index`:\\[in\\] Index of a face of *element*. +* `global_treeid`:\\[in\\] Global index of the tree that contains *element*. +* `dual_face`:\\[out\\] Return value, the dual\\_face index of the face neighbor. +# Returns +The index of the face neighbor leaf (local element or ghost). +### Prototype +```c +t8_locidx_t t8_forest_same_level_leaf_face_neighbor_index (const t8_forest_t forest, const t8_locidx_t element_index, const int face_index, const t8_gloidx_t global_treeid, int *dual_face); +``` +""" +function t8_forest_same_level_leaf_face_neighbor_index(forest, element_index, face_index, global_treeid, dual_face) + @ccall libt8.t8_forest_same_level_leaf_face_neighbor_index(forest::t8_forest_t, element_index::t8_locidx_t, face_index::Cint, global_treeid::t8_gloidx_t, dual_face::Ptr{Cint})::t8_locidx_t end """ - t8_element_array_new(scheme, tree_class) + t8_forest_leaf_neighbor_subface(forest, ltreeid, leaf, face, neighbor_tree_class, neighbor_leaf, neighbor_face) -Creates a new array structure with 0 elements. +Compute the subface index for a coarser neighbor + +\\pre *leaf* and *neighbor_leaf* must be a face neighbors. The common face must correspond to *face* for *leaf* and *neighbor_face* for *neighbor_leaf* respectively. *neighbor_leaf* must be one level coarser than *leaf*. Otherwise the behavior is undefined. + +!!! note + + This function is designed to be called after t8_forest_leaf_face_neighbors_ext to complement its output. It is primarily intended for balanced forests, but can be used on any committed forest as long as the preconditions hold (i.e. the forest must be ''locally balanced''). # Arguments -* `scheme`:\\[in\\] The eclass scheme of which elements should be stored. -* `tree_class`:\\[in\\] The tree class of the elements stored in the array. +* `forest`:\\[in\\] The forest. Must be committed. +* `ltreeid`:\\[in\\] A local tree id. +* `leaf`:\\[in\\] A leaf in *ltreeid*. +* `face`:\\[in\\] The face index of *leaf* to consider. +* `neighbor_tree_class`:\\[in\\] The eclass of the neighbor element. +* `neighbor_leaf`:\\[in\\] The leaf of *forest* on the other side of the face of index *face* of element *leaf*. +* `neighbor_face`:\\[in\\] The face index of *neighbor_leaf* (i.e. the dual face of *face*). # Returns -Return an allocated array of zero length. +The index of the subface of *neighbor_face* which corresponds to *face*. ### Prototype ```c -t8_element_array_t * t8_element_array_new (const t8_scheme_c *scheme, const t8_eclass_t tree_class); +int t8_forest_leaf_neighbor_subface (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *leaf, int face, t8_eclass_t neighbor_tree_class, const t8_element_t *neighbor_leaf, int neighbor_face); ``` """ -function t8_element_array_new(scheme, tree_class) - @ccall libt8.t8_element_array_new(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Ptr{t8_element_array_t} +function t8_forest_leaf_neighbor_subface(forest, ltreeid, leaf, face, neighbor_tree_class, neighbor_leaf, neighbor_face) + @ccall libt8.t8_forest_leaf_neighbor_subface(forest::t8_forest_t, ltreeid::t8_locidx_t, leaf::Ptr{t8_element_t}, face::Cint, neighbor_tree_class::t8_eclass_t, neighbor_leaf::Ptr{t8_element_t}, neighbor_face::Cint)::Cint end """ - t8_element_array_new_count(scheme, tree_class, num_elements) + t8_forest_ghost_exchange_data(forest, element_data) -Creates a new array structure with a given length (number of elements) and calls t8_element_new for those elements. +Exchange ghost information of user defined element data. + +!!! note + + This function is collective and hence must be called by all processes in the forest's MPI Communicator. # Arguments -* `scheme`:\\[in\\] The eclass scheme of which elements should be stored. -* `tree_class`:\\[in\\] The tree class of the elements stored in the array. -* `num_elements`:\\[in\\] Initial number of array elements. -# Returns -Return an allocated array with allocated and initialized elements for which t8_element_new was called. +* `forest`:\\[in\\] The forest. Must be committed. +* `element_data`:\\[in\\] An array of length num\\_local\\_elements + num\\_ghosts storing one value for each local element and ghost in *forest*. After calling this function the entries for the ghost elements are update with the entries in the *element_data* array of the corresponding owning process. ### Prototype ```c -t8_element_array_t * t8_element_array_new_count (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const size_t num_elements); +void t8_forest_ghost_exchange_data (t8_forest_t forest, sc_array_t *element_data); ``` """ -function t8_element_array_new_count(scheme, tree_class, num_elements) - @ccall libt8.t8_element_array_new_count(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, num_elements::Csize_t)::Ptr{t8_element_array_t} +function t8_forest_ghost_exchange_data(forest, element_data) + @ccall libt8.t8_forest_ghost_exchange_data(forest::t8_forest_t, element_data::Ptr{sc_array_t})::Cvoid end """ - t8_element_array_init(element_array, scheme, tree_class) + t8_forest_ghost_print(forest) -Initializes an already allocated (or static) array structure. +Print the ghost structure of a forest. Only used for debugging. -# Arguments -* `element_array`:\\[in,out\\] Array structure to be initialized. -* `scheme`:\\[in\\] The eclass scheme of which elements should be stored. -* `tree_class`:\\[in\\] The tree class of the elements stored in the array. ### Prototype ```c -void t8_element_array_init (t8_element_array_t *element_array, const t8_scheme_c *scheme, const t8_eclass_t tree_class); +void t8_forest_ghost_print (t8_forest_t forest); ``` """ -function t8_element_array_init(element_array, scheme, tree_class) - @ccall libt8.t8_element_array_init(element_array::Ptr{t8_element_array_t}, scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Cvoid +function t8_forest_ghost_print(forest) + @ccall libt8.t8_forest_ghost_print(forest::t8_forest_t)::Cvoid end """ - t8_element_array_init_size(element_array, scheme, tree_class, num_elements) - -Initializes an already allocated (or static) array structure and allocates a given number of elements and initializes them with t8_element_init. + t8_forest_partition_cmesh(forest, comm, set_profiling) -# Arguments -* `element_array`:\\[in,out\\] Array structure to be initialized. -* `scheme`:\\[in\\] The eclass scheme of which elements should be stored. -* `tree_class`:\\[in\\] The tree class of the elements stored in the array. -* `num_elements`:\\[in\\] Number of initial array elements. ### Prototype ```c -void t8_element_array_init_size (t8_element_array_t *element_array, const t8_scheme_c *scheme, const t8_eclass_t tree_class, const size_t num_elements); +void t8_forest_partition_cmesh (t8_forest_t forest, sc_MPI_Comm comm, int set_profiling); ``` """ -function t8_element_array_init_size(element_array, scheme, tree_class, num_elements) - @ccall libt8.t8_element_array_init_size(element_array::Ptr{t8_element_array_t}, scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, num_elements::Csize_t)::Cvoid +function t8_forest_partition_cmesh(forest, comm, set_profiling) + @ccall libt8.t8_forest_partition_cmesh(forest::t8_forest_t, comm::MPI_Comm, set_profiling::Cint)::Cvoid end """ - t8_element_array_init_view(view, array, offset, length) - -Initializes an already allocated (or static) view from existing t8\\_element\\_array. The array view returned does not require [`t8_element_array_reset`](@ref) (doesn't hurt though). + t8_forest_get_mpicomm(forest) -# Arguments -* `view`:\\[in,out\\] Array structure to be initialized. -* `array`:\\[in\\] The array must not be resized while view is alive. -* `offset`:\\[in\\] The offset of the viewed section in element units. This offset cannot be changed until the view is reset. -* `length`:\\[in\\] The length of the view in element units. The view cannot be resized to exceed this length. It is not necessary to call [`sc_array_reset`](@ref) later. ### Prototype ```c -void t8_element_array_init_view (t8_element_array_t *view, const t8_element_array_t *array, const size_t offset, const size_t length); +sc_MPI_Comm t8_forest_get_mpicomm (const t8_forest_t forest); ``` """ -function t8_element_array_init_view(view, array, offset, length) - @ccall libt8.t8_element_array_init_view(view::Ptr{t8_element_array_t}, array::Ptr{t8_element_array_t}, offset::Csize_t, length::Csize_t)::Cvoid +function t8_forest_get_mpicomm(forest) + @ccall libt8.t8_forest_get_mpicomm(forest::t8_forest_t)::MPI_Comm end -mutable struct t8_element end - -"""Opaque structure for a generic element, only used as pointer. Implementations are free to cast it to their internal data structure.""" -const t8_element_t = t8_element - """ - t8_element_array_init_data(view, base, scheme, tree_class, elem_count) + t8_forest_get_first_local_tree_id(forest) -Initializes an already allocated (or static) view from given plain C data (array of [`t8_element_t`](@ref)). The array view returned does not require [`t8_element_array_reset`](@ref) (doesn't hurt though). +Return the global id of the first local tree of a forest. # Arguments -* `view`:\\[in,out\\] Array structure to be initialized. -* `base`:\\[in\\] The data must not be moved while view is alive. Must be an array of [`t8_element_t`](@ref) corresponding to *scheme*. -* `scheme`:\\[in\\] The scheme of the elements stored in *base*. -* `tree_class`:\\[in\\] The tree class of the elements stored in *base*. -* `elem_count`:\\[in\\] The length of the view in element units. The view cannot be resized to exceed this length. It is not necessary to call [`t8_element_array_reset`](@ref) later. +* `forest`:\\[in\\] The forest. +# Returns +The global id of the first local tree in *forest*. ### Prototype ```c -void t8_element_array_init_data (t8_element_array_t *view, const t8_element_t *base, const t8_scheme_c *scheme, const t8_eclass_t tree_class, const size_t elem_count); +t8_gloidx_t t8_forest_get_first_local_tree_id (const t8_forest_t forest); ``` """ -function t8_element_array_init_data(view, base, scheme, tree_class, elem_count) - @ccall libt8.t8_element_array_init_data(view::Ptr{t8_element_array_t}, base::Ptr{t8_element_t}, scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem_count::Csize_t)::Cvoid +function t8_forest_get_first_local_tree_id(forest) + @ccall libt8.t8_forest_get_first_local_tree_id(forest::t8_forest_t)::t8_gloidx_t end """ - t8_element_array_init_copy(element_array, scheme, tree_class, data, num_elements) + t8_forest_get_num_local_trees(forest) -Initializes an already allocated (or static) array structure and copy an existing array of [`t8_element_t`](@ref) into it. +Return the number of local trees of a given forest. # Arguments -* `element_array`:\\[in,out\\] Array structure to be initialized. -* `scheme`:\\[in\\] The eclass scheme of which elements should be stored. -* `tree_class`:\\[in\\] The tree class of the elements stored in the array. -* `data`:\\[in\\] An array of [`t8_element_t`](@ref) which will be copied into *element_array*. The elements in *data* must belong to *scheme* and must be properly initialized with either t8_element_new or t8_element_init. -* `num_elements`:\\[in\\] Number of elements in *data* to be copied. +* `forest`:\\[in\\] The forest. +# Returns +The number of local trees of that forest. ### Prototype ```c -void t8_element_array_init_copy (t8_element_array_t *element_array, const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *data, const size_t num_elements); +t8_locidx_t t8_forest_get_num_local_trees (const t8_forest_t forest); ``` """ -function t8_element_array_init_copy(element_array, scheme, tree_class, data, num_elements) - @ccall libt8.t8_element_array_init_copy(element_array::Ptr{t8_element_array_t}, scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, data::Ptr{t8_element_t}, num_elements::Csize_t)::Cvoid +function t8_forest_get_num_local_trees(forest) + @ccall libt8.t8_forest_get_num_local_trees(forest::t8_forest_t)::t8_locidx_t end """ - t8_element_array_resize(element_array, new_count) - -Change the number of elements stored in an element array. - -!!! note + t8_forest_get_num_ghost_trees(forest) - If *new_count* is larger than the number of current elements on *element_array*, then t8_element_init is called for the new elements. +Return the number of ghost trees of a given forest. # Arguments -* `element_array`:\\[in,out\\] The element array to be modified. -* `new_count`:\\[in\\] The new element count of the array. If it is zero the effect equals t8_element_array_reset. +* `forest`:\\[in\\] The forest. +# Returns +The number of ghost trees of that forest. ### Prototype ```c -void t8_element_array_resize (t8_element_array_t *element_array, const size_t new_count); +t8_locidx_t t8_forest_get_num_ghost_trees (const t8_forest_t forest); ``` """ -function t8_element_array_resize(element_array, new_count) - @ccall libt8.t8_element_array_resize(element_array::Ptr{t8_element_array_t}, new_count::Csize_t)::Cvoid +function t8_forest_get_num_ghost_trees(forest) + @ccall libt8.t8_forest_get_num_ghost_trees(forest::t8_forest_t)::t8_locidx_t end """ - t8_element_array_copy(dest, src) + t8_forest_get_num_global_trees(forest) -Copy the contents of an array into another. Both arrays must have the same eclass\\_scheme. +Return the number of global trees of a given forest. # Arguments -* `dest`:\\[in\\] Array will be resized and get new data. -* `src`:\\[in\\] Array used as source of new data, will not be changed. +* `forest`:\\[in\\] The forest. +# Returns +The number of global trees of that forest. ### Prototype ```c -void t8_element_array_copy (t8_element_array_t *dest, const t8_element_array_t *src); +t8_gloidx_t t8_forest_get_num_global_trees (const t8_forest_t forest); ``` """ -function t8_element_array_copy(dest, src) - @ccall libt8.t8_element_array_copy(dest::Ptr{t8_element_array_t}, src::Ptr{t8_element_array_t})::Cvoid +function t8_forest_get_num_global_trees(forest) + @ccall libt8.t8_forest_get_num_global_trees(forest::t8_forest_t)::t8_gloidx_t end """ - t8_element_array_push(element_array) + t8_forest_global_tree_id(forest, ltreeid) -Enlarge an array by one element. +Return the global id of a local tree or a ghost tree. # Arguments -* `element_array`:\\[in,out\\] Array structure to be modified. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] An id 0 <= *ltreeid* < num\\_local\\_trees + num\\_ghosts specifying a local tree or ghost tree. # Returns -Returns a pointer to a newly added element for which t8_element_init was called. +The global id corresponding to the tree with local id *ltreeid*. *forest* must be committed before calling this function. +# See also +https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. + ### Prototype ```c -t8_element_t * t8_element_array_push (t8_element_array_t *element_array); +t8_gloidx_t t8_forest_global_tree_id (const t8_forest_t forest, const t8_locidx_t ltreeid); ``` """ -function t8_element_array_push(element_array) - @ccall libt8.t8_element_array_push(element_array::Ptr{t8_element_array_t})::Ptr{t8_element_t} +function t8_forest_global_tree_id(forest, ltreeid) + @ccall libt8.t8_forest_global_tree_id(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_gloidx_t end """ - t8_element_array_push_count(element_array, count) + t8_forest_get_tree(forest, ltree_id) -Enlarge an array by a number of elements. +Return a pointer to a tree in a forest. # Arguments -* `element_array`:\\[in,out\\] Array structure to be modified. -* `count`:\\[in\\] The number of elements to add. +* `forest`:\\[in\\] The forest. +* `ltree_id`:\\[in\\] The local id of the tree. # Returns -Returns a pointer to the newly added elements for which t8_element_init was called. +A pointer to the tree with local id *ltree_id*. *forest* must be committed before calling this function. ### Prototype ```c -t8_element_t * t8_element_array_push_count (t8_element_array_t *element_array, size_t count); +t8_tree_t t8_forest_get_tree (const t8_forest_t forest, const t8_locidx_t ltree_id); ``` """ -function t8_element_array_push_count(element_array, count) - @ccall libt8.t8_element_array_push_count(element_array::Ptr{t8_element_array_t}, count::Csize_t)::Ptr{t8_element_t} +function t8_forest_get_tree(forest, ltree_id) + @ccall libt8.t8_forest_get_tree(forest::t8_forest_t, ltree_id::t8_locidx_t)::t8_tree_t end """ - t8_element_array_index_locidx(element_array, index) + t8_forest_get_tree_vertices(forest, ltreeid) -Return a given element in an array. Const version. +Return a pointer to the vertex coordinates of a tree. # Arguments -* `element_array`:\\[in\\] Array of elements. -* `index`:\\[in\\] The index of an element within the array. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The id of a local tree. # Returns -A pointer to the element stored at position *index* in *element_array*. +If stored, a pointer to the vertex coordinates of *tree*. If no coordinates for this tree are found, NULL. ### Prototype ```c -const t8_element_t * t8_element_array_index_locidx (const t8_element_array_t *element_array, const t8_locidx_t index); +double * t8_forest_get_tree_vertices (t8_forest_t forest, t8_locidx_t ltreeid); ``` """ -function t8_element_array_index_locidx(element_array, index) - @ccall libt8.t8_element_array_index_locidx(element_array::Ptr{t8_element_array_t}, index::t8_locidx_t)::Ptr{t8_element_t} +function t8_forest_get_tree_vertices(forest, ltreeid) + @ccall libt8.t8_forest_get_tree_vertices(forest::t8_forest_t, ltreeid::t8_locidx_t)::Ptr{Cdouble} end """ - t8_element_array_index_int(element_array, index) + t8_forest_tree_get_leaf_elements(forest, ltree_id) -Return a given element in an array. Const version. +Return the array of leaf elements of a local tree in a forest. # Arguments -* `element_array`:\\[in\\] Array of elements. -* `index`:\\[in\\] The index of an element within the array. +* `forest`:\\[in\\] The forest. +* `ltree_id`:\\[in\\] The local id of a local tree of *forest*. # Returns -A pointer to the element stored at position *index* in *element_array*. +An array of [`t8_element_t`](@ref) * storing all leaf elements of this tree. ### Prototype ```c -const t8_element_t * t8_element_array_index_int (const t8_element_array_t *element_array, const int index); +t8_element_array_t * t8_forest_tree_get_leaf_elements (const t8_forest_t forest, const t8_locidx_t ltree_id); ``` """ -function t8_element_array_index_int(element_array, index) - @ccall libt8.t8_element_array_index_int(element_array::Ptr{t8_element_array_t}, index::Cint)::Ptr{t8_element_t} +function t8_forest_tree_get_leaf_elements(forest, ltree_id) + @ccall libt8.t8_forest_tree_get_leaf_elements(forest::t8_forest_t, ltree_id::t8_locidx_t)::Ptr{t8_element_array_t} end """ - t8_element_array_index_locidx_mutable(element_array, index) + t8_forest_get_cmesh(forest) -Return a given element in an array. Mutable version. +Return a cmesh associated to a forest. # Arguments -* `element_array`:\\[in\\] Array of elements. -* `index`:\\[in\\] The index of an element within the array. +* `forest`:\\[in\\] The forest. # Returns -A pointer to the element stored at position *index* in *element_array*. +The cmesh associated to the forest. ### Prototype ```c -t8_element_t * t8_element_array_index_locidx_mutable (t8_element_array_t *element_array, const t8_locidx_t index); +t8_cmesh_t t8_forest_get_cmesh (t8_forest_t forest); ``` """ -function t8_element_array_index_locidx_mutable(element_array, index) - @ccall libt8.t8_element_array_index_locidx_mutable(element_array::Ptr{t8_element_array_t}, index::t8_locidx_t)::Ptr{t8_element_t} +function t8_forest_get_cmesh(forest) + @ccall libt8.t8_forest_get_cmesh(forest::t8_forest_t)::t8_cmesh_t end -""" - t8_element_array_index_int_mutable(element_array, index) +""" + t8_forest_get_leaf_element(forest, lelement_id, ltreeid) + +Return a leaf element of the forest. -Return a given element in an array. Mutable version. +!!! note + + This function performs a binary search. For constant access, use t8_forest_get_leaf_element_in_tree *forest* must be committed before calling this function. # Arguments -* `element_array`:\\[in\\] Array of elements. -* `index`:\\[in\\] The index of an element within the array. +* `forest`:\\[in\\] The forest. +* `lelement_id`:\\[in\\] The local id of a leaf element in *forest*. +* `ltreeid`:\\[out\\] If not NULL, on output the local tree id of the tree in which the leaf element lies in. # Returns -A pointer to the element stored at position *index* in *element_array*. +A pointer to the leaf element. NULL if this element does not exist. Ghost elements are not considered as local. +# See also +[`t8_forest_ghost_get_leaf_element`](@ref) to access ghost leaf elements. + ### Prototype ```c -t8_element_t * t8_element_array_index_int_mutable (t8_element_array_t *element_array, const int index); +t8_element_t * t8_forest_get_leaf_element (t8_forest_t forest, t8_locidx_t lelement_id, t8_locidx_t *ltreeid); ``` """ -function t8_element_array_index_int_mutable(element_array, index) - @ccall libt8.t8_element_array_index_int_mutable(element_array::Ptr{t8_element_array_t}, index::Cint)::Ptr{t8_element_t} +function t8_forest_get_leaf_element(forest, lelement_id, ltreeid) + @ccall libt8.t8_forest_get_leaf_element(forest::t8_forest_t, lelement_id::t8_locidx_t, ltreeid::Ptr{t8_locidx_t})::Ptr{t8_element_t} end """ - t8_element_array_get_scheme(element_array) + t8_forest_get_leaf_element_in_tree(forest, ltreeid, leid_in_tree) -Return the eclass scheme associated to a t8\\_element\\_array. +Return a leaf element of a local tree in a forest. + +!!! note + + If the tree id is know, this function should be preferred over t8_forest_get_leaf_element. *forest* must be committed before calling this function. # Arguments -* `element_array`:\\[in\\] Array of elements. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] An id of a local tree in the forest. Ghost trees are not considered local. +* `leid_in_tree`:\\[in\\] The index of a leaf element in the tree. # Returns -The eclass scheme stored at *element_array*. +A pointer to the leaf element. +# See also +t8\\_forest\\_ghost\\_get\\_leaf\\_element\\_in\\_tree to access ghost leaf elements. + ### Prototype ```c -const t8_scheme_c * t8_element_array_get_scheme (const t8_element_array_t *element_array); +const t8_element_t * t8_forest_get_leaf_element_in_tree (t8_forest_t forest, t8_locidx_t ltreeid, t8_locidx_t leid_in_tree); ``` """ -function t8_element_array_get_scheme(element_array) - @ccall libt8.t8_element_array_get_scheme(element_array::Ptr{t8_element_array_t})::Ptr{t8_scheme_c} +function t8_forest_get_leaf_element_in_tree(forest, ltreeid, leid_in_tree) + @ccall libt8.t8_forest_get_leaf_element_in_tree(forest::t8_forest_t, ltreeid::t8_locidx_t, leid_in_tree::t8_locidx_t)::Ptr{t8_element_t} end """ - t8_element_array_get_tree_class(element_array) + t8_forest_get_tree_num_leaf_elements(forest, ltreeid) -Return the tree class of the t8\\_element\\_array . +Return the number of leaf elements of a tree. # Arguments -* `element_array`:\\[in\\] Array of elements. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] A local id of a tree. # Returns -The tree class stored at *element_array*. +The number of leaf elements in the local tree *ltreeid*. ### Prototype ```c -t8_eclass_t t8_element_array_get_tree_class (const t8_element_array_t *element_array); +t8_locidx_t t8_forest_get_tree_num_leaf_elements (t8_forest_t forest, t8_locidx_t ltreeid); ``` """ -function t8_element_array_get_tree_class(element_array) - @ccall libt8.t8_element_array_get_tree_class(element_array::Ptr{t8_element_array_t})::t8_eclass_t +function t8_forest_get_tree_num_leaf_elements(forest, ltreeid) + @ccall libt8.t8_forest_get_tree_num_leaf_elements(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_locidx_t end """ - t8_element_array_get_count(element_array) + t8_forest_get_tree_element_offset(forest, ltreeid) -Return the number of elements stored in a [`t8_element_array_t`](@ref). +Return the element offset of a local tree, that is the number of leaf elements in all trees with smaller local treeid. + +!!! note + + *forest* must be committed before calling this function. # Arguments -* `element_array`:\\[in\\] Array structure. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] A local id of a tree. # Returns -The number of elements stored in *element_array*. +The number of leaf elements on all local tree with id < *ltreeid*. ### Prototype ```c -size_t t8_element_array_get_count (const t8_element_array_t *element_array); +t8_locidx_t t8_forest_get_tree_element_offset (const t8_forest_t forest, const t8_locidx_t ltreeid); ``` """ -function t8_element_array_get_count(element_array) - @ccall libt8.t8_element_array_get_count(element_array::Ptr{t8_element_array_t})::Csize_t +function t8_forest_get_tree_element_offset(forest, ltreeid) + @ccall libt8.t8_forest_get_tree_element_offset(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_locidx_t end """ - t8_element_array_get_size(element_array) + t8_forest_get_tree_leaf_element_count(tree) -Return the data size of elements stored in a [`t8_element_array_t`](@ref). +Return the number of leaf elements of a tree. # Arguments -* `element_array`:\\[in\\] Array structure. +* `tree`:\\[in\\] A tree in a forest. # Returns -The size (in bytes) of a single element in *element_array*. +The number of leaf elements of that tree. ### Prototype ```c -size_t t8_element_array_get_size (const t8_element_array_t *element_array); +t8_locidx_t t8_forest_get_tree_leaf_element_count (t8_tree_t tree); ``` """ -function t8_element_array_get_size(element_array) - @ccall libt8.t8_element_array_get_size(element_array::Ptr{t8_element_array_t})::Csize_t +function t8_forest_get_tree_leaf_element_count(tree) + @ccall libt8.t8_forest_get_tree_leaf_element_count(tree::t8_tree_t)::t8_locidx_t end """ - t8_element_array_get_data(element_array) + t8_forest_get_tree_class(forest, ltreeid) -Return a const pointer to the real data array stored in a t8\\_element\\_array. +Return the eclass of a tree in a forest. # Arguments -* `element_array`:\\[in\\] Array structure. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The local id of a tree (local or ghost) in *forest*. # Returns -A pointer to the stored data. If the number of stored elements is 0, then NULL is returned. +The element class of the tree with local id *ltreeid*. ### Prototype ```c -const t8_element_t * t8_element_array_get_data (const t8_element_array_t *element_array); +t8_eclass_t t8_forest_get_tree_class (const t8_forest_t forest, const t8_locidx_t ltreeid); ``` """ -function t8_element_array_get_data(element_array) - @ccall libt8.t8_element_array_get_data(element_array::Ptr{t8_element_array_t})::Ptr{t8_element_t} +function t8_forest_get_tree_class(forest, ltreeid) + @ccall libt8.t8_forest_get_tree_class(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_eclass_t end """ - t8_element_array_get_data_mutable(element_array) + t8_forest_get_first_local_leaf_element_id(forest) -Return a pointer to the real data array stored in a t8\\_element\\_array. +Compute the global index of the first local leaf element of a forest. This function is collective. # Arguments -* `element_array`:\\[in\\] Array structure. +* `forest`:\\[in\\] A committed forest, whose first leaf element's index is computed. # Returns -A pointer to the stored data. If the number of stored elements is 0, then NULL is returned. +The global index of *forest*'s first local leaf element. Forest must be committed when calling this function. This function is collective and must be called on each process. ### Prototype ```c -t8_element_t * t8_element_array_get_data_mutable (t8_element_array_t *element_array); +t8_gloidx_t t8_forest_get_first_local_leaf_element_id (t8_forest_t forest); ``` """ -function t8_element_array_get_data_mutable(element_array) - @ccall libt8.t8_element_array_get_data_mutable(element_array::Ptr{t8_element_array_t})::Ptr{t8_element_t} +function t8_forest_get_first_local_leaf_element_id(forest) + @ccall libt8.t8_forest_get_first_local_leaf_element_id(forest::t8_forest_t)::t8_gloidx_t end """ - t8_element_array_get_array(element_array) - -Return a const pointer to the [`sc_array`](@ref) stored in a t8\\_element\\_array. - -!!! note + t8_forest_get_scheme(forest) - The data cannot be modified. +Return the element scheme associated to a forest. # Arguments -* `element_array`:\\[in\\] Array structure. +* `forest`:\\[in\\] A committed forest. # Returns -A const pointer to the [`sc_array`](@ref) storing the data. +The element scheme of the forest. +# See also +[`t8_forest_set_scheme`](@ref) + ### Prototype ```c -const sc_array_t * t8_element_array_get_array (const t8_element_array_t *element_array); +const t8_scheme_c * t8_forest_get_scheme (const t8_forest_t forest); ``` """ -function t8_element_array_get_array(element_array) - @ccall libt8.t8_element_array_get_array(element_array::Ptr{t8_element_array_t})::Ptr{sc_array_t} +function t8_forest_get_scheme(forest) + @ccall libt8.t8_forest_get_scheme(forest::t8_forest_t)::Ptr{t8_scheme_c} end """ - t8_element_array_get_array_mutable(element_array) - -Return a mutable pointer to the [`sc_array`](@ref) stored in a t8\\_element\\_array. - -!!! note + t8_forest_element_neighbor_eclass(forest, ltreeid, elem, face) - The data can be modified. +Return the eclass of the tree in which a face neighbor of a given element or ghost lies. # Arguments -* `element_array`:\\[in\\] Array structure. +* `forest`:\\[in\\] A committed forest. +* `ltreeid`:\\[in\\] The local tree or ghost tree in which the element lies. 0 <= *ltreeid* < num\\_local\\_trees + num\\_ghost\\_trees +* `elem`:\\[in\\] An element or ghost in the tree *ltreeid*. +* `face`:\\[in\\] A face number of *elem*. # Returns -A pointer to the [`sc_array`](@ref) storing the data. +The eclass of the local tree or ghost tree that is face neighbor of *elem* across *face*. T8\\_ECLASS\\_INVALID if no neighbor exists. ### Prototype ```c -sc_array_t * t8_element_array_get_array_mutable (t8_element_array_t *element_array); +t8_eclass_t t8_forest_element_neighbor_eclass (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *elem, const int face); ``` """ -function t8_element_array_get_array_mutable(element_array) - @ccall libt8.t8_element_array_get_array_mutable(element_array::Ptr{t8_element_array_t})::Ptr{sc_array_t} +function t8_forest_element_neighbor_eclass(forest, ltreeid, elem, face) + @ccall libt8.t8_forest_element_neighbor_eclass(forest::t8_forest_t, ltreeid::t8_locidx_t, elem::Ptr{t8_element_t}, face::Cint)::t8_eclass_t end """ - t8_element_array_find(element_array, element) + t8_forest_element_face_neighbor(forest, ltreeid, elem, neigh, neigh_eclass, face, neigh_face) -Search for an element in an array. +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. # Arguments -* `element_array`:\\[in\\] Array structure. -* `element`:\\[in\\] Element to be found in *element_array*. The element must have been created with the scheme used in *element_array*. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The local tree in which the element lies. +* `elem`:\\[in\\] The element to be considered. +* `neigh`:\\[in,out\\] 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. +* `neigh_eclass`:\\[in\\] The eclass of *neigh*. +* `face`:\\[in\\] The number of the face along which the neighbor should be constructed. +* `neigh_face`:\\[out\\] The number of the face viewed from perspective of *neigh*. Can be nullptr, in which case the output is discarded. # Returns -If *element* was found in *element_array* then the position in the array is returned. If the element is not found, -1 is returned. +The global tree-id of the tree in which *neigh* is in. -1 if there exists no neighbor across that face. Domain boundary. -2 if the neighbor is not in a local tree or ghost tree. Process/Ghost boundary. ### Prototype ```c -t8_locidx_t t8_element_array_find (const t8_element_array_t *element_array, const t8_element_t *element); +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); ``` """ -function t8_element_array_find(element_array, element) - @ccall libt8.t8_element_array_find(element_array::Ptr{t8_element_array_t}, element::Ptr{t8_element_t})::t8_locidx_t +function t8_forest_element_face_neighbor(forest, ltreeid, elem, neigh, neigh_eclass, face, neigh_face) + @ccall libt8.t8_forest_element_face_neighbor(forest::t8_forest_t, ltreeid::t8_locidx_t, elem::Ptr{t8_element_t}, neigh::Ptr{t8_element_t}, neigh_eclass::t8_eclass_t, face::Cint, neigh_face::Ptr{Cint})::t8_gloidx_t end """ - t8_element_array_reset(element_array) - -Sets the array count to zero and frees all elements. - -!!! note + t8_forest_iterate(forest) - Calling [`t8_element_array_init`](@ref), then any array operations, then [`t8_element_array_reset`](@ref) is memory neutral. +TODO: Can be removed since it is unused. # Arguments -* `element_array`:\\[in,out\\] Array structure to be reset. +* `forest`:\\[in\\] The forest. ### Prototype ```c -void t8_element_array_reset (t8_element_array_t *element_array); +void t8_forest_iterate (t8_forest_t forest); ``` """ -function t8_element_array_reset(element_array) - @ccall libt8.t8_element_array_reset(element_array::Ptr{t8_element_array_t})::Cvoid +function t8_forest_iterate(forest) + @ccall libt8.t8_forest_iterate(forest::t8_forest_t)::Cvoid end """ - t8_element_array_truncate(element_array) + t8_forest_element_points_inside(forest, ltreeid, element, points, num_points, is_inside, tolerance) -Sets the array count to zero, but does not free elements. +Query whether a batch of points lies inside an element. For bilinearly interpolated elements. !!! note - This is intended to allow an t8\\_element\\_array to be used as a reusable buffer, where the "high water mark" of the buffer is preserved, so that O(log (max n)) reallocs occur over the life of the buffer. + For 2D quadrilateral elements this function is only an approximation. It is correct 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. # Arguments -* `element_array`:\\[in,out\\] Element array structure to be truncated. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +* `points`:\\[in\\] 3-dimensional coordinates of the points to check +* `num_points`:\\[in\\] The number of points to check +* `is_inside`:\\[in,out\\] An array of length *num_points*, filled with 0/1 on output. True (non-zero) if a *point* lies within an *element*, false otherwise. The return value is also true if the point lies on the element boundary. Thus, this function may return true for different leaf elements, if they are neighbors and the point lies on the common boundary. +* `tolerance`:\\[in\\] Tolerance that we allow the point to not exactly match the element. If this value is larger we detect more points. If it is zero we probably do not detect points even if they are inside due to rounding errors. ### Prototype ```c -void t8_element_array_truncate (t8_element_array_t *element_array); +void t8_forest_element_points_inside (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, const double *points, int num_points, int *is_inside, const double tolerance); ``` """ -function t8_element_array_truncate(element_array) - @ccall libt8.t8_element_array_truncate(element_array::Ptr{t8_element_array_t})::Cvoid +function t8_forest_element_points_inside(forest, ltreeid, element, points, num_points, is_inside, tolerance) + @ccall libt8.t8_forest_element_points_inside(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, points::Ptr{Cdouble}, num_points::Cint, is_inside::Ptr{Cint}, tolerance::Cdouble)::Cvoid end """ - t8_shmem_init(comm) + t8_forest_element_find_owner(forest, gtreeid, element, eclass) -### Prototype -```c -int t8_shmem_init (sc_MPI_Comm comm); -``` -""" -function t8_shmem_init(comm) - @ccall libt8.t8_shmem_init(comm::MPI_Comm)::Cint -end +Find the owner process of a given element. -""" - t8_shmem_finalize(comm) +!!! note -### Prototype -```c -void t8_shmem_finalize (sc_MPI_Comm comm); -``` -""" -function t8_shmem_finalize(comm) - @ccall libt8.t8_shmem_finalize(comm::MPI_Comm)::Cvoid -end + 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. -""" - t8_shmem_set_type(comm, type) +!!! note + + *forest* must be committed before calling this function. + +# Arguments +* `forest`:\\[in\\] The forest. +* `gtreeid`:\\[in\\] The global id of the tree in which the element lies. +* `element`:\\[in\\] The element to look for. +* `eclass`:\\[in\\] The element class of the tree *gtreeid*. +# Returns +The mpirank of the process that owns *element*. +# See also +t8\\_forest\\_element\\_find\\_owner\\_ext, t8\\_forest\\_element\\_owners\\_bounds ### Prototype ```c -void t8_shmem_set_type (sc_MPI_Comm comm, sc_shmem_type_t type); +int t8_forest_element_find_owner (t8_forest_t forest, t8_gloidx_t gtreeid, t8_element_t *element, t8_eclass_t eclass); ``` """ -function t8_shmem_set_type(comm, type) - @ccall libt8.t8_shmem_set_type(comm::MPI_Comm, type::sc_shmem_type_t)::Cvoid +function t8_forest_element_find_owner(forest, gtreeid, element, eclass) + @ccall libt8.t8_forest_element_find_owner(forest::t8_forest_t, gtreeid::t8_gloidx_t, element::Ptr{t8_element_t}, eclass::t8_eclass_t)::Cint end """ - t8_shmem_array_init(parray, elem_size, elem_count, comm) + t8_forest_new_uniform(cmesh, scheme, level, do_face_ghost, comm) ### Prototype ```c -void t8_shmem_array_init (t8_shmem_array_t *parray, size_t elem_size, size_t elem_count, sc_MPI_Comm comm); +t8_forest_t t8_forest_new_uniform (t8_cmesh_t cmesh, const t8_scheme_c *scheme, const int level, const int do_face_ghost, sc_MPI_Comm comm); ``` """ -function t8_shmem_array_init(parray, elem_size, elem_count, comm) - @ccall libt8.t8_shmem_array_init(parray::Ptr{t8_shmem_array_t}, elem_size::Csize_t, elem_count::Csize_t, comm::MPI_Comm)::Cvoid +function t8_forest_new_uniform(cmesh, scheme, level, do_face_ghost, comm) + @ccall libt8.t8_forest_new_uniform(cmesh::t8_cmesh_t, scheme::Ptr{t8_scheme_c}, level::Cint, do_face_ghost::Cint, comm::MPI_Comm)::t8_forest_t end """ - t8_shmem_array_start_writing(array) + t8_forest_new_adapt(forest_from, adapt_fn, recursive, do_face_ghost, user_data) -Enable writing mode for a shmem array. Only some processes may be allowed to write into the array, which is indicated by the return value being non-zero. The shared memory is managed via inter- and intranode communicators. Only rank 0 of the intranode communicator will be allowed to write into the array. +Build a adapted forest from another forest. !!! note - This function is MPI collective. + This is equivalent to calling t8_forest_init, t8_forest_set_adapt, t8_forest_set_ghost, and t8_forest_commit # Arguments -* `array`:\\[in,out\\] Initialized array. Writing will be enabled on certain processes. +* `forest_from`:\\[in\\] The forest to refine +* `adapt_fn`:\\[in\\] Adapt function to use +* `recursive`:\\[in\\] If true adaptation is recursive +* `do_face_ghost`:\\[in\\] If true, a layer of ghost elements is created for the forest. +* `user_data`:\\[in\\] If not NULL, the user data pointer of the forest is set to this value. # Returns -True if the calling process can write into the array. +A new forest that is adapted from *forest_from*. ### Prototype ```c -int t8_shmem_array_start_writing (t8_shmem_array_t array); +t8_forest_t t8_forest_new_adapt (t8_forest_t forest_from, t8_forest_adapt_t adapt_fn, int recursive, int do_face_ghost, void *user_data); ``` """ -function t8_shmem_array_start_writing(array) - @ccall libt8.t8_shmem_array_start_writing(array::t8_shmem_array_t)::Cint +function t8_forest_new_adapt(forest_from, adapt_fn, recursive, do_face_ghost, user_data) + @ccall libt8.t8_forest_new_adapt(forest_from::t8_forest_t, adapt_fn::t8_forest_adapt_t, recursive::Cint, do_face_ghost::Cint, user_data::Ptr{Cvoid})::t8_forest_t end """ - t8_shmem_array_end_writing(array) - -Disable writing mode for a shmem array. - -!!! note + t8_forest_ref(forest) - This function is MPI collective. +Increase the reference counter of a forest. # Arguments -* `array`:\\[in,out\\] Initialized with writing mode enabled. -# See also -[`t8_shmem_array_start_writing`](@ref). - +* `forest`:\\[in,out\\] On input, this forest must exist with positive reference count. It may be in any state. ### Prototype ```c -void t8_shmem_array_end_writing (t8_shmem_array_t array); +void t8_forest_ref (t8_forest_t forest); ``` """ -function t8_shmem_array_end_writing(array) - @ccall libt8.t8_shmem_array_end_writing(array::t8_shmem_array_t)::Cvoid +function t8_forest_ref(forest) + @ccall libt8.t8_forest_ref(forest::t8_forest_t)::Cvoid end """ - t8_shmem_array_set_gloidx(array, index, value) + t8_forest_unref(pforest) -Set an entry of a t8\\_shmem array that is used to store [`t8_gloidx_t`](@ref). The array must have writing mode enabled t8_shmem_array_start_writing. +Decrease the reference counter of a forest. If the counter reaches zero, this forest is destroyed. In this case, the forest dereferences its cmesh and scheme members. # Arguments -* `array`:\\[in,out\\] The array to be modified. -* `index`:\\[in\\] The array entry to be modified. -* `value`:\\[in\\] The new value to be set. +* `pforest`:\\[in,out\\] On input, the forest pointed to must exist with positive reference count. It may be in any state. If the reference count reaches zero, the forest is destroyed and this pointer set to NULL. Otherwise, the pointer is not changed and the forest is not modified in other ways. ### Prototype ```c -void t8_shmem_array_set_gloidx (t8_shmem_array_t array, int index, t8_gloidx_t value); +void t8_forest_unref (t8_forest_t *pforest); ``` """ -function t8_shmem_array_set_gloidx(array, index, value) - @ccall libt8.t8_shmem_array_set_gloidx(array::t8_shmem_array_t, index::Cint, value::t8_gloidx_t)::Cvoid +function t8_forest_unref(pforest) + @ccall libt8.t8_forest_unref(pforest::Ptr{t8_forest_t})::Cvoid end """ - t8_shmem_array_copy(dest, source) + sc_keyvalue_entry_type_t -Copy the contents of one t8\\_shmem array into another. +The values can have different types. -!!! note +| Enumerator | Note | +| :------------------------------ | :------------------------------------------ | +| SC\\_KEYVALUE\\_ENTRY\\_NONE | Designate an invalid situation. | +| SC\\_KEYVALUE\\_ENTRY\\_INT | Used for values of type int. | +| SC\\_KEYVALUE\\_ENTRY\\_DOUBLE | Used for values of type double. | +| SC\\_KEYVALUE\\_ENTRY\\_STRING | Used for values of type const char *. | +| SC\\_KEYVALUE\\_ENTRY\\_POINTER | Used for values of anonymous pointer type. | +""" +@cenum sc_keyvalue_entry_type_t::UInt32 begin + SC_KEYVALUE_ENTRY_NONE = 0 + SC_KEYVALUE_ENTRY_INT = 1 + SC_KEYVALUE_ENTRY_DOUBLE = 2 + SC_KEYVALUE_ENTRY_STRING = 3 + SC_KEYVALUE_ENTRY_POINTER = 4 +end - *dest* must be initialized and match in element size and element count to *source*. +mutable struct sc_keyvalue end -!!! note +"""The key-value container is an opaque structure.""" +const sc_keyvalue_t = sc_keyvalue - *dest* must have writing mode disabled. +# no prototype is found for this function at sc_keyvalue.h:54:21, please use with caution +""" + sc_keyvalue_new() -# Arguments -* `dest`:\\[in,out\\] The array in which *source* should be copied. -* `source`:\\[in\\] The array to copy. +Create a new key-value container. + +# Returns +The container is ready to use. ### Prototype ```c -void t8_shmem_array_copy (t8_shmem_array_t dest, t8_shmem_array_t source); +sc_keyvalue_t *sc_keyvalue_new (); ``` """ -function t8_shmem_array_copy(dest, source) - @ccall libt8.t8_shmem_array_copy(dest::t8_shmem_array_t, source::t8_shmem_array_t)::Cvoid +function sc_keyvalue_new() + @ccall libsc.sc_keyvalue_new()::Ptr{sc_keyvalue_t} end +# automatic type deduction for variadic arguments may not be what you want, please use with caution +@generated function sc_keyvalue_newf(dummy, va_list...) + :(@ccall(libsc.sc_keyvalue_newf(dummy::Cint; $(to_c_type_pairs(va_list)...))::Ptr{sc_keyvalue_t})) + end + """ - t8_shmem_array_allgather(sendbuf, sendcount, sendtype, recvarray, recvcount, recvtype) + sc_keyvalue_destroy(kv) +Free a key-value container and all internal memory for key storage. + +# Arguments +* `kv`:\\[in,out\\] The key-value container is invalidated by this call. ### Prototype ```c -void t8_shmem_array_allgather (const void *sendbuf, int sendcount, sc_MPI_Datatype sendtype, t8_shmem_array_t recvarray, int recvcount, sc_MPI_Datatype recvtype); +void sc_keyvalue_destroy (sc_keyvalue_t * kv); ``` """ -function t8_shmem_array_allgather(sendbuf, sendcount, sendtype, recvarray, recvcount, recvtype) - @ccall libt8.t8_shmem_array_allgather(sendbuf::Ptr{Cvoid}, sendcount::Cint, sendtype::Cint, recvarray::t8_shmem_array_t, recvcount::Cint, recvtype::Cint)::Cvoid +function sc_keyvalue_destroy(kv) + @ccall libsc.sc_keyvalue_destroy(kv::Ptr{sc_keyvalue_t})::Cvoid end """ - t8_shmem_array_allgatherv(sendbuf, sendcount, sendtype, recvarray, recvtype, comm) + sc_keyvalue_exists(kv, key) +Routine to check existence of an entry. + +# Arguments +* `kv`:\\[in\\] Valid key-value container. +* `key`:\\[in\\] Lookup key to query. +# Returns +The entry's type if found and SC\\_KEYVALUE\\_ENTRY\\_NONE otherwise. ### Prototype ```c -void t8_shmem_array_allgatherv (void *sendbuf, const int sendcount, sc_MPI_Datatype sendtype, t8_shmem_array_t recvarray, sc_MPI_Datatype recvtype, sc_MPI_Comm comm); +sc_keyvalue_entry_type_t sc_keyvalue_exists (sc_keyvalue_t * kv, const char *key); ``` """ -function t8_shmem_array_allgatherv(sendbuf, sendcount, sendtype, recvarray, recvtype, comm) - @ccall libt8.t8_shmem_array_allgatherv(sendbuf::Ptr{Cvoid}, sendcount::Cint, sendtype::Cint, recvarray::t8_shmem_array_t, recvtype::Cint, comm::MPI_Comm)::Cvoid +function sc_keyvalue_exists(kv, key) + @ccall libsc.sc_keyvalue_exists(kv::Ptr{sc_keyvalue_t}, key::Cstring)::sc_keyvalue_entry_type_t end """ - t8_shmem_array_prefix(sendbuf, recvarray, count, type, op, comm) + sc_keyvalue_unset(kv, key) + +Routine to remove an entry. +# Arguments +* `kv`:\\[in\\] Valid key-value container. +* `key`:\\[in\\] Lookup key to remove if it exists. +# Returns +The entry's type if found and removed, SC\\_KEYVALUE\\_ENTRY\\_NONE otherwise. ### Prototype ```c -void t8_shmem_array_prefix (const void *sendbuf, t8_shmem_array_t recvarray, const int count, sc_MPI_Datatype type, sc_MPI_Op op, sc_MPI_Comm comm); +sc_keyvalue_entry_type_t sc_keyvalue_unset (sc_keyvalue_t * kv, const char *key); ``` """ -function t8_shmem_array_prefix(sendbuf, recvarray, count, type, op, comm) - @ccall libt8.t8_shmem_array_prefix(sendbuf::Ptr{Cvoid}, recvarray::t8_shmem_array_t, count::Cint, type::Cint, op::Cint, comm::MPI_Comm)::Cvoid +function sc_keyvalue_unset(kv, key) + @ccall libsc.sc_keyvalue_unset(kv::Ptr{sc_keyvalue_t}, key::Cstring)::sc_keyvalue_entry_type_t end """ - t8_shmem_array_get_comm(array) + sc_keyvalue_get_int(kv, key, dvalue) + +Routines to retrieve an integer value by its key. This function asserts that the key, if existing, points to the correct type. +# Arguments +* `kv`:\\[in\\] Valid key-value container. +* `key`:\\[in\\] Lookup key, may or may not exist. +* `dvalue`:\\[in\\] Default value returned if key is not found. +# Returns +If key is not present then **dvalue** is returned, otherwise the value stored under **key**. ### Prototype ```c -sc_MPI_Comm t8_shmem_array_get_comm (t8_shmem_array_t array); +int sc_keyvalue_get_int (sc_keyvalue_t * kv, const char *key, int dvalue); ``` """ -function t8_shmem_array_get_comm(array) - @ccall libt8.t8_shmem_array_get_comm(array::t8_shmem_array_t)::Cint +function sc_keyvalue_get_int(kv, key, dvalue) + @ccall libsc.sc_keyvalue_get_int(kv::Ptr{sc_keyvalue_t}, key::Cstring, dvalue::Cint)::Cint end """ - t8_shmem_array_get_elem_size(array) + sc_keyvalue_get_double(kv, key, dvalue) -Get the element size of a [`t8_shmem_array`](@ref) +Retrieve a double value by its key. This function asserts that the key, if existing, points to the correct type. # Arguments -* `array`:\\[in\\] The array. +* `kv`:\\[in\\] Valid key-value container. +* `key`:\\[in\\] Lookup key, may or may not exist. +* `dvalue`:\\[in\\] Default value returned if key is not found. # Returns -The element size of *array*'s elements. +If key is not present then **dvalue** is returned, otherwise the value stored under **key**. ### Prototype ```c -size_t t8_shmem_array_get_elem_size (t8_shmem_array_t array); +double sc_keyvalue_get_double (sc_keyvalue_t * kv, const char *key, double dvalue); ``` """ -function t8_shmem_array_get_elem_size(array) - @ccall libt8.t8_shmem_array_get_elem_size(array::t8_shmem_array_t)::Csize_t +function sc_keyvalue_get_double(kv, key, dvalue) + @ccall libsc.sc_keyvalue_get_double(kv::Ptr{sc_keyvalue_t}, key::Cstring, dvalue::Cdouble)::Cdouble end """ - t8_shmem_array_get_elem_count(array) + sc_keyvalue_get_string(kv, key, dvalue) -Get the number of elements of a [`t8_shmem_array`](@ref) +Retrieve a string value by its key. This function asserts that the key, if existing, points to the correct type. # Arguments -* `array`:\\[in\\] The array. +* `kv`:\\[in\\] Valid key-value container. +* `key`:\\[in\\] Lookup key, may or may not exist. +* `dvalue`:\\[in\\] Default value returned if key is not found. # Returns -The number of elements in *array*. +If key is not present then **dvalue** is returned, otherwise the value stored under **key**. ### Prototype ```c -size_t t8_shmem_array_get_elem_count (t8_shmem_array_t array); +const char *sc_keyvalue_get_string (sc_keyvalue_t * kv, const char *key, const char *dvalue); ``` """ -function t8_shmem_array_get_elem_count(array) - @ccall libt8.t8_shmem_array_get_elem_count(array::t8_shmem_array_t)::Csize_t +function sc_keyvalue_get_string(kv, key, dvalue) + @ccall libsc.sc_keyvalue_get_string(kv::Ptr{sc_keyvalue_t}, key::Cstring, dvalue::Cstring)::Cstring end """ - t8_shmem_array_get_gloidx_array(array) - -Return a read-only pointer to the data of a shared memory array interpreted as an [`t8_gloidx_t`](@ref) array. - -!!! note + sc_keyvalue_get_pointer(kv, key, dvalue) - Writing mode must be disabled for *array*. +Retrieve a pointer value by its key. This function asserts that the key, if existing, points to the correct type. # Arguments -* `array`:\\[in\\] The [`t8_shmem_array`](@ref) +* `kv`:\\[in\\] Valid key-value container. +* `key`:\\[in\\] Lookup key, may or may not exist. +* `dvalue`:\\[in\\] Default value returned if key is not found. # Returns -The data of *array* as [`t8_gloidx_t`](@ref) pointer. +If key is not present then **dvalue** is returned, otherwise the value stored under **key**. ### Prototype ```c -const t8_gloidx_t * t8_shmem_array_get_gloidx_array (t8_shmem_array_t array); +void *sc_keyvalue_get_pointer (sc_keyvalue_t * kv, const char *key, void *dvalue); ``` """ -function t8_shmem_array_get_gloidx_array(array) - @ccall libt8.t8_shmem_array_get_gloidx_array(array::t8_shmem_array_t)::Ptr{t8_gloidx_t} +function sc_keyvalue_get_pointer(kv, key, dvalue) + @ccall libsc.sc_keyvalue_get_pointer(kv::Ptr{sc_keyvalue_t}, key::Cstring, dvalue::Ptr{Cvoid})::Ptr{Cvoid} end """ - t8_shmem_array_get_gloidx_array_for_writing(array) + sc_keyvalue_get_int_check(kv, key, status) -Return a pointer to the data of a shared memory array interpreted as an [`t8_gloidx_t`](@ref) array. The array must have writing enabled t8_shmem_array_start_writing and you should not write into the memory after t8_shmem_array_end_writing was called. +Query an integer key with error checking. We check whether the key is not found or it is of the wrong type. A default value to be returned on error can be passed in as *status. If status is NULL, then the result on error is undefined. # Arguments -* `array`:\\[in\\] The [`t8_shmem_array`](@ref) +* `kv`:\\[in\\] Valid key-value table. +* `key`:\\[in\\] Non-NULL key string. +* `status`:\\[in,out\\] If not NULL, set to 0 if there is no error, 1 if the key is not found, 2 if a value is found but its type is not integer, and return the input value *status on error. # Returns -The data of *array* as [`t8_gloidx_t`](@ref) pointer. +On error we return *status if status is not NULL, and else an undefined value backed by an assertion. Without error, return the result of the lookup. ### Prototype ```c -t8_gloidx_t * t8_shmem_array_get_gloidx_array_for_writing (t8_shmem_array_t array); +int sc_keyvalue_get_int_check (sc_keyvalue_t * kv, const char *key, int *status); ``` """ -function t8_shmem_array_get_gloidx_array_for_writing(array) - @ccall libt8.t8_shmem_array_get_gloidx_array_for_writing(array::t8_shmem_array_t)::Ptr{t8_gloidx_t} +function sc_keyvalue_get_int_check(kv, key, status) + @ccall libsc.sc_keyvalue_get_int_check(kv::Ptr{sc_keyvalue_t}, key::Cstring, status::Ptr{Cint})::Cint end """ - t8_shmem_array_get_gloidx(array, index) - -Return an entry of a shared memory array that stores [`t8_gloidx_t`](@ref). - -!!! note + sc_keyvalue_set_int(kv, key, newvalue) - Writing mode must be disabled for *array*. +Routine to set an integer value for a given key. # Arguments -* `array`:\\[in\\] The [`t8_shmem_array`](@ref) -* `index`:\\[in\\] The index of the entry to be queried. -# Returns -The *index*-th entry of *array* as [`t8_gloidx_t`](@ref). +* `kv`:\\[in\\] Valid key-value table. +* `key`:\\[in\\] Non-NULL key to insert or replace. If it already exists, it must be of type integer. +* `newvalue`:\\[in\\] New value will be stored under key. ### Prototype ```c -t8_gloidx_t t8_shmem_array_get_gloidx (t8_shmem_array_t array, int index); +void sc_keyvalue_set_int (sc_keyvalue_t * kv, const char *key, int newvalue); ``` """ -function t8_shmem_array_get_gloidx(array, index) - @ccall libt8.t8_shmem_array_get_gloidx(array::t8_shmem_array_t, index::Cint)::t8_gloidx_t +function sc_keyvalue_set_int(kv, key, newvalue) + @ccall libsc.sc_keyvalue_set_int(kv::Ptr{sc_keyvalue_t}, key::Cstring, newvalue::Cint)::Cvoid end """ - t8_shmem_array_get_array(array) - -Return a pointer to the data array of a [`t8_shmem_array`](@ref). - -!!! note + sc_keyvalue_set_double(kv, key, newvalue) - Writing mode must be disabled for *array*. +Routine to set a double value for a given key. # Arguments -* `array`:\\[in\\] The [`t8_shmem_array`](@ref). -# Returns -A pointer to the data array of *array*. +* `kv`:\\[in\\] Valid key-value table. +* `key`:\\[in\\] Non-NULL key to insert or replace. If it already exists, it must be of type double. +* `newvalue`:\\[in\\] New value will be stored under key. ### Prototype ```c -const void * t8_shmem_array_get_array (t8_shmem_array_t array); +void sc_keyvalue_set_double (sc_keyvalue_t * kv, const char *key, double newvalue); ``` """ -function t8_shmem_array_get_array(array) - @ccall libt8.t8_shmem_array_get_array(array::t8_shmem_array_t)::Ptr{Cvoid} +function sc_keyvalue_set_double(kv, key, newvalue) + @ccall libsc.sc_keyvalue_set_double(kv::Ptr{sc_keyvalue_t}, key::Cstring, newvalue::Cdouble)::Cvoid end """ - t8_shmem_array_index(array, index) - -Return a read-only pointer to an element in a [`t8_shmem_array`](@ref). - -!!! note - - You should not modify the value. - -!!! note + sc_keyvalue_set_string(kv, key, newvalue) - Writing mode must be disabled for *array*. +Routine to set a string value for a given key. # Arguments -* `array`:\\[in\\] The [`t8_shmem_array`](@ref). -* `index`:\\[in\\] The index of an element. -# Returns -A pointer to the element at *index* in *array*. +* `kv`:\\[in\\] Valid key-value table. +* `key`:\\[in\\] Non-NULL key to insert or replace. If it already exists, it must be of type string. +* `newvalue`:\\[in\\] New value will be stored under key. ### Prototype ```c -const void * t8_shmem_array_index (t8_shmem_array_t array, size_t index); +void sc_keyvalue_set_string (sc_keyvalue_t * kv, const char *key, const char *newvalue); ``` """ -function t8_shmem_array_index(array, index) - @ccall libt8.t8_shmem_array_index(array::t8_shmem_array_t, index::Csize_t)::Ptr{Cvoid} +function sc_keyvalue_set_string(kv, key, newvalue) + @ccall libsc.sc_keyvalue_set_string(kv::Ptr{sc_keyvalue_t}, key::Cstring, newvalue::Cstring)::Cvoid end """ - t8_shmem_array_index_for_writing(array, index) - -Return a pointer to an element in a [`t8_shmem_array`](@ref) in writing mode. - -!!! note - - You can modify the value before the next call to t8_shmem_array_end_writing. - -!!! note + sc_keyvalue_set_pointer(kv, key, newvalue) - Writing mode must be enabled for *array*. +Routine to set a pointer value for a given key. # Arguments -* `array`:\\[in\\] The [`t8_shmem_array`](@ref). -* `index`:\\[in\\] The index of an element. -# Returns -A pointer to the element at *index* in *array*. +* `kv`:\\[in\\] Valid key-value table. +* `key`:\\[in\\] Non-NULL key to insert or replace. If it already exists, it must be of type pointer. +* `newvalue`:\\[in\\] New value will be stored under key. ### Prototype ```c -void * t8_shmem_array_index_for_writing (t8_shmem_array_t array, size_t index); +void sc_keyvalue_set_pointer (sc_keyvalue_t * kv, const char *key, void *newvalue); ``` """ -function t8_shmem_array_index_for_writing(array, index) - @ccall libt8.t8_shmem_array_index_for_writing(array::t8_shmem_array_t, index::Csize_t)::Ptr{Cvoid} +function sc_keyvalue_set_pointer(kv, key, newvalue) + @ccall libsc.sc_keyvalue_set_pointer(kv::Ptr{sc_keyvalue_t}, key::Cstring, newvalue::Ptr{Cvoid})::Cvoid end +# typedef int ( * sc_keyvalue_foreach_t ) ( const char * key , const sc_keyvalue_entry_type_t type , void * entry , const void * u ) """ - t8_shmem_array_is_equal(array_a, array_b) - -Check if two t8\\_shmem arrays are equal. - -!!! note - - Writing mode must be disabled for *array_a* and *array_b*. +Function to call on every key value pair # Arguments -* `array_a`:\\[in\\] The first [`t8_shmem_array`](@ref) to compare. -* `array_b`:\\[in\\] The second [`t8_shmem_array`](@ref) to compare. +* `key`:\\[in\\] The key for this pair +* `type`:\\[in\\] The type of entry +* `entry`:\\[in\\] Pointer to the entry +* `u`:\\[in\\] Arbitrary user data. # Returns -1 if the arrays are equal, 0 otherwise. -### Prototype -```c -int t8_shmem_array_is_equal (t8_shmem_array_t array_a, t8_shmem_array_t array_b); -``` +Return true if the traversal should continue, false to stop. """ -function t8_shmem_array_is_equal(array_a, array_b) - @ccall libt8.t8_shmem_array_is_equal(array_a::t8_shmem_array_t, array_b::t8_shmem_array_t)::Cint -end +const sc_keyvalue_foreach_t = Ptr{Cvoid} """ - t8_shmem_array_destroy(parray) + sc_keyvalue_foreach(kv, fn, user_data) -Free all memory associated with a [`t8_shmem_array`](@ref). +Iterate through all stored key-value pairs. # Arguments -* `parray`:\\[in,out\\] On input a pointer to a valid [`t8_shmem_array`](@ref). This array is freed and *parray* is set to NULL on return. +* `kv`:\\[in\\] Valid key-value container. +* `fn`:\\[in\\] Function to call on each key-value pair. +* `user_data`:\\[in,out\\] This pointer is passed through to **fn**. ### Prototype ```c -void t8_shmem_array_destroy (t8_shmem_array_t *parray); +void sc_keyvalue_foreach (sc_keyvalue_t * kv, sc_keyvalue_foreach_t fn, void *user_data); ``` """ -function t8_shmem_array_destroy(parray) - @ccall libt8.t8_shmem_array_destroy(parray::Ptr{t8_shmem_array_t})::Cvoid +function sc_keyvalue_foreach(kv, fn, user_data) + @ccall libsc.sc_keyvalue_foreach(kv::Ptr{sc_keyvalue_t}, fn::sc_keyvalue_foreach_t, user_data::Ptr{Cvoid})::Cvoid end """ - t8_shmem_array_binary_search(array, value, size, compare) + sc_statinfo -Perform a binary search in a [`t8_shmem_array`](@ref). +Store information of one random variable. -# Arguments -* `array`:\\[in\\] The [`t8_shmem_array`](@ref) to search in. -* `value`:\\[in\\] The value to search for. -* `size`:\\[in\\] The number of elements in the array. -* `compare`:\\[in\\] A function that compares an element of the array with the value. -# Returns -The index of the element in *array* that matches *value*. -### Prototype -```c -int t8_shmem_array_binary_search (t8_shmem_array_t array, const t8_gloidx_t value, const int size, int (*compare) (t8_shmem_array_t, const int, const t8_gloidx_t)); -``` +| Field | Note | +| :--------------- | :--------------------------------------- | +| dirty | Only update stats if this is true. | +| count | Inout; global count is 52 bit accurate. | +| sum\\_values | Inout; global sum of values. | +| sum\\_squares | Inout; global sum of squares. | +| min | Inout; minimum over values. | +| max | Inout; maximum over values. | +| variable | Name of the variable for output. | +| variable\\_owned | NULL or deep copy of variable. | +| group | Grouping identifier. | +| prio | Priority identifier. | """ -function t8_shmem_array_binary_search(array, value, size, compare) - @ccall libt8.t8_shmem_array_binary_search(array::t8_shmem_array_t, value::t8_gloidx_t, size::Cint, compare::Ptr{Cvoid})::Cint +struct sc_statinfo + dirty::Cint + count::Clong + sum_values::Cdouble + sum_squares::Cdouble + min::Cdouble + max::Cdouble + min_at_rank::Cint + max_at_rank::Cint + average::Cdouble + variance::Cdouble + standev::Cdouble + variance_mean::Cdouble + standev_mean::Cdouble + variable::Cstring + variable_owned::Cstring + group::Cint + prio::Cint +end + +"""Store information of one random variable.""" +const sc_statinfo_t = sc_statinfo + +struct sc_stats + mpicomm::MPI_Comm + kv::Ptr{sc_keyvalue_t} + sarray::Ptr{sc_array_t} end +"""The statistics container allows dynamically adding random variables.""" +const sc_statistics_t = sc_stats + """ - t8_eclass_count_boundary(theclass, min_dim, per_eclass) + sc_stats_set1(stats, value, variable) -Query the element class and count of boundary points. +Populate a [`sc_statinfo_t`](@ref) structure assuming count=1 and mark it dirty. We set sc_stats_group_all and sc_stats_prio_all internally. # Arguments -* `theclass`:\\[in\\] We query a point of this element class. -* `min_dim`:\\[in\\] Ignore boundary points of lesser dimension. The ignored points get a count value of 0. -* `per_eclass`:\\[out\\] Array of length T8\\_ECLASS\\_COUNT to be filled with the count of the boundary objects, counted per each of the element classes. -# Returns -The count over all boundary points. +* `stats`:\\[out\\] Will be filled with count=1 and the value. +* `value`:\\[in\\] Value used to fill statistics information. +* `variable`:\\[in\\] String to be reported by sc_stats_print. This string is assigned by pointer, not copied. Thus, it must stay alive while stats is in use. ### Prototype ```c -int t8_eclass_count_boundary (t8_eclass_t theclass, int min_dim, int *per_eclass); +void sc_stats_set1 (sc_statinfo_t * stats, double value, const char *variable); ``` """ -function t8_eclass_count_boundary(theclass, min_dim, per_eclass) - @ccall libt8.t8_eclass_count_boundary(theclass::t8_eclass_t, min_dim::Cint, per_eclass::Ptr{Cint})::Cint +function sc_stats_set1(stats, value, variable) + @ccall libsc.sc_stats_set1(stats::Ptr{sc_statinfo_t}, value::Cdouble, variable::Cstring)::Cvoid end """ - t8_eclass_compare(eclass1, eclass2) + sc_stats_set1_ext(stats, value, variable, copy_variable, stats_group, stats_prio) -Compare two eclasses of the same dimension as necessary for face neighbor orientation. The implemented order is Triangle < Square in 2D and Tet < Hex < Prism < Pyramid in 3D. +Populate a [`sc_statinfo_t`](@ref) structure assuming count=1 and mark it dirty. # Arguments -* `eclass1`:\\[in\\] The first eclass to compare. -* `eclass2`:\\[in\\] The second eclass to compare. -# Returns -0 if the eclasses are equal, 1 if eclass1 > eclass2 and -1 if eclass1 < eclass2 +* `stats`:\\[out\\] Will be filled with count=1 and the value. +* `value`:\\[in\\] Value used to fill statistics information. +* `variable`:\\[in\\] String to be reported by sc_stats_print. +* `copy_variable`:\\[in\\] If true, make internal copy of variable. Otherwise just assign the pointer. +* `stats_group`:\\[in\\] Non-negative number or sc_stats_group_all. +* `stats_prio`:\\[in\\] Non-negative number or sc_stats_prio_all. ### Prototype ```c -int t8_eclass_compare (t8_eclass_t eclass1, t8_eclass_t eclass2); +void sc_stats_set1_ext (sc_statinfo_t * stats, double value, const char *variable, int copy_variable, int stats_group, int stats_prio); ``` """ -function t8_eclass_compare(eclass1, eclass2) - @ccall libt8.t8_eclass_compare(eclass1::t8_eclass_t, eclass2::t8_eclass_t)::Cint +function sc_stats_set1_ext(stats, value, variable, copy_variable, stats_group, stats_prio) + @ccall libsc.sc_stats_set1_ext(stats::Ptr{sc_statinfo_t}, value::Cdouble, variable::Cstring, copy_variable::Cint, stats_group::Cint, stats_prio::Cint)::Cvoid end """ - t8_eclass_is_valid(eclass) + sc_stats_init(stats, variable) -Check whether a class is a valid class. Returns non-zero if it is a valid class, returns zero, if the class is equal to T8\\_ECLASS\\_INVALID. +Initialize a [`sc_statinfo_t`](@ref) structure assuming count=0 and mark it dirty. This is useful if *stats* will be used to sc_stats_accumulate instances locally before global statistics are computed. We set sc_stats_group_all and sc_stats_prio_all internally. # Arguments -* `eclass`:\\[in\\] The eclass to check. -# Returns -Non-zero if *eclass* is valid, zero otherwise. +* `stats`:\\[out\\] Will be filled with count 0 and values of 0. +* `variable`:\\[in\\] String to be reported by sc_stats_print. This string is assigned by pointer, not copied. Thus, it must stay alive while stats is in use. ### Prototype ```c -int t8_eclass_is_valid (t8_eclass_t eclass); +void sc_stats_init (sc_statinfo_t * stats, const char *variable); ``` """ -function t8_eclass_is_valid(eclass) - @ccall libt8.t8_eclass_is_valid(eclass::t8_eclass_t)::Cint +function sc_stats_init(stats, variable) + @ccall libsc.sc_stats_init(stats::Ptr{sc_statinfo_t}, variable::Cstring)::Cvoid end -"""Type definition for the geometric shape of an element. Currently the possible shapes are the same as the possible element classes. I.e. T8\\_ECLASS\\_VERTEX, T8\\_ECLASS\\_TET, etc...""" -const t8_element_shape_t = t8_eclass_t - """ - t8_element_shape_num_faces(element_shape) + sc_stats_init_ext(stats, variable, copy_variable, stats_group, stats_prio) -The number of codimension-one boundaries of an element class. +Initialize a [`sc_statinfo_t`](@ref) structure assuming count=0 and mark it dirty. This is useful if *stats* will be used to sc_stats_accumulate instances locally before global statistics are computed. +# Arguments +* `stats`:\\[out\\] Will be filled with count 0 and values of 0. +* `variable`:\\[in\\] String to be reported by sc_stats_print. +* `copy_variable`:\\[in\\] If true, make internal copy of variable. Otherwise just assign the pointer. +* `stats_group`:\\[in\\] Non-negative number or sc_stats_group_all. +* `stats_prio`:\\[in\\] Non-negative number or sc_stats_prio_all. Values increase by importance. ### Prototype ```c -int t8_element_shape_num_faces (int element_shape); +void sc_stats_init_ext (sc_statinfo_t * stats, const char *variable, int copy_variable, int stats_group, int stats_prio); ``` """ -function t8_element_shape_num_faces(element_shape) - @ccall libt8.t8_element_shape_num_faces(element_shape::Cint)::Cint +function sc_stats_init_ext(stats, variable, copy_variable, stats_group, stats_prio) + @ccall libsc.sc_stats_init_ext(stats::Ptr{sc_statinfo_t}, variable::Cstring, copy_variable::Cint, stats_group::Cint, stats_prio::Cint)::Cvoid end """ - t8_element_shape_max_num_faces(element_shape) + sc_stats_reset(stats, reset_vgp) -For each dimension the maximum possible number of faces of an element\\_shape of that dimension. +Reset all values to zero, optionally unassign name, group, and priority. +# Arguments +* `stats`:\\[in,out\\] Variables are zeroed. They can be set again by set1 or accumulate. +* `reset_vgp`:\\[in\\] If true, the variable name string is zeroed and if we did a copy, the copy is freed. If true, group and priority are set to all. If false, we don't touch any of the above. ### Prototype ```c -int t8_element_shape_max_num_faces (int element_shape); +void sc_stats_reset (sc_statinfo_t * stats, int reset_vgp); ``` """ -function t8_element_shape_max_num_faces(element_shape) - @ccall libt8.t8_element_shape_max_num_faces(element_shape::Cint)::Cint +function sc_stats_reset(stats, reset_vgp) + @ccall libsc.sc_stats_reset(stats::Ptr{sc_statinfo_t}, reset_vgp::Cint)::Cvoid end """ - t8_element_shape_num_vertices(element_shape) + sc_stats_set_group_prio(stats, stats_group, stats_prio) -The number of vertices of an element class. +Set/update the group and priority information for a stats item. +# Arguments +* `stats`:\\[out\\] Only group and stats entries are updated. +* `stats_group`:\\[in\\] Non-negative number or sc_stats_group_all. +* `stats_prio`:\\[in\\] Non-negative number or sc_stats_prio_all. Values increase by importance. ### Prototype ```c -int t8_element_shape_num_vertices (int element_shape); +void sc_stats_set_group_prio (sc_statinfo_t * stats, int stats_group, int stats_prio); ``` """ -function t8_element_shape_num_vertices(element_shape) - @ccall libt8.t8_element_shape_num_vertices(element_shape::Cint)::Cint +function sc_stats_set_group_prio(stats, stats_group, stats_prio) + @ccall libsc.sc_stats_set_group_prio(stats::Ptr{sc_statinfo_t}, stats_group::Cint, stats_prio::Cint)::Cvoid end """ - t8_element_shape_vtk_type(element_shape) + sc_stats_accumulate(stats, value) -The vtk cell type for the element\\_shape +Add an instance of the random variable. The counter of the variable is increased by one. The value is added into the present values of the variable. +# Arguments +* `stats`:\\[out\\] Must be dirty. We bump count and values. +* `value`:\\[in\\] Value used to update statistics information. ### Prototype ```c -int t8_element_shape_vtk_type (int element_shape); +void sc_stats_accumulate (sc_statinfo_t * stats, double value); ``` """ -function t8_element_shape_vtk_type(element_shape) - @ccall libt8.t8_element_shape_vtk_type(element_shape::Cint)::Cint +function sc_stats_accumulate(stats, value) + @ccall libsc.sc_stats_accumulate(stats::Ptr{sc_statinfo_t}, value::Cdouble)::Cvoid end """ - t8_element_shape_t8_to_vtk_corner_number(element_shape, index) - -Maps the t8code corner number of the element to the vtk corner number + sc_stats_compute(mpicomm, nvars, stats) -# Arguments -* `element_shape`:\\[in\\] The shape of the element. -* `index`:\\[in\\] The index of the corner in z-order (t8code numeration). -# Returns -The corresponding vtk index. ### Prototype ```c -int t8_element_shape_t8_to_vtk_corner_number (int element_shape, int index); +void sc_stats_compute (sc_MPI_Comm mpicomm, int nvars, sc_statinfo_t * stats); ``` """ -function t8_element_shape_t8_to_vtk_corner_number(element_shape, index) - @ccall libt8.t8_element_shape_t8_to_vtk_corner_number(element_shape::Cint, index::Cint)::Cint +function sc_stats_compute(mpicomm, nvars, stats) + @ccall libsc.sc_stats_compute(mpicomm::MPI_Comm, nvars::Cint, stats::Ptr{sc_statinfo_t})::Cvoid end """ - t8_element_shape_t8_corner_number(element_shape, index) - -Maps the vtk corner number of the element to the t8code corner number + sc_stats_compute1(mpicomm, nvars, stats) -# Arguments -* `element_shape`:\\[in\\] The shape of the element. -* `index`:\\[in\\] The index of the corner in vtk ordering. -# Returns -The corresponding t8code index. ### Prototype ```c -int t8_element_shape_t8_corner_number (int element_shape, int index); +void sc_stats_compute1 (sc_MPI_Comm mpicomm, int nvars, sc_statinfo_t * stats); ``` """ -function t8_element_shape_t8_corner_number(element_shape, index) - @ccall libt8.t8_element_shape_t8_corner_number(element_shape::Cint, index::Cint)::Cint +function sc_stats_compute1(mpicomm, nvars, stats) + @ccall libsc.sc_stats_compute1(mpicomm::MPI_Comm, nvars::Cint, stats::Ptr{sc_statinfo_t})::Cvoid end """ - t8_element_shape_to_string(element_shape) + sc_stats_print(package_id, log_priority, nvars, stats, full, summary) -For each element\\_shape, the name of this class as a string +Print measured statistics. This function uses the [`SC_LC_GLOBAL`](@ref) log category. That means the default action is to print only on rank 0. Applications can change that by providing a user-defined log handler. All groups and priorities are printed. +# Arguments +* `package_id`:\\[in\\] Registered package id or -1. +* `log_priority`:\\[in\\] Log priority for output according to sc.h. +* `nvars`:\\[in\\] Number of stats items in input array. +* `stats`:\\[in\\] Input array of stats variable items. +* `full`:\\[in\\] Print full information for every variable. +* `summary`:\\[in\\] Print summary information all on 1 line. ### Prototype ```c -const char* t8_element_shape_to_string (int element_shape); +void sc_stats_print (int package_id, int log_priority, int nvars, sc_statinfo_t * stats, int full, int summary); ``` """ -function t8_element_shape_to_string(element_shape) - @ccall libt8.t8_element_shape_to_string(element_shape::Cint)::Cstring +function sc_stats_print(package_id, log_priority, nvars, stats, full, summary) + @ccall libsc.sc_stats_print(package_id::Cint, log_priority::Cint, nvars::Cint, stats::Ptr{sc_statinfo_t}, full::Cint, summary::Cint)::Cvoid end """ - t8_element_shape_compare(element_shape1, element_shape2) + sc_stats_print_ext(package_id, log_priority, nvars, stats, stats_group, stats_prio, full, summary) -Compare two element\\_shapes of the same dimension as necessary for face neighbor orientation. The implemented order is Triangle < Square in 2D and Tet < Hex < Prism < Pyramid in 3D. +Print measured statistics, filter by group and/or priority. This function uses the [`SC_LC_GLOBAL`](@ref) log category. That means the default action is to print only on rank 0. Applications can change that by providing a user-defined log handler. # Arguments -* `element_shape1`:\\[in\\] The first element\\_shape to compare. -* `element_shape2`:\\[in\\] The second element\\_shape to compare. -# Returns -0 if the element\\_shapes are equal, 1 if element\\_shape1 > element\\_shape2 and -1 if element\\_shape1 < element\\_shape2 +* `package_id`:\\[in\\] Registered package id or -1. +* `log_priority`:\\[in\\] Log priority for output according to sc.h. +* `nvars`:\\[in\\] Number of stats items in input array. +* `stats`:\\[in\\] Input array of stats variable items. +* `stats_group`:\\[in\\] Print only this group. Non-negative or sc_stats_group_all. We skip printing a variable if neither this parameter nor the item's group is all and if the item's group does not match this. +* `stats_prio`:\\[in\\] Print this and higher priorities. Non-negative or sc_stats_prio_all. We skip printing a variable if neither this parameter nor the item's prio is all and if the item's prio is less than this. +* `full`:\\[in\\] Print full information for every variable. This produces multiple lines including minimum, maximum, and standard deviation. If this is false, print one line per variable. +* `summary`:\\[in\\] Print summary information all on 1 line. This always contains all variables. Not affected by stats\\_group and stats\\_prio. ### Prototype ```c -int t8_element_shape_compare (t8_element_shape_t element_shape1, t8_element_shape_t element_shape2); +void sc_stats_print_ext (int package_id, int log_priority, int nvars, sc_statinfo_t * stats, int stats_group, int stats_prio, int full, int summary); ``` """ -function t8_element_shape_compare(element_shape1, element_shape2) - @ccall libt8.t8_element_shape_compare(element_shape1::t8_element_shape_t, element_shape2::t8_element_shape_t)::Cint +function sc_stats_print_ext(package_id, log_priority, nvars, stats, stats_group, stats_prio, full, summary) + @ccall libsc.sc_stats_print_ext(package_id::Cint, log_priority::Cint, nvars::Cint, stats::Ptr{sc_statinfo_t}, stats_group::Cint, stats_prio::Cint, full::Cint, summary::Cint)::Cvoid end """ - sc_keyvalue_entry_type_t - -The values can have different types. + sc_statistics_new(mpicomm) -| Enumerator | Note | -| :------------------------------ | :------------------------------------------ | -| SC\\_KEYVALUE\\_ENTRY\\_NONE | Designate an invalid situation. | -| SC\\_KEYVALUE\\_ENTRY\\_INT | Used for values of type int. | -| SC\\_KEYVALUE\\_ENTRY\\_DOUBLE | Used for values of type double. | -| SC\\_KEYVALUE\\_ENTRY\\_STRING | Used for values of type const char *. | -| SC\\_KEYVALUE\\_ENTRY\\_POINTER | Used for values of anonymous pointer type. | +### Prototype +```c +sc_statistics_t *sc_statistics_new (sc_MPI_Comm mpicomm); +``` """ -@cenum sc_keyvalue_entry_type_t::UInt32 begin - SC_KEYVALUE_ENTRY_NONE = 0 - SC_KEYVALUE_ENTRY_INT = 1 - SC_KEYVALUE_ENTRY_DOUBLE = 2 - SC_KEYVALUE_ENTRY_STRING = 3 - SC_KEYVALUE_ENTRY_POINTER = 4 +function sc_statistics_new(mpicomm) + @ccall libsc.sc_statistics_new(mpicomm::MPI_Comm)::Ptr{sc_statistics_t} end -mutable struct sc_keyvalue end - -"""The key-value container is an opaque structure.""" -const sc_keyvalue_t = sc_keyvalue - -# no prototype is found for this function at sc_keyvalue.h:54:21, please use with caution """ - sc_keyvalue_new() + sc_statistics_destroy(stats) -Create a new key-value container. +Destroy a statistics structure. -# Returns -The container is ready to use. +# Arguments +* `stats`:\\[in,out\\] Valid object is invalidated. ### Prototype ```c -sc_keyvalue_t *sc_keyvalue_new (); +void sc_statistics_destroy (sc_statistics_t * stats); ``` """ -function sc_keyvalue_new() - @ccall libsc.sc_keyvalue_new()::Ptr{sc_keyvalue_t} +function sc_statistics_destroy(stats) + @ccall libsc.sc_statistics_destroy(stats::Ptr{sc_statistics_t})::Cvoid end -# automatic type deduction for variadic arguments may not be what you want, please use with caution -@generated function sc_keyvalue_newf(dummy, va_list...) - :(@ccall(libsc.sc_keyvalue_newf(dummy::Cint; $(to_c_type_pairs(va_list)...))::Ptr{sc_keyvalue_t})) - end - """ - sc_keyvalue_destroy(kv) + sc_statistics_add(stats, name) -Free a key-value container and all internal memory for key storage. +Register a statistics variable by name and set its value to 0. This variable must not exist already. -# Arguments -* `kv`:\\[in,out\\] The key-value container is invalidated by this call. ### Prototype ```c -void sc_keyvalue_destroy (sc_keyvalue_t * kv); +void sc_statistics_add (sc_statistics_t * stats, const char *name); ``` """ -function sc_keyvalue_destroy(kv) - @ccall libsc.sc_keyvalue_destroy(kv::Ptr{sc_keyvalue_t})::Cvoid +function sc_statistics_add(stats, name) + @ccall libsc.sc_statistics_add(stats::Ptr{sc_statistics_t}, name::Cstring)::Cvoid end """ - sc_keyvalue_exists(kv, key) + sc_statistics_add_empty(stats, name) -Routine to check existence of an entry. +Register a statistics variable by name and set its count to 0. This variable must not exist already. -# Arguments -* `kv`:\\[in\\] Valid key-value container. -* `key`:\\[in\\] Lookup key to query. -# Returns -The entry's type if found and SC\\_KEYVALUE\\_ENTRY\\_NONE otherwise. ### Prototype ```c -sc_keyvalue_entry_type_t sc_keyvalue_exists (sc_keyvalue_t * kv, const char *key); +void sc_statistics_add_empty (sc_statistics_t * stats, const char *name); ``` """ -function sc_keyvalue_exists(kv, key) - @ccall libsc.sc_keyvalue_exists(kv::Ptr{sc_keyvalue_t}, key::Cstring)::sc_keyvalue_entry_type_t +function sc_statistics_add_empty(stats, name) + @ccall libsc.sc_statistics_add_empty(stats::Ptr{sc_statistics_t}, name::Cstring)::Cvoid end """ - sc_keyvalue_unset(kv, key) + sc_statistics_has(stats, name) -Routine to remove an entry. +Returns true if the stats include a variable with the given name -# Arguments -* `kv`:\\[in\\] Valid key-value container. -* `key`:\\[in\\] Lookup key to remove if it exists. -# Returns -The entry's type if found and removed, SC\\_KEYVALUE\\_ENTRY\\_NONE otherwise. ### Prototype ```c -sc_keyvalue_entry_type_t sc_keyvalue_unset (sc_keyvalue_t * kv, const char *key); +int sc_statistics_has (sc_statistics_t * stats, const char *name); ``` """ -function sc_keyvalue_unset(kv, key) - @ccall libsc.sc_keyvalue_unset(kv::Ptr{sc_keyvalue_t}, key::Cstring)::sc_keyvalue_entry_type_t +function sc_statistics_has(stats, name) + @ccall libsc.sc_statistics_has(stats::Ptr{sc_statistics_t}, name::Cstring)::Cint end """ - sc_keyvalue_get_int(kv, key, dvalue) + sc_statistics_set(stats, name, value) -Routines to retrieve an integer value by its key. This function asserts that the key, if existing, points to the correct type. +Set the value of a statistics variable, see [`sc_stats_set1`](@ref). The variable must previously be added with [`sc_statistics_add`](@ref). This assumes count=1 as in the [`sc_stats_set1`](@ref) function above. -# Arguments -* `kv`:\\[in\\] Valid key-value container. -* `key`:\\[in\\] Lookup key, may or may not exist. -* `dvalue`:\\[in\\] Default value returned if key is not found. -# Returns -If key is not present then **dvalue** is returned, otherwise the value stored under **key**. ### Prototype ```c -int sc_keyvalue_get_int (sc_keyvalue_t * kv, const char *key, int dvalue); +void sc_statistics_set (sc_statistics_t * stats, const char *name, double value); ``` """ -function sc_keyvalue_get_int(kv, key, dvalue) - @ccall libsc.sc_keyvalue_get_int(kv::Ptr{sc_keyvalue_t}, key::Cstring, dvalue::Cint)::Cint +function sc_statistics_set(stats, name, value) + @ccall libsc.sc_statistics_set(stats::Ptr{sc_statistics_t}, name::Cstring, value::Cdouble)::Cvoid end """ - sc_keyvalue_get_double(kv, key, dvalue) + sc_statistics_accumulate(stats, name, value) -Retrieve a double value by its key. This function asserts that the key, if existing, points to the correct type. +Add an instance of a statistics variable, see [`sc_stats_accumulate`](@ref) The variable must previously be added with [`sc_statistics_add_empty`](@ref). -# Arguments -* `kv`:\\[in\\] Valid key-value container. -* `key`:\\[in\\] Lookup key, may or may not exist. -* `dvalue`:\\[in\\] Default value returned if key is not found. -# Returns -If key is not present then **dvalue** is returned, otherwise the value stored under **key**. ### Prototype ```c -double sc_keyvalue_get_double (sc_keyvalue_t * kv, const char *key, double dvalue); +void sc_statistics_accumulate (sc_statistics_t * stats, const char *name, double value); ``` """ -function sc_keyvalue_get_double(kv, key, dvalue) - @ccall libsc.sc_keyvalue_get_double(kv::Ptr{sc_keyvalue_t}, key::Cstring, dvalue::Cdouble)::Cdouble +function sc_statistics_accumulate(stats, name, value) + @ccall libsc.sc_statistics_accumulate(stats::Ptr{sc_statistics_t}, name::Cstring, value::Cdouble)::Cvoid end """ - sc_keyvalue_get_string(kv, key, dvalue) + sc_statistics_compute(stats) -Retrieve a string value by its key. This function asserts that the key, if existing, points to the correct type. +Compute statistics for all variables, see [`sc_stats_compute`](@ref). -# Arguments -* `kv`:\\[in\\] Valid key-value container. -* `key`:\\[in\\] Lookup key, may or may not exist. -* `dvalue`:\\[in\\] Default value returned if key is not found. -# Returns -If key is not present then **dvalue** is returned, otherwise the value stored under **key**. ### Prototype ```c -const char *sc_keyvalue_get_string (sc_keyvalue_t * kv, const char *key, const char *dvalue); +void sc_statistics_compute (sc_statistics_t * stats); ``` """ -function sc_keyvalue_get_string(kv, key, dvalue) - @ccall libsc.sc_keyvalue_get_string(kv::Ptr{sc_keyvalue_t}, key::Cstring, dvalue::Cstring)::Cstring +function sc_statistics_compute(stats) + @ccall libsc.sc_statistics_compute(stats::Ptr{sc_statistics_t})::Cvoid end """ - sc_keyvalue_get_pointer(kv, key, dvalue) + sc_statistics_print(stats, package_id, log_priority, full, summary) -Retrieve a pointer value by its key. This function asserts that the key, if existing, points to the correct type. +Print all statistics variables, see [`sc_stats_print`](@ref). -# Arguments -* `kv`:\\[in\\] Valid key-value container. -* `key`:\\[in\\] Lookup key, may or may not exist. -* `dvalue`:\\[in\\] Default value returned if key is not found. -# Returns -If key is not present then **dvalue** is returned, otherwise the value stored under **key**. ### Prototype ```c -void *sc_keyvalue_get_pointer (sc_keyvalue_t * kv, const char *key, void *dvalue); +void sc_statistics_print (sc_statistics_t * stats, int package_id, int log_priority, int full, int summary); ``` """ -function sc_keyvalue_get_pointer(kv, key, dvalue) - @ccall libsc.sc_keyvalue_get_pointer(kv::Ptr{sc_keyvalue_t}, key::Cstring, dvalue::Ptr{Cvoid})::Ptr{Cvoid} +function sc_statistics_print(stats, package_id, log_priority, full, summary) + @ccall libsc.sc_statistics_print(stats::Ptr{sc_statistics_t}, package_id::Cint, log_priority::Cint, full::Cint, summary::Cint)::Cvoid end """ - sc_keyvalue_get_int_check(kv, key, status) + t8_forest_get_dimension(forest) -Query an integer key with error checking. We check whether the key is not found or it is of the wrong type. A default value to be returned on error can be passed in as *status. If status is NULL, then the result on error is undefined. +Return the dimension of a forest. # Arguments -* `kv`:\\[in\\] Valid key-value table. -* `key`:\\[in\\] Non-NULL key string. -* `status`:\\[in,out\\] If not NULL, set to 0 if there is no error, 1 if the key is not found, 2 if a value is found but its type is not integer, and return the input value *status on error. +* `forest`:\\[in\\] A forest. # Returns -On error we return *status if status is not NULL, and else an undefined value backed by an assertion. Without error, return the result of the lookup. +The dimension. *forest* must be committed before calling this function. Note: The dimension is inferred from the associated **cmesh**. ### Prototype ```c -int sc_keyvalue_get_int_check (sc_keyvalue_t * kv, const char *key, int *status); +int t8_forest_get_dimension (const t8_forest_t forest); ``` """ -function sc_keyvalue_get_int_check(kv, key, status) - @ccall libsc.sc_keyvalue_get_int_check(kv::Ptr{sc_keyvalue_t}, key::Cstring, status::Ptr{Cint})::Cint +function t8_forest_get_dimension(forest) + @ccall libt8.t8_forest_get_dimension(forest::t8_forest_t)::Cint end """ - sc_keyvalue_set_int(kv, key, newvalue) + t8_forest_element_coordinate(forest, ltree_id, element, corner_number, coordinates) -Routine to set an integer value for a given key. +Compute the coordinates of a given vertex of an element if a geometry for this tree is registered in the forest's cmesh. # Arguments -* `kv`:\\[in\\] Valid key-value table. -* `key`:\\[in\\] Non-NULL key to insert or replace. If it already exists, it must be of type integer. -* `newvalue`:\\[in\\] New value will be stored under key. +* `forest`:\\[in\\] The forest. +* `ltree_id`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +* `corner_number`:\\[in\\] The corner number, in Z-order, of the vertex which should be computed. +* `coordinates`:\\[out\\] On input an allocated array to store 3 doubles, on output the x, y and z coordinates of the vertex. ### Prototype ```c -void sc_keyvalue_set_int (sc_keyvalue_t * kv, const char *key, int newvalue); +void t8_forest_element_coordinate (t8_forest_t forest, t8_locidx_t ltree_id, const t8_element_t *element, int corner_number, double *coordinates); ``` """ -function sc_keyvalue_set_int(kv, key, newvalue) - @ccall libsc.sc_keyvalue_set_int(kv::Ptr{sc_keyvalue_t}, key::Cstring, newvalue::Cint)::Cvoid +function t8_forest_element_coordinate(forest, ltree_id, element, corner_number, coordinates) + @ccall libt8.t8_forest_element_coordinate(forest::t8_forest_t, ltree_id::t8_locidx_t, element::Ptr{t8_element_t}, corner_number::Cint, coordinates::Ptr{Cdouble})::Cvoid end """ - sc_keyvalue_set_double(kv, key, newvalue) + t8_forest_element_from_ref_coords_ext(forest, ltreeid, element, ref_coords, num_coords, coords_out, stretch_factors) -Routine to set a double value for a given key. +Compute the coordinates of a point inside an element inside a tree. The point is given in reference coordinates inside the element and gets converted to reference coordinates inside the tree. After that, the point is converted to global coordinates inside the domain. If needed, the element is stretched by the given stretch factors (the resulting mesh is then no longer non-overlapping). # Arguments -* `kv`:\\[in\\] Valid key-value table. -* `key`:\\[in\\] Non-NULL key to insert or replace. If it already exists, it must be of type double. -* `newvalue`:\\[in\\] New value will be stored under key. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +* `ref_coords`:\\[in\\] The reference coordinates of the point inside the element. +* `num_coords`:\\[in\\] The number of coordinate sets in ref\\_coord (dimension x double). +* `coords_out`:\\[out\\] On input an allocated array to store 3 doubles, on output the x, y and z coordinates of the point inside the domain. +* `stretch_factors`:\\[in\\] If provided, elements are stretched according to the stretch factors of the tree. ### Prototype ```c -void sc_keyvalue_set_double (sc_keyvalue_t * kv, const char *key, double newvalue); +void t8_forest_element_from_ref_coords_ext (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, const double *ref_coords, const size_t num_coords, double *coords_out, const double *stretch_factors); ``` """ -function sc_keyvalue_set_double(kv, key, newvalue) - @ccall libsc.sc_keyvalue_set_double(kv::Ptr{sc_keyvalue_t}, key::Cstring, newvalue::Cdouble)::Cvoid +function t8_forest_element_from_ref_coords_ext(forest, ltreeid, element, ref_coords, num_coords, coords_out, stretch_factors) + @ccall libt8.t8_forest_element_from_ref_coords_ext(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, coords_out::Ptr{Cdouble}, stretch_factors::Ptr{Cdouble})::Cvoid end """ - sc_keyvalue_set_string(kv, key, newvalue) + t8_forest_element_from_ref_coords(forest, ltreeid, element, ref_coords, num_coords, coords_out) -Routine to set a string value for a given key. +Compute the coordinates of a point inside an element inside a tree. The point is given in reference coordinates inside the element and gets converted to reference coordinates inside the tree. After that, the point is converted to global coordinates inside the domain. # Arguments -* `kv`:\\[in\\] Valid key-value table. -* `key`:\\[in\\] Non-NULL key to insert or replace. If it already exists, it must be of type string. -* `newvalue`:\\[in\\] New value will be stored under key. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +* `ref_coords`:\\[in\\] The reference coordinates of the point inside the element. +* `num_coords`:\\[in\\] The number of coordinate sets in ref\\_coord (dimension x double). +* `coords_out`:\\[out\\] On input an allocated array to store 3 doubles, on output the x, y and z coordinates of the point inside the domain. ### Prototype ```c -void sc_keyvalue_set_string (sc_keyvalue_t * kv, const char *key, const char *newvalue); +void t8_forest_element_from_ref_coords (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, const double *ref_coords, const size_t num_coords, double *coords_out); ``` """ -function sc_keyvalue_set_string(kv, key, newvalue) - @ccall libsc.sc_keyvalue_set_string(kv::Ptr{sc_keyvalue_t}, key::Cstring, newvalue::Cstring)::Cvoid +function t8_forest_element_from_ref_coords(forest, ltreeid, element, ref_coords, num_coords, coords_out) + @ccall libt8.t8_forest_element_from_ref_coords(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, coords_out::Ptr{Cdouble})::Cvoid end """ - sc_keyvalue_set_pointer(kv, key, newvalue) + t8_forest_element_centroid(forest, ltreeid, element, coordinates) -Routine to set a pointer value for a given key. +Compute the coordinates of the centroid of an element if a geometry for this tree is registered in the forest's cmesh. 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. # Arguments -* `kv`:\\[in\\] Valid key-value table. -* `key`:\\[in\\] Non-NULL key to insert or replace. If it already exists, it must be of type pointer. -* `newvalue`:\\[in\\] New value will be stored under key. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +* `coordinates`:\\[out\\] On input an allocated array to store 3 doubles, on output the x, y and z coordinates of the centroid. ### Prototype ```c -void sc_keyvalue_set_pointer (sc_keyvalue_t * kv, const char *key, void *newvalue); +void t8_forest_element_centroid (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, double *coordinates); ``` """ -function sc_keyvalue_set_pointer(kv, key, newvalue) - @ccall libsc.sc_keyvalue_set_pointer(kv::Ptr{sc_keyvalue_t}, key::Cstring, newvalue::Ptr{Cvoid})::Cvoid +function t8_forest_element_centroid(forest, ltreeid, element, coordinates) + @ccall libt8.t8_forest_element_centroid(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, coordinates::Ptr{Cdouble})::Cvoid end -# typedef int ( * sc_keyvalue_foreach_t ) ( const char * key , const sc_keyvalue_entry_type_t type , void * entry , const void * u ) """ -Function to call on every key value pair + t8_forest_element_linear_centroid(forest, ltreeid, element, coordinates) -# Arguments -* `key`:\\[in\\] The key for this pair -* `type`:\\[in\\] The type of entry -* `entry`:\\[in\\] Pointer to the entry -* `u`:\\[in\\] Arbitrary user data. -# Returns -Return true if the traversal should continue, false to stop. -""" -const sc_keyvalue_foreach_t = Ptr{Cvoid} +Compute the coordinates of the centroid of an element by its corner coordinates. This treats every element as a linear element. The centroid is the mean of all the corner coordinates. -""" - sc_keyvalue_foreach(kv, fn, user_data) +!!! warning -Iterate through all stored key-value pairs. + This function omits if an element is curved. So for linear elements it produces the same results as t8_forest_element_centroid. For curved elements the curvature is ignored. # Arguments -* `kv`:\\[in\\] Valid key-value container. -* `fn`:\\[in\\] Function to call on each key-value pair. -* `user_data`:\\[in,out\\] This pointer is passed through to **fn**. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +* `coordinates`:\\[out\\] On input an allocated array to store 3 doubles, on output the x, y and z coordinates of the centroid. ### Prototype ```c -void sc_keyvalue_foreach (sc_keyvalue_t * kv, sc_keyvalue_foreach_t fn, void *user_data); +void t8_forest_element_linear_centroid (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *element, double *coordinates); ``` """ -function sc_keyvalue_foreach(kv, fn, user_data) - @ccall libsc.sc_keyvalue_foreach(kv::Ptr{sc_keyvalue_t}, fn::sc_keyvalue_foreach_t, user_data::Ptr{Cvoid})::Cvoid +function t8_forest_element_linear_centroid(forest, ltreeid, element, coordinates) + @ccall libt8.t8_forest_element_linear_centroid(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, coordinates::Ptr{Cdouble})::Cvoid end """ - sc_statinfo + t8_forest_element_diam(forest, ltreeid, element) -Store information of one random variable. +Compute the diameter of an element if a geometry for this tree is registered in the forest's cmesh. This is only an approximation. -| Field | Note | -| :--------------- | :--------------------------------------- | -| dirty | Only update stats if this is true. | -| count | Inout; global count is 52 bit accurate. | -| sum\\_values | Inout; global sum of values. | -| sum\\_squares | Inout; global sum of squares. | -| min | Inout; minimum over values. | -| max | Inout; maximum over values. | -| variable | Name of the variable for output. | -| variable\\_owned | NULL or deep copy of variable. | -| group | Grouping identifier. | -| prio | Priority identifier. | -""" -struct sc_statinfo - dirty::Cint - count::Clong - sum_values::Cdouble - sum_squares::Cdouble - min::Cdouble - max::Cdouble - min_at_rank::Cint - max_at_rank::Cint - average::Cdouble - variance::Cdouble - standev::Cdouble - variance_mean::Cdouble - standev_mean::Cdouble - variable::Cstring - variable_owned::Cstring - group::Cint - prio::Cint -end +!!! note -"""Store information of one random variable.""" -const sc_statinfo_t = sc_statinfo + For lines the value is exact while for other element types it is only an approximation. -struct sc_stats - mpicomm::MPI_Comm - kv::Ptr{sc_keyvalue_t} - sarray::Ptr{sc_array_t} +# Arguments +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +# Returns +The diameter of the element. +### Prototype +```c +double t8_forest_element_diam (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element); +``` +""" +function t8_forest_element_diam(forest, ltreeid, element) + @ccall libt8.t8_forest_element_diam(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t})::Cdouble end -"""The statistics container allows dynamically adding random variables.""" -const sc_statistics_t = sc_stats - """ - sc_stats_set1(stats, value, variable) + t8_forest_element_volume(forest, ltreeid, element) -Populate a [`sc_statinfo_t`](@ref) structure assuming count=1 and mark it dirty. We set sc_stats_group_all and sc_stats_prio_all internally. +Compute the volume of an element if a geometry for this tree is registered in the forest's cmesh. This is only an approximation. + +!!! note + + This function assumes d-linear interpolation for the tree vertex coordinates. *forest* must be committed when calling this function. # Arguments -* `stats`:\\[out\\] Will be filled with count=1 and the value. -* `value`:\\[in\\] Value used to fill statistics information. -* `variable`:\\[in\\] String to be reported by sc_stats_print. This string is assigned by pointer, not copied. Thus, it must stay alive while stats is in use. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +# Returns +The volume of the element. ### Prototype ```c -void sc_stats_set1 (sc_statinfo_t * stats, double value, const char *variable); +double t8_forest_element_volume (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element); ``` """ -function sc_stats_set1(stats, value, variable) - @ccall libsc.sc_stats_set1(stats::Ptr{sc_statinfo_t}, value::Cdouble, variable::Cstring)::Cvoid +function t8_forest_element_volume(forest, ltreeid, element) + @ccall libt8.t8_forest_element_volume(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t})::Cdouble end """ - sc_stats_set1_ext(stats, value, variable, copy_variable, stats_group, stats_prio) + t8_forest_element_face_area(forest, ltreeid, element, face) -Populate a [`sc_statinfo_t`](@ref) structure assuming count=1 and mark it dirty. +Compute the area of an element's face if a geometry for this tree is registered in the forest's cmesh. Currently implemented for 2D elements only. This is only an approximation. # Arguments -* `stats`:\\[out\\] Will be filled with count=1 and the value. -* `value`:\\[in\\] Value used to fill statistics information. -* `variable`:\\[in\\] String to be reported by sc_stats_print. -* `copy_variable`:\\[in\\] If true, make internal copy of variable. Otherwise just assign the pointer. -* `stats_group`:\\[in\\] Non-negative number or sc_stats_group_all. -* `stats_prio`:\\[in\\] Non-negative number or sc_stats_prio_all. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +* `face`:\\[in\\] A face of *element*. +# Returns +The area of *face*. *forest* must be committed when calling this function. ### Prototype ```c -void sc_stats_set1_ext (sc_statinfo_t * stats, double value, const char *variable, int copy_variable, int stats_group, int stats_prio); +double t8_forest_element_face_area (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, int face); ``` """ -function sc_stats_set1_ext(stats, value, variable, copy_variable, stats_group, stats_prio) - @ccall libsc.sc_stats_set1_ext(stats::Ptr{sc_statinfo_t}, value::Cdouble, variable::Cstring, copy_variable::Cint, stats_group::Cint, stats_prio::Cint)::Cvoid +function t8_forest_element_face_area(forest, ltreeid, element, face) + @ccall libt8.t8_forest_element_face_area(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, face::Cint)::Cdouble end """ - sc_stats_init(stats, variable) + t8_forest_element_face_centroid(forest, ltreeid, element, face, centroid) -Initialize a [`sc_statinfo_t`](@ref) structure assuming count=0 and mark it dirty. This is useful if *stats* will be used to sc_stats_accumulate instances locally before global statistics are computed. We set sc_stats_group_all and sc_stats_prio_all internally. +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. # Arguments -* `stats`:\\[out\\] Will be filled with count 0 and values of 0. -* `variable`:\\[in\\] String to be reported by sc_stats_print. This string is assigned by pointer, not copied. Thus, it must stay alive while stats is in use. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +* `face`:\\[in\\] A face of *element*. +* `centroid`:\\[out\\] On output the centroid of *face*. *forest* must be committed when calling this function. ### Prototype ```c -void sc_stats_init (sc_statinfo_t * stats, const char *variable); +void t8_forest_element_face_centroid (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, int face, double centroid[3]); ``` """ -function sc_stats_init(stats, variable) - @ccall libsc.sc_stats_init(stats::Ptr{sc_statinfo_t}, variable::Cstring)::Cvoid +function t8_forest_element_face_centroid(forest, ltreeid, element, face, centroid) + @ccall libt8.t8_forest_element_face_centroid(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, face::Cint, centroid::Ptr{Cdouble})::Cvoid end """ - sc_stats_init_ext(stats, variable, copy_variable, stats_group, stats_prio) + t8_forest_element_face_normal(forest, ltreeid, element, face, normal) -Initialize a [`sc_statinfo_t`](@ref) structure assuming count=0 and mark it dirty. This is useful if *stats* will be used to sc_stats_accumulate instances locally before global statistics are computed. +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. # Arguments -* `stats`:\\[out\\] Will be filled with count 0 and values of 0. -* `variable`:\\[in\\] String to be reported by sc_stats_print. -* `copy_variable`:\\[in\\] If true, make internal copy of variable. Otherwise just assign the pointer. -* `stats_group`:\\[in\\] Non-negative number or sc_stats_group_all. -* `stats_prio`:\\[in\\] Non-negative number or sc_stats_prio_all. Values increase by importance. +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. +* `element`:\\[in\\] The element. +* `face`:\\[in\\] A face of *element*. +* `normal`:\\[out\\] On output the normal vector of *element* at *face*. *forest* must be committed when calling this function. ### Prototype ```c -void sc_stats_init_ext (sc_statinfo_t * stats, const char *variable, int copy_variable, int stats_group, int stats_prio); +void t8_forest_element_face_normal (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, int face, double normal[3]); ``` """ -function sc_stats_init_ext(stats, variable, copy_variable, stats_group, stats_prio) - @ccall libsc.sc_stats_init_ext(stats::Ptr{sc_statinfo_t}, variable::Cstring, copy_variable::Cint, stats_group::Cint, stats_prio::Cint)::Cvoid +function t8_forest_element_face_normal(forest, ltreeid, element, face, normal) + @ccall libt8.t8_forest_element_face_normal(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, face::Cint, normal::Ptr{Cdouble})::Cvoid end """ - sc_stats_reset(stats, reset_vgp) + t8_forest_set_profiling(forest, set_profiling) -Reset all values to zero, optionally unassign name, group, and priority. +Enable or disable profiling for a forest. If profiling is enabled, runtimes and statistics are collected during forest\\_commit. + +Profiling is disabled by default. The forest must not be committed before calling this function. # Arguments -* `stats`:\\[in,out\\] Variables are zeroed. They can be set again by set1 or accumulate. -* `reset_vgp`:\\[in\\] If true, the variable name string is zeroed and if we did a copy, the copy is freed. If true, group and priority are set to all. If false, we don't touch any of the above. +* `forest`:\\[in,out\\] The forest to be updated. +* `set_profiling`:\\[in\\] If true, profiling will be enabled, if false disabled. +# See also +[`t8_forest_print_profile`](@ref) + ### Prototype ```c -void sc_stats_reset (sc_statinfo_t * stats, int reset_vgp); +void t8_forest_set_profiling (t8_forest_t forest, int set_profiling); ``` """ -function sc_stats_reset(stats, reset_vgp) - @ccall libsc.sc_stats_reset(stats::Ptr{sc_statinfo_t}, reset_vgp::Cint)::Cvoid +function t8_forest_set_profiling(forest, set_profiling) + @ccall libt8.t8_forest_set_profiling(forest::t8_forest_t, set_profiling::Cint)::Cvoid end """ - sc_stats_set_group_prio(stats, stats_group, stats_prio) + t8_forest_compute_profile(forest) -Set/update the group and priority information for a stats item. +Compute the profiling stats. # Arguments -* `stats`:\\[out\\] Only group and stats entries are updated. -* `stats_group`:\\[in\\] Non-negative number or sc_stats_group_all. -* `stats_prio`:\\[in\\] Non-negative number or sc_stats_prio_all. Values increase by importance. +* `forest`:\\[in,out\\] A committed forest. ### Prototype ```c -void sc_stats_set_group_prio (sc_statinfo_t * stats, int stats_group, int stats_prio); +void t8_forest_compute_profile (t8_forest_t forest); ``` """ -function sc_stats_set_group_prio(stats, stats_group, stats_prio) - @ccall libsc.sc_stats_set_group_prio(stats::Ptr{sc_statinfo_t}, stats_group::Cint, stats_prio::Cint)::Cvoid +function t8_forest_compute_profile(forest) + @ccall libt8.t8_forest_compute_profile(forest::t8_forest_t)::Cvoid end """ - sc_stats_accumulate(stats, value) + t8_forest_profile_get_adapt_stats(forest) -Add an instance of the random variable. The counter of the variable is increased by one. The value is added into the present values of the variable. +Return this forest's profiling statistics for adaptation. # Arguments -* `stats`:\\[out\\] Must be dirty. We bump count and values. -* `value`:\\[in\\] Value used to update statistics information. +* `forest`:\\[in\\] A committed forest. +# Returns +The profiling stats of adaptation as pointer to const [`sc_statinfo_t`](@ref). ### Prototype ```c -void sc_stats_accumulate (sc_statinfo_t * stats, double value); +const sc_statinfo_t * t8_forest_profile_get_adapt_stats (t8_forest_t forest); ``` """ -function sc_stats_accumulate(stats, value) - @ccall libsc.sc_stats_accumulate(stats::Ptr{sc_statinfo_t}, value::Cdouble)::Cvoid +function t8_forest_profile_get_adapt_stats(forest) + @ccall libt8.t8_forest_profile_get_adapt_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} end """ - sc_stats_compute(mpicomm, nvars, stats) + t8_forest_profile_get_ghost_stats(forest) +Return this forest's profiling statistics for ghost computations. + +# Arguments +* `forest`:\\[in\\] A committed forest. +# Returns +The profiling stats of ghost computation as pointer to const [`sc_statinfo_t`](@ref). ### Prototype ```c -void sc_stats_compute (sc_MPI_Comm mpicomm, int nvars, sc_statinfo_t * stats); +const sc_statinfo_t * t8_forest_profile_get_ghost_stats (t8_forest_t forest); ``` """ -function sc_stats_compute(mpicomm, nvars, stats) - @ccall libsc.sc_stats_compute(mpicomm::MPI_Comm, nvars::Cint, stats::Ptr{sc_statinfo_t})::Cvoid +function t8_forest_profile_get_ghost_stats(forest) + @ccall libt8.t8_forest_profile_get_ghost_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} end """ - sc_stats_compute1(mpicomm, nvars, stats) + t8_forest_profile_get_partition_stats(forest) +Return this forest's profiling statistics for partitioning. + +# Arguments +* `forest`:\\[in\\] A committed forest. +# Returns +The profiling stats of partitioning as pointer to const [`sc_statinfo_t`](@ref). ### Prototype ```c -void sc_stats_compute1 (sc_MPI_Comm mpicomm, int nvars, sc_statinfo_t * stats); +const sc_statinfo_t * t8_forest_profile_get_partition_stats (t8_forest_t forest); ``` """ -function sc_stats_compute1(mpicomm, nvars, stats) - @ccall libsc.sc_stats_compute1(mpicomm::MPI_Comm, nvars::Cint, stats::Ptr{sc_statinfo_t})::Cvoid +function t8_forest_profile_get_partition_stats(forest) + @ccall libt8.t8_forest_profile_get_partition_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} end """ - sc_stats_print(package_id, log_priority, nvars, stats, full, summary) + t8_forest_profile_get_commit_stats(forest) -Print measured statistics. This function uses the [`SC_LC_GLOBAL`](@ref) log category. That means the default action is to print only on rank 0. Applications can change that by providing a user-defined log handler. All groups and priorities are printed. +Return this forest's profiling statistics for committing. # Arguments -* `package_id`:\\[in\\] Registered package id or -1. -* `log_priority`:\\[in\\] Log priority for output according to sc.h. -* `nvars`:\\[in\\] Number of stats items in input array. -* `stats`:\\[in\\] Input array of stats variable items. -* `full`:\\[in\\] Print full information for every variable. -* `summary`:\\[in\\] Print summary information all on 1 line. +* `forest`:\\[in\\] A committed forest. +# Returns +The profiling stats of commit as pointer to const [`sc_statinfo_t`](@ref). ### Prototype ```c -void sc_stats_print (int package_id, int log_priority, int nvars, sc_statinfo_t * stats, int full, int summary); +const sc_statinfo_t * t8_forest_profile_get_commit_stats (t8_forest_t forest); ``` """ -function sc_stats_print(package_id, log_priority, nvars, stats, full, summary) - @ccall libsc.sc_stats_print(package_id::Cint, log_priority::Cint, nvars::Cint, stats::Ptr{sc_statinfo_t}, full::Cint, summary::Cint)::Cvoid +function t8_forest_profile_get_commit_stats(forest) + @ccall libt8.t8_forest_profile_get_commit_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} end """ - sc_stats_print_ext(package_id, log_priority, nvars, stats, stats_group, stats_prio, full, summary) + t8_forest_profile_get_balance_stats(forest) -Print measured statistics, filter by group and/or priority. This function uses the [`SC_LC_GLOBAL`](@ref) log category. That means the default action is to print only on rank 0. Applications can change that by providing a user-defined log handler. +Return this forest's profiling statistics for balancing. # Arguments -* `package_id`:\\[in\\] Registered package id or -1. -* `log_priority`:\\[in\\] Log priority for output according to sc.h. -* `nvars`:\\[in\\] Number of stats items in input array. -* `stats`:\\[in\\] Input array of stats variable items. -* `stats_group`:\\[in\\] Print only this group. Non-negative or sc_stats_group_all. We skip printing a variable if neither this parameter nor the item's group is all and if the item's group does not match this. -* `stats_prio`:\\[in\\] Print this and higher priorities. Non-negative or sc_stats_prio_all. We skip printing a variable if neither this parameter nor the item's prio is all and if the item's prio is less than this. -* `full`:\\[in\\] Print full information for every variable. This produces multiple lines including minimum, maximum, and standard deviation. If this is false, print one line per variable. -* `summary`:\\[in\\] Print summary information all on 1 line. This always contains all variables. Not affected by stats\\_group and stats\\_prio. +* `forest`:\\[in\\] A committed forest. +# Returns +The profiling stats of balancing as pointer to const [`sc_statinfo_t`](@ref). ### Prototype ```c -void sc_stats_print_ext (int package_id, int log_priority, int nvars, sc_statinfo_t * stats, int stats_group, int stats_prio, int full, int summary); +const sc_statinfo_t * t8_forest_profile_get_balance_stats (t8_forest_t forest); ``` """ -function sc_stats_print_ext(package_id, log_priority, nvars, stats, stats_group, stats_prio, full, summary) - @ccall libsc.sc_stats_print_ext(package_id::Cint, log_priority::Cint, nvars::Cint, stats::Ptr{sc_statinfo_t}, stats_group::Cint, stats_prio::Cint, full::Cint, summary::Cint)::Cvoid +function t8_forest_profile_get_balance_stats(forest) + @ccall libt8.t8_forest_profile_get_balance_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} end """ - sc_statistics_new(mpicomm) + t8_forest_profile_get_balance_rounds_stats(forest) +Return this forest's profiling statistics for the performed balance rounds. + +# Arguments +* `forest`:\\[in\\] A committed forest. +# Returns +The profiling stats of the balance rounds as pointer to const [`sc_statinfo_t`](@ref). ### Prototype ```c -sc_statistics_t *sc_statistics_new (sc_MPI_Comm mpicomm); +const sc_statinfo_t * t8_forest_profile_get_balance_rounds_stats (t8_forest_t forest); ``` """ -function sc_statistics_new(mpicomm) - @ccall libsc.sc_statistics_new(mpicomm::MPI_Comm)::Ptr{sc_statistics_t} +function t8_forest_profile_get_balance_rounds_stats(forest) + @ccall libt8.t8_forest_profile_get_balance_rounds_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} end """ - sc_statistics_destroy(stats) + t8_forest_print_profile(forest) -Destroy a statistics structure. +Print the collected statistics from a forest profile. + +*forest* must be committed before calling this function. # Arguments -* `stats`:\\[in,out\\] Valid object is invalidated. +* `forest`:\\[in\\] The forest. +# See also +[`t8_forest_set_profiling`](@ref) + ### Prototype ```c -void sc_statistics_destroy (sc_statistics_t * stats); +void t8_forest_print_profile (t8_forest_t forest); ``` """ -function sc_statistics_destroy(stats) - @ccall libsc.sc_statistics_destroy(stats::Ptr{sc_statistics_t})::Cvoid +function t8_forest_print_profile(forest) + @ccall libt8.t8_forest_print_profile(forest::t8_forest_t)::Cvoid end """ - sc_statistics_add(stats, name) + t8_forest_profile_get_adapt_time(forest) -Register a statistics variable by name and set its value to 0. This variable must not exist already. +Get the runtime of the last call to t8_forest_adapt. + +# Arguments +* `forest`:\\[in\\] The forest. +# Returns +The runtime of adapt if profiling was activated. 0 otherwise. *forest* must be committed before calling this function. +# See also +[`t8_forest_set_profiling`](@ref), [`t8_forest_set_adapt`](@ref) ### Prototype ```c -void sc_statistics_add (sc_statistics_t * stats, const char *name); +double t8_forest_profile_get_adapt_time (t8_forest_t forest); ``` """ -function sc_statistics_add(stats, name) - @ccall libsc.sc_statistics_add(stats::Ptr{sc_statistics_t}, name::Cstring)::Cvoid +function t8_forest_profile_get_adapt_time(forest) + @ccall libt8.t8_forest_profile_get_adapt_time(forest::t8_forest_t)::Cdouble end """ - sc_statistics_add_empty(stats, name) + t8_forest_profile_get_partition_time(forest, procs_sent) -Register a statistics variable by name and set its count to 0. This variable must not exist already. +Get the runtime of the last call to t8_forest_partition. + +# Arguments +* `forest`:\\[in\\] The forest. +* `procs_sent`:\\[out\\] On output the number of processes that this rank sent elements to in partition if profiling was activated. +# Returns +The runtime of partition if profiling was activated. 0 otherwise. *forest* must be committed before calling this function. +# See also +[`t8_forest_set_profiling`](@ref), [`t8_forest_set_partition`](@ref) ### Prototype ```c -void sc_statistics_add_empty (sc_statistics_t * stats, const char *name); +double t8_forest_profile_get_partition_time (t8_forest_t forest, int *procs_sent); ``` """ -function sc_statistics_add_empty(stats, name) - @ccall libsc.sc_statistics_add_empty(stats::Ptr{sc_statistics_t}, name::Cstring)::Cvoid +function t8_forest_profile_get_partition_time(forest, procs_sent) + @ccall libt8.t8_forest_profile_get_partition_time(forest::t8_forest_t, procs_sent::Ptr{Cint})::Cdouble end """ - sc_statistics_has(stats, name) + t8_forest_profile_get_balance_time(forest, balance_rounds) -Returns true if the stats include a variable with the given name +Get the runtime of the last call to t8_forest_balance. + +# Arguments +* `forest`:\\[in\\] The forest. +* `balance_rounds`:\\[out\\] On output the number of rounds in balance if profiling was activated. +# Returns +The runtime of balance if profiling was activated. 0 otherwise. *forest* must be committed before calling this function. +# See also +[`t8_forest_set_profiling`](@ref), [`t8_forest_set_balance`](@ref) ### Prototype ```c -int sc_statistics_has (sc_statistics_t * stats, const char *name); +double t8_forest_profile_get_balance_time (t8_forest_t forest, int *balance_rounds); ``` """ -function sc_statistics_has(stats, name) - @ccall libsc.sc_statistics_has(stats::Ptr{sc_statistics_t}, name::Cstring)::Cint +function t8_forest_profile_get_balance_time(forest, balance_rounds) + @ccall libt8.t8_forest_profile_get_balance_time(forest::t8_forest_t, balance_rounds::Ptr{Cint})::Cdouble end """ - sc_statistics_set(stats, name, value) + t8_forest_profile_get_ghost_time(forest, ghosts_sent) -Set the value of a statistics variable, see [`sc_stats_set1`](@ref). The variable must previously be added with [`sc_statistics_add`](@ref). This assumes count=1 as in the [`sc_stats_set1`](@ref) function above. +Get the runtime of the last call to t8_forest_ghost_create. + +# Arguments +* `forest`:\\[in\\] The forest. +* `ghosts_sent`:\\[out\\] On output the number of ghost elements sent to other processes if profiling was activated. +# Returns +The runtime of ghost if profiling was activated. 0 otherwise. *forest* must be committed before calling this function. +# See also +[`t8_forest_set_profiling`](@ref), [`t8_forest_set_ghost`](@ref) ### Prototype ```c -void sc_statistics_set (sc_statistics_t * stats, const char *name, double value); +double t8_forest_profile_get_ghost_time (t8_forest_t forest, t8_locidx_t *ghosts_sent); ``` """ -function sc_statistics_set(stats, name, value) - @ccall libsc.sc_statistics_set(stats::Ptr{sc_statistics_t}, name::Cstring, value::Cdouble)::Cvoid +function t8_forest_profile_get_ghost_time(forest, ghosts_sent) + @ccall libt8.t8_forest_profile_get_ghost_time(forest::t8_forest_t, ghosts_sent::Ptr{t8_locidx_t})::Cdouble end """ - sc_statistics_accumulate(stats, name, value) + t8_forest_profile_get_ghostexchange_waittime(forest) -Add an instance of a statistics variable, see [`sc_stats_accumulate`](@ref) The variable must previously be added with [`sc_statistics_add_empty`](@ref). +Get the waittime of the last call to t8_forest_ghost_exchange_data. + +# Arguments +* `forest`:\\[in\\] The forest. +# Returns +The time of ghost\\_exchange\\_data that was spent waiting for other MPI processes, if profiling was activated. 0 otherwise. *forest* must be committed before calling this function. +# See also +[`t8_forest_set_profiling`](@ref), [`t8_forest_ghost_exchange_data`](@ref) ### Prototype ```c -void sc_statistics_accumulate (sc_statistics_t * stats, const char *name, double value); +double t8_forest_profile_get_ghostexchange_waittime (t8_forest_t forest); ``` """ -function sc_statistics_accumulate(stats, name, value) - @ccall libsc.sc_statistics_accumulate(stats::Ptr{sc_statistics_t}, name::Cstring, value::Cdouble)::Cvoid +function t8_forest_profile_get_ghostexchange_waittime(forest) + @ccall libt8.t8_forest_profile_get_ghostexchange_waittime(forest::t8_forest_t)::Cdouble end """ - sc_statistics_compute(stats) + t8_forest_profile_get_cmesh_offsets_runtime(forest) -Compute statistics for all variables, see [`sc_stats_compute`](@ref). +Get the runtime of the last call to t8_forest_partition_create_tree_offsets. + +# Arguments +* `forest`:\\[in\\] The forest. +# Returns +The time *forest* must be committed before calling this function. +# See also +[`t8_forest_set_profiling`](@ref) ### Prototype ```c -void sc_statistics_compute (sc_statistics_t * stats); +double t8_forest_profile_get_cmesh_offsets_runtime (t8_forest_t forest); ``` """ -function sc_statistics_compute(stats) - @ccall libsc.sc_statistics_compute(stats::Ptr{sc_statistics_t})::Cvoid +function t8_forest_profile_get_cmesh_offsets_runtime(forest) + @ccall libt8.t8_forest_profile_get_cmesh_offsets_runtime(forest::t8_forest_t)::Cdouble end """ - sc_statistics_print(stats, package_id, log_priority, full, summary) + t8_forest_profile_get_forest_offsets_runtime(forest) -Print all statistics variables, see [`sc_stats_print`](@ref). +Get the runtime of the last call to t8_forest_partition_create_offsets. + +# Arguments +* `forest`:\\[in\\] The forest. +# Returns +The time *forest* must be committed before calling this function. +# See also +[`t8_forest_set_profiling`](@ref) ### Prototype ```c -void sc_statistics_print (sc_statistics_t * stats, int package_id, int log_priority, int full, int summary); +double t8_forest_profile_get_forest_offsets_runtime (t8_forest_t forest); ``` """ -function sc_statistics_print(stats, package_id, log_priority, full, summary) - @ccall libsc.sc_statistics_print(stats::Ptr{sc_statistics_t}, package_id::Cint, log_priority::Cint, full::Cint, summary::Cint)::Cvoid +function t8_forest_profile_get_forest_offsets_runtime(forest) + @ccall libt8.t8_forest_profile_get_forest_offsets_runtime(forest::t8_forest_t)::Cdouble end """ - t8_forest - -| Field | Note | -| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| rc | Reference counter. | -| set\\_partition\\_offset | Flag indicating whether the partition range was set manually. | -| set\\_first\\_global\\_element | If set\\_partition\\_offset is true, the global ID of the first local element after partitioning. | -| set\\_level | Level to use in new construction. | -| set\\_for\\_coarsening | Change partition to allow for one round of coarsening | -| weight\\_function | Pointer to user defined element weight function. Nullptr for standard, element-based partitioning. | -| cmesh | Coarse mesh to use. | -| scheme | Scheme for element types. | -| maxlevel | The maximum allowed refinement level for elements in this forest. | -| maxlevel\\_existing | If >= 0, the maximum occurring refinement level of a forest element. | -| do\\_dup | Communicator shall be duped. | -| dimension | Dimension inferred from **cmesh**. | -| incomplete\\_trees | Flag to check whether the forest has (potential) incomplete trees. A tree is incomplete if an element has been removed from it. Once an element got removed, the flag sets to 1 (true) and stays. For a committed forest this flag is either true on all ranks or false on all ranks. | -| set\\_from | Temporarily store source forest. | -| from\\_method | Method to derive from **set_from**. | -| set\\_adapt\\_fn | refinement and coarsen function. Called when **from_method** is set to [`T8_FOREST_FROM_ADAPT`](@ref). | -| set\\_adapt\\_recursive | Flag to decide whether coarsen and refine are carried out recursive | -| set\\_balance | Flag to decide whether to forest will be balance in t8_forest_commit. See t8_forest_set_balance. If 0, no balance. If 1 balance with repartitioning, if 2 balance without repartitioning, # See also t8\\_forest\\_balance | -| do\\_ghost | If True, a ghost layer will be created when the forest is committed. | -| ghost\\_type | If a ghost layer will be created, the type of neighbors that count as ghost. | -| ghost\\_algorithm | Controls the algorithm used for ghost. 1 = balanced only. 2 = also unbalanced 3 = top-down search and unbalanced. | -| user\\_data | Pointer for arbitrary user data. # See also [`t8_forest_set_user_data`](@ref). | -| user\\_function | Pointer for arbitrary user function. # See also [`t8_forest_set_user_function`](@ref). | -| t8code\\_data | Pointer for arbitrary data that is used internally. | -| committed | t8_forest_commit called? | -| mpisize | Number of MPI processes. | -| mpirank | Number of this MPI process. | -| first\\_local\\_tree | The global index of the first local tree on this process. If first\\_local\\_tree is larger than last\\_local\\_tree then this processor/forest is empty. See https://github.com/DLR-AMR/t8code/wiki/Tree-indexing | -| last\\_local\\_tree | The global index of the last local tree on this process. -1 if this processor is empty. | -| global\\_num\\_trees | The total number of global trees. | -| trees | The array of trees. | -| ghosts | If not NULL, the ghost elements. # See also [`t8_forest_ghost`](@ref).h | -| element\\_offsets | If partitioned, for each process the global index of its first element. Since it is memory consuming, it is usually only constructed when needed and otherwise unallocated. | -| global\\_first\\_desc | If partitioned, for each process the linear id (at maxlevel) of its first element's first descendant. t8_element_set_linear_id. Stores 0 for empty processes. Since it is memory consuming, it is usually only constructed when needed and otherwise unallocated. | -| tree\\_offsets | If partitioned for each process the global index of its first local tree or -(first local tree) - 1 if the first tree on that process is shared. Since this is memory consuming we only construct it when needed. This array follows the same logic as *tree_offsets* in [`t8_cmesh_t`](@ref) | -| local\\_num\\_leaf\\_elements | Number of leaf elements on this processor. | -| global\\_num\\_leaf\\_elements | Number of leaf elements on all processors. | -| profile | If not NULL, runtimes and statistics about forest\\_commit are stored here. | -| stats | The SC profiling stats of the forest. | -| stats\\_computed | Switch indicating whether the profiling stats have been compute (1) or not (0) | -""" -# This struct is not supposed to be read and modified directly. -# Besides, there is a circular dependency with `t8_forest_t` -# leading to an error output by Julia. -mutable struct t8_forest end - -"""Opaque pointer to a forest implementation.""" -const t8_forest_t = Ptr{t8_forest} + t8_forest_profile_get_first_descendant_runtime(forest) -""" - t8_forest_adapt(forest) +Get the waittime of the last call to t8_forest_partition_create_first_desc. -Adapt a forest. +# Arguments +* `forest`:\\[in\\] The forest. +# Returns +The time *forest* must be committed before calling this function. +# See also +[`t8_forest_set_profiling`](@ref) -# Arguments -* `forest`:\\[in,out\\] The forest to be adapted ### Prototype ```c -void t8_forest_adapt (t8_forest_t forest); +double t8_forest_profile_get_first_descendant_runtime (t8_forest_t forest); ``` """ -function t8_forest_adapt(forest) - @ccall libt8.t8_forest_adapt(forest::t8_forest_t)::Cvoid +function t8_forest_profile_get_first_descendant_runtime(forest) + @ccall libt8.t8_forest_profile_get_first_descendant_runtime(forest::t8_forest_t)::Cdouble end """ - t8_tree + t8_vtk_data_type_t -The t8 tree datatype +TODO: Add support for integer data type. -| Field | Note | -| :---------------- | :----------------------------------------------------------------- | -| leaf\\_elements | locally stored leaf elements | -| eclass | The element class of this tree | -| first\\_desc | first local descendant | -| last\\_desc | last local descendant | -| elements\\_offset | cumulative sum over earlier trees on this processor (locals only) | +| Enumerator | Note | +| :---------------- | :---------------------------- | +| T8\\_VTK\\_SCALAR | One double value per element | +| T8\\_VTK\\_VECTOR | 3 double values per element | """ -struct t8_tree - leaf_elements::t8_element_array_t - eclass::t8_eclass_t - first_desc::Ptr{t8_element_t} - last_desc::Ptr{t8_element_t} - elements_offset::t8_locidx_t +@cenum t8_vtk_data_type_t::UInt32 begin + T8_VTK_SCALAR = 0 + T8_VTK_VECTOR = 1 end -"""Opaque pointer to a tree implementation.""" -const t8_tree_t = Ptr{t8_tree} - """ - t8_ghost_type_t + t8_vtk_data_field_t -This type controls, which neighbors count as ghost elements. Currently, we support face-neighbors. Vertex and edge neighbors will eventually be added. +A data field for VTK output. This struct is used to store data that is written to the VTK files. It contains the type of the data, a description, and the actual data array. -| Enumerator | Note | -| :-------------------- | :---------------------------------------------------------------- | -| T8\\_GHOST\\_NONE | Do not create ghost layer. | -| T8\\_GHOST\\_FACES | Consider all face (codimension 1) neighbors. | -| T8\\_GHOST\\_EDGES | Consider all edge (codimension 2) and face neighbors. | -| T8\\_GHOST\\_VERTICES | Consider all vertex (codimension 3) and edge and face neighbors. | +| Field | Note | +| :---------- | :----------------------------------------- | +| type | Describes of which type the data array is | +| description | String that describes the data. | """ -@cenum t8_ghost_type_t::UInt32 begin - T8_GHOST_NONE = 0 - T8_GHOST_FACES = 1 - T8_GHOST_EDGES = 2 - T8_GHOST_VERTICES = 3 +struct t8_vtk_data_field_t + type::t8_vtk_data_type_t + description::NTuple{8192, Cchar} + data::Ptr{Cdouble} end -# typedef void ( * t8_generic_function_pointer ) ( void ) -""" -This typedef is needed as a helper construct to properly be able to define a function that returns a pointer to a void fun(void) function. - -# See also -[`t8_forest_get_user_function`](@ref). """ -const t8_generic_function_pointer = Ptr{Cvoid} + t8_write_pvtu(filename, num_procs, write_tree, write_rank, write_level, write_id, num_data, data) -# typedef double ( t8_weight_fcn_t ) ( t8_forest_t , t8_locidx_t , t8_locidx_t ) -"""The prototype of a weight function for the partition algorithm. The function should be pure, and return a positive weight given a forest, a local tree index and an element index within the local tree""" -const t8_weight_fcn_t = Cvoid +Writes the pvtu header file that links to the processor local files. It is used by the cmesh and forest vtk routines. This function should only be called by one process. Return 0 on success. -# typedef void ( * t8_forest_replace_t ) ( t8_forest_t forest_old , t8_forest_t forest_new , t8_locidx_t which_tree , const t8_eclass_t tree_class , const t8_scheme_c * scheme , const int refine , const int num_outgoing , const t8_locidx_t first_outgoing , const int num_incoming , const t8_locidx_t first_incoming ) +### Prototype +```c +int t8_write_pvtu (const char *filename, int num_procs, int write_tree, int write_rank, int write_level, int write_id, int num_data, t8_vtk_data_field_t *data); +``` """ -Callback function prototype to replace one set of elements with another. +function t8_write_pvtu(filename, num_procs, write_tree, write_rank, write_level, write_id, num_data, data) + @ccall libt8.t8_write_pvtu(filename::Cstring, num_procs::Cint, write_tree::Cint, write_rank::Cint, write_level::Cint, write_id::Cint, num_data::Cint, data::Ptr{t8_vtk_data_field_t})::Cint +end -This is used by the replace routine which can be called after adapt, when the elements of an existing, valid forest are changed. The callback allows the user to make changes to the elements of the new forest that are either refined, coarsened or the same as elements in the old forest. +""" + t8_forest_save(forest) -If an element is being refined, *refine* and *num_outgoing* will be 1 and *num_incoming* will be the number of children. If a family is being coarsened, *refine* will be -1, *num_outgoing* will be the number of family members and *num_incoming* will be 1. If an element is being removed, *refine* and *num_outgoing* will be 1 and *num_incoming* will be 0. Else *refine* will be 0 and *num_outgoing* and *num_incoming* will both be 1. +TODO: implement -# Arguments -* `forest_old`:\\[in\\] The forest that is adapted -* `forest_new`:\\[in,out\\] The forest that is newly constructed from *forest_old* -* `which_tree`:\\[in\\] The local tree containing *first_outgoing* and *first_incoming* -* `tree_class`:\\[in\\] The eclass of the local tree containing *first_outgoing* and *first_incoming* -* `scheme`:\\[in\\] The scheme of the forest -* `refine`:\\[in\\] -1 if family in *forest_old* got coarsened, 0 if element has not been touched, 1 if element got refined and -2 if element got removed. See return of [`t8_forest_adapt_t`](@ref). -* `num_outgoing`:\\[in\\] The number of outgoing elements. -* `first_outgoing`:\\[in\\] The tree local index of the first outgoing element. 0 <= first\\_outgoing < which\\_tree->num\\_elements -* `num_incoming`:\\[in\\] The number of incoming elements. -* `first_incoming`:\\[in\\] The tree local index of the first incoming element. 0 <= first\\_incom < new\\_which\\_tree->num\\_elements -# See also -[`t8_forest_iterate_replace`](@ref) +### Prototype +```c +void t8_forest_save (t8_forest_t forest); +``` """ -const t8_forest_replace_t = Ptr{Cvoid} +function t8_forest_save(forest) + @ccall libt8.t8_forest_save(forest::t8_forest_t)::Cvoid +end -# typedef int ( * t8_forest_adapt_t ) ( t8_forest_t forest , t8_forest_t forest_from , t8_locidx_t which_tree , const t8_eclass_t tree_class , t8_locidx_t lelement_id , const t8_scheme_c * scheme , const int is_family , const int num_elements , t8_element_t * elements [ ] ) """ -Callback function prototype to decide for refining and coarsening. If *is_family* equals 1, the first *num_elements* in *elements* form a family and we decide whether this family should be coarsened or only the first element should be refined. Otherwise *is_family* must equal zero and we consider the first entry of the element array for refinement. Entries of the element array beyond the first *num_elements* are undefined. + t8_forest_write_vtk_ext(forest, fileprefix, write_treeid, write_mpirank, write_level, write_element_id, write_ghosts, write_curved, do_not_use_API, num_data, data) + +Write the forest in a parallel vtu format. Extended version. See # Arguments -* `forest`:\\[in\\] The forest to which the new elements belong. -* `forest_from`:\\[in\\] The forest that is adapted. -* `which_tree`:\\[in\\] The local tree containing *elements*. -* `tree_class`:\\[in\\] The eclass of *which_tree*. -* `lelement_id`:\\[in\\] The local element id in *forest_from* in the tree of the current element. -* `scheme`:\\[in\\] The scheme of the forest. -* `is_family`:\\[in\\] If 1, the first *num_elements* entries in *elements* form a family. If 0, they do not. -* `num_elements`:\\[in\\] The number of entries in *elements* that are defined -* `elements`:\\[in\\] Pointers to a family or, if *is_family* is zero, pointer to one element. +* `forest`:\\[in\\] The forest to write. +* `fileprefix`:\\[in\\] The prefix of the files where the vtk will be stored. The master file is then fileprefix.pvtu and the process with rank r writes in the file fileprefix\\_r.vtu. +* `write_treeid`:\\[in\\] If true, the global tree id is written for each element. +* `write_mpirank`:\\[in\\] If true, the mpirank is written for each element. +* `write_level`:\\[in\\] If true, the refinement level is written for each element. +* `write_element_id`:\\[in\\] If true, the global element id is written for each element. +* `write_ghosts`:\\[in\\] If true, each process additionally writes its ghost elements. For ghost element the treeid is -1. +* `write_curved`:\\[in\\] If true, write the elements as curved element types from vtk. +* `do_not_use_API`:\\[in\\] Do not use the VTK API, even if linked and available. +* `num_data`:\\[in\\] Number of user defined double valued data fields to write. +* `data`:\\[in\\] Array of [`t8_vtk_data_field_t`](@ref) of length *num_data* providing the user defined per element data. If scalar and vector fields are used, all scalar fields must come first in the array. # Returns -1 if the first entry in *elements* should be refined, -1 if the family *elements* shall be coarsened, -2 if the first entry in *elements* should be removed, 0 else. +True if successful, false if not (process local). See also +# See also +[`t8_forest_write_vtk`](@ref) for the standard version of this function. Writes one master .pvtu file and each process writes in its own .vtu file. If linked and not otherwise specified, the VTK API is used. If the VTK library is not linked, an ASCII file is written. This may change in accordance with *write_ghosts*, *write_curved* and *do_not_use_API*, because the export of ghosts is not yet available with the VTK API and the export of curved elements is not available with the inbuilt function to write ASCII files. The function will for example still use the VTK API to satisfy *write_curved*, even if *do_not_use_API* is set to true. Forest must be committed when calling this function. This function is collective and must be called on each process., [`t8_forest_write_vtk`](@ref) . + +### Prototype +```c +int t8_forest_write_vtk_ext (t8_forest_t forest, const char *fileprefix, const int write_treeid, const int write_mpirank, const int write_level, const int write_element_id, const int write_ghosts, const int write_curved, int do_not_use_API, const int num_data, t8_vtk_data_field_t *data); +``` """ -const t8_forest_adapt_t = Ptr{Cvoid} +function t8_forest_write_vtk_ext(forest, fileprefix, write_treeid, write_mpirank, write_level, write_element_id, write_ghosts, write_curved, do_not_use_API, num_data, data) + @ccall libt8.t8_forest_write_vtk_ext(forest::t8_forest_t, fileprefix::Cstring, write_treeid::Cint, write_mpirank::Cint, write_level::Cint, write_element_id::Cint, write_ghosts::Cint, write_curved::Cint, do_not_use_API::Cint, num_data::Cint, data::Ptr{t8_vtk_data_field_t})::Cint +end """ - t8_forest_init(pforest) + t8_forest_write_vtk(forest, fileprefix) -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 +Write the forest in a parallel vtu format. Writes one master .pvtu file and each process writes in its own .vtu file. If linked, the VTK API is used. If the VTK library is not linked, an ASCII file is written. This function writes the forest elements, the tree id, element level, mpirank and element id as data. Forest must be committed when calling this function. This function is collective and must be called on each process. For more options use # Arguments -* `pforest`:\\[in,out\\] On input, this pointer must be non-NULL. On return, this pointer set to the new forest. +* `forest`:\\[in\\] The forest to write. +* `fileprefix`:\\[in\\] The prefix of the files where the vtk will be stored. The master file is then fileprefix.pvtu and the process with rank r writes in the file fileprefix\\_r.vtu. +# Returns +True if successful, false if not (process local). # See also -t8\\_forest\\_set\\_mpicomm, t8_forest_set_cmesh, and t8_forest_set_scheme, or to call one of t8_forest_set_copy, t8_forest_set_adapt, or t8_forest_set_partition. It is illegal to mix these calls, or to call more than one of the three latter functions Then it needs to be set up with t8_forest_commit. +[`t8_forest_write_vtk_ext`](@ref) ### Prototype ```c -void t8_forest_init (t8_forest_t *pforest); +int t8_forest_write_vtk (t8_forest_t forest, const char *fileprefix); ``` """ -function t8_forest_init(pforest) - @ccall libt8.t8_forest_init(pforest::Ptr{t8_forest_t})::Cvoid +function t8_forest_write_vtk(forest, fileprefix) + @ccall libt8.t8_forest_write_vtk(forest::t8_forest_t, fileprefix::Cstring)::Cint end """ - t8_forest_is_initialized(forest) + t8_forest_adapt(forest) -Check whether a forest is not NULL, initialized and not committed. In addition, it asserts that the forest is consistent as much as possible. +Adapt a forest. # Arguments -* `forest`:\\[in\\] This forest is examined. May be NULL. -# Returns -True if forest is not NULL, t8_forest_init has been called on it, but not t8_forest_commit. False otherwise. +* `forest`:\\[in,out\\] The forest to be adapted ### Prototype ```c -int t8_forest_is_initialized (t8_forest_t forest); +void t8_forest_adapt (t8_forest_t forest); ``` """ -function t8_forest_is_initialized(forest) - @ccall libt8.t8_forest_is_initialized(forest::t8_forest_t)::Cint +function t8_forest_adapt(forest) + @ccall libt8.t8_forest_adapt(forest::t8_forest_t)::Cvoid +end + +""" + t8_profile + +This struct holds profiling information, such as timings or statistics about communication. + +| Field | Note | +| :----------------------------- | :------------------------------------------------------------------------------------------------------------- | +| partition\\_elements\\_shipped | The number of elements this process has sent to other in the last partition call. | +| partition\\_elements\\_recv | The number of elements this process has received from other in the last partition call. | +| partition\\_bytes\\_sent | The total number of bytes sent to other processes in the last partition call. | +| partition\\_procs\\_sent | The number of different processes this process has send local elements to in the last partition call. | +| ghosts\\_shipped | The number of ghost elements this process has sent to other processes. | +| ghosts\\_received | The number of ghost elements this process has received from other processes. | +| ghosts\\_remotes | The number of processes this process have sent ghost elements to (and received from). | +| balance\\_rounds | The number of iterations during balance. | +| adapt\\_runtime | The runtime of the last call to [`t8_forest_adapt`](@ref) (not counting adaptation in t8\\_forest\\_balance). | +| partition\\_runtime | The runtime of the last call to *t8_cmesh_partition* (not count in partition in t8\\_forest\\_balance). | +| ghost\\_runtime | The runtime of the last call to [`t8_forest_ghost_create`](@ref). | +| ghost\\_waittime | Amount of synchronisation time in ghost. | +| balance\\_runtime | The runtime of the last call to *t8_forest_balance*. | +| commit\\_runtime | The runtime of the last call to [`t8_cmesh_commit`](@ref). | +| cmesh\\_offsets\\_runtime | The runtime of the last call to [`t8_forest_partition_create_tree_offsets`](@ref). | +| forest\\_offsets\\_runtime | The runtime of the last call to [`t8_forest_partition_create_offsets`](@ref). | +| first\\_descendant\\_runtime | The runtime of the last call to [`t8_forest_partition_create_first_desc`](@ref). | +""" +struct t8_profile + partition_elements_shipped::t8_locidx_t + partition_elements_recv::t8_locidx_t + partition_bytes_sent::Csize_t + partition_procs_sent::Cint + ghosts_shipped::t8_locidx_t + ghosts_received::t8_locidx_t + ghosts_remotes::Cint + balance_rounds::Cint + adapt_runtime::Cdouble + partition_runtime::Cdouble + ghost_runtime::Cdouble + ghost_waittime::Cdouble + balance_runtime::Cdouble + commit_runtime::Cdouble + cmesh_offsets_runtime::Cdouble + forest_offsets_runtime::Cdouble + first_descendant_runtime::Cdouble +end + +"""This struct holds profiling information, such as timings or statistics about communication.""" +const t8_profile_t = t8_profile + +""" + t8_forest_ghost + +This struct stores various information about a forest's ghost elements and ghost trees. + +| Field | Note | +| :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| rc | The reference counter. | +| num\\_ghosts\\_elements | The count of non-local ghost leaf elements | +| num\\_remote\\_elements | The count of local leaf elements that are ghost to another process. | +| ghost\\_type | Describes which neighbors are considered ghosts. | +| ghost\\_trees | ghost tree data: global\\_id. eclass. elements. In linear id order | +| global\\_tree\\_to\\_ghost\\_tree | Indexes into ghost\\_trees. Given a global tree id I give the index i such that the tree is in ghost\\_trees[i] | +| process\\_offsets | Given a process, return the first ghost tree and within it the first element of that process. | +| remote\\_ghosts | array of local trees that have ghost elements for another process. for each tree an array of [`t8_element_t`](@ref) * of the local ghost elements. Also an array of [`t8_locidx_t`](@ref) of the local indices of these elements within the tree. It is a hash table, hashed with the rank of a remote process. Sorted within each process by linear id. | +| remote\\_processes | The ranks of the processes for which local elements are ghost. Array of int's. | +| glo\\_tree\\_mempool | The global tree memory pool. | +| proc\\_offset\\_mempool | The process offset memory pool. | +""" +struct t8_forest_ghost + rc::t8_refcount_t + num_ghosts_elements::t8_locidx_t + num_remote_elements::t8_locidx_t + ghost_type::t8_ghost_type_t + ghost_trees::Ptr{sc_array_t} + global_tree_to_ghost_tree::Ptr{sc_hash_t} + process_offsets::Ptr{sc_hash_t} + remote_ghosts::Ptr{sc_hash_array_t} + remote_processes::Ptr{sc_array_t} + glo_tree_mempool::Ptr{sc_mempool_t} + proc_offset_mempool::Ptr{sc_mempool_t} end +const t8_forest_ghost_t = Ptr{t8_forest_ghost} + +"""If a forest is to be derived from another forest, there are different possibilities how the original forest is modified. Currently we support: Copying, adapting, partitioning, and balancing a forest. The latter 3 can be combined, in which case the order is 1. Adapt, 2. Partition, 3. Balance. We store the methods in an int8\\_t and use these defines to distinguish between them.""" +const t8_forest_from_t = Int8 + +"""This structure is private to the implementation.""" +const t8_forest_struct_t = t8_forest + +"""The t8 tree datatype""" +const t8_tree_struct_t = t8_tree + +"""This struct holds profiling information, such as timings or statistics about communication.""" +const t8_profile_struct_t = t8_profile + +"""This struct stores various information about a forest's ghost elements and ghost trees.""" +const t8_forest_ghost_struct_t = t8_forest_ghost + """ - t8_forest_is_committed(forest) + t8_forest_ghost_init(pghost, ghost_type) -Check whether a forest is not NULL, initialized and committed. In addition, it asserts that the forest is consistent as much as possible. +Initialize a ghost type of a forest. # Arguments -* `forest`:\\[in\\] This forest is examined. May be NULL. -# Returns -True if forest is not NULL and t8_forest_init has been called on it as well as t8_forest_commit. False otherwise. +* `pghost`:\\[out\\] Pointer to the forest's ghost. +* `ghost_type`:\\[in\\] The type of the ghost elements, +# See also +[`t8_ghost_type_t`](@ref). + ### Prototype ```c -int t8_forest_is_committed (t8_forest_t forest); +void t8_forest_ghost_init (t8_forest_ghost_t *pghost, t8_ghost_type_t ghost_type); ``` """ -function t8_forest_is_committed(forest) - @ccall libt8.t8_forest_is_committed(forest::t8_forest_t)::Cint +function t8_forest_ghost_init(pghost, ghost_type) + @ccall libt8.t8_forest_ghost_init(pghost::Ptr{t8_forest_ghost_t}, ghost_type::t8_ghost_type_t)::Cvoid end """ - t8_forest_no_overlap(forest) - -Check whether the forest has local overlapping elements. - -!!! note + t8_forest_ghost_num_trees(forest) - This function is collective, but only checks local overlapping on each process. +Return the number of trees in a ghost. # Arguments -* `forest`:\\[in\\] The forest to consider. +* `forest`:\\[in\\] The forest. # Returns -True if *forest* has no elements which are inside each other. -# See also -[`t8_forest_partition_test_boundary_element`](@ref) if you also want to test for global overlap across the process boundaries. - +The number of trees in the forest's ghost (or 0 if ghost structure does not exist). ### Prototype ```c -int t8_forest_no_overlap (t8_forest_t forest); +t8_locidx_t t8_forest_ghost_num_trees (const t8_forest_t forest); ``` """ -function t8_forest_no_overlap(forest) - @ccall libt8.t8_forest_no_overlap(forest::t8_forest_t)::Cint +function t8_forest_ghost_num_trees(forest) + @ccall libt8.t8_forest_ghost_num_trees(forest::t8_forest_t)::t8_locidx_t end """ - t8_forest_is_equal(forest_a, forest_b) + t8_forest_ghost_get_tree_element_offset(forest, lghost_tree) -Check whether two committed forests have the same local elements. +Return the element offset of a ghost tree. !!! note - This function is not collective. It only returns the state on the current rank. + forest must be committed before calling this function. # Arguments -* `forest_a`:\\[in\\] The first forest. -* `forest_b`:\\[in\\] The second forest. +* `forest`:\\[in\\] The forest with constructed ghost layer. +* `lghost_tree`:\\[in\\] A local ghost id of a ghost tree. # Returns -True if *forest_a* and *forest_b* do have the same number of local trees and each local tree has the same elements, that is t8_element_is_equal returns true for each pair of elements of *forest_a* and *forest_b*. -### Prototype -```c -int t8_forest_is_equal (t8_forest_t forest_a, t8_forest_t forest_b); -``` -""" -function t8_forest_is_equal(forest_a, forest_b) - @ccall libt8.t8_forest_is_equal(forest_a::t8_forest_t, forest_b::t8_forest_t)::Cint -end - -""" - t8_forest_set_cmesh(forest, cmesh, comm) - +The element offset of this ghost tree within the set of local ghost elements. ### Prototype ```c -void t8_forest_set_cmesh (t8_forest_t forest, t8_cmesh_t cmesh, sc_MPI_Comm comm); +t8_locidx_t t8_forest_ghost_get_tree_element_offset (t8_forest_t forest, t8_locidx_t lghost_tree); ``` """ -function t8_forest_set_cmesh(forest, cmesh, comm) - @ccall libt8.t8_forest_set_cmesh(forest::t8_forest_t, cmesh::t8_cmesh_t, comm::MPI_Comm)::Cvoid +function t8_forest_ghost_get_tree_element_offset(forest, lghost_tree) + @ccall libt8.t8_forest_ghost_get_tree_element_offset(forest::t8_forest_t, lghost_tree::t8_locidx_t)::t8_locidx_t end """ - t8_forest_set_scheme(forest, scheme) + t8_forest_ghost_tree_num_leaf_elements(forest, lghost_tree) -Set the element scheme associated to a forest. By default, the forest takes ownership of the scheme such that it will be destroyed when the forest is destroyed. To keep ownership of the scheme, call t8_scheme_ref before passing it to t8_forest_set_scheme. This means that it is ILLEGAL to continue using scheme or dereferencing it UNLESS it is referenced directly before passing it into this function. +Given an index in the ghost\\_tree array, return this tree's number of leaf elements # Arguments -* `forest`:\\[in,out\\] The forest whose scheme variable will be set. -* `scheme`:\\[in\\] The scheme to be set. We take ownership. This can be prevented by referencing **scheme**. +* `forest`:\\[in\\] The *forest*. Ghost layer must exist. +* `lghost_tree`:\\[in\\] The ghost tree id of a ghost tree. +# Returns +The number of ghost leaf elements of the tree. *forest* must be committed before calling this function. ### Prototype ```c -void t8_forest_set_scheme (t8_forest_t forest, const t8_scheme_c *scheme); +t8_locidx_t t8_forest_ghost_tree_num_leaf_elements (t8_forest_t forest, t8_locidx_t lghost_tree); ``` """ -function t8_forest_set_scheme(forest, scheme) - @ccall libt8.t8_forest_set_scheme(forest::t8_forest_t, scheme::Ptr{t8_scheme_c})::Cvoid +function t8_forest_ghost_tree_num_leaf_elements(forest, lghost_tree) + @ccall libt8.t8_forest_ghost_tree_num_leaf_elements(forest::t8_forest_t, lghost_tree::t8_locidx_t)::t8_locidx_t end """ - t8_forest_set_level(forest, level) - -Set the initial refinement level to be used when **forest** is committed. - -!!! note + t8_forest_ghost_get_tree_leaf_elements(forest, lghost_tree) - This setting cannot be combined with any of the derived forest methods (t8_forest_set_copy, t8_forest_set_adapt, t8_forest_set_partition, and t8_forest_set_balance) and overwrites any of these settings. If this function is used, then the forest is created from scratch as a uniform refinement of the specified cmesh (t8_forest_set_cmesh, t8_forest_set_scheme). +Get a pointer to the ghost leaf element array of a ghost tree. # Arguments -* `forest`:\\[in,out\\] The forest whose level will be set. -* `level`:\\[in\\] The initial refinement level of **forest**, when it is committed. +* `forest`:\\[in\\] The forest. Ghost layer must exist. +* `lghost_tree`:\\[in\\] The ghost tree id of a ghost tree. 0 <= *lghost_tree* < num\\_ghost\\_trees +# Returns +A pointer to the array of ghost leaf elements of the tree. *forest* must be committed before calling this function. ### Prototype ```c -void t8_forest_set_level (t8_forest_t forest, int level); +t8_element_array_t * t8_forest_ghost_get_tree_leaf_elements (const t8_forest_t forest, const t8_locidx_t lghost_tree); ``` """ -function t8_forest_set_level(forest, level) - @ccall libt8.t8_forest_set_level(forest::t8_forest_t, level::Cint)::Cvoid +function t8_forest_ghost_get_tree_leaf_elements(forest, lghost_tree) + @ccall libt8.t8_forest_ghost_get_tree_leaf_elements(forest::t8_forest_t, lghost_tree::t8_locidx_t)::Ptr{t8_element_array_t} end """ - t8_forest_set_copy(forest, from) - -Set a forest as source for copying on committing. By default, the forest takes ownership of the source **from** such that it will be destroyed on calling t8_forest_commit. To keep ownership of **from**, call t8_forest_ref before passing it into this function. This means that it is ILLEGAL to continue using **from** or dereferencing it UNLESS it is referenced directly before passing it into this function. - -!!! note + t8_forest_ghost_get_ghost_treeid(forest, gtreeid) - This setting cannot be combined with t8_forest_set_adapt, t8_forest_set_partition, or t8_forest_set_balance and overwrites these settings. +Given a global tree compute the ghost local tree id of it. # Arguments -* `forest`:\\[in,out\\] The forest. -* `from`:\\[in\\] A second forest from which *forest* will be copied in t8_forest_commit. +* `forest`:\\[in\\] The forest. Ghost layer must exist. +* `gtreeid`:\\[in\\] A global tree in *forest*. +# Returns +If *gtreeid* is also a ghost tree, the index in the ghost->ghost\\_trees array of the tree. Otherwise a negative number. *forest* must be committed before calling this function. +# See also +https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. + ### Prototype ```c -void t8_forest_set_copy (t8_forest_t forest, const t8_forest_t from); +t8_locidx_t t8_forest_ghost_get_ghost_treeid (t8_forest_t forest, t8_gloidx_t gtreeid); ``` """ -function t8_forest_set_copy(forest, from) - @ccall libt8.t8_forest_set_copy(forest::t8_forest_t, from::t8_forest_t)::Cvoid +function t8_forest_ghost_get_ghost_treeid(forest, gtreeid) + @ccall libt8.t8_forest_ghost_get_ghost_treeid(forest::t8_forest_t, gtreeid::t8_gloidx_t)::t8_locidx_t end """ - t8_forest_set_adapt(forest, set_from, adapt_fn, recursive) - -Set a source forest with an adapt function to be adapted on committing. By default, the forest takes ownership of the source **set_from** such that it will be destroyed on calling t8_forest_commit. To keep ownership of **set_from**, call t8_forest_ref before passing it into this function. This means that it is ILLEGAL to continue using **set_from** or dereferencing it UNLESS it is referenced directly before passing it into this function. - -!!! note - - This setting can be combined with t8_forest_set_partition and t8_forest_set_balance. The order in which these operations are executed is always 1) Adapt 2) Partition 3) Balance. - -!!! note + t8_forest_ghost_get_tree_class(forest, lghost_tree) - This setting may not be combined with t8_forest_set_copy and overwrites this setting. +Given an index in the ghost\\_tree array, return this tree's element class. # Arguments -* `forest`:\\[in,out\\] The forest -* `set_from`:\\[in\\] The source forest from which **forest** will be adapted. We take ownership. This can be prevented by referencing **set_from**. If NULL, a previously (or later) set forest will be taken (t8_forest_set_partition, t8_forest_set_balance). -* `adapt_fn`:\\[in\\] The adapt function used on committing. -* `recursive`:\\[in\\] A flag specifying whether adaptation is to be done recursively or not. If the value is zero, adaptation is not recursive and it is recursive otherwise. +* `forest`:\\[in\\] A committed forest. +* `lghost_tree`:\\[in\\] The tree's local index in the ghost\\_tree array. +# Returns +The element class of the given tree. ### Prototype ```c -void t8_forest_set_adapt (t8_forest_t forest, const t8_forest_t set_from, t8_forest_adapt_t adapt_fn, const int recursive); +t8_eclass_t t8_forest_ghost_get_tree_class (const t8_forest_t forest, const t8_locidx_t lghost_tree); ``` """ -function t8_forest_set_adapt(forest, set_from, adapt_fn, recursive) - @ccall libt8.t8_forest_set_adapt(forest::t8_forest_t, set_from::t8_forest_t, adapt_fn::t8_forest_adapt_t, recursive::Cint)::Cvoid +function t8_forest_ghost_get_tree_class(forest, lghost_tree) + @ccall libt8.t8_forest_ghost_get_tree_class(forest::t8_forest_t, lghost_tree::t8_locidx_t)::t8_eclass_t end """ - t8_forest_set_user_data(forest, data) + t8_forest_ghost_get_global_treeid(forest, lghost_tree) -Set the user data of a forest. This can i.e. be used to pass user defined arguments to the adapt routine. +Given a local ghost tree compute the global tree id of it. # Arguments -* `forest`:\\[in,out\\] The forest -* `data`:\\[in\\] A pointer to user data. t8code will never touch the data. The forest does not need be committed before calling this function. +* `forest`:\\[in\\] The forest. Ghost layer must exist. +* `lghost_tree`:\\[in\\] The ghost tree id of a ghost tree. (0 <= *lghost_tree* < num\\_ghost\\_trees) +# Returns +The global id of the local ghost tree *lghost_tree*. *forest* must be committed before calling this function. # See also -[`t8_forest_get_user_data`](@ref) +https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. ### Prototype ```c -void t8_forest_set_user_data (t8_forest_t forest, void *data); +t8_gloidx_t t8_forest_ghost_get_global_treeid (const t8_forest_t forest, const t8_locidx_t lghost_tree); ``` """ -function t8_forest_set_user_data(forest, data) - @ccall libt8.t8_forest_set_user_data(forest::t8_forest_t, data::Ptr{Cvoid})::Cvoid +function t8_forest_ghost_get_global_treeid(forest, lghost_tree) + @ccall libt8.t8_forest_ghost_get_global_treeid(forest::t8_forest_t, lghost_tree::t8_locidx_t)::t8_gloidx_t end """ - t8_forest_get_user_data(forest) + t8_forest_ghost_get_leaf_element(forest, lghost_tree, lelement) -Return the user data pointer associated with a forest. +Given an index into the ghost\\_trees array and for that tree an element index, return the corresponding element. # Arguments -* `forest`:\\[in\\] The forest. +* `forest`:\\[in\\] The *forest*. Ghost layer must exist. +* `lghost_tree`:\\[in\\] The ghost tree id of a ghost tree. +* `lelement`:\\[in\\] The local id of the ghost leaf element considered. # Returns -The user data pointer of *forest*. The forest does not need be committed before calling this function. -# See also -[`t8_forest_set_user_data`](@ref) - +A pointer to the ghost leaf element. *forest* must be committed before calling this function. ### Prototype ```c -void * t8_forest_get_user_data (const t8_forest_t forest); +t8_element_t * t8_forest_ghost_get_leaf_element (t8_forest_t forest, t8_locidx_t lghost_tree, t8_locidx_t lelement); ``` """ -function t8_forest_get_user_data(forest) - @ccall libt8.t8_forest_get_user_data(forest::t8_forest_t)::Ptr{Cvoid} +function t8_forest_ghost_get_leaf_element(forest, lghost_tree, lelement) + @ccall libt8.t8_forest_ghost_get_leaf_element(forest::t8_forest_t, lghost_tree::t8_locidx_t, lelement::t8_locidx_t)::Ptr{t8_element_t} end """ - t8_forest_set_user_function(forest, _function) + t8_forest_element_is_ghost(forest, element, lghost_tree) -Set the user function pointer of a forest. This can i.e. be used to pass user defined functions to the adapt routine. +Query whether a given element is a ghost of a certrain tree in a forest. !!! note - *function* can be an arbitrary function with return value and parameters of your choice. When accessing it with t8_forest_get_user_function you should cast it into the proper type. + *forest* must be committed before calling this function. # Arguments -* `forest`:\\[in,out\\] The forest -* `function`:\\[in\\] A pointer to a user defined function. t8code will never touch the function. The forest does not need be committed before calling this function. -# See also -[`t8_forest_get_user_function`](@ref) - +* `forest`:\\[in\\] The forest. +* `element`:\\[in\\] An element of a ghost tree in *forest*. +* `lghost_tree`:\\[in\\] A local ghost tree id of *forest*. (0 <= *lghost_tree* < num\\_ghost\\_trees) +# Returns +True (non-zero) if and only if *element* is a ghost in *lghost_tree* of *forest*. ### Prototype ```c -void t8_forest_set_user_function (t8_forest_t forest, t8_generic_function_pointer function); +int t8_forest_element_is_ghost (const t8_forest_t forest, const t8_element_t *element, const t8_locidx_t lghost_tree); ``` """ -function t8_forest_set_user_function(forest, _function) - @ccall libt8.t8_forest_set_user_function(forest::t8_forest_t, _function::t8_generic_function_pointer)::Cvoid +function t8_forest_element_is_ghost(forest, element, lghost_tree) + @ccall libt8.t8_forest_element_is_ghost(forest::t8_forest_t, element::Ptr{t8_element_t}, lghost_tree::t8_locidx_t)::Cint end """ - t8_forest_get_user_function(forest) + t8_forest_ghost_get_remotes(forest, num_remotes) -Return the user function pointer associated with a forest. +Return the array of remote ranks. # Arguments -* `forest`:\\[in\\] The forest. +* `forest`:\\[in\\] A forest with constructed ghost layer. +* `num_remotes`:\\[in,out\\] On output the number of remote ranks is stored here. # Returns -The user function pointer of *forest*. The forest does not need be committed before calling this function. -# See also -[`t8_forest_set_user_function`](@ref) - +The array of remote ranks in ascending order. ### Prototype ```c -t8_generic_function_pointer t8_forest_get_user_function (const t8_forest_t forest); +int * t8_forest_ghost_get_remotes (t8_forest_t forest, int *num_remotes); ``` """ -function t8_forest_get_user_function(forest) - @ccall libt8.t8_forest_get_user_function(forest::t8_forest_t)::t8_generic_function_pointer +function t8_forest_ghost_get_remotes(forest, num_remotes) + @ccall libt8.t8_forest_ghost_get_remotes(forest::t8_forest_t, num_remotes::Ptr{Cint})::Ptr{Cint} end """ - t8_forest_set_partition(forest, set_from, set_for_coarsening) - -Set a source forest to be partitioned during commit. The partitioning is done according to the SFC and each rank is assigned the same (maybe +1) number of elements. + t8_forest_ghost_remote_first_tree(forest, remote) -!!! note +Return the first local ghost tree of a remote rank. - This setting can be combined with t8_forest_set_adapt and t8_forest_set_balance. The order in which these operations are executed is always 1) Adapt 2) Partition 3) Balance. If t8_forest_set_balance is called with the *no_repartition* parameter set as false, it is not necessary to call t8_forest_set_partition additionally. +# Arguments +* `forest`:\\[in\\] A forest with constructed ghost layer. +* `remote`:\\[in\\] A remote rank of the ghost layer in *forest*. +# Returns +The ghost tree id of the first ghost tree that stores ghost elements of *remote*. +### Prototype +```c +t8_locidx_t t8_forest_ghost_remote_first_tree (t8_forest_t forest, int remote); +``` +""" +function t8_forest_ghost_remote_first_tree(forest, remote) + @ccall libt8.t8_forest_ghost_remote_first_tree(forest::t8_forest_t, remote::Cint)::t8_locidx_t +end -!!! note +""" + t8_forest_ghost_remote_first_elem(forest, remote) - This setting may not be combined with t8_forest_set_copy and overwrites this setting. +Return the local index of the first ghost element that belongs to a given remote rank. # Arguments -* `forest`:\\[in,out\\] The forest. -* `set_from`:\\[in\\] A second forest that should be partitioned. We take ownership. This can be prevented by referencing **set_from**. If NULL, a previously (or later) set forest will be taken (t8_forest_set_adapt, t8_forest_set_balance). -* `set_for_coarsening`:\\[in\\] If true, the partition will be such that coarsening a family of elements into their parent once is a process-local operation. This is ensured by a post-processing step that slightly shifts the newly determined process boundaries such that no full family of (same-level) siblings is split between processes. +* `forest`:\\[in\\] A forest with constructed ghost layer. +* `remote`:\\[in\\] A remote rank of the ghost layer in *forest*. +# Returns +The index i in the ghost elements of the first element of rank *remote* ### Prototype ```c -void t8_forest_set_partition (t8_forest_t forest, const t8_forest_t set_from, int set_for_coarsening); +t8_locidx_t t8_forest_ghost_remote_first_elem (t8_forest_t forest, int remote); ``` """ -function t8_forest_set_partition(forest, set_from, set_for_coarsening) - @ccall libt8.t8_forest_set_partition(forest::t8_forest_t, set_from::t8_forest_t, set_for_coarsening::Cint)::Cvoid +function t8_forest_ghost_remote_first_elem(forest, remote) + @ccall libt8.t8_forest_ghost_remote_first_elem(forest::t8_forest_t, remote::Cint)::t8_locidx_t end """ - t8_forest_set_partition_weight_function(forest, weight_callback) - -Set a user-defined weight function to guide the partitioning. - -\\pre *weight_callback* must be free of side effects (like changing the forest, some global state, etc.), the behavior is undefined otherwise. - -!!! note + t8_forest_ghost_ref(ghost) - If *weight_callback* is null, then all the elements are assumed to have the same weight +Increase the reference count of a ghost structure. # Arguments -* `forest`:\\[in,out\\] The forest. -* `weight_callback`:\\[in\\] A callback function defining element weights for the partitioning. +* `ghost`:\\[in,out\\] On input, this ghost structure must exist with positive reference count. ### Prototype ```c -void t8_forest_set_partition_weight_function (t8_forest_t forest, t8_weight_fcn_t *weight_callback); +void t8_forest_ghost_ref (t8_forest_ghost_t ghost); ``` """ -function t8_forest_set_partition_weight_function(forest, weight_callback) - @ccall libt8.t8_forest_set_partition_weight_function(forest::t8_forest_t, weight_callback::Ptr{t8_weight_fcn_t})::Cvoid +function t8_forest_ghost_ref(ghost) + @ccall libt8.t8_forest_ghost_ref(ghost::t8_forest_ghost_t)::Cvoid end """ - t8_forest_set_balance(forest, set_from, no_repartition) - -Set a source forest to be balanced during commit. A forest is said to be balanced if each element has face neighbors of level at most +1 or -1 of the element's level. - -!!! note - - This setting can be combined with t8_forest_set_adapt and t8_forest_set_partition. The order in which these operations are executed is always 1) Adapt 2) Partition 3) Balance. - -!!! note + t8_forest_ghost_unref(pghost) - This setting may not be combined with t8_forest_set_copy and overwrites this setting. +Decrease the reference count of a ghost structure. If the counter reaches zero, the ghost structure is destroyed. See also t8_forest_ghost_destroy, which is to be preferred when it is known that the last reference to a cmesh is deleted. # Arguments -* `forest`:\\[in,out\\] The forest. -* `set_from`:\\[in\\] A second forest that should be balanced. We take ownership. This can be prevented by referencing **set_from**. If NULL, a previously (or later) set forest will be taken (t8_forest_set_adapt, t8_forest_set_partition) -* `no_repartition`:\\[in\\] Balance constructs several intermediate forest that are refined from each other. In order to maintain a balanced load these forest are repartitioned in each round and the resulting forest is load-balanced per default. If this behaviour is not desired, *no_repartition* should be set to true. If *no_repartition* is false, an additional call of t8_forest_set_partition is not necessary. +* `pghost`:\\[in,out\\] On input, the ghost structure pointed to must exist with positive reference count. If the reference count reaches zero, the ghost structure is destroyed and this pointer is set to NULL. Otherwise, the pointer is not changed. ### Prototype ```c -void t8_forest_set_balance (t8_forest_t forest, const t8_forest_t set_from, int no_repartition); +void t8_forest_ghost_unref (t8_forest_ghost_t *pghost); ``` """ -function t8_forest_set_balance(forest, set_from, no_repartition) - @ccall libt8.t8_forest_set_balance(forest::t8_forest_t, set_from::t8_forest_t, no_repartition::Cint)::Cvoid +function t8_forest_ghost_unref(pghost) + @ccall libt8.t8_forest_ghost_unref(pghost::Ptr{t8_forest_ghost_t})::Cvoid end """ - t8_forest_set_ghost(forest, do_ghost, ghost_type) + t8_forest_ghost_destroy(pghost) -Enable or disable the creation of a layer of ghost elements. On default no ghosts are created. +Verify that a ghost structure has only one reference left and destroy it. This function is preferred over t8_forest_ghost_unref when it is known that the last reference is to be deleted. # Arguments -* `forest`:\\[in\\] The forest. -* `do_ghost`:\\[in\\] If non-zero a ghost layer will be created. -* `ghost_type`:\\[in\\] Controls which neighbors count as ghost elements, currently only T8\\_GHOST\\_FACES is supported. This value is ignored if *do_ghost* = 0. +* `pghost`:\\[in,out\\] This ghost structure must have a reference count of one. It can be in any state (committed or not). Then it effectively calls t8_forest_ghost_unref. ### Prototype ```c -void t8_forest_set_ghost (t8_forest_t forest, int do_ghost, t8_ghost_type_t ghost_type); +void t8_forest_ghost_destroy (t8_forest_ghost_t *pghost); ``` """ -function t8_forest_set_ghost(forest, do_ghost, ghost_type) - @ccall libt8.t8_forest_set_ghost(forest::t8_forest_t, do_ghost::Cint, ghost_type::t8_ghost_type_t)::Cvoid +function t8_forest_ghost_destroy(pghost) + @ccall libt8.t8_forest_ghost_destroy(pghost::Ptr{t8_forest_ghost_t})::Cvoid end """ - t8_forest_set_ghost_ext(forest, do_ghost, ghost_type, ghost_version) + t8_forest_ghost_create(forest) -Like 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 t8_forest_set_ghost. +Create one layer of ghost elements for a forest. # Arguments -* `forest`:\\[in\\] The forest. -* `do_ghost`:\\[in\\] If non-zero a ghost layer will be created. -* `ghost_type`:\\[in\\] Controls which neighbors count as ghost elements, currently only T8\\_GHOST\\_FACES is supported. This value is ignored if *do_ghost* = 0. -* `ghost_version`:\\[in\\] 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. +* `forest`:\\[in,out\\] The forest. *forest* must be committed before calling this function. # See also [`t8_forest_set_ghost`](@ref) ### Prototype ```c -void t8_forest_set_ghost_ext (t8_forest_t forest, int do_ghost, t8_ghost_type_t ghost_type, int ghost_version); +void t8_forest_ghost_create (t8_forest_t forest); ``` """ -function t8_forest_set_ghost_ext(forest, do_ghost, ghost_type, ghost_version) - @ccall libt8.t8_forest_set_ghost_ext(forest::t8_forest_t, do_ghost::Cint, ghost_type::t8_ghost_type_t, ghost_version::Cint)::Cvoid +function t8_forest_ghost_create(forest) + @ccall libt8.t8_forest_ghost_create(forest::t8_forest_t)::Cvoid end """ - t8_forest_set_load(forest, filename) + t8_forest_ghost_create_balanced_only(forest) -Use assertions and document that the forest\\_set (..., from) and set\\_load are mutually exclusive. +Create one layer of ghost elements for a forest. This version only works with balanced forests and is the original algorithm from p4est: Scalable Algorithms For Parallel Adaptive Mesh Refinement On Forests of Octrees -TODO: Unused function -> remove? +!!! note + + The user should prefer t8_forest_ghost_create even for balanced forests. +# Arguments +* `forest`:\\[in,out\\] The balanced forest/ *forest* must be committed before calling this function. ### Prototype ```c -void t8_forest_set_load (t8_forest_t forest, const char *filename); +void t8_forest_ghost_create_balanced_only (t8_forest_t forest); ``` """ -function t8_forest_set_load(forest, filename) - @ccall libt8.t8_forest_set_load(forest::t8_forest_t, filename::Cstring)::Cvoid +function t8_forest_ghost_create_balanced_only(forest) + @ccall libt8.t8_forest_ghost_create_balanced_only(forest::t8_forest_t)::Cvoid end """ - t8_forest_comm_global_num_leaf_elements(forest) + t8_forest_ghost_create_topdown(forest) -Compute the global number of leaf elements in a forest as the sum of the local leaf element counts. +Experimental version of t8_forest_ghost_create using the ghost\\_v3 algorithm -# Arguments -* `forest`:\\[in\\] The forest. ### Prototype ```c -void t8_forest_comm_global_num_leaf_elements (t8_forest_t forest); +void t8_forest_ghost_create_topdown (t8_forest_t forest); ``` """ -function t8_forest_comm_global_num_leaf_elements(forest) - @ccall libt8.t8_forest_comm_global_num_leaf_elements(forest::t8_forest_t)::Cvoid +function t8_forest_ghost_create_topdown(forest) + @ccall libt8.t8_forest_ghost_create_topdown(forest::t8_forest_t)::Cvoid end +# typedef int ( * t8_forest_iterate_face_fn ) ( const t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int face , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index , void * user_data ) """ - t8_forest_commit(forest) - -After allocating and adding properties to a forest, commit the changes. This call sets up the internal state of the forest. +Callback function used in # Arguments -* `forest`:\\[in,out\\] Must be created with t8_forest_init and specialized with t8\\_forest\\_set\\_* calls first. -### Prototype -```c -void t8_forest_commit (t8_forest_t forest); -``` +* `forest`:\\[in\\] The forest. +* `ltreeid`:\\[in\\] Local index of the tree containing the *element*. +* `element`:\\[in\\] The considered element. +* `face`:\\[in\\] The integer index of the considered face of *element*. +* `is_leaf`:\\[in\\] True if and only if the currently considered element is a leaf element. +* `leaf_elements`:\\[in\\] The array of leaf elements that are descendants of *element*. Sorted by linear index. +* `tree_leaf_index`:\\[in\\] Tree-local index of the first leaf. +* `user_data`:\\[in\\] Some user-defined data, as void pointer. +# Returns +Nonzero if the element may touch the face and the top-down search shall be continued, zero otherwise. +# See also +[`t8_forest_iterate_faces`](@ref). """ -function t8_forest_commit(forest) - @ccall libt8.t8_forest_commit(forest::t8_forest_t)::Cvoid -end +const t8_forest_iterate_face_fn = Ptr{Cvoid} +# typedef int ( * t8_forest_search_fn ) ( t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index ) """ - t8_forest_get_maxlevel(forest) - -Return the maximum allowed refinement level for any element in a forest. +A call-back function used by t8_forest_search describing a search-criterion. Is called on an element and the search criterion should be checked on that element. Return true if the search criterion is met, false otherwise. # Arguments -* `forest`:\\[in\\] A forest. +* `forest`:\\[in\\] the forest +* `ltreeid`:\\[in\\] the local tree id of the current tree +* `element`:\\[in\\] the element for which the search criterion is checked. +* `is_leaf`:\\[in\\] true if and only if *element* is a leaf element +* `leaf_elements`:\\[in\\] the leaf elements in *forest* that are descendants of *element* (or the element itself if *is_leaf* is true) +* `tree_leaf_index`:\\[in\\] the local index of the first leaf in *leaf_elements* # Returns -The maximum level of refinement that is allowed for an element in this forest. It is guaranteed that any tree in *forest* can be refined this many times and it is not allowed to refine further. *forest* must be committed before calling this function. For forest with a single element class (non-hybrid) maxlevel is the maximum refinement level of this element class, whilst for hybrid forests the maxlevel is the minimum of all maxlevels of the element classes in this forest. -### Prototype -```c -int t8_forest_get_maxlevel (const t8_forest_t forest); -``` +non-zero if the search criterion is met, zero otherwise. """ -function t8_forest_get_maxlevel(forest) - @ccall libt8.t8_forest_get_maxlevel(forest::t8_forest_t)::Cint -end +const t8_forest_search_fn = Ptr{Cvoid} +# typedef void ( * t8_forest_query_fn ) ( t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index , sc_array_t * queries , sc_array_t * query_indices , int * query_matches , const size_t num_active_queries ) """ - t8_forest_get_local_num_leaf_elements(forest) +A call-back function used by t8_forest_search for queries. Is called on an element and all queries are checked on that element. All positive queries are passed further down to the children of the element up to leaf elements of the tree. The results of the check are stored in *query_matches*. -Return the number of process local leaf elements in the forest. +# Arguments +* `forest`:\\[in\\] the forest +* `ltreeid`:\\[in\\] the local tree id of the current tree +* `element`:\\[in\\] the element for which the queries are executed +* `is_leaf`:\\[in\\] true if and only if *element* is a leaf element +* `leaf_elements`:\\[in\\] the leaf elements in *forest* that are descendants of *element* (or the element itself if *is_leaf* is true) +* `tree_leaf_index`:\\[in\\] the local index of the first leaf in *leaf_elements* +* `queries`:\\[in\\] An array of queries that are checked by the function +* `query_indices`:\\[in\\] An array of size\\_t entries, where each entry is an index of a query in *queries*. +* `query_matches`:\\[in,out\\] An array of length *num_active_queries*. If the element is not a leave must be set to true or false at the i-th index for each query, specifying whether the element 'matches' the query of the i-th query index or not. When the element is a leaf we can return before all entries are set. +* `num_active_queries`:\\[in\\] The number of currently active queries (equals the number of entries of *query_matches* and entries of *query_indices*). +""" +const t8_forest_query_fn = Ptr{Cvoid} + +# typedef int ( * t8_forest_partition_search_fn ) ( const t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int pfirst , const int plast ) +""" +A call-back function used by t8_forest_search_partition describing a search-criterion. Is called on an element and the search criterion should be checked on that element. Return true if the search criterion is met, false otherwise. # Arguments -* `forest`:\\[in\\] A forest. +* `forest`:\\[in\\] the forest +* `ltreeid`:\\[in\\] the local tree id of the current tree in the cmesh. Since the cmesh has to be replicated, it coincides with the global tree id. +* `element`:\\[in\\] the element for which the search criterion is checked +* `pfirst`:\\[in\\] the first processor that owns part of *element*. Guaranteed to be non-empty. +* `plast`:\\[in\\] the last processor that owns part of *element*. Guaranteed to be non-empty. # Returns -The number of leaf elements on this process in *forest*. *forest* must be committed before calling this function. -### Prototype -```c -t8_locidx_t t8_forest_get_local_num_leaf_elements (const t8_forest_t forest); -``` +non-zero if the search criterion is met, zero otherwise. """ -function t8_forest_get_local_num_leaf_elements(forest) - @ccall libt8.t8_forest_get_local_num_leaf_elements(forest::t8_forest_t)::t8_locidx_t -end +const t8_forest_partition_search_fn = Ptr{Cvoid} +# typedef void ( * t8_forest_partition_query_fn ) ( const t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int pfirst , const int plast , void * queries , sc_array_t * query_indices , int * query_matches , const size_t num_active_queries ) """ - t8_forest_get_global_num_leaf_elements(forest) +A call-back function used by t8_forest_search_partition for queries. Is called on an element and all queries are checked on that element. All positive queries are passed further down to the children of the element. The results of the check are stored in *query_matches*. -Return the number of global leaf elements in the forest. +# Arguments +* `forest`:\\[in\\] the forest +* `ltreeid`:\\[in\\] the local tree id of the current tree in the cmesh. Since the cmesh has to be replicated, it coincides with the global tree id. +* `element`:\\[in\\] the element for which the query is executed +* `pfirst`:\\[in\\] the first processor that owns part of *element*. Guaranteed to be non-empty. +* `plast`:\\[in\\] the last processor that owns part of *element*. Guaranteed to be non-empty. if this is equal to *pfirst*, then the recursion will stop for *element*'s branch after this function returns. +* `queries`:\\[in\\] an array of queries that are checked by the function +* `query_indices`:\\[in\\] an array of size\\_t entries, where each entry is an index of a query in *queries*. +* `query_matches`:\\[in,out\\] an array of length *num_active_queries*. If the element is not a leaf must be set to true or false at the i-th index for each query, specifying whether the element 'matches' the query of the i-th query index or not. When the element is a leaf we can return before all entries are set. +* `num_active_queries`:\\[in\\] The number of currently active queries (equals the number of entries of *query_matches* and entries of *query_indices*). +""" +const t8_forest_partition_query_fn = Ptr{Cvoid} + +""" + t8_forest_split_array(element, leaf_elements, offsets) + +Split an array of elements according to the children of a given element E. In other words for each child C of E, find the index i, j, such that all descendants of C are elements[i], ..., elements[j-1]. # Arguments -* `forest`:\\[in\\] A forest. -# Returns -The number of leaf elements (summed over all processes) in *forest*. *forest* must be committed before calling this function. +* `element`:\\[in\\] An element. +* `leaf_elements`:\\[in\\] An array of leaf elements of *element*. Thus, all elements must be descendants. Sorted by linear index. +* `offsets`:\\[in,out\\] On input an allocated array of *num_children_of_E* + 1 entries. On output entry i indicates the position in *leaf_elements* where the descandents of the i-th child of E start. ### Prototype ```c -t8_gloidx_t t8_forest_get_global_num_leaf_elements (const t8_forest_t forest); +void t8_forest_split_array (const t8_element_t *element, const t8_element_array_t *leaf_elements, size_t *offsets); ``` """ -function t8_forest_get_global_num_leaf_elements(forest) - @ccall libt8.t8_forest_get_global_num_leaf_elements(forest::t8_forest_t)::t8_gloidx_t +function t8_forest_split_array(element, leaf_elements, offsets) + @ccall libt8.t8_forest_split_array(element::Ptr{t8_element_t}, leaf_elements::Ptr{t8_element_array_t}, offsets::Ptr{Csize_t})::Cvoid end """ - t8_forest_get_num_ghosts(forest) + t8_forest_iterate_faces(forest, ltreeid, element, face, leaf_elements, tree_lindex_of_first_leaf, callback, user_data) -Return the number of ghost elements of a forest. +Iterate over all leaves of an element that touch a given face of the element. Callback is called in each recursive step with element as input. leaf\\_index is only not negative if element is a leaf, in which case it indicates the index of the leaf in the leaves of the tree. If it is negative, it is - (index + 1) Top-down iteration and callback is called on each intermediate level. If it returns false, the current element is not traversed further -# Arguments -* `forest`:\\[in\\] The forest. -# Returns -The number of ghost elements stored in the ghost structure of *forest*. 0 if no ghosts were constructed. -# See also -[`t8_forest_set_ghost`](@ref) *forest* must be committed before calling this function. +!!! note + + *tree_lindex_of_first_leaf* is not an index in *leaf_elements*. *leaf_elements* may only be a part of the tree's leaves. +# Arguments +* `forest`:\\[in\\] A committed forest. +* `ltreeid`:\\[in\\] Local index of the tree containing the *element*. +* `element`:\\[in\\] The considered element. +* `face`:\\[in\\] The integer index of the considered face of *element*. +* `leaf_elements`:\\[in\\] The array of leaf elements that are descendants of *element*. Sorted by linear index. +* `tree_lindex_of_first_leaf`:\\[in\\] Index of the first leaf of *element* in the tree's leaves. The corresponding leaf does not necessarily lie on the face of *element*. +* `callback`:\\[in\\] The callback function. +* `user_data`:\\[in\\] The user data passed to the *callback* function. ### Prototype ```c -t8_locidx_t t8_forest_get_num_ghosts (const t8_forest_t forest); +void t8_forest_iterate_faces (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *element, const int face, const t8_element_array_t *const leaf_elements, const t8_locidx_t tree_lindex_of_first_leaf, const t8_forest_iterate_face_fn callback, void *user_data); ``` """ -function t8_forest_get_num_ghosts(forest) - @ccall libt8.t8_forest_get_num_ghosts(forest::t8_forest_t)::t8_locidx_t +function t8_forest_iterate_faces(forest, ltreeid, element, face, leaf_elements, tree_lindex_of_first_leaf, callback, user_data) + @ccall libt8.t8_forest_iterate_faces(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, face::Cint, leaf_elements::Ptr{t8_element_array_t}, tree_lindex_of_first_leaf::t8_locidx_t, callback::t8_forest_iterate_face_fn, user_data::Ptr{Cvoid})::Cvoid end """ - t8_forest_get_eclass(forest, ltreeid) + t8_forest_search(forest, search_fn, query_fn, queries) -Return the element class of a forest local tree. +Perform a top-down search of the forest, executing a callback on each intermediate element. The search will enter each tree at least once. If the callback returns false for an element, its descendants are not further searched. To pass user data to the search\\_fn function use t8_forest_set_user_data. # Arguments * `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] The local id of a tree in *forest*. -# Returns -The element class of the tree *ltreeid*. *forest* must be committed before calling this function. +* `search_fn`:\\[in\\] The callback function describing the search criterion. +* `query_fn`:\\[in\\] The query function. +* `queries`:\\[in\\] The array of queries. ### Prototype ```c -t8_eclass_t t8_forest_get_eclass (const t8_forest_t forest, const t8_locidx_t ltreeid); +void t8_forest_search (t8_forest_t forest, t8_forest_search_fn search_fn, t8_forest_query_fn query_fn, sc_array_t *queries); ``` """ -function t8_forest_get_eclass(forest, ltreeid) - @ccall libt8.t8_forest_get_eclass(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_eclass_t +function t8_forest_search(forest, search_fn, query_fn, queries) + @ccall libt8.t8_forest_search(forest::t8_forest_t, search_fn::t8_forest_search_fn, query_fn::t8_forest_query_fn, queries::Ptr{sc_array_t})::Cvoid end """ - t8_forest_tree_is_local(forest, local_tree) + t8_forest_iterate_replace(forest_new, forest_old, replace_fn) -Check whether a given tree id belongs to a local tree in a forest. +Given two forest where the elements in one forest are either direct children or parents of the elements in the other forest compare the two forests and for each refined element or coarsened family in the old one, call a callback function providing the local indices of the old and new elements. + +!!! note + + To pass a user pointer to *replace_fn* use t8_forest_set_user_data and t8_forest_get_user_data. # Arguments -* `forest`:\\[in\\] The forest. -* `local_tree`:\\[in\\] A tree id. -# Returns -True if and only if the id *local_tree* belongs to a local tree of *forest*. *forest* must be committed before calling this function. +* `forest_new`:\\[in\\] A forest, each element is a parent or child of an element in *forest_old*. +* `forest_old`:\\[in\\] The initial forest. +* `replace_fn`:\\[in\\] A replace callback function. ### Prototype ```c -int t8_forest_tree_is_local (const t8_forest_t forest, const t8_locidx_t local_tree); +void t8_forest_iterate_replace (t8_forest_t forest_new, t8_forest_t forest_old, t8_forest_replace_t replace_fn); ``` """ -function t8_forest_tree_is_local(forest, local_tree) - @ccall libt8.t8_forest_tree_is_local(forest::t8_forest_t, local_tree::t8_locidx_t)::Cint +function t8_forest_iterate_replace(forest_new, forest_old, replace_fn) + @ccall libt8.t8_forest_iterate_replace(forest_new::t8_forest_t, forest_old::t8_forest_t, replace_fn::t8_forest_replace_t)::Cvoid end """ - t8_forest_get_local_id(forest, gtreeid) + t8_forest_search_partition(forest, search_fn, query_fn, queries) -Given a global tree id compute the forest local id of this tree. If the tree is a local tree, then the local id is between 0 and the number of local trees. If the tree is not a local tree, a negative number is returned. +Perform a top-down search of the global partition, executing a callback on each intermediate element. The search will enter each tree at least once. The recursion will only go down branches that are split between multiple processors. This is not a collective function. It does not communicate. The function expects the coarse mesh to be replicated. If the callback returns false for an element, its descendants are not further searched. To pass user data to **search_fn** function use t8_forest_set_user_data # Arguments -* `forest`:\\[in\\] The forest. -* `gtreeid`:\\[in\\] The global id of a tree. -# Returns -The tree's local id in *forest*, if it is a local tree. A negative number if not. Ghosts trees are not considered as local. -# See also -[`t8_forest_get_local_or_ghost_id`](@ref) for ghost trees., https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. - +* `forest`:\\[in\\] the forest to be searched +* `search_fn`:\\[in\\] a search callback function called on elements +* `query_fn`:\\[in\\] a query callback function called for all active queries of an element +* `queries`:\\[in,out\\] an array of queries that are checked by the function ### Prototype ```c -t8_locidx_t t8_forest_get_local_id (const t8_forest_t forest, const t8_gloidx_t gtreeid); +void t8_forest_search_partition (const t8_forest_t forest, t8_forest_partition_search_fn search_fn, t8_forest_partition_query_fn query_fn, sc_array_t *queries); ``` """ -function t8_forest_get_local_id(forest, gtreeid) - @ccall libt8.t8_forest_get_local_id(forest::t8_forest_t, gtreeid::t8_gloidx_t)::t8_locidx_t +function t8_forest_search_partition(forest, search_fn, query_fn, queries) + @ccall libt8.t8_forest_search_partition(forest::t8_forest_t, search_fn::t8_forest_partition_search_fn, query_fn::t8_forest_partition_query_fn, queries::Ptr{sc_array_t})::Cvoid end """ - t8_forest_get_local_or_ghost_id(forest, gtreeid) + t8_forest_partition(forest) -Given a global tree id compute the forest local id of this tree. If the tree is a local tree, then the local id is between 0 and the number of local trees. If the tree is a ghost, then the local id is between num\\_local\\_trees and num\\_local\\_trees + num\\_ghost\\_trees. If the tree is neither a local tree nor a ghost tree, a negative number is returned. +Populate a forest with the partitioned elements of forest->set\\_from. # Arguments -* `forest`:\\[in\\] The forest. -* `gtreeid`:\\[in\\] The global id of a tree. -# Returns -The tree's local id in *forest*, if it is a local tree. num\\_local\\_trees + the ghosts id, if it is a ghost tree. A negative number if not. -# See also -https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing - +* `forest`:\\[in,out\\] The forest. ### Prototype ```c -t8_locidx_t t8_forest_get_local_or_ghost_id (const t8_forest_t forest, const t8_gloidx_t gtreeid); +void t8_forest_partition (t8_forest_t forest); ``` """ -function t8_forest_get_local_or_ghost_id(forest, gtreeid) - @ccall libt8.t8_forest_get_local_or_ghost_id(forest::t8_forest_t, gtreeid::t8_gloidx_t)::t8_locidx_t +function t8_forest_partition(forest) + @ccall libt8.t8_forest_partition(forest::t8_forest_t)::Cvoid end """ - t8_forest_ltreeid_to_cmesh_ltreeid(forest, ltreeid) - -Given the local id of a tree in a forest, compute the tree's local id in the associated cmesh. + t8_forest_new_gather(forest_from, gather_rank) -!!! note +Create a new forest that gathers a given forest on one process. - For forest local trees, this is the inverse function of t8_forest_cmesh_ltreeid_to_ltreeid. +This functionality is mostly required for comparison purposes and sanity checks within the testing framework. # Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] The local id of a tree or ghost in the forest. +* `forest_from`:\\[in\\] the forest that should be gathered on one rank +* `gather_rank`:\\[in\\] the rank of the process the forest will be gathered on # Returns -The local id of the tree in the cmesh associated with the forest. *forest* must be committed before calling this function. -# See also -https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. - +The gathered forest: The same as *forest_from*, but all elements are on rank *gather_rank*. ### Prototype ```c -t8_locidx_t t8_forest_ltreeid_to_cmesh_ltreeid (t8_forest_t forest, t8_locidx_t ltreeid); +t8_forest_t t8_forest_new_gather (const t8_forest_t forest_from, const int gather_rank); ``` """ -function t8_forest_ltreeid_to_cmesh_ltreeid(forest, ltreeid) - @ccall libt8.t8_forest_ltreeid_to_cmesh_ltreeid(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_locidx_t +function t8_forest_new_gather(forest_from, gather_rank) + @ccall libt8.t8_forest_new_gather(forest_from::t8_forest_t, gather_rank::Cint)::t8_forest_t end """ - t8_forest_cmesh_ltreeid_to_ltreeid(forest, lctreeid) - -Given the local id of a tree in the coarse mesh of a forest, compute the tree's local id in the forest. + t8_forest_set_partition_offset(forest, first_global_element) -!!! note +Manually set the partition offset of the current process. - For forest local trees, this is the inverse function of t8_forest_ltreeid_to_cmesh_ltreeid. +If set, the next partitioning of the forest will use the manually defined element offsets. # Arguments -* `forest`:\\[in\\] The forest. -* `lctreeid`:\\[in\\] The local id of a tree in the coarse mesh of *forest*. -# Returns -The local id of the tree in the forest. -1 if the tree is not forest local. *forest* must be committed before calling this function. -# See also -https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. - +* `forest`:\\[in,out\\] the considered forest +* `first_global_element`:\\[in\\] the global ID that will become the first local element ### Prototype ```c -t8_locidx_t t8_forest_cmesh_ltreeid_to_ltreeid (t8_forest_t forest, t8_locidx_t lctreeid); +void t8_forest_set_partition_offset (t8_forest_t forest, const t8_gloidx_t first_global_element); ``` """ -function t8_forest_cmesh_ltreeid_to_ltreeid(forest, lctreeid) - @ccall libt8.t8_forest_cmesh_ltreeid_to_ltreeid(forest::t8_forest_t, lctreeid::t8_locidx_t)::t8_locidx_t +function t8_forest_set_partition_offset(forest, first_global_element) + @ccall libt8.t8_forest_set_partition_offset(forest::t8_forest_t, first_global_element::t8_gloidx_t)::Cvoid end """ - t8_forest_get_coarse_tree(forest, ltreeid) + t8_forest_partition_create_offsets(forest) -Given the local id of a tree in a forest, return the coarse tree of the cmesh that corresponds to this tree. +Create the element\\_offset array of a partitioned forest. # Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] The local id of a tree in the forest. -# Returns -The coarse tree that matches the forest tree with local id *ltreeid*. +* `forest`:\\[in,out\\] The forest. *forest* must be committed before calling this function. ### Prototype ```c -t8_ctree_t t8_forest_get_coarse_tree (t8_forest_t forest, t8_locidx_t ltreeid); +void t8_forest_partition_create_offsets (t8_forest_t forest); ``` """ -function t8_forest_get_coarse_tree(forest, ltreeid) - @ccall libt8.t8_forest_get_coarse_tree(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_ctree_t +function t8_forest_partition_create_offsets(forest) + @ccall libt8.t8_forest_partition_create_offsets(forest::t8_forest_t)::Cvoid end """ - t8_forest_element_is_leaf(forest, element, local_tree) - -Query whether a given element is a leaf in a forest. - -!!! note - - This does not query for ghost leaves. - -!!! note + t8_forest_partition_next_nonempty_rank(forest, rank) - *forest* must be committed before calling this function. +If t8_forest_partition_create_offsets was already called, compute for a given rank the next greater rank that is not empty. # Arguments * `forest`:\\[in\\] The forest. -* `element`:\\[in\\] An element of a local tree in *forest*. -* `local_tree`:\\[in\\] A local tree id of *forest*. +* `rank`:\\[in\\] An MPI rank. # Returns -True (non-zero) if and only if *element* is a leaf in *local_tree* of *forest*. +A rank q > *rank* such that the forest has elements on *q*. If such a *q* does not exist, returns mpisize. ### Prototype ```c -int t8_forest_element_is_leaf (const t8_forest_t forest, const t8_element_t *element, const t8_locidx_t local_tree); +int t8_forest_partition_next_nonempty_rank (t8_forest_t forest, int rank); ``` """ -function t8_forest_element_is_leaf(forest, element, local_tree) - @ccall libt8.t8_forest_element_is_leaf(forest::t8_forest_t, element::Ptr{t8_element_t}, local_tree::t8_locidx_t)::Cint +function t8_forest_partition_next_nonempty_rank(forest, rank) + @ccall libt8.t8_forest_partition_next_nonempty_rank(forest::t8_forest_t, rank::Cint)::Cint end """ - t8_forest_element_is_leaf_or_ghost(forest, element, local_tree, check_ghost) - -Query whether a given element or a ghost is a leaf of a local or ghost tree in a forest. - -!!! note + t8_forest_partition_create_first_desc(forest) - *forest* must be committed before calling this function. t8_forest_element_is_leaf t8_forest_element_is_ghost +Create the array of global\\_first\\_descendant ids of a partitioned forest. # Arguments -* `forest`:\\[in\\] The forest. -* `element`:\\[in\\] An element of a local tree in *forest*. -* `local_tree`:\\[in\\] A local tree id of *forest* or a ghost tree id -* `check_ghost`:\\[in\\] If true *element* is interpreted as a ghost element and *local_tree* as the id of a ghost tree (0 <= *local_tree* < num\\_ghost\\_trees). If false *element* is interpreted as an element and *local_tree* as the id of a local tree (0 <= *local_tree* < num\\_local\\_trees). -# Returns -True (non-zero) if and only if *element* is a leaf (or ghost) in *local_tree* of *forest*. +* `forest`:\\[in,out\\] The forest. *forest* must be committed before calling this function. ### Prototype ```c -int t8_forest_element_is_leaf_or_ghost (const t8_forest_t forest, const t8_element_t *element, const t8_locidx_t local_tree, const int check_ghost); +void t8_forest_partition_create_first_desc (t8_forest_t forest); ``` """ -function t8_forest_element_is_leaf_or_ghost(forest, element, local_tree, check_ghost) - @ccall libt8.t8_forest_element_is_leaf_or_ghost(forest::t8_forest_t, element::Ptr{t8_element_t}, local_tree::t8_locidx_t, check_ghost::Cint)::Cint +function t8_forest_partition_create_first_desc(forest) + @ccall libt8.t8_forest_partition_create_first_desc(forest::t8_forest_t)::Cvoid end """ - t8_forest_leaf_face_orientation(forest, ltreeid, scheme, leaf, face) - -Compute the leaf face orientation at given face in a forest. + t8_forest_partition_create_tree_offsets(forest) -For more information about the encoding of face orientation refer to t8_cmesh_get_face_neighbor. +Create the array tree offsets of a partitioned forest. This arrays stores at position p the global id of the first tree of this process. Or if this tree is shared, it stores -(global\\_id) - 1. # Arguments -* `forest`:\\[in\\] The forest. Must have a valid ghost layer. -* `ltreeid`:\\[in\\] A local tree id. -* `scheme`:\\[in\\] The eclass scheme of the element. -* `leaf`:\\[in\\] A leaf in tree *ltreeid* of *forest*. -* `face`:\\[in\\] The index of the face across which the face neighbors are searched. -# Returns -Face orientation encoded as integer. +* `forest`:\\[in,out\\] The forest. *forest* must be committed before calling this function. ### Prototype ```c -int t8_forest_leaf_face_orientation (t8_forest_t forest, const t8_locidx_t ltreeid, const t8_scheme_c *scheme, const t8_element_t *leaf, const int face); +void t8_forest_partition_create_tree_offsets (t8_forest_t forest); ``` """ -function t8_forest_leaf_face_orientation(forest, ltreeid, scheme, leaf, face) - @ccall libt8.t8_forest_leaf_face_orientation(forest::t8_forest_t, ltreeid::t8_locidx_t, scheme::Ptr{t8_scheme_c}, leaf::Ptr{t8_element_t}, face::Cint)::Cint +function t8_forest_partition_create_tree_offsets(forest) + @ccall libt8.t8_forest_partition_create_tree_offsets(forest::t8_forest_t)::Cvoid end """ - t8_forest_leaf_face_neighbors(forest, ltreeid, leaf, pneighbor_leaves, face, dual_faces, num_neighbors, pelement_indices, pneigh_eclass) - -Compute the leaf face neighbors of a forest leaf element or ghost leaf. - -!!! note - - If there are no face neighbors, then *pneighbor\\_leaves = NULL, num\\_neighbors = 0, and *pelement\\_indices = NULL on output. - -!!! note - - *forest* must be committed before calling this function. - -!!! note + t8_forest_partition_data(forest_from, forest_to, data_in, data_out) - If *forest* does not have a ghost layer then leaf elements at the process boundaries have 0 neighbors along the boundary face. (The function output for leaf elements then depends on the parallel partition.) +Re-Partition an array accordingly to a partitioned forest. !!! note - Important! This routine allocates memory which must be freed. Do it like this: - -if (num\\_neighbors > 0) { [`T8_FREE`](@ref) (pneighbor\\_leaves); [`T8_FREE`](@ref) (pelement\\_indices); [`T8_FREE`](@ref) (dual\\_faces); } + *data_in* has to be of size equal to the number of local elements of *forest_from* *data_out* has to be already allocated and has to be of size equal to the number of local elements of *forest_to*. # Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] A local tree id (could also be a ghost tree). 0 <= *ltreeid* < num\\_local trees+num\\_ghost\\_trees -* `leaf`:\\[in\\] A leaf in tree *ltreeid* of *forest*. -* `pneighbor_leaves`:\\[out\\] Unallocated on input. On output the neighbor leaves are stored here. -* `face`:\\[in\\] The index of the face across which the face neighbors are searched. -* `dual_faces`:\\[out\\] On output the face id's of the neighboring elements' faces. -* `num_neighbors`:\\[out\\] On output the number of neighbor leaves. -* `pelement_indices`:\\[out\\] Unallocated on input. On output the element indices of the neighbor leaves are stored here. 0, 1, ... num\\_local\\_el - 1 for local leaves and num\\_local\\_el , ... , num\\_local\\_el + num\\_ghosts - 1 for ghosts. -* `pneigh_eclass`:\\[out\\] On output the eclass of the neighbor elements. +* `forest_from`:\\[in\\] The forest before the partitioning step. +* `forest_to`:\\[in\\] The partitioned forest of *forest_from*. +* `data_in`:\\[in\\] A pointer to an [`sc_array_t`](@ref) holding data (one value per element) accordingly to *forest_from*. +* `data_out`:\\[in,out\\] A pointer to an already allocated [`sc_array_t`](@ref) capable of holding data accordingly to *forest_to*. ### Prototype ```c -void t8_forest_leaf_face_neighbors (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *leaf, const t8_element_t **pneighbor_leaves[], const int face, int *dual_faces[], int *num_neighbors, t8_locidx_t **pelement_indices, t8_eclass_t *pneigh_eclass); +void t8_forest_partition_data (t8_forest_t forest_from, t8_forest_t forest_to, const sc_array_t *data_in, sc_array_t *data_out); ``` """ -function t8_forest_leaf_face_neighbors(forest, ltreeid, leaf, pneighbor_leaves, face, dual_faces, num_neighbors, pelement_indices, pneigh_eclass) - @ccall libt8.t8_forest_leaf_face_neighbors(forest::t8_forest_t, ltreeid::t8_locidx_t, leaf::Ptr{t8_element_t}, pneighbor_leaves::Ptr{Ptr{Ptr{t8_element_t}}}, face::Cint, dual_faces::Ptr{Ptr{Cint}}, num_neighbors::Ptr{Cint}, pelement_indices::Ptr{Ptr{t8_locidx_t}}, pneigh_eclass::Ptr{t8_eclass_t})::Cvoid -end - -""" - t8_forest_leaf_face_neighbors_ext(forest, ltreeid, leaf_or_ghost, pneighbor_leaves, face, dual_faces, num_neighbors, pelement_indices, pneigh_eclass, gneigh_tree, orientation) - -Like t8_forest_leaf_face_neighbors but also provides information about the global neighbors and the orientation. - -!!! note - - If there are no face neighbors, then *pneighbor\\_leaves = NULL, num\\_neighbors = 0, and *pelement\\_indices = NULL on output. +function t8_forest_partition_data(forest_from, forest_to, data_in, data_out) + @ccall libt8.t8_forest_partition_data(forest_from::t8_forest_t, forest_to::t8_forest_t, data_in::Ptr{sc_array_t}, data_out::Ptr{sc_array_t})::Cvoid +end -!!! note +""" + t8_forest_partition_test_boundary_element(forest) - *forest* must be committed before calling this function. +Test if the last descendant of the last element of current rank has a smaller linear id than the stored first descendant of rank+1. If this is not the case, elements overlap. !!! note - Important! This routine allocates memory which must be freed. Do it like this: - -if (num\\_neighbors > 0) { [`T8_FREE`](@ref) (pneighbor\\_leaves); [`T8_FREE`](@ref) (pelement\\_indices); [`T8_FREE`](@ref) (dual\\_faces); } + *forest* must be committed before calling this function. # Arguments -* `forest`:\\[in\\] The forest. Must have a valid ghost layer. -* `ltreeid`:\\[in\\] A local tree id (could also be a ghost tree). 0 <= *ltreeid* < num\\_local trees+num\\_ghost\\_trees -* `leaf_or_ghost`:\\[in\\] A leaf or ghost leaf element in tree *ltreeid* of *forest*. -* `pneighbor_leaves`:\\[out\\] Unallocated on input. On output the neighbor leaves are stored here. -* `face`:\\[in\\] The index of the face across which the face neighbors are searched. -* `dual_faces`:\\[out\\] On output the face id's of the neighboring elements' faces. -* `num_neighbors`:\\[out\\] On output the number of neighbor leaves. -* `pelement_indices`:\\[out\\] Unallocated on input. On output the element indices of the neighbor leaves are stored here. 0, 1, ... num\\_local\\_el - 1 for local leaves and num\\_local\\_el , ... , num\\_local\\_el + num\\_ghosts - 1 for ghosts. -* `pneigh_eclass`:\\[out\\] On output the eclass of the neighbor elements. -* `gneigh_tree`:\\[out\\] The global tree IDs of the neighbor trees. -* `orientation`:\\[out\\] 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 t8_forest_leaf_face_neighbors. +* `forest`:\\[in\\] The forest. ### Prototype ```c -void t8_forest_leaf_face_neighbors_ext (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *leaf_or_ghost, const t8_element_t **pneighbor_leaves[], const int face, int *dual_faces[], int *num_neighbors, t8_locidx_t **pelement_indices, t8_eclass_t *pneigh_eclass, t8_gloidx_t *gneigh_tree, int *orientation); +void t8_forest_partition_test_boundary_element (const t8_forest_t forest); ``` """ -function t8_forest_leaf_face_neighbors_ext(forest, ltreeid, leaf_or_ghost, pneighbor_leaves, face, dual_faces, num_neighbors, pelement_indices, pneigh_eclass, gneigh_tree, orientation) - @ccall libt8.t8_forest_leaf_face_neighbors_ext(forest::t8_forest_t, ltreeid::t8_locidx_t, leaf_or_ghost::Ptr{t8_element_t}, pneighbor_leaves::Ptr{Ptr{Ptr{t8_element_t}}}, face::Cint, dual_faces::Ptr{Ptr{Cint}}, num_neighbors::Ptr{Cint}, pelement_indices::Ptr{Ptr{t8_locidx_t}}, pneigh_eclass::Ptr{t8_eclass_t}, gneigh_tree::Ptr{t8_gloidx_t}, orientation::Ptr{Cint})::Cvoid +function t8_forest_partition_test_boundary_element(forest) + @ccall libt8.t8_forest_partition_test_boundary_element(forest::t8_forest_t)::Cvoid end """ - t8_forest_same_level_leaf_face_neighbor_index(forest, element_index, face_index, global_treeid, dual_face) - -Given a leaf element or ghost index in "all local elements + ghosts" enumeration compute the index of the face neighbor of the element - provided that only one or no face neighbors exists. HANDLE WITH CARE. DO NOT CALL IF THE FOREST IS NOT UNIFORM. + t8_forest_pfc_correction_offsets(forest) -!!! note +Correct the partitioning if element families are split across process boundaries. - Do not call if you are unsure about the number of face neighbors. In particular if the forest is not uniform. +The default partitioning distributes the elements into equally-sized partitions. For coarsening, however, all elements of a family have to be on the same process in order to be coarsened into their parent element. This function corrects the partitioning such that no families are split across process boundaries. The price to be paid is a slight deviation from the optimal balance of elements among processors. # Arguments -* `forest`:\\[in\\] The forest. Must be committed. -* `element_index`:\\[in\\] Index of an element in *forest*. Must have only one or no facen neighbors across the given face. 0 <= *element_index* < num\\_local\\_elements + num\\_ghosts -* `face_index`:\\[in\\] Index of a face of *element*. -* `global_treeid`:\\[in\\] Global index of the tree that contains *element*. -* `dual_face`:\\[out\\] Return value, the dual\\_face index of the face neighbor. -# Returns -The index of the face neighbor leaf (local element or ghost). +* `forest`:\\[in,out\\] the forest. On input, it has been partitioned into equally-sized element partitions. On output, the partitioning has been adjusted such that no element families are split across the process boundaries. ### Prototype ```c -t8_locidx_t t8_forest_same_level_leaf_face_neighbor_index (const t8_forest_t forest, const t8_locidx_t element_index, const int face_index, const t8_gloidx_t global_treeid, int *dual_face); +void t8_forest_pfc_correction_offsets (t8_forest_t forest); ``` """ -function t8_forest_same_level_leaf_face_neighbor_index(forest, element_index, face_index, global_treeid, dual_face) - @ccall libt8.t8_forest_same_level_leaf_face_neighbor_index(forest::t8_forest_t, element_index::t8_locidx_t, face_index::Cint, global_treeid::t8_gloidx_t, dual_face::Ptr{Cint})::t8_locidx_t +function t8_forest_pfc_correction_offsets(forest) + @ccall libt8.t8_forest_pfc_correction_offsets(forest::t8_forest_t)::Cvoid end +# typedef int ( * t8_search_element_callback_c_wrapper ) ( t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index , void * user_data ) """ - t8_forest_leaf_neighbor_subface(forest, ltreeid, leaf, face, neighbor_tree_class, neighbor_leaf, neighbor_face) +A call-back function used by t8_forest_init_search for searching elements. Is called on an element and the search criterion should be checked on that element. Return true if the search criterion is met, false otherwise. -Compute the subface index for a coarser neighbor +# Arguments +* `forest`:\\[in\\] the forest +* `ltreeid`:\\[in\\] the local tree id of the current tree in the cmesh. +* `element`:\\[in\\] the element for which the search criterion is checked +* `is_leaf`:\\[in\\] true if and only if *element* is a leaf element +* `leaf_elements`:\\[in\\] the leaf elements in *forest* +* `tree_leaf_index`:\\[in\\] the local index of the first leaf in *leaf_elements* +* `user_data`:\\[in\\] a user data pointer that can be set by the user +# Returns +non-zero if the search criterion is met, zero otherwise. +""" +const t8_search_element_callback_c_wrapper = Ptr{Cvoid} -\\pre *leaf* and *neighbor_leaf* must be a face neighbors. The common face must correspond to *face* for *leaf* and *neighbor_face* for *neighbor_leaf* respectively. *neighbor_leaf* must be one level coarser than *leaf*. Otherwise the behavior is undefined. +# typedef int ( * t8_search_queries_callback_c_wrapper ) ( t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index , void * queries , void * user_data ) +""" +A call-back function used by t8_forest_init_search_with_queries for searching elements and executing queries. Is called on an element and all queries are checked on that element. All positive queries are passed further down to the children of the element up to leaf elements of the tree. The results of the check are stored in *query_matches*. -!!! note +# Arguments +* `forest`:\\[in\\] the forest +* `ltreeid`:\\[in\\] the local tree id of the current tree in the cmesh. +* `element`:\\[in\\] the element for which the search criterion is checked +* `is_leaf`:\\[in\\] true if and only if *element* is a leaf element +* `leaf_elements`:\\[in\\] the leaf elements in *forest* +* `tree_leaf_index`:\\[in\\] the local index of the first leaf in *leaf_elements* +* `queries`:\\[in\\] a pointer to an array of queries +* `user_data`:\\[in\\] a user data pointer that can be set by the user +""" +const t8_search_queries_callback_c_wrapper = Ptr{Cvoid} - This function is designed to be called after t8_forest_leaf_face_neighbors_ext to complement its output. It is primarily intended for balanced forests, but can be used on any committed forest as long as the preconditions hold (i.e. the forest must be ''locally balanced''). +# typedef void ( * t8_search_batched_queries_callback_c_wrapper ) ( t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index , const void * queries , const size_t * active_query_indices , int * query_matches , void * user_data ) +""" +A call-back function used by t8_forest_init_search_with_batched_queries for searching elements and executing batched queries. Is called on an element and all queries are checked on that element. All positive queries are passed further down to the children of the element up to leaf elements of the tree. The results of the check are stored in *query_matches*. # Arguments -* `forest`:\\[in\\] The forest. Must be committed. -* `ltreeid`:\\[in\\] A local tree id. -* `leaf`:\\[in\\] A leaf in *ltreeid*. -* `face`:\\[in\\] The face index of *leaf* to consider. -* `neighbor_tree_class`:\\[in\\] The eclass of the neighbor element. -* `neighbor_leaf`:\\[in\\] The leaf of *forest* on the other side of the face of index *face* of element *leaf*. -* `neighbor_face`:\\[in\\] The face index of *neighbor_leaf* (i.e. the dual face of *face*). -# Returns -The index of the subface of *neighbor_face* which corresponds to *face*. +* `forest`:\\[in\\] the forest +* `ltreeid`:\\[in\\] the local tree id of the current tree in the cmesh. +* `element`:\\[in\\] the element for which the search criterion is checked +* `is_leaf`:\\[in\\] true if and only if *element* is a leaf element +* `leaf_elements`:\\[in\\] the leaf elements in *forest* +* `tree_leaf_index`:\\[in\\] the local index of the first leaf in *leaf_elements* +* `queries`:\\[in\\] a pointer to an array of queries +* `active_query_indices`:\\[in\\] a pointer to an array of indices of active queries in *queries* +* `query_matches`:\\[in,out\\] a pointer to an array of length *num_active_queries*. If query\\_matches[i] is true, then the element 'matches' the query of the active query with index active\\_query\\_indices[i]. +* `user_data`:\\[in\\] a user data pointer that can be set by the user +""" +const t8_search_batched_queries_callback_c_wrapper = Ptr{Cvoid} + +mutable struct t8_forest_c_search end + +"""A wrapper around the forest search context""" +const t8_forest_search_c_wrapper = Ptr{t8_forest_c_search} + +""" + t8_forest_init_search(search, element_callback, forest) + ### Prototype ```c -int t8_forest_leaf_neighbor_subface (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *leaf, int face, t8_eclass_t neighbor_tree_class, const t8_element_t *neighbor_leaf, int neighbor_face); +void t8_forest_init_search (t8_forest_search_c_wrapper search, t8_search_element_callback_c_wrapper element_callback, const t8_forest_t forest); ``` """ -function t8_forest_leaf_neighbor_subface(forest, ltreeid, leaf, face, neighbor_tree_class, neighbor_leaf, neighbor_face) - @ccall libt8.t8_forest_leaf_neighbor_subface(forest::t8_forest_t, ltreeid::t8_locidx_t, leaf::Ptr{t8_element_t}, face::Cint, neighbor_tree_class::t8_eclass_t, neighbor_leaf::Ptr{t8_element_t}, neighbor_face::Cint)::Cint +function t8_forest_init_search(search, element_callback, forest) + @ccall libt8.t8_forest_init_search(search::t8_forest_search_c_wrapper, element_callback::t8_search_element_callback_c_wrapper, forest::t8_forest_t)::Cvoid end """ - t8_forest_ghost_exchange_data(forest, element_data) + t8_forest_search_update_forest(search, forest) -Exchange ghost information of user defined element data. +### Prototype +```c +void t8_forest_search_update_forest (t8_forest_search_c_wrapper search, const t8_forest_t forest); +``` +""" +function t8_forest_search_update_forest(search, forest) + @ccall libt8.t8_forest_search_update_forest(search::t8_forest_search_c_wrapper, forest::t8_forest_t)::Cvoid +end -!!! note +""" + t8_forest_search_update_user_data(search, udata) - This function is collective and hence must be called by all processes in the forest's MPI Communicator. +Update the user data pointer in the search context # Arguments -* `forest`:\\[in\\] The forest. Must be committed. -* `element_data`:\\[in\\] An array of length num\\_local\\_elements + num\\_ghosts storing one value for each local element and ghost in *forest*. After calling this function the entries for the ghost elements are update with the entries in the *element_data* array of the corresponding owning process. +* `search`:\\[in,out\\] the search context to update +* `udata`:\\[in\\] the new user data pointer to use ### Prototype ```c -void t8_forest_ghost_exchange_data (t8_forest_t forest, sc_array_t *element_data); +void t8_forest_search_update_user_data (t8_forest_search_c_wrapper search, void *udata); ``` """ -function t8_forest_ghost_exchange_data(forest, element_data) - @ccall libt8.t8_forest_ghost_exchange_data(forest::t8_forest_t, element_data::Ptr{sc_array_t})::Cvoid +function t8_forest_search_update_user_data(search, udata) + @ccall libt8.t8_forest_search_update_user_data(search::t8_forest_search_c_wrapper, udata::Ptr{Cvoid})::Cvoid end """ - t8_forest_ghost_print(forest) + t8_forest_search_do_search(search) -Print the ghost structure of a forest. Only used for debugging. +Perform the search +# Arguments +* `search`:\\[in,out\\] the search context to use ### Prototype ```c -void t8_forest_ghost_print (t8_forest_t forest); +void t8_forest_search_do_search (t8_forest_search_c_wrapper search); ``` """ -function t8_forest_ghost_print(forest) - @ccall libt8.t8_forest_ghost_print(forest::t8_forest_t)::Cvoid +function t8_forest_search_do_search(search) + @ccall libt8.t8_forest_search_do_search(search::t8_forest_search_c_wrapper)::Cvoid end """ - t8_forest_partition_cmesh(forest, comm, set_profiling) + t8_forest_search_destroy(search) + +Destroy the search context +# Arguments +* `search`:\\[in,out\\] the search context to destroy ### Prototype ```c -void t8_forest_partition_cmesh (t8_forest_t forest, sc_MPI_Comm comm, int set_profiling); +void t8_forest_search_destroy (t8_forest_search_c_wrapper search); ``` """ -function t8_forest_partition_cmesh(forest, comm, set_profiling) - @ccall libt8.t8_forest_partition_cmesh(forest::t8_forest_t, comm::MPI_Comm, set_profiling::Cint)::Cvoid +function t8_forest_search_destroy(search) + @ccall libt8.t8_forest_search_destroy(search::t8_forest_search_c_wrapper)::Cvoid end +mutable struct t8_forest_search_with_queries end + +"""A wrapper around the forest search with queries context""" +const t8_forest_search_with_queries_c_wrapper = Ptr{t8_forest_search_with_queries} + """ - t8_forest_get_mpicomm(forest) + t8_forest_init_search_with_queries(search_with_queries, element_callback, queries_callback, queries, num_queries, forest) ### Prototype ```c -sc_MPI_Comm t8_forest_get_mpicomm (const t8_forest_t forest); +void t8_forest_init_search_with_queries (t8_forest_search_with_queries_c_wrapper search_with_queries, t8_search_element_callback_c_wrapper element_callback, t8_search_queries_callback_c_wrapper queries_callback, void **queries, const size_t num_queries, const t8_forest_t forest); ``` """ -function t8_forest_get_mpicomm(forest) - @ccall libt8.t8_forest_get_mpicomm(forest::t8_forest_t)::MPI_Comm +function t8_forest_init_search_with_queries(search_with_queries, element_callback, queries_callback, queries, num_queries, forest) + @ccall libt8.t8_forest_init_search_with_queries(search_with_queries::t8_forest_search_with_queries_c_wrapper, element_callback::t8_search_element_callback_c_wrapper, queries_callback::t8_search_queries_callback_c_wrapper, queries::Ptr{Ptr{Cvoid}}, num_queries::Csize_t, forest::t8_forest_t)::Cvoid end """ - t8_forest_get_first_local_tree_id(forest) - -Return the global id of the first local tree of a forest. + t8_forest_search_with_queries_update_forest(search_with_queries, forest) -# Arguments -* `forest`:\\[in\\] The forest. -# Returns -The global id of the first local tree in *forest*. ### Prototype ```c -t8_gloidx_t t8_forest_get_first_local_tree_id (const t8_forest_t forest); +void t8_forest_search_with_queries_update_forest (t8_forest_search_with_queries_c_wrapper search_with_queries, const t8_forest_t forest); ``` """ -function t8_forest_get_first_local_tree_id(forest) - @ccall libt8.t8_forest_get_first_local_tree_id(forest::t8_forest_t)::t8_gloidx_t +function t8_forest_search_with_queries_update_forest(search_with_queries, forest) + @ccall libt8.t8_forest_search_with_queries_update_forest(search_with_queries::t8_forest_search_with_queries_c_wrapper, forest::t8_forest_t)::Cvoid end """ - t8_forest_get_num_local_trees(forest) + t8_forest_search_with_queries_update_user_data(search_with_queries, udata) -Return the number of local trees of a given forest. +Update the user data pointer in the search with queries context # Arguments -* `forest`:\\[in\\] The forest. -# Returns -The number of local trees of that forest. +* `search_with_queries`:\\[in,out\\] the search with queries context to update +* `udata`:\\[in\\] the new user data pointer to use ### Prototype ```c -t8_locidx_t t8_forest_get_num_local_trees (const t8_forest_t forest); +void t8_forest_search_with_queries_update_user_data (t8_forest_search_with_queries_c_wrapper search_with_queries, void *udata); ``` """ -function t8_forest_get_num_local_trees(forest) - @ccall libt8.t8_forest_get_num_local_trees(forest::t8_forest_t)::t8_locidx_t +function t8_forest_search_with_queries_update_user_data(search_with_queries, udata) + @ccall libt8.t8_forest_search_with_queries_update_user_data(search_with_queries::t8_forest_search_with_queries_c_wrapper, udata::Ptr{Cvoid})::Cvoid end """ - t8_forest_get_num_ghost_trees(forest) + t8_forest_search_with_queries_update_queries(search_with_queries, queries, num_queries) -Return the number of ghost trees of a given forest. +Update the queries in the search with queries context # Arguments -* `forest`:\\[in\\] The forest. -# Returns -The number of ghost trees of that forest. +* `search_with_queries`:\\[in,out\\] the search with queries context to update +* `queries`:\\[in\\] a pointer to an array of queries +* `num_queries`:\\[in\\] the number of queries in the array ### Prototype ```c -t8_locidx_t t8_forest_get_num_ghost_trees (const t8_forest_t forest); +void t8_forest_search_with_queries_update_queries (t8_forest_search_with_queries_c_wrapper search_with_queries, void **queries, const size_t num_queries); ``` """ -function t8_forest_get_num_ghost_trees(forest) - @ccall libt8.t8_forest_get_num_ghost_trees(forest::t8_forest_t)::t8_locidx_t +function t8_forest_search_with_queries_update_queries(search_with_queries, queries, num_queries) + @ccall libt8.t8_forest_search_with_queries_update_queries(search_with_queries::t8_forest_search_with_queries_c_wrapper, queries::Ptr{Ptr{Cvoid}}, num_queries::Csize_t)::Cvoid end """ - t8_forest_get_num_global_trees(forest) + t8_forest_search_with_queries_destroy(search) -Return the number of global trees of a given forest. +Destroy the search with queries context # Arguments -* `forest`:\\[in\\] The forest. -# Returns -The number of global trees of that forest. +* `search`:\\[in,out\\] the search with queries context to destroy ### Prototype ```c -t8_gloidx_t t8_forest_get_num_global_trees (const t8_forest_t forest); +void t8_forest_search_with_queries_destroy (t8_forest_search_with_queries_c_wrapper search); ``` """ -function t8_forest_get_num_global_trees(forest) - @ccall libt8.t8_forest_get_num_global_trees(forest::t8_forest_t)::t8_gloidx_t +function t8_forest_search_with_queries_destroy(search) + @ccall libt8.t8_forest_search_with_queries_destroy(search::t8_forest_search_with_queries_c_wrapper)::Cvoid end """ - t8_forest_global_tree_id(forest, ltreeid) - -Return the global id of a local tree or a ghost tree. - -# Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] An id 0 <= *ltreeid* < num\\_local\\_trees + num\\_ghosts specifying a local tree or ghost tree. -# Returns -The global id corresponding to the tree with local id *ltreeid*. *forest* must be committed before calling this function. -# See also -https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. + t8_forest_search_with_queries_do_search(search) +Perform the search with queries + +# Arguments +* `search`:\\[in,out\\] the search with queries context to use ### Prototype ```c -t8_gloidx_t t8_forest_global_tree_id (const t8_forest_t forest, const t8_locidx_t ltreeid); +void t8_forest_search_with_queries_do_search (t8_forest_search_with_queries_c_wrapper search); ``` """ -function t8_forest_global_tree_id(forest, ltreeid) - @ccall libt8.t8_forest_global_tree_id(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_gloidx_t +function t8_forest_search_with_queries_do_search(search) + @ccall libt8.t8_forest_search_with_queries_do_search(search::t8_forest_search_with_queries_c_wrapper)::Cvoid end -""" - t8_forest_get_tree(forest, ltree_id) +mutable struct t8_forest_search_with_batched_queries end -Return a pointer to a tree in a forest. +"""A wrapper around the forest search with batched queries context""" +const t8_forest_search_with_batched_queries_c_wrapper = Ptr{t8_forest_search_with_batched_queries} + +""" + t8_forest_init_search_with_batched_queries(search_with_queries, element_callback, queries_callback, queries, num_queries, forest) -# Arguments -* `forest`:\\[in\\] The forest. -* `ltree_id`:\\[in\\] The local id of the tree. -# Returns -A pointer to the tree with local id *ltree_id*. *forest* must be committed before calling this function. ### Prototype ```c -t8_tree_t t8_forest_get_tree (const t8_forest_t forest, const t8_locidx_t ltree_id); +void t8_forest_init_search_with_batched_queries (t8_forest_search_with_batched_queries_c_wrapper search_with_queries, t8_search_element_callback_c_wrapper element_callback, t8_search_batched_queries_callback_c_wrapper queries_callback, void **queries, const size_t num_queries, const t8_forest_t forest); ``` """ -function t8_forest_get_tree(forest, ltree_id) - @ccall libt8.t8_forest_get_tree(forest::t8_forest_t, ltree_id::t8_locidx_t)::t8_tree_t +function t8_forest_init_search_with_batched_queries(search_with_queries, element_callback, queries_callback, queries, num_queries, forest) + @ccall libt8.t8_forest_init_search_with_batched_queries(search_with_queries::t8_forest_search_with_batched_queries_c_wrapper, element_callback::t8_search_element_callback_c_wrapper, queries_callback::t8_search_batched_queries_callback_c_wrapper, queries::Ptr{Ptr{Cvoid}}, num_queries::Csize_t, forest::t8_forest_t)::Cvoid end """ - t8_forest_get_tree_vertices(forest, ltreeid) - -Return a pointer to the vertex coordinates of a tree. + t8_forest_search_with_batched_queries_update_forest(search_with_queries, forest) -# Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] 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. ### Prototype ```c -double * t8_forest_get_tree_vertices (t8_forest_t forest, t8_locidx_t ltreeid); +void t8_forest_search_with_batched_queries_update_forest ( t8_forest_search_with_batched_queries_c_wrapper search_with_queries, const t8_forest_t forest); ``` """ -function t8_forest_get_tree_vertices(forest, ltreeid) - @ccall libt8.t8_forest_get_tree_vertices(forest::t8_forest_t, ltreeid::t8_locidx_t)::Ptr{Cdouble} +function t8_forest_search_with_batched_queries_update_forest(search_with_queries, forest) + @ccall libt8.t8_forest_search_with_batched_queries_update_forest(search_with_queries::t8_forest_search_with_batched_queries_c_wrapper, forest::t8_forest_t)::Cvoid end """ - t8_forest_tree_get_leaf_elements(forest, ltree_id) + t8_forest_search_with_batched_queries_update_user_data(search_with_queries, udata) -Return the array of leaf elements of a local tree in a forest. +Update the user data pointer in the search with batched queries context # Arguments -* `forest`:\\[in\\] The forest. -* `ltree_id`:\\[in\\] The local id of a local tree of *forest*. -# Returns -An array of [`t8_element_t`](@ref) * storing all leaf elements of this tree. +* `search_with_queries`:\\[in,out\\] the search with batched queries context to update +* `udata`:\\[in\\] the new user data pointer to use ### Prototype ```c -t8_element_array_t * t8_forest_tree_get_leaf_elements (const t8_forest_t forest, const t8_locidx_t ltree_id); +void t8_forest_search_with_batched_queries_update_user_data ( t8_forest_search_with_batched_queries_c_wrapper search_with_queries, void *udata); ``` """ -function t8_forest_tree_get_leaf_elements(forest, ltree_id) - @ccall libt8.t8_forest_tree_get_leaf_elements(forest::t8_forest_t, ltree_id::t8_locidx_t)::Ptr{t8_element_array_t} +function t8_forest_search_with_batched_queries_update_user_data(search_with_queries, udata) + @ccall libt8.t8_forest_search_with_batched_queries_update_user_data(search_with_queries::t8_forest_search_with_batched_queries_c_wrapper, udata::Ptr{Cvoid})::Cvoid end """ - t8_forest_get_cmesh(forest) + t8_forest_search_with_batched_queries_update_queries(search_with_queries, queries, num_queries) -Return a cmesh associated to a forest. +Update the queries in the search with batched queries context # Arguments -* `forest`:\\[in\\] The forest. -# Returns -The cmesh associated to the forest. +* `search_with_queries`:\\[in,out\\] the search with batched queries context to update +* `queries`:\\[in\\] a pointer to an array of queries +* `num_queries`:\\[in\\] the number of queries in the array ### Prototype ```c -t8_cmesh_t t8_forest_get_cmesh (t8_forest_t forest); +void t8_forest_search_with_batched_queries_update_queries ( t8_forest_search_with_batched_queries_c_wrapper search_with_queries, void **queries, const size_t num_queries); ``` """ -function t8_forest_get_cmesh(forest) - @ccall libt8.t8_forest_get_cmesh(forest::t8_forest_t)::t8_cmesh_t +function t8_forest_search_with_batched_queries_update_queries(search_with_queries, queries, num_queries) + @ccall libt8.t8_forest_search_with_batched_queries_update_queries(search_with_queries::t8_forest_search_with_batched_queries_c_wrapper, queries::Ptr{Ptr{Cvoid}}, num_queries::Csize_t)::Cvoid end """ - t8_forest_get_leaf_element(forest, lelement_id, ltreeid) - -Return a leaf element of the forest. - -!!! note + t8_forest_search_with_batched_queries_destroy(search) - This function performs a binary search. For constant access, use t8_forest_get_leaf_element_in_tree *forest* must be committed before calling this function. +Destroy the search with batched queries context # Arguments -* `forest`:\\[in\\] The forest. -* `lelement_id`:\\[in\\] The local id of a leaf element in *forest*. -* `ltreeid`:\\[out\\] If not NULL, on output the local tree id of the tree in which the leaf element lies in. -# Returns -A pointer to the leaf element. NULL if this element does not exist. Ghost elements are not considered as local. -# See also -[`t8_forest_ghost_get_leaf_element`](@ref) to access ghost leaf elements. - +* `search`:\\[in,out\\] the search with batched queries context to destroy ### Prototype ```c -t8_element_t * t8_forest_get_leaf_element (t8_forest_t forest, t8_locidx_t lelement_id, t8_locidx_t *ltreeid); +void t8_forest_search_with_batched_queries_destroy (t8_forest_search_with_batched_queries_c_wrapper search); ``` """ -function t8_forest_get_leaf_element(forest, lelement_id, ltreeid) - @ccall libt8.t8_forest_get_leaf_element(forest::t8_forest_t, lelement_id::t8_locidx_t, ltreeid::Ptr{t8_locidx_t})::Ptr{t8_element_t} +function t8_forest_search_with_batched_queries_destroy(search) + @ccall libt8.t8_forest_search_with_batched_queries_destroy(search::t8_forest_search_with_batched_queries_c_wrapper)::Cvoid end """ - t8_forest_get_leaf_element_in_tree(forest, ltreeid, leid_in_tree) - -Return a leaf element of a local tree in a forest. - -!!! note + t8_forest_search_with_batched_queries_do_search(search) - If the tree id is know, this function should be preferred over t8_forest_get_leaf_element. *forest* must be committed before calling this function. +Perform the search with batched queries # Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] An id of a local tree in the forest. Ghost trees are not considered local. -* `leid_in_tree`:\\[in\\] The index of a leaf element in the tree. -# Returns -A pointer to the leaf element. -# See also -t8\\_forest\\_ghost\\_get\\_leaf\\_element\\_in\\_tree to access ghost leaf elements. - +* `search`:\\[in,out\\] the search with batched queries context to use ### Prototype ```c -const t8_element_t * t8_forest_get_leaf_element_in_tree (t8_forest_t forest, t8_locidx_t ltreeid, t8_locidx_t leid_in_tree); +void t8_forest_search_with_batched_queries_do_search (t8_forest_search_with_batched_queries_c_wrapper search); ``` """ -function t8_forest_get_leaf_element_in_tree(forest, ltreeid, leid_in_tree) - @ccall libt8.t8_forest_get_leaf_element_in_tree(forest::t8_forest_t, ltreeid::t8_locidx_t, leid_in_tree::t8_locidx_t)::Ptr{t8_element_t} +function t8_forest_search_with_batched_queries_do_search(search) + @ccall libt8.t8_forest_search_with_batched_queries_do_search(search::t8_forest_search_with_batched_queries_c_wrapper)::Cvoid end """ - t8_forest_get_tree_num_leaf_elements(forest, ltreeid) + t8_geom_get_name(geom) -Return the number of leaf elements of a tree. +Get the name of a geometry. # Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] A local id of a tree. +* `geom`:\\[in\\] A geometry. # Returns -The number of leaf elements in the local tree *ltreeid*. +The name of *geom*. ### Prototype ```c -t8_locidx_t t8_forest_get_tree_num_leaf_elements (t8_forest_t forest, t8_locidx_t ltreeid); +const char * t8_geom_get_name (const t8_geometry_c *geom); ``` """ -function t8_forest_get_tree_num_leaf_elements(forest, ltreeid) - @ccall libt8.t8_forest_get_tree_num_leaf_elements(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_locidx_t +function t8_geom_get_name(geom) + @ccall libt8.t8_geom_get_name(geom::Ptr{t8_geometry_c})::Cstring end """ - t8_forest_get_tree_element_offset(forest, ltreeid) - -Return the element offset of a local tree, that is the number of leaf elements in all trees with smaller local treeid. - -!!! note + t8_geom_get_type(geom) - *forest* must be committed before calling this function. +Get the type of a geometry. # Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] A local id of a tree. +* `geom`:\\[in\\] A geometry. # Returns -The number of leaf elements on all local tree with id < *ltreeid*. +The type of *geom*. ### Prototype ```c -t8_locidx_t t8_forest_get_tree_element_offset (const t8_forest_t forest, const t8_locidx_t ltreeid); +t8_geometry_type_t t8_geom_get_type (const t8_geometry_c *geom); ``` """ -function t8_forest_get_tree_element_offset(forest, ltreeid) - @ccall libt8.t8_forest_get_tree_element_offset(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_locidx_t +function t8_geom_get_type(geom) + @ccall libt8.t8_geom_get_type(geom::Ptr{t8_geometry_c})::t8_geometry_type_t end """ - t8_forest_get_tree_leaf_element_count(tree) - -Return the number of leaf elements of a tree. + t8_geom_compute_linear_geometry(tree_class, tree_vertices, ref_coords, num_coords, out_coords) -# Arguments -* `tree`:\\[in\\] A tree in a forest. -# Returns -The number of leaf elements of that tree. ### Prototype ```c -t8_locidx_t t8_forest_get_tree_leaf_element_count (t8_tree_t tree); +void t8_geom_compute_linear_geometry (t8_eclass_t tree_class, const double *tree_vertices, const double *ref_coords, const size_t num_coords, double *out_coords); ``` """ -function t8_forest_get_tree_leaf_element_count(tree) - @ccall libt8.t8_forest_get_tree_leaf_element_count(tree::t8_tree_t)::t8_locidx_t +function t8_geom_compute_linear_geometry(tree_class, tree_vertices, ref_coords, num_coords, out_coords) + @ccall libt8.t8_geom_compute_linear_geometry(tree_class::Cint, tree_vertices::Ptr{Cdouble}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid end """ - t8_forest_get_tree_class(forest, ltreeid) - -Return the eclass of a tree in a forest. + t8_geom_compute_linear_axis_aligned_geometry(tree_class, tree_vertices, ref_coords, num_coords, out_coords) -# Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] The local id of a tree (local or ghost) in *forest*. -# Returns -The element class of the tree with local id *ltreeid*. ### Prototype ```c -t8_eclass_t t8_forest_get_tree_class (const t8_forest_t forest, const t8_locidx_t ltreeid); +void t8_geom_compute_linear_axis_aligned_geometry (t8_eclass_t tree_class, const double *tree_vertices, const double *ref_coords, const size_t num_coords, double *out_coords); ``` """ -function t8_forest_get_tree_class(forest, ltreeid) - @ccall libt8.t8_forest_get_tree_class(forest::t8_forest_t, ltreeid::t8_locidx_t)::t8_eclass_t +function t8_geom_compute_linear_axis_aligned_geometry(tree_class, tree_vertices, ref_coords, num_coords, out_coords) + @ccall libt8.t8_geom_compute_linear_axis_aligned_geometry(tree_class::Cint, tree_vertices::Ptr{Cdouble}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid end """ - t8_forest_get_first_local_leaf_element_id(forest) + t8_geom_linear_interpolation(coefficients, corner_values, corner_value_dim, interpolation_dim, evaluated_function) -Compute the global index of the first local leaf element of a forest. This function is collective. +Interpolates linearly between 2, bilinearly between 4 or trilineraly between 8 points. # Arguments -* `forest`:\\[in\\] A committed forest, whose first leaf element's index is computed. -# Returns -The global index of *forest*'s first local leaf element. Forest must be committed when calling this function. This function is collective and must be called on each process. +* `coefficients`:\\[in\\] An array of size at least dim giving the coefficients used for the interpolation +* `corner_values`:\\[in\\] An array of size 2^dim * 3, giving for each corner (in zorder) of the unit square/cube its function values in space. +* `corner_value_dim`:\\[in\\] The dimension of the *corner_values*. +* `interpolation_dim`:\\[in\\] The dimension of the interpolation (1 for linear, 2 for bilinear, 3 for trilinear) +* `evaluated_function`:\\[out\\] An array of size *corner_value_dim*, on output the result of the interpolation. ### Prototype ```c -t8_gloidx_t t8_forest_get_first_local_leaf_element_id (t8_forest_t forest); +void t8_geom_linear_interpolation (const double *coefficients, const double *corner_values, int corner_value_dim, int interpolation_dim, double *evaluated_function); ``` """ -function t8_forest_get_first_local_leaf_element_id(forest) - @ccall libt8.t8_forest_get_first_local_leaf_element_id(forest::t8_forest_t)::t8_gloidx_t +function t8_geom_linear_interpolation(coefficients, corner_values, corner_value_dim, interpolation_dim, evaluated_function) + @ccall libt8.t8_geom_linear_interpolation(coefficients::Ptr{Cdouble}, corner_values::Ptr{Cdouble}, corner_value_dim::Cint, interpolation_dim::Cint, evaluated_function::Ptr{Cdouble})::Cvoid end """ - t8_forest_get_scheme(forest) + t8_geom_triangular_interpolation(coefficients, corner_values, corner_value_dim, interpolation_dim, evaluated_function) -Return the element scheme associated to a forest. +Triangular interpolation between 3 points (triangle) or 4 points (tetrahedron) using cartesian coordinates. The input coefficients have to be given as coordinates in the reference triangle (interpolation\\_dim = 2) with points (0,0) (1,0) (1,1) or the reference tet (interpolation\\_dim = 3) with points (0,0,0) (1,0,0) (1,1,0) (1,1,1). # Arguments -* `forest`:\\[in\\] A committed forest. -# Returns -The element scheme of the forest. -# See also -[`t8_forest_set_scheme`](@ref) - +* `coefficients`:\\[in\\] An array of size *interpolation_dim* giving the coefficients in the reference triangle/tet used for the interpolation +* `corner_values`:\\[in\\] An array of size 3 * *corner_value_dim* for *interpolation_dim* == 2 or 4 * *corner_value_dim* for *interpolation_dim* == 3, giving the function values of the triangle/tetrahedron for each corner (in zorder) +* `corner_value_dim`:\\[in\\] The dimension of the *corner_values*. +* `interpolation_dim`:\\[in\\] The dimension of the interpolation (2 for triangle, 3 for tetrahedron) +* `evaluated_function`:\\[out\\] An array of size *corner_value_dim*, on output the result of the interpolation. ### Prototype ```c -const t8_scheme_c * t8_forest_get_scheme (const t8_forest_t forest); +void t8_geom_triangular_interpolation (const double *coefficients, const double *corner_values, int corner_value_dim, int interpolation_dim, double *evaluated_function); ``` """ -function t8_forest_get_scheme(forest) - @ccall libt8.t8_forest_get_scheme(forest::t8_forest_t)::Ptr{t8_scheme_c} +function t8_geom_triangular_interpolation(coefficients, corner_values, corner_value_dim, interpolation_dim, evaluated_function) + @ccall libt8.t8_geom_triangular_interpolation(coefficients::Ptr{Cdouble}, corner_values::Ptr{Cdouble}, corner_value_dim::Cint, interpolation_dim::Cint, evaluated_function::Ptr{Cdouble})::Cvoid end """ - t8_forest_element_neighbor_eclass(forest, ltreeid, elem, face) - -Return the eclass of the tree in which a face neighbor of a given element or ghost lies. + t8_geom_get_face_vertices(tree_class, tree_vertices, face_index, dim, face_vertices) -# Arguments -* `forest`:\\[in\\] A committed forest. -* `ltreeid`:\\[in\\] The local tree or ghost tree in which the element lies. 0 <= *ltreeid* < num\\_local\\_trees + num\\_ghost\\_trees -* `elem`:\\[in\\] An element or ghost in the tree *ltreeid*. -* `face`:\\[in\\] A face number of *elem*. -# Returns -The eclass of the local tree or ghost tree that is face neighbor of *elem* across *face*. T8\\_ECLASS\\_INVALID if no neighbor exists. ### Prototype ```c -t8_eclass_t t8_forest_element_neighbor_eclass (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *elem, const int face); +void t8_geom_get_face_vertices (t8_eclass_t tree_class, const double *tree_vertices, int face_index, int dim, double *face_vertices); ``` """ -function t8_forest_element_neighbor_eclass(forest, ltreeid, elem, face) - @ccall libt8.t8_forest_element_neighbor_eclass(forest::t8_forest_t, ltreeid::t8_locidx_t, elem::Ptr{t8_element_t}, face::Cint)::t8_eclass_t +function t8_geom_get_face_vertices(tree_class, tree_vertices, face_index, dim, face_vertices) + @ccall libt8.t8_geom_get_face_vertices(tree_class::Cint, tree_vertices::Ptr{Cdouble}, face_index::Cint, dim::Cint, face_vertices::Ptr{Cdouble})::Cvoid end """ - t8_forest_element_face_neighbor(forest, ltreeid, elem, neigh, neigh_eclass, face, neigh_face) - -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. - -# Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] The local tree in which the element lies. -* `elem`:\\[in\\] The element to be considered. -* `neigh`:\\[in,out\\] 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. -* `neigh_eclass`:\\[in\\] The eclass of *neigh*. -* `face`:\\[in\\] The number of the face along which the neighbor should be constructed. -* `neigh_face`:\\[out\\] The number of the face viewed from perspective of *neigh*. Can be nullptr, in which case the output is discarded. -# Returns -The global tree-id of the tree in which *neigh* is in. -1 if there exists no neighbor across that face. Domain boundary. -2 if the neighbor is not in a local tree or ghost tree. Process/Ghost boundary. + t8_geom_get_edge_vertices(tree_class, tree_vertices, edge_index, dim, edge_vertices) + ### Prototype ```c -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); +void t8_geom_get_edge_vertices (t8_eclass_t tree_class, const double *tree_vertices, int edge_index, int dim, double *edge_vertices); ``` """ -function t8_forest_element_face_neighbor(forest, ltreeid, elem, neigh, neigh_eclass, face, neigh_face) - @ccall libt8.t8_forest_element_face_neighbor(forest::t8_forest_t, ltreeid::t8_locidx_t, elem::Ptr{t8_element_t}, neigh::Ptr{t8_element_t}, neigh_eclass::t8_eclass_t, face::Cint, neigh_face::Ptr{Cint})::t8_gloidx_t +function t8_geom_get_edge_vertices(tree_class, tree_vertices, edge_index, dim, edge_vertices) + @ccall libt8.t8_geom_get_edge_vertices(tree_class::Cint, tree_vertices::Ptr{Cdouble}, edge_index::Cint, dim::Cint, edge_vertices::Ptr{Cdouble})::Cvoid end """ - t8_forest_iterate(forest) + t8_geom_get_ref_intersection(edge_index, ref_coords, ref_intersection) -TODO: Can be removed since it is unused. +Calculates a point of intersection in a triangular reference space. The intersection is the extension of a straight line passing through a reference point and the opposite vertex of the edge. /|\\ / | \\ o -> reference point / o \\ x -> intersection point / | \\ /\\_\\_\\_\\_x\\_\\_\\_\\_\\ # Arguments -* `forest`:\\[in\\] The forest. +* `edge_index`:\\[in\\] Index of the edge, the intersection lies on. +* `ref_coords`:\\[in\\] Array containing the coordinates of the reference point. +* `ref_intersection`:\\[out\\] Coordinates of the intersection point. ### Prototype ```c -void t8_forest_iterate (t8_forest_t forest); +void t8_geom_get_ref_intersection (int edge_index, const double *ref_coords, double ref_intersection[2]); ``` """ -function t8_forest_iterate(forest) - @ccall libt8.t8_forest_iterate(forest::t8_forest_t)::Cvoid +function t8_geom_get_ref_intersection(edge_index, ref_coords, ref_intersection) + @ccall libt8.t8_geom_get_ref_intersection(edge_index::Cint, ref_coords::Ptr{Cdouble}, ref_intersection::Ptr{Cdouble})::Cvoid end """ - t8_forest_element_points_inside(forest, ltreeid, element, points, num_points, is_inside, tolerance) - -Query whether a batch of points lies inside an element. For bilinearly interpolated elements. - -!!! note + t8_geom_get_triangle_scaling_factor(edge_index, tree_vertices, glob_intersection, glob_ref_point) - For 2D quadrilateral elements this function is only an approximation. It is correct 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. +Calculates the scaling factor for edge displacement along a triangular tree face depending on the position of the global reference point. # Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] The forest local id of the tree in which the element is. -* `element`:\\[in\\] The element. -* `points`:\\[in\\] 3-dimensional coordinates of the points to check -* `num_points`:\\[in\\] The number of points to check -* `is_inside`:\\[in,out\\] An array of length *num_points*, filled with 0/1 on output. True (non-zero) if a *point* lies within an *element*, false otherwise. The return value is also true if the point lies on the element boundary. Thus, this function may return true for different leaf elements, if they are neighbors and the point lies on the common boundary. -* `tolerance`:\\[in\\] Tolerance that we allow the point to not exactly match the element. If this value is larger we detect more points. If it is zero we probably do not detect points even if they are inside due to rounding errors. +* `edge_index`:\\[in\\] Index of the edge, whose displacement should be scaled. +* `tree_vertices`:\\[in\\] Array with the tree vertex coordinates. +* `glob_intersection`:\\[in\\] Array containing the coordinates of the intersection point of a line drawn from the opposite vertex through the glob\\_ref\\_point onto the edge with edge\\_index. +* `glob_ref_point`:\\[in\\] Array containing the coordinates of the reference point mapped into the global space. ### Prototype ```c -void t8_forest_element_points_inside (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, const double *points, int num_points, int *is_inside, const double tolerance); +double t8_geom_get_triangle_scaling_factor (int edge_index, const double *tree_vertices, const double *glob_intersection, const double *glob_ref_point); ``` """ -function t8_forest_element_points_inside(forest, ltreeid, element, points, num_points, is_inside, tolerance) - @ccall libt8.t8_forest_element_points_inside(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, points::Ptr{Cdouble}, num_points::Cint, is_inside::Ptr{Cint}, tolerance::Cdouble)::Cvoid +function t8_geom_get_triangle_scaling_factor(edge_index, tree_vertices, glob_intersection, glob_ref_point) + @ccall libt8.t8_geom_get_triangle_scaling_factor(edge_index::Cint, tree_vertices::Ptr{Cdouble}, glob_intersection::Ptr{Cdouble}, glob_ref_point::Ptr{Cdouble})::Cdouble end """ - t8_forest_element_find_owner(forest, gtreeid, element, eclass) - -Find the owner process of a given 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. - -!!! note + t8_geom_get_scaling_factor_of_edge_on_face_tet(edge_index, face_index, ref_coords) - *forest* must be committed before calling this function. +Calculates the scaling factor for the displacement of an edge over a face of a tetrahedral element. # Arguments -* `forest`:\\[in\\] The forest. -* `gtreeid`:\\[in\\] The global id of the tree in which the element lies. -* `element`:\\[in\\] The element to look for. -* `eclass`:\\[in\\] The element class of the tree *gtreeid*. +* `edge_index`:\\[in\\] Index of the edge, whose displacement should be scaled. +* `face_index`:\\[in\\] Index of the face, the displacement should be scaled on. +* `ref_coords`:\\[in\\] Array containing the coordinates of the reference point. # Returns -The mpirank of the process that owns *element*. -# See also -t8\\_forest\\_element\\_find\\_owner\\_ext, t8\\_forest\\_element\\_owners\\_bounds - +The scaling factor of the edge displacement on the face at the point of the reference coordinates. ### Prototype ```c -int t8_forest_element_find_owner (t8_forest_t forest, t8_gloidx_t gtreeid, t8_element_t *element, t8_eclass_t eclass); +double t8_geom_get_scaling_factor_of_edge_on_face_tet (int edge_index, int face_index, const double *ref_coords); ``` """ -function t8_forest_element_find_owner(forest, gtreeid, element, eclass) - @ccall libt8.t8_forest_element_find_owner(forest::t8_forest_t, gtreeid::t8_gloidx_t, element::Ptr{t8_element_t}, eclass::t8_eclass_t)::Cint +function t8_geom_get_scaling_factor_of_edge_on_face_tet(edge_index, face_index, ref_coords) + @ccall libt8.t8_geom_get_scaling_factor_of_edge_on_face_tet(edge_index::Cint, face_index::Cint, ref_coords::Ptr{Cdouble})::Cdouble end """ - t8_forest_new_uniform(cmesh, scheme, level, do_face_ghost, comm) + t8_geom_get_tet_face_intersection(face_index, ref_coords, face_intersection) + +Calculates the face intersection of a ray passing trough the reference coordinates and the opposite vertex of that face for a tetrahedron. The coordinates of the face intersection are reference coordinates: [0,1]^3. +# Arguments +* `face_index`:\\[in\\] Index of the face, on which the intersection should be calculated. +* `ref_coords`:\\[in\\] Array containing the coordinates of the reference point. +* `face_intersection`:\\[out\\] Three dimensional array containing the intersection point on the face in reference space. ### Prototype ```c -t8_forest_t t8_forest_new_uniform (t8_cmesh_t cmesh, const t8_scheme_c *scheme, const int level, const int do_face_ghost, sc_MPI_Comm comm); +void t8_geom_get_tet_face_intersection (const int face_index, const double *ref_coords, double face_intersection[3]); ``` """ -function t8_forest_new_uniform(cmesh, scheme, level, do_face_ghost, comm) - @ccall libt8.t8_forest_new_uniform(cmesh::t8_cmesh_t, scheme::Ptr{t8_scheme_c}, level::Cint, do_face_ghost::Cint, comm::MPI_Comm)::t8_forest_t +function t8_geom_get_tet_face_intersection(face_index, ref_coords, face_intersection) + @ccall libt8.t8_geom_get_tet_face_intersection(face_index::Cint, ref_coords::Ptr{Cdouble}, face_intersection::Ptr{Cdouble})::Cvoid end """ - t8_forest_new_adapt(forest_from, adapt_fn, recursive, do_face_ghost, user_data) - -Build a adapted forest from another forest. - -!!! note + t8_geom_get_scaling_factor_of_edge_on_face_prism(edge_index, face_index, ref_coords) - This is equivalent to calling t8_forest_init, t8_forest_set_adapt, t8_forest_set_ghost, and t8_forest_commit +Calculates the scaling factor for the displacement of an edge over a face of a prism element. # Arguments -* `forest_from`:\\[in\\] The forest to refine -* `adapt_fn`:\\[in\\] Adapt function to use -* `recursive`:\\[in\\] If true adaptation is recursive -* `do_face_ghost`:\\[in\\] If true, a layer of ghost elements is created for the forest. -* `user_data`:\\[in\\] If not NULL, the user data pointer of the forest is set to this value. +* `edge_index`:\\[in\\] Index of the edge, whose displacement should be scaled. +* `face_index`:\\[in\\] Index of the face, the displacement should be scaled on. +* `ref_coords`:\\[in\\] Array containing the coordinates of the reference point. # Returns -A new forest that is adapted from *forest_from*. +The scaling factor of the edge displacement on the face at the point of the reference coordinates. ### Prototype ```c -t8_forest_t t8_forest_new_adapt (t8_forest_t forest_from, t8_forest_adapt_t adapt_fn, int recursive, int do_face_ghost, void *user_data); +double t8_geom_get_scaling_factor_of_edge_on_face_prism (int edge_index, int face_index, const double *ref_coords); ``` """ -function t8_forest_new_adapt(forest_from, adapt_fn, recursive, do_face_ghost, user_data) - @ccall libt8.t8_forest_new_adapt(forest_from::t8_forest_t, adapt_fn::t8_forest_adapt_t, recursive::Cint, do_face_ghost::Cint, user_data::Ptr{Cvoid})::t8_forest_t +function t8_geom_get_scaling_factor_of_edge_on_face_prism(edge_index, face_index, ref_coords) + @ccall libt8.t8_geom_get_scaling_factor_of_edge_on_face_prism(edge_index::Cint, face_index::Cint, ref_coords::Ptr{Cdouble})::Cdouble end """ - t8_forest_ref(forest) + t8_geom_get_scaling_factor_face_through_volume_prism(face, ref_coords) -Increase the reference counter of a forest. +Calculates the scaling factor for the displacement of an face through the volume of a prism element. # Arguments -* `forest`:\\[in,out\\] On input, this forest must exist with positive reference count. It may be in any state. +* `face`:\\[in\\] Index of the displaced face. +* `ref_coords`:\\[in\\] Array containing the coordinates of the reference point. +# Returns +The scaling factor of the face displacement at the point of the reference coordinates inside the prism volume. ### Prototype ```c -void t8_forest_ref (t8_forest_t forest); +double t8_geom_get_scaling_factor_face_through_volume_prism (const int face, const double *ref_coords); ``` """ -function t8_forest_ref(forest) - @ccall libt8.t8_forest_ref(forest::t8_forest_t)::Cvoid +function t8_geom_get_scaling_factor_face_through_volume_prism(face, ref_coords) + @ccall libt8.t8_geom_get_scaling_factor_face_through_volume_prism(face::Cint, ref_coords::Ptr{Cdouble})::Cdouble end """ - t8_forest_unref(pforest) + t8_vertex_point_inside(vertex_coords, point, tolerance) -Decrease the reference counter of a forest. If the counter reaches zero, this forest is destroyed. In this case, the forest dereferences its cmesh and scheme members. +Check if a point lies inside a vertex # Arguments -* `pforest`:\\[in,out\\] On input, the forest pointed to must exist with positive reference count. It may be in any state. If the reference count reaches zero, the forest is destroyed and this pointer set to NULL. Otherwise, the pointer is not changed and the forest is not modified in other ways. +* `vertex_coords`:\\[in\\] The coordinates of the vertex +* `point`:\\[in\\] The coordinates of the point to check +* `tolerance`:\\[in\\] A double > 0 defining the tolerance +# Returns +0 if the point is outside, 1 otherwise. ### Prototype ```c -void t8_forest_unref (t8_forest_t *pforest); +int t8_vertex_point_inside (const double vertex_coords[3], const double point[3], const double tolerance); ``` """ -function t8_forest_unref(pforest) - @ccall libt8.t8_forest_unref(pforest::Ptr{t8_forest_t})::Cvoid +function t8_vertex_point_inside(vertex_coords, point, tolerance) + @ccall libt8.t8_vertex_point_inside(vertex_coords::Ptr{Cdouble}, point::Ptr{Cdouble}, tolerance::Cdouble)::Cint end """ - t8_forest_get_dimension(forest) + t8_line_point_inside(p_0, vec, point, tolerance) +Check if a point is inside a line that is defined by a starting point *p_0* and a vector *vec* + +# Arguments +* `p_0`:\\[in\\] Starting point of the line +* `vec`:\\[in\\] Direction of the line (not normalized) +* `point`:\\[in\\] The coordinates of the point to check +* `tolerance`:\\[in\\] A double > 0 defining the tolerance +# Returns +0 if the point is outside, 1 otherwise. ### Prototype ```c -int t8_forest_get_dimension (const t8_forest_t forest); +int t8_line_point_inside (const double *p_0, const double *vec, const double *point, const double tolerance); ``` """ -function t8_forest_get_dimension(forest) - @ccall libt8.t8_forest_get_dimension(forest::t8_forest_t)::Cint +function t8_line_point_inside(p_0, vec, point, tolerance) + @ccall libt8.t8_line_point_inside(p_0::Ptr{Cdouble}, vec::Ptr{Cdouble}, point::Ptr{Cdouble}, tolerance::Cdouble)::Cint end """ - t8_forest_element_coordinate(forest, ltree_id, element, corner_number, coordinates) + t8_triangle_point_inside(p_0, v, w, point, tolerance) + +Check if a point is inside of a triangle described by a point *p_0* and two vectors *v* and *w*. +# Arguments +* `p_0`:\\[in\\] The first vertex of a triangle +* `v`:\\[in\\] The vector from p\\_0 to p\\_1 (second vertex in the triangle) +* `w`:\\[in\\] The vector from p\\_0 to p\\_2 (third vertex in the triangle) +* `point`:\\[in\\] The coordinates of the point to check +* `tolerance`:\\[in\\] A double > 0 defining the tolerance +# Returns +0 if the point is outside, 1 otherwise. ### Prototype ```c -void t8_forest_element_coordinate (t8_forest_t forest, t8_locidx_t ltree_id, const t8_element_t *element, int corner_number, double *coordinates); +int t8_triangle_point_inside (const double p_0[3], const double v[3], const double w[3], const double point[3], const double tolerance); ``` """ -function t8_forest_element_coordinate(forest, ltree_id, element, corner_number, coordinates) - @ccall libt8.t8_forest_element_coordinate(forest::t8_forest_t, ltree_id::t8_locidx_t, element::Ptr{t8_element_t}, corner_number::Cint, coordinates::Ptr{Cdouble})::Cvoid +function t8_triangle_point_inside(p_0, v, w, point, tolerance) + @ccall libt8.t8_triangle_point_inside(p_0::Ptr{Cdouble}, v::Ptr{Cdouble}, w::Ptr{Cdouble}, point::Ptr{Cdouble}, tolerance::Cdouble)::Cint end """ - t8_forest_element_from_ref_coords_ext(forest, ltreeid, element, ref_coords, num_coords, coords_out, stretch_factors) + t8_plane_point_inside(point_on_face, face_normal, point) + +Check if a point lays on the inner side of a plane of a bilinearly interpolated volume element. the plane is described by a point and the normal of the face. +# Arguments +* `point_on_face`:\\[in\\] A point on the plane +* `face_normal`:\\[in\\] The normal of the face +* `point`:\\[in\\] The point to check +# Returns +0 if the point is outside, 1 otherwise. ### Prototype ```c -void t8_forest_element_from_ref_coords_ext (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, const double *ref_coords, const size_t num_coords, double *coords_out, const double *stretch_factors); +int t8_plane_point_inside (const double point_on_face[3], const double face_normal[3], const double point[3]); ``` """ -function t8_forest_element_from_ref_coords_ext(forest, ltreeid, element, ref_coords, num_coords, coords_out, stretch_factors) - @ccall libt8.t8_forest_element_from_ref_coords_ext(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, coords_out::Ptr{Cdouble}, stretch_factors::Ptr{Cdouble})::Cvoid +function t8_plane_point_inside(point_on_face, face_normal, point) + @ccall libt8.t8_plane_point_inside(point_on_face::Ptr{Cdouble}, face_normal::Ptr{Cdouble}, point::Ptr{Cdouble})::Cint end +# typedef void ( * t8_geom_analytic_fn ) ( t8_cmesh_t cmesh , t8_gloidx_t gtreeid , const double * ref_coords , const size_t num_coords , double * out_coords , const void * tree_data , const void * user_data ) """ - t8_forest_element_from_ref_coords(forest, ltreeid, element, ref_coords, num_coords, coords_out) +Definition of an analytic geometry function. This function maps reference coordinates to physical coordinates. -### Prototype -```c -void t8_forest_element_from_ref_coords (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, const double *ref_coords, const size_t num_coords, double *coords_out); +```c++ + [0,1]^\\mathrm{dim} ``` + +. + +# Arguments +* `cmesh`:\\[in\\] The cmesh. +* `gtreeid`:\\[in\\] The global tree (of the cmesh) in which the reference point is. +* `ref_coords`:\\[in\\] Array of dimension x *num_coords* many entries, specifying a point in +* `num_coords`:\\[in\\] The number of coordinates in *ref_coords*. +* `out_coords`:\\[out\\] The mapped coordinates in physical space of *ref_coords*. The length is *num_coords* * 3. +* `tree_data`:\\[in\\] The data of the current tree as loaded by a t8_geom_load_tree_data_fn. +* `user_data`:\\[in\\] The user data pointer stored in the geometry. """ -function t8_forest_element_from_ref_coords(forest, ltreeid, element, ref_coords, num_coords, coords_out) - @ccall libt8.t8_forest_element_from_ref_coords(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, coords_out::Ptr{Cdouble})::Cvoid -end +const t8_geom_analytic_fn = Ptr{Cvoid} +# typedef void ( * t8_geom_analytic_jacobian_fn ) ( t8_cmesh_t cmesh , t8_gloidx_t gtreeid , const double * ref_coords , const size_t num_coords , double * jacobian , const void * tree_data , const void * user_data ) """ - t8_forest_element_centroid(forest, ltreeid, element, coordinates) +Definition for the jacobian of an analytic geometry function. -### Prototype -```c -void t8_forest_element_centroid (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, double *coordinates); +```c++ + [0,1]^\\mathrm{dim} +``` + +. + +```c++ + \\mathrm{dim} +``` + +to map. + +```c++ + \\mathrm{dim} \\cdot 3 +``` + +x *num_coords*. Indices + +```c++ + 3 \\cdot i +``` + +, + +```c++ + 3 \\cdot i+1 ``` -""" -function t8_forest_element_centroid(forest, ltreeid, element, coordinates) - @ccall libt8.t8_forest_element_centroid(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, coordinates::Ptr{Cdouble})::Cvoid -end -""" - t8_forest_element_linear_centroid(forest, ltreeid, element, coordinates) +, -### Prototype -```c -void t8_forest_element_linear_centroid (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *element, double *coordinates); +```c++ + 3 \\cdot i+2 ``` -""" -function t8_forest_element_linear_centroid(forest, ltreeid, element, coordinates) - @ccall libt8.t8_forest_element_linear_centroid(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, coordinates::Ptr{Cdouble})::Cvoid -end -""" - t8_forest_element_diam(forest, ltreeid, element) +correspond to the -### Prototype -```c -double t8_forest_element_diam (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element); +```c++ + i ``` -""" -function t8_forest_element_diam(forest, ltreeid, element) - @ccall libt8.t8_forest_element_diam(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t})::Cdouble -end -""" - t8_forest_element_volume(forest, ltreeid, element) +-th column of the jacobian (Entry -### Prototype -```c -double t8_forest_element_volume (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element); +```c++ + 3 \\cdot i + j ``` -""" -function t8_forest_element_volume(forest, ltreeid, element) - @ccall libt8.t8_forest_element_volume(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t})::Cdouble -end -""" - t8_forest_element_face_area(forest, ltreeid, element, face) +is -### Prototype -```c -double t8_forest_element_face_area (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, int face); +```c++ + \\frac{\\partial f_j}{\\partial x_i} ``` + +). + +# Arguments +* `cmesh`:\\[in\\] The cmesh. +* `gtreeid`:\\[in\\] The global tree (of the cmesh) in which the reference point is. +* `ref_coords`:\\[in\\] Array of tree dimension x *num_coords* many entries, specifying points in +* `num_coords`:\\[in\\] Amount of points of +* `jacobian`:\\[out\\] The jacobian at *ref_coords*. Array of size +* `tree_data`:\\[in\\] The data of the current tree as loaded by a t8_geom_load_tree_data_fn. +* `user_data`:\\[in\\] The user data pointer stored in the geometry. """ -function t8_forest_element_face_area(forest, ltreeid, element, face) - @ccall libt8.t8_forest_element_face_area(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, face::Cint)::Cdouble -end +const t8_geom_analytic_jacobian_fn = Ptr{Cvoid} +# typedef void ( * t8_geom_load_tree_data_fn ) ( t8_cmesh_t cmesh , t8_gloidx_t gtreeid , const void * * tree_data ) """ - t8_forest_element_face_centroid(forest, ltreeid, element, face, centroid) +Definition for the load tree data function. -### Prototype -```c -void t8_forest_element_face_centroid (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, int face, double centroid[3]); -``` +# Arguments +* `cmesh`:\\[in\\] The cmesh. +* `gtreeid`:\\[in\\] The global tree (of the cmesh) in which the reference point is. +* `tree_data`:\\[in\\] The data of the trees. """ -function t8_forest_element_face_centroid(forest, ltreeid, element, face, centroid) - @ccall libt8.t8_forest_element_face_centroid(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, face::Cint, centroid::Ptr{Cdouble})::Cvoid -end +const t8_geom_load_tree_data_fn = Ptr{Cvoid} + +# typedef int ( * t8_geom_tree_negative_volume_fn ) ( ) +"""Definition for the negative volume function.""" +const t8_geom_tree_negative_volume_fn = Ptr{Cvoid} + +# typedef int ( * t8_geom_tree_compatible_fn ) ( ) +"""Definition for the tree compatible function.""" +const t8_geom_tree_compatible_fn = Ptr{Cvoid} """ - t8_forest_element_face_normal(forest, ltreeid, element, face, normal) + t8_geometry_analytic_destroy(geom) +Destroy a geometry analytic object. + +# Arguments +* `geom`:\\[in,out\\] A pointer to a geometry object. Set to NULL on output. ### Prototype ```c -void t8_forest_element_face_normal (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, int face, double normal[3]); +void t8_geometry_analytic_destroy (t8_geometry_c **geom); ``` """ -function t8_forest_element_face_normal(forest, ltreeid, element, face, normal) - @ccall libt8.t8_forest_element_face_normal(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, face::Cint, normal::Ptr{Cdouble})::Cvoid +function t8_geometry_analytic_destroy(geom) + @ccall libt8.t8_geometry_analytic_destroy(geom::Ptr{Ptr{t8_geometry_c}})::Cvoid end -"""We can reuse the reference counter type from libsc.""" -const t8_refcount_t = sc_refcount_t - """ - t8_forest_ghost + t8_geometry_analytic_new(name, analytical, jacobian, load_tree_data, tree_negative_volume, tree_compatible, user_data) -This struct stores various information about a forest's ghost elements and ghost trees. +Create a new analytic geometry. The geometry is viable with all tree types and uses a user-provided analytic and jacobian function. The actual mappings are done by these functions. -| Field | Note | -| :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| rc | The reference counter. | -| num\\_ghosts\\_elements | The count of non-local ghost leaf elements | -| num\\_remote\\_elements | The count of local leaf elements that are ghost to another process. | -| ghost\\_type | Describes which neighbors are considered ghosts. | -| ghost\\_trees | ghost tree data: global\\_id. eclass. elements. In linear id order | -| global\\_tree\\_to\\_ghost\\_tree | Indexes into ghost\\_trees. Given a global tree id I give the index i such that the tree is in ghost\\_trees[i] | -| process\\_offsets | Given a process, return the first ghost tree and within it the first element of that process. | -| remote\\_ghosts | array of local trees that have ghost elements for another process. for each tree an array of [`t8_element_t`](@ref) * of the local ghost elements. Also an array of [`t8_locidx_t`](@ref) of the local indices of these elements within the tree. It is a hash table, hashed with the rank of a remote process. Sorted within each process by linear id. | -| remote\\_processes | The ranks of the processes for which local elements are ghost. Array of int's. | -| glo\\_tree\\_mempool | The global tree memory pool. | -| proc\\_offset\\_mempool | The process offset memory pool. | +# Arguments +* `name`:\\[in\\] The name to give this geometry. +* `analytical`:\\[in\\] The analytical function to use for this geometry. +* `jacobian`:\\[in\\] The jacobian of *analytical*. +* `load_tree_data`:\\[in\\] The function that is used to load a tree's data. +* `tree_negative_volume`:\\[in\\] The function that is used to compute if a trees volume is negative. +* `tree_compatible`:\\[in\\] The function that is used to check if a tree is compatible with the geometry. +* `user_data`:\\[in\\] Additional user data which the geometry can use. +# Returns +A pointer to an allocated geometry struct. +### Prototype +```c +t8_geometry_c * t8_geometry_analytic_new (const char *name, t8_geom_analytic_fn analytical, t8_geom_analytic_jacobian_fn jacobian, t8_geom_load_tree_data_fn load_tree_data, t8_geom_tree_negative_volume_fn tree_negative_volume, t8_geom_tree_compatible_fn tree_compatible, const void *user_data); +``` """ -struct t8_forest_ghost - rc::t8_refcount_t - num_ghosts_elements::t8_locidx_t - num_remote_elements::t8_locidx_t - ghost_type::t8_ghost_type_t - ghost_trees::Ptr{sc_array_t} - global_tree_to_ghost_tree::Ptr{sc_hash_t} - process_offsets::Ptr{sc_hash_t} - remote_ghosts::Ptr{sc_hash_array_t} - remote_processes::Ptr{sc_array_t} - glo_tree_mempool::Ptr{sc_mempool_t} - proc_offset_mempool::Ptr{sc_mempool_t} +function t8_geometry_analytic_new(name, analytical, jacobian, load_tree_data, tree_negative_volume, tree_compatible, user_data) + @ccall libt8.t8_geometry_analytic_new(name::Cstring, analytical::t8_geom_analytic_fn, jacobian::t8_geom_analytic_jacobian_fn, load_tree_data::t8_geom_load_tree_data_fn, tree_negative_volume::t8_geom_tree_negative_volume_fn, tree_compatible::t8_geom_tree_compatible_fn, user_data::Ptr{Cvoid})::Ptr{t8_geometry_c} end -const t8_forest_ghost_t = Ptr{t8_forest_ghost} - """ - t8_forest_ghost_init(pghost, ghost_type) + t8_geom_load_tree_data_vertices(cmesh, gtreeid, user_data) -Initialize a ghost type of a forest. +Load vertex data from given tree. # Arguments -* `pghost`:\\[out\\] Pointer to the forest's ghost. -* `ghost_type`:\\[in\\] The type of the ghost elements, -# See also -[`t8_ghost_type_t`](@ref). - +* `cmesh`:\\[in\\] The cmesh. +* `gtreeid`:\\[in\\] The global tree id (in the cmesh). +* `user_data`:\\[out\\] The load tree vertices. ### Prototype ```c -void t8_forest_ghost_init (t8_forest_ghost_t *pghost, t8_ghost_type_t ghost_type); +void t8_geom_load_tree_data_vertices (t8_cmesh_t cmesh, t8_gloidx_t gtreeid, const void **user_data); ``` """ -function t8_forest_ghost_init(pghost, ghost_type) - @ccall libt8.t8_forest_ghost_init(pghost::Ptr{t8_forest_ghost_t}, ghost_type::t8_ghost_type_t)::Cvoid +function t8_geom_load_tree_data_vertices(cmesh, gtreeid, user_data) + @ccall libt8.t8_geom_load_tree_data_vertices(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t, user_data::Ptr{Ptr{Cvoid}})::Cvoid end """ - t8_forest_ghost_num_trees(forest) + t8_geometry_destroy(geom) -Return the number of trees in a ghost. +Destroy a geometry object. # Arguments -* `forest`:\\[in\\] The forest. -# Returns -The number of trees in the forest's ghost (or 0 if ghost structure does not exist). +* `geom`:\\[in,out\\] A pointer to a geometry object. Set to NULL on output. ### Prototype ```c -t8_locidx_t t8_forest_ghost_num_trees (const t8_forest_t forest); +void t8_geometry_destroy (t8_geometry_c **geom); ``` """ -function t8_forest_ghost_num_trees(forest) - @ccall libt8.t8_forest_ghost_num_trees(forest::t8_forest_t)::t8_locidx_t +function t8_geometry_destroy(geom) + @ccall libt8.t8_geometry_destroy(geom::Ptr{Ptr{t8_geometry_c}})::Cvoid end +# no prototype is found for this function at t8_geometry_examples.h:45:1, please use with caution """ - t8_forest_ghost_get_tree_element_offset(forest, lghost_tree) - -Return the element offset of a ghost tree. - -!!! note + t8_geometry_quadrangulated_disk_new() - forest must be committed before calling this function. +Create a new quadrangulated\\_disk geometry. -# Arguments -* `forest`:\\[in\\] The forest with constructed ghost layer. -* `lghost_tree`:\\[in\\] A local ghost id of a ghost tree. # Returns -The element offset of this ghost tree within the set of local ghost elements. +A pointer to an allocated geometry struct. ### Prototype ```c -t8_locidx_t t8_forest_ghost_get_tree_element_offset (t8_forest_t forest, t8_locidx_t lghost_tree); +t8_geometry_c * t8_geometry_quadrangulated_disk_new (); ``` """ -function t8_forest_ghost_get_tree_element_offset(forest, lghost_tree) - @ccall libt8.t8_forest_ghost_get_tree_element_offset(forest::t8_forest_t, lghost_tree::t8_locidx_t)::t8_locidx_t +function t8_geometry_quadrangulated_disk_new() + @ccall libt8.t8_geometry_quadrangulated_disk_new()::Ptr{t8_geometry_c} end +# no prototype is found for this function at t8_geometry_examples.h:51:1, please use with caution """ - t8_forest_ghost_tree_num_leaf_elements(forest, lghost_tree) + t8_geometry_triangulated_spherical_surface_new() -Given an index in the ghost\\_tree array, return this tree's number of leaf elements +Create a new triangulated\\_spherical\\_surface geometry. -# Arguments -* `forest`:\\[in\\] The *forest*. Ghost layer must exist. -* `lghost_tree`:\\[in\\] The ghost tree id of a ghost tree. # Returns -The number of ghost leaf elements of the tree. *forest* must be committed before calling this function. +A pointer to an allocated geometry struct. ### Prototype ```c -t8_locidx_t t8_forest_ghost_tree_num_leaf_elements (t8_forest_t forest, t8_locidx_t lghost_tree); +t8_geometry_c * t8_geometry_triangulated_spherical_surface_new (); ``` """ -function t8_forest_ghost_tree_num_leaf_elements(forest, lghost_tree) - @ccall libt8.t8_forest_ghost_tree_num_leaf_elements(forest::t8_forest_t, lghost_tree::t8_locidx_t)::t8_locidx_t +function t8_geometry_triangulated_spherical_surface_new() + @ccall libt8.t8_geometry_triangulated_spherical_surface_new()::Ptr{t8_geometry_c} end +# no prototype is found for this function at t8_geometry_examples.h:57:1, please use with caution """ - t8_forest_ghost_get_tree_leaf_elements(forest, lghost_tree) + t8_geometry_tessellated_spherical_surface_new() -Get a pointer to the ghost leaf element array of a ghost tree. +Create a new tessellated\\_spherical\\_surface geometry. -# Arguments -* `forest`:\\[in\\] The forest. Ghost layer must exist. -* `lghost_tree`:\\[in\\] The ghost tree id of a ghost tree. 0 <= *lghost_tree* < num\\_ghost\\_trees # Returns -A pointer to the array of ghost leaf elements of the tree. *forest* must be committed before calling this function. +A pointer to an allocated geometry struct. ### Prototype ```c -t8_element_array_t * t8_forest_ghost_get_tree_leaf_elements (const t8_forest_t forest, const t8_locidx_t lghost_tree); +t8_geometry_c * t8_geometry_tessellated_spherical_surface_new (); ``` """ -function t8_forest_ghost_get_tree_leaf_elements(forest, lghost_tree) - @ccall libt8.t8_forest_ghost_get_tree_leaf_elements(forest::t8_forest_t, lghost_tree::t8_locidx_t)::Ptr{t8_element_array_t} +function t8_geometry_tessellated_spherical_surface_new() + @ccall libt8.t8_geometry_tessellated_spherical_surface_new()::Ptr{t8_geometry_c} end +# no prototype is found for this function at t8_geometry_examples.h:63:1, please use with caution """ - t8_forest_ghost_get_ghost_treeid(forest, gtreeid) + t8_geometry_cubed_spherical_shell_new() -Given a global tree compute the ghost local tree id of it. +Create a new cubed\\_spherical\\_shell geometry. -# Arguments -* `forest`:\\[in\\] The forest. Ghost layer must exist. -* `gtreeid`:\\[in\\] A global tree in *forest*. # Returns -If *gtreeid* is also a ghost tree, the index in the ghost->ghost\\_trees array of the tree. Otherwise a negative number. *forest* must be committed before calling this function. -# See also -https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. - +A pointer to an allocated geometry struct. ### Prototype ```c -t8_locidx_t t8_forest_ghost_get_ghost_treeid (t8_forest_t forest, t8_gloidx_t gtreeid); +t8_geometry_c * t8_geometry_cubed_spherical_shell_new (); ``` """ -function t8_forest_ghost_get_ghost_treeid(forest, gtreeid) - @ccall libt8.t8_forest_ghost_get_ghost_treeid(forest::t8_forest_t, gtreeid::t8_gloidx_t)::t8_locidx_t +function t8_geometry_cubed_spherical_shell_new() + @ccall libt8.t8_geometry_cubed_spherical_shell_new()::Ptr{t8_geometry_c} end +# no prototype is found for this function at t8_geometry_examples.h:69:1, please use with caution """ - t8_forest_ghost_get_tree_class(forest, lghost_tree) + t8_geometry_prismed_spherical_shell_new() -Given an index in the ghost\\_tree array, return this tree's element class. +Create a new spherical\\_shell geometry. -# Arguments -* `forest`:\\[in\\] A committed forest. -* `lghost_tree`:\\[in\\] The tree's local index in the ghost\\_tree array. # Returns -The element class of the given tree. +A pointer to an allocated geometry struct. ### Prototype ```c -t8_eclass_t t8_forest_ghost_get_tree_class (const t8_forest_t forest, const t8_locidx_t lghost_tree); +t8_geometry_c * t8_geometry_prismed_spherical_shell_new (); ``` """ -function t8_forest_ghost_get_tree_class(forest, lghost_tree) - @ccall libt8.t8_forest_ghost_get_tree_class(forest::t8_forest_t, lghost_tree::t8_locidx_t)::t8_eclass_t +function t8_geometry_prismed_spherical_shell_new() + @ccall libt8.t8_geometry_prismed_spherical_shell_new()::Ptr{t8_geometry_c} end +# no prototype is found for this function at t8_geometry_examples.h:75:1, please use with caution """ - t8_forest_ghost_get_global_treeid(forest, lghost_tree) + t8_geometry_cubed_sphere_new() -Given a local ghost tree compute the global tree id of it. +Create a new cubed sphere geometry. -# Arguments -* `forest`:\\[in\\] The forest. Ghost layer must exist. -* `lghost_tree`:\\[in\\] The ghost tree id of a ghost tree. (0 <= *lghost_tree* < num\\_ghost\\_trees) # Returns -The global id of the local ghost tree *lghost_tree*. *forest* must be committed before calling this function. -# See also -https://github.com/DLR-AMR/t8code/wiki/Tree-indexing for more details about tree indexing. - +A pointer to an allocated geometry struct. ### Prototype ```c -t8_gloidx_t t8_forest_ghost_get_global_treeid (const t8_forest_t forest, const t8_locidx_t lghost_tree); +t8_geometry_c * t8_geometry_cubed_sphere_new (); ``` """ -function t8_forest_ghost_get_global_treeid(forest, lghost_tree) - @ccall libt8.t8_forest_ghost_get_global_treeid(forest::t8_forest_t, lghost_tree::t8_locidx_t)::t8_gloidx_t +function t8_geometry_cubed_sphere_new() + @ccall libt8.t8_geometry_cubed_sphere_new()::Ptr{t8_geometry_c} end """ - t8_forest_ghost_get_leaf_element(forest, lghost_tree, lelement) + t8_cmesh_set_tree_vertices(cmesh, gtree_id, vertices, num_vertices) -Given an index into the ghost\\_trees array and for that tree an element index, return the corresponding element. +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. # Arguments -* `forest`:\\[in\\] The *forest*. Ghost layer must exist. -* `lghost_tree`:\\[in\\] The ghost tree id of a ghost tree. -* `lelement`:\\[in\\] The local id of the ghost leaf element considered. -# Returns -A pointer to the ghost leaf element. *forest* must be committed before calling this function. +* `cmesh`:\\[in,out\\] The cmesh to be updated. +* `gtree_id`:\\[in\\] The global number of the tree. +* `vertices`:\\[in\\] An array of 3 doubles per tree vertex. +* `num_vertices`:\\[in\\] The number of verticess in *vertices*. Must match the number of corners of the tree. ### Prototype ```c -t8_element_t * t8_forest_ghost_get_leaf_element (t8_forest_t forest, t8_locidx_t lghost_tree, t8_locidx_t lelement); +void t8_cmesh_set_tree_vertices (t8_cmesh_t cmesh, const t8_gloidx_t gtree_id, const double *vertices, const int num_vertices); ``` """ -function t8_forest_ghost_get_leaf_element(forest, lghost_tree, lelement) - @ccall libt8.t8_forest_ghost_get_leaf_element(forest::t8_forest_t, lghost_tree::t8_locidx_t, lelement::t8_locidx_t)::Ptr{t8_element_t} +function t8_cmesh_set_tree_vertices(cmesh, gtree_id, vertices, num_vertices) + @ccall libt8.t8_cmesh_set_tree_vertices(cmesh::t8_cmesh_t, gtree_id::t8_gloidx_t, vertices::Ptr{Cdouble}, num_vertices::Cint)::Cvoid end +# no prototype is found for this function at t8_geometry_lagrange.h:47:1, please use with caution """ - t8_forest_element_is_ghost(forest, element, lghost_tree) - -Query whether a given element is a ghost of a certrain tree in a forest. - -!!! note + t8_geometry_lagrange_new() - *forest* must be committed before calling this function. +Create a new Lagrange geometry of a given dimension. The geometry is compatible with all tree types and uses as many vertices as the number of Lagrange basis functions used for the mapping. The vertices are saved via the t8_cmesh_set_tree_vertices function. Sets the name to "t8\\_geom\\_lagrange" -# Arguments -* `forest`:\\[in\\] The forest. -* `element`:\\[in\\] An element of a ghost tree in *forest*. -* `lghost_tree`:\\[in\\] A local ghost tree id of *forest*. (0 <= *lghost_tree* < num\\_ghost\\_trees) # Returns -True (non-zero) if and only if *element* is a ghost in *lghost_tree* of *forest*. +A pointer to an allocated t8\\_geometry\\_lagrange struct, as if the t8_geometry_lagrange () constructor was called. ### Prototype ```c -int t8_forest_element_is_ghost (const t8_forest_t forest, const t8_element_t *element, const t8_locidx_t lghost_tree); +t8_geometry_c * t8_geometry_lagrange_new (); ``` """ -function t8_forest_element_is_ghost(forest, element, lghost_tree) - @ccall libt8.t8_forest_element_is_ghost(forest::t8_forest_t, element::Ptr{t8_element_t}, lghost_tree::t8_locidx_t)::Cint +function t8_geometry_lagrange_new() + @ccall libt8.t8_geometry_lagrange_new()::Ptr{t8_geometry_c} end """ - t8_forest_ghost_get_remotes(forest, num_remotes) + t8_geometry_lagrange_destroy(geom) -Return the array of remote ranks. +Destroy a Lagrange geometry that was created with t8_geometry_lagrange_new. # Arguments -* `forest`:\\[in\\] A forest with constructed ghost layer. -* `num_remotes`:\\[in,out\\] On output the number of remote ranks is stored here. -# Returns -The array of remote ranks in ascending order. +* `geom`:\\[in,out\\] A Lagrange geometry. Set to NULL on output. ### Prototype ```c -int * t8_forest_ghost_get_remotes (t8_forest_t forest, int *num_remotes); +void t8_geometry_lagrange_destroy (t8_geometry_c **geom); ``` """ -function t8_forest_ghost_get_remotes(forest, num_remotes) - @ccall libt8.t8_forest_ghost_get_remotes(forest::t8_forest_t, num_remotes::Ptr{Cint})::Ptr{Cint} +function t8_geometry_lagrange_destroy(geom) + @ccall libt8.t8_geometry_lagrange_destroy(geom::Ptr{Ptr{t8_geometry_c}})::Cvoid end +# no prototype is found for this function at t8_geometry_linear.h:45:1, please use with caution """ - t8_forest_ghost_remote_first_tree(forest, remote) + t8_geometry_linear_new() -Return the first local ghost tree of a remote rank. +Create a new linear geometry. The geometry is only all tree types and as many vertices as the tree type has. The vertices are saved via the t8_cmesh_set_tree_vertices function. Sets the dimension and the name to "t8\\_geom\\_linear" -# Arguments -* `forest`:\\[in\\] A forest with constructed ghost layer. -* `remote`:\\[in\\] A remote rank of the ghost layer in *forest*. # Returns -The ghost tree id of the first ghost tree that stores ghost elements of *remote*. +A pointer to an allocated t8\\_geometry\\_linear struct, as if the t8_geometry_linear () constructor was called. ### Prototype ```c -t8_locidx_t t8_forest_ghost_remote_first_tree (t8_forest_t forest, int remote); +t8_geometry_c * t8_geometry_linear_new (); ``` """ -function t8_forest_ghost_remote_first_tree(forest, remote) - @ccall libt8.t8_forest_ghost_remote_first_tree(forest::t8_forest_t, remote::Cint)::t8_locidx_t +function t8_geometry_linear_new() + @ccall libt8.t8_geometry_linear_new()::Ptr{t8_geometry_c} end """ - t8_forest_ghost_remote_first_elem(forest, remote) + t8_geometry_linear_destroy(geom) -Return the local index of the first ghost element that belongs to a given remote rank. +Destroy a linear geometry that was created with t8_geometry_linear_new. # Arguments -* `forest`:\\[in\\] A forest with constructed ghost layer. -* `remote`:\\[in\\] A remote rank of the ghost layer in *forest*. -# Returns -The index i in the ghost elements of the first element of rank *remote* +* `geom`:\\[in,out\\] A linear geometry. Set to NULL on output. ### Prototype ```c -t8_locidx_t t8_forest_ghost_remote_first_elem (t8_forest_t forest, int remote); +void t8_geometry_linear_destroy (t8_geometry_c **geom); ``` """ -function t8_forest_ghost_remote_first_elem(forest, remote) - @ccall libt8.t8_forest_ghost_remote_first_elem(forest::t8_forest_t, remote::Cint)::t8_locidx_t +function t8_geometry_linear_destroy(geom) + @ccall libt8.t8_geometry_linear_destroy(geom::Ptr{Ptr{t8_geometry_c}})::Cvoid end +# no prototype is found for this function at t8_geometry_linear_axis_aligned.h:47:1, please use with caution """ - t8_forest_ghost_ref(ghost) + t8_geometry_linear_axis_aligned_new() -Increase the reference count of a ghost structure. +Create a new linear, axis-aligned geometry of a given dimension. The geometry is only viable for line/quad/hex elements and uses two vertices (min and max coords) per tree. The vertices are saved via the t8_cmesh_set_tree_vertices function. -# Arguments -* `ghost`:\\[in,out\\] On input, this ghost structure must exist with positive reference count. +# Returns +A pointer to an allocated t8\\_geometry\\_linear\\_axis\\_aligned struct, as if the t8\\_geometry\\_linear\\_axis\\_aligned () constructor was called. ### Prototype ```c -void t8_forest_ghost_ref (t8_forest_ghost_t ghost); +t8_geometry_c * t8_geometry_linear_axis_aligned_new (); ``` """ -function t8_forest_ghost_ref(ghost) - @ccall libt8.t8_forest_ghost_ref(ghost::t8_forest_ghost_t)::Cvoid +function t8_geometry_linear_axis_aligned_new() + @ccall libt8.t8_geometry_linear_axis_aligned_new()::Ptr{t8_geometry_c} end """ - t8_forest_ghost_unref(pghost) + t8_geometry_linear_axis_aligned_destroy(geom) -Decrease the reference count of a ghost structure. If the counter reaches zero, the ghost structure is destroyed. See also t8_forest_ghost_destroy, which is to be preferred when it is known that the last reference to a cmesh is deleted. +Destroy a linear, axis-aligned geometry that was created with t8_geometry_linear_axis_aligned_new. # Arguments -* `pghost`:\\[in,out\\] On input, the ghost structure pointed to must exist with positive reference count. If the reference count reaches zero, the ghost structure is destroyed and this pointer is set to NULL. Otherwise, the pointer is not changed. +* `geom`:\\[in,out\\] A linear, axis-aligned geometry. Set to NULL on output. ### Prototype ```c -void t8_forest_ghost_unref (t8_forest_ghost_t *pghost); +void t8_geometry_linear_axis_aligned_destroy (t8_geometry_c **geom); ``` """ -function t8_forest_ghost_unref(pghost) - @ccall libt8.t8_forest_ghost_unref(pghost::Ptr{t8_forest_ghost_t})::Cvoid +function t8_geometry_linear_axis_aligned_destroy(geom) + @ccall libt8.t8_geometry_linear_axis_aligned_destroy(geom::Ptr{Ptr{t8_geometry_c}})::Cvoid end +# no prototype is found for this function at t8_geometry_zero.h:45:1, please use with caution """ - t8_forest_ghost_destroy(pghost) + t8_geometry_zero_new() -Verify that a ghost structure has only one reference left and destroy it. This function is preferred over t8_forest_ghost_unref when it is known that the last reference is to be deleted. +Create a new zero geometry. The geometry is only all tree types and as many vertices as the tree type has. The vertices are saved via the t8_cmesh_set_tree_vertices function. Sets the dimension and the name to "t8\\_geom\\_zero\\_" -# Arguments -* `pghost`:\\[in,out\\] This ghost structure must have a reference count of one. It can be in any state (committed or not). Then it effectively calls t8_forest_ghost_unref. +# Returns +A pointer to an allocated t8\\_geometry\\_zero struct, as if the t8_geometry_zero () constructor was called. ### Prototype ```c -void t8_forest_ghost_destroy (t8_forest_ghost_t *pghost); +t8_geometry_c * t8_geometry_zero_new (); ``` """ -function t8_forest_ghost_destroy(pghost) - @ccall libt8.t8_forest_ghost_destroy(pghost::Ptr{t8_forest_ghost_t})::Cvoid +function t8_geometry_zero_new() + @ccall libt8.t8_geometry_zero_new()::Ptr{t8_geometry_c} end """ - t8_forest_ghost_create(forest) + t8_geometry_zero_destroy(geom) -Create one layer of ghost elements for a forest. +Destroy a zero geometry that was created with t8_geometry_zero_new. # Arguments -* `forest`:\\[in,out\\] The forest. *forest* must be committed before calling this function. -# See also -[`t8_forest_set_ghost`](@ref) - +* `geom`:\\[in,out\\] A zero geometry. Set to NULL on output. ### Prototype ```c -void t8_forest_ghost_create (t8_forest_t forest); +void t8_geometry_zero_destroy (t8_geometry_c **geom); ``` """ -function t8_forest_ghost_create(forest) - @ccall libt8.t8_forest_ghost_create(forest::t8_forest_t)::Cvoid +function t8_geometry_zero_destroy(geom) + @ccall libt8.t8_geometry_zero_destroy(geom::Ptr{Ptr{t8_geometry_c}})::Cvoid end +# no prototype is found for this function at t8_version.h:67:1, please use with caution """ - t8_forest_ghost_create_balanced_only(forest) - -Create one layer of ghost elements for a forest. This version only works with balanced forests and is the original algorithm from p4est: Scalable Algorithms For Parallel Adaptive Mesh Refinement On Forests of Octrees - -!!! note + t8_get_package_string() - The user should prefer t8_forest_ghost_create even for balanced forests. +Return the package string of t8code. This string has the format "t8 version\\_number". -# Arguments -* `forest`:\\[in,out\\] The balanced forest/ *forest* must be committed before calling this function. +# Returns +The version string of t8code. ### Prototype ```c -void t8_forest_ghost_create_balanced_only (t8_forest_t forest); +const char* t8_get_package_string (); ``` """ -function t8_forest_ghost_create_balanced_only(forest) - @ccall libt8.t8_forest_ghost_create_balanced_only(forest::t8_forest_t)::Cvoid +function t8_get_package_string() + @ccall libt8.t8_get_package_string()::Cstring end +# no prototype is found for this function at t8_version.h:73:1, please use with caution """ - t8_forest_ghost_create_topdown(forest) + t8_get_version_number() -Experimental version of t8_forest_ghost_create using the ghost\\_v3 algorithm +Return the version number of t8code as a string. +# Returns +The version number of t8code as a string. ### Prototype ```c -void t8_forest_ghost_create_topdown (t8_forest_t forest); +const char* t8_get_version_number (); ``` """ -function t8_forest_ghost_create_topdown(forest) - @ccall libt8.t8_forest_ghost_create_topdown(forest::t8_forest_t)::Cvoid +function t8_get_version_number() + @ccall libt8.t8_get_version_number()::Cstring end +# no prototype is found for this function at t8_version.h:79:1, please use with caution """ - t8_forest_save(forest) + t8_get_version_point_string() +Return the version point string. + +# Returns +The version point point string. ### Prototype ```c -void t8_forest_save (t8_forest_t forest); +const char* t8_get_version_point_string (); ``` """ -function t8_forest_save(forest) - @ccall libt8.t8_forest_save(forest::t8_forest_t)::Cvoid +function t8_get_version_point_string() + @ccall libt8.t8_get_version_point_string()::Cstring end +# no prototype is found for this function at t8_version.h:85:1, please use with caution """ - t8_vtk_data_type_t + t8_get_version_major() -TODO: Add support for integer data type. +Return the major version number of t8code. -| Enumerator | Note | -| :---------------- | :---------------------------- | -| T8\\_VTK\\_SCALAR | One double value per element | -| T8\\_VTK\\_VECTOR | 3 double values per element | +# Returns +The major version number of t8code. +### Prototype +```c +int t8_get_version_major (); +``` """ -@cenum t8_vtk_data_type_t::UInt32 begin - T8_VTK_SCALAR = 0 - T8_VTK_VECTOR = 1 +function t8_get_version_major() + @ccall libt8.t8_get_version_major()::Cint end +# no prototype is found for this function at t8_version.h:91:1, please use with caution """ - t8_vtk_data_field_t + t8_get_version_minor() -A data field for VTK output. This struct is used to store data that is written to the VTK files. It contains the type of the data, a description, and the actual data array. +Return the minor version number of t8code. -| Field | Note | -| :---------- | :----------------------------------------- | -| type | Describes of which type the data array is | -| description | String that describes the data. | +# Returns +The minor version number of t8code. +### Prototype +```c +int t8_get_version_minor (); +``` """ -struct t8_vtk_data_field_t - type::t8_vtk_data_type_t - description::NTuple{8192, Cchar} - data::Ptr{Cdouble} +function t8_get_version_minor() + @ccall libt8.t8_get_version_minor()::Cint end +# no prototype is found for this function at t8_version.h:97:1, please use with caution """ - t8_forest_write_vtk_ext(forest, fileprefix, write_treeid, write_mpirank, write_level, write_element_id, write_ghosts, write_curved, do_not_use_API, num_data, data) + t8_get_version_patch() + +Return the patch version number of t8code. +# Returns +The patch version number of t8code. ### Prototype ```c -int t8_forest_write_vtk_ext (t8_forest_t forest, const char *fileprefix, const int write_treeid, const int write_mpirank, const int write_level, const int write_element_id, const int write_ghosts, const int write_curved, int do_not_use_API, const int num_data, t8_vtk_data_field_t *data); +int t8_get_version_patch (); ``` """ -function t8_forest_write_vtk_ext(forest, fileprefix, write_treeid, write_mpirank, write_level, write_element_id, write_ghosts, write_curved, do_not_use_API, num_data, data) - @ccall libt8.t8_forest_write_vtk_ext(forest::t8_forest_t, fileprefix::Cstring, write_treeid::Cint, write_mpirank::Cint, write_level::Cint, write_element_id::Cint, write_ghosts::Cint, write_curved::Cint, do_not_use_API::Cint, num_data::Cint, data::Ptr{t8_vtk_data_field_t})::Cint +function t8_get_version_patch() + @ccall libt8.t8_get_version_patch()::Cint end """ - t8_forest_write_vtk(forest, fileprefix) + getdelim(lineptr, n, delimiter, stream) ### Prototype ```c -int t8_forest_write_vtk (t8_forest_t forest, const char *fileprefix); +static ssize_t getdelim (char **lineptr, size_t *n, int delimiter, FILE *stream); ``` """ -function t8_forest_write_vtk(forest, fileprefix) - @ccall libt8.t8_forest_write_vtk(forest::t8_forest_t, fileprefix::Cstring)::Cint +function getdelim(lineptr, n, delimiter, stream) + @ccall libt8.getdelim(lineptr::Ptr{Cstring}, n::Ptr{Cint}, delimiter::Cint, stream::Ptr{Cint})::Cint end -# typedef int ( * t8_forest_iterate_face_fn ) ( const t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int face , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index , void * user_data ) """ -Callback function used in + getline(lineptr, n, stream) -# Arguments -* `forest`:\\[in\\] The forest. -* `ltreeid`:\\[in\\] Local index of the tree containing the *element*. -* `element`:\\[in\\] The considered element. -* `face`:\\[in\\] The integer index of the considered face of *element*. -* `is_leaf`:\\[in\\] True if and only if the currently considered element is a leaf element. -* `leaf_elements`:\\[in\\] The array of leaf elements that are descendants of *element*. Sorted by linear index. -* `tree_leaf_index`:\\[in\\] Tree-local index of the first leaf. -* `user_data`:\\[in\\] Some user-defined data, as void pointer. -# Returns -Nonzero if the element may touch the face and the top-down search shall be continued, zero otherwise. -# See also -[`t8_forest_iterate_faces`](@ref). +### Prototype +```c +static ssize_t getline (char **lineptr, size_t *n, FILE *stream); +``` """ -const t8_forest_iterate_face_fn = Ptr{Cvoid} +function getline(lineptr, n, stream) + @ccall libt8.getline(lineptr::Ptr{Cstring}, n::Ptr{Cint}, stream::Ptr{Cint})::Cint +end -# typedef int ( * t8_forest_search_fn ) ( t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index ) """ -A call-back function used by t8_forest_search describing a search-criterion. Is called on an element and the search criterion should be checked on that element. Return true if the search criterion is met, false otherwise. + strsep(stringp, delim) -# Arguments -* `forest`:\\[in\\] the forest -* `ltreeid`:\\[in\\] the local tree id of the current tree -* `element`:\\[in\\] the element for which the search criterion is checked. -* `is_leaf`:\\[in\\] true if and only if *element* is a leaf element -* `leaf_elements`:\\[in\\] the leaf elements in *forest* that are descendants of *element* (or the element itself if *is_leaf* is true) -* `tree_leaf_index`:\\[in\\] the local index of the first leaf in *leaf_elements* -# Returns -non-zero if the search criterion is met, zero otherwise. -""" -const t8_forest_search_fn = Ptr{Cvoid} +Extract token from string up to a given delimiter. -# typedef void ( * t8_forest_query_fn ) ( t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index , sc_array_t * queries , sc_array_t * query_indices , int * query_matches , const size_t num_active_queries ) -""" -A call-back function used by t8_forest_search for queries. Is called on an element and all queries are checked on that element. All positive queries are passed further down to the children of the element up to leaf elements of the tree. The results of the check are stored in *query_matches*. +For a full description see https://linux.die.net/man/3/[`strsep`](@ref) -# Arguments -* `forest`:\\[in\\] the forest -* `ltreeid`:\\[in\\] the local tree id of the current tree -* `element`:\\[in\\] the element for which the queries are executed -* `is_leaf`:\\[in\\] true if and only if *element* is a leaf element -* `leaf_elements`:\\[in\\] the leaf elements in *forest* that are descendants of *element* (or the element itself if *is_leaf* is true) -* `tree_leaf_index`:\\[in\\] the local index of the first leaf in *leaf_elements* -* `queries`:\\[in\\] An array of queries that are checked by the function -* `query_indices`:\\[in\\] An array of size\\_t entries, where each entry is an index of a query in *queries*. -* `query_matches`:\\[in,out\\] An array of length *num_active_queries*. If the element is not a leave must be set to true or false at the i-th index for each query, specifying whether the element 'matches' the query of the i-th query index or not. When the element is a leaf we can return before all entries are set. -* `num_active_queries`:\\[in\\] The number of currently active queries (equals the number of entries of *query_matches* and entries of *query_indices*). +### Prototype +```c +static char * strsep (char **stringp, const char *delim); +``` """ -const t8_forest_query_fn = Ptr{Cvoid} +function strsep(stringp, delim) + @ccall libt8.strsep(stringp::Ptr{Cstring}, delim::Cstring)::Cstring +end -# typedef int ( * t8_forest_partition_search_fn ) ( const t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int pfirst , const int plast ) """ -A call-back function used by t8_forest_search_partition describing a search-criterion. Is called on an element and the search criterion should be checked on that element. Return true if the search criterion is met, false otherwise. + t8_scheme_new_default() -# Arguments -* `forest`:\\[in\\] the forest -* `ltreeid`:\\[in\\] the local tree id of the current tree in the cmesh. Since the cmesh has to be replicated, it coincides with the global tree id. -* `element`:\\[in\\] the element for which the search criterion is checked -* `pfirst`:\\[in\\] the first processor that owns part of *element*. Guaranteed to be non-empty. -* `plast`:\\[in\\] the last processor that owns part of *element*. Guaranteed to be non-empty. -# Returns -non-zero if the search criterion is met, zero otherwise. +### Prototype +```c +const t8_scheme_c * t8_scheme_new_default (void); +``` """ -const t8_forest_partition_search_fn = Ptr{Cvoid} +function t8_scheme_new_default() + @ccall libt8.t8_scheme_new_default()::Ptr{t8_scheme_c} +end -# typedef void ( * t8_forest_partition_query_fn ) ( const t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int pfirst , const int plast , void * queries , sc_array_t * query_indices , int * query_matches , const size_t num_active_queries ) """ -A call-back function used by t8_forest_search_partition for queries. Is called on an element and all queries are checked on that element. All positive queries are passed further down to the children of the element. The results of the check are stored in *query_matches*. + t8_eclass_scheme_is_default(scheme, eclass) -# Arguments -* `forest`:\\[in\\] the forest -* `ltreeid`:\\[in\\] the local tree id of the current tree in the cmesh. Since the cmesh has to be replicated, it coincides with the global tree id. -* `element`:\\[in\\] the element for which the query is executed -* `pfirst`:\\[in\\] the first processor that owns part of *element*. Guaranteed to be non-empty. -* `plast`:\\[in\\] the last processor that owns part of *element*. Guaranteed to be non-empty. if this is equal to *pfirst*, then the recursion will stop for *element*'s branch after this function returns. -* `queries`:\\[in\\] an array of queries that are checked by the function -* `query_indices`:\\[in\\] an array of size\\_t entries, where each entry is an index of a query in *queries*. -* `query_matches`:\\[in,out\\] an array of length *num_active_queries*. If the element is not a leaf must be set to true or false at the i-th index for each query, specifying whether the element 'matches' the query of the i-th query index or not. When the element is a leaf we can return before all entries are set. -* `num_active_queries`:\\[in\\] The number of currently active queries (equals the number of entries of *query_matches* and entries of *query_indices*). +### Prototype +```c +int t8_eclass_scheme_is_default (const t8_scheme_c *scheme, const t8_eclass_t eclass); +``` """ -const t8_forest_partition_query_fn = Ptr{Cvoid} +function t8_eclass_scheme_is_default(scheme, eclass) + @ccall libt8.t8_eclass_scheme_is_default(scheme::Ptr{t8_scheme_c}, eclass::t8_eclass_t)::Cint +end + +"""Type of an integer coordinate for a node of a hex element.""" +const t8_dhex_coord_t = Int32 """ - t8_forest_split_array(element, leaf_elements, offsets) + t8_dhex -Split an array of elements according to the children of a given element E. In other words for each child C of E, find the index i, j, such that all descendants of C are elements[i], ..., elements[j-1]. +The data container describing a refined element in a refined tree for the hex element class. -# Arguments -* `element`:\\[in\\] An element. -* `leaf_elements`:\\[in\\] An array of leaf elements of *element*. Thus, all elements must be descendants. Sorted by linear index. -* `offsets`:\\[in,out\\] On input an allocated array of *num_children_of_E* + 1 entries. On output entry i indicates the position in *leaf_elements* where the descandents of the i-th child of E start. -### Prototype -```c -void t8_forest_split_array (const t8_element_t *element, const t8_element_array_t *leaf_elements, size_t *offsets); -``` +| Field | Note | +| :---- | :-------------------------------------------------------------------- | +| level | The refinement level of the element relative to the root at level 0. | +| x | The x integer coordinate of the anchor node. | +| y | The y integer coordinate of the anchor node. | +| z | The z integer coordinate of the anchor node. | """ -function t8_forest_split_array(element, leaf_elements, offsets) - @ccall libt8.t8_forest_split_array(element::Ptr{t8_element_t}, leaf_elements::Ptr{t8_element_array_t}, offsets::Ptr{Csize_t})::Cvoid +struct t8_dhex + level::Int8 + x::t8_dhex_coord_t + y::t8_dhex_coord_t + z::t8_dhex_coord_t end +"""The data container describing a refined element in a refined tree for the hex element class.""" +const t8_dhex_t = t8_dhex + """ - t8_forest_iterate_faces(forest, ltreeid, element, face, leaf_elements, tree_lindex_of_first_leaf, callback, user_data) + t8_dhex_compute_reference_coords(elem, ref_coords, num_coords, out_coords) -Iterate over all leaves of an element that touch a given face of the element. Callback is called in each recursive step with element as input. leaf\\_index is only not negative if element is a leaf, in which case it indicates the index of the leaf in the leaves of the tree. If it is negative, it is - (index + 1) Top-down iteration and callback is called on each intermediate level. If it returns false, the current element is not traversed further +Convert points in the reference space of a hex element to points in the reference space of the tree (level 0) embedded in -!!! note +```c++ + [0,1]^3 +``` - *tree_lindex_of_first_leaf* is not an index in *leaf_elements*. *leaf_elements* may only be a part of the tree's leaves. +. -# Arguments -* `forest`:\\[in\\] A committed forest. -* `ltreeid`:\\[in\\] Local index of the tree containing the *element*. -* `element`:\\[in\\] The considered element. -* `face`:\\[in\\] The integer index of the considered face of *element*. -* `leaf_elements`:\\[in\\] The array of leaf elements that are descendants of *element*. Sorted by linear index. -* `tree_lindex_of_first_leaf`:\\[in\\] Index of the first leaf of *element* in the tree's leaves. The corresponding leaf does not necessarily lie on the face of *element*. -* `callback`:\\[in\\] The callback function. -* `user_data`:\\[in\\] The user data passed to the *callback* function. -### Prototype -```c -void t8_forest_iterate_faces (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *element, const int face, const t8_element_array_t *const leaf_elements, const t8_locidx_t tree_lindex_of_first_leaf, const t8_forest_iterate_face_fn callback, void *user_data); +```c++ + [0,1]^3 ``` -""" -function t8_forest_iterate_faces(forest, ltreeid, element, face, leaf_elements, tree_lindex_of_first_leaf, callback, user_data) - @ccall libt8.t8_forest_iterate_faces(forest::t8_forest_t, ltreeid::t8_locidx_t, element::Ptr{t8_element_t}, face::Cint, leaf_elements::Ptr{t8_element_array_t}, tree_lindex_of_first_leaf::t8_locidx_t, callback::t8_forest_iterate_face_fn, user_data::Ptr{Cvoid})::Cvoid -end -""" - t8_forest_search(forest, search_fn, query_fn, queries) - -Perform a top-down search of the forest, executing a callback on each intermediate element. The search will enter each tree at least once. If the callback returns false for an element, its descendants are not further searched. To pass user data to the search\\_fn function use t8_forest_set_user_data. +) # Arguments -* `forest`:\\[in\\] The forest. -* `search_fn`:\\[in\\] The callback function describing the search criterion. -* `query_fn`:\\[in\\] The query function. -* `queries`:\\[in\\] The array of queries. +* `elem`:\\[in\\] Input hex. +* `ref_coords`:\\[in\\] The reference coordinates in the hex (*num_coords* times +* `num_coords`:\\[in\\] Number of coordinates to evaluate +* `out_coords`:\\[out\\] An array of *num_coords* x 3 x double that will be filled with the reference coordinates of the points on the hex. ### Prototype ```c -void t8_forest_search (t8_forest_t forest, t8_forest_search_fn search_fn, t8_forest_query_fn query_fn, sc_array_t *queries); +void t8_dhex_compute_reference_coords (const t8_dhex_t *elem, const double *ref_coords, const size_t num_coords, double *out_coords); ``` """ -function t8_forest_search(forest, search_fn, query_fn, queries) - @ccall libt8.t8_forest_search(forest::t8_forest_t, search_fn::t8_forest_search_fn, query_fn::t8_forest_query_fn, queries::Ptr{sc_array_t})::Cvoid +function t8_dhex_compute_reference_coords(elem, ref_coords, num_coords, out_coords) + @ccall libt8.t8_dhex_compute_reference_coords(elem::Ptr{t8_dhex_t}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid end -""" - t8_forest_iterate_replace(forest_new, forest_old, replace_fn) - -Given two forest where the elements in one forest are either direct children or parents of the elements in the other forest compare the two forests and for each refined element or coarsened family in the old one, call a callback function providing the local indices of the old and new elements. +"""Type of an integer coordinate for a node of a line element.""" +const t8_dline_coord_t = Int32 -!!! note +""" + t8_dline - To pass a user pointer to *replace_fn* use t8_forest_set_user_data and t8_forest_get_user_data. +The data container describing a refined element in a refined tree for the line element class. -# Arguments -* `forest_new`:\\[in\\] A forest, each element is a parent or child of an element in *forest_old*. -* `forest_old`:\\[in\\] The initial forest. -* `replace_fn`:\\[in\\] A replace callback function. -### Prototype -```c -void t8_forest_iterate_replace (t8_forest_t forest_new, t8_forest_t forest_old, t8_forest_replace_t replace_fn); -``` +| Field | Note | +| :---- | :-------------------------------------------------------------------- | +| x | The integer coordinate of the anchor node. | +| level | The refinement level of the element relative to the root at level 0. | """ -function t8_forest_iterate_replace(forest_new, forest_old, replace_fn) - @ccall libt8.t8_forest_iterate_replace(forest_new::t8_forest_t, forest_old::t8_forest_t, replace_fn::t8_forest_replace_t)::Cvoid +struct t8_dline + x::t8_dline_coord_t + level::Int8 end +"""The data container describing a refined element in a refined tree for the line element class.""" +const t8_dline_t = t8_dline + """ - t8_forest_search_partition(forest, search_fn, query_fn, queries) + t8_dvertex -Perform a top-down search of the global partition, executing a callback on each intermediate element. The search will enter each tree at least once. The recursion will only go down branches that are split between multiple processors. This is not a collective function. It does not communicate. The function expects the coarse mesh to be replicated. If the callback returns false for an element, its descendants are not further searched. To pass user data to **search_fn** function use t8_forest_set_user_data +The data container describing a refined element in a refined tree for the vertex element class. -# Arguments -* `forest`:\\[in\\] the forest to be searched -* `search_fn`:\\[in\\] a search callback function called on elements -* `query_fn`:\\[in\\] a query callback function called for all active queries of an element -* `queries`:\\[in,out\\] an array of queries that are checked by the function -### Prototype -```c -void t8_forest_search_partition (const t8_forest_t forest, t8_forest_partition_search_fn search_fn, t8_forest_partition_query_fn query_fn, sc_array_t *queries); -``` +| Field | Note | +| :---- | :-------------------------------------------------------------------- | +| level | The refinement level of the element relative to the root at level 0. | """ -function t8_forest_search_partition(forest, search_fn, query_fn, queries) - @ccall libt8.t8_forest_search_partition(forest::t8_forest_t, search_fn::t8_forest_partition_search_fn, query_fn::t8_forest_partition_query_fn, queries::Ptr{sc_array_t})::Cvoid +struct t8_dvertex + level::UInt8 end +"""The data container describing a refined element in a refined tree for the vertex element class.""" +const t8_dvertex_t = t8_dvertex + """ - t8_forest_partition(forest) + t8_dline_get_level(line) -Populate a forest with the partitioned elements of forest->set\\_from. +Compute the level of a line. # Arguments -* `forest`:\\[in,out\\] The forest. +* `line`:\\[in\\] Line whose level is computed. +# Returns +The level of *line*. ### Prototype ```c -void t8_forest_partition (t8_forest_t forest); +int t8_dline_get_level (const t8_dline_t *line); ``` """ -function t8_forest_partition(forest) - @ccall libt8.t8_forest_partition(forest::t8_forest_t)::Cvoid +function t8_dline_get_level(line) + @ccall libt8.t8_dline_get_level(line::Ptr{t8_dline_t})::Cint end """ - t8_forest_new_gather(forest_from, gather_rank) - -Create a new forest that gathers a given forest on one process. + t8_dline_copy(line, dest) -This functionality is mostly required for comparison purposes and sanity checks within the testing framework. +Copy all values from one line to another. # Arguments -* `forest_from`:\\[in\\] the forest that should be gathered on one rank -* `gather_rank`:\\[in\\] the rank of the process the forest will be gathered on -# Returns -The gathered forest: The same as *forest_from*, but all elements are on rank *gather_rank*. +* `line`:\\[in\\] The line to be copied. +* `dest`:\\[in,out\\] Existing line whose data will be filled with the data of *line*. ### Prototype ```c -t8_forest_t t8_forest_new_gather (const t8_forest_t forest_from, const int gather_rank); +void t8_dline_copy (const t8_dline_t *line, t8_dline_t *dest); ``` """ -function t8_forest_new_gather(forest_from, gather_rank) - @ccall libt8.t8_forest_new_gather(forest_from::t8_forest_t, gather_rank::Cint)::t8_forest_t +function t8_dline_copy(line, dest) + @ccall libt8.t8_dline_copy(line::Ptr{t8_dline_t}, dest::Ptr{t8_dline_t})::Cvoid end """ - t8_forest_set_partition_offset(forest, first_global_element) - -Manually set the partition offset of the current process. + t8_dline_compare(line1, line2) -If set, the next partitioning of the forest will use the manually defined element offsets. +Compare two elements. returns negative if line1 < line2, zero if line1 equals line2 and positive if line1 > line2. If line2 is a copy of line1 then the elements are equal. -# Arguments -* `forest`:\\[in,out\\] the considered forest -* `first_global_element`:\\[in\\] the global ID that will become the first local element ### Prototype ```c -void t8_forest_set_partition_offset (t8_forest_t forest, const t8_gloidx_t first_global_element); +int t8_dline_compare (const t8_dline_t *line1, const t8_dline_t *line2); ``` """ -function t8_forest_set_partition_offset(forest, first_global_element) - @ccall libt8.t8_forest_set_partition_offset(forest::t8_forest_t, first_global_element::t8_gloidx_t)::Cvoid +function t8_dline_compare(line1, line2) + @ccall libt8.t8_dline_compare(line1::Ptr{t8_dline_t}, line2::Ptr{t8_dline_t})::Cint end """ - t8_forest_partition_create_offsets(forest) + t8_dline_equal(line1, line2) -Create the element\\_offset array of a partitioned forest. +Check if two elements are equal. # Arguments -* `forest`:\\[in,out\\] The forest. *forest* must be committed before calling this function. +* `line1`:\\[in\\] The first element. +* `line2`:\\[in\\] The second element. +# Returns +1 if the elements are equal, 0 if they are not equal ### Prototype ```c -void t8_forest_partition_create_offsets (t8_forest_t forest); +int t8_dline_equal (const t8_dline_t *line1, const t8_dline_t *line2); ``` """ -function t8_forest_partition_create_offsets(forest) - @ccall libt8.t8_forest_partition_create_offsets(forest::t8_forest_t)::Cvoid +function t8_dline_equal(line1, line2) + @ccall libt8.t8_dline_equal(line1::Ptr{t8_dline_t}, line2::Ptr{t8_dline_t})::Cint end """ - t8_forest_partition_next_nonempty_rank(forest, rank) + t8_dline_parent(line, parent) -If t8_forest_partition_create_offsets was already called, compute for a given rank the next greater rank that is not empty. +Compute the parent of a line. # Arguments -* `forest`:\\[in\\] The forest. -* `rank`:\\[in\\] An MPI rank. -# Returns -A rank q > *rank* such that the forest has elements on *q*. If such a *q* does not exist, returns mpisize. +* `line`:\\[in\\] The input line. +* `parent`:\\[in,out\\] Existing line whose data will be filled with the parent data of *line*. ### Prototype ```c -int t8_forest_partition_next_nonempty_rank (t8_forest_t forest, int rank); +void t8_dline_parent (const t8_dline_t *line, t8_dline_t *parent); ``` """ -function t8_forest_partition_next_nonempty_rank(forest, rank) - @ccall libt8.t8_forest_partition_next_nonempty_rank(forest::t8_forest_t, rank::Cint)::Cint +function t8_dline_parent(line, parent) + @ccall libt8.t8_dline_parent(line::Ptr{t8_dline_t}, parent::Ptr{t8_dline_t})::Cvoid end """ - t8_forest_partition_create_first_desc(forest) + t8_dline_ancestor(line, level, ancestor) -Create the array of global\\_first\\_descendant ids of a partitioned forest. +Compute the ancestor of a line at a given level. + +!!! note + + The line *ancestor* may point to the same line as *line*. # Arguments -* `forest`:\\[in,out\\] The forest. *forest* must be committed before calling this function. +* `line`:\\[in\\] Input line. +* `level`:\\[in\\] A smaller level than *line*. +* `ancestor`:\\[in,out\\] Existing line whose data will be filled with the data of *line*'s ancestor on level *level*. ### Prototype ```c -void t8_forest_partition_create_first_desc (t8_forest_t forest); +void t8_dline_ancestor (const t8_dline_t *line, int level, t8_dline_t *ancestor); ``` """ -function t8_forest_partition_create_first_desc(forest) - @ccall libt8.t8_forest_partition_create_first_desc(forest::t8_forest_t)::Cvoid +function t8_dline_ancestor(line, level, ancestor) + @ccall libt8.t8_dline_ancestor(line::Ptr{t8_dline_t}, level::Cint, ancestor::Ptr{t8_dline_t})::Cvoid end """ - t8_forest_partition_create_tree_offsets(forest) + t8_dline_child(line, childid, child) -Create the array tree offsets of a partitioned forest. This arrays stores at position p the global id of the first tree of this process. Or if this tree is shared, it stores -(global\\_id) - 1. +Compute the childid-th child in Morton order of a line. # Arguments -* `forest`:\\[in,out\\] The forest. *forest* must be committed before calling this function. +* `line`:\\[in\\] Input Line. +* `childid`:\\[in\\] The id of the child, 0 or 1, in Morton order. +* `child`:\\[in,out\\] Existing Line whose data will be filled with the date of l's childid-th child. ### Prototype ```c -void t8_forest_partition_create_tree_offsets (t8_forest_t forest); +void t8_dline_child (const t8_dline_t *line, int childid, t8_dline_t *child); ``` """ -function t8_forest_partition_create_tree_offsets(forest) - @ccall libt8.t8_forest_partition_create_tree_offsets(forest::t8_forest_t)::Cvoid +function t8_dline_child(line, childid, child) + @ccall libt8.t8_dline_child(line::Ptr{t8_dline_t}, childid::Cint, child::Ptr{t8_dline_t})::Cvoid end """ - t8_forest_partition_data(forest_from, forest_to, data_in, data_out) + t8_dline_face_neighbour(line, neigh, face, dual_face) -Re-Partition an array accordingly to a partitioned forest. +Compute the face neighbor of a line. !!! note - *data_in* has to be of size equal to the number of local elements of *forest_from* *data_out* has to be already allocated and has to be of size equal to the number of local elements of *forest_to*. + *line* may point to the same line as *neigh*. # Arguments -* `forest_from`:\\[in\\] The forest before the partitioning step. -* `forest_to`:\\[in\\] The partitioned forest of *forest_from*. -* `data_in`:\\[in\\] A pointer to an [`sc_array_t`](@ref) holding data (one value per element) accordingly to *forest_from*. -* `data_out`:\\[in,out\\] A pointer to an already allocated [`sc_array_t`](@ref) capable of holding data accordingly to *forest_to*. +* `line`:\\[in\\] Input line. +* `neigh`:\\[in,out\\] Existing line whose data will be filled. +* `face`:\\[in\\] The face across which to generate the neighbor. +* `dual_face`:\\[out\\] If not NULL, the face number as seen from *neigh* is stored. ### Prototype ```c -void t8_forest_partition_data (t8_forest_t forest_from, t8_forest_t forest_to, const sc_array_t *data_in, sc_array_t *data_out); +void t8_dline_face_neighbour (const t8_dline_t *line, t8_dline_t *neigh, int face, int *dual_face); ``` """ -function t8_forest_partition_data(forest_from, forest_to, data_in, data_out) - @ccall libt8.t8_forest_partition_data(forest_from::t8_forest_t, forest_to::t8_forest_t, data_in::Ptr{sc_array_t}, data_out::Ptr{sc_array_t})::Cvoid +function t8_dline_face_neighbour(line, neigh, face, dual_face) + @ccall libt8.t8_dline_face_neighbour(line::Ptr{t8_dline_t}, neigh::Ptr{t8_dline_t}, face::Cint, dual_face::Ptr{Cint})::Cvoid end """ - t8_forest_partition_test_boundary_element(forest) + t8_dline_nearest_common_ancestor(line1, line2, nca) -Test if the last descendant of the last element of current rank has a smaller linear id than the stored first descendant of rank+1. If this is not the case, elements overlap. +Computes the nearest common ancestor of two lines in the same tree. !!! note - *forest* must be committed before calling this function. + *line1*, *line2*, *nca* may point to the same line. # Arguments -* `forest`:\\[in\\] The forest. +* `line1`:\\[in\\] First input line. +* `line2`:\\[in\\] Second input line. +* `nca`:\\[in,out\\] Existing line whose data will be filled. ### Prototype ```c -void t8_forest_partition_test_boundary_element (const t8_forest_t forest); +void t8_dline_nearest_common_ancestor (const t8_dline_t *line1, const t8_dline_t *line2, t8_dline_t *nca); ``` """ -function t8_forest_partition_test_boundary_element(forest) - @ccall libt8.t8_forest_partition_test_boundary_element(forest::t8_forest_t)::Cvoid +function t8_dline_nearest_common_ancestor(line1, line2, nca) + @ccall libt8.t8_dline_nearest_common_ancestor(line1::Ptr{t8_dline_t}, line2::Ptr{t8_dline_t}, nca::Ptr{t8_dline_t})::Cvoid end """ - t8_forest_pfc_correction_offsets(forest) + t8_dline_ancestor_id(line, level) -Correct the partitioning if element families are split across process boundaries. +Compute the position of the ancestor of this child at level *level* within its siblings. -The default partitioning distributes the elements into equally-sized partitions. For coarsening, however, all elements of a family have to be on the same process in order to be coarsened into their parent element. This function corrects the partitioning such that no families are split across process boundaries. The price to be paid is a slight deviation from the optimal balance of elements among processors. +# Arguments +* `line`:\\[in\\] line to be considered. +* `level`:\\[in\\] level to be considered. +# Returns +Returns its child id 0 or 1. +### Prototype +```c +int t8_dline_ancestor_id (const t8_dline_t *line, int level); +``` +""" +function t8_dline_ancestor_id(line, level) + @ccall libt8.t8_dline_ancestor_id(line::Ptr{t8_dline_t}, level::Cint)::Cint +end + +""" + t8_dline_face_parent_face(line, face) + +Given a face of a line return the face number of the parent of the line that matches the line's face. Or return -1 if no face of the parent matches the face. # Arguments -* `forest`:\\[in,out\\] the forest. On input, it has been partitioned into equally-sized element partitions. On output, the partitioning has been adjusted such that no element families are split across the process boundaries. +* `line`:\\[in\\] The line. +* `face`:\\[in\\] The number of the face. +# Returns +If *face* of *line* is also a face of *line*'s parent, the face number of this face. Otherwise -1. ### Prototype ```c -void t8_forest_pfc_correction_offsets (t8_forest_t forest); +int t8_dline_face_parent_face (const t8_dline_t *line, int face); ``` """ -function t8_forest_pfc_correction_offsets(forest) - @ccall libt8.t8_forest_pfc_correction_offsets(forest::t8_forest_t)::Cvoid +function t8_dline_face_parent_face(line, face) + @ccall libt8.t8_dline_face_parent_face(line::Ptr{t8_dline_t}, face::Cint)::Cint end """ - t8_forest_set_profiling(forest, set_profiling) + t8_dline_child_id(line) +Compute the position of the ancestor of this child at level *level* within its siblings. + +# Arguments +* `line`:\\[in\\] line to be considered. +# Returns +Returns its child id in 0,1 ### Prototype ```c -void t8_forest_set_profiling (t8_forest_t forest, int set_profiling); +int t8_dline_child_id (const t8_dline_t *line); ``` """ -function t8_forest_set_profiling(forest, set_profiling) - @ccall libt8.t8_forest_set_profiling(forest::t8_forest_t, set_profiling::Cint)::Cvoid +function t8_dline_child_id(line) + @ccall libt8.t8_dline_child_id(line::Ptr{t8_dline_t})::Cint end """ - t8_forest_compute_profile(forest) + t8_dline_childrenpv(line, c) + +Compute the 2 children of a line, array version. +# Arguments +* `line`:\\[in\\] Input line. +* `c`:\\[in,out\\] Pointers to the 2 computed children in Morton order. t may point to the same quadrant as c[0]. ### Prototype ```c -void t8_forest_compute_profile (t8_forest_t forest); +void t8_dline_childrenpv (const t8_dline_t *line, t8_dline_t *c[T8_DLINE_CHILDREN]); ``` """ -function t8_forest_compute_profile(forest) - @ccall libt8.t8_forest_compute_profile(forest::t8_forest_t)::Cvoid +function t8_dline_childrenpv(line, c) + @ccall libt8.t8_dline_childrenpv(line::Ptr{t8_dline_t}, c::Ptr{Ptr{t8_dline_t}})::Cvoid end """ - t8_forest_profile_get_adapt_stats(forest) + t8_dline_is_familypv(f) + +Check whether a collection of two lines is a family in Morton order. +# Arguments +* `f`:\\[in\\] An array of two lines. +# Returns +Nonzero if *f* is a family of lines. ### Prototype ```c -const sc_statinfo_t * t8_forest_profile_get_adapt_stats (t8_forest_t forest); +int t8_dline_is_familypv (const t8_dline_t *f[]); ``` """ -function t8_forest_profile_get_adapt_stats(forest) - @ccall libt8.t8_forest_profile_get_adapt_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} +function t8_dline_is_familypv(f) + @ccall libt8.t8_dline_is_familypv(f::Ptr{Ptr{t8_dline_t}})::Cint end """ - t8_forest_profile_get_ghost_stats(forest) + t8_dline_is_root_boundary(line, face) +Compute whether a given line shares a given face with its root tree. + +# Arguments +* `line`:\\[in\\] The input line. +* `face`:\\[in\\] A face of *line*. +# Returns +True if *face* is a subface of the line's root element. ### Prototype ```c -const sc_statinfo_t * t8_forest_profile_get_ghost_stats (t8_forest_t forest); +int t8_dline_is_root_boundary (const t8_dline_t *line, int face); ``` """ -function t8_forest_profile_get_ghost_stats(forest) - @ccall libt8.t8_forest_profile_get_ghost_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} +function t8_dline_is_root_boundary(line, face) + @ccall libt8.t8_dline_is_root_boundary(line::Ptr{t8_dline_t}, face::Cint)::Cint end """ - t8_forest_profile_get_partition_stats(forest) + t8_dline_is_inside_root(line) + +Test if a line lies inside of the root line, that is the line of level 0, anchor node (0,0) +# Arguments +* `line`:\\[in\\] Input line. +# Returns +true If *line* lies inside of the root line. ### Prototype ```c -const sc_statinfo_t * t8_forest_profile_get_partition_stats (t8_forest_t forest); +int t8_dline_is_inside_root (const t8_dline_t *line); ``` """ -function t8_forest_profile_get_partition_stats(forest) - @ccall libt8.t8_forest_profile_get_partition_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} +function t8_dline_is_inside_root(line) + @ccall libt8.t8_dline_is_inside_root(line::Ptr{t8_dline_t})::Cint end """ - t8_forest_profile_get_commit_stats(forest) + t8_dline_init_linear_id(line, level, id) +Initialize a line as the line with a given global id in a uniform refinement of a given level. * + +# Arguments +* `line`:\\[in,out\\] Existing line whose data will be filled. +* `id`:\\[in\\] Index to be considered. +* `level`:\\[in\\] level of uniform grid to be considered. ### Prototype ```c -const sc_statinfo_t * t8_forest_profile_get_commit_stats (t8_forest_t forest); +void t8_dline_init_linear_id (t8_dline_t *line, int level, t8_linearidx_t id); ``` """ -function t8_forest_profile_get_commit_stats(forest) - @ccall libt8.t8_forest_profile_get_commit_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} +function t8_dline_init_linear_id(line, level, id) + @ccall libt8.t8_dline_init_linear_id(line::Ptr{t8_dline_t}, level::Cint, id::t8_linearidx_t)::Cvoid end """ - t8_forest_profile_get_balance_stats(forest) + t8_dline_successor(line, succ, level) +Computes the successor of a line in a uniform grid of level *level*. + +# Arguments +* `line`:\\[in\\] line whose id will be computed. +* `succ`:\\[in,out\\] Existing line whose data will be filled with the data of *line*'s successor on level *level*. +* `level`:\\[in\\] level of uniform grid to be considered. ### Prototype ```c -const sc_statinfo_t * t8_forest_profile_get_balance_stats (t8_forest_t forest); +void t8_dline_successor (const t8_dline_t *line, t8_dline_t *succ, int level); ``` """ -function t8_forest_profile_get_balance_stats(forest) - @ccall libt8.t8_forest_profile_get_balance_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} +function t8_dline_successor(line, succ, level) + @ccall libt8.t8_dline_successor(line::Ptr{t8_dline_t}, succ::Ptr{t8_dline_t}, level::Cint)::Cvoid end """ - t8_forest_profile_get_balance_rounds_stats(forest) + t8_dline_transform_face(line1, line2, orientation) +Suppose we have two trees that share a common face f. Given a Line e that is a subface of f in one of the trees and given the orientation of the tree connection, construct the face Line of the respective tree neighbor that logically coincides with e but lies in the coordinate system of the neighbor tree. + +# Arguments +* `line1`:\\[in\\] The face element. +* `line2`:\\[in,out\\] On return the face element *line1* with respect to the coordinate system of the other tree. +* `orientation`:\\[in\\] The orientation of the tree-tree connection. 0 if vertex 0 of face 0 coincides with vertex 0 of face 1. 1 if vertex 0 of face 0 coincides with vertex 1 of face 1. ### Prototype ```c -const sc_statinfo_t * t8_forest_profile_get_balance_rounds_stats (t8_forest_t forest); +void t8_dline_transform_face (const t8_dline_t *line1, t8_dline_t *line2, int orientation); ``` """ -function t8_forest_profile_get_balance_rounds_stats(forest) - @ccall libt8.t8_forest_profile_get_balance_rounds_stats(forest::t8_forest_t)::Ptr{sc_statinfo_t} +function t8_dline_transform_face(line1, line2, orientation) + @ccall libt8.t8_dline_transform_face(line1::Ptr{t8_dline_t}, line2::Ptr{t8_dline_t}, orientation::Cint)::Cvoid end """ - t8_forest_print_profile(forest) + t8_dline_extrude_face(face, root_face, line) +Given a vertex at the boundary of a line at a root tree boundary, construct the line from it. + +# Arguments +* `face`:\\[in\\] The face element (vertex). +* `root_face`:\\[in\\] The index of the face of the tree. +* `line`:\\[out\\] The line that has *face* as face element at face *root_face* +# Returns +The face number pf *line* that coincides with *face*, thus *root_face* is returned. ### Prototype ```c -void t8_forest_print_profile (t8_forest_t forest); +int t8_dline_extrude_face (const t8_dvertex_t *face, int root_face, t8_dline_t *line); ``` """ -function t8_forest_print_profile(forest) - @ccall libt8.t8_forest_print_profile(forest::t8_forest_t)::Cvoid +function t8_dline_extrude_face(face, root_face, line) + @ccall libt8.t8_dline_extrude_face(face::Ptr{t8_dvertex_t}, root_face::Cint, line::Ptr{t8_dline_t})::Cint end """ - t8_forest_profile_get_adapt_time(forest) + t8_dline_first_descendant(line, desc, level) + +Compute the first descendant of a line at a given level. This is the descendant of the line in a uniform level refinement that has the smallest id. +# Arguments +* `line`:\\[in\\] Line whose descendant is computed. +* `desc`:\\[out\\] Existing line whose data will be filled with the data of *line*'s first descendant on level *level*. +* `level`:\\[in\\] The refinement level. Must be greater than *line*'s refinement level. ### Prototype ```c -double t8_forest_profile_get_adapt_time (t8_forest_t forest); +void t8_dline_first_descendant (const t8_dline_t *line, t8_dline_t *desc, int level); ``` """ -function t8_forest_profile_get_adapt_time(forest) - @ccall libt8.t8_forest_profile_get_adapt_time(forest::t8_forest_t)::Cdouble +function t8_dline_first_descendant(line, desc, level) + @ccall libt8.t8_dline_first_descendant(line::Ptr{t8_dline_t}, desc::Ptr{t8_dline_t}, level::Cint)::Cvoid end """ - t8_forest_profile_get_partition_time(forest, procs_sent) + t8_dline_last_descendant(line, desc, level) + +Compute the last descendant of a line at a given level. This is the descendant of the line in a uniform level refinement that has the largest id. +# Arguments +* `line`:\\[in\\] Line whose descendant is computed. +* `desc`:\\[out\\] Existing line whose data will be filled with the data of *line*'s last descendant on level *level*. +* `level`:\\[in\\] The refinement level. Must be greater than *line*'s refinement level. ### Prototype ```c -double t8_forest_profile_get_partition_time (t8_forest_t forest, int *procs_sent); +void t8_dline_last_descendant (const t8_dline_t *line, t8_dline_t *desc, int level); ``` """ -function t8_forest_profile_get_partition_time(forest, procs_sent) - @ccall libt8.t8_forest_profile_get_partition_time(forest::t8_forest_t, procs_sent::Ptr{Cint})::Cdouble +function t8_dline_last_descendant(line, desc, level) + @ccall libt8.t8_dline_last_descendant(line::Ptr{t8_dline_t}, desc::Ptr{t8_dline_t}, level::Cint)::Cvoid end """ - t8_forest_profile_get_balance_time(forest, balance_rounds) + t8_dline_vertex_integer_coords(line, vertex, coords) + +Compute the first or second vertex of a line. +# Arguments +* `line`:\\[in\\] Line whose vertex is computed. +* `vertex`:\\[in\\] The number of the vertex of *line* +* `coords`:\\[out\\] The coordinates of the computed vertex ### Prototype ```c -double t8_forest_profile_get_balance_time (t8_forest_t forest, int *balance_rounds); +void t8_dline_vertex_integer_coords (const t8_dline_t *line, const int vertex, int coords[]); ``` """ -function t8_forest_profile_get_balance_time(forest, balance_rounds) - @ccall libt8.t8_forest_profile_get_balance_time(forest::t8_forest_t, balance_rounds::Ptr{Cint})::Cdouble +function t8_dline_vertex_integer_coords(line, vertex, coords) + @ccall libt8.t8_dline_vertex_integer_coords(line::Ptr{t8_dline_t}, vertex::Cint, coords::Ptr{Cint})::Cvoid end """ - t8_forest_profile_get_ghost_time(forest, ghosts_sent) + t8_dline_vertex_ref_coords(line, vertex, coordinates) + +Compute the coordinates of a vertex of a line when the tree (level 0 line) is embedded in [0,1]^1. +# Arguments +* `line`:\\[in\\] Input line. +* `vertex`:\\[in\\] The number of the vertex. +* `coordinates`:\\[out\\] An array of 1 double that will be filled with the reference coordinates of the vertex. ### Prototype ```c -double t8_forest_profile_get_ghost_time (t8_forest_t forest, t8_locidx_t *ghosts_sent); +void t8_dline_vertex_ref_coords (const t8_dline_t *line, const int vertex, double coordinates[1]); ``` """ -function t8_forest_profile_get_ghost_time(forest, ghosts_sent) - @ccall libt8.t8_forest_profile_get_ghost_time(forest::t8_forest_t, ghosts_sent::Ptr{Cint})::Cdouble +function t8_dline_vertex_ref_coords(line, vertex, coordinates) + @ccall libt8.t8_dline_vertex_ref_coords(line::Ptr{t8_dline_t}, vertex::Cint, coordinates::Ptr{Cdouble})::Cvoid end """ - t8_forest_profile_get_ghostexchange_waittime(forest) + t8_dline_compute_reference_coords(line, ref_coords, num_coords, skip_coords, out_coords) + +Convert points in the reference space of a line element to points in the reference space of the tree (level 0) embedded in [0,1]^1. + +```c++ + [0,1]^1 +``` +) + +# Arguments +* `line`:\\[in\\] Input line. +* `ref_coords`:\\[in\\] The reference coordinates in the line (*num_coords* times +* `num_coords`:\\[in\\] Number of coordinates to evaluate +* `skip_coords`:\\[in\\] Only used for batch computation of prisms. In all other cases 0. Skip coordinates in the *ref_coords* and *out_coords* array. +* `out_coords`:\\[out\\] An array of *num_coords* x 1 x double that will be filled with the reference coordinates of the points on the line. ### Prototype ```c -double t8_forest_profile_get_ghostexchange_waittime (t8_forest_t forest); +void t8_dline_compute_reference_coords (const t8_dline_t *line, const double *ref_coords, const size_t num_coords, const size_t skip_coords, double *out_coords); ``` """ -function t8_forest_profile_get_ghostexchange_waittime(forest) - @ccall libt8.t8_forest_profile_get_ghostexchange_waittime(forest::t8_forest_t)::Cdouble +function t8_dline_compute_reference_coords(line, ref_coords, num_coords, skip_coords, out_coords) + @ccall libt8.t8_dline_compute_reference_coords(line::Ptr{t8_dline_t}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, skip_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid end """ - t8_forest_profile_get_cmesh_offsets_runtime(forest) + t8_dline_linear_id(line, level) +Computes the linear position of a line in an uniform grid. + +# Arguments +* `line`:\\[in\\] Pointer to a line element whose id will be computed. +* `level`:\\[in\\] Refinement level of the line element. +# Returns +Returns the linear position of this line on a grid. ### Prototype ```c -double t8_forest_profile_get_cmesh_offsets_runtime (t8_forest_t forest); +t8_linearidx_t t8_dline_linear_id (const t8_dline_t *line, int level); ``` """ -function t8_forest_profile_get_cmesh_offsets_runtime(forest) - @ccall libt8.t8_forest_profile_get_cmesh_offsets_runtime(forest::t8_forest_t)::Cdouble +function t8_dline_linear_id(line, level) + @ccall libt8.t8_dline_linear_id(line::Ptr{t8_dline_t}, level::Cint)::t8_linearidx_t end """ - t8_forest_profile_get_forest_offsets_runtime(forest) + t8_dline_is_valid(line) + +Query whether all entries of a line are in valid ranges. +# Arguments +* `line`:\\[in\\] line to be considered. +# Returns +True, if *line* is a valid line and it is safe to call any function in this file on *line*. False otherwise. ### Prototype ```c -double t8_forest_profile_get_forest_offsets_runtime (t8_forest_t forest); +int t8_dline_is_valid (const t8_dline_t *line); ``` """ -function t8_forest_profile_get_forest_offsets_runtime(forest) - @ccall libt8.t8_forest_profile_get_forest_offsets_runtime(forest::t8_forest_t)::Cdouble +function t8_dline_is_valid(line) + @ccall libt8.t8_dline_is_valid(line::Ptr{t8_dline_t})::Cint end """ - t8_forest_profile_get_first_descendant_runtime(forest) + t8_dline_init(line) +Set default values for a line, such that it passes t8_dline_is_valid. + +# Arguments +* `line`:\\[in\\] line to be initialized ### Prototype ```c -double t8_forest_profile_get_first_descendant_runtime (t8_forest_t forest); +void t8_dline_init (t8_dline_t *line); ``` """ -function t8_forest_profile_get_first_descendant_runtime(forest) - @ccall libt8.t8_forest_profile_get_first_descendant_runtime(forest::t8_forest_t)::Cdouble +function t8_dline_init(line) + @ccall libt8.t8_dline_init(line::Ptr{t8_dline_t})::Cvoid end +"""Type for the (integer) type of a triangular element.""" +const t8_dtri_type_t = Int8 + +"""Type of an integer coordinate for a node of a triangular element.""" +const t8_dtri_coord_t = Int32 + """ - t8_profile + t8_dtri -This struct holds profiling information, such as timings or statistics about communication. +The data container describing a refined element in a refined tree for the triangular element class. -| Field | Note | -| :----------------------------- | :------------------------------------------------------------------------------------------------------------- | -| partition\\_elements\\_shipped | The number of elements this process has sent to other in the last partition call. | -| partition\\_elements\\_recv | The number of elements this process has received from other in the last partition call. | -| partition\\_bytes\\_sent | The total number of bytes sent to other processes in the last partition call. | -| partition\\_procs\\_sent | The number of different processes this process has send local elements to in the last partition call. | -| ghosts\\_shipped | The number of ghost elements this process has sent to other processes. | -| ghosts\\_received | The number of ghost elements this process has received from other processes. | -| ghosts\\_remotes | The number of processes this process have sent ghost elements to (and received from). | -| balance\\_rounds | The number of iterations during balance. | -| adapt\\_runtime | The runtime of the last call to [`t8_forest_adapt`](@ref) (not counting adaptation in t8\\_forest\\_balance). | -| partition\\_runtime | The runtime of the last call to *t8_cmesh_partition* (not count in partition in t8\\_forest\\_balance). | -| ghost\\_runtime | The runtime of the last call to [`t8_forest_ghost_create`](@ref). | -| ghost\\_waittime | Amount of synchronisation time in ghost. | -| balance\\_runtime | The runtime of the last call to *t8_forest_balance*. | -| commit\\_runtime | The runtime of the last call to [`t8_cmesh_commit`](@ref). | -| cmesh\\_offsets\\_runtime | The runtime of the last call to [`t8_forest_partition_create_tree_offsets`](@ref). | -| forest\\_offsets\\_runtime | The runtime of the last call to [`t8_forest_partition_create_offsets`](@ref). | -| first\\_descendant\\_runtime | The runtime of the last call to [`t8_forest_partition_create_first_desc`](@ref). | +| Field | Note | +| :---- | :-------------------------------------------------------------------- | +| level | The refinement level of the element relative to the root at level 0. | +| type | Type of the triangle (0 or 1). | +| x | The x integer coordinate of the anchor node. | +| y | The y integer coordinate of the anchor node. | """ -struct t8_profile - partition_elements_shipped::t8_locidx_t - partition_elements_recv::t8_locidx_t - partition_bytes_sent::Csize_t - partition_procs_sent::Cint - ghosts_shipped::t8_locidx_t - ghosts_received::t8_locidx_t - ghosts_remotes::Cint - balance_rounds::Cint - adapt_runtime::Cdouble - partition_runtime::Cdouble - ghost_runtime::Cdouble - ghost_waittime::Cdouble - balance_runtime::Cdouble - commit_runtime::Cdouble - cmesh_offsets_runtime::Cdouble - forest_offsets_runtime::Cdouble - first_descendant_runtime::Cdouble +struct t8_dtri + level::Int8 + type::t8_dtri_type_t + x::t8_dtri_coord_t + y::t8_dtri_coord_t end -"""This struct holds profiling information, such as timings or statistics about communication.""" -const t8_profile_t = t8_profile +"""The data container describing a refined element in a refined tree for the triangular element class.""" +const t8_dtri_t = t8_dtri -"""If a forest is to be derived from another forest, there are different possibilities how the original forest is modified. Currently we support: Copying, adapting, partitioning, and balancing a forest. The latter 3 can be combined, in which case the order is 1. Adapt, 2. Partition, 3. Balance. We store the methods in an int8\\_t and use these defines to distinguish between them.""" -const t8_forest_from_t = Int8 +"""Type of an integer coordinate for a node of a prism element.""" +const t8_dprism_coord_t = Int32 -"""This structure is private to the implementation.""" -const t8_forest_struct_t = t8_forest +""" + t8_dprism -"""The t8 tree datatype""" -const t8_tree_struct_t = t8_tree +The data container describing a refined element in a refined tree for the prism element class. -"""This struct holds profiling information, such as timings or statistics about communication.""" -const t8_profile_struct_t = t8_profile +| Field | Note | +| :---- | :------------------------------ | +| line | z coordinate + level. | +| tri | x,y coordinate + level + type. | +""" +struct t8_dprism + line::t8_dline_t + tri::t8_dtri_t +end -"""This struct stores various information about a forest's ghost elements and ghost trees.""" -const t8_forest_ghost_struct_t = t8_forest_ghost +"""The data container describing a refined element in a refined tree for the prism element class.""" +const t8_dprism_t = t8_dprism """ - t8_geometry_type + t8_dprism_get_level(p) -This enumeration contains all possible geometries. +Compute the level of a prism. -| Enumerator | Note | -| :--------------------------------------------- | :----------------------------------------------------------------------------------------------- | -| T8\\_GEOMETRY\\_TYPE\\_ZERO | The zero geometry maps all points to zero. | -| T8\\_GEOMETRY\\_TYPE\\_LINEAR | The linear geometry uses linear interpolations to interpolate between the tree vertices. | -| T8\\_GEOMETRY\\_TYPE\\_LINEAR\\_AXIS\\_ALIGNED | The linear, axis aligned geometry uses only 2 vertices, since it is axis aligned. | -| T8\\_GEOMETRY\\_TYPE\\_LAGRANGE | The Lagrange geometry uses a mapping with Lagrange polynomials to approximate curved elements . | -| T8\\_GEOMETRY\\_TYPE\\_ANALYTIC | The analytic geometry uses a user-defined analytic function to map into the physical domain. | -| T8\\_GEOMETRY\\_TYPE\\_CAD | The opencascade geometry uses CAD shapes to map trees exactly to the underlying CAD model. | -| T8\\_GEOMETRY\\_TYPE\\_COUNT | This is no geometry type but can be used as the number of geometry types. | -| T8\\_GEOMETRY\\_TYPE\\_INVALID | This is no geometry type but is used as error type to describe invalid geometries | -| T8\\_GEOMETRY\\_TYPE\\_UNDEFINED | This is no geometry type but is used for every geometry, where no type is defined | +# Arguments +* `p`:\\[in\\] Line whose prism is computed. +# Returns +The level of *p*. +### Prototype +```c +int t8_dprism_get_level (const t8_dprism_t *p); +``` """ -@cenum t8_geometry_type::UInt32 begin - T8_GEOMETRY_TYPE_ZERO = 0 - T8_GEOMETRY_TYPE_LINEAR = 1 - T8_GEOMETRY_TYPE_LINEAR_AXIS_ALIGNED = 2 - T8_GEOMETRY_TYPE_LAGRANGE = 3 - T8_GEOMETRY_TYPE_ANALYTIC = 4 - T8_GEOMETRY_TYPE_CAD = 5 - T8_GEOMETRY_TYPE_COUNT = 6 - T8_GEOMETRY_TYPE_INVALID = 7 - T8_GEOMETRY_TYPE_UNDEFINED = 8 +function t8_dprism_get_level(p) + @ccall libt8.t8_dprism_get_level(p::Ptr{t8_dprism_t})::Cint +end + +""" + t8_dprism_copy(p, dest) + +Copy all values from one prism to another. + +# Arguments +* `p`:\\[in\\] The prism to be copied. +* `dest`:\\[in,out\\] Existing prism whose data will be filled with the data of *p*. +### Prototype +```c +void t8_dprism_copy (const t8_dprism_t *p, t8_dprism_t *dest); +``` +""" +function t8_dprism_copy(p, dest) + @ccall libt8.t8_dprism_copy(p::Ptr{t8_dprism_t}, dest::Ptr{t8_dprism_t})::Cvoid +end + +""" + t8_dprism_compare(p1, p2) + +Compare two elements. returns negative if p1 < p2, zero if p1 equals p2 and positive if p1 > p2. If p2 is a copy of p1 then the elements are equal. + +### Prototype +```c +int t8_dprism_compare (const t8_dprism_t *p1, const t8_dprism_t *p2); +``` +""" +function t8_dprism_compare(p1, p2) + @ccall libt8.t8_dprism_compare(p1::Ptr{t8_dprism_t}, p2::Ptr{t8_dprism_t})::Cint end -"""This enumeration contains all possible geometries.""" -const t8_geometry_type_t = t8_geometry_type +""" + t8_dprism_equal(elem1, elem2) -mutable struct t8_geometry_handler end +Check if two elements are equal. -"""This typedef holds virtual functions for the geometry handler. We need it so that we can use [`t8_geometry_handler_c`](@ref) pointers in .c files without them seeing the actual C++ code (and then not compiling) TODO: Delete this when the cmesh is a proper cpp class.""" -const t8_geometry_handler_c = t8_geometry_handler +# Arguments +* `elem1`:\\[in\\] The first element. +* `elem2`:\\[in\\] The second element. +# Returns +1 if the elements are equal, 0 if they are not equal +### Prototype +```c +int t8_dprism_equal (const t8_dprism_t *elem1, const t8_dprism_t *elem2); +``` +""" +function t8_dprism_equal(elem1, elem2) + @ccall libt8.t8_dprism_equal(elem1::Ptr{t8_dprism_t}, elem2::Ptr{t8_dprism_t})::Cint +end """ - t8_geometry_evaluate(cmesh, gtreeid, ref_coords, num_coords, out_coords) + t8_dprism_init_linear_id(p, level, id) -Evaluates the geometry of a tree at a given reference point. +Initialize a prism as the prism with a given global id in a uniform refinement of a given level. * # Arguments -* `cmesh`:\\[in\\] The cmesh -* `gtreeid`:\\[in\\] The global id of the tree -* `ref_coords`:\\[in\\] The reference coordinates at which to evaluate the geometry -* `num_coords`:\\[in\\] The number of reference coordinates -* `out_coords`:\\[out\\] The evaluated coordinates +* `p`:\\[in,out\\] Existing prism whose data will be filled. +* `id`:\\[in\\] Index to be considered. +* `level`:\\[in\\] level of uniform grid to be considered. ### Prototype ```c -void t8_geometry_evaluate (t8_cmesh_t cmesh, t8_gloidx_t gtreeid, const double *ref_coords, const size_t num_coords, double *out_coords); +void t8_dprism_init_linear_id (t8_dprism_t *p, int level, t8_linearidx_t id); ``` """ -function t8_geometry_evaluate(cmesh, gtreeid, ref_coords, num_coords, out_coords) - @ccall libt8.t8_geometry_evaluate(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid +function t8_dprism_init_linear_id(p, level, id) + @ccall libt8.t8_dprism_init_linear_id(p::Ptr{t8_dprism_t}, level::Cint, id::t8_linearidx_t)::Cvoid end """ - t8_geometry_jacobian(cmesh, gtreeid, ref_coords, num_coords, jacobian) + t8_dprism_successor(p, succ, level) -Evaluates the jacobian of a tree at a given reference point. +Computes the successor of a prism in a uniform grid of level *level*. # Arguments -* `cmesh`:\\[in\\] The cmesh -* `gtreeid`:\\[in\\] The global id of the tree -* `ref_coords`:\\[in\\] The reference coordinates at which to evaluate the jacobian -* `num_coords`:\\[in\\] The number of reference coordinates -* `jacobian`:\\[out\\] The jacobian at the reference coordinates +* `p`:\\[in\\] prism whose id will be computed. +* `succ`:\\[in,out\\] Existing prism whose data will be filled with the data of *l*'s successor on level *level*. +* `level`:\\[in\\] level of uniform grid to be considered. ### Prototype ```c -void t8_geometry_jacobian (t8_cmesh_t cmesh, t8_gloidx_t gtreeid, const double *ref_coords, const size_t num_coords, double *jacobian); +void t8_dprism_successor (const t8_dprism_t *p, t8_dprism_t *succ, int level); ``` """ -function t8_geometry_jacobian(cmesh, gtreeid, ref_coords, num_coords, jacobian) - @ccall libt8.t8_geometry_jacobian(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, jacobian::Ptr{Cdouble})::Cvoid +function t8_dprism_successor(p, succ, level) + @ccall libt8.t8_dprism_successor(p::Ptr{t8_dprism_t}, succ::Ptr{t8_dprism_t}, level::Cint)::Cvoid end """ - t8_geometry_get_type(cmesh, gtreeid) + t8_dprism_parent(p, parent) -This function returns the geometry type of a tree. +Compute the parent of a prism. + +!!! note + + *p* may point to the same prism as *parent*. # Arguments -* `cmesh`:\\[in\\] The cmesh -* `gtreeid`:\\[in\\] The global id of the tree -# Returns -The geometry type of the tree with id *gtreeid* +* `p`:\\[in\\] Input prism. +* `parent`:\\[in,out\\] Existing prism whose data will be filled with the data of p's parent. ### Prototype ```c -t8_geometry_type_t t8_geometry_get_type (t8_cmesh_t cmesh, t8_gloidx_t gtreeid); +void t8_dprism_parent (const t8_dprism_t *p, t8_dprism_t *parent); ``` """ -function t8_geometry_get_type(cmesh, gtreeid) - @ccall libt8.t8_geometry_get_type(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t)::t8_geometry_type_t +function t8_dprism_parent(p, parent) + @ccall libt8.t8_dprism_parent(p::Ptr{t8_dprism_t}, parent::Ptr{t8_dprism_t})::Cvoid end """ - t8_geometry_tree_negative_volume(cmesh, gtreeid) + t8_dprism_first_descendant(p, desc, level) -Check if a tree has a negative volume +Compute the first descendant of a prism at a given level. This is the descendant of the prism in a uniform level refinement that has the smallest id. # Arguments -* `cmesh`:\\[in\\] The cmesh to check -* `gtreeid`:\\[in\\] The global id of the tree -# Returns -True if the tree with id *gtreeid* has a negative volume. False otherwise. +* `p`:\\[in\\] Prism whose descendant is computed. +* `desc`:\\[out\\] Existing prism whose data will be filled with the data of *p*'s first descendant on level *level*. +* `level`:\\[in\\] The refinement level. Must be greater than *p*'s refinement level. ### Prototype ```c -int t8_geometry_tree_negative_volume (const t8_cmesh_t cmesh, const t8_gloidx_t gtreeid); +void t8_dprism_first_descendant (const t8_dprism_t *p, t8_dprism_t *desc, int level); ``` """ -function t8_geometry_tree_negative_volume(cmesh, gtreeid) - @ccall libt8.t8_geometry_tree_negative_volume(cmesh::t8_cmesh_t, gtreeid::t8_gloidx_t)::Cint +function t8_dprism_first_descendant(p, desc, level) + @ccall libt8.t8_dprism_first_descendant(p::Ptr{t8_dprism_t}, desc::Ptr{t8_dprism_t}, level::Cint)::Cvoid end """ - t8_geom_get_name(geom) + t8_dprism_child_id(p) -Get the name of a geometry. +Compute the position of the ancestor of this child at level *level* within its siblings. # Arguments -* `geom`:\\[in\\] A geometry. +* `p`:\\[in\\] prism to be considered. # Returns -The name of *geom*. +Returns its child id in 0 - 7 ### Prototype ```c -const char * t8_geom_get_name (const t8_geometry_c *geom); +int t8_dprism_child_id (const t8_dprism_t *p); ``` """ -function t8_geom_get_name(geom) - @ccall libt8.t8_geom_get_name(geom::Ptr{t8_geometry_c})::Cstring +function t8_dprism_child_id(p) + @ccall libt8.t8_dprism_child_id(p::Ptr{t8_dprism_t})::Cint end """ - t8_geom_get_type(geom) + t8_dprism_is_familypv(fam) -Get the type of a geometry. +Check whether a collection of eight prism is a family in Morton order. # Arguments -* `geom`:\\[in\\] A geometry. +* `fam`:\\[in\\] An array of eight prism. # Returns -The type of *geom*. +Nonzero if *fam* is a family of prism. ### Prototype ```c -t8_geometry_type_t t8_geom_get_type (const t8_geometry_c *geom); +int t8_dprism_is_familypv (t8_dprism_t **fam); ``` """ -function t8_geom_get_type(geom) - @ccall libt8.t8_geom_get_type(geom::Ptr{t8_geometry_c})::t8_geometry_type_t +function t8_dprism_is_familypv(fam) + @ccall libt8.t8_dprism_is_familypv(fam::Ptr{Ptr{t8_dprism_t}})::Cint end """ - t8_geom_compute_linear_geometry(tree_class, tree_vertices, ref_coords, num_coords, out_coords) + t8_dprism_nearest_common_ancestor(p1, p2, r) + +Computes the nearest common ancestor of two prisms in the same tree. +!!! note + + *t1*, *t2*, *r* may point to the same tetrahedron. + +# Arguments +* `p1`:\\[in\\] First input tetrahedron. +* `p2`:\\[in\\] Second input tetrahedron. +* `r`:\\[in,out\\] Existing tetrahedron whose data will be filled. ### Prototype ```c -void t8_geom_compute_linear_geometry (t8_eclass_t tree_class, const double *tree_vertices, const double *ref_coords, const size_t num_coords, double *out_coords); +void t8_dprism_nearest_common_ancestor (const t8_dprism_t *p1, const t8_dprism_t *p2, t8_dprism_t *r); ``` """ -function t8_geom_compute_linear_geometry(tree_class, tree_vertices, ref_coords, num_coords, out_coords) - @ccall libt8.t8_geom_compute_linear_geometry(tree_class::Cint, tree_vertices::Ptr{Cdouble}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid +function t8_dprism_nearest_common_ancestor(p1, p2, r) + @ccall libt8.t8_dprism_nearest_common_ancestor(p1::Ptr{t8_dprism_t}, p2::Ptr{t8_dprism_t}, r::Ptr{t8_dprism_t})::Cvoid end """ - t8_geom_compute_linear_axis_aligned_geometry(tree_class, tree_vertices, ref_coords, num_coords, out_coords) + t8_dprism_boundary_face(p, face, boundary) +Constructs the boundary element of a prism at a given face + +# Arguments +* `p`:\\[in\\] The input prism. +* `face`:\\[in\\] A face of *p* +* `boundary`:\\[in,out\\] The boundary element at *face* of *p* ### Prototype ```c -void t8_geom_compute_linear_axis_aligned_geometry (t8_eclass_t tree_class, const double *tree_vertices, const double *ref_coords, const size_t num_coords, double *out_coords); +void t8_dprism_boundary_face (const t8_dprism_t *p, int face, t8_element_t *boundary); ``` """ -function t8_geom_compute_linear_axis_aligned_geometry(tree_class, tree_vertices, ref_coords, num_coords, out_coords) - @ccall libt8.t8_geom_compute_linear_axis_aligned_geometry(tree_class::Cint, tree_vertices::Ptr{Cdouble}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid +function t8_dprism_boundary_face(p, face, boundary) + @ccall libt8.t8_dprism_boundary_face(p::Ptr{t8_dprism_t}, face::Cint, boundary::Ptr{t8_element_t})::Cvoid end """ - t8_geom_linear_interpolation(coefficients, corner_values, corner_value_dim, interpolation_dim, evaluated_function) + t8_dprism_is_root_boundary(p, face) -Interpolates linearly between 2, bilinearly between 4 or trilineraly between 8 points. +Compute whether a given prism shares a given face with its root tree. # Arguments -* `coefficients`:\\[in\\] An array of size at least dim giving the coefficients used for the interpolation -* `corner_values`:\\[in\\] An array of size 2^dim * 3, giving for each corner (in zorder) of the unit square/cube its function values in space. -* `corner_value_dim`:\\[in\\] The dimension of the *corner_values*. -* `interpolation_dim`:\\[in\\] The dimension of the interpolation (1 for linear, 2 for bilinear, 3 for trilinear) -* `evaluated_function`:\\[out\\] An array of size *corner_value_dim*, on output the result of the interpolation. +* `p`:\\[in\\] The input prism. +* `face`:\\[in\\] A face of *p*. +# Returns +True if *face* is a subface of the prisms's root element. ### Prototype ```c -void t8_geom_linear_interpolation (const double *coefficients, const double *corner_values, int corner_value_dim, int interpolation_dim, double *evaluated_function); +int t8_dprism_is_root_boundary (const t8_dprism_t *p, int face); ``` """ -function t8_geom_linear_interpolation(coefficients, corner_values, corner_value_dim, interpolation_dim, evaluated_function) - @ccall libt8.t8_geom_linear_interpolation(coefficients::Ptr{Cdouble}, corner_values::Ptr{Cdouble}, corner_value_dim::Cint, interpolation_dim::Cint, evaluated_function::Ptr{Cdouble})::Cvoid +function t8_dprism_is_root_boundary(p, face) + @ccall libt8.t8_dprism_is_root_boundary(p::Ptr{t8_dprism_t}, face::Cint)::Cint end """ - t8_geom_triangular_interpolation(coefficients, corner_values, corner_value_dim, interpolation_dim, evaluated_function) + t8_dprism_is_inside_root(p) -Triangular interpolation between 3 points (triangle) or 4 points (tetrahedron) using cartesian coordinates. The input coefficients have to be given as coordinates in the reference triangle (interpolation\\_dim = 2) with points (0,0) (1,0) (1,1) or the reference tet (interpolation\\_dim = 3) with points (0,0,0) (1,0,0) (1,1,0) (1,1,1). +Test if a prism lies inside of the root prism, that is the prism of level 0, anchor node (0,0) and type 0. # Arguments -* `coefficients`:\\[in\\] An array of size *interpolation_dim* giving the coefficients in the reference triangle/tet used for the interpolation -* `corner_values`:\\[in\\] An array of size 3 * *corner_value_dim* for *interpolation_dim* == 2 or 4 * *corner_value_dim* for *interpolation_dim* == 3, giving the function values of the triangle/tetrahedron for each corner (in zorder) -* `corner_value_dim`:\\[in\\] The dimension of the *corner_values*. -* `interpolation_dim`:\\[in\\] The dimension of the interpolation (2 for triangle, 3 for tetrahedron) -* `evaluated_function`:\\[out\\] An array of size *corner_value_dim*, on output the result of the interpolation. +* `p`:\\[in\\] Input prism. +# Returns +true If *p* lies inside of the root prism. ### Prototype ```c -void t8_geom_triangular_interpolation (const double *coefficients, const double *corner_values, int corner_value_dim, int interpolation_dim, double *evaluated_function); +int t8_dprism_is_inside_root (t8_dprism_t *p); ``` """ -function t8_geom_triangular_interpolation(coefficients, corner_values, corner_value_dim, interpolation_dim, evaluated_function) - @ccall libt8.t8_geom_triangular_interpolation(coefficients::Ptr{Cdouble}, corner_values::Ptr{Cdouble}, corner_value_dim::Cint, interpolation_dim::Cint, evaluated_function::Ptr{Cdouble})::Cvoid +function t8_dprism_is_inside_root(p) + @ccall libt8.t8_dprism_is_inside_root(p::Ptr{t8_dprism_t})::Cint end """ - t8_geom_get_face_vertices(tree_class, tree_vertices, face_index, dim, face_vertices) + t8_dprism_child(p, childid, child) +Compute the childid-th child in Morton order of a prism. + +# Arguments +* `p`:\\[in\\] Input prism. +* `childid`:\\[in\\] The id of the child, in 0 - 7, in Morton order. +* `child`:\\[in,out\\] Existing prism whose data will be filled with the date of p's childid-th child. ### Prototype ```c -void t8_geom_get_face_vertices (t8_eclass_t tree_class, const double *tree_vertices, int face_index, int dim, double *face_vertices); +void t8_dprism_child (const t8_dprism_t *p, int childid, t8_dprism_t *child); ``` """ -function t8_geom_get_face_vertices(tree_class, tree_vertices, face_index, dim, face_vertices) - @ccall libt8.t8_geom_get_face_vertices(tree_class::Cint, tree_vertices::Ptr{Cdouble}, face_index::Cint, dim::Cint, face_vertices::Ptr{Cdouble})::Cvoid +function t8_dprism_child(p, childid, child) + @ccall libt8.t8_dprism_child(p::Ptr{t8_dprism_t}, childid::Cint, child::Ptr{t8_dprism_t})::Cvoid end """ - t8_geom_get_edge_vertices(tree_class, tree_vertices, edge_index, dim, edge_vertices) + t8_dprism_face_shape(face) +Return the shape of a face. + +# Arguments +* `face`:\\[in\\] A face id for *p*. +# Returns +The shape of *face*. ### Prototype ```c -void t8_geom_get_edge_vertices (t8_eclass_t tree_class, const double *tree_vertices, int edge_index, int dim, double *edge_vertices); +t8_element_shape_t t8_dprism_face_shape (int face); ``` """ -function t8_geom_get_edge_vertices(tree_class, tree_vertices, edge_index, dim, edge_vertices) - @ccall libt8.t8_geom_get_edge_vertices(tree_class::Cint, tree_vertices::Ptr{Cdouble}, edge_index::Cint, dim::Cint, edge_vertices::Ptr{Cdouble})::Cvoid +function t8_dprism_face_shape(face) + @ccall libt8.t8_dprism_face_shape(face::Cint)::t8_element_shape_t end """ - t8_geom_get_ref_intersection(edge_index, ref_coords, ref_intersection) + t8_dprism_num_face_children(face) -Calculates a point of intersection in a triangular reference space. The intersection is the extension of a straight line passing through a reference point and the opposite vertex of the edge. /|\\ / | \\ o -> reference point / o \\ x -> intersection point / | \\ /\\_\\_\\_\\_x\\_\\_\\_\\_\\ +Compute the number of children at a given face. # Arguments -* `edge_index`:\\[in\\] Index of the edge, the intersection lies on. -* `ref_coords`:\\[in\\] Array containing the coordinates of the reference point. -* `ref_intersection`:\\[out\\] Coordinates of the intersection point. +* `face`:\\[in\\] The face number +# Returns +Number of Children at *face* ### Prototype ```c -void t8_geom_get_ref_intersection (int edge_index, const double *ref_coords, double ref_intersection[2]); +int t8_dprism_num_face_children (int face); ``` """ -function t8_geom_get_ref_intersection(edge_index, ref_coords, ref_intersection) - @ccall libt8.t8_geom_get_ref_intersection(edge_index::Cint, ref_coords::Ptr{Cdouble}, ref_intersection::Ptr{Cdouble})::Cvoid +function t8_dprism_num_face_children(face) + @ccall libt8.t8_dprism_num_face_children(face::Cint)::Cint end """ - t8_geom_get_triangle_scaling_factor(edge_index, tree_vertices, glob_intersection, glob_ref_point) + t8_dprism_face_neighbour(p, face, neigh) -Calculates the scaling factor for edge displacement along a triangular tree face depending on the position of the global reference point. +Compute the face neighbor of a prism. + +!!! note + + *p* may point to the same prism as *n*. # Arguments -* `edge_index`:\\[in\\] Index of the edge, whose displacement should be scaled. -* `tree_vertices`:\\[in\\] Array with the tree vertex coordinates. -* `glob_intersection`:\\[in\\] Array containing the coordinates of the intersection point of a line drawn from the opposite vertex through the glob\\_ref\\_point onto the edge with edge\\_index. -* `glob_ref_point`:\\[in\\] Array containing the coordinates of the reference point mapped into the global space. +* `p`:\\[in\\] Input prism. +* `face`:\\[in\\] The face across which to generate the neighbor. +* `neigh`:\\[in,out\\] Existing prism whose data will be filled. +# Returns +The face number of *neigh* of the respective face. ### Prototype ```c -double t8_geom_get_triangle_scaling_factor (int edge_index, const double *tree_vertices, const double *glob_intersection, const double *glob_ref_point); +int t8_dprism_face_neighbour (const t8_dprism_t *p, int face, t8_dprism_t *neigh); ``` """ -function t8_geom_get_triangle_scaling_factor(edge_index, tree_vertices, glob_intersection, glob_ref_point) - @ccall libt8.t8_geom_get_triangle_scaling_factor(edge_index::Cint, tree_vertices::Ptr{Cdouble}, glob_intersection::Ptr{Cdouble}, glob_ref_point::Ptr{Cdouble})::Cdouble +function t8_dprism_face_neighbour(p, face, neigh) + @ccall libt8.t8_dprism_face_neighbour(p::Ptr{t8_dprism_t}, face::Cint, neigh::Ptr{t8_dprism_t})::Cint end """ - t8_geom_get_scaling_factor_of_edge_on_face_tet(edge_index, face_index, ref_coords) + t8_dprism_get_face_corner(face, corner) -Calculates the scaling factor for the displacement of an edge over a face of a tetrahedral element. +Return the corner number of a prism corresponding to a given face corner. # Arguments -* `edge_index`:\\[in\\] Index of the edge, whose displacement should be scaled. -* `face_index`:\\[in\\] Index of the face, the displacement should be scaled on. -* `ref_coords`:\\[in\\] Array containing the coordinates of the reference point. +* `face`:\\[in\\] The face number. +* `corner`:\\[in\\] A corner of *face* # Returns -The scaling factor of the edge displacement on the face at the point of the reference coordinates. +The corner index of *p* corresponding to the *corner*-th corner of *face*. ### Prototype ```c -double t8_geom_get_scaling_factor_of_edge_on_face_tet (int edge_index, int face_index, const double *ref_coords); +int t8_dprism_get_face_corner (int face, int corner); ``` """ -function t8_geom_get_scaling_factor_of_edge_on_face_tet(edge_index, face_index, ref_coords) - @ccall libt8.t8_geom_get_scaling_factor_of_edge_on_face_tet(edge_index::Cint, face_index::Cint, ref_coords::Ptr{Cdouble})::Cdouble +function t8_dprism_get_face_corner(face, corner) + @ccall libt8.t8_dprism_get_face_corner(face::Cint, corner::Cint)::Cint end """ - t8_geom_get_tet_face_intersection(face_index, ref_coords, face_intersection) + t8_dprism_childrenpv(p, length, c) -Calculates the face intersection of a ray passing trough the reference coordinates and the opposite vertex of that face for a tetrahedron. The coordinates of the face intersection are reference coordinates: [0,1]^3. +Compute the children of a prism, array version. # Arguments -* `face_index`:\\[in\\] Index of the face, on which the intersection should be calculated. -* `ref_coords`:\\[in\\] Array containing the coordinates of the reference point. -* `face_intersection`:\\[out\\] Three dimensional array containing the intersection point on the face in reference space. +* `p`:\\[in\\] Pointers to prism element the children should be computed for. +* `length`:\\[in\\] Number of children. +* `c`:\\[in,out\\] Pointers to the computed children in Morton order. ### Prototype ```c -void t8_geom_get_tet_face_intersection (const int face_index, const double *ref_coords, double face_intersection[3]); +void t8_dprism_childrenpv (const t8_dprism_t *p, int length, t8_dprism_t *c[]); ``` """ -function t8_geom_get_tet_face_intersection(face_index, ref_coords, face_intersection) - @ccall libt8.t8_geom_get_tet_face_intersection(face_index::Cint, ref_coords::Ptr{Cdouble}, face_intersection::Ptr{Cdouble})::Cvoid +function t8_dprism_childrenpv(p, length, c) + @ccall libt8.t8_dprism_childrenpv(p::Ptr{t8_dprism_t}, length::Cint, c::Ptr{Ptr{t8_dprism_t}})::Cvoid end """ - t8_geom_get_scaling_factor_of_edge_on_face_prism(edge_index, face_index, ref_coords) + t8_dprism_ancestor_id(p, level) -Calculates the scaling factor for the displacement of an edge over a face of a prism element. +Compute the position of the ancestor of this child at level *level* within its siblings. # Arguments -* `edge_index`:\\[in\\] Index of the edge, whose displacement should be scaled. -* `face_index`:\\[in\\] Index of the face, the displacement should be scaled on. -* `ref_coords`:\\[in\\] Array containing the coordinates of the reference point. +* `p`:\\[in\\] prism to be considered. +* `level`:\\[in\\] level to be considered. # Returns -The scaling factor of the edge displacement on the face at the point of the reference coordinates. +Returns its child id in 0..7 ### Prototype ```c -double t8_geom_get_scaling_factor_of_edge_on_face_prism (int edge_index, int face_index, const double *ref_coords); +int t8_dprism_ancestor_id (t8_dprism_t *p, int level); ``` """ -function t8_geom_get_scaling_factor_of_edge_on_face_prism(edge_index, face_index, ref_coords) - @ccall libt8.t8_geom_get_scaling_factor_of_edge_on_face_prism(edge_index::Cint, face_index::Cint, ref_coords::Ptr{Cdouble})::Cdouble +function t8_dprism_ancestor_id(p, level) + @ccall libt8.t8_dprism_ancestor_id(p::Ptr{t8_dprism_t}, level::Cint)::Cint end """ - t8_geom_get_scaling_factor_face_through_volume_prism(face, ref_coords) + t8_dprism_children_at_face(p, face, children, num_children, child_indices) -Calculates the scaling factor for the displacement of an face through the volume of a prism element. +Given a prism and a face of the prism, compute all children of the prism that touch the face. # Arguments -* `face`:\\[in\\] Index of the displaced face. -* `ref_coords`:\\[in\\] Array containing the coordinates of the reference point. -# Returns -The scaling factor of the face displacement at the point of the reference coordinates inside the prism volume. +* `p`:\\[in\\] The prism. +* `face`:\\[in\\] A face of *p*. +* `children`:\\[in,out\\] Allocated prism, in which the children of *p* that share a face with *face* are stored. They will be stored in order of their child\\_id. +* `num_children`:\\[in\\] The number of prisms in *children*. Must match the number of children that touch *face*. +* `child_indices`:\\[in,out\\] The indices of the children in *children*. Only filled if this is null previously. ### Prototype ```c -double t8_geom_get_scaling_factor_face_through_volume_prism (const int face, const double *ref_coords); +void t8_dprism_children_at_face (const t8_dprism_t *p, int face, t8_dprism_t **children, int num_children, int *child_indices); ``` """ -function t8_geom_get_scaling_factor_face_through_volume_prism(face, ref_coords) - @ccall libt8.t8_geom_get_scaling_factor_face_through_volume_prism(face::Cint, ref_coords::Ptr{Cdouble})::Cdouble +function t8_dprism_children_at_face(p, face, children, num_children, child_indices) + @ccall libt8.t8_dprism_children_at_face(p::Ptr{t8_dprism_t}, face::Cint, children::Ptr{Ptr{t8_dprism_t}}, num_children::Cint, child_indices::Ptr{Cint})::Cvoid end """ - t8_vertex_point_inside(vertex_coords, point, tolerance) + t8_dprism_face_child_face(face) -Check if a point lies inside a vertex +Given a face of a prism and a child number of a child of that face, return the face number of the child of the prism that matches the child face. # Arguments -* `vertex_coords`:\\[in\\] The coordinates of the vertex -* `point`:\\[in\\] The coordinates of the point to check -* `tolerance`:\\[in\\] A double > 0 defining the tolerance +* `face`:\\[in\\] The number of the face. # Returns -0 if the point is outside, 1 otherwise. +The face number of the face of a child of *p* that coincides with *face_child*. ### Prototype ```c -int t8_vertex_point_inside (const double vertex_coords[3], const double point[3], const double tolerance); +int t8_dprism_face_child_face (int face); ``` """ -function t8_vertex_point_inside(vertex_coords, point, tolerance) - @ccall libt8.t8_vertex_point_inside(vertex_coords::Ptr{Cdouble}, point::Ptr{Cdouble}, tolerance::Cdouble)::Cint +function t8_dprism_face_child_face(face) + @ccall libt8.t8_dprism_face_child_face(face::Cint)::Cint end """ - t8_line_point_inside(p_0, vec, point, tolerance) + t8_dprism_face_parent_face(prism, face) -Check if a point is inside a line that is defined by a starting point *p_0* and a vector *vec* +Given a face of a prism return the face number of the parent of the prism that matches the prism's face. Or return -1 if no face of the parent matches the face. # Arguments -* `p_0`:\\[in\\] Starting point of the line -* `vec`:\\[in\\] Direction of the line (not normalized) -* `point`:\\[in\\] The coordinates of the point to check -* `tolerance`:\\[in\\] A double > 0 defining the tolerance +* `prism`:\\[in\\] The prism. +* `face`:\\[in\\] Then number of the face. # Returns -0 if the point is outside, 1 otherwise. +If *face* of *prism* is also a face of *prism*'s parent, the face number of this face. Otherwise -1. ### Prototype ```c -int t8_line_point_inside (const double *p_0, const double *vec, const double *point, const double tolerance); +int t8_dprism_face_parent_face (const t8_dprism_t *prism, int face); ``` """ -function t8_line_point_inside(p_0, vec, point, tolerance) - @ccall libt8.t8_line_point_inside(p_0::Ptr{Cdouble}, vec::Ptr{Cdouble}, point::Ptr{Cdouble}, tolerance::Cdouble)::Cint +function t8_dprism_face_parent_face(prism, face) + @ccall libt8.t8_dprism_face_parent_face(prism::Ptr{t8_dprism_t}, face::Cint)::Cint end """ - t8_triangle_point_inside(p_0, v, w, point, tolerance) + t8_dprism_tree_face(face) -Check if a point is inside of a triangle described by a point *p_0* and two vectors *v* and *w*. +Given a prism and a face of this prism. If the face lies on the tree boundary, return the face number of the tree face. If not the return value is arbitrary. # Arguments -* `p_0`:\\[in\\] The first vertex of a triangle -* `v`:\\[in\\] The vector from p\\_0 to p\\_1 (second vertex in the triangle) -* `w`:\\[in\\] The vector from p\\_0 to p\\_2 (third vertex in the triangle) -* `point`:\\[in\\] The coordinates of the point to check -* `tolerance`:\\[in\\] A double > 0 defining the tolerance +* `face`:\\[in\\] The index of a face of *elem*. # Returns -0 if the point is outside, 1 otherwise. +The index of the tree face that *face* is a subface of, if *face* is on a tree boundary. Any arbitrary integer if *is* not at a tree boundary. ### Prototype ```c -int t8_triangle_point_inside (const double p_0[3], const double v[3], const double w[3], const double point[3], const double tolerance); +int t8_dprism_tree_face (int face); ``` """ -function t8_triangle_point_inside(p_0, v, w, point, tolerance) - @ccall libt8.t8_triangle_point_inside(p_0::Ptr{Cdouble}, v::Ptr{Cdouble}, w::Ptr{Cdouble}, point::Ptr{Cdouble}, tolerance::Cdouble)::Cint +function t8_dprism_tree_face(face) + @ccall libt8.t8_dprism_tree_face(face::Cint)::Cint end """ - t8_plane_point_inside(point_on_face, face_normal, point) + t8_dprism_extrude_face(face, elem, root_face) -Check if a point lays on the inner side of a plane of a bilinearly interpolated volume element. the plane is described by a point and the normal of the face. +Given a boundary face inside a root tree's face construct the element inside the root tree that has the given face as a face. # Arguments -* `point_on_face`:\\[in\\] A point on the plane -* `face_normal`:\\[in\\] The normal of the face -* `point`:\\[in\\] The point to check -# Returns -0 if the point is outside, 1 otherwise. +* `face`:\\[in\\] A face element. +* `elem`:\\[in,out\\] An allocated element. The entries will be filled with the data of the element that has *face* as a face and lies within the root tree. +* `root_face`:\\[in\\] The index of the face of the root tree in which *face* lies. ### Prototype ```c -int t8_plane_point_inside (const double point_on_face[3], const double face_normal[3], const double point[3]); +void t8_dprism_extrude_face (const t8_element_t *face, t8_element_t *elem, const int root_face); ``` """ -function t8_plane_point_inside(point_on_face, face_normal, point) - @ccall libt8.t8_plane_point_inside(point_on_face::Ptr{Cdouble}, face_normal::Ptr{Cdouble}, point::Ptr{Cdouble})::Cint +function t8_dprism_extrude_face(face, elem, root_face) + @ccall libt8.t8_dprism_extrude_face(face::Ptr{t8_element_t}, elem::Ptr{t8_element_t}, root_face::Cint)::Cvoid end """ - t8_cmesh_set_tree_vertices(cmesh, gtree_id, vertices, num_vertices) + t8_dprism_last_descendant(p, s, level) -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. +Compute the last descendant of a prism at a given level. This is the descendant of the prism in a uniform level refinement that has the largest id. # Arguments -* `cmesh`:\\[in,out\\] The cmesh to be updated. -* `gtree_id`:\\[in\\] The global number of the tree. -* `vertices`:\\[in\\] An array of 3 doubles per tree vertex. -* `num_vertices`:\\[in\\] The number of verticess in *vertices*. Must match the number of corners of the tree. +* `p`:\\[in\\] Prism whose descendant is computed. +* `s`:\\[out\\] Existing prism whose data will be filled with the data of *p*'s last descendant on level *level*. +* `level`:\\[in\\] The refinement level. Must be greater than *p*'s refinement level. ### Prototype ```c -void t8_cmesh_set_tree_vertices (t8_cmesh_t cmesh, const t8_gloidx_t gtree_id, const double *vertices, const int num_vertices); +void t8_dprism_last_descendant (const t8_dprism_t *p, t8_dprism_t *s, int level); ``` """ -function t8_cmesh_set_tree_vertices(cmesh, gtree_id, vertices, num_vertices) - @ccall libt8.t8_cmesh_set_tree_vertices(cmesh::t8_cmesh_t, gtree_id::t8_gloidx_t, vertices::Ptr{Cdouble}, num_vertices::Cint)::Cvoid +function t8_dprism_last_descendant(p, s, level) + @ccall libt8.t8_dprism_last_descendant(p::Ptr{t8_dprism_t}, s::Ptr{t8_dprism_t}, level::Cint)::Cvoid +end + +""" + t8_dprism_corner_descendant(p, s, corner, level) + +Compute the descendant of a prism in a given corner. + +# Arguments +* `p`:\\[in\\] Prism whose descendant is computed. +* `s`:\\[out\\] Existing prism whose data will be filled with the data of p's descendant in *corner*. +* `corner`:\\[in\\] The corner in which the descendant should lie. +* `level`:\\[in\\] The refinement level of the descendant. Must be greater or equal to *p*'s level. +### Prototype +```c +void t8_dprism_corner_descendant (const t8_dprism_t *p, t8_dprism_t *s, int corner, int level); +``` +""" +function t8_dprism_corner_descendant(p, s, corner, level) + @ccall libt8.t8_dprism_corner_descendant(p::Ptr{t8_dprism_t}, s::Ptr{t8_dprism_t}, corner::Cint, level::Cint)::Cvoid end """ - t8_mat_init_xrot(mat, angle) + t8_dprism_vertex_integer_coords(elem, vertex, coords) -Initialize given 3x3 matrix as rotation matrix around the x-axis with given angle. +Compute the coordinates of a vertex of a prism. # Arguments -* `mat`:\\[in,out\\] 3x3-matrix. -* `angle`:\\[in\\] Rotation angle in radians. +* `elem`:\\[in\\] Input prism. +* `vertex`:\\[in\\] The number of the vertex. +* `coords`:\\[out\\] An array of 3 [`t8_dprism_coord_t`](@ref) that will be filled with the coordinates of the vertex. ### Prototype ```c -static inline void t8_mat_init_xrot (double mat[3][3], const double angle); +void t8_dprism_vertex_integer_coords (const t8_dprism_t *elem, int vertex, int coords[3]); ``` """ -function t8_mat_init_xrot(mat, angle) - @ccall libt8.t8_mat_init_xrot(mat::Ptr{NTuple{3, Cdouble}}, angle::Cdouble)::Cvoid +function t8_dprism_vertex_integer_coords(elem, vertex, coords) + @ccall libt8.t8_dprism_vertex_integer_coords(elem::Ptr{t8_dprism_t}, vertex::Cint, coords::Ptr{Cint})::Cvoid end """ - t8_mat_init_yrot(mat, angle) + t8_dprism_vertex_ref_coords(elem, vertex, coords) + +Compute the reference coordinates of a vertex of a prism when the tree (level 0) is embedded in + +```c++ + [0,1]^3 +``` -Initialize given 3x3 matrix as rotation matrix around the y-axis with given angle. +. # Arguments -* `mat`:\\[in,out\\] 3x3-matrix. -* `angle`:\\[in\\] Rotation angle in radians. +* `elem`:\\[in\\] Input prism. +* `vertex`:\\[in\\] The number of the vertex. +* `coords`:\\[out\\] An array of 3 double that will be filled with the reference coordinates of the vertex. ### Prototype ```c -static inline void t8_mat_init_yrot (double mat[3][3], const double angle); +void t8_dprism_vertex_ref_coords (const t8_dprism_t *elem, int vertex, double coords[3]); ``` """ -function t8_mat_init_yrot(mat, angle) - @ccall libt8.t8_mat_init_yrot(mat::Ptr{NTuple{3, Cdouble}}, angle::Cdouble)::Cvoid +function t8_dprism_vertex_ref_coords(elem, vertex, coords) + @ccall libt8.t8_dprism_vertex_ref_coords(elem::Ptr{t8_dprism_t}, vertex::Cint, coords::Ptr{Cdouble})::Cvoid end """ - t8_mat_init_zrot(mat, angle) + t8_dprism_compute_reference_coords(elem, ref_coords, num_coords, out_coords) + +Convert points in the reference space of a prism element to points in the reference space of the tree (level 0) embedded in + +```c++ + [0,1]^3 +``` + +. + +```c++ + [0,1]^3 +``` -Initialize given 3x3 matrix as rotation matrix around the z-axis with given angle. +) # Arguments -* `mat`:\\[in,out\\] 3x3-matrix. -* `angle`:\\[in\\] Rotation angle in radians. +* `elem`:\\[in\\] Pointer to the prism element. +* `ref_coords`:\\[in\\] The reference coordinates in the prism (*num_coords* times +* `num_coords`:\\[in\\] Number of coordinates to evaluate +* `out_coords`:\\[out\\] An array of *num_coords* x 3 x double that will be filled with the reference coordinates of the points on the prism. ### Prototype ```c -static inline void t8_mat_init_zrot (double mat[3][3], const double angle); +void t8_dprism_compute_reference_coords (const t8_dprism_t *elem, const double *ref_coords, const size_t num_coords, double *out_coords); ``` """ -function t8_mat_init_zrot(mat, angle) - @ccall libt8.t8_mat_init_zrot(mat::Ptr{NTuple{3, Cdouble}}, angle::Cdouble)::Cvoid +function t8_dprism_compute_reference_coords(elem, ref_coords, num_coords, out_coords) + @ccall libt8.t8_dprism_compute_reference_coords(elem::Ptr{t8_dprism_t}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid end """ - t8_mat_mult_vec(mat, a, b) + t8_dprism_linear_id(p, level) -Apply matrix-matrix multiplication: b = M*a. +Computes the linear position of a prism in an uniform grid. # Arguments -* `mat`:\\[in\\] 3x3-matrix. -* `a`:\\[in\\] 3-vector. -* `b`:\\[in,out\\] 3-vector. +* `p`:\\[in\\] Prism whose id will be computed. +* `level`:\\[in\\] Refinement level of the prism. +# Returns +Returns the linear position of this prism on a grid. ### Prototype ```c -static inline void t8_mat_mult_vec (const double mat[3][3], const double a[3], double b[3]); +t8_linearidx_t t8_dprism_linear_id (const t8_dprism_t *p, int level); ``` """ -function t8_mat_mult_vec(mat, a, b) - @ccall libt8.t8_mat_mult_vec(mat::Ptr{NTuple{3, Cdouble}}, a::Ptr{Cdouble}, b::Ptr{Cdouble})::Cvoid +function t8_dprism_linear_id(p, level) + @ccall libt8.t8_dprism_linear_id(p::Ptr{t8_dprism_t}, level::Cint)::t8_linearidx_t end """ - t8_mat_mult_mat(A, B, C) + t8_dprism_is_valid(p) -Apply matrix-matrix multiplication: C = A*B. +Query whether all entries of a prism are in valid ranges. A prism is valid if and only if its triangle and line member are valid. # Arguments -* `A`:\\[in\\] 3x3-matrix. -* `B`:\\[in\\] 3x3-matrix. -* `C`:\\[in,out\\] 3x3-matrix. +* `p`:\\[in\\] prism to be considered. +# Returns +True, if *p* is a valid prism and it is safe to call any function in this file on *p*. False otherwise. ### Prototype ```c -static inline void t8_mat_mult_mat (const double A[3][3], const double B[3][3], double C[3][3]); +int t8_dprism_is_valid (const t8_dprism_t *p); ``` """ -function t8_mat_mult_mat(A, B, C) - @ccall libt8.t8_mat_mult_mat(A::Ptr{NTuple{3, Cdouble}}, B::Ptr{NTuple{3, Cdouble}}, C::Ptr{NTuple{3, Cdouble}})::Cvoid +function t8_dprism_is_valid(p) + @ccall libt8.t8_dprism_is_valid(p::Ptr{t8_dprism_t})::Cint end +"""The type of a tetrahedron designates its position relative to the surrounding cube.""" +const t8_dtet_type_t = Int8 + +"""The coordinates of a tetrahedron are integers relative to the maximum refinement.""" +const t8_dtet_coord_t = Int32 + """ - t8_refcount_init(rc) + t8_dtet -Initialize a reference counter to 1. It is legal if its status prior to this call is undefined. +This data type stores a tetrahedron. -# Arguments -* `rc`:\\[out\\] The reference counter is set to one by this call. -### Prototype -```c -void t8_refcount_init (t8_refcount_t *rc); -``` +| Field | Note | +| :---- | :------------------------------------------------------------------------ | +| level | The refinement level of the tetrahedron relative to the root at level 0. | +| type | Type of the tetrahedron in 0, ..., 5. | +| x | The x integer coordinate of the anchor node. | +| y | The y integer coordinate of the anchor node. | +| z | The z integer coordinate of the anchor node. | """ -function t8_refcount_init(rc) - @ccall libt8.t8_refcount_init(rc::Ptr{t8_refcount_t})::Cvoid +struct t8_dtet + level::Int8 + type::t8_dtet_type_t + x::t8_dtet_coord_t + y::t8_dtet_coord_t + z::t8_dtet_coord_t end -""" - t8_refcount_new() +"""This data type stores a tetrahedron.""" +const t8_dtet_t = t8_dtet -Create a new reference counter with count initialized to 1. Equivalent to calling [`t8_refcount_init`](@ref) on a newly allocated refcount\\_t. It is mandatory to free this with t8_refcount_destroy. +"""The coordinates of a pyramid are integers relative to the maximum refinement.""" +const t8_dpyramid_coord_t = Int32 -# Returns -An allocated reference counter whose count has been set to one. -### Prototype -```c -t8_refcount_t * t8_refcount_new (void); -``` -""" -function t8_refcount_new() - @ccall libt8.t8_refcount_new()::Ptr{t8_refcount_t} -end +"""The type of pyramid in 0, ...,7. The first 6 types describe tetrahedra. Type 6 is an upward facing pyramid. Type 7 is a downward facing pyramid.""" +const t8_dpyramid_type_t = Int8 """ - t8_refcount_destroy(rc) + t8_dpyramid -Destroy a reference counter that we allocated with t8_refcount_new. Its reference count must have decreased to zero. +This data type stores a pyramid. The coordinates, the level and the type of a pyramid are stored in the tet-struct *pyramid*. Level, at which the shape switches from tet, to pyra. -1 if not computed for a pyramid with the shape of a tet undefined, if the pyramid has the shape of a pyramid. -# Arguments -* `rc`:\\[in,out\\] Allocated, formerly valid reference counter. -### Prototype -```c -void t8_refcount_destroy (t8_refcount_t *rc); -``` +| Field | Note | +| :-------------------------- | :----------------------------------------------------- | +| pyramid | Coordinates, level and type | +| switch\\_shape\\_at\\_level | Level, at which the shape switches from tet, to pyra. | """ -function t8_refcount_destroy(rc) - @ccall libt8.t8_refcount_destroy(rc::Ptr{t8_refcount_t})::Cvoid +struct t8_dpyramid + pyramid::t8_dtet_t + switch_shape_at_level::Int8 end -# no prototype is found for this function at t8_version.h:67:1, please use with caution +"""This data type stores a pyramid. The coordinates, the level and the type of a pyramid are stored in the tet-struct *pyramid*. Level, at which the shape switches from tet, to pyra. -1 if not computed for a pyramid with the shape of a tet undefined, if the pyramid has the shape of a pyramid.""" +const t8_dpyramid_t = t8_dpyramid + """ - t8_get_package_string() + t8_dpyramid_init_linear_id(p, level, id) -Return the package string of t8code. This string has the format "t8 version\\_number". +Initialize a pyramid as the pyramid with a given global id in a uniform refinement of a given level. * -# Returns -The version string of t8code. +# Arguments +* `p`:\\[in,out\\] Existing pyramid whose data will be filled. +* `level`:\\[in\\] level of uniform grid to be considered. +* `id`:\\[in\\] Index to be considered. ### Prototype ```c -const char* t8_get_package_string (); +void t8_dpyramid_init_linear_id (t8_dpyramid_t *p, const int level, t8_linearidx_t id); ``` """ -function t8_get_package_string() - @ccall libt8.t8_get_package_string()::Cstring +function t8_dpyramid_init_linear_id(p, level, id) + @ccall libt8.t8_dpyramid_init_linear_id(p::Ptr{t8_dpyramid_t}, level::Cint, id::t8_linearidx_t)::Cvoid end -# no prototype is found for this function at t8_version.h:73:1, please use with caution """ - t8_get_version_number() + t8_dpyramid_get_level(p) -Return the version number of t8code as a string. +Compute the level of a pyramid. +# Arguments +* `p`:\\[in\\] Pyramid whose level is computed. # Returns -The version number of t8code as a string. +The level of *p*. ### Prototype ```c -const char* t8_get_version_number (); +int t8_dpyramid_get_level (const t8_dpyramid_t *p); ``` """ -function t8_get_version_number() - @ccall libt8.t8_get_version_number()::Cstring +function t8_dpyramid_get_level(p) + @ccall libt8.t8_dpyramid_get_level(p::Ptr{t8_dpyramid_t})::Cint end -# no prototype is found for this function at t8_version.h:79:1, please use with caution """ - t8_get_version_point_string() + t8_dpyramid_copy(source, dest) -Return the version point string. +Copy the data from source to dest -# Returns -The version point point string. +# Arguments +* `source`:\\[in\\] The source-pyramid +* `dest`:\\[in,out\\] The destination ### Prototype ```c -const char* t8_get_version_point_string (); +void t8_dpyramid_copy (const t8_dpyramid_t *source, t8_dpyramid_t *dest); ``` """ -function t8_get_version_point_string() - @ccall libt8.t8_get_version_point_string()::Cstring +function t8_dpyramid_copy(source, dest) + @ccall libt8.t8_dpyramid_copy(source::Ptr{t8_dpyramid_t}, dest::Ptr{t8_dpyramid_t})::Cvoid end -# no prototype is found for this function at t8_version.h:85:1, please use with caution """ - t8_get_version_major() + t8_dpyramid_linear_id(p, level) -Return the major version number of t8code. +Computes the linear position of a pyramid in an uniform grid. +# Arguments +* `p`:\\[in\\] pyramid whose id will be computed. +* `level`:\\[in\\] The level on which the linear-id should be computed. # Returns -The major version number of t8code. +Returns the linear position of this pyramid on a grid. ### Prototype ```c -int t8_get_version_major (); +t8_linearidx_t t8_dpyramid_linear_id (const t8_dpyramid_t *p, const int level); ``` """ -function t8_get_version_major() - @ccall libt8.t8_get_version_major()::Cint +function t8_dpyramid_linear_id(p, level) + @ccall libt8.t8_dpyramid_linear_id(p::Ptr{t8_dpyramid_t}, level::Cint)::t8_linearidx_t end -# no prototype is found for this function at t8_version.h:91:1, please use with caution """ - t8_get_version_minor() + t8_dpyramid_child(elem, child_id, child) -Return the minor version number of t8code. +Compute the child\\_id-th child in Morton order of a pyramid. -# Returns -The minor version number of t8code. +# Arguments +* `elem`:\\[in\\] Input pyramid. +* `child_id`:\\[in,out\\] The id of the child, 0..7 in Morton order. +* `child`:\\[out\\] Existing pyramid whose data will be filled with the date of t's child\\_id-th child. ### Prototype ```c -int t8_get_version_minor (); +void t8_dpyramid_child (const t8_dpyramid_t *elem, const int child_id, t8_dpyramid_t *child); ``` """ -function t8_get_version_minor() - @ccall libt8.t8_get_version_minor()::Cint +function t8_dpyramid_child(elem, child_id, child) + @ccall libt8.t8_dpyramid_child(elem::Ptr{t8_dpyramid_t}, child_id::Cint, child::Ptr{t8_dpyramid_t})::Cvoid end -# no prototype is found for this function at t8_version.h:97:1, please use with caution """ - t8_get_version_patch() + t8_dpyramid_children(p, c) -Return the patch version number of t8code. +Compute the children of a pyramid, array version -# Returns -The patch version number of t8code. +# Arguments +* `p`:\\[in\\] Input pyramid +* `c`:\\[in,out\\] Pointers to the computed children in Morton order ### Prototype ```c -int t8_get_version_patch (); +void t8_dpyramid_children (const t8_dpyramid_t *p, t8_dpyramid_t **c); ``` """ -function t8_get_version_patch() - @ccall libt8.t8_get_version_patch()::Cint +function t8_dpyramid_children(p, c) + @ccall libt8.t8_dpyramid_children(p::Ptr{t8_dpyramid_t}, c::Ptr{Ptr{t8_dpyramid_t}})::Cvoid end """ - getdelim(lineptr, n, delimiter, stream) + t8_dpyramid_children_at_face(p, face, children, num_children, child_indices) + +Given a pyramid and a face, compute all children touching this face +# Arguments +* `p`:\\[in\\] Input pyramid +* `face`:\\[in\\] The face to compute the children at +* `children`:\\[in,out\\] The children of *p* at *face* +* `num_children`:\\[in\\] The number of children at this face +* `child_indices`:\\[in,out\\] An array to be filled with the local-ids of the children. ### Prototype ```c -static ssize_t getdelim (char **lineptr, size_t *n, int delimiter, FILE *stream); +void t8_dpyramid_children_at_face (const t8_dpyramid_t *p, const int face, t8_dpyramid_t *children[], const int num_children, int *child_indices); ``` """ -function getdelim(lineptr, n, delimiter, stream) - @ccall libt8.getdelim(lineptr::Ptr{Cstring}, n::Ptr{Cint}, delimiter::Cint, stream::Ptr{Cint})::Cint +function t8_dpyramid_children_at_face(p, face, children, num_children, child_indices) + @ccall libt8.t8_dpyramid_children_at_face(p::Ptr{t8_dpyramid_t}, face::Cint, children::Ptr{Ptr{t8_dpyramid_t}}, num_children::Cint, child_indices::Ptr{Cint})::Cvoid end """ - getline(lineptr, n, stream) + t8_dpyramid_face_child_face(p, face, face_child) + +Given a face of a pyramid and a child number of a child of that face, return the face number of the child of the pyramid that matches the child face. +# Arguments +* `p`:\\[in\\] Input pyramid +* `face`:\\[in\\] A face of *p* +* `face_child`:\\[in\\] A number specifying a child on the *face* +# Returns +The number of the face of the child *face_child* ### Prototype ```c -static ssize_t getline (char **lineptr, size_t *n, FILE *stream); +int t8_dpyramid_face_child_face (const t8_dpyramid_t *p, const int face, const int face_child); ``` """ -function getline(lineptr, n, stream) - @ccall libt8.getline(lineptr::Ptr{Cstring}, n::Ptr{Cint}, stream::Ptr{Cint})::Cint +function t8_dpyramid_face_child_face(p, face, face_child) + @ccall libt8.t8_dpyramid_face_child_face(p::Ptr{t8_dpyramid_t}, face::Cint, face_child::Cint)::Cint end """ - strsep(stringp, delim) - -Extract token from string up to a given delimiter. + t8_dpyramid_face_shape(pyra, face) -For a full description see https://linux.die.net/man/3/[`strsep`](@ref) +Given the facenumber of a pyramid, return the shape of the face +# Arguments +* `pyra`:\\[in\\] Input pyramid +* `face`:\\[in\\] The facenumber +# Returns +the shape of the face ### Prototype ```c -static char * strsep (char **stringp, const char *delim); +t8_element_shape_t t8_dpyramid_face_shape (const t8_dpyramid_t *pyra, int face); ``` """ -function strsep(stringp, delim) - @ccall libt8.strsep(stringp::Ptr{Cstring}, delim::Cstring)::Cstring +function t8_dpyramid_face_shape(pyra, face) + @ccall libt8.t8_dpyramid_face_shape(pyra::Ptr{t8_dpyramid_t}, face::Cint)::t8_element_shape_t end """ - t8_scheme_ref(scheme) + t8_dpyramid_get_face_corner(pyra, face, corner) -Increase the reference counter of a scheme. +Returns the corner number of a pyramid given a face of a pyramid and a corner number regarding that face. # Arguments -* `scheme`:\\[in,out\\] On input, this scheme must be alive, that is, exist with positive reference count. +* `pyra`:\\[in\\] Input pyramid +* `face`:\\[in\\] The facenumber of a face of *pyra* +* `corner`:\\[in\\] The cornernumber of a corner of *face* +# Returns +The cornernumber of *pyra* ### Prototype ```c -void t8_scheme_ref (t8_scheme_c *scheme); +int t8_dpyramid_get_face_corner (const t8_dpyramid_t *pyra, int face, int corner); ``` """ -function t8_scheme_ref(scheme) - @ccall libt8.t8_scheme_ref(scheme::Ptr{t8_scheme_c})::Cvoid +function t8_dpyramid_get_face_corner(pyra, face, corner) + @ccall libt8.t8_dpyramid_get_face_corner(pyra::Ptr{t8_dpyramid_t}, face::Cint, corner::Cint)::Cint end """ - t8_scheme_unref(pscheme) + t8_dpyramid_boundary_face(p, face, boundary) -Decrease the reference counter of a scheme. If the counter reaches zero, this scheme is destroyed. +Given a boundary element and a facenumber of this element, compute the boundary face # Arguments -* `pscheme`:\\[in,out\\] On input, the scheme pointed to must exist with positive reference count. If the reference count reaches zero, the scheme is destroyed and this pointer set to NULL. Otherwise, the pointer is not changed and the scheme is not modified in other ways. +* `p`:\\[in\\] Input pyramid +* `face`:\\[in\\] The face number of an element +* `boundary`:\\[in,out\\] The boundary face ### Prototype ```c -void t8_scheme_unref (t8_scheme_c **pscheme); +void t8_dpyramid_boundary_face (const t8_dpyramid_t *p, const int face, t8_element_t *boundary); ``` """ -function t8_scheme_unref(pscheme) - @ccall libt8.t8_scheme_unref(pscheme::Ptr{Ptr{t8_scheme_c}})::Cvoid +function t8_dpyramid_boundary_face(p, face, boundary) + @ccall libt8.t8_dpyramid_boundary_face(p::Ptr{t8_dpyramid_t}, face::Cint, boundary::Ptr{t8_element_t})::Cvoid end """ - t8_element_get_element_size(scheme, tree_class) + t8_dpyramid_extrude_face(face, p, root_face) -Return the size of any element of a given class. +Given a boundary face inside the root pyramids's face construct the element inside the root pyramid that has the given face as a face. +# Arguments +* `face`:\\[in\\] A face element. +* `p`:\\[in,out\\] An allocated element. The entries will be filled with the data of the element that has *face* as a face and lies within the root tree. +* `root_face`:\\[in\\] The index of the face of the root tree in which *face* lies. # Returns -The size of an element of class **ts**. We provide a default implementation of this routine that should suffice for most use cases. +The face number of the face of *p* that coincides with *face*. ### Prototype ```c -size_t t8_element_get_element_size (const t8_scheme_c *scheme, const t8_eclass_t tree_class); +int t8_dpyramid_extrude_face (const t8_element_t *face, t8_dpyramid_t *p, const int root_face); ``` """ -function t8_element_get_element_size(scheme, tree_class) - @ccall libt8.t8_element_get_element_size(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Csize_t +function t8_dpyramid_extrude_face(face, p, root_face) + @ccall libt8.t8_dpyramid_extrude_face(face::Ptr{t8_element_t}, p::Ptr{t8_dpyramid_t}, root_face::Cint)::Cint end """ - t8_element_refines_irregular(scheme, tree_class) + t8_dpyramid_compare(p1, p2) -Returns true, if there is one element in the tree, that does not refine into 2^dim children. Returns false otherwise. +Compare two elements. returns negative if p1 < p2, zero if p1 equals p2 and positive if p1 > p2. If p2 is a copy of p1 then the elements are equal. +# Arguments +* `p1`:\\[in\\] A pyramid +* `p2`:\\[in\\] Another pyramid +# Returns +an integer describing which pyramid is larger. ### Prototype ```c -int t8_element_refines_irregular (const t8_scheme_c *scheme, const t8_eclass_t tree_class); +int t8_dpyramid_compare (const t8_dpyramid_t *p1, const t8_dpyramid_t *p2); ``` """ -function t8_element_refines_irregular(scheme, tree_class) - @ccall libt8.t8_element_refines_irregular(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Cint +function t8_dpyramid_compare(p1, p2) + @ccall libt8.t8_dpyramid_compare(p1::Ptr{t8_dpyramid_t}, p2::Ptr{t8_dpyramid_t})::Cint end """ - t8_element_get_maxlevel(scheme, tree_class) + t8_dpyramid_equal(elem1, elem2) -Return the maximum allowed level for any element of a given class. +Check if two elements are equal. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. +* `elem1`:\\[in\\] The first element. +* `elem2`:\\[in\\] The second element. # Returns -The maximum allowed level for elements of class **ts**. +1 if the elements are equal, 0 if they are not equal ### Prototype ```c -int t8_element_get_maxlevel (const t8_scheme_c *scheme, const t8_eclass_t tree_class); +int t8_dpyramid_equal (const t8_dpyramid_t *elem1, const t8_dpyramid_t *elem2); ``` """ -function t8_element_get_maxlevel(scheme, tree_class) - @ccall libt8.t8_element_get_maxlevel(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Cint +function t8_dpyramid_equal(elem1, elem2) + @ccall libt8.t8_dpyramid_equal(elem1::Ptr{t8_dpyramid_t}, elem2::Ptr{t8_dpyramid_t})::Cint end """ - t8_element_get_level(scheme, tree_class, element) + t8_dpyramid_is_family(fam) -Return the level of an element. +Check whether a collection of 10 pyramids is a family in Morton order. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. +* `fam`:\\[in\\] A collection of pyramids # Returns -The level of *element*. +Nonzero if *fam* is a family of pyramids ### Prototype ```c -int t8_element_get_level (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); +int t8_dpyramid_is_family (t8_dpyramid_t **fam); ``` """ -function t8_element_get_level(scheme, tree_class, element) - @ccall libt8.t8_element_get_level(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint +function t8_dpyramid_is_family(fam) + @ccall libt8.t8_dpyramid_is_family(fam::Ptr{Ptr{t8_dpyramid_t}})::Cint end """ - t8_element_copy(scheme, tree_class, source, dest) - -Copy all entries of **source** to **dest**. **dest** must be an existing element. No memory is allocated by this function. - -!!! note + t8_dpyramid_is_root_boundary(p, face) - *source* and *dest* may point to the same element. +Compute whether a given pyramid shares a given face with its root tree. # Arguments -* `scheme`:\\[in\\] Implementation of a class scheme. -* `tree_class`:\\[in\\] The eclass of the current tree. -* `source`:\\[in\\] The element whose entries will be copied to **dest**. -* `dest`:\\[in,out\\] This element's entries will be overwritten with the entries of **source**. +* `p`:\\[in\\] The input pyramid +* `face`:\\[in\\] A face of *p* +# Returns +True, if *is* a subface of the pyramid root element. ### Prototype ```c -void t8_element_copy (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *source, t8_element_t *dest); +int t8_dpyramid_is_root_boundary (const t8_dpyramid_t *p, const int face); ``` """ -function t8_element_copy(scheme, tree_class, source, dest) - @ccall libt8.t8_element_copy(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, source::Ptr{t8_element_t}, dest::Ptr{t8_element_t})::Cvoid +function t8_dpyramid_is_root_boundary(p, face) + @ccall libt8.t8_dpyramid_is_root_boundary(p::Ptr{t8_dpyramid_t}, face::Cint)::Cint end """ - t8_element_compare(scheme, tree_class, elem1, elem2) + t8_dpyramid_face_neighbor_inside(p, neigh, face, neigh_face) -Compare two elements with respect to the scheme. +Compute the neighbor of p along a given face and the number of the dual face if the neighbor is inside the root pyramid. Return 0 if the neighbor is not inside, 1 ow. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `elem1`:\\[in\\] The first element. -* `elem2`:\\[in\\] The second element. -# Returns -negative if elem1 < elem2, zero if elem1 equals elem2 and positive if elem1 > elem2. If elem2 is a copy of elem1 then the elements are equal. +* `p`:\\[in\\] Input pyramid +* `neigh`:\\[in,out\\] The neighbor of *p* +* `face`:\\[in\\] The face of *p* along which *neigh* is computed +* `neigh_face`:\\[in,out\\] The dual face ### Prototype ```c -int t8_element_compare (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *elem1, const t8_element_t *elem2); +int t8_dpyramid_face_neighbor_inside (const t8_dpyramid_t *p, t8_dpyramid_t *neigh, const int face, int *neigh_face); ``` """ -function t8_element_compare(scheme, tree_class, elem1, elem2) - @ccall libt8.t8_element_compare(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem1::Ptr{t8_element_t}, elem2::Ptr{t8_element_t})::Cint +function t8_dpyramid_face_neighbor_inside(p, neigh, face, neigh_face) + @ccall libt8.t8_dpyramid_face_neighbor_inside(p::Ptr{t8_dpyramid_t}, neigh::Ptr{t8_dpyramid_t}, face::Cint, neigh_face::Ptr{Cint})::Cint end """ - t8_element_is_equal(scheme, tree_class, elem1, elem2) + t8_dpyramid_child_id(p) -Check if two elements are equal. +Compute the position of the ancestor of this child at level *level* within its siblings. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `elem1`:\\[in\\] The first element. -* `elem2`:\\[in\\] The second element. +* `p`:\\[in\\] pyramid to be considered. # Returns -1 if the elements are equal, 0 if they are not equal +Returns its child id in 0..9 ### Prototype ```c -int t8_element_is_equal (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *elem1, const t8_element_t *elem2); +int t8_dpyramid_child_id (const t8_dpyramid_t *p); ``` """ -function t8_element_is_equal(scheme, tree_class, elem1, elem2) - @ccall libt8.t8_element_is_equal(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem1::Ptr{t8_element_t}, elem2::Ptr{t8_element_t})::Cint +function t8_dpyramid_child_id(p) + @ccall libt8.t8_dpyramid_child_id(p::Ptr{t8_dpyramid_t})::Cint end """ - element_is_refinable(scheme, tree_class, element) + t8_dpyramid_is_inside_root(p) -Indicates if an element is refinable. Possible reasons for being not refinable could be that the element has reached its max level. +Returns zero if p is not inside root, 1 ow # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element to check. +* `p`:\\[in\\] Pyramid to check # Returns -1 if the element is refinable, 0 otherwise. +0 if p is inside root, 1, ow ### Prototype ```c -int element_is_refinable (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); +int t8_dpyramid_is_inside_root (const t8_dpyramid_t *p); ``` """ -function element_is_refinable(scheme, tree_class, element) - @ccall libt8.element_is_refinable(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint +function t8_dpyramid_is_inside_root(p) + @ccall libt8.t8_dpyramid_is_inside_root(p::Ptr{t8_dpyramid_t})::Cint end """ - t8_element_get_parent(scheme, tree_class, element, parent) + t8_dpyramid_tet_boundary(p, face) -Compute the parent of a given element **element** and store it in **parent**. **parent** needs to be an existing element. No memory is allocated by this function. **element** and **parent** can point to the same element, then the entries of **element** are overwritten by the ones of its parent. +Check, if a tet of type 0 or 3 has a common face with its pyramid-ancestor # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element whose parent will be computed. -* `parent`:\\[in,out\\] This element's entries will be overwritten by those of **element**'s parent. The storage for this element must exist and match the element class of the parent. +* `p`:\\[in\\] input pyramid +* `face`:\\[in\\] A face of *p*. +# Returns +false if they don't share a face, true otherwise ### Prototype ```c -void t8_element_get_parent (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, t8_element_t *parent); +int t8_dpyramid_tet_boundary (const t8_dpyramid_t *p, const int face); ``` """ -function t8_element_get_parent(scheme, tree_class, element, parent) - @ccall libt8.t8_element_get_parent(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, parent::Ptr{t8_element_t})::Cvoid +function t8_dpyramid_tet_boundary(p, face) + @ccall libt8.t8_dpyramid_tet_boundary(p::Ptr{t8_dpyramid_t}, face::Cint)::Cint end """ - t8_element_get_num_siblings(scheme, tree_class, element) + t8_dpyramid_tree_face(p, face) -Compute the number of siblings of an element. That is the number of Children of its parent. +compute if a given element lies on the tree boundary and return the face number of the tree face. If not the return value is arbitrary # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. +* `p`:\\[in\\] pyramid +* `face`:\\[in\\] a face of *p* # Returns -The number of siblings of *element*. Note that this number is >= 1, since we count the element itself as a sibling. +See description ### Prototype ```c -int t8_element_get_num_siblings (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); +int t8_dpyramid_tree_face (const t8_dpyramid_t *p, const int face); ``` """ -function t8_element_get_num_siblings(scheme, tree_class, element) - @ccall libt8.t8_element_get_num_siblings(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint +function t8_dpyramid_tree_face(p, face) + @ccall libt8.t8_dpyramid_tree_face(p::Ptr{t8_dpyramid_t}, face::Cint)::Cint end """ - t8_element_get_sibling(scheme, tree_class, elem, sibid, sibling) + t8_dpyramid_first_descendant(p, desc, level) -Compute a specific sibling of a given element **element** and store it in **sibling**. **sibling** needs to be an existing element. No memory is allocated by this function. **element** and **sibling** can point to the same element, then the entries of **element** are overwritten by the ones of its i-th sibling. +Compute the first descendant of a pyramid at a given level. This is the descendant of the pyramid in a uniform level refinement that has the smallest id. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `elem`:\\[in\\] The element whose sibling will be computed. -* `sibid`:\\[in\\] The id of the sibling computed. -* `sibling`:\\[in,out\\] This element's entries will be overwritten by those of **element**'s sibid-th sibling. The storage for this element must exist and match the element class of the sibling. +* `p`:\\[in\\] pyramid whose descendant is computed. +* `desc`:\\[out\\] Existing pyramid whose data will be filled with the data of *p*'s first descendant on level *level*. +* `level`:\\[in\\] The refinement level. Must be greater than *p*'s refinement level. ### Prototype ```c -void t8_element_get_sibling (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *elem, const int sibid, t8_element_t *sibling); +void t8_dpyramid_first_descendant (const t8_dpyramid_t *p, t8_dpyramid_t *desc, const int level); ``` """ -function t8_element_get_sibling(scheme, tree_class, elem, sibid, sibling) - @ccall libt8.t8_element_get_sibling(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem::Ptr{t8_element_t}, sibid::Cint, sibling::Ptr{t8_element_t})::Cvoid +function t8_dpyramid_first_descendant(p, desc, level) + @ccall libt8.t8_dpyramid_first_descendant(p::Ptr{t8_dpyramid_t}, desc::Ptr{t8_dpyramid_t}, level::Cint)::Cvoid end """ - t8_element_get_num_corners(scheme, tree_class, element) + t8_dpyramid_first_descendant_face(p, face, first_desc, level) -Compute the number of corners of an element. +Construct the first descendant of a pyramid touching a given face # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -# Returns -The number of corners of *element*. +* `p`:\\[in\\] pyramid whose descendant is computed. +* `face`:\\[in\\] The face at which the descendant is computed +* `first_desc`:\\[out\\] Existing pyramid whose data will be filled with the data of *p*'s first descendant on level *level*. +* `level`:\\[in\\] The refinement level. Must be greater than *p*'s refinement level. ### Prototype ```c -int t8_element_get_num_corners (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); +void t8_dpyramid_first_descendant_face (const t8_dpyramid_t *p, const int face, t8_dpyramid_t *first_desc, const int level); ``` """ -function t8_element_get_num_corners(scheme, tree_class, element) - @ccall libt8.t8_element_get_num_corners(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint +function t8_dpyramid_first_descendant_face(p, face, first_desc, level) + @ccall libt8.t8_dpyramid_first_descendant_face(p::Ptr{t8_dpyramid_t}, face::Cint, first_desc::Ptr{t8_dpyramid_t}, level::Cint)::Cvoid end """ - t8_element_get_num_faces(scheme, tree_class, element) + t8_dpyramid_last_descendant(p, desc, level) -Compute the number of faces of an element. - -# Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -# Returns -The number of faces of *element*. +Compute the last descendant of a pyramid at a given level. This is the descendant of the pyramid in a uniform level refinement that has the largest id. + +# Arguments +* `p`:\\[in\\] pyramid whose descendant is computed. +* `desc`:\\[out\\] Existing pyramid whose data will be filled with the data of *p*'s last descendant on level *level*. +* `level`:\\[in\\] The refinement level. Must be greater than *p*'s refinement level. ### Prototype ```c -int t8_element_get_num_faces (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); +void t8_dpyramid_last_descendant (const t8_dpyramid_t *p, t8_dpyramid_t *desc, int level); ``` """ -function t8_element_get_num_faces(scheme, tree_class, element) - @ccall libt8.t8_element_get_num_faces(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint +function t8_dpyramid_last_descendant(p, desc, level) + @ccall libt8.t8_dpyramid_last_descendant(p::Ptr{t8_dpyramid_t}, desc::Ptr{t8_dpyramid_t}, level::Cint)::Cvoid end """ - t8_element_get_max_num_faces(scheme, tree_class, element) + t8_dpyramid_last_descendant_face(p, face, last_desc, level) -Compute the maximum number of faces of a given element and all of its descendants. +Construct the last descendant of a pyramid touching a given face # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -# Returns -The number of faces of *element*. +* `p`:\\[in\\] pyramid whose descendant is computed. +* `face`:\\[in\\] The face at which the descendant is computed +* `last_desc`:\\[out\\] Existing pyramid whose data will be filled with the data of *p*'s first descendant on level *level*. +* `level`:\\[in\\] The refinement level. Must be greater than *p*'s refinement level. ### Prototype ```c -int t8_element_get_max_num_faces (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); +void t8_dpyramid_last_descendant_face (const t8_dpyramid_t *p, const int face, t8_dpyramid_t *last_desc, const int level); ``` """ -function t8_element_get_max_num_faces(scheme, tree_class, element) - @ccall libt8.t8_element_get_max_num_faces(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint +function t8_dpyramid_last_descendant_face(p, face, last_desc, level) + @ccall libt8.t8_dpyramid_last_descendant_face(p::Ptr{t8_dpyramid_t}, face::Cint, last_desc::Ptr{t8_dpyramid_t}, level::Cint)::Cvoid end """ - t8_element_get_num_children(scheme, tree_class, element) + t8_dpyramid_compute_integer_coords(elem, vertex, coords) -Compute the number of children of an element when it is refined. +Compute the coordinates of a vertex of a pyramid. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -# Returns -The number of children of *element*. +* `elem`:\\[in\\] Input pyramid. +* `vertex`:\\[in\\] The number of the vertex. +* `coords`:\\[out\\] An array of 3 [`t8_dpyramid_coord_t`](@ref) that will be filled with the coordinates of the vertex. ### Prototype ```c -int t8_element_get_num_children (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); +void t8_dpyramid_compute_integer_coords (const t8_dpyramid_t *elem, const int vertex, int coords[]); ``` """ -function t8_element_get_num_children(scheme, tree_class, element) - @ccall libt8.t8_element_get_num_children(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint +function t8_dpyramid_compute_integer_coords(elem, vertex, coords) + @ccall libt8.t8_dpyramid_compute_integer_coords(elem::Ptr{t8_dpyramid_t}, vertex::Cint, coords::Ptr{Cint})::Cvoid end """ - t8_get_max_num_children(scheme, tree_class) + t8_dpyramid_parent(p, parent) -Return the max number of children of an eclass. +Compute the parent of a given pyramid # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -# Returns -The max number of children of *element*. +* `p`:\\[in\\] Input pyramid. +* `parent`:\\[out\\] The parent of *p*. ### Prototype ```c -int t8_get_max_num_children (const t8_scheme_c *scheme, const t8_eclass_t tree_class); +void t8_dpyramid_parent (const t8_dpyramid_t *p, t8_dpyramid_t *parent); ``` """ -function t8_get_max_num_children(scheme, tree_class) - @ccall libt8.t8_get_max_num_children(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t)::Cint +function t8_dpyramid_parent(p, parent) + @ccall libt8.t8_dpyramid_parent(p::Ptr{t8_dpyramid_t}, parent::Ptr{t8_dpyramid_t})::Cvoid end """ - t8_element_get_num_face_children(scheme, tree_class, element, face) + t8_dpyramid_num_corners(p) -Compute the number of children of an element's face when the element is refined. +Compute the number of corners of a pyramid. If pyramid has type less than 6, it is actually a tetrahedron. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -* `face`:\\[in\\] A face of *element*. +* `p`:\\[in\\] Input pyramid. # Returns -The number of children of *face* if *element* is to be refined. +The number of corners of p. ### Prototype ```c -int t8_element_get_num_face_children (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face); +int t8_dpyramid_num_corners (const t8_dpyramid_t *p); ``` """ -function t8_element_get_num_face_children(scheme, tree_class, element, face) - @ccall libt8.t8_element_get_num_face_children(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint)::Cint +function t8_dpyramid_num_corners(p) + @ccall libt8.t8_dpyramid_num_corners(p::Ptr{t8_dpyramid_t})::Cint end """ - t8_element_get_face_corner(scheme, tree_class, element, face, corner) - -Return the corner number of an element's face corner. Example quad: 2 x --- x 3 | | | | face 1 0 x --- x 1 Thus for face = 1 the output is: corner=0 : 1, corner=1: 3 + t8_dpyramid_num_children(p) -The order in which the corners must be given is determined by the eclass of *element*: LINE/QUAD/TRIANGLE: No specific order. HEX : In Z-order of the face starting with the lowest corner number. TET : Starting with the lowest corner number counterclockwise as seen from 'outside' of the element. +Compute the number of children of p # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -* `face`:\\[in\\] A face index for *element*. -* `corner`:\\[in\\] A corner index for the face 0 <= *corner* < num\\_face\\_corners. +* `p`:\\[in\\] Input pyramid. # Returns -The corner number of the *corner*-th vertex of *face*. +The number of children of p. ### Prototype ```c -int t8_element_get_face_corner (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face, const int corner); +int t8_dpyramid_num_children (const t8_dpyramid_t *p); ``` """ -function t8_element_get_face_corner(scheme, tree_class, element, face, corner) - @ccall libt8.t8_element_get_face_corner(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint, corner::Cint)::Cint +function t8_dpyramid_num_children(p) + @ccall libt8.t8_dpyramid_num_children(p::Ptr{t8_dpyramid_t})::Cint end """ - t8_element_get_corner_face(scheme, tree_class, element, corner, face) + t8_dpyramid_num_siblings(p) -Compute the face numbers of the faces sharing an element's corner. Example quad: 2 x --- x 3 | | | | face 1 0 x --- x 1 face 2 Thus for corner = 1 the output is: face=0 : 2, face=1: 1 +Compute the number of siblings of p # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -* `corner`:\\[in\\] A corner index for the face. -* `face`:\\[in\\] A face index for *corner*. +* `p`:\\[in\\] Input pyramid # Returns -The face number of the *face*-th face at *corner*. +The number of siblings of p. ### Prototype ```c -int t8_element_get_corner_face (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int corner, const int face); +int t8_dpyramid_num_siblings (const t8_dpyramid_t *p); ``` """ -function t8_element_get_corner_face(scheme, tree_class, element, corner, face) - @ccall libt8.t8_element_get_corner_face(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, corner::Cint, face::Cint)::Cint +function t8_dpyramid_num_siblings(p) + @ccall libt8.t8_dpyramid_num_siblings(p::Ptr{t8_dpyramid_t})::Cint end """ - t8_element_get_child(scheme, tree_class, element, childid, child) + t8_dpyramid_num_faces(p) -Construct the child element of a given number. +Return the number of faces of p # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] This must be a valid element, bigger than maxlevel. -* `childid`:\\[in\\] The number of the child to construct. -* `child`:\\[in,out\\] The storage for this element must exist. On output, a valid element. It is valid to call this function with element = child. +* `p`:\\[in\\] Input pyramid +# Returns +The number of faces of p ### Prototype ```c -void t8_element_get_child (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int childid, t8_element_t *child); +int t8_dpyramid_num_faces (const t8_dpyramid_t *p); ``` """ -function t8_element_get_child(scheme, tree_class, element, childid, child) - @ccall libt8.t8_element_get_child(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, childid::Cint, child::Ptr{t8_element_t})::Cvoid +function t8_dpyramid_num_faces(p) + @ccall libt8.t8_dpyramid_num_faces(p::Ptr{t8_dpyramid_t})::Cint end """ - t8_element_get_children(scheme, tree_class, element, length, c) + t8_dpyramid_max_num_faces(p) -Construct all children of a given element. +Return the maximal number of faces of an element p # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] This must be a valid element, bigger than maxlevel. -* `length`:\\[in\\] The length of the output array *c* must match the number of children. -* `c`:\\[in,out\\] The storage for these *length* elements must exist and match the element class in the children's ordering. On output, all children are valid. It is valid to call this function with element = c[0]. -# See also -t8\\_element\\_num\\_children - +* `p`:\\[in\\] Input pyramid +# Returns +The maximal number of faces of p ### Prototype ```c -void t8_element_get_children (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int length, t8_element_t *c[]); +int t8_dpyramid_max_num_faces (const t8_dpyramid_t *p); ``` """ -function t8_element_get_children(scheme, tree_class, element, length, c) - @ccall libt8.t8_element_get_children(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, length::Cint, c::Ptr{Ptr{t8_element_t}})::Cvoid +function t8_dpyramid_max_num_faces(p) + @ccall libt8.t8_dpyramid_max_num_faces(p::Ptr{t8_dpyramid_t})::Cint end """ - t8_element_get_child_id(scheme, tree_class, element) + t8_dpyramid_face_parent_face(elem, face) -Compute the child id of an element. +Given a face of an element return the face number of the parent of the element that matches the element's face. Or return -1 if no face of the parent matches the face. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] This must be a valid element. +* `elem`:\\[in\\] Input pyramid +* `face`:\\[in\\] a face of *elem* # Returns -The child id of element. +the facenumber of the parent of *elem* matching *face* or -1 ### Prototype ```c -int t8_element_get_child_id (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); +int t8_dpyramid_face_parent_face (const t8_dpyramid_t *elem, const int face); ``` """ -function t8_element_get_child_id(scheme, tree_class, element) - @ccall libt8.t8_element_get_child_id(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cint +function t8_dpyramid_face_parent_face(elem, face) + @ccall libt8.t8_dpyramid_face_parent_face(elem::Ptr{t8_dpyramid_t}, face::Cint)::Cint end """ - t8_element_get_ancestor_id(scheme, tree_class, element, level) + t8_dpyramid_ancestor_id(p, level) -Compute the ancestor id of an element, that is the child id at a given level. +Return the child-id of the ancestor of p at level level # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] This must be a valid element. -* `level`:\\[in\\] A refinement level. Must satisfy *level* < element.level +* `p`:\\[in\\] Input pyramid +* `level`:\\[in\\] The ancestor-level # Returns -The child\\_id of *element* in regard to its *level* ancestor. +The child-id of the ancestor ### Prototype ```c -int t8_element_get_ancestor_id (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int level); +int t8_dpyramid_ancestor_id (const t8_dpyramid_t *p, const int level); ``` """ -function t8_element_get_ancestor_id(scheme, tree_class, element, level) - @ccall libt8.t8_element_get_ancestor_id(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, level::Cint)::Cint +function t8_dpyramid_ancestor_id(p, level) + @ccall libt8.t8_dpyramid_ancestor_id(p::Ptr{t8_dpyramid_t}, level::Cint)::Cint end """ - t8_elements_are_family(scheme, tree_class, fam) + t8_dpyramid_ancestor(pyra, level, ancestor) -Query whether a given set of elements is a family or not. +Compute the ancestor of *pyra* at a given level # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `fam`:\\[in\\] An array of as many elements as an element of class **scheme** has children. -# Returns -Zero if **fam** is not a family, nonzero if it is. +* `pyra`:\\[in\\] Input pyramid +* `level`:\\[in\\] Level of the ancestor to compute +* `ancestor`:\\[in,out\\] Allocated element that will be filled with the data of the ancestor. ### Prototype ```c -int t8_elements_are_family (const t8_scheme_c *scheme, const t8_eclass_t tree_class, t8_element_t *const *fam); +void t8_dpyramid_ancestor (const t8_dpyramid_t *pyra, const int level, t8_dpyramid_t *ancestor); ``` """ -function t8_elements_are_family(scheme, tree_class, fam) - @ccall libt8.t8_elements_are_family(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, fam::Ptr{Ptr{t8_element_t}})::Cint +function t8_dpyramid_ancestor(pyra, level, ancestor) + @ccall libt8.t8_dpyramid_ancestor(pyra::Ptr{t8_dpyramid_t}, level::Cint, ancestor::Ptr{t8_dpyramid_t})::Cvoid end """ - t8_element_get_nca(scheme, tree_class, elem1, elem2, nca) + t8_dpyramid_type_at_level(p, level) -Compute the nearest common ancestor of two elements. That is, the element with highest level that still has both given elements as descendants. +Compute the type of a pyramid at a given level. Starting from its own level, we iterate over the levels and compute the type of this level. If p is a tetrahedron, we compute it in a tetrahedral fashion up unto the last level where p is a tet and continue in a pyramidal fashion # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `elem1`:\\[in\\] The first of the two input elements. -* `elem2`:\\[in\\] The second of the two input elements. -* `nca`:\\[in,out\\] The storage for this element must exist and match the element class of the child. On output the unique nearest common ancestor of **elem1** and **elem2**. +* `p`:\\[in\\] Input pyramid +* `level`:\\[in\\] The level at which the type is computed +# Returns +The type of *p* at level *level*. ### Prototype ```c -void t8_element_get_nca (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *elem1, const t8_element_t *elem2, t8_element_t *nca); +int t8_dpyramid_type_at_level (const t8_dpyramid_t *p, const int level); ``` """ -function t8_element_get_nca(scheme, tree_class, elem1, elem2, nca) - @ccall libt8.t8_element_get_nca(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem1::Ptr{t8_element_t}, elem2::Ptr{t8_element_t}, nca::Ptr{t8_element_t})::Cvoid +function t8_dpyramid_type_at_level(p, level) + @ccall libt8.t8_dpyramid_type_at_level(p::Ptr{t8_dpyramid_t}, level::Cint)::Cint end """ - t8_element_get_face_shape(scheme, tree_class, element, face) + t8_dpyramid_shape(p) -Compute the shape of the face of an element. +Returns the shape of the pyramid (pyramid or tetrahedron) # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -* `face`:\\[in\\] A face of *element*. +* `p`:\\[in\\] Input pyramid. # Returns -The element shape of the face. I.e. T8\\_ECLASS\\_LINE for quads, T8\\_ECLASS\\_TRIANGLE for tets and depending on the face number either T8\\_ECLASS\\_QUAD or T8\\_ECLASS\\_TRIANGLE for prisms. +The eclass of the element ### Prototype ```c -t8_element_shape_t t8_element_get_face_shape (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face); +t8_element_shape_t t8_dpyramid_shape (const t8_dpyramid_t *p); ``` """ -function t8_element_get_face_shape(scheme, tree_class, element, face) - @ccall libt8.t8_element_get_face_shape(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint)::t8_element_shape_t +function t8_dpyramid_shape(p) + @ccall libt8.t8_dpyramid_shape(p::Ptr{t8_dpyramid_t})::t8_element_shape_t end """ - t8_element_get_children_at_face(scheme, tree_class, element, face, children, num_children, child_indices) + t8_dpyramid_successor(elem, s, level) -Given an element and a face of the element, compute all children of the element that touch the face. +Computes the successor of a pyramid in a uniform grid of level *level*. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -* `face`:\\[in\\] A face of *element*. -* `children`:\\[in,out\\] Allocated elements, in which the children of *element* that share a face with *face* are stored. They will be stored in order of their linear id. -* `num_children`:\\[in\\] The number of elements in *children*. Must match the number of children that touch *face*. t8_scheme::element_get_num_face_children -* `child_indices`:\\[in,out\\] If not NULL, an array of num\\_children integers must be given, on output its i-th entry is the child\\_id of the i-th face\\_child. It is valid to call this function with element = children[0]. +* `elem`:\\[in\\] pyramid whose id will be computed. +* `s`:\\[in,out\\] Existing pyramid whose data will be filled with the data of *l*'s successor on level *level*. +* `level`:\\[in\\] level of uniform grid to be considered. ### Prototype ```c -void t8_element_get_children_at_face (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face, t8_element_t *children[], const int num_children, int *child_indices); +void t8_dpyramid_successor (const t8_dpyramid_t *elem, t8_dpyramid_t *s, const int level); ``` """ -function t8_element_get_children_at_face(scheme, tree_class, element, face, children, num_children, child_indices) - @ccall libt8.t8_element_get_children_at_face(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint, children::Ptr{Ptr{t8_element_t}}, num_children::Cint, child_indices::Ptr{Cint})::Cvoid +function t8_dpyramid_successor(elem, s, level) + @ccall libt8.t8_dpyramid_successor(elem::Ptr{t8_dpyramid_t}, s::Ptr{t8_dpyramid_t}, level::Cint)::Cvoid end """ - t8_element_face_get_child_face(scheme, tree_class, element, face, face_child) + t8_dpyramid_vertex_reference_coords(elem, vertex, coords) -Given a face of an element and a child number of a child of that face, return the face number of the child of the element that matches the child face. +Compute the reference coordinates of a vertex of a pyramid when the tree (level 0 triangle) is embedded in ```c++ - x ---- x x x x ---- x - | | | | | | | <-- f - | | | x | x--x - | | | | | - x ---- x x x ---- x - element face face_child Returns the face number f + [0,1]^3 ``` +. + # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -* `face`:\\[in\\] Then number of the face. -* `face_child`:\\[in\\] A number 0 <= *face_child* < num\\_face\\_children, specifying a child of *element* that shares a face with *face*. These children are counted in linear order. This coincides with the order of children from a call to t8_scheme::element_get_children_at_face. -# Returns -The face number of the face of a child of *element* that coincides with *face_child*. +* `elem`:\\[in\\] Input pyramid. +* `vertex`:\\[in\\] The number of the vertex. +* `coords`:\\[out\\] An array of 3 double that will be filled with the reference coordinates of the vertex. ### Prototype ```c -int t8_element_face_get_child_face (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face, const int face_child); +void t8_dpyramid_vertex_reference_coords (const t8_dpyramid_t *elem, const int vertex, double coords[]); ``` """ -function t8_element_face_get_child_face(scheme, tree_class, element, face, face_child) - @ccall libt8.t8_element_face_get_child_face(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint, face_child::Cint)::Cint +function t8_dpyramid_vertex_reference_coords(elem, vertex, coords) + @ccall libt8.t8_dpyramid_vertex_reference_coords(elem::Ptr{t8_dpyramid_t}, vertex::Cint, coords::Ptr{Cdouble})::Cvoid end """ - t8_element_face_get_parent_face(scheme, tree_class, element, face) + t8_dpyramid_compute_reference_coords(elem, ref_coords, num_coords, out_coords) -Given a face of an element return the face number of the parent of the element that matches the element's face. Or return -1 if no face of the parent matches the face. +Convert points in the reference space of a pyramid element to points in the reference space of the tree (level 0) embedded in -!!! note +```c++ + [0,1]^3 +``` - For the root element this function always returns *face*. +. + +```c++ + [0,1]^3 +``` + +) # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -* `face`:\\[in\\] Then number of the face. -# Returns -If *face* of *element* is also a face of *element*'s parent, the face number of this face. Otherwise -1. +* `elem`:\\[in\\] Input pyramid. +* `ref_coords`:\\[in\\] The reference coordinates in the pyramid (*num_coords* times +* `num_coords`:\\[in\\] Number of coordinates to evaluate +* `out_coords`:\\[out\\] An array of *num_coords* x 3 x double that will be filled with the reference coordinates of the points on the pyramid. ### Prototype ```c -int t8_element_face_get_parent_face (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face); +void t8_dpyramid_compute_reference_coords (const t8_dpyramid_t *elem, const double *ref_coords, const size_t num_coords, double *out_coords); ``` """ -function t8_element_face_get_parent_face(scheme, tree_class, element, face) - @ccall libt8.t8_element_face_get_parent_face(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint)::Cint +function t8_dpyramid_compute_reference_coords(elem, ref_coords, num_coords, out_coords) + @ccall libt8.t8_dpyramid_compute_reference_coords(elem::Ptr{t8_dpyramid_t}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid end """ - t8_element_get_tree_face(scheme, tree_class, element, face) + t8_dpyramid_nearest_common_ancestor(pyra1, pyra2, nca) -Given an element and a face of this element. If the face lies on the tree boundary, return the face number of the tree face. If not the return value is arbitrary. +Compute the nearest common ancestor of two elements # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element. -* `face`:\\[in\\] The index of a face of *element*. -# Returns -The index of the tree face that *face* is a subface of, if *face* is on a tree boundary. Any arbitrary integer if *is* not at a tree boundary. +* `pyra1`:\\[in\\] The first pyramid +* `pyra2`:\\[in\\] The second pyramid +* `nca`:\\[in,out\\] Existing pyramid whose data will be filled with the data of *pyra1* and *pyra2* nearest common ancestor. ### Prototype ```c -int t8_element_get_tree_face (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face); +void t8_dpyramid_nearest_common_ancestor (const t8_dpyramid_t *pyra1, const t8_dpyramid_t *pyra2, t8_dpyramid_t *nca); ``` """ -function t8_element_get_tree_face(scheme, tree_class, element, face) - @ccall libt8.t8_element_get_tree_face(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint)::Cint +function t8_dpyramid_nearest_common_ancestor(pyra1, pyra2, nca) + @ccall libt8.t8_dpyramid_nearest_common_ancestor(pyra1::Ptr{t8_dpyramid_t}, pyra2::Ptr{t8_dpyramid_t}, nca::Ptr{t8_dpyramid_t})::Cvoid end """ - t8_element_transform_face(scheme, tree_class, elem1, elem2, orientation, sign, is_smaller_face) + t8_dpyramid_is_valid(p) -Suppose we have two trees that share a common face f. Given an element e that is a subface of f in one of the trees and given the orientation of the tree connection, construct the face element of the respective tree neighbor that logically coincides with e but lies in the coordinate system of the neighbor tree. +Query whether all entries of a pyramid are in valid ranges. A pyramid is valid if and only if its triangle and line member are valid. -!!! note +# Arguments +* `p`:\\[in\\] pyramid to be considered. +# Returns +True, if *p* is a valid pyramid and it is safe to call any function in this file on *p*. False otherwise. +### Prototype +```c +int t8_dpyramid_is_valid (const t8_dpyramid_t *p); +``` +""" +function t8_dpyramid_is_valid(p) + @ccall libt8.t8_dpyramid_is_valid(p::Ptr{t8_dpyramid_t})::Cint +end - *elem1* and *elem2* may point to the same element. +""" + t8_dtet_compute_integer_coords(elem, vertex, coordinates) -# Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `elem1`:\\[in\\] The face element. -* `elem2`:\\[in,out\\] On return the face element *elem1* with respect to the coordinate system of the other tree. -* `orientation`:\\[in\\] The orientation of the tree-tree connection. -* `sign`:\\[in\\] Depending on the topological orientation of the two tree faces, either 0 (both faces have opposite orientation) or 1 (both faces have the same top. orientation). t8_eclass_face_orientation -* `is_smaller_face`:\\[in\\] Flag to declare whether *elem1* belongs to the smaller face. A face f of tree T is smaller than f' of T' if either the eclass of T is smaller or if the classes are equal and f tet2 ### Prototype ```c -int t8_element_is_root_boundary (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int face); +int t8_dtet_compare (const t8_dtet_t *tet1, const t8_dtet_t *tet2); ``` """ -function t8_element_is_root_boundary(scheme, tree_class, element, face) - @ccall libt8.t8_element_is_root_boundary(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, face::Cint)::Cint +function t8_dtet_compare(tet1, tet2) + @ccall libt8.t8_dtet_compare(tet1::Ptr{t8_dtet_t}, tet2::Ptr{t8_dtet_t})::Cint end """ - t8_element_get_face_neighbor_inside(scheme, tree_class, element, neigh, face, neigh_face) + t8_dtet_equal(tet1, tet2) -Construct the face neighbor of a given element if this face neighbor is inside the root tree. Return 0 otherwise. +Check if two elements are equal. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element to be considered. -* `neigh`:\\[in,out\\] If the face neighbor of *element* along *face* is inside the root tree, this element's data is filled with the data of the face neighbor. Otherwise the data can be modified arbitrarily. -* `face`:\\[in\\] The number of the face along which the neighbor should be constructed. -* `neigh_face`:\\[out\\] The number of *face* as viewed from *neigh*. An arbitrary value, if the neighbor is not inside the root tree. +* `tet1`:\\[in\\] The first element. +* `tet2`:\\[in\\] The second element. # Returns -True if *neigh* is inside the root tree. False if not. In this case *neigh*'s data can be arbitrary on output. +1 if the elements are equal, 0 if they are not equal ### Prototype ```c -int t8_element_get_face_neighbor_inside (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, t8_element_t *neigh, const int face, int *neigh_face); +int t8_dtet_equal (const t8_dtet_t *tet1, const t8_dtet_t *tet2); ``` """ -function t8_element_get_face_neighbor_inside(scheme, tree_class, element, neigh, face, neigh_face) - @ccall libt8.t8_element_get_face_neighbor_inside(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, neigh::Ptr{t8_element_t}, face::Cint, neigh_face::Ptr{Cint})::Cint +function t8_dtet_equal(tet1, tet2) + @ccall libt8.t8_dtet_equal(tet1::Ptr{t8_dtet_t}, tet2::Ptr{t8_dtet_t})::Cint end """ - t8_element_get_shape(scheme, tree_class, element) + t8_dtet_parent(tet, parent) -Return the shape of an allocated element according its type. For example, a child of an element can be an element of a different shape and has to be handled differently - according to its shape. +Compute the parent of a tetrahedron. + +!!! note + + *t* may point to the same tetrahedron as *parent*. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element to be considered -# Returns -The shape of the element as an eclass +* `tet`:\\[in\\] Input tetrahedron. +* `parent`:\\[in,out\\] Existing tetrahedron whose data will be filled with the data of *tet*'s parent. ### Prototype ```c -t8_element_shape_t t8_element_get_shape (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element); +void t8_dtet_parent (const t8_dtet_t *tet, t8_dtet_t *parent); ``` """ -function t8_element_get_shape(scheme, tree_class, element) - @ccall libt8.t8_element_get_shape(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::t8_element_shape_t +function t8_dtet_parent(tet, parent) + @ccall libt8.t8_dtet_parent(tet::Ptr{t8_dtet_t}, parent::Ptr{t8_dtet_t})::Cvoid end """ - t8_element_set_linear_id(scheme, tree_class, element, level, id) + t8_dtet_ancestor(tet, level, ancestor) -Initialize the entries of an allocated element according to a given linear id in a uniform refinement. +Compute the ancestor of a tetrahedron at a given level. + +!!! note + + The tetrahedron *ancestor* may point to the same tetrahedron as *tet*. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in,out\\] The element whose entries will be set. -* `level`:\\[in\\] The level of the uniform refinement to consider. -* `id`:\\[in\\] The linear id. id must fulfil 0 <= id < 'number of leaves in the uniform refinement' +* `tet`:\\[in\\] Input tetrahedron. +* `level`:\\[in\\] A smaller level than *tet*. +* `ancestor`:\\[in,out\\] Existing tetrahedron whose data will be filled with the data of *tet*'s ancestor on level *level*. ### Prototype ```c -void t8_element_set_linear_id (const t8_scheme_c *scheme, const t8_eclass_t tree_class, t8_element_t *element, const int level, const t8_linearidx_t id); +void t8_dtet_ancestor (const t8_dtet_t *tet, int level, t8_dtet_t *ancestor); ``` """ -function t8_element_set_linear_id(scheme, tree_class, element, level, id) - @ccall libt8.t8_element_set_linear_id(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, level::Cint, id::t8_linearidx_t)::Cvoid +function t8_dtet_ancestor(tet, level, ancestor) + @ccall libt8.t8_dtet_ancestor(tet::Ptr{t8_dtet_t}, level::Cint, ancestor::Ptr{t8_dtet_t})::Cvoid end """ - t8_element_get_linear_id(scheme, tree_class, element, level) + t8_dtet_child(tet, childid, child) -Compute the linear id of a given element in a hypothetical uniform refinement of a given level. +Compute the childid-th child in Morton order of a tetrahedron t. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element whose id we compute. -* `level`:\\[in\\] The level of the uniform refinement to consider. -# Returns -The linear id of the element. +* `tet`:\\[in\\] Input tetrahedron. +* `childid`:\\[in,out\\] The id of the child, 0..7 in Bey order. +* `child`:\\[out\\] Existing tetrahedron whose data will be filled with the date of t's childid-th child. ### Prototype ```c -t8_linearidx_t t8_element_get_linear_id (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int level); +void t8_dtet_child (const t8_dtet_t *tet, int childid, t8_dtet_t *child); ``` """ -function t8_element_get_linear_id(scheme, tree_class, element, level) - @ccall libt8.t8_element_get_linear_id(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, level::Cint)::t8_linearidx_t +function t8_dtet_child(tet, childid, child) + @ccall libt8.t8_dtet_child(tet::Ptr{t8_dtet_t}, childid::Cint, child::Ptr{t8_dtet_t})::Cvoid end """ - t8_element_get_first_descendant(scheme, tree_class, element, desc, level) + t8_dtet_childrenpv(tet, c) -Compute the first descendant of a given element. +Compute the 8 children of a tetrahedron, array version. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element whose descendant is computed. -* `desc`:\\[out\\] The first element in a uniform refinement of *element* at level *level*. -* `level`:\\[in\\] The uniform refinement level at which the descendant is computed. *level* must be greater or equal to the level of *element*. +* `tet`:\\[in\\] Input tetrahedron. +* `c`:\\[in,out\\] Pointers to the 8 computed children in Morton order. t may point to the same quadrant as c[0]. ### Prototype ```c -void t8_element_get_first_descendant (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, t8_element_t *desc, const int level); +void t8_dtet_childrenpv (const t8_dtet_t *tet, t8_dtet_t *c[T8_DTET_CHILDREN]); ``` """ -function t8_element_get_first_descendant(scheme, tree_class, element, desc, level) - @ccall libt8.t8_element_get_first_descendant(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, desc::Ptr{t8_element_t}, level::Cint)::Cvoid +function t8_dtet_childrenpv(tet, c) + @ccall libt8.t8_dtet_childrenpv(tet::Ptr{t8_dtet_t}, c::Ptr{Ptr{t8_dtet_t}})::Cvoid end """ - t8_element_get_last_descendant(scheme, tree_class, element, desc, level) + t8_dtet_is_familypv(f) -Compute the last descendant of a given element. +Check whether a collection of eight tetrahedra is a family in Morton order. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element whose descendant is computed. -* `desc`:\\[out\\] The last element in a uniform refinement of *element* of the maximum possible level. -* `level`:\\[in\\] The uniform refinement level at which the descendant is computed. *level* must be greater or equal to the level of *element*. +* `f`:\\[in\\] An array of eight tetrahedra. +# Returns +Nonzero if *f* is a family of tetrahedra. ### Prototype ```c -void t8_element_get_last_descendant (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, t8_element_t *desc, const int level); +int t8_dtet_is_familypv (const t8_dtet_t *f[]); ``` """ -function t8_element_get_last_descendant(scheme, tree_class, element, desc, level) - @ccall libt8.t8_element_get_last_descendant(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, desc::Ptr{t8_element_t}, level::Cint)::Cvoid +function t8_dtet_is_familypv(f) + @ccall libt8.t8_dtet_is_familypv(f::Ptr{Ptr{t8_dtet_t}})::Cint end """ - t8_element_get_successor(scheme, tree_class, elem1, elem2) + t8_dtet_sibling(tet, sibid, sibling) -Construct the successor in a uniform refinement of a given element. +Compute a specific sibling of a tetrahedron. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `elem1`:\\[in\\] The element whose successor should be constructed. -* `elem2`:\\[in,out\\] The element whose entries will be set. +* `tet`:\\[in\\] Input tetrahedron. +* `sibling`:\\[in,out\\] Existing tetrahedron whose data will be filled with the data of sibling no. sibling\\_id of *tet*. +* `sibid`:\\[in\\] The id of the sibling computed, 0..7 in Bey order. ### Prototype ```c -void t8_element_get_successor (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *elem1, t8_element_t *elem2); +void t8_dtet_sibling (const t8_dtet_t *tet, int sibid, t8_dtet_t *sibling); ``` """ -function t8_element_get_successor(scheme, tree_class, elem1, elem2) - @ccall libt8.t8_element_get_successor(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elem1::Ptr{t8_element_t}, elem2::Ptr{t8_element_t})::Cvoid +function t8_dtet_sibling(tet, sibid, sibling) + @ccall libt8.t8_dtet_sibling(tet::Ptr{t8_dtet_t}, sibid::Cint, sibling::Ptr{t8_dtet_t})::Cvoid end """ - t8_element_get_vertex_reference_coords(scheme, tree_class, element, vertex, coords) + t8_dtet_face_neighbour(tet, face, neigh) -Compute the coordinates of a given element vertex inside a reference tree that is embedded into [0,1]^d (d = dimension). +Compute the face neighbor of a tetrahedron. -!!! warning +!!! note - coords should be zero-initialized, as only the first d coords will be set, but when used elsewhere all coords might be used. + *tet* may point to the same tetrahedron as *neigh*. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element to be considered. -* `vertex`:\\[in\\] The id of the vertex whose coordinates shall be computed. -* `coords`:\\[out\\] An array of at least as many doubles as the element's dimension whose entries will be filled with the coordinates of *vertex*. +* `tet`:\\[in\\] Input tetrahedron. +* `face`:\\[in\\] The face across which to generate the neighbor. +* `neigh`:\\[in,out\\] Existing tetrahedron whose data will be filled. ### Prototype ```c -void t8_element_get_vertex_reference_coords (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int vertex, double coords[]); +int t8_dtet_face_neighbour (const t8_dtet_t *tet, int face, t8_dtet_t *neigh); ``` """ -function t8_element_get_vertex_reference_coords(scheme, tree_class, element, vertex, coords) - @ccall libt8.t8_element_get_vertex_reference_coords(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, vertex::Cint, coords::Ptr{Cdouble})::Cvoid +function t8_dtet_face_neighbour(tet, face, neigh) + @ccall libt8.t8_dtet_face_neighbour(tet::Ptr{t8_dtet_t}, face::Cint, neigh::Ptr{t8_dtet_t})::Cint end """ - t8_element_get_reference_coords(scheme, tree_class, element, ref_coords, num_coords, out_coords) - -Convert points in the reference space of an element to points in the reference space of the tree. - -```c++ - [0,1]^\\mathrm{dim} -``` + t8_dtet_nearest_common_ancestor(tet1, tet2, nca) -of the point in the reference space of the element. +Computes the nearest common ancestor of two tetrahedra in the same tree. -```c++ - dim -``` +!!! note --sized coordinates to evaluate. + *tet1*, *tet2*, *nca* may point to the same tetrahedron. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of the current tree. -* `element`:\\[in\\] The element. -* `ref_coords`:\\[in\\] The coordinates -* `num_coords`:\\[in\\] Number of -* `out_coords`:\\[out\\] The coordinates of the points in the reference space of the tree. +* `tet1`:\\[in\\] First input tetrahedron. +* `tet2`:\\[in\\] Second input tetrahedron. +* `nca`:\\[in,out\\] Existing tetrahedron whose data will be filled. ### Prototype ```c -void t8_element_get_reference_coords (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const double *ref_coords, const size_t num_coords, double out_coords[]); +void t8_dtet_nearest_common_ancestor (const t8_dtet_t *tet1, const t8_dtet_t *tet2, t8_dtet_t *nca); ``` """ -function t8_element_get_reference_coords(scheme, tree_class, element, ref_coords, num_coords, out_coords) - @ccall libt8.t8_element_get_reference_coords(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid +function t8_dtet_nearest_common_ancestor(tet1, tet2, nca) + @ccall libt8.t8_dtet_nearest_common_ancestor(tet1::Ptr{t8_dtet_t}, tet2::Ptr{t8_dtet_t}, nca::Ptr{t8_dtet_t})::Cvoid end """ - t8_element_count_leaves(scheme, tree_class, element, level) - -Count how many leaf descendants of a given uniform level an element would produce. + t8_dtet_children_at_face(tet, face, children, num_children, child_indices) -Example: If *element* is a line element that refines into 2 line elements on each level, then the return value is max(0, 2^{*level* - level(*t*)}). Thus, if *element*'s level is 0, and *level* = 3, the return value is 2^3 = 8. +Given a tetrahedron and a face of the tetrahedron, compute all children of the tetrahedron that touch the face. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in\\] The element to be checked. -* `level`:\\[in\\] A refinement level. -# Returns -Suppose *element* is uniformly refined up to level *level*. The return value is the resulting number of elements (of the given level). If *level* < [`t8_element_get_level`](@ref)(element), the return value should be 0. +* `tet`:\\[in\\] The tetrahedron. +* `face`:\\[in\\] A face of *tet*. +* `children`:\\[in,out\\] Allocated tetrahedra, in which the children of *tet* that share a face with *face* are stored. They will be stored in order of their child\\_id. +* `num_children`:\\[in\\] The number of tetrahedra in *children*. Must match the number of children that touch *face*. +* `child_indices`:\\[in,out\\] The indices of the children in *children*. Only filled if this is null previously. ### Prototype ```c -t8_gloidx_t t8_element_count_leaves (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, const int level); +void t8_dtet_children_at_face (const t8_dtet_t *tet, int face, t8_dtet_t *children[], int num_children, int *child_indices); ``` """ -function t8_element_count_leaves(scheme, tree_class, element, level) - @ccall libt8.t8_element_count_leaves(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, level::Cint)::t8_gloidx_t +function t8_dtet_children_at_face(tet, face, children, num_children, child_indices) + @ccall libt8.t8_dtet_children_at_face(tet::Ptr{t8_dtet_t}, face::Cint, children::Ptr{Ptr{t8_dtet_t}}, num_children::Cint, child_indices::Ptr{Cint})::Cvoid end """ - t8_element_count_leaves_from_root(scheme, tree_class, level) - -Count how many leaf descendants of a given uniform level the root element will produce. + t8_dtet_face_child_face(tet, face, face_child) -This is a convenience function, and can be implemented via t8_element_count_leaves. +Given a face of an tetrahedron and a child number of a child of that face, return the face number of the child of the tetrahedron that matches the child face. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `level`:\\[in\\] A refinement level. +* `tet`:\\[in\\] The tetrahedron. +* `face`:\\[in\\] Then number of the face. +* `face_child`:\\[in\\] The child number of a child of the face tetrahedron. # Returns -The value of t8_element_count_leaves if the input element is the root (level 0) element. +The face number of the face of a child of *tetrahedron* that coincides with *face_child*. ### Prototype ```c -t8_gloidx_t t8_element_count_leaves_from_root (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const int level); +int t8_dtet_face_child_face (const t8_dtet_t *tet, int face, int face_child); ``` """ -function t8_element_count_leaves_from_root(scheme, tree_class, level) - @ccall libt8.t8_element_count_leaves_from_root(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, level::Cint)::t8_gloidx_t +function t8_dtet_face_child_face(tet, face, face_child) + @ccall libt8.t8_dtet_face_child_face(tet::Ptr{t8_dtet_t}, face::Cint, face_child::Cint)::Cint end """ - t8_element_to_string(scheme, tree_class, element, debug_string, string_size) + t8_dtet_face_parent_face(tet, face) -Fill a string with readable information about the element +Given a face of an tet return the face number of the parent of the tet that matches the tet's face. Or return -1 if no face of the parent matches the face. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of the current tree. -* `element`:\\[in\\] The element to translate into human-readable information. -* `debug_string`:\\[in,out\\] The string to fill. -* `string_size`:\\[in\\] The length of *debug_string*. +* `tet`:\\[in\\] The tet. +* `face`:\\[in\\] Then number of the face. +# Returns +If *face* of *tet* is also a face of *tet*'s parent, the face number of this face. Otherwise -1. ### Prototype ```c -void t8_element_to_string (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const t8_element_t *element, char *debug_string, const int string_size); +int t8_dtet_face_parent_face (const t8_dtet_t *tet, int face); ``` """ -function t8_element_to_string(scheme, tree_class, element, debug_string, string_size) - @ccall libt8.t8_element_to_string(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t}, debug_string::Cstring, string_size::Cint)::Cvoid +function t8_dtet_face_parent_face(tet, face) + @ccall libt8.t8_dtet_face_parent_face(tet::Ptr{t8_dtet_t}, face::Cint)::Cint end """ - t8_element_new(scheme, tree_class, length, elems) - -Allocate memory for an array of elements of a given class and initialize them. + t8_dtet_tree_face(tet, face) -!!! note - - Not every element that is created in t8code will be created by a call to this function. However, if an element is not created using t8_element_new, then it is guaranteed that t8_scheme::element_init is called on it. - -!!! note - - In debugging mode, an element that was created with t8_element_new must pass t8_element_is_valid. +Given a tetrahedron and a face of this tetrahedron. If the face lies on the tree boundary, return the face number of the tree face. If not the return value is arbitrary. !!! note - If an element was created by t8_element_new then t8_scheme::element_init may not be called for it. Thus, t8_element_new should initialize an element in the same way as a call to t8_scheme::element_init would. + For boundary tetrahedra, this function is the inverse of t8_dtet_root_face_to_face. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `length`:\\[in\\] The number of elements to be allocated. -* `elems`:\\[in,out\\] On input an array of **length** many unallocated element pointers. On output all these pointers will point to an allocated and initialized element. -# See also -[`t8_element_init`](@ref), element\\_is\\_valid - +* `tet`:\\[in\\] The tetrahedron. +* `face`:\\[in\\] The index of a face of *tet*. +# Returns +The index of the tree face that *face* is a subface of, if *face* is on a tree boundary. Any arbitrary integer if *face* is not at a tree boundary. ### Prototype ```c -void t8_element_new (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const int length, t8_element_t **elems); +int t8_dtet_tree_face (t8_dtet_t *tet, int face); ``` """ -function t8_element_new(scheme, tree_class, length, elems) - @ccall libt8.t8_element_new(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, length::Cint, elems::Ptr{Ptr{t8_element_t}})::Cvoid +function t8_dtet_tree_face(tet, face) + @ccall libt8.t8_dtet_tree_face(tet::Ptr{t8_dtet_t}, face::Cint)::Cint end """ - t8_element_init(scheme, tree_class, length, elem) - -Initialize an array of allocated elements. - -!!! note + t8_dtet_root_face_to_face(tet, root_face) - In debugging mode, an element that was passed to t8_element_init must pass t8_element_is_valid. - -!!! note - - If an element was created by t8_element_new then t8_element_init may not be called for it. Thus, t8_element_init should initialize an element in the same way as a call to t8_element_new would. +Given a tetrahedron and a face of the root tetrahedron. If the tetrahedron lies on the tree boundary, return the corresponding face number of the tetrahedron. If not the return value is arbitrary. !!! note - Every call to + For boundary tetrahedra, this function is the inverse of t8_dtet_tree_face. # Arguments -* `scheme`:\\[in\\] The scheme to use. -* `tree_class`:\\[in\\] The eclass of the current tree. -* `length`:\\[in\\] The number of elements to be initialized. -* `elem`:\\[in,out\\] On input an array of *length* many allocated elements. -# See also -[`t8_element_init`](@ref) must be matched by a call to, [`t8_element_deinit`](@ref), [`t8_element_deinit`](@ref), [`t8_element_new`](@ref), t8\\_element\\_is\\_valid - +* `tet`:\\[in\\] The tetrahedron. +* `root_face`:\\[in\\] The index of a face of the root tetrahedron. +# Returns +The index of the face of *tet* that is a subface of *root_face*, if *tet* is on the tree boundary. Any arbitrary integer if *tet* is not at a tree boundary. ### Prototype ```c -void t8_element_init (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const int length, t8_element_t *elem); +int t8_dtet_root_face_to_face (t8_dtet_t *tet, int root_face); ``` """ -function t8_element_init(scheme, tree_class, length, elem) - @ccall libt8.t8_element_init(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, length::Cint, elem::Ptr{t8_element_t})::Cvoid +function t8_dtet_root_face_to_face(tet, root_face) + @ccall libt8.t8_dtet_root_face_to_face(tet::Ptr{t8_dtet_t}, root_face::Cint)::Cint end """ - t8_element_deinit(scheme, tree_class, length, elems) - -Deinitialize an array of allocated elements. - -!!! note - - Call this function if you called t8_element_init on the element pointers. - -# Arguments -* `scheme`:\\[in\\] The scheme to use. -* `tree_class`:\\[in\\] The eclass of the current tree. -* `length`:\\[in\\] The number of elements to be deinitialized. -* `elems`:\\[in,out\\] On input an array of *length* many allocated and initialized elements, on output an array of *length* many allocated, but not initialized elements. -# See also -[`t8_element_init`](@ref) + t8_dtet_is_inside_root(tet) +Test if a tetrahedron lies inside of the root tetrahedron, that is the tetrahedron of level 0, anchor node (0,0,0) and type 0. + +# Arguments +* `tet`:\\[in\\] Input tetrahedron. +# Returns +true If *tet* lies inside of the root tetrahedron. ### Prototype ```c -void t8_element_deinit (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const int length, t8_element_t *elems); +int t8_dtet_is_inside_root (t8_dtet_t *tet); ``` """ -function t8_element_deinit(scheme, tree_class, length, elems) - @ccall libt8.t8_element_deinit(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, length::Cint, elems::Ptr{t8_element_t})::Cvoid +function t8_dtet_is_inside_root(tet) + @ccall libt8.t8_dtet_is_inside_root(tet::Ptr{t8_dtet_t})::Cint end """ - t8_element_destroy(scheme, tree_class, length, elems) + t8_dtet_is_root_boundary(tet, face) -Deallocate an array of elements. +Compute whether a given tetrahedron shares a given face with its root tree. # Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `length`:\\[in\\] The number of elements in the array. -* `elems`:\\[in,out\\] On input an array of **length** many allocated element pointers. On output all these pointers will be freed. **element** itself will not be freed by this function. +* `tet`:\\[in\\] The input tet. +* `face`:\\[in\\] A face of *tet*. +# Returns +True if *face* is a subface of the tet's root element. ### Prototype ```c -void t8_element_destroy (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const int length, t8_element_t **elems); +int t8_dtet_is_root_boundary (const t8_dtet_t *tet, int face); ``` """ -function t8_element_destroy(scheme, tree_class, length, elems) - @ccall libt8.t8_element_destroy(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, length::Cint, elems::Ptr{Ptr{t8_element_t}})::Cvoid +function t8_dtet_is_root_boundary(tet, face) + @ccall libt8.t8_dtet_is_root_boundary(tet::Ptr{t8_dtet_t}, face::Cint)::Cint end """ - t8_element_set_to_root(scheme, tree_class, element) + t8_dtet_is_equal(tet1, tet2) -Fills an element with the root element. +Test if two tetrahedra have the same coordinates, type and level. -# Arguments -* `scheme`:\\[in\\] The scheme of the forest. -* `tree_class`:\\[in\\] The eclass of tree the elements are part of. -* `element`:\\[in,out\\] The element to be filled with root. +# Returns +true if *tet1* describes the same tetrahedron as *tet2*. ### Prototype ```c -void t8_element_set_to_root (const t8_scheme_c *scheme, const t8_eclass_t tree_class, t8_element_t *element); +int t8_dtet_is_equal (const t8_dtet_t *tet1, const t8_dtet_t *tet2); ``` """ -function t8_element_set_to_root(scheme, tree_class, element) - @ccall libt8.t8_element_set_to_root(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, element::Ptr{t8_element_t})::Cvoid +function t8_dtet_is_equal(tet1, tet2) + @ccall libt8.t8_dtet_is_equal(tet1::Ptr{t8_dtet_t}, tet2::Ptr{t8_dtet_t})::Cint end """ - t8_element_MPI_Pack(scheme, tree_class, elements, count, send_buffer, buffer_size, position, comm) + t8_dtet_is_sibling(tet1, tet2) + +Test if two tetrahedra are siblings. +# Arguments +* `tet1`:\\[in\\] First tetrahedron to be tested. +* `tet2`:\\[in\\] Second tetrahedron to be tested. +# Returns +true if *tet1* is equal to or a sibling of *tet2*. ### Prototype ```c -void t8_element_MPI_Pack (const t8_scheme_c *scheme, const t8_eclass_t tree_class, t8_element_t **const elements, const unsigned int count, void *send_buffer, const int buffer_size, int *position, sc_MPI_Comm comm); +int t8_dtet_is_sibling (const t8_dtet_t *tet1, const t8_dtet_t *tet2); ``` """ -function t8_element_MPI_Pack(scheme, tree_class, elements, count, send_buffer, buffer_size, position, comm) - @ccall libt8.t8_element_MPI_Pack(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, elements::Ptr{Ptr{t8_element_t}}, count::Cuint, send_buffer::Ptr{Cvoid}, buffer_size::Cint, position::Ptr{Cint}, comm::MPI_Comm)::Cvoid +function t8_dtet_is_sibling(tet1, tet2) + @ccall libt8.t8_dtet_is_sibling(tet1::Ptr{t8_dtet_t}, tet2::Ptr{t8_dtet_t})::Cint end """ - t8_element_MPI_Pack_size(scheme, tree_class, count, comm, pack_size) + t8_dtet_is_parent(tet, child) +Test if a tetrahedron is the parent of another tetrahedron. + +# Arguments +* `tet`:\\[in\\] tetrahedron to be tested. +* `child`:\\[in\\] Possible child tetrahedron. +# Returns +true if *tet* is the parent of *child*. ### Prototype ```c -void t8_element_MPI_Pack_size (const t8_scheme_c *scheme, const t8_eclass_t tree_class, const unsigned int count, sc_MPI_Comm comm, int *pack_size); +int t8_dtet_is_parent (const t8_dtet_t *tet, const t8_dtet_t *child); ``` """ -function t8_element_MPI_Pack_size(scheme, tree_class, count, comm, pack_size) - @ccall libt8.t8_element_MPI_Pack_size(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, count::Cuint, comm::MPI_Comm, pack_size::Ptr{Cint})::Cvoid +function t8_dtet_is_parent(tet, child) + @ccall libt8.t8_dtet_is_parent(tet::Ptr{t8_dtet_t}, child::Ptr{t8_dtet_t})::Cint end """ - t8_element_MPI_Unpack(scheme, tree_class, recvbuf, buffer_size, position, elements, count, comm) + t8_dtet_is_ancestor(tet, c) + +Test if a tetrahedron is an ancestor of another tetrahedron. +# Arguments +* `tet`:\\[in\\] tetrahedron to be tested. +* `c`:\\[in\\] Descendent tetrahedron. +# Returns +true if *tet* is equal to or an ancestor of *c*. ### Prototype ```c -void t8_element_MPI_Unpack (const t8_scheme_c *scheme, const t8_eclass_t tree_class, void *recvbuf, const int buffer_size, int *position, t8_element_t **elements, const unsigned int count, sc_MPI_Comm comm); +int t8_dtet_is_ancestor (const t8_dtet_t *tet, const t8_dtet_t *c); ``` """ -function t8_element_MPI_Unpack(scheme, tree_class, recvbuf, buffer_size, position, elements, count, comm) - @ccall libt8.t8_element_MPI_Unpack(scheme::Ptr{t8_scheme_c}, tree_class::t8_eclass_t, recvbuf::Ptr{Cvoid}, buffer_size::Cint, position::Ptr{Cint}, elements::Ptr{Ptr{t8_element_t}}, count::Cuint, comm::MPI_Comm)::Cvoid +function t8_dtet_is_ancestor(tet, c) + @ccall libt8.t8_dtet_is_ancestor(tet::Ptr{t8_dtet_t}, c::Ptr{t8_dtet_t})::Cint end """ - t8_norm(vec) + t8_dtet_linear_id(tet, level) -Vector norm. +Computes the linear position of a tetrahedron in a uniform grid. + +!!! note + + This id is not the Morton index. # Arguments -* `vec`:\\[in\\] A 3D vector. +* `tet`:\\[in\\] tetrahedron whose id will be computed. +* `level`:\\[in\\] level of uniform grid to be considered. # Returns -The norm of *vec*. +Returns the linear position of this tetrahedron on a grid of level *level*. ### Prototype ```c -double t8_norm (const double vec[3]); +t8_linearidx_t t8_dtet_linear_id (const t8_dtet_t *tet, int level); ``` """ -function t8_norm(vec) - @ccall libt8.t8_norm(vec::Ptr{Cdouble})::Cdouble +function t8_dtet_linear_id(tet, level) + @ccall libt8.t8_dtet_linear_id(tet::Ptr{t8_dtet_t}, level::Cint)::t8_linearidx_t end """ - t8_normalize(vec) + t8_dtet_init_linear_id_with_level(tet, id, start_level, end_level, parenttype) -Normalize a vector. +Same as init\\_linear\\_id, but we only consider the subtree. Used for computing the index of a tetrahedron lying in a pyramid # Arguments -* `vec`:\\[in,out\\] A 3D vector. +* `tet`:\\[in,out\\] Existing tet whose data will be filled +* `id`: Index to be considered +* `start_level`: The level of the root of the subtree +* `end_level`: Level of uniform grid to be considered +* `parenttype`: The type of the parent. ### Prototype ```c -void t8_normalize (double vec[3]); +void t8_dtet_init_linear_id_with_level (t8_dtet_t *tet, t8_linearidx_t id, int start_level, int end_level, t8_dtet_type_t parenttype); ``` """ -function t8_normalize(vec) - @ccall libt8.t8_normalize(vec::Ptr{Cdouble})::Cvoid +function t8_dtet_init_linear_id_with_level(tet, id, start_level, end_level, parenttype) + @ccall libt8.t8_dtet_init_linear_id_with_level(tet::Ptr{t8_dtet_t}, id::t8_linearidx_t, start_level::Cint, end_level::Cint, parenttype::t8_dtet_type_t)::Cvoid end """ - t8_copy(dimensional_in, dimensional_out) + t8_dtet_init_linear_id(tet, id, level) -Make a copy of a dimensional object. +Initialize a tetrahedron as the tetrahedron with a given global id in a uniform refinement of a given level. # Arguments -* `dimensional_in`:\\[in\\] -* `dimensional_out`:\\[out\\] +* `tet`:\\[in,out\\] Existing tetrahedron whose data will be filled. +* `id`:\\[in\\] Index to be considered. +* `level`:\\[in\\] level of uniform grid to be considered. ### Prototype ```c -void t8_copy (const double dimensional_in[3], double dimensional_out[3]); +void t8_dtet_init_linear_id (t8_dtet_t *tet, t8_linearidx_t id, int level); ``` """ -function t8_copy(dimensional_in, dimensional_out) - @ccall libt8.t8_copy(dimensional_in::Ptr{Cdouble}, dimensional_out::Ptr{Cdouble})::Cvoid +function t8_dtet_init_linear_id(tet, id, level) + @ccall libt8.t8_dtet_init_linear_id(tet::Ptr{t8_dtet_t}, id::t8_linearidx_t, level::Cint)::Cvoid end """ - t8_dist(vec_x, vec_y) + t8_dtet_init_root(tet) -Euclidean distance of X and Y. +Initialize a tetrahedron as the root tetrahedron (type 0 at level 0) # Arguments -* `vec_x`:\\[in\\] A 3D vector. -* `vec_y`:\\[in\\] A 3D vector. -# Returns -The euclidean distance. Equivalent to norm (X-Y). +* `tet`:\\[in,out\\] Existing tetrahedron whose data will be filled. ### Prototype ```c -double t8_dist (const double vec_x[3], const double vec_y[3]); +void t8_dtet_init_root (t8_dtet_t *tet); ``` """ -function t8_dist(vec_x, vec_y) - @ccall libt8.t8_dist(vec_x::Ptr{Cdouble}, vec_y::Ptr{Cdouble})::Cdouble +function t8_dtet_init_root(tet) + @ccall libt8.t8_dtet_init_root(tet::Ptr{t8_dtet_t})::Cvoid end """ - t8_ax(vec_x, alpha) + t8_dtet_successor(tet, succ, level) -Compute X = alpha * X +Computes the successor of a tetrahedron in a uniform grid of level *level*. # Arguments -* `vec_x`:\\[in,out\\] A 3D vector. On output set to *alpha* * *vec_x*. -* `alpha`:\\[in\\] A factor. +* `tet`:\\[in\\] tetrahedron whose id will be computed. +* `succ`:\\[out\\] Existing tetrahedron whose data will be filled with the data of t's successor on level *level*. +* `level`:\\[in\\] level of uniform grid to be considered. ### Prototype ```c -void t8_ax (double vec_x[3], const double alpha); +void t8_dtet_successor (const t8_dtet_t *tet, t8_dtet_t *succ, int level); ``` """ -function t8_ax(vec_x, alpha) - @ccall libt8.t8_ax(vec_x::Ptr{Cdouble}, alpha::Cdouble)::Cvoid +function t8_dtet_successor(tet, succ, level) + @ccall libt8.t8_dtet_successor(tet::Ptr{t8_dtet_t}, succ::Ptr{t8_dtet_t}, level::Cint)::Cvoid end """ - t8_axy(vec_x, vec_y, alpha) + t8_dtet_first_descendant(tet, s, level) -Compute Y = alpha * X +Compute the first descendant of a tetrahedron at a given level. This is the descendant of the tetrahedron in a uniform maxlevel refinement that has the smaller id. # Arguments -* `vec_x`:\\[in\\] A 3D vector. -* `vec_y`:\\[out\\] On output set to *alpha* * *vec_x*. -* `alpha`:\\[in\\] A factor. +* `tet`:\\[in\\] tetrahedron whose descendant is computed. +* `level`:\\[in\\] A given level. Must be greater or equal to *tet*'s level. +* `s`:\\[out\\] Existing tetrahedron whose data will be filled with the data of t's first descendant. ### Prototype ```c -void t8_axy (const double vec_x[3], double vec_y[3], const double alpha); +void t8_dtet_first_descendant (const t8_dtet_t *tet, t8_dtet_t *s, int level); ``` """ -function t8_axy(vec_x, vec_y, alpha) - @ccall libt8.t8_axy(vec_x::Ptr{Cdouble}, vec_y::Ptr{Cdouble}, alpha::Cdouble)::Cvoid +function t8_dtet_first_descendant(tet, s, level) + @ccall libt8.t8_dtet_first_descendant(tet::Ptr{t8_dtet_t}, s::Ptr{t8_dtet_t}, level::Cint)::Cvoid end """ - t8_axb(vec_x, vec_y, alpha, b) - -Y = alpha * X + b - -!!! note + t8_dtet_last_descendant(tet, s, level) - It is possible that vec\\_x = vec\\_y on input to overwrite x +Compute the last descendant of a tetrahedron at a given level. This is the descendant of the tetrahedron in a uniform maxlevel refinement that has the biggest id. # Arguments -* `vec_x`:\\[in\\] A 3D vector. -* `vec_y`:\\[out\\] On input, a 3D vector. On output set to *alpha* * *vec_x* + *b*. -* `alpha`:\\[in\\] A factor. -* `b`:\\[in\\] An offset. +* `tet`:\\[in\\] tetrahedron whose descendant is computed. +* `level`:\\[in\\] A given level. Must be greater or equal to *tet*'s level. +* `s`:\\[out\\] Existing tetrahedron whose data will be filled with the data of t's last descendant. ### Prototype ```c -void t8_axb (const double vec_x[3], double vec_y[3], const double alpha, const double b); +void t8_dtet_last_descendant (const t8_dtet_t *tet, t8_dtet_t *s, int level); ``` """ -function t8_axb(vec_x, vec_y, alpha, b) - @ccall libt8.t8_axb(vec_x::Ptr{Cdouble}, vec_y::Ptr{Cdouble}, alpha::Cdouble, b::Cdouble)::Cvoid +function t8_dtet_last_descendant(tet, s, level) + @ccall libt8.t8_dtet_last_descendant(tet::Ptr{t8_dtet_t}, s::Ptr{t8_dtet_t}, level::Cint)::Cvoid end """ - t8_axpy(vec_x, vec_y, alpha) + t8_dtet_corner_descendant(tet, s, corner, level) -Y = Y + alpha * X +Compute the descendant of a tetrahedron in a given corner. # Arguments -* `vec_x`:\\[in\\] A 3D vector. -* `vec_y`:\\[in,out\\] On input, a 3D vector. On output set *to* vec\\_y + *alpha* * *vec_x* -* `alpha`:\\[in\\] A factor. +* `tet`:\\[in\\] Tetrahedron whose descendant is computed. +* `s`:\\[out\\] Existing tetrahedron whose data will be filled with the data of t's descendant in *corner*. +* `corner`:\\[in\\] The corner in which the descendant should lie. +* `level`:\\[in\\] The refinement level of the descendant. Must be greater or equal to *tet*'s level. ### Prototype ```c -void t8_axpy (const double vec_x[3], double vec_y[3], const double alpha); +void t8_dtet_corner_descendant (const t8_dtet_t *tet, t8_dtet_t *s, int corner, int level); ``` """ -function t8_axpy(vec_x, vec_y, alpha) - @ccall libt8.t8_axpy(vec_x::Ptr{Cdouble}, vec_y::Ptr{Cdouble}, alpha::Cdouble)::Cvoid +function t8_dtet_corner_descendant(tet, s, corner, level) + @ccall libt8.t8_dtet_corner_descendant(tet::Ptr{t8_dtet_t}, s::Ptr{t8_dtet_t}, corner::Cint, level::Cint)::Cvoid end """ - t8_axpyz(vec_x, vec_y, vec_z, alpha) + t8_dtet_predecessor(tet, s, level) -Z = Y + alpha * X +Computes the predecessor of a tetrahedron in a uniform grid of level *level*. # Arguments -* `vec_x`:\\[in\\] A 3D vector. -* `vec_y`:\\[in\\] A 3D vector. -* `vec_z`:\\[out\\] On output set *to* vec\\_y + *alpha* * *vec_x* -* `alpha`:\\[in\\] A factor for the multiplication of *vec_x*. +* `tet`:\\[in\\] tetrahedron whose id will be computed. +* `s`:\\[in,out\\] Existing tetrahedron whose data will be filled with the data of t's predecessor on level *level*. +* `level`:\\[in\\] level of uniform grid to be considered. ### Prototype ```c -void t8_axpyz (const double vec_x[3], const double vec_y[3], double vec_z[3], const double alpha); +void t8_dtet_predecessor (const t8_dtet_t *tet, t8_dtet_t *s, int level); ``` """ -function t8_axpyz(vec_x, vec_y, vec_z, alpha) - @ccall libt8.t8_axpyz(vec_x::Ptr{Cdouble}, vec_y::Ptr{Cdouble}, vec_z::Ptr{Cdouble}, alpha::Cdouble)::Cvoid +function t8_dtet_predecessor(tet, s, level) + @ccall libt8.t8_dtet_predecessor(tet::Ptr{t8_dtet_t}, s::Ptr{t8_dtet_t}, level::Cint)::Cvoid end """ - t8_dot(vec_x, vec_y) + t8_dtet_ancestor_id(tet, level) -Dot product of X and Y. +Compute the position of the ancestor of this child at level *level* within its siblings. # Arguments -* `vec_x`:\\[in\\] A 3D vector. -* `vec_y`:\\[in\\] A 3D vector. +* `tet`:\\[in\\] tetrahedron to be considered. +* `level`:\\[in\\] level to be considered. # Returns -The dot product *vec_x* * *vec_y* +Returns its child id in 0..7 ### Prototype ```c -double t8_dot (const double vec_x[3], const double vec_y[3]); +int t8_dtet_ancestor_id (const t8_dtet_t *tet, int level); ``` """ -function t8_dot(vec_x, vec_y) - @ccall libt8.t8_dot(vec_x::Ptr{Cdouble}, vec_y::Ptr{Cdouble})::Cdouble +function t8_dtet_ancestor_id(tet, level) + @ccall libt8.t8_dtet_ancestor_id(tet::Ptr{t8_dtet_t}, level::Cint)::Cint end """ - t8_cross_3D(vec_x, vec_y, cross) + t8_dtet_child_id(tet) -Cross product of X and Y +Compute the position of the ancestor of this child at level *level* within its siblings. # Arguments -* `vec_x`:\\[in\\] A 3D vector. -* `vec_y`:\\[in\\] A 3D vector. -* `cross`:\\[out\\] On output, the cross product of *vec_x* and *vec_y*. +* `tet`:\\[in\\] tetrahedron to be considered. +# Returns +Returns its child id in 0..7 ### Prototype ```c -void t8_cross_3D (const double vec_x[3], const double vec_y[3], double cross[3]); +int t8_dtet_child_id (const t8_dtet_t *tet); ``` """ -function t8_cross_3D(vec_x, vec_y, cross) - @ccall libt8.t8_cross_3D(vec_x::Ptr{Cdouble}, vec_y::Ptr{Cdouble}, cross::Ptr{Cdouble})::Cvoid +function t8_dtet_child_id(tet) + @ccall libt8.t8_dtet_child_id(tet::Ptr{t8_dtet_t})::Cint end """ - t8_cross_2D(vec_x, vec_y) + t8_dtet_get_level(tet) -Cross product of X and Y +Return the level of a tetrahedron. # Arguments -* `vec_x`:\\[in\\] A 2D vector. -* `vec_y`:\\[in\\] A 2D vector. +* `tet`:\\[in\\] tetrahedron to be considered. # Returns -The cross product of *vec_x* and *vec_y*. +The level of *tet*. ### Prototype ```c -double t8_cross_2D (const double vec_x[2], const double vec_y[2]); +int t8_dtet_get_level (const t8_dtet_t *tet); ``` """ -function t8_cross_2D(vec_x, vec_y) - @ccall libt8.t8_cross_2D(vec_x::Ptr{Cdouble}, vec_y::Ptr{Cdouble})::Cdouble +function t8_dtet_get_level(tet) + @ccall libt8.t8_dtet_get_level(tet::Ptr{t8_dtet_t})::Cint end """ - t8_diff(vec_x, vec_y, diff) + t8_dtet_is_valid(tet) -Compute the difference of two vectors. +Query whether all entries of a tet are in valid ranges. # Arguments -* `vec_x`:\\[in\\] A 3D vector. -* `vec_y`:\\[in\\] A 3D vector. -* `diff`:\\[out\\] On output, the difference of *vec_x* and *vec_y*. +* `tet`:\\[in\\] tet to be considered. +# Returns +True, if *tet* is a valid tet and it is safe to call any function on *tet*. False otherwise. ### Prototype ```c -void t8_diff (const double vec_x[3], const double vec_y[3], double diff[3]); +int t8_dtet_is_valid (const t8_dtet_t *tet); ``` """ -function t8_diff(vec_x, vec_y, diff) - @ccall libt8.t8_diff(vec_x::Ptr{Cdouble}, vec_y::Ptr{Cdouble}, diff::Ptr{Cdouble})::Cvoid +function t8_dtet_is_valid(tet) + @ccall libt8.t8_dtet_is_valid(tet::Ptr{t8_dtet_t})::Cint end """ - t8_eq(vec_x, vec_y, tol) + t8_dtet_init(tet) -Check the equality of two vectors elementwise +Set sensible default values for a tet. # Arguments -* `vec_x`:\\[in\\] -* `vec_y`:\\[in\\] -* `tol`:\\[in\\] -# Returns -true, if the vectors are equal up to *tol* +* `tet`:\\[in,out\\] A tet. ### Prototype ```c -int t8_eq (const double vec_x[3], const double vec_y[3], const double tol); +void t8_dtet_init (t8_dtet_t *tet); ``` """ -function t8_eq(vec_x, vec_y, tol) - @ccall libt8.t8_eq(vec_x::Ptr{Cdouble}, vec_y::Ptr{Cdouble}, tol::Cdouble)::Cint +function t8_dtet_init(tet) + @ccall libt8.t8_dtet_init(tet::Ptr{t8_dtet_t})::Cvoid end """ - t8_rescale(vec, new_length) + t8_dtet_element_pack(elements, count, send_buffer, buffer_size, position, comm) -Rescale a vector to a new length. +### Prototype +```c +void t8_dtet_element_pack (t8_dtet_t **const elements, const unsigned int count, void *send_buffer, const int buffer_size, int *position, sc_MPI_Comm comm); +``` +""" +function t8_dtet_element_pack(elements, count, send_buffer, buffer_size, position, comm) + @ccall libt8.t8_dtet_element_pack(elements::Ptr{Ptr{t8_dtet_t}}, count::Cuint, send_buffer::Ptr{Cvoid}, buffer_size::Cint, position::Ptr{Cint}, comm::MPI_Comm)::Cvoid +end + +""" + t8_dtet_element_pack_size(count, comm, pack_size) -# Arguments -* `vec`:\\[in,out\\] A 3D vector. -* `new_length`:\\[in\\] New length of the vector. ### Prototype ```c -void t8_rescale (double vec[3], const double new_length); +void t8_dtet_element_pack_size (const unsigned int count, sc_MPI_Comm comm, int *pack_size); ``` """ -function t8_rescale(vec, new_length) - @ccall libt8.t8_rescale(vec::Ptr{Cdouble}, new_length::Cdouble)::Cvoid +function t8_dtet_element_pack_size(count, comm, pack_size) + @ccall libt8.t8_dtet_element_pack_size(count::Cuint, comm::MPI_Comm, pack_size::Ptr{Cint})::Cvoid end """ - t8_normal_of_tri(p1, p2, p3, normal) + t8_dtet_element_unpack(recvbuf, buffer_size, position, elements, count, comm) -Compute the normal of a triangle given by its three vertices. +### Prototype +```c +void t8_dtet_element_unpack (void *recvbuf, const int buffer_size, int *position, t8_dtet_t **elements, const unsigned int count, sc_MPI_Comm comm); +``` +""" +function t8_dtet_element_unpack(recvbuf, buffer_size, position, elements, count, comm) + @ccall libt8.t8_dtet_element_unpack(recvbuf::Ptr{Cvoid}, buffer_size::Cint, position::Ptr{Cint}, elements::Ptr{Ptr{t8_dtet_t}}, count::Cuint, comm::MPI_Comm)::Cvoid +end + +""" + t8_dtri_copy(element, dest) + +Copy the values of one triangle to another. # Arguments -* `p1`:\\[in\\] A 3D vector. -* `p2`:\\[in\\] A 3D vector. -* `p3`:\\[in\\] A 3D vector. -* `normal`:\\[out\\] vector of the triangle. (Not necessarily of length 1!) +* `element`:\\[in\\] Triangle whose values will be copied. +* `dest`:\\[in,out\\] Existing triangle whose data will be filled with the data of *element*. ### Prototype ```c -void t8_normal_of_tri (const double p1[3], const double p2[3], const double p3[3], double normal[3]); +void t8_dtri_copy (const t8_dtri_t *element, t8_dtri_t *dest); ``` """ -function t8_normal_of_tri(p1, p2, p3, normal) - @ccall libt8.t8_normal_of_tri(p1::Ptr{Cdouble}, p2::Ptr{Cdouble}, p3::Ptr{Cdouble}, normal::Ptr{Cdouble})::Cvoid +function t8_dtri_copy(element, dest) + @ccall libt8.t8_dtri_copy(element::Ptr{t8_dtri_t}, dest::Ptr{t8_dtri_t})::Cvoid end """ - t8_orthogonal_tripod(v1, v2, v3) + t8_dtri_compare(element1, element2) -Compute an orthogonal coordinate system from a given vector. +Compare two triangle in their linear order. # Arguments -* `v1`:\\[in\\] 3D vector. -* `v2`:\\[out\\] 3D vector. -* `v3`:\\[out\\] 3D vector. +* `element1`:\\[in\\] Triangle one. +* `element2`:\\[in\\] Triangle two. +# Returns +Returns negative if tri1 < tri2, zero if tri1 = tri2, positive if tri1 > tri2 ### Prototype ```c -void t8_orthogonal_tripod (const double v1[3], double v2[3], double v3[3]); +int t8_dtri_compare (const t8_dtri_t *element1, const t8_dtri_t *element2); ``` """ -function t8_orthogonal_tripod(v1, v2, v3) - @ccall libt8.t8_orthogonal_tripod(v1::Ptr{Cdouble}, v2::Ptr{Cdouble}, v3::Ptr{Cdouble})::Cvoid +function t8_dtri_compare(element1, element2) + @ccall libt8.t8_dtri_compare(element1::Ptr{t8_dtri_t}, element2::Ptr{t8_dtri_t})::Cint end """ - t8_swap(p1, p2) + t8_dtri_equal(element1, element2) -Swap the components of two vectors. +Check if two elements are equal. # Arguments -* `p1`:\\[in,out\\] A 3D vector. -* `p2`:\\[in,out\\] A 3D vector. +* `element1`:\\[in\\] The first element. +* `element2`:\\[in\\] The second element. +# Returns +1 if the elements are equal, 0 if they are not equal ### Prototype ```c -void t8_swap (double p1[3], double p2[3]); +int t8_dtri_equal (const t8_dtri_t *element1, const t8_dtri_t *element2); ``` """ -function t8_swap(p1, p2) - @ccall libt8.t8_swap(p1::Ptr{Cdouble}, p2::Ptr{Cdouble})::Cvoid +function t8_dtri_equal(element1, element2) + @ccall libt8.t8_dtri_equal(element1::Ptr{t8_dtri_t}, element2::Ptr{t8_dtri_t})::Cint end """ - t8_write_pvtu(filename, num_procs, write_tree, write_rank, write_level, write_id, num_data, data) + t8_dtri_parent(element, parent) -Writes the pvtu header file that links to the processor local files. It is used by the cmesh and forest vtk routines. This function should only be called by one process. Return 0 on success. +Compute the parent of a triangle. + +!!! note + + *element* may point to the same triangle as *parent*. +# Arguments +* `element`:\\[in\\] Input triangle. +* `parent`:\\[in,out\\] Existing triangle whose data will be filled with the data of elem's parent. ### Prototype ```c -int t8_write_pvtu (const char *filename, int num_procs, int write_tree, int write_rank, int write_level, int write_id, int num_data, t8_vtk_data_field_t *data); +void t8_dtri_parent (const t8_dtri_t *element, t8_dtri_t *parent); ``` """ -function t8_write_pvtu(filename, num_procs, write_tree, write_rank, write_level, write_id, num_data, data) - @ccall libt8.t8_write_pvtu(filename::Cstring, num_procs::Cint, write_tree::Cint, write_rank::Cint, write_level::Cint, write_id::Cint, num_data::Cint, data::Ptr{t8_vtk_data_field_t})::Cint +function t8_dtri_parent(element, parent) + @ccall libt8.t8_dtri_parent(element::Ptr{t8_dtri_t}, parent::Ptr{t8_dtri_t})::Cvoid end """ - vtk_file_type + t8_dtri_ancestor(element, level, ancestor) -Enumerator for all types of files readable by t8code. +Compute the ancestor of a triangle at a given level. -| Enumerator | Note | -| :----------------------------------- | :--------------------------------------------- | -| VTK\\_FILE\\_ERROR | For Testing purpose. | -| VTK\\_SERIAL\\_FILE | VTK file type of serial files. | -| VTK\\_UNSTRUCTURED\\_FILE | Unstructured file type is the same as serial. | -| VTK\\_POLYDATA\\_FILE | VTK polydata file type. | -| VTK\\_PARALLEL\\_FILE | VTK file type of parallel files. | -| VTK\\_PARALLEL\\_UNSTRUCTURED\\_FILE | For parallel unstructured files. | -| VTK\\_PARALLEL\\_POLYDATA\\_FILE | VTK polydata parallel file type. | -| VTK\\_NUM\\_TYPES | Number of different vtk file types supported. | -""" -@cenum vtk_file_type::Int32 begin - VTK_FILE_ERROR = -1 - VTK_SERIAL_FILE = 8 - VTK_UNSTRUCTURED_FILE = 8 - VTK_POLYDATA_FILE = 9 - VTK_PARALLEL_FILE = 16 - VTK_PARALLEL_UNSTRUCTURED_FILE = 16 - VTK_PARALLEL_POLYDATA_FILE = 17 - VTK_NUM_TYPES = 5 +!!! note + + The triangle *ancestor* may point to the same triangle as *element*. + +# Arguments +* `element`:\\[in\\] Input triangle. +* `level`:\\[in\\] A smaller level than *element*. +* `ancestor`:\\[in,out\\] Existing triangle whose data will be filled with the data of *element*'s ancestor on level *level*. +### Prototype +```c +void t8_dtri_ancestor (const t8_dtri_t *element, int level, t8_dtri_t *ancestor); +``` +""" +function t8_dtri_ancestor(element, level, ancestor) + @ccall libt8.t8_dtri_ancestor(element::Ptr{t8_dtri_t}, level::Cint, ancestor::Ptr{t8_dtri_t})::Cvoid end -"""Enumerator for all types of files readable by t8code.""" -const vtk_file_type_t = vtk_file_type - """ - vtk_read_success + t8_dtri_compute_integer_coords(element, vertex, coordinates) -Enumerator for the success of reading a vtk file. This is used to indicate whether the reading was successful or not. +Compute the coordinates of a vertex of a triangle. -| Enumerator | Note | -| :------------- | :----------------------------------------------- | -| read\\_failure | Indicates that file reading was not successful. | -| read\\_success | Indicates that file reading was successful. | +# Arguments +* `element`:\\[in\\] Input triangle. +* `vertex`:\\[in\\] The number of the vertex. +* `coordinates`:\\[out\\] An array of 2 [`t8_dtri_coord_t`](@ref) that will be filled with the coordinates of the vertex. +### Prototype +```c +void t8_dtri_compute_integer_coords (const t8_dtri_t *element, const int vertex, t8_dtri_coord_t coordinates[2]); +``` """ -@cenum vtk_read_success::UInt32 begin - read_failure = 0 - read_success = 1 +function t8_dtri_compute_integer_coords(element, vertex, coordinates) + @ccall libt8.t8_dtri_compute_integer_coords(element::Ptr{t8_dtri_t}, vertex::Cint, coordinates::Ptr{t8_dtri_coord_t})::Cvoid end -"""Enumerator for the success of reading a vtk file. This is used to indicate whether the reading was successful or not.""" -const vtk_read_success_t = vtk_read_success - """ - t8_forest_vtk_write_file_via_API(forest, fileprefix, write_treeid, write_mpirank, write_level, write_element_id, curved_flag, write_ghosts, num_data, data) + t8_dtri_compute_vertex_ref_coords(element, vertex, coordinates) -Write the forest in .pvtu file format. Writes one .vtu file per process and a meta .pvtu file. This function uses the vtk library. t8code must be configured with "-DT8CODE\\_ENABLE\\_VTK=ON" in order to use it. Currently does not support pyramid elements. +Compute the reference coordinates of a vertex of a triangle when the tree (level 0 triangle) is embedded in -!!! note +```c++ + [0,1]^2 +``` - If t8code was not configured with vtk, use t8_forest_vtk_write_file +. # Arguments -* `forest`:\\[in\\] The forest. -* `fileprefix`:\\[in\\] The prefix of the output files. The meta file will be named *fileprefix*.pvtu . -* `write_treeid`:\\[in\\] If true, the global tree id is written for each element. -* `write_mpirank`:\\[in\\] If true, the mpirank is written for each element. -* `write_level`:\\[in\\] If true, the refinement level is written for each element. -* `write_element_id`:\\[in\\] If true, the global element id is written for each element. -* `curved_flag`:\\[in\\] If true, write the elements as curved element types from vtk. -* `write_ghosts`:\\[in\\] If true, write out ghost elements as well. -* `num_data`:\\[in\\] Number of user defined double valued data fields to write. -* `data`:\\[in\\] Array of [`t8_vtk_data_field_t`](@ref) of length *num_data* providing the user defined per element data. If scalar and vector fields are used, all scalar fields must come first in the array. -# Returns -True if successful, false if not (process local). +* `element`:\\[in\\] Input triangle. +* `vertex`:\\[in\\] The number of the vertex. +* `coordinates`:\\[out\\] An array of 2 double that will be filled with the reference coordinates of the vertex. ### Prototype ```c -int t8_forest_vtk_write_file_via_API (t8_forest_t forest, const char *fileprefix, const int write_treeid, const int write_mpirank, const int write_level, const int write_element_id, const int curved_flag, const int write_ghosts, const int num_data, t8_vtk_data_field_t *data); +void t8_dtri_compute_vertex_ref_coords (const t8_dtri_t *element, const int vertex, double coordinates[2]); ``` """ -function t8_forest_vtk_write_file_via_API(forest, fileprefix, write_treeid, write_mpirank, write_level, write_element_id, curved_flag, write_ghosts, num_data, data) - @ccall libt8.t8_forest_vtk_write_file_via_API(forest::t8_forest_t, fileprefix::Cstring, write_treeid::Cint, write_mpirank::Cint, write_level::Cint, write_element_id::Cint, curved_flag::Cint, write_ghosts::Cint, num_data::Cint, data::Ptr{t8_vtk_data_field_t})::Cint +function t8_dtri_compute_vertex_ref_coords(element, vertex, coordinates) + @ccall libt8.t8_dtri_compute_vertex_ref_coords(element::Ptr{t8_dtri_t}, vertex::Cint, coordinates::Ptr{Cdouble})::Cvoid end """ - t8_forest_vtk_write_file(forest, fileprefix, write_treeid, write_mpirank, write_level, write_element_id, write_ghosts, num_data, data) + t8_dtri_compute_reference_coords(element, ref_coords, num_coords, skip_coords, out_coords) -Write the forest in .pvtu file format. Writes one .vtu file per process and a meta .pvtu file. This function writes ASCII files and can be used when t8code is not configured with "-DT8CODE\\_ENABLE\\_VTK=ON" and t8_forest_vtk_write_file_via_API is not available. +Convert points in the reference space of a tri element to points in the reference space of the tree (level 0) embedded in + +```c++ + [0,1]^2 +``` + +. + +```c++ + [0,1]^2 +``` + +) # Arguments -* `forest`:\\[in\\] The forest. -* `fileprefix`:\\[in\\] The prefix of the output files. -* `write_treeid`:\\[in\\] If true, the global tree id is written for each element. -* `write_mpirank`:\\[in\\] If true, the mpirank is written for each element. -* `write_level`:\\[in\\] If true, the refinement level is written for each element. -* `write_element_id`:\\[in\\] If true, the global element id is written for each element. -* `write_ghosts`:\\[in\\] If true, each process additionally writes its ghost elements. For ghost element the treeid is -1. -* `num_data`:\\[in\\] Number of user defined double valued data fields to write. -* `data`:\\[in\\] Array of [`t8_vtk_data_field_t`](@ref) of length *num_data* providing the used defined per element data. If scalar and vector fields are used, all scalar fields must come first in the array. -# Returns -True if successful, false if not (process local). +* `element`:\\[in\\] Input triangle. +* `ref_coords`:\\[in\\] The reference coordinates in the triangle (*num_coords* times +* `num_coords`:\\[in\\] Number of coordinates to evaluate +* `skip_coords`:\\[in\\] Only used for batch computation of prisms. In all other cases 0. Skip coordinates in the *ref_coords* and *out_coords* array. +* `out_coords`:\\[out\\] An array of *num_coords* x 2 x double that will be filled with the reference coordinates of the points on the triangle. ### Prototype ```c -int t8_forest_vtk_write_file (t8_forest_t forest, const char *fileprefix, const int write_treeid, const int write_mpirank, const int write_level, const int write_element_id, int write_ghosts, const int num_data, t8_vtk_data_field_t *data); +void t8_dtri_compute_reference_coords (const t8_dtri_t *element, const double *ref_coords, const size_t num_coords, const size_t skip_coords, double *out_coords); ``` """ -function t8_forest_vtk_write_file(forest, fileprefix, write_treeid, write_mpirank, write_level, write_element_id, write_ghosts, num_data, data) - @ccall libt8.t8_forest_vtk_write_file(forest::t8_forest_t, fileprefix::Cstring, write_treeid::Cint, write_mpirank::Cint, write_level::Cint, write_element_id::Cint, write_ghosts::Cint, num_data::Cint, data::Ptr{t8_vtk_data_field_t})::Cint +function t8_dtri_compute_reference_coords(element, ref_coords, num_coords, skip_coords, out_coords) + @ccall libt8.t8_dtri_compute_reference_coords(element::Ptr{t8_dtri_t}, ref_coords::Ptr{Cdouble}, num_coords::Csize_t, skip_coords::Csize_t, out_coords::Ptr{Cdouble})::Cvoid end """ - t8_cmesh_vtk_write_file_via_API(cmesh, fileprefix, comm) + t8_dtri_compute_all_coords(element, coordinates) + +Compute the coordinates of the four vertices of a triangle. +# Arguments +* `element`:\\[in\\] Input triangle. +* `coordinates`:\\[out\\] An array of 4x3 [`t8_dtri_coord_t`](@ref) that will be filled with the coordinates of t's vertices. ### Prototype ```c -int t8_cmesh_vtk_write_file_via_API (t8_cmesh_t cmesh, const char *fileprefix, sc_MPI_Comm comm); +void t8_dtri_compute_all_coords (const t8_dtri_t *element, t8_dtri_coord_t coordinates[3][2]); ``` """ -function t8_cmesh_vtk_write_file_via_API(cmesh, fileprefix, comm) - @ccall libt8.t8_cmesh_vtk_write_file_via_API(cmesh::t8_cmesh_t, fileprefix::Cstring, comm::MPI_Comm)::Cint +function t8_dtri_compute_all_coords(element, coordinates) + @ccall libt8.t8_dtri_compute_all_coords(element::Ptr{t8_dtri_t}, coordinates::Ptr{NTuple{2, t8_dtri_coord_t}})::Cvoid end """ - t8_cmesh_vtk_write_file(cmesh, fileprefix) + t8_dtri_child(element, childid, child) -Write the cmesh in .pvtu file format. Writes one .vtu file per process and a meta .pvtu file. This function writes ASCII files and can be used when t8code is not configured with "-DT8CODE\\_ENABLE\\_VTK=ON" and t8_cmesh_vtk_write_file_via_API is not available. +Compute the childid-th child in Morton order of a triangle. # Arguments -* `cmesh`:\\[in\\] The cmesh -* `fileprefix`:\\[in\\] The prefix of the output files -# Returns -True (nonzero) if successful, false (zero) otherwise +* `element`:\\[in\\] Input triangle. +* `childid`:\\[in,out\\] The id of the child, 0..7 in Morton order. +* `child`:\\[out\\] Existing triangle whose data will be filled with the date of t's childid-th child. ### Prototype ```c -int t8_cmesh_vtk_write_file (t8_cmesh_t cmesh, const char *fileprefix); +void t8_dtri_child (const t8_dtri_t *element, int childid, t8_dtri_t *child); ``` """ -function t8_cmesh_vtk_write_file(cmesh, fileprefix) - @ccall libt8.t8_cmesh_vtk_write_file(cmesh::t8_cmesh_t, fileprefix::Cstring)::Cint +function t8_dtri_child(element, childid, child) + @ccall libt8.t8_dtri_child(element::Ptr{t8_dtri_t}, childid::Cint, child::Ptr{t8_dtri_t})::Cvoid end """ - t8_cmesh_from_msh_file(fileprefix, partition, comm, dim, master, use_cad_geometry) + t8_dtri_childrenpv(element, children) +Compute the 4 children of a triangle, array version. + +# Arguments +* `element`:\\[in\\] Input triangle. +* `children`:\\[in,out\\] Pointers to the 4 computed children in Morton order. t may point to the same quadrant as c[0]. ### Prototype ```c -t8_cmesh_t t8_cmesh_from_msh_file (const char *fileprefix, int partition, sc_MPI_Comm comm, int dim, int master, int use_cad_geometry); +void t8_dtri_childrenpv (const t8_dtri_t *element, t8_dtri_t *children[T8_DTRI_CHILDREN]); ``` """ -function t8_cmesh_from_msh_file(fileprefix, partition, comm, dim, master, use_cad_geometry) - @ccall libt8.t8_cmesh_from_msh_file(fileprefix::Cstring, partition::Cint, comm::MPI_Comm, dim::Cint, master::Cint, use_cad_geometry::Cint)::t8_cmesh_t +function t8_dtri_childrenpv(element, children) + @ccall libt8.t8_dtri_childrenpv(element::Ptr{t8_dtri_t}, children::Ptr{Ptr{t8_dtri_t}})::Cvoid end -mutable struct t8_cmesh_vertex_connectivity end - """ -[`t8_cmesh_vertex_connectivity_c`](@ref) + t8_dtri_is_familypv(f) -Opaque pointer to the cmesh vertex connectivity structure. +Check whether a collection of eight triangles is a family in Morton order. + +# Arguments +* `f`:\\[in\\] An array of eight triangles. +# Returns +Nonzero if *f* is a family of triangles. +### Prototype +```c +int t8_dtri_is_familypv (const t8_dtri_t *f[]); +``` """ -const t8_cmesh_vertex_connectivity_c = Ptr{t8_cmesh_vertex_connectivity} +function t8_dtri_is_familypv(f) + @ccall libt8.t8_dtri_is_familypv(f::Ptr{Ptr{t8_dtri_t}})::Cint +end """ - t8_cmesh_set_global_vertices_of_tree(cmesh, global_tree, global_tree_vertices, num_vertices) + t8_dtri_sibling(element, sibid, sibling) +Compute a specific sibling of a triangle. + +# Arguments +* `element`:\\[in\\] Input triangle. +* `sibid`:\\[in\\] The id of the sibling computed, 0..7 in Bey order. +* `sibling`:\\[in,out\\] Existing triangle whose data will be filled with the data of sibling no. sibling\\_id of *element*. ### Prototype ```c -void t8_cmesh_set_global_vertices_of_tree (const t8_cmesh_t cmesh, const t8_gloidx_t global_tree, const t8_gloidx_t *global_tree_vertices, const int num_vertices); +void t8_dtri_sibling (const t8_dtri_t *element, int sibid, t8_dtri_t *sibling); ``` """ -function t8_cmesh_set_global_vertices_of_tree(cmesh, global_tree, global_tree_vertices, num_vertices) - @ccall libt8.t8_cmesh_set_global_vertices_of_tree(cmesh::Cint, global_tree::Cint, global_tree_vertices::Ptr{Cint}, num_vertices::Cint)::Cvoid +function t8_dtri_sibling(element, sibid, sibling) + @ccall libt8.t8_dtri_sibling(element::Ptr{t8_dtri_t}, sibid::Cint, sibling::Ptr{t8_dtri_t})::Cvoid end """ - t8_cmesh_get_num_global_vertices(cmesh) + t8_dtri_face_neighbour(element, face, neigh) + +Compute the face neighbor of a triangle. + +!!! note + + *element* may point to the same triangle as *neigh*. +# Arguments +* `element`:\\[in\\] Input triangle. +* `face`:\\[in\\] The face across which to generate the neighbor. +* `neigh`:\\[in,out\\] Existing triangle whose data will be filled. ### Prototype ```c -t8_gloidx_t t8_cmesh_get_num_global_vertices (const t8_cmesh_t cmesh); +int t8_dtri_face_neighbour (const t8_dtri_t *element, int face, t8_dtri_t *neigh); ``` """ -function t8_cmesh_get_num_global_vertices(cmesh) - @ccall libt8.t8_cmesh_get_num_global_vertices(cmesh::Cint)::Cint +function t8_dtri_face_neighbour(element, face, neigh) + @ccall libt8.t8_dtri_face_neighbour(element::Ptr{t8_dtri_t}, face::Cint, neigh::Ptr{t8_dtri_t})::Cint end """ - t8_cmesh_get_num_local_vertices(cmesh) + t8_dtri_nearest_common_ancestor(element1, element2, nca) + +Computes the nearest common ancestor of two triangles in the same tree. + +!!! note + *element1*, *element2*, *nca* may point to the same quadrant. + +# Arguments +* `element1`:\\[in\\] First input triangle. +* `element2`:\\[in\\] Second input triangle. +* `nca`:\\[in,out\\] Existing triangle whose data will be filled. ### Prototype ```c -t8_locidx_t t8_cmesh_get_num_local_vertices (const t8_cmesh_t cmesh); +void t8_dtri_nearest_common_ancestor (const t8_dtri_t *element1, const t8_dtri_t *element2, t8_dtri_t *nca); ``` """ -function t8_cmesh_get_num_local_vertices(cmesh) - @ccall libt8.t8_cmesh_get_num_local_vertices(cmesh::Cint)::Cint +function t8_dtri_nearest_common_ancestor(element1, element2, nca) + @ccall libt8.t8_dtri_nearest_common_ancestor(element1::Ptr{t8_dtri_t}, element2::Ptr{t8_dtri_t}, nca::Ptr{t8_dtri_t})::Cvoid end """ - t8_cmesh_get_global_vertices_of_tree(cmesh, local_tree, num_vertices) + t8_dtri_children_at_face(element, face, children, num_children, child_indices) +Given a triangle and a face of the triangle, compute all children of the triangle that touch the face. + +# Arguments +* `element`:\\[in\\] The triangle. +* `face`:\\[in\\] A face of *element*. +* `children`:\\[in,out\\] Allocated triangles, in which the children of *element* that share a face with *face* are stored. They will be stored in order of their child\\_id. +* `num_children`:\\[in\\] The number of triangles in *children*. Must match the number of children that touch *face*. +* `child_indices`:\\[in,out\\] The indices of the children in *children*. Only filled if this is null previously. ### Prototype ```c -const t8_gloidx_t * t8_cmesh_get_global_vertices_of_tree (const t8_cmesh_t cmesh, const t8_locidx_t local_tree, int *num_vertices); +void t8_dtri_children_at_face (const t8_dtri_t *element, int face, t8_dtri_t *children[], int num_children, int *child_indices); ``` """ -function t8_cmesh_get_global_vertices_of_tree(cmesh, local_tree, num_vertices) - @ccall libt8.t8_cmesh_get_global_vertices_of_tree(cmesh::Cint, local_tree::Cint, num_vertices::Ptr{Cint})::Ptr{Cint} +function t8_dtri_children_at_face(element, face, children, num_children, child_indices) + @ccall libt8.t8_dtri_children_at_face(element::Ptr{t8_dtri_t}, face::Cint, children::Ptr{Ptr{t8_dtri_t}}, num_children::Cint, child_indices::Ptr{Cint})::Cvoid end """ - t8_cmesh_get_global_vertex_of_tree(cmesh, local_tree, local_tree_vertex) + t8_dtri_face_child_face(triangle, face, face_child) + +Given a face of a triangle and a child number of a child of that face, return the face number of the child of the triangle that matches the child face. +# Arguments +* `triangle`:\\[in\\] The triangle. +* `face`:\\[in\\] Then number of the face. +* `face_child`:\\[in\\] The child number of a child of the face triangle. +# Returns +The face number of the face of a child of *triangle* that coincides with *face_child*. ### Prototype ```c -t8_gloidx_t t8_cmesh_get_global_vertex_of_tree (const t8_cmesh_t cmesh, const t8_locidx_t local_tree, const int local_tree_vertex); +int t8_dtri_face_child_face (const t8_dtri_t *triangle, int face, int face_child); ``` """ -function t8_cmesh_get_global_vertex_of_tree(cmesh, local_tree, local_tree_vertex) - @ccall libt8.t8_cmesh_get_global_vertex_of_tree(cmesh::Cint, local_tree::Cint, local_tree_vertex::Cint)::Cint +function t8_dtri_face_child_face(triangle, face, face_child) + @ccall libt8.t8_dtri_face_child_face(triangle::Ptr{t8_dtri_t}, face::Cint, face_child::Cint)::Cint end """ - t8_cmesh_get_num_trees_at_vertex(cmesh, global_vertex) + t8_dtri_face_parent_face(triangle, face) + +Given a face of an triangle return the face number of the parent of the triangle that matches the triangle's face. Or return -1 if no face of the parent matches the face. +# Arguments +* `triangle`:\\[in\\] The triangle. +* `face`:\\[in\\] Then number of the face. +# Returns +If *face* of *elem* is also a face of *elem*'s parent, the face number of this face. Otherwise -1. ### Prototype ```c -int t8_cmesh_get_num_trees_at_vertex (const t8_cmesh_t cmesh, t8_gloidx_t global_vertex); +int t8_dtri_face_parent_face (const t8_dtri_t *triangle, int face); ``` """ -function t8_cmesh_get_num_trees_at_vertex(cmesh, global_vertex) - @ccall libt8.t8_cmesh_get_num_trees_at_vertex(cmesh::Cint, global_vertex::Cint)::Cint +function t8_dtri_face_parent_face(triangle, face) + @ccall libt8.t8_dtri_face_parent_face(triangle::Ptr{t8_dtri_t}, face::Cint)::Cint end """ - t8_cmesh_uses_vertex_connectivity(cmesh) + t8_dtri_tree_face(element, face) + +Given a triangle and a face of this triangle. If the face lies on the tree boundary, return the face number of the tree face. If not the return value is arbitrary. + +!!! note + For boundary triangles, this function is the inverse of t8_dtri_root_face_to_face + +# Arguments +* `element`:\\[in\\] The triangle. +* `face`:\\[in\\] The index of a face of *element*. +# Returns +The index of the tree face that *face* is a subface of, if *face* is on a tree boundary. Any arbitrary integer if *element* is not at a tree boundary. ### Prototype ```c -int t8_cmesh_uses_vertex_connectivity (const t8_cmesh_t cmesh); +int t8_dtri_tree_face (t8_dtri_t *element, int face); ``` """ -function t8_cmesh_uses_vertex_connectivity(cmesh) - @ccall libt8.t8_cmesh_uses_vertex_connectivity(cmesh::Cint)::Cint +function t8_dtri_tree_face(element, face) + @ccall libt8.t8_dtri_tree_face(element::Ptr{t8_dtri_t}, face::Cint)::Cint end -# typedef int ( * t8_search_element_callback_c_wrapper ) ( t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index , void * user_data ) """ -A call-back function used by t8_forest_init_search for searching elements. Is called on an element and the search criterion should be checked on that element. Return true if the search criterion is met, false otherwise. + t8_dtri_root_face_to_face(element, root_face) + +Given a triangle and a face of the root triangle. If the triangle lies on the tree boundary, return the corresponding face number of the triangle. If not the return value is arbitrary. + +!!! note + + For boundary triangles, this function is the inverse of t8_dtri_tree_face # Arguments -* `forest`:\\[in\\] the forest -* `ltreeid`:\\[in\\] the local tree id of the current tree in the cmesh. -* `element`:\\[in\\] the element for which the search criterion is checked -* `is_leaf`:\\[in\\] true if and only if *element* is a leaf element -* `leaf_elements`:\\[in\\] the leaf elements in *forest* -* `tree_leaf_index`:\\[in\\] the local index of the first leaf in *leaf_elements* -* `user_data`:\\[in\\] a user data pointer that can be set by the user +* `element`:\\[in\\] The triangle. +* `root_face`:\\[in\\] The index of a face of the root element. # Returns -non-zero if the search criterion is met, zero otherwise. +The index of the face of *element* that is a subface of *root_face*, if *element* is on the tree boundary. Any arbitrary integer if *element* is not at a tree boundary. +### Prototype +```c +int t8_dtri_root_face_to_face (t8_dtri_t *element, int root_face); +``` """ -const t8_search_element_callback_c_wrapper = Ptr{Cvoid} +function t8_dtri_root_face_to_face(element, root_face) + @ccall libt8.t8_dtri_root_face_to_face(element::Ptr{t8_dtri_t}, root_face::Cint)::Cint +end -# typedef int ( * t8_search_queries_callback_c_wrapper ) ( t8_forest_t forest , const t8_locidx_t ltreeid , const t8_element_t * element , const int is_leaf , const t8_element_array_t * leaf_elements , const t8_locidx_t tree_leaf_index , void * queries , void * user_data ) """ -A call-back function used by t8_forest_init_search_with_queries for searching elements and executing queries. Is called on an element and all queries are checked on that element. All positive queries are passed further down to the children of the element up to leaf elements of the tree. The results of the check are stored in *query_matches*. + t8_dtri_transform_face(trianglein, triangle2, orientation, sign, is_smaller_face) + +Suppose we have two trees that share a common triangle f. Given a triangle e that is a subface of f in one of the trees and given the orientation of the tree connection, construct the face triangle of the respective tree neighbor that logically coincides with e but lies in the coordinate system of the neighbor tree. + +!!! note + + *trianglein* and *triangle2* may point to the same element. # Arguments -* `forest`:\\[in\\] the forest -* `ltreeid`:\\[in\\] the local tree id of the current tree in the cmesh. -* `element`:\\[in\\] the element for which the search criterion is checked -* `is_leaf`:\\[in\\] true if and only if *element* is a leaf element -* `leaf_elements`:\\[in\\] the leaf elements in *forest* -* `tree_leaf_index`:\\[in\\] the local index of the first leaf in *leaf_elements* -* `queries`:\\[in\\] a pointer to an array of queries -* `user_data`:\\[in\\] a user data pointer that can be set by the user -""" -const t8_search_queries_callback_c_wrapper = Ptr{Cvoid} +* `trianglein`:\\[in\\] The face triangle. +* `triangle2`:\\[in,out\\] On return the face triangle *triangle1* with respective to the coordinate system of the other tree. +* `orientation`:\\[in\\] The orientation of the tree-tree connection. +* `sign`:\\[in\\] Depending on the topological orientation of the two tree faces, either 0 (both faces have opposite orientation) or 1 (both faces have the same top. orientation). t8_eclass_face_orientation +* `is_smaller_face`:\\[in\\] Flag to declare whether *triangle1* belongs to the smaller face. A face f of tree T is smaller than f' of T' if either the eclass of T is smaller or if the classes are equal and f