Feature: SFC-Based Tree Indexing

src/CMakeLists.txt

@@ -151,6 +151,7 @@ target_sources( T8 PRIVATE
     t8_cmesh/t8_cmesh_internal/t8_cmesh_partition.cxx
     t8_cmesh/t8_cmesh_internal/t8_cmesh_stash.c
     t8_cmesh/t8_cmesh_internal/t8_cmesh_trees.cxx
+    t8_cmesh/t8_cmesh_internal/t8_cmesh_tree_reindex.cxx
     t8_cmesh/t8_cmesh_vertex_connectivity/t8_cmesh_vertex_conn_tree_to_vertex.cxx
     t8_cmesh/t8_cmesh_vertex_connectivity/t8_cmesh_vertex_conn_vertex_to_tree.cxx
     t8_cmesh/t8_cmesh_vertex_connectivity/t8_cmesh_vertex_connectivity.cxx

src/t8_cmesh/t8_cmesh.cxx

@@ -152,6 +152,12 @@ t8_cmesh_disable_negative_volume_check ([[maybe_unused]] t8_cmesh_t cmesh)
 #endif
 }
 
+void
+t8_cmesh_enable_tree_reordering (t8_cmesh_t cmesh)
+{
+  cmesh->reindex_trees = 1;
+}
+
 #if T8_ENABLE_DEBUG
 int
 t8_cmesh_validate_geometry (const t8_cmesh_t cmesh, const int check_for_negative_volume)
@@ -239,6 +245,7 @@ t8_cmesh_init (t8_cmesh_t *pcmesh)
 #if T8_ENABLE_DEBUG
   cmesh->negative_volume_check = 1;
 #endif /* T8_ENABLE_DEBUG */
+  cmesh->reindex_trees = 0;
 
   T8_ASSERT (t8_cmesh_is_initialized (cmesh));
 }

src/t8_cmesh/t8_cmesh.h

@@ -132,6 +132,13 @@ t8_cmesh_stash_is_empty (const t8_cmesh_t cmesh);
 void
 t8_cmesh_disable_negative_volume_check (t8_cmesh_t cmesh);
 
+/**
+ * Enable localitly based indexing of trees during \ref t8_cmesh_commit.
+ * \param [in, out] cmesh 
+ */
+void
+t8_cmesh_enable_tree_reordering (t8_cmesh_t cmesh);
+
 #if T8_ENABLE_DEBUG
 /** Check the geometry of the mesh for validity, this means checking if trees and their geometries
  *  are compatible and if they have negative volume.
@@ -140,7 +147,6 @@ t8_cmesh_disable_negative_volume_check (t8_cmesh_t cmesh);
  * \return                                True if the geometry of the cmesh is valid.
  */
 int
-
 t8_cmesh_validate_geometry (const t8_cmesh_t cmesh, const int check_for_negative_volume);
 #endif
 

src/t8_cmesh/t8_cmesh_internal/t8_cmesh_commit.cxx

@@ -36,6 +36,7 @@
 #include <t8_cmesh/t8_cmesh_geometry.hxx>
 #include <t8_geometry/t8_geometry_handler.hxx>
 #include <t8_cmesh/t8_cmesh_vertex_connectivity/t8_cmesh_vertex_connectivity.hxx>
+#include <t8_cmesh/t8_cmesh_internal/t8_cmesh_tree_reindex.hxx>
 
 /**
  * A struct to hold the information about a ghost facejoin.
@@ -148,6 +149,10 @@ t8_cmesh_commit_replicated_new (t8_cmesh_t cmesh)
     t8_stash_class_struct_t *entry;
     t8_locidx_t num_trees = class_entries->elem_count, ltree;
 
+    if (cmesh->reindex_trees) {
+      t8_cmesh_tree_perform_reindex_inplace (stash, t8_cmesh_reindex_tree (cmesh));
+    }
+
     t8_cmesh_trees_init (&cmesh->trees, 1, num_trees, 0);
     t8_cmesh_trees_start_part (cmesh->trees, 0, 0, num_trees, 0, 0, 1);
     /* set tree classes */

src/t8_cmesh/t8_cmesh_internal/t8_cmesh_tree_reindex.hxx

