Bugfixes, benchmarks and improvements to FlatMap

RELEASE-NOTES.md

@@ -59,6 +59,8 @@ The Axom project release numbers follow [Semantic Versioning](http://semver.org/
 - Primal: Improves reproducibility of 3D GWN methods by removing some sources of randomness
 - Core: ArrayView assigments/copies now copy the stride
 - Core: Array construction from strided ArrayView now correctly copies the strided elements
+- Core: Improved `axom::FlatMap` insertion performance by fusing duplicate-key lookup with empty-slot probing.
+- Core: Updated DeviceHash to use 64-bit hash results and improved coverage for integer and floating-point hashing.
 
 ## [Version 0.14.0] - Release date 2026-03-31
 

src/CMakeLists.txt

@@ -42,7 +42,7 @@ else()
     endif()
 endif()
 
-if (“${PROJECT_SOURCE_DIR}” STREQUAL “${CMAKE_SOURCE_DIR}”)
+if ("${PROJECT_SOURCE_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
     # Set some default BLT options before loading BLT only if not included in
     # another project
     if (NOT BLT_CXX_STD)

src/axom/core/DeviceHash.hpp

@@ -11,6 +11,8 @@
 #include "axom/core/Macros.hpp"
 #include "axom/core/Types.hpp"
 
+#include <cstdint>
+#include <cstring>
 #include <type_traits>
 
 namespace axom
@@ -25,24 +27,45 @@ template <typename T>
 struct DeviceHashHelper<T, std::enable_if_t<std::is_integral<T>::value>>
 {
   using argument_type = T;
-  using result_type = axom::IndexType;
-  AXOM_HOST_DEVICE axom::IndexType operator()(T value) const { return value; }
+  using result_type = std::uint64_t;
+  AXOM_HOST_DEVICE std::uint64_t operator()(T value) const
+  {
+    return static_cast<std::uint64_t>(value);
+  }
 };
 
 /// \brief Specialization for floating-point types
 template <typename T>
 struct DeviceHashHelper<T, std::enable_if_t<std::is_floating_point<T>::value>>
 {
   using argument_type = T;
-  using result_type = axom::IndexType;
-  AXOM_HOST_DEVICE axom::IndexType operator()(T value) const
+  using result_type = std::uint64_t;
+  AXOM_HOST_DEVICE std::uint64_t operator()(T value) const
   {
-    // Special case: -0.0 and 0.0 compare equal but have different byte representations.
+    // -0.0 and 0.0 compare equal but have different bit patterns; normalize so both hash identically
     if(value == T {0.})
     {
-      return 0;
+      value = T {0.};
+    }
+
+    // Hash the bit pattern, not the converted value.
+    // A float-to-integer value conversion collapses every key sharing an integer part,
+    // e.g. all numbers between -1 and 1 converts to integer 0
+
+    if constexpr(sizeof(T) <= sizeof(std::uint64_t))
+    {
+      // Zero-initialize first since we only copy 4 bytes for floats.
+      std::uint64_t result = 0;
+      memcpy(&result, &value, sizeof(T));
+      return result;
     }
-    return value;
+
+    // Avoid hashing padding bytes for wider floating types such as x86 long double.
+    // Collisions are acceptable for a hash; equal values must hash identically.
+    double narrowed_value = static_cast<double>(value);
+    std::uint64_t result = 0;
+    memcpy(&result, &narrowed_value, sizeof(narrowed_value));
+    return result;
   }
 };
 
@@ -51,10 +74,10 @@ template <typename T>
 struct DeviceHashHelper<T, std::enable_if_t<std::is_enum<T>::value>>
 {
   using argument_type = T;
-  using result_type = axom::IndexType;
-  AXOM_HOST_DEVICE axom::IndexType operator()(T value) const
+  using result_type = std::uint64_t;
+  AXOM_HOST_DEVICE std::uint64_t operator()(T value) const
   {
-    return static_cast<axom::IndexType>(value);
+    return static_cast<std::uint64_t>(value);
   }
 };
 
@@ -63,10 +86,10 @@ template <typename T>
 struct DeviceHashHelper<T*, void>
 {
   using argument_type = T*;
-  using result_type = axom::IndexType;
-  AXOM_HOST_DEVICE axom::IndexType operator()(T* ptr) const
+  using result_type = std::uint64_t;
+  AXOM_HOST_DEVICE std::uint64_t operator()(T* ptr) const
   {
-    return static_cast<axom::IndexType>(reinterpret_cast<std::uintptr_t>(ptr));
+    return static_cast<std::uint64_t>(reinterpret_cast<std::uintptr_t>(ptr));
   }
 };
 
@@ -75,10 +98,10 @@ template <typename T, typename Enable>
 struct DeviceHashHelper
 {
   using argument_type = T;
-  using result_type = axom::IndexType;
-  axom::IndexType operator()(const T& object) const
+  using result_type = std::uint64_t;
+  std::uint64_t operator()(const T& object) const
   {
-    return static_cast<axom::IndexType>(std::hash<T> {}(object));
+    return static_cast<std::uint64_t>(std::hash<T> {}(object));
   }
 };
 
@@ -89,6 +112,10 @@ struct DeviceHashHelper
  *
  * \brief Implements a host/device-callable hash function for supported types,
  *  and passes through to std::hash otherwise.
+ *
+ *  The result type is always std::uint64_t, independent of the configured axom::IndexType width.
+ *  Hashes feed bit mixers and bucket selection, where truncating wide keys (e.g. 64-bit Morton codes)
+ *  to a 32-bit IndexType before mixing would make keys equal mod 2^32 collide.
  */
 template <typename T>
 struct DeviceHash : public detail::DeviceHashHelper<T>

src/axom/core/FlatMap.hpp

@@ -7,6 +7,7 @@
 #ifndef Axom_Core_FlatMap_HPP
 #define Axom_Core_FlatMap_HPP
 
+#include <cstdint>
 #include <tuple>
 #include <type_traits>
 #include <utility>
@@ -74,6 +75,8 @@ class FlatMap : detail::flat_map::SequentialLookupPolicy<typename Hash::result_t
   using mapped_type = ValueType;
   using size_type = IndexType;
   using value_type = KeyValuePair;
+  using hasher = Hash;
+  using hash_result_type = typename Hash::result_type;
   using iterator = IteratorImpl<false>;
   using const_iterator = IteratorImpl<true>;
 
@@ -179,7 +182,7 @@ class FlatMap : detail::flat_map::SequentialLookupPolicy<typename Hash::result_t
     static_assert(std::is_copy_constructible<ValueType>::value,
                   "Cannot copy an axom::FlatMap when value type is not "
                   "copy-constructible.");
-    if(*this != other)
+    if(this != &other)
     {
       FlatMap new_map(other);
       swap(new_map);
@@ -287,8 +290,25 @@ class FlatMap : detail::flat_map::SequentialLookupPolicy<typename Hash::result_t
    *  if the key wasn't found.
    */
   /// @{
-  iterator find(const KeyType& key);
-  const_iterator find(const KeyType& key) const;
+  AXOM_FORCE_INLINE iterator find(const KeyType& key);
+  AXOM_FORCE_INLINE const_iterator find(const KeyType& key) const;
+  /// @}
+
+  /*!
+   * \brief Try to find an entry with a given key and a precomputed hash.
+   *
+   * \param [in] key the key to search for
+   * \param [in] hash the precomputed hash for \a key
+   *
+   * \return An iterator pointing to the corresponding key-value pair, or end()
+   *  if the key wasn't found.
+   *
+   * \pre hash must be equivalent to hasher{}(key) for this FlatMap's Hash policy.
+   *  Supplying a hash computed for a different key or Hash policy can miss an existing key
+   */
+  /// @{
+  AXOM_FORCE_INLINE iterator find_with_hash(const KeyType& key, hash_result_type hash);
+  AXOM_FORCE_INLINE const_iterator find_with_hash(const KeyType& key, hash_result_type hash) const;
   /// @}
 
   /*!
@@ -332,22 +352,13 @@ class FlatMap : detail::flat_map::SequentialLookupPolicy<typename Hash::result_t
    *
    * \pre ValueType is default-constructible
    */
-  /// @{
   ValueType& operator[](const KeyType& key)
   {
     static_assert(std::is_default_constructible<ValueType>::value,
                   "Cannot use axom::FlatMap::operator[] when value type is not "
                   "default-constructible.");
     return this->try_emplace(key).first->second;
   }
-  const ValueType& operator[](const KeyType& key) const
-  {
-    static_assert(std::is_default_constructible<ValueType>::value,
-                  "Cannot use axom::FlatMap::operator[] when value type is not "
-                  "default-constructible.");
-    return this->try_emplace(key).first->second;
-  }
-  /// @}
 
   /*!
    * \brief Return the number of entries matching a given key.
@@ -840,7 +851,13 @@ FlatMap<KeyType, ValueType, Hash>::FlatMap(IndexType num_elems,
 template <typename KeyType, typename ValueType, typename Hash>
 auto FlatMap<KeyType, ValueType, Hash>::find(const KeyType& key) -> iterator
 {
-  auto hash = Hash {}(key);
+  return find_with_hash(key, Hash {}(key));
+}
+
+template <typename KeyType, typename ValueType, typename Hash>
+auto FlatMap<KeyType, ValueType, Hash>::find_with_hash(const KeyType& key, hash_result_type hash)
+  -> iterator
+{
   iterator found_iter = end();
   this->probeIndex(m_numGroups2, m_metadata, hash, [&](IndexType bucket_index) -> bool {
     if(this->m_buckets[bucket_index].get().first == key)
@@ -857,7 +874,13 @@ auto FlatMap<KeyType, ValueType, Hash>::find(const KeyType& key) -> iterator
 template <typename KeyType, typename ValueType, typename Hash>
 auto FlatMap<KeyType, ValueType, Hash>::find(const KeyType& key) const -> const_iterator
 {
-  auto hash = Hash {}(key);
+  return find_with_hash(key, Hash {}(key));
+}
+
+template <typename KeyType, typename ValueType, typename Hash>
+auto FlatMap<KeyType, ValueType, Hash>::find_with_hash(const KeyType& key, hash_result_type hash) const
+  -> const_iterator
+{
   const_iterator found_iter = end();
   this->probeIndex(m_numGroups2, m_metadata, hash, [&](IndexType bucket_index) -> bool {
     if(this->m_buckets[bucket_index].get().first == key)
@@ -888,23 +911,38 @@ auto FlatMap<KeyType, ValueType, Hash>::getEmplacePos(const KeyType& key)
 {
   auto hash = Hash {}(key);
 
-  // If the key already exists, return the existing iterator.
-  iterator existing_elem = this->find(key);
+  // Single fused probe: visit key matches and locate the insertion slot in a single pass
+  iterator existing_elem = this->end();
+  IndexType newBucket =
+    this->probeEmplaceIndex(m_numGroups2, m_metadata, hash, [&](IndexType bucket_index) -> bool {
+      if(this->m_buckets[bucket_index].get().first == key)
+      {
+        existing_elem = iterator(this, bucket_index);
+        return false;
+      }
+      return true;
+    });
+
   if(existing_elem != this->end())
   {
     return {existing_elem, false};
   }
   // Resize to double the number of bucket groups if insertion would put us
   // above the maximum load factor.
-  if(((m_loadCount + 1) / (double)bucket_count()) >= MAX_LOAD_FACTOR)
+  // MAX_LOAD_FACTOR is exactly 7/8, so (count + 1) / buckets >= 7/8 is
+  // equivalent to 8 * (count + 1) >= 7 * buckets in exact integer arithmetic.
+  // This avoids a floating-point division on every insertion.
+  static_assert(MAX_LOAD_FACTOR == 0.875,
+                "Integer load-factor check below assumes MAX_LOAD_FACTOR == 7/8.");
+  if(8 * (static_cast<std::uint64_t>(m_loadCount) + 1) >=
+     7 * static_cast<std::uint64_t>(bucket_count()))
   {
     IndexType newNumGroups = m_metadata.size() * 2;
     rehash(newNumGroups * BucketsPerGroup - 1);
+    // The table was rebuilt, so the slot is stale. If we got here, the key is missing
+    newBucket = this->probeEmptyIndex(m_numGroups2, m_metadata, hash);
   }
 
-  // Get an empty index to place the element into.
-  IndexType newBucket = this->probeEmptyIndex(m_numGroups2, m_metadata, hash);
-
   // Add a hash to the corresponding bucket slot.
   this->setBucketHash(m_metadata, newBucket, hash);
   m_size++;