🎨 Usability improvement by return type adjustments

cli/cmd/technology/area.hpp

@@ -10,6 +10,7 @@
 
 #include <alice/alice.hpp>
 
+#include <type_traits>
 #include <variant>
 
 namespace alice

cli/stores.hpp

@@ -10,7 +10,6 @@
 #include <fiction/io/print_layout.hpp>
 #include <fiction/io/write_svg_layout.hpp>
 #include <fiction/layouts/coordinates.hpp>
-#include <fiction/technology/cell_technologies.hpp>
 #include <fiction/traits.hpp>
 #include <fiction/types.hpp>
 
@@ -19,6 +18,8 @@
 #include <kitty/print.hpp>
 #include <mockturtle/views/depth_view.hpp>
 
+#include <cstdint>
+#include <stdexcept>
 #include <type_traits>
 #include <variant>
 
@@ -74,7 +75,7 @@ ALICE_DESCRIBE_STORE(fiction::logic_network_t, ln)
     {
         using Ntk = typename std::decay_t<decltype(ntk_ptr)>::element_type;
 
-        mockturtle::depth_view depth_ntk{*ntk_ptr};
+        const mockturtle::depth_view depth_ntk{*ntk_ptr};
 
         return fmt::format("{} ({}) - I/O: {}/{}, gates: {}, level: {}", ntk_ptr->get_network_name(),
                            fiction::ntk_type_name<Ntk>, ntk_ptr->num_pis(), ntk_ptr->num_pos(), ntk_ptr->num_gates(),
@@ -90,7 +91,7 @@ ALICE_PRINT_STORE_STATISTICS(fiction::logic_network_t, os, ln)
     {
         using Ntk = typename std::decay_t<decltype(ntk_ptr)>::element_type;
 
-        mockturtle::depth_view depth_ntk{*ntk_ptr};
+        const mockturtle::depth_view depth_ntk{*ntk_ptr};
 
         os << fmt::format("[i] {} ({}) - I/O: {}/{}, gates: {}, level: {}\n", ntk_ptr->get_network_name(),
                           fiction::ntk_type_name<Ntk>, ntk_ptr->num_pis(), ntk_ptr->num_pos(), ntk_ptr->num_gates(),
@@ -106,7 +107,7 @@ ALICE_LOG_STORE_STATISTICS(fiction::logic_network_t, ln)
     {
         using Ntk = typename std::decay_t<decltype(ntk_ptr)>::element_type;
 
-        mockturtle::depth_view depth_ntk{*ntk_ptr};
+        const mockturtle::depth_view depth_ntk{*ntk_ptr};
 
         return nlohmann::json{{"name", ntk_ptr->get_network_name()}, {"type", fiction::ntk_type_name<Ntk>},
                               {"inputs", ntk_ptr->num_pis()},        {"outputs", ntk_ptr->num_pos()},
@@ -135,7 +136,7 @@ void show<fiction::logic_network_t>(std::ostream& os, const fiction::logic_netwo
     {
         try
         {
-            mockturtle::depth_view depth_ntk{*ntk_ptr};
+            const mockturtle::depth_view depth_ntk{*ntk_ptr};
 
             using Ntk = typename std::decay_t<decltype(depth_ntk)>;
 
@@ -182,13 +183,12 @@ ALICE_DESCRIBE_STORE(fiction::gate_layout_t, layout)
             num_se = lyt_ptr->num_se();
         }
 
-        fiction::critical_path_length_and_throughput_stats st{};
-        fiction::critical_path_length_and_throughput(*lyt_ptr, &st);
+        const auto cp_tp = fiction::critical_path_length_and_throughput(*lyt_ptr);
 
         return fmt::format("{} ({}) - {} × {}, I/O: {}/{}, gates: {}, wires: {}, CP: {}, TP: 1/{}, sync. elems.: {}",
                            lyt_ptr->get_layout_name(), lyt_ptr->get_clocking_scheme().name, lyt_ptr->x() + 1,
                            lyt_ptr->y() + 1, lyt_ptr->num_pis(), lyt_ptr->num_pos(), lyt_ptr->num_gates(),
-                           lyt_ptr->num_wires(), st.critical_path_length, st.throughput, num_se);
+                           lyt_ptr->num_wires(), cp_tp.critical_path_length, cp_tp.throughput, num_se);
     };
 
     return std::visit(describe, layout);
@@ -208,14 +208,13 @@ ALICE_PRINT_STORE_STATISTICS(fiction::gate_layout_t, os, layout)
             num_se = lyt_ptr->num_se();
         }
 
-        fiction::critical_path_length_and_throughput_stats st{};
-        fiction::critical_path_length_and_throughput(*lyt_ptr, &st);
+        const auto cp_tp = fiction::critical_path_length_and_throughput(*lyt_ptr);
 
         os << fmt::format(
             "[i] {} ({}) - {} × {}, I/O: {}/{}, gates: {}, wires: {}, CP: {}, TP: 1/{}, sync. elems.: {}\n",
             lyt_ptr->get_layout_name(), lyt_ptr->get_clocking_scheme().name, lyt_ptr->x() + 1, lyt_ptr->y() + 1,
-            lyt_ptr->num_pis(), lyt_ptr->num_pos(), lyt_ptr->num_gates(), lyt_ptr->num_wires(), st.critical_path_length,
-            st.throughput, num_se);
+            lyt_ptr->num_pis(), lyt_ptr->num_pos(), lyt_ptr->num_gates(), lyt_ptr->num_wires(),
+            cp_tp.critical_path_length, cp_tp.throughput, num_se);
     };
 
     std::visit(print_statistics, layout);
@@ -234,8 +233,7 @@ ALICE_LOG_STORE_STATISTICS(fiction::gate_layout_t, layout)
             num_se = lyt_ptr->num_se();
         }
 
-        fiction::critical_path_length_and_throughput_stats st{};
-        fiction::critical_path_length_and_throughput(*lyt_ptr, &st);
+        const auto cp_tp = fiction::critical_path_length_and_throughput(*lyt_ptr);
 
         return nlohmann::json{
             {"name", lyt_ptr->get_layout_name()},
@@ -248,8 +246,8 @@ ALICE_LOG_STORE_STATISTICS(fiction::gate_layout_t, layout)
             // {"free tiles", area - (gate_tiles + wire_tiles - crossings)},  // free tiles in ground layer
             // {"crossings", crossings},
             {"synchronization elements", num_se},
-            {"critical path", st.critical_path_length},
-            {"throughput", fmt::format("1/{}", st.throughput)}};
+            {"critical path", cp_tp.critical_path_length},
+            {"throughput", fmt::format("1/{}", cp_tp.throughput)}};
     };
 
     return std::visit(log_statistics, layout);

