✨ Added a framework for accurate and efficient simulation of SiDB logic

docs/index.rst

@@ -49,6 +49,7 @@ Let there be a *fiction*
 
    technology/cell_technologies.rst
    technology/defects.rst
+   technology/simulation.rst
    technology/gate_libraries.rst
    technology/properties.rst
 

docs/layouts/coordinates.rst

@@ -22,8 +22,18 @@ At the same time, they can be used to address 3-dimensional grids.
 
 .. doxygenstruct:: fiction::cube::coord_t
 
+SiQAD coordinates
+----------------
+
+SiQAD coordinates are used to describe locations of Silicon Dangling Bonds on the H-Si(100) 2x1 surface were dimer columns and rows are identified by x and y values, respecitvely,
+while the z value (0,1) points to the top or bottom Si atom in the dimer. The coordinates are originally used in the SiQAD simulator (https://github.com/siqad).
+
+.. doxygenstruct:: fiction::siqad::coord_t
+
 Utility functions
 -----------------
 
 .. doxygenfunction:: fiction::area(const CoordinateType& coord) noexcept
 .. doxygenfunction:: fiction::volume(const CoordinateType& coord) noexcept
+.. doxygenfunction:: fiction::to_fiction_coord(const fiction::offset::ucoord_t& coord) noexcept
+.. doxygenfunction:: fiction::to_siqad_coord(const CoordinateType& coord) noexcept

docs/technology/simulation.rst

@@ -0,0 +1,17 @@
+Physical Simulation of SiDBs
+===================
+
+Layout to store and read charge states of a SiDB layout
+
+SiDB charge states
+------------
+
+**Header:** ``fiction/technology/sidb_charge_state.hpp``
+
+.. doxygenenum:: fiction::sidb_charge_state
+
+**Header:** ``fiction/technology/charge_distribution_surface.hpp``
+
+.. doxygenclass:: fiction::charge_distribution_surface
+   :members:
+

experiments/defect_aware_physical_design/generate_defective_surface.py

@@ -1,11 +1,10 @@
 # this one treats each H-Si as an array value
 
 
-import random
-import sys
-
 import matplotlib.pyplot as plt
 import numpy as np
+import random
+import sys
 
 np.set_printoptions(threshold=sys.maxsize)
 from matplotlib.axes._axes import _log as matplotlib_axes_logger

include/fiction/algorithms/path_finding/distance.hpp

@@ -5,6 +5,7 @@
 #ifndef FICTION_DISTANCE_HPP
 #define FICTION_DISTANCE_HPP
 
+#include "fiction/technology/sidb_nm_position.hpp"
 #include "fiction/traits.hpp"
 
 #include <cmath>
@@ -61,6 +62,33 @@ template <typename Lyt, typename Dist = double>
 
     return static_cast<Dist>(std::hypot(x, y));
 }
+/**
+ * Computes the distance between two SiDB cells in nanometers.
+ *
+ * @tparam Lyt SiDB cell-level layout type.
+ * @tparam Dist Floating-point type for the distance.
+ * @param c1 The first cell.
+ * @param c2 The second cell.
+ * @return The distance between the two cells in nanometers.
+ */
+template <typename Lyt, typename Dist = double>
+[[nodiscard]] constexpr Dist
+sidb_nanometer_distance([[maybe_unused]] const Lyt& lyt, const coordinate<Lyt>& source, const coordinate<Lyt>& target,
+                        const sidb_simulation_parameters& sp = sidb_simulation_parameters{}) noexcept
+{
+    static_assert(is_cell_level_layout_v<Lyt>, "Lyt is not a cell-level layout");
+    static_assert(has_sidb_technology_v<Lyt>, "Lyt is not based on SiDB technology");
+    static_assert(has_siqad_coord_v<Lyt>, "Lyt is not based on SiQAD coordinates");
+    static_assert(std::is_floating_point_v<Dist>, "Dist is not a floating-point type");
+
+    const auto pos_c1 = sidb_nm_position<Lyt>(sp, source);
+    const auto pos_c2 = sidb_nm_position<Lyt>(sp, target);
+
+    const auto x = static_cast<Dist>(pos_c1.first) - static_cast<double>(pos_c2.first);
+    const auto y = static_cast<Dist>(pos_c1.second) - static_cast<double>(pos_c2.second);
+
+    return static_cast<Dist>(std::hypot(x, y));
+}
 
 // NOLINTBEGIN(*-special-member-functions): virtual destructor is prudent
 

include/fiction/algorithms/simulation_sidb/check_groundstate.hpp

