Feature: SFC-Based Tree Indexing

src/CMakeLists.txt

@@ -164,6 +164,7 @@ target_sources( T8 PRIVATE
     t8_cmesh/t8_cmesh_internal/t8_cmesh_partition.cxx
     t8_cmesh/t8_cmesh_internal/t8_cmesh_stash.cxx
     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

@@ -153,6 +153,21 @@ t8_cmesh_disable_negative_volume_check ([[maybe_unused]] t8_cmesh_t cmesh)
 #endif
 }
 
+void
+t8_cmesh_enable_tree_reordering (t8_cmesh_t cmesh, const int keep_reindex_map)
+{
+  T8_ASSERT (t8_cmesh_is_initialized (cmesh));
+  cmesh->reindex_trees = 1;
+  cmesh->keep_reindex_map = keep_reindex_map;
+}
+
+const t8_gloidx_t *
+t8_cmesh_get_tree_reindex_map (const t8_cmesh_t cmesh)
+{
+  T8_ASSERT (t8_cmesh_is_committed (cmesh));
+  return cmesh->tree_reindex_map;
+}
+
 #if T8_ENABLE_DEBUG
 int
 t8_cmesh_validate_geometry (const t8_cmesh_t cmesh, const int check_for_negative_volume)
@@ -240,7 +255,9 @@ t8_cmesh_init (t8_cmesh_t *pcmesh)
 #if T8_ENABLE_DEBUG
   cmesh->negative_volume_check = 1;
 #endif /* T8_ENABLE_DEBUG */
-
+  cmesh->reindex_trees = 0;
+  cmesh->keep_reindex_map = 0;
+  cmesh->tree_reindex_map = nullptr;
   T8_ASSERT (t8_cmesh_is_initialized (cmesh));
 }
 
@@ -1248,6 +1265,11 @@ t8_cmesh_reset (t8_cmesh_t *pcmesh)
     cmesh->set_partition_scheme->unref ();
   }
 
+  /* Release the optional tree-ID mapping owned by the coarse mesh. */
+  if (cmesh->tree_reindex_map != nullptr) {
+    T8_FREE (cmesh->tree_reindex_map);
+  }
+
   delete cmesh->vertex_connectivity;
   delete cmesh->boundary_condition_handler;
 
@@ -2261,8 +2283,8 @@ t8_cmesh_uniform_bounds_from_partition (const t8_cmesh_t cmesh, const t8_gloidx_
 #endif
 
       } /* End sending of end message */