docs/technology/properties.rst

@@ -7,7 +7,7 @@ Area Requirements
 **Header:** ``fiction/technology/area.hpp``
 
 .. doxygenfunction:: fiction::area(const Lyt& lyt, area_params<technology<Lyt>, AreaType>& ps = {}, area_stats<AreaType>* pst = nullptr)
-.. doxygenfunction:: area(const bounding_box_2d<Lyt>& bb, area_params<technology<Lyt>, AreaType>& ps = {}, area_stats<AreaType>* pst = nullptr)
+.. doxygenfunction:: fiction::area(const bounding_box_2d<Lyt>& bb, area_params<technology<Lyt>, AreaType>& ps = {}, area_stats<AreaType>* pst = nullptr)
 
 MagCAD Magnet Count
 ###################

experiments/bestagon/bestagon.cpp

@@ -144,8 +144,7 @@ int main()  // NOLINT
             assert(eq.has_value());
 
             // compute critical path and throughput
-            fiction::critical_path_length_and_throughput_stats cp_tp_stats{};
-            fiction::critical_path_length_and_throughput(*gate_level_layout, &cp_tp_stats);
+            const auto cp_tp = fiction::critical_path_length_and_throughput(*gate_level_layout);
 
             // apply gate library
             const auto cell_level_layout =