@@ -0,0 +1,49 @@
+//
+// Created by Jan Drewniok on 18.01.23.
+//
+
+#ifndef FICTION_CHECK_GROUNDSTATE_HPP
+#define FICTION_CHECK_GROUNDSTATE_HPP
+
+#include "fiction/algorithms/simulation_sidb/exhaustive_ground_state_simulation.hpp"
+#include "fiction/algorithms/simulation_sidb/minimum_energy.hpp"
+#include "fiction/algorithms/simulation_sidb/quicksim.hpp"
+#include "fiction/traits.hpp"
+
+#include <cmath>
+
+namespace fiction
+{
+
+/**
+ * This function checks if the ground state is found by the quicksim algorithm.
+ *
+ * @tparam Lyt Cell-level layout type.
+ * @param quicksim_results All found physically valid charge distribution surfaces obtained with the new quicksim
+ * algorithm (see quicksim.hpp).
+ * @param exhaustive_results All valid charge distribution surfaces (ExGS, see ExGS.hpp).
+ * @return Returns `true` if the relative difference between the lowest energies of the two sets is less than 0.00001,
+ * `false` otherwise.
+ */
+template <typename Lyt>
+[[nodiscard]] bool check_groundstate(const quicksim_stats<Lyt>& quicksim_results,
+                                     const exgs_stats<Lyt>&     exhaustive_results)
+{
+    static_assert(is_cell_level_layout_v<Lyt>, "Lyt is not a cell-level layout");
+    static_assert(has_sidb_technology_v<Lyt>, "Lyt is not an SiDB layout");
+    static_assert(has_siqad_coord_v<Lyt>, "Lyt is not based on SiQAD coordinates");
+
+    if (exhaustive_results.valid_lyts.empty())
+    {
+        return false;
+    }
+
+    const auto min_energy_exact  = minimum_energy(exhaustive_results.valid_lyts);
+    const auto min_energy_new_ap = minimum_energy(quicksim_results.valid_lyts);
+
+    return std::abs(min_energy_exact - min_energy_new_ap) / min_energy_exact < 0.00001;
+}
+
+}  // namespace fiction
+
+#endif  // FICTION_CHECK_GROUNDSTATE_HPP

include/fiction/algorithms/simulation_sidb/energy_distribution.hpp

@@ -0,0 +1,48 @@
+//
+// Created by Jan Drewniok on 17.01.23.
+//
+
+#ifndef FICTION_ENERGY_DISTRIBUTION_HPP
+#define FICTION_ENERGY_DISTRIBUTION_HPP
+
+#include "fiction/technology/charge_distribution_surface.hpp"
+
+#include <cmath>
+#include <cstdint>
+#include <map>
+#include <vector>
+
+namespace fiction
+{
+
+/**
+ * This function takes in a vector of charge_distribution_surface objects and returns a map containing the system energy
+ * and the number of occurrences of that energy in the input vector.
+ *
+ * @tparam Lyt Cell-level layout type.
+ * @param input_vec A vector of charge_distribution_surface objects for which statistics are to be computed.
+ * @return A map containing the system energy as the key and the number of occurrences of that energy in the input
+ * vector as the value.
+ */
+template <typename Lyt>
+std::map<double, uint64_t> energy_distribution(const std::vector<charge_distribution_surface<Lyt>>& input_vec)
+{
+    static_assert(is_cell_level_layout_v<Lyt>, "Lyt is not a cell-level layout");
+    static_assert(has_sidb_technology_v<Lyt>, "Lyt is not an SiDB layout");
+
+    std::map<double, uint64_t> distribution{};
+
+    for (const auto& lyt : input_vec)
+    {
+        const auto energy =
+            std::round(lyt.get_system_energy() * 1'000'000) / 1'000'000;  // rounding to 6 decimal places.
+
+        distribution[energy]++;
+    }
+
+    return distribution;
+}
+
+}  // namespace fiction
+
+#endif  // FICTION_ENERGY_DISTRIBUTION_HPP

include/fiction/algorithms/simulation_sidb/exhaustive_ground_state_simulation.hpp

