🎨 Improved usability of the on-the-fly SiDB gate library

docs/algorithms/on_the_fly_circuit_design_on_defective_surface.rst

@@ -1,6 +1,6 @@
 .. _on_the_fly_design:
 
-SiDB Circuit Design Algorithm in the Presence of Atomic Defects
+SiDB Circuit Design Algorithm on defectivein the Presence of Atomic Defects
 ---------------------------------------------------------------
 
 This algorithm is designed to create SiDB circuits on a clocked surface, accommodating the presence of atomic defects.

include/fiction/algorithms/physical_design/on_the_fly_sidb_circuit_design.hpp

@@ -27,19 +27,34 @@ namespace fiction
 {
 
 /**
- * Exception thrown when no valid placement and routing is found for the given blacklist.
+ * If the blacklist is overly restrictive, finding a valid placement and routing becomes impossible, resulting in this
+ * exception being thrown.
  */
 class unsuccessful_pr_error : public std::runtime_error
 {
   public:
+    /**
+     * This class inherits from `std::runtime_error` and is used to signal
+     * errors related to unsuccessful placement and routing.
+     *
+     * @param msg The error message describing the unsuccessful placement and routing.
+     */
     explicit unsuccessful_pr_error(const std::string_view& msg) noexcept : std::runtime_error(msg.data()) {}
 };
 /**
- * Exception thrown when the gate design was unsuccessful.
+ * Exception thrown if the gate design was unsuccessful. Depending on the given gate design parameters and the defect
+ * density, the gate design may fail.
  */
 class unsuccessful_gate_design_error : public std::runtime_error
 {
   public:
+    /**
+     * This explicit constructor initializes the base `std::runtime_error` class
+     * with the provided error message, ensuring that the exception contains
+     * detailed information about the reason for the gate design failure.
+     *
+     * @param msg A descriptive message explaining why the gate design failed.
+     */
     explicit unsuccessful_gate_design_error(const std::string_view& msg) noexcept : std::runtime_error(msg.data()) {}
 };
 /**
@@ -133,7 +148,7 @@ template <typename Ntk, typename CellLyt, typename GateLyt>
     static_assert(is_cell_level_layout_v<CellLyt>, "CellLyt is not a cell-level layout");
     static_assert(has_sidb_technology_v<CellLyt>, "CellLyt is not an SiDB layout");
     static_assert(mockturtle::is_network_type_v<Ntk>, "Ntk is not a network type");
-    static_assert(is_sidb_defect_surface_v<CellLyt>, "CellLyt is not an SiDB defect layout");
+    static_assert(is_sidb_defect_surface_v<CellLyt>, "CellLyt is not an SiDB defect surface");
 
     on_the_fly_circuit_design_on_defective_surface_stats<GateLyt> st{};
 
@@ -183,21 +198,19 @@ template <typename Ntk, typename CellLyt, typename GateLyt>
                 {
                     fmt::print(stderr, "[e] Unsupported gate orientation encountered at tile: {} and ports: {}\n",
                                e.where(), e.which_ports());
-                    fmt::print(stderr, "[e] Terminating loop due to critical error.\n");
                     break;
                 }
 
                 catch (...)
                 {
                     fmt::print(stderr, "[e] An unexpected error occurred during gate design.\n");
-                    fmt::print(stderr, "[e] Terminating loop due to critical error.\n");
                     break;
                 }
             }
             // P&R was unsuccessful
             else
             {
-                throw unsuccessful_pr_error("Placement and routing was unsuccessful");
+                throw unsuccessful_pr_error("Placement and routing is impossible with the current blacklist.");
             }
         }
 
@@ -235,7 +248,7 @@ template <typename CellLyt, typename GateLyt>
     static_assert(is_hexagonal_layout_v<GateLyt>, "GateLyt is not a hexagonal");
     static_assert(is_cell_level_layout_v<CellLyt>, "CellLyt is not a cell-level layout");
     static_assert(has_sidb_technology_v<CellLyt>, "CellLyt is not an SiDB layout");
-    static_assert(!is_sidb_defect_surface_v<CellLyt>, "CellLyt cannot be an SiDB defect layout");
+    static_assert(!is_sidb_defect_surface_v<CellLyt>, "CellLyt cannot be an SiDB defect surface");
 
     CellLyt result{};
 

include/fiction/technology/sidb_on_the_fly_gate_library.hpp

@@ -98,7 +98,7 @@ class gate_design_exception : public std::exception
 /**
  * This struct encapsulates parameters for the parameterized SiDB gate library.
  *
- * @tparam CellType Cell type.
+ * @tparam CellType SiDB cell type.
  */
 template <typename CellType>
 struct sidb_on_the_fly_gate_library_params
@@ -153,12 +153,12 @@ class sidb_on_the_fly_gate_library : public fcn_gate_library<sidb_technology, 60
      * case there is no possible SiDB design, the blacklist is updated and an error fcn gate is returned.
      *
      * @tparam GateLyt Pointy-top hexagonal gate-level layout type.
-     * @tparam CellLyt The type of the cell-level layout.
+     * @tparam CellLyt SiDB cell-level layout type.
      * @tparam Params Type of the parameter used for the gate library.
      * @param lyt Layout that hosts tile `t`.
      * @param t Tile to be realized as a Bestagon gate.
      * @param parameters Parameter to design SiDB gates.
-     * @param defect_surface Optional atomic defect surface.
+     * @param defect_surface Optional atomic defect surface in case atomic defects are present.
      * @return Bestagon gate representation of `t` including mirroring.
      */
     template <typename GateLyt, typename CellLyt, typename Params>
@@ -167,6 +167,8 @@ class sidb_on_the_fly_gate_library : public fcn_gate_library<sidb_technology, 60
     {
         static_assert(is_gate_level_layout_v<GateLyt>, "GateLyt must be a gate-level layout");
         static_assert(has_cube_coord_v<CellLyt>, "CellLyt must be based on cube coordinates");
+        static_assert(is_cell_level_layout_v<CellLyt>, "Lyt is not a cell-level layout");
+        static_assert(has_sidb_technology_v<CellLyt>, "Lyt is not an SiDB layout");
 
         const auto n = lyt.get_node(t);
         const auto f = lyt.node_function(n);

test/algorithms/physical_design/apply_gate_library.cpp

@@ -9,6 +9,7 @@
 #include <fiction/algorithms/physical_design/design_sidb_gates.hpp>
 #include <fiction/algorithms/simulation/sidb/is_operational.hpp>
 #include <fiction/io/read_sqd_layout.hpp>
+#include <fiction/io/write_sqd_layout.hpp>
 #include <fiction/layouts/clocking_scheme.hpp>
 #include <fiction/layouts/gate_level_layout.hpp>
 #include <fiction/technology/sidb_bestagon_library.hpp>
@@ -85,7 +86,9 @@ TEST_CASE("Gate-level layout with AND gate", "[apply-gate-library]")
                 apply_parameterized_gate_library<cell_lyt, sidb_on_the_fly_gate_library, hex_even_row_gate_clk_lyt>(
                     layout, params);
 
-            check_equivalence(bestagon_and, fmt::format("{}/resources/AND_gate.sqd", TEST_PATH));
+            check_equivalence(
+                bestagon_and,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/single_tile_layout/AND_gate.sqd", TEST_PATH));
 
             CHECK(is_operational(bestagon_and, std::vector<tt>{create_and_tt()}, design_gate_params.operational_params)
                       .first == operational_status::OPERATIONAL);
@@ -145,7 +148,9 @@ TEST_CASE("Gate-level layout with two input wires, one double wire, and two outp
     {
         const auto double_wire = apply_gate_library<cell_lyt, sidb_bestagon_library, hex_even_row_gate_clk_lyt>(layout);
 
-        check_equivalence(double_wire, fmt::format("{}/resources/double_wire.sqd", TEST_PATH));
+        check_equivalence(
+            double_wire,
+            fmt::format("{}/resources/sidb_bestagon_library/multi_tile_layout/double_wire.sqd", TEST_PATH));
     }
 
     SECTION("Use parameterized gate library")
@@ -169,7 +174,10 @@ TEST_CASE("Gate-level layout with two input wires, one double wire, and two outp
                 apply_parameterized_gate_library<cell_lyt, sidb_on_the_fly_gate_library, hex_even_row_gate_clk_lyt>(
                     layout, params);
 
-            check_equivalence(bestagon_double_wire, fmt::format("{}/resources/predefined_double_wire.sqd", TEST_PATH));
+            check_equivalence(
+                bestagon_double_wire,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/predefined_double_wire.sqd",
+                            TEST_PATH));
         }
         SECTION("Design all gates of the layout on-the-fly")
         {
@@ -187,7 +195,14 @@ TEST_CASE("Gate-level layout with two input wires, one double wire, and two outp
                 apply_parameterized_gate_library<cell_lyt, sidb_on_the_fly_gate_library, hex_even_row_gate_clk_lyt>(
                     layout, params);
 
-            check_equivalence(bestagon_double_wire, fmt::format("{}/resources/double_wire_gate.sqd", TEST_PATH));
+            fiction::write_sqd_layout(
+                bestagon_double_wire,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/double_wire.sqd", TEST_PATH));
+
+            // todo
+            check_equivalence(
+                bestagon_double_wire,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/double_wire.sqd", TEST_PATH));
 
             SECTION("with defects")
             {
@@ -206,8 +221,11 @@ TEST_CASE("Gate-level layout with two input wires, one double wire, and two outp
                 CHECK(bestagon_double_wire_with_defects.get_sidb_defect({30, 20, 0}).type == sidb_defect_type::DB);
                 CHECK(bestagon_double_wire_with_defects.get_sidb_defect({45, 55, 0}).type == sidb_defect_type::DB);
 
-                check_equivalence(bestagon_double_wire,
-                                  fmt::format("{}/resources/double_wire_and_defects.sqd", TEST_PATH));
+                check_equivalence(
+                    bestagon_double_wire,
+                    fmt::format(
+                        "{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/double_wire_and_defects.sqd",
+                        TEST_PATH));
             }
         }
     }
@@ -228,7 +246,8 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
             const auto inverter =
                 apply_gate_library<cell_lyt, sidb_bestagon_library, hex_even_row_gate_clk_lyt>(layout);
 
-            check_equivalence(inverter, fmt::format("{}/resources/INV.sqd", TEST_PATH));
+            check_equivalence(inverter,
+                              fmt::format("{}/resources/sidb_bestagon_library/multi_tile_layout/INV.sqd", TEST_PATH));
         }
 
         SECTION("Use parameterized gate library")
@@ -248,7 +267,9 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
                 apply_parameterized_gate_library<cell_lyt, sidb_on_the_fly_gate_library, hex_even_row_gate_clk_lyt>(
                     layout, params);
 
-            check_equivalence(inverter, fmt::format("{}/resources/INV.sqd", TEST_PATH));
+            check_equivalence(
+                inverter,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/INV.sqd", TEST_PATH));
 
             SECTION("with defects")
             {
@@ -264,7 +285,10 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
 
                 CHECK(inverter_with_defects.num_defects() == 1);
 
-                check_equivalence(inverter_with_defects, fmt::format("{}/resources/INV_and_defects.sqd", TEST_PATH));
+                check_equivalence(
+                    inverter_with_defects,
+                    fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/INV_and_defects.sqd",
+                                TEST_PATH));
             }
         }
     }
@@ -283,7 +307,8 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
             const auto or_layout =
                 apply_gate_library<cell_lyt, sidb_bestagon_library, hex_even_row_gate_clk_lyt>(layout);
 
-            check_equivalence(or_layout, fmt::format("{}/resources/OR.sqd", TEST_PATH));
+            check_equivalence(or_layout,
+                              fmt::format("{}/resources/sidb_bestagon_library/multi_tile_layout/OR.sqd", TEST_PATH));
         }
 
         SECTION("Use parameterized gate library")
@@ -303,7 +328,9 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
                 apply_parameterized_gate_library<cell_lyt, sidb_on_the_fly_gate_library, hex_even_row_gate_clk_lyt>(
                     layout, params);
 
-            check_equivalence(or_layout, fmt::format("{}/resources/OR.sqd", TEST_PATH));
+            check_equivalence(
+                or_layout,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/OR.sqd", TEST_PATH));
 
             SECTION("with defects")
             {
@@ -319,7 +346,10 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
 
                 CHECK(or_layout_with_defects.num_defects() == 1);
 
-                check_equivalence(or_layout_with_defects, fmt::format("{}/resources/OR_and_defects.sqd", TEST_PATH));
+                check_equivalence(
+                    or_layout_with_defects,
+                    fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/OR_and_defects.sqd",
+                                TEST_PATH));
             }
         }
     }
