add dfuds implementation and tests

Author: Sanya239

.github/workflows/build-test.yml

@@ -32,6 +32,10 @@ jobs:
       working-directory: ./build
       run: ./louds_tree_tests
 
+    - name: Run DFUDS Tree Tests
+      working-directory: ./build
+      run: ./dfuds_tree_tests
+
     - name: Run Benchmark Tests
       working-directory: ./build
       run: ./benchmark_tests
@@ -92,3 +96,15 @@ jobs:
         fi
         exit $rc
 
+    - name: Run DFUDS Tree Tests
+      working-directory: ./build
+      run: |
+        timeout 1800 sde-external-9.58.0-2025-06-16-lin/sde64 -icl -emu-xinuse 0 -- \
+          ./dfuds_tree_tests --gtest_output=xml:dfuds_results.xml
+        rc=$?
+        if [ $rc -eq 124 ] && grep -q 'failures="0"' dfuds_results.xml 2>/dev/null; then
+          echo "SDE timed out during process teardown (known SDE/ASan issue) - all tests passed, treating as success"
+          exit 0
+        fi
+        exit $rc
+

CMakeLists.txt

@@ -157,6 +157,15 @@ if(PIXIE_TESTS)
         gtest
         gtest_main
         ${PIXIE_DIAGNOSTICS_LIBS})
+
+    add_executable(dfuds_tree_tests
+            src/tests/dfuds_tree_tests.cpp)
+    target_include_directories(dfuds_tree_tests
+            PUBLIC include)
+    target_link_libraries(dfuds_tree_tests
+            gtest
+            gtest_main
+            ${PIXIE_DIAGNOSTICS_LIBS})
 endif()
 
 # ---------------------------------------------------------------------------

include/pixie/dfuds_tree.h

@@ -0,0 +1,121 @@
+#pragma once
+
+#include <pixie/rmm_tree.h>
+
+#include <cstdint>
+
+namespace pixie {
+
+/**
+ * @brief A tree class based on the depth-first unary degree sequence (DFUDS)
+ * representation
+ */
+class DFUDSTree {
+ private:
+  const size_t num_bits_;
+  RmMTree rmm_;
+
+ public:
+
+  struct Node {
+    size_t number;
+
+    size_t pos;
+
+    /**
+   * @brief A node class of DFUDS tree
+   */
+    Node(size_t node_number, size_t dfuds_pos)
+        : number(node_number), pos(dfuds_pos) {}
+  };
+  /**
+   * @brief Constructor from an external array of uint64_t
+   */
+  explicit DFUDSTree(const std::vector<std::uint64_t>& words, size_t tree_size)
+      : num_bits_(2 * tree_size - 1), rmm_(words, 2 * tree_size - 1) {}
+
+  /**
+   * @brief Returns the root node
+   */
+  static Node root() { return Node(0, 0); }
+
+  /**
+   * @brief Returns the size of the tree
+   */
+  size_t size() const { return num_bits_ / 2; }
+
+  /**
+   * @brief Indicates if @p node is a leaf
+   */
+  bool is_leaf(const Node& node) const {
+    return (node.pos + 1 == num_bits_) or rmm_.bit(node.pos) == 0;
+  }
+
+  /**
+   * @brief Indicates if @p node is a root
+   */
+  bool is_root(const Node& node) const { return node.number == 0; }
+
+  /**
+   * @brief Returns the number of children of a @p node
+   */
+  size_t degree(const Node& node) const {
+    return rmm_.select0(node.number + 1) - node.pos;
+  }
+
+  /**
+   * @brief Returns first child of a @p node
+   */
+  Node first_child(const Node& node) {
+    size_t pos = rmm_.select0(node.number + 1);
+    size_t num = node.number + 1;
+    return Node(num, pos + 1);
+  }
+
+  /**
+   * @brief Returns the i-th child of @p node
+   * Indexing starts at 0
+   */
+  Node child(const Node& node, size_t i) const {
+    size_t pos = rmm_.close(rmm_.select0(node.number + 1) - i) + 1;
+    size_t num = rmm_.rank0(pos);
+    return Node(num, pos);
+  }
+
+  /**
+   * @brief Returns next sibling of a @p node
+   */
+  Node next_sibling(const Node& node) const {
+    size_t end = rmm_.fwdsearch(node.pos, -1);
+    size_t pos = end + 1;
+    size_t num = rmm_.rank0(pos);
+    return Node(num, pos);
+  }
+
+  /**
+   * @brief Returns the parent of a @p node if @p node is not root,
+   * else returns root
+   */
+  Node parent(const Node& node) const {
+    if (node.number == 0) {
+      return root();
+    }
+    size_t open = rmm_.open(node.pos);
+    size_t rank = rmm_.rank0(open);
+    size_t pos = rmm_.select0(rank) + 1;  // some overflow-related magic here
+    size_t num = rmm_.rank0(pos);
+    return Node(num, pos);
+  }
+
+  /**
+   * @brief Indicates if @p node is last child
+   */
+  bool is_last_child(const Node& node) const {
+    size_t end = rmm_.fwdsearch(node.pos, -1);
+    size_t pos = end + 1;
+    size_t op = rmm_.open(node.pos);
+    size_t op2 = rmm_.open(pos);
+    return pos == num_bits_ || op != op2 + 1;
+  }
+};
+}  // namespace pixie