@@ -164,7 +163,7 @@ int main()  // NOLINT
                          cut_xag.num_gates(), depth_cut_xag.depth(), mapped_network.num_gates(),
                          depth_mapped_network.depth(), gate_level_layout->x() + 1, gate_level_layout->y() + 1,
                          (gate_level_layout->x() + 1) * (gate_level_layout->y() + 1), gate_level_layout->num_gates(),
-                         gate_level_layout->num_wires(), cp_tp_stats.critical_path_length, cp_tp_stats.throughput,
+                         gate_level_layout->num_wires(), cp_tp.critical_path_length, cp_tp.throughput,
                          mockturtle::to_seconds(exact_stats.time_total), *eq, cell_level_layout.num_cells(),
                          area_stats.area);
         }

experiments/defect_aware_physical_design/defect_aware_physical_design.cpp

@@ -180,8 +180,7 @@ int main()  // NOLINT
             assert(eq.has_value());
 
             // compute critical path and throughput
-            fiction::critical_path_length_and_throughput_stats cp_tp_stats{};
-            fiction::critical_path_length_and_throughput(*gate_level_layout, &cp_tp_stats);
+            const auto cp_tp = fiction::critical_path_length_and_throughput(*gate_level_layout);
 
             // apply gate library
             const auto cell_level_layout =
@@ -204,7 +203,7 @@ int main()  // NOLINT
                        depth_cut_xag.depth(), mapped_network.num_gates(), depth_mapped_network.depth(),
                        gate_level_layout->x() + 1, gate_level_layout->y() + 1,
                        (gate_level_layout->x() + 1) * (gate_level_layout->y() + 1), gate_level_layout->num_gates(),
-                       gate_level_layout->num_wires(), cp_tp_stats.critical_path_length, cp_tp_stats.throughput,
+                       gate_level_layout->num_wires(), cp_tp.critical_path_length, cp_tp.throughput,
                        mockturtle::to_seconds(exact_stats.time_total), *eq, cell_level_layout.num_cells(),
                        area_stats.area);
         }

experiments/hexagonalization/hexagonalization.cpp

@@ -5,10 +5,9 @@
 #include <fiction/algorithms/physical_design/orthogonal.hpp>  // scalable heuristic for physical design of FCN layouts
 #include <fiction/algorithms/properties/critical_path_length_and_throughput.hpp>  // critical path and throughput calculations
 #include <fiction/algorithms/verification/equivalence_checking.hpp>               // SAT-based equivalence checking
-#include <fiction/layouts/bounding_box.hpp>  // computes a minimum-sized box around all non-empty coordinates in a given layout
-#include <fiction/technology/area.hpp>                        // area requirement calculations
-#include <fiction/technology/cell_technologies.hpp>           // cell implementations
-#include <fiction/technology/sidb_bestagon_library.hpp>       // a pre-defined SiDB gate library
+#include <fiction/technology/area.hpp>                                            // area requirement calculations
+#include <fiction/technology/cell_technologies.hpp>                               // cell implementations
+#include <fiction/technology/sidb_bestagon_library.hpp>                           // a pre-defined SiDB gate library
 #include <fiction/technology/technology_mapping_library.hpp>  // pre-defined gate types for technology mapping
 #include <fiction/traits.hpp>                                 // traits for type-checking
 #include <fiction/types.hpp>                                  // pre-defined types suitable for the FCN domain
@@ -25,7 +24,6 @@
 #include <mockturtle/utils/tech_library.hpp>                   // technology library utils
 
 #include <cassert>
-#include <chrono>
 #include <cstdint>
 #include <cstdlib>
 #include <sstream>
@@ -128,8 +126,7 @@ int main()  // NOLINT
         const auto gate_level_layout = fiction::orthogonal<gate_lyt>(mapped_network, {}, &orthogonal_stats);
 
         // compute critical path and throughput