@@ -0,0 +1,64 @@
+/*
+  This file is part of t8code.
+  t8code is a C library to manage a collection (a forest) of multiple
+  connected adaptive space-trees of general element classes in parallel.
+
+  Copyright (C) 2026 the developers
+
+  t8code is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  t8code is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with t8code; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+#ifndef T8_CMESH_REINDEX_TREES_H
+#define T8_CMESH_REINDEX_TREES_H
+
+#include <t8.h>
+#include <t8_cmesh/t8_cmesh.h>
+#include <t8_cmesh/t8_cmesh_internal/t8_cmesh_types.h>
+#include <map>
+
+/**
+ * Compute a spatially coherent reindexing of the coarse mesh trees.
+ *
+ * Constructs an auxiliary bounding box forest containing the centers of the
+ * original coarse mesh trees. The forest is adaptively refined until each
+ * leaf element contains at most one tree center. The leaves are then traversed
+ * in SFC order to assign new indices to the original trees.
+ *
+ * \param [in] cmesh  The original coarse mesh whose trees are to be reindexed.
+ * \param [in] comm   MPI communicator used to construct the auxiliary forest.
+ *
+ * \return A map from the original global tree IDs to their new SFC-based indices.
+ *
+ * \note This function only computes the reindexing and does not modify the
+ *       original coarse mesh.
+ */
+
+std::map<t8_gloidx_t, t8_gloidx_t>
+t8_cmesh_reindex_tree (t8_cmesh_t cmesh, sc_MPI_Comm comm = sc_MPI_COMM_SELF);
+
+/**
+ * Apply a tree reindexing to the coarse mesh stash in place.
+ *
+ * Updates the tree IDs stored in the stash according to the given mapping,
+ * allowing the coarse mesh to use the newly computed tree ordering.
+ *
+ * \param [in,out] stash         The coarse mesh stash to be modified.
+ * \param [in]     tree_reindex  Mapping from original global tree IDs to
+ *                              their new indices.
+ */
+void
+t8_cmesh_tree_perform_reindex_inplace (t8_stash_t &stash, const std::map<t8_gloidx_t, t8_gloidx_t> &tree_reindex);
+
+#endif /* !T8_CMESH_REINDEX_TREES_H */

src/t8_cmesh/t8_cmesh_internal/t8_cmesh_types.h

@@ -99,6 +99,8 @@ typedef struct t8_cmesh
   int face_knowledge; /**< If partitioned the level of face knowledge that is expected.
 */
 
+  int reindex_trees; /**< If nonzero the trees will be indexed according to their geometric locality */
+
   const t8_scheme_c *set_partition_scheme; /**< If the cmesh is to be partitioned according to a uniform level,
                                                 the scheme that describes the refinement pattern. */
   int8_t set_partition_level;  /**< Non-negative if the cmesh should be partitioned from an already existing cmesh

test/CMakeLists.txt

@@ -135,6 +135,7 @@ add_t8_cpp_test( NAME t8_gtest_cmesh_add_attributes_when_derive_parallel    SOUR
 add_t8_cpp_test( NAME t8_gtest_cmesh_vertex_conn_tree_to_vertex_parallel    SOURCES t8_cmesh/t8_gtest_cmesh_vertex_conn_tree_to_vertex.cxx )
 add_t8_cpp_test( NAME t8_gtest_cmesh_vertex_conn_vertex_to_tree_parallel    SOURCES t8_cmesh/t8_gtest_cmesh_vertex_conn_vertex_to_tree.cxx )
 add_t8_cpp_test( NAME t8_gtest_cmesh_vertex_conn_serial                     SOURCES t8_cmesh/t8_gtest_cmesh_vertex_conn.cxx )
+add_t8_cpp_test( NAME t8_gtest_cmesh_tree_reindex_serial                    SOURCES t8_cmesh/t8_gtest_cmesh_tree_reindex.cxx)
 add_t8_cpp_test( NAME t8_gtest_multiple_attributes_parallel                 SOURCES t8_cmesh/t8_gtest_multiple_attributes.cxx )
 add_t8_cpp_test( NAME t8_gtest_attribute_gloidx_array_serial                SOURCES t8_cmesh/t8_gtest_attribute_gloidx_array.cxx )
 add_t8_cpp_test( NAME t8_gtest_cmesh_bounding_box_serial                    SOURCES t8_cmesh/t8_gtest_cmesh_bounding_box.cxx )