@@ -338,7 +368,8 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
             const auto nand_layout =
                 apply_gate_library<cell_lyt, sidb_bestagon_library, hex_even_row_gate_clk_lyt>(layout);
 
-            check_equivalence(nand_layout, fmt::format("{}/resources/NAND.sqd", TEST_PATH));
+            check_equivalence(nand_layout,
+                              fmt::format("{}/resources/sidb_bestagon_library/multi_tile_layout/NAND.sqd", TEST_PATH));
         }
 
         SECTION("Use parameterized gate library")
@@ -358,7 +389,9 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
                 apply_parameterized_gate_library<cell_lyt, sidb_on_the_fly_gate_library, hex_even_row_gate_clk_lyt>(
                     layout, params);
 
-            check_equivalence(nand_layout, fmt::format("{}/resources/NAND.sqd", TEST_PATH));
+            check_equivalence(
+                nand_layout,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/NAND.sqd", TEST_PATH));
 
             SECTION("with defects")
             {
@@ -379,8 +412,10 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
 
                 CHECK(nand_layout_with_defects.num_defects() == 2);
 
-                check_equivalence(nand_layout_with_defects,
-                                  fmt::format("{}/resources/NAND_and_defects.sqd", TEST_PATH));
+                check_equivalence(
+                    nand_layout_with_defects,
+                    fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/NAND_and_defects.sqd",
+                                TEST_PATH));
             }
         }
     }