-    }   /* End loop over processes */
-  }     /* if (num_pure_local_trees > 0) */
+    } /* End loop over processes */
+  } /* if (num_pure_local_trees > 0) */
 
   if (this_proc_is_empty) {
     /* If this proc is empty, we only expect a start message.

src/t8_cmesh/t8_cmesh.h

@@ -132,6 +132,22 @@ t8_cmesh_stash_is_empty (const t8_cmesh_t cmesh);
 void
 t8_cmesh_disable_negative_volume_check (t8_cmesh_t cmesh);
 
+/** Enable locality-based coarse-tree reordering during \ref t8_cmesh_commit.
+ * \param [in,out] cmesh             An initialized, uncommitted coarse mesh.
+ * \param [in]     keep_reindex_map  Nonzero to retain an old-to-new tree-ID mapping after commit.
+ * \note Enable on every process participating in commit. Stash records are gathered on rank zero,
+ *       reordered there, and broadcast. Partition ranges and offsets refer to the reordered tree IDs.
+ */
+void
+t8_cmesh_enable_tree_reordering (t8_cmesh_t cmesh, int keep_reindex_map);
+
+/** Return the stored old-to-new tree-ID mapping.
+ * \param [in] cmesh  A committed coarse mesh.
+ * \return            Read-only array indexed by the old global tree ID, or nullptr if none was retained.
+ *                    The array has t8_cmesh_get_num_trees(cmesh) entries and remains owned by \a cmesh.
+ */
+const t8_gloidx_t *
+t8_cmesh_get_tree_reindex_map (const 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 +156,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_internal/t8_cmesh_geometry_internal.hxx>
 #include <t8_cmesh/t8_cmesh_geometry.hxx>
 #include <t8_cmesh/t8_cmesh_vertex_connectivity/t8_cmesh_vertex_connectivity.hxx>
+#include <t8_cmesh/t8_cmesh_internal/t8_cmesh_tree_reindex.hxx>
 #include <t8_cmesh/t8_cmesh_boundary_conditions/internal/t8_cmesh_boundary_condition_handler.hxx>
 
 /**
@@ -545,6 +546,10 @@ t8_cmesh_commit_from_stash (t8_cmesh_t cmesh, sc_MPI_Comm comm)
   }
 #endif
 
+  if (cmesh->reindex_trees) {
+    t8_cmesh_reindex_trees (cmesh, comm);
+  }
+
   if (cmesh->set_partition) {
     /* partitioned commit */
     t8_cmesh_commit_partitioned_new (cmesh, comm);

src/t8_cmesh/t8_cmesh_internal/t8_cmesh_tree_reindex.hxx

@@ -0,0 +1,76 @@
+/*
+  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.
+*/
+
+/** \file t8_cmesh_tree_reindex.hxx
+ * Internal declarations for reindexing coarse trees by geometric locality.
+ */
+
+#ifndef T8_CMESH_TREE_REINDEX_HXX
+#define T8_CMESH_TREE_REINDEX_HXX
+
+#include <t8_cmesh/t8_cmesh.h>
+#include <t8_cmesh/t8_cmesh_internal/t8_cmesh_stash.h>
+
+#include <map>
+
+/** Calculate the old-to-new coarse-tree ID mapping from the auxiliary forest's SFC order.
+ *
+ * The tree centers are computed from the vertex attributes of all coarse trees.
+ * The auxiliary forest is adapted until its leaves isolate the centers or reach
+ * the maximum refinement level. Multiple centers in one terminal leaf are ordered
+ * by their original global tree IDs.
+ *
+ * \param [in] cmesh  Uncommitted coarse mesh with a complete replicated stash.
+ * \param [in] comm   Communicator used for the auxiliary forest. Defaults to MPI self.
+ * \return            Map from original global tree ID to its new SFC-based ID.
+ *
+ * \note This function only calculates the permutation and does not modify \a cmesh.
+ */
+std::map<t8_gloidx_t, t8_gloidx_t>
+t8_cmesh_calculate_tree_reindexing_map (t8_cmesh_t cmesh, sc_MPI_Comm comm = sc_MPI_COMM_SELF);
+
+/** Apply an already calculated old-to-new tree-ID permutation to a stash.
+ * Changes tree classes, attributes, and both endpoints of every face join, then
+ * restores the canonical ordering of the stash entries.
+ *
+ * \param [in,out] stash         Stash containing the tree records to reindex.
+ * \param [in]     tree_reindex  Map from old global IDs to new global IDs.
+ */
+void
+t8_cmesh_tree_perform_reindex_inplace (t8_stash_t &stash, const std::map<t8_gloidx_t, t8_gloidx_t> &tree_reindex);
+
+/** Calculate and apply SFC-based coarse-tree reindexing.
+ *
+ * Gathers the stash on rank zero, calls \ref t8_cmesh_calculate_tree_reindexing_map and
+ * \ref t8_cmesh_tree_perform_reindex_inplace there, then broadcasts the reordered stash.
+ * If requested with
+ * \ref t8_cmesh_enable_tree_reordering, the original-to-new mapping is
+ * retained in the coarse mesh for retrieval after commit.
+ *
+ * \param [in,out] cmesh  Uncommitted coarse mesh with replicated or distributed stash records.
+ * \param [in]     comm   Communicator on which all processes participate in reindexing.
+ * \note For partitioned coarse meshes, partition ranges and offsets refer to the reordered tree IDs.
+ */
+void
+t8_cmesh_reindex_trees (t8_cmesh_t cmesh, sc_MPI_Comm comm);
+
+#endif /* T8_CMESH_TREE_REINDEX_HXX */

src/t8_cmesh/t8_cmesh_internal/t8_cmesh_types.h

@@ -101,6 +101,10 @@ 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 */
+  int keep_reindex_map;          /**< Retain the old-to-new tree-ID mapping after commit if nonzero. */
+  t8_gloidx_t *tree_reindex_map; /**< Retained mapping indexed by original global tree ID, or nullptr. */
+
   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

@@ -136,6 +136,8 @@ 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_cmesh_tree_reindex_parallel                  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 )