include/pixie/rmm_tree.h

@@ -966,6 +966,13 @@ class RmMTree {
     return (result == npos ? npos : result + 1);
   }
 
+  /**
+   * @brief Read bit at position @p position (LSB-first across words).
+   */
+  inline int bit(const size_t& position) const noexcept {
+    return (bits[position >> 6] >> (position & 63)) & 1u;
+  }
+
  private:
   /**
    * @brief Count "10" occurrences inside a 64-bit slice of given logical
@@ -2215,13 +2222,6 @@ class RmMTree {
     build(leaf_block_bits, max_overhead);
   }
 
-  /**
-   * @brief Read bit at position @p position (LSB-first across words).
-   */
-  inline int bit(const size_t& position) const noexcept {
-    return (bits[position >> 6] >> (position & 63)) & 1u;
-  }
-
   /**
    * @brief Set bit at position @p position to 1.
    */

include/pixie/utils.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <pixie/dfuds_tree.h>
 #include <pixie/louds_tree.h>
 
 #include <queue>
@@ -8,6 +9,8 @@
 
 using pixie::LoudsNode;
 
+using Node = pixie::DFUDSTree::Node;
+
 std::vector<std::vector<size_t>> generate_random_tree(size_t tree_size,
                                                       std::mt19937_64& rng) {
   if (tree_size == 0) {
@@ -46,6 +49,32 @@ std::vector<std::vector<size_t>> bfs_order(
   return bfs_adj;
 }
 
+std::vector<std::vector<size_t>> dfs_order(
+    size_t tree_size,
+    const std::vector<std::vector<size_t>>& adj) {
+  std::vector<std::vector<size_t>> dfs_adj(tree_size);
+  std::vector<std::pair<size_t, size_t>> stack;
+  dfs_adj[0].push_back(0);
+  stack.push_back({0, 0});
+  std::vector<size_t> renumbering(tree_size, 0);
+  size_t next_number = 1;
+  while (!stack.empty()) {
+    auto& [v, i] = stack.back();
+    i++;
+    if (i == adj[v].size()) {
+      stack.pop_back();
+      continue;
+    }
+    size_t u = adj[v][i];
+    renumbering[u] = next_number++;
+    dfs_adj[renumbering[v]].push_back(renumbering[u]);
+    dfs_adj[renumbering[u]].push_back(renumbering[v]);
+
+    stack.push_back(std::pair{u, 0});
+  }
+  return dfs_adj;
+}
+
 std::vector<uint64_t> adj_to_louds(
     size_t tree_size,
     const std::vector<std::vector<size_t>>& adj) {
@@ -59,6 +88,28 @@ std::vector<uint64_t> adj_to_louds(
   return louds;
 }
 
+std::vector<uint64_t> adj_to_dfuds(
+    size_t tree_size,
+    const std::vector<std::vector<size_t>>& adj) {
+  size_t dfuds_size = tree_size * 2 - 1;
+  std::vector<uint64_t> dfuds((dfuds_size + 63) / 64, 0);
+  std::vector<size_t> stack;
+  stack.push_back(0);
+  size_t pos = 0;
+  while (!stack.empty()) {
+    auto v = stack.back();
+    stack.pop_back();
+    size_t edge_count = adj[v].size();
+    for (size_t i = 0; i < edge_count - 1; ++i) {  // edge 0 goes to parent
+      dfuds[pos >> 6] = dfuds[pos >> 6] | (1ULL << (pos & 63));
+      pos++;
+      stack.push_back(adj[v][edge_count - 1 - i]);
+    }
+    pos++;
+  }
+  return dfuds;
+}
+
 struct AdjListNode {
   size_t number;
 };
@@ -71,6 +122,14 @@ bool operator==(const LoudsNode& b, const AdjListNode& a) {
   return a.number == b.number;
 }
 
+bool operator==(const AdjListNode& a, const Node& b) {
+  return a.number == b.number;
+}
+
+bool operator==(const Node& b, const AdjListNode& a) {
+  return a.number == b.number;
+}
+
 class AdjListTree {
  private:
   std::vector<std::vector<size_t>> adj;

scripts/coverage_report.sh

@@ -10,6 +10,7 @@ cmake --build --preset coverage
 "${BUILD_DIR}/unittests"
 "${BUILD_DIR}/excess_positions_tests"
 "${BUILD_DIR}/louds_tree_tests"
+"${BUILD_DIR}/dfuds_tree_tests"
 "${BUILD_DIR}/test_rmm"
 
 cd "${BUILD_DIR}"