@@ -399,7 +434,8 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
             const auto nor_layout =
                 apply_gate_library<cell_lyt, sidb_bestagon_library, hex_even_row_gate_clk_lyt>(layout);
 
-            check_equivalence(nor_layout, fmt::format("{}/resources/NOR.sqd", TEST_PATH));
+            check_equivalence(nor_layout,
+                              fmt::format("{}/resources/sidb_bestagon_library/multi_tile_layout/NOR.sqd", TEST_PATH));
         }
 
         SECTION("Use parameterized gate library")
@@ -419,7 +455,9 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
                 apply_parameterized_gate_library<cell_lyt, sidb_on_the_fly_gate_library, hex_even_row_gate_clk_lyt>(
                     layout, params);
 
-            check_equivalence(nor_layout, fmt::format("{}/resources/NOR.sqd", TEST_PATH));
+            check_equivalence(
+                nor_layout,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/NOR.sqd", TEST_PATH));
         }
     }
 
@@ -437,7 +475,8 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
             const auto xor_layout =
                 apply_gate_library<cell_lyt, sidb_bestagon_library, hex_even_row_gate_clk_lyt>(layout);
 
-            check_equivalence(xor_layout, fmt::format("{}/resources/XOR.sqd", TEST_PATH));
+            check_equivalence(xor_layout,
+                              fmt::format("{}/resources/sidb_bestagon_library/multi_tile_layout/XOR.sqd", TEST_PATH));
         }
 
         SECTION("Use parameterized gate library")