@@ -0,0 +1,100 @@
+//
+// Created by Jan Drewniok on 18.12.22.
+//
+
+#ifndef FICTION_EXHAUSTIVE_GROUND_STATE_SIMULATION_HPP
+#define FICTION_EXHAUSTIVE_GROUND_STATE_SIMULATION_HPP
+
+#include "fiction/algorithms/simulation_sidb/energy_distribution.hpp"
+#include "fiction/algorithms/simulation_sidb/minimum_energy.hpp"
+#include "fiction/algorithms/simulation_sidb/sidb_simulation_parameters.hpp"
+#include "fiction/technology/charge_distribution_surface.hpp"
+
+#include <fmt/format.h>
+#include <mockturtle/utils/stopwatch.hpp>
+
+#include <iostream>
+#include <vector>
+
+namespace fiction
+{
+
+template <typename Lyt>
+struct exgs_stats
+{
+    mockturtle::stopwatch<>::duration             time_total{0};
+    std::vector<charge_distribution_surface<Lyt>> valid_lyts{};
+
+    void report(std::ostream& out = std::cout) const
+    {
+        out << fmt::format("total time  = {:.2f} secs\n", mockturtle::to_seconds(time_total));
+        if (!valid_lyts.empty())
+        {
+            for (const auto& [energy, count] : energy_distribution<Lyt>(valid_lyts))
+            {
+                out << fmt::format("energy: {} | occurance: {} \n", energy, count);
+            }
+            out << fmt::format("the ground state energy is  = {:.4f} \n", minimum_energy(valid_lyts));
+        }
+        else
+        {
+            std::cout << "no state found | if two state simulation is used, continue with three state" << std::endl;
+        }
+
+        out << fmt::format("{} phyiscally valid charge states were found \n", valid_lyts.size());
+        std::cout << "_____________________________________________________ \n";
+    }
+};
+
+/**
+ *  All metastable and physically valid charge distribution layouts are computed, stored in a vector and returned.
+ *
+ * @tparam Lyt Cell-level layout type.
+ * @param lyt Charge distribution layout.
+ * @param params Simulation parameters.
+ * @param ps Simulation statistics.
+ */
+template <typename Lyt>
+void exhaustive_ground_state_simulation(charge_distribution_surface<Lyt>& lyt,
+                                        const sidb_simulation_parameters& params = sidb_simulation_parameters{},
+                                        exgs_stats<Lyt>*                  ps     = nullptr)
+{
+    static_assert(is_cell_level_layout_v<Lyt>, "Lyt is not a cell-level layout");
+    static_assert(has_sidb_technology_v<Lyt>, "Lyt is not an SiDB layout");
+
+    exgs_stats<Lyt> st{};
+
+    {
+        mockturtle::stopwatch stop{st.time_total};
+        lyt.set_physical_parameters(params);
+        lyt.set_all_charge_states(sidb_charge_state::NEGATIVE);
+        lyt.update_after_charge_change();
+
+        while (lyt.get_charge_index().first < lyt.get_max_charge_index())
+        {
+
+            if (lyt.is_physically_valid())
+            {
+                charge_distribution_surface<Lyt> lyt_new{lyt};
+                st.valid_lyts.push_back(lyt_new);
+            }
+
+            lyt.increase_charge_index_by_one();
+        }
+
+        if (lyt.is_physically_valid())
+        {
+            charge_distribution_surface<Lyt> lyt_new{lyt};
+            st.valid_lyts.push_back(lyt_new);
+        }
+    }
+
+    if (ps)
+    {
+        *ps = st;
+    }
+}
+
+}  // namespace fiction
+
+#endif  // FICTION_EXHAUSTIVE_GROUND_STATE_SIMULATION_HPP

include/fiction/algorithms/simulation_sidb/minimum_energy.hpp

@@ -0,0 +1,36 @@
+//
+// Created by Jan Drewniok on 18.01.23.
+//
+
+#ifndef FICTION_MINIMUM_ENERGY_HPP
+#define FICTION_MINIMUM_ENERGY_HPP
+
+#include "fiction/technology/charge_distribution_surface.hpp"
+
+#include <algorithm>
+#include <limits>
+#include <vector>
+
+namespace fiction
+{
+
+/**
+ * Computes the minimum energy of a vector of charge_distribution_surface objects.
+ *
+ * @tparam Lyt Cell-level layout type.
+ * @param result Vector of charge_distribution_surface objects.
+ * @return Value of the minimum energy found in the input vector.
+ */
+template <typename Lyt>
+double minimum_energy(const std::vector<charge_distribution_surface<Lyt>>& charge_lyts)
+{
+    static_assert(is_cell_level_layout_v<Lyt>, "Lyt is not a cell-level layout");
+    static_assert(has_sidb_technology_v<Lyt>, "Lyt is not an SiDB layout");
+
+    return std::accumulate(charge_lyts.begin(), charge_lyts.end(), std::numeric_limits<double>::max(),
+                           [](double a, const auto& lyt) { return std::min(a, lyt.get_system_energy()); });
+}
+
+}  // namespace fiction
+
+#endif  // FICTION_MINIMUM_ENERGY_HPP