✨ Added additional distance functions and distance maps

.github/workflows/macos.yml

@@ -99,6 +99,7 @@ jobs:
           -DCMAKE_BUILD_TYPE=${{matrix.build_type}}
           -DFICTION_CLI=ON
           -DFICTION_TEST=ON
+          -DFICTION_BENCHMARK=ON
           -DFICTION_EXPERIMENTS=ON
           -DFICTION_Z3=ON
           -DFICTION_PROGRESS_BARS=OFF

.github/workflows/ubuntu.yml

@@ -107,6 +107,7 @@ jobs:
           -DCMAKE_BUILD_TYPE=${{matrix.build_type}}
           -DFICTION_CLI=ON
           -DFICTION_TEST=ON
+          -DFICTION_BENCHMARK=ON
           -DFICTION_EXPERIMENTS=ON
           -DFICTION_Z3=ON
           -DFICTION_ENABLE_MUGEN=ON

.github/workflows/windows.yml

@@ -83,6 +83,7 @@ jobs:
           -DCMAKE_BUILD_TYPE=${{matrix.build_type}}
           -DFICTION_CLI=ON
           -DFICTION_TEST=ON
+          -DFICTION_BENCHMARK=ON
           -DFICTION_EXPERIMENTS=ON
           -DFICTION_Z3=ON
           -DMOCKTURTLE_EXAMPLES=OFF

docs/algorithms/path_finding.rst

@@ -7,11 +7,35 @@ Distance functions compute (an approximation for) the distance between two coord
 
 .. doxygenfunction:: fiction::manhattan_distance
 .. doxygenfunction:: fiction::euclidean_distance
+.. doxygenfunction:: fiction::twoddwave_distance
 
 .. doxygenclass:: fiction::distance_functor
    :members:
 .. doxygenclass:: fiction::manhattan_distance_functor
 .. doxygenclass:: fiction::euclidean_distance_functor
+.. doxygenclass:: fiction::twoddwave_distance_functor
+
+Distance Maps
+-------------
+
+Distance maps can store the distance from a coordinate to all other coordinates. They are particularly useful when
+repeatedly calling complex distance functions that are expensive to evaluate. The distance maps can serve as a
+lookup-table for these cases.
+
+**Header:** ``fiction/algorithms/path_finding/distance_map.hpp``
+
+.. doxygentypedef:: fiction::distance_map
+.. doxygentypedef:: fiction::sparse_distance_map
+
+.. doxygenfunction:: fiction::initialize_distance_map
+.. doxygenfunction:: fiction::initialize_sparse_distance_map
+
+.. doxygenclass:: fiction::distance_map_functor
+   :members:
+.. doxygenclass:: fiction::sparse_distance_map_functor
+   :members:
+.. doxygenclass:: fiction::smart_distance_cache_functor
+   :members:
 
 Cost Functions
 --------------

docs/getting_started.rst

@@ -153,6 +153,18 @@ linked against *fiction* and compiled as a stand-alone binary using the followin
   cmake --build . -j4
 
 
+Building code benchmarks
+------------------------
+
+Using ``Catch2``'s micro-benchmarking feature, you can compile and run code tests that evaluate the performance of
+certain code constructs. The ``test/benchmark`` folder provides a selection of benchmarks we were running to evaluate
+the performance of our code during development. Any ``*.cpp`` file that is placed in that folder is automatically
+linked against *fiction* and compiled as a stand-alone binary using the following commands::
+
+  cmake . -B build -DFICTION_BENCHMARK=ON
+  cd build
+  cmake --build . -j4
+
 Uninstall
 ---------
 

include/fiction/algorithms/path_finding/distance.hpp

@@ -11,6 +11,7 @@
 #include <cmath>
 #include <cstdint>
 #include <functional>
+#include <limits>
 #include <type_traits>
 
 namespace fiction
@@ -62,6 +63,33 @@ template <typename Lyt, typename Dist = double>
 
     return static_cast<Dist>(std::hypot(x, y));
 }
+/**
+ * The 2DDWave distance \f$ D \f$ between two layout coordinates \f$ s = (x_1, y_1) \f$ and \f$ t = (x_2, y_2) \f$ given
+ * by
+ *
+ *  \f$ D = |x_1 - x_2| + |y_1 - y_2| \f$ iff \f$ s \leq t \f$ and \f$ \infty \f$, otherwise.
+ *
+ * Thereby, \f$ s \leq t \f$ iff \f$ x_1 \leq x_2 \f$ and \f$ y_1 \leq y_2 \f$.
+ *
+ * @note To represent \f$ \infty \f$, `std::numeric_limits<Dist>::max()` is returned for distances of infinite length.
+ *
+ * @tparam Lyt Coordinate layout type.
+ * @tparam Dist Integral type for the distance.
+ * @param lyt Layout.
+ * @param source Source coordinate.
+ * @param target Target coordinate.
+ * @return 2DDWave distance between `source` and `target`.
+ */
+template <typename Lyt, typename Dist = uint64_t>
+[[nodiscard]] constexpr Dist twoddwave_distance([[maybe_unused]] const Lyt& lyt, const coordinate<Lyt>& source,
+                                                const coordinate<Lyt>& target) noexcept
+{
+    static_assert(is_coordinate_layout_v<Lyt>, "Lyt is not a coordinate layout");
+    static_assert(std::is_integral_v<Dist>, "Dist is not an integral type");
+
+    return source.x <= target.x && source.y <= target.y ? manhattan_distance<Lyt, Dist>(lyt, source, target) :
+                                                          std::numeric_limits<Dist>::max();
+}
 /**
  * Computes the distance between two SiDB cells in nanometers.
  *
@@ -109,7 +137,7 @@ class distance_functor
      * @param dist_fn A function that maps from layout coordinates to a distance value.
      */
     explicit distance_functor(
-        const std::function<Dist(const Lyt& lyt, const coordinate<Lyt>&, const coordinate<Lyt>&)>& dist_fn) :
+        const std::function<Dist(const Lyt&, const coordinate<Lyt>&, const coordinate<Lyt>&)>& dist_fn) :
             distance_function{dist_fn}
     {
         static_assert(is_coordinate_layout_v<Lyt>, "Lyt is not a coordinate layout");
@@ -136,7 +164,7 @@ class distance_functor
     /**
      * Distance function.
      */
-    const std::function<Dist(const Lyt& lyt, const coordinate<Lyt>&, const coordinate<Lyt>&)> distance_function;
+    const std::function<Dist(const Lyt&, const coordinate<Lyt>&, const coordinate<Lyt>&)> distance_function;
 };
 
 // NOLINTEND(*-special-member-functions)
@@ -165,6 +193,18 @@ class euclidean_distance_functor : public distance_functor<Lyt, Dist>
   public:
     euclidean_distance_functor() : distance_functor<Lyt, Dist>(&euclidean_distance<Lyt, Dist>) {}
 };
+/**
+ * A pre-defined distance functor that uses the 2DDWave distance.
+ *
+ * @tparam Lyt Coordinate layout type.
+ * @tparam Dist Integral distance type.
+ */
+template <typename Lyt, typename Dist = uint64_t>
+class twoddwave_distance_functor : public distance_functor<Lyt, Dist>
+{
+  public:
+    twoddwave_distance_functor() : distance_functor<Lyt, Dist>(&twoddwave_distance<Lyt, Dist>) {}
+};
 
 }  // namespace fiction