@@ -457,7 +496,9 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
                 apply_parameterized_gate_library<cell_lyt, sidb_on_the_fly_gate_library, hex_even_row_gate_clk_lyt>(
                     layout, params);
 
-            check_equivalence(xor_layout, fmt::format("{}/resources/XOR.sqd", TEST_PATH));
+            check_equivalence(
+                xor_layout,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/XOR.sqd", TEST_PATH));
         }
 
         SECTION("Use parameterized gate library, reject kinks")
@@ -479,7 +520,10 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
                 apply_parameterized_gate_library<cell_lyt, sidb_on_the_fly_gate_library, hex_even_row_gate_clk_lyt>(
                     layout, params);
 
-            check_equivalence(xor_layout, fmt::format("{}/resources/XOR_rejecting_kinks.sqd", TEST_PATH));
+            check_equivalence(
+                xor_layout,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/XOR_rejecting_kinks.sqd",
+                            TEST_PATH));
         }
     }
 
@@ -497,7 +541,8 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
             const auto xnor_layout =
                 apply_gate_library<cell_lyt, sidb_bestagon_library, hex_even_row_gate_clk_lyt>(layout);
 
-            check_equivalence(xnor_layout, fmt::format("{}/resources/XNOR.sqd", TEST_PATH));
+            check_equivalence(xnor_layout,
+                              fmt::format("{}/resources/sidb_bestagon_library/multi_tile_layout/XNOR.sqd", TEST_PATH));
         }
 
         SECTION("Use parameterized gate library")
@@ -517,7 +562,9 @@ TEST_CASE("Gate-level layout with with different gates", "[apply-gate-library]")
                 apply_parameterized_gate_library<cell_lyt, sidb_on_the_fly_gate_library, hex_even_row_gate_clk_lyt>(
                     layout, params);
 
-            check_equivalence(xnor_layout, fmt::format("{}/resources/XNOR.sqd", TEST_PATH));
+            check_equivalence(
+                xnor_layout,
+                fmt::format("{}/resources/sidb_on_the_fly_gate_library/multi_tile_layout/XNOR.sqd", TEST_PATH));
         }
     }
 }