-        fiction::critical_path_length_and_throughput_stats cp_tp_stats{};
-        fiction::critical_path_length_and_throughput(gate_level_layout, &cp_tp_stats);
+        const auto cp_tp = fiction::critical_path_length_and_throughput(gate_level_layout);
 
         const auto hex_layout =
             fiction::hexagonalization<hex_lyt, gate_lyt>(gate_level_layout, &hexagonalization_stats);
@@ -152,15 +149,15 @@ int main()  // NOLINT
         fiction::area(cell_level_layout, area_ps, &area_stats);
 
         // log results
-        hexagonalization_exp(
-            benchmark, xag.num_pis(), xag.num_pos(), xag.num_gates(), depth_xag.depth(), cut_xag.num_gates(),
-            depth_cut_xag.depth(), mapped_network.num_gates(), depth_mapped_network.depth(), gate_level_layout.x() + 1,
-            gate_level_layout.y() + 1, (gate_level_layout.x() + 1) * (gate_level_layout.y() + 1), (hex_layout.x() + 1),
-            (hex_layout.y() + 1), (hex_layout.x() + 1) * (hex_layout.y() + 1), gate_level_layout.num_gates(),
-            gate_level_layout.num_wires(), cp_tp_stats.critical_path_length, cp_tp_stats.throughput,
-            mockturtle::to_seconds(orthogonal_stats.time_total),
-            mockturtle::to_seconds(hexagonalization_stats.time_total), eq_result, cell_level_layout.num_cells(),
-            area_stats.area);
+        hexagonalization_exp(benchmark, xag.num_pis(), xag.num_pos(), xag.num_gates(), depth_xag.depth(),
+                             cut_xag.num_gates(), depth_cut_xag.depth(), mapped_network.num_gates(),
+                             depth_mapped_network.depth(), gate_level_layout.x() + 1, gate_level_layout.y() + 1,
+                             (gate_level_layout.x() + 1) * (gate_level_layout.y() + 1), (hex_layout.x() + 1),
+                             (hex_layout.y() + 1), (hex_layout.x() + 1) * (hex_layout.y() + 1),
+                             gate_level_layout.num_gates(), gate_level_layout.num_wires(), cp_tp.critical_path_length,
+                             cp_tp.throughput, mockturtle::to_seconds(orthogonal_stats.time_total),
+                             mockturtle::to_seconds(hexagonalization_stats.time_total), eq_result,
+                             cell_level_layout.num_cells(), area_stats.area);
 
         hexagonalization_exp.save();
         hexagonalization_exp.table();

experiments/post_layout_optimization/post_layout_optimization.cpp

@@ -62,8 +62,7 @@ int main()  // NOLINT
         auto gate_level_layout = fiction::orthogonal<gate_lyt>(network, {}, &orthogonal_stats);
 
         //  compute critical path and throughput
-        fiction::critical_path_length_and_throughput_stats cp_tp_stats{};
-        fiction::critical_path_length_and_throughput(gate_level_layout, &cp_tp_stats);
+        const auto cp_tp = fiction::critical_path_length_and_throughput(gate_level_layout);
 
         // calculate bounding box
         const auto bounding_box_before_optimization = fiction::bounding_box_2d(gate_level_layout);
@@ -96,8 +95,8 @@ int main()  // NOLINT
         optimization_exp(benchmark, network.num_pis(), network.num_pos(), network.num_gates(),
                          width_before_optimization, height_before_optimization, area_before_optimization,
                          width_after_optimization, height_after_optimization, area_after_optimization,
-                         gate_level_layout.num_gates(), gate_level_layout.num_wires(), cp_tp_stats.critical_path_length,
-                         cp_tp_stats.throughput, mockturtle::to_seconds(orthogonal_stats.time_total),
+                         gate_level_layout.num_gates(), gate_level_layout.num_wires(), cp_tp.critical_path_length,
+                         cp_tp.throughput, mockturtle::to_seconds(orthogonal_stats.time_total),
                          mockturtle::to_seconds(post_layout_optimization_stats.time_total), improv, eq_result);
 
         optimization_exp.save();

