⚡ improved collision logic in RealNumberUniqueTable (#461)

## Description

This PR improves the logic for handling collisions in the unique table
for real numbers.
Since we track tail pointers anyway, insertions in the back can be
accomplished very cheaply.
This can be used in both lookup scenarios; the border case and the
middle case.
If no match was found in a border case, it is clear that the new entry
should either be added to the end of one or the beginning of the other
bucket list.
In the standard case, one can first check whether the looked up value is
larger (or equal) than the last element in the bucket.
If so, the new entry can just be added to the end of the collision
chain.
In a 33-qubit Grover simulation this saved a couple million collisions.

## Checklist:

<!---
This checklist serves as a reminder of a couple of things that ensure
your pull request will be merged swiftly.
-->

- [x] The pull request only contains commits that are related to it.
- [x] I have added appropriate tests and documentation.
- [x] I have made sure that all CI jobs on GitHub pass.
- [x] The pull request introduces no new warnings and follows the
project's style guidelines.

Author: burgholzer

include/dd/RealNumberUniqueTable.hpp

@@ -189,14 +189,20 @@ class RealNumberUniqueTable {
   RealNumber* findOrInsert(std::int64_t key, fp val);
 
   /**
-   * @brief Inserts a value into the bucket indexed by key.
-   * @details This function inserts a value into the bucket indexed by key.
-   * It assumes that no element within TOLERANCE is present in the bucket.
+   * @brief Inserts a value in the front of the bucket indexed by key.
    * @param key The index of the bucket to insert the value into.
    * @param val The value to insert.
-   * @returns A pointer to the inserted entry.
+   * @return A pointer to the inserted entry.
    */
-  RealNumber* insert(std::int64_t key, fp val);
+  RealNumber* insertFront(std::int64_t key, fp val);
+
+  /**
+   * @brief Inserts a value in the back of the bucket indexed by key.
+   * @param key The index of the bucket to insert the value into.
+   * @param val The value to insert.
+   * @return A pointer to the inserted entry.
+   */
+  RealNumber* insertBack(std::int64_t key, fp val);
 
   /**
    * @brief Lookup a non-negative number in the table.

src/dd/RealNumberUniqueTable.cpp

@@ -117,9 +117,13 @@ RealNumber* RealNumberUniqueTable::lookupNonNegative(const fp val) {
     return pUpper;
   }
 
-  // value was not found in the table -> get a new entry and add it to the
-  // central bucket
-  return insert(key, val);
+  // Since no match was found, a new value needs to be added
+  // Depending on which border of the bucket the value lies, a value either
+  // needs to be inserted in the front or the back of the bucket.
+  if (key == lowerKey) {
+    return insertFront(key, val);
+  }
+  return insertBack(key, val);
 }
 
 bool RealNumberUniqueTable::possiblyNeedsCollection() const noexcept {
@@ -226,11 +230,36 @@ std::ostream& RealNumberUniqueTable::printBucketDistribution(std::ostream& os) {
 
 RealNumber* RealNumberUniqueTable::findOrInsert(const std::int64_t key,
                                                 const fp val) {
-  const fp valTol = val + RealNumber::eps;
+  const auto k = static_cast<std::size_t>(key);
+  auto* curr = table[k];
+  if (curr == nullptr) {
+    auto* entry = memoryManager->get();
+    entry->value = val;
+    entry->next = curr;
+    table[k] = entry;
+    tailTable[k] = entry;
+    stats.trackInsert();
+    return entry;
+  }
 
-  auto* curr = table[static_cast<std::size_t>(key)];
-  RealNumber* prev = nullptr;
+  auto* back = tailTable[k];
+  if (back != nullptr && back->value <= val) {
+    if (RealNumber::approximatelyEquals(val, back->value)) {
+      ++stats.hits;
+      return back;
+    }
+    ++stats.collisions;
+    auto* entry = memoryManager->get();
+    entry->value = val;
+    entry->next = nullptr;
+    back->next = entry;
+    tailTable[k] = entry;
+    stats.trackInsert();
+    return entry;
+  }
 
+  RealNumber* prev = nullptr;
+  const fp valTol = val + RealNumber::eps;
   while (curr != nullptr && curr->value <= valTol) {
     if (RealNumber::approximatelyEquals(curr->value, val)) {
       // check if val is actually closer to the next element in the list (if
@@ -260,42 +289,46 @@ RealNumber* RealNumberUniqueTable::findOrInsert(const std::int64_t key,
   entry->value = val;
 
   if (prev == nullptr) {
-    // table bucket is empty
-    table[static_cast<std::size_t>(key)] = entry;
+    // add to front of bucket
+    table[k] = entry;
   } else {
     prev->next = entry;
   }
   entry->next = curr;
   if (curr == nullptr) {
-    tailTable[static_cast<std::size_t>(key)] = entry;
+    tailTable[k] = entry;
   }
   stats.trackInsert();
   return entry;
 }
 
-RealNumber* RealNumberUniqueTable::insert(const std::int64_t key,
-                                          const fp val) {
+RealNumber* RealNumberUniqueTable::insertFront(const std::int64_t key,
+                                               const fp val) {
   auto* entry = memoryManager->get();
   entry->value = val;
 
   auto* curr = table[static_cast<std::size_t>(key)];
-  RealNumber* prev = nullptr;
-
-  while (curr != nullptr && curr->value <= val) {
-    ++stats.collisions;
-    prev = curr;
-    curr = curr->next;
+  table[static_cast<std::size_t>(key)] = entry;
+  entry->next = curr;
+  if (curr == nullptr) {
+    tailTable[static_cast<std::size_t>(key)] = entry;
   }
+  stats.trackInsert();
+  return entry;
+}
 
-  if (prev == nullptr) {
-    // table bucket is empty
+RealNumber* RealNumberUniqueTable::insertBack(const std::int64_t key,
+                                              const fp val) {
+  auto* entry = memoryManager->get();
+  entry->value = val;
+  entry->next = nullptr;
+
+  auto* back = tailTable[static_cast<std::size_t>(key)];
+  tailTable[static_cast<std::size_t>(key)] = entry;
+  if (back == nullptr) {
     table[static_cast<std::size_t>(key)] = entry;
   } else {
-    prev->next = entry;
-  }
-  entry->next = curr;
-  if (curr == nullptr) {
-    tailTable[static_cast<std::size_t>(key)] = entry;
+    back->next = entry;
   }
   stats.trackInsert();
   return entry;