include/fiction/algorithms/physical_design/exact.hpp

@@ -57,9 +57,15 @@ namespace fiction
 /**
  * Target technologies.
  */
-enum class technology_constraints
+enum class technology_constraints : uint8_t
 {
-    NONE,
+    /**
+     * No technology-specific constraints.
+     */
+    NONE = 0,
+    /**
+     * ToPoLiNano technology-specific constraints.
+     */
     TOPOLINANO
 };
 /**

include/fiction/algorithms/properties/critical_path_length_and_throughput.hpp

@@ -12,13 +12,25 @@
 
 #include <algorithm>
 #include <cstdint>
+#include <cstdlib>
+#include <vector>
 
 namespace fiction
 {
 
-struct critical_path_length_and_throughput_stats
+/**
+ * Critical path length and throughput storage struct.
+ */
+struct cp_and_tp
 {
-    uint64_t critical_path_length{0ull}, throughput{0ull};
+    /**
+     * Length of the critical path in tiles.
+     */
+    uint64_t critical_path_length{0ull};
+    /**
+     * Throughput of the layout in clock cycles as \f$\frac{1}{x}\f$ where only \f$x\f$ is stored.
+     */
+    uint64_t throughput{0ull};
 };
 
 namespace detail
@@ -28,17 +40,15 @@ template <typename Lyt>
 class critical_path_length_and_throughput_impl
 {
   public:
-    critical_path_length_and_throughput_impl(const Lyt& src, critical_path_length_and_throughput_stats& st) :
-            lyt{src},
-            pst{st}
-    {}
+    explicit critical_path_length_and_throughput_impl(const Lyt& src) : lyt{src} {}
 
-    void run()
+    cp_and_tp run()
     {
         lyt.foreach_po(
-            [this](const auto& po) {
-                pst.critical_path_length =
-                    std::max(signal_delay(static_cast<tile<Lyt>>(po)).length, pst.critical_path_length);
+            [this](const auto& po)
+            {
+                result.critical_path_length =
+                    std::max(signal_delay(static_cast<tile<Lyt>>(po)).length, result.critical_path_length);
             });
 
         const auto max_diff =
@@ -47,20 +57,27 @@ class critical_path_length_and_throughput_impl
 
         if (max_diff != delay_cache.cend())
         {
-            pst.throughput = max_diff->second.diff;
+            result.throughput = max_diff->second.diff;
         }
 
         // give throughput in cycles, not in phases
-        pst.throughput /= lyt.num_clocks();
+        result.throughput /= lyt.num_clocks();
 
         // convert cycle difference to throughput, i.e., x where throughput == 1/x
-        pst.throughput++;
+        result.throughput++;
+
+        return result;
     }
 
   private:
+    /**
+     * Gate-level layout.
+     */
     Lyt lyt;
-
-    critical_path_length_and_throughput_stats& pst;
+    /**
+     * Result storage.
+     */
+    cp_and_tp result;
 
     struct path_info
     {
@@ -159,22 +176,16 @@ class critical_path_length_and_throughput_impl
  *
  * @tparam Lyt Gate-level layout type.
  * @param lyt The gate-level layout whose CP and TP are desired.
- * @param pst Statistics.
+ * @return A struct containing the CP and TP.
  */
 template <typename Lyt>
-void critical_path_length_and_throughput(const Lyt& lyt, critical_path_length_and_throughput_stats* pst = nullptr)
+cp_and_tp critical_path_length_and_throughput(const Lyt& lyt)
 {
     static_assert(is_gate_level_layout_v<Lyt>, "Lyt is not a gate layout type");
 
-    critical_path_length_and_throughput_stats        st{};
-    detail::critical_path_length_and_throughput_impl p{lyt, st};
+    detail::critical_path_length_and_throughput_impl p{lyt};
 
-    p.run();
-
-    if (pst)
-    {
-        *pst = st;
-    }
+    return p.run();
 }
 
 }  // namespace fiction