✨ Extended Time-to-Solution Function

bindings/pyfiction/include/pyfiction/algorithms/simulation/sidb/sidb_simulation_engine.hpp

@@ -26,12 +26,11 @@ inline void sidb_simulation_engine(pybind11::module& m)
 
         ;
 
-    py::enum_<fiction::exhaustive_sidb_simulation_engine>(m, "exhaustive_sidb_simulation_engine",
-                                                          DOC(fiction_exhaustive_sidb_simulation_engine))
-        .value("EXGS", fiction::exhaustive_sidb_simulation_engine::EXGS,
-               DOC(fiction_exhaustive_sidb_simulation_engine_EXGS))
-        .value("QUICKEXACT", fiction::exhaustive_sidb_simulation_engine::QUICKEXACT,
-               DOC(fiction_exhaustive_sidb_simulation_engine_QUICKEXACT))
+    py::enum_<fiction::exact_sidb_simulation_engine>(m, "exact_sidb_simulation_engine",
+                                                     DOC(fiction_exact_sidb_simulation_engine))
+        .value("EXGS", fiction::exact_sidb_simulation_engine::EXGS, DOC(fiction_exact_sidb_simulation_engine_EXGS))
+        .value("QUICKEXACT", fiction::exact_sidb_simulation_engine::QUICKEXACT,
+               DOC(fiction_exact_sidb_simulation_engine_QUICKEXACT))
 
         ;
 }

bindings/pyfiction/include/pyfiction/algorithms/simulation/sidb/time_to_solution.hpp

@@ -20,12 +20,15 @@ namespace detail
 {
 
 template <typename Lyt>
-void time_to_solution(pybind11::module& m, const std::string& lattice = "")
+void time_to_solution(pybind11::module& m)
 {
     using namespace pybind11::literals;
 
     m.def("time_to_solution", &fiction::time_to_solution<Lyt>, "lyt"_a, "quickim_params"_a,
           "tts_params"_a = fiction::time_to_solution_params{}, "ps"_a = nullptr, DOC(fiction_time_to_solution));
+    m.def("time_to_solution_for_given_simulation_results", &fiction::time_to_solution_for_given_simulation_results<Lyt>,
+          "results_exact"_a, "results_heuristic"_a, "confidence_level"_a = 0.997, "ps"_a = nullptr,
+          DOC(fiction_time_to_solution_for_given_simulation_results));
 }
 
 }  // namespace detail
@@ -54,8 +57,8 @@ inline void time_to_solution(pybind11::module& m)
         .def_readwrite("acc", &fiction::time_to_solution_stats::acc, DOC(fiction_time_to_solution_stats_acc))
         .def_readwrite("mean_single_runtime", &fiction::time_to_solution_stats::mean_single_runtime,
                        DOC(fiction_time_to_solution_stats_mean_single_runtime))
-        .def_readwrite("single_runtime_exhaustive", &fiction::time_to_solution_stats::single_runtime_exhaustive,
-                       DOC(fiction_time_to_solution_stats_single_runtime_exhaustive))
+        .def_readwrite("single_runtime_exact", &fiction::time_to_solution_stats::single_runtime_exact,
+                       DOC(fiction_time_to_solution_stats_single_runtime_exact))
         .def_readwrite("algorithm", &fiction::time_to_solution_stats::algorithm,
                        DOC(fiction_time_to_solution_stats_algorithm))
         .def("report", &fiction::time_to_solution_stats::report, DOC(fiction_time_to_solution_stats_report));

bindings/pyfiction/include/pyfiction/pybind11_mkdoc_docstrings.hpp

@@ -1914,6 +1914,18 @@ R"doc(The previous charge distribution is not used. Hence, the local
 electrostatic potential of the given charge distribution is calculated
 from scratch.)doc";
 
+static const char *__doc_fiction_charge_distribution_mode =
+R"doc(An enumeration of modes for handling the charge distribution when
+assigning a charge index to the charge distribution surface.)doc";
+
+static const char *__doc_fiction_charge_distribution_mode_KEEP_CHARGE_DISTRIBUTION =
+R"doc(The charge distribution is kept and is not updated after a charge
+index is assigned to the charge distribution surface.)doc";
+
+static const char *__doc_fiction_charge_distribution_mode_UPDATE_CHARGE_DISTRIBUTION =
+R"doc(The charge distribution is updated after the charge index is assigned
+to the charge distribution surface.)doc";
+
 static const char *__doc_fiction_charge_distribution_surface = R"doc()doc";
 
 static const char *__doc_fiction_charge_distribution_surface_2 = R"doc()doc";
@@ -8910,6 +8922,17 @@ static const char *__doc_fiction_exact_physical_design_stats_x_size = R"doc()doc
 
 static const char *__doc_fiction_exact_physical_design_stats_y_size = R"doc()doc";
 
+static const char *__doc_fiction_exact_sidb_simulation_engine = R"doc(Selector exclusively for exact SiDB simulation engines.)doc";
+
+static const char *__doc_fiction_exact_sidb_simulation_engine_EXGS =
+R"doc(*Exhaustive Ground State Search* (EXGS) is an exact simulation engine
+that always has exponential runtime.)doc";
+
+static const char *__doc_fiction_exact_sidb_simulation_engine_QUICKEXACT =
+R"doc(*QuickExact* is also an exact simulation engine that requires
+exponential runtime, but it scales a lot better than ExGS due to its
+effective search-space pruning.)doc";
+
 static const char *__doc_fiction_exact_with_blacklist =
 R"doc(The same as `exact` but with a black list of tiles that are not
 allowed to be used to a specified set of Boolean functions and their
@@ -8973,17 +8996,6 @@ Parameter ``ps``:
 Returns:
     sidb_simulation_result is returned with all results.)doc";
 
-static const char *__doc_fiction_exhaustive_sidb_simulation_engine = R"doc(Selector exclusively for exhaustive SiDB simulation engines.)doc";
-
-static const char *__doc_fiction_exhaustive_sidb_simulation_engine_EXGS =
-R"doc(*Exhaustive Ground State Search* (EXGS) is an exact simulation engine
-that always has exponential runtime.)doc";
-
-static const char *__doc_fiction_exhaustive_sidb_simulation_engine_QUICKEXACT =
-R"doc(*QuickExact* is also an exact simulation engine that requires
-exponential runtime, but it scales a lot better than ExGS due to its
-effective search-space pruning.)doc";
-
 static const char *__doc_fiction_extract_routing_objectives =
 R"doc(Extracts all routing objectives from the given layout. To this end,
 all routing paths in the layout are traversed, starting at each PI.
@@ -12386,22 +12398,22 @@ Parameter ``ps``:
 static const char *__doc_fiction_is_gate_level_layout = R"doc()doc";
 
 static const char *__doc_fiction_is_ground_state =
-R"doc(This function checks if the ground state is found by the *QuickSim*
-algorithm.
+R"doc(This function checks if the elstrostatic ground state of an SiDB
+layout is found by a heuristic for the physical simulation (e.g.,
+*QuickSim* or *SimAnneal*).
 
 Template parameter ``Lyt``:
-    Cell-level layout type.
+    SiDB cell-level layout type.
 
 Parameter ``heuristic_results``:
-    All found physically valid charge distribution surfaces obtained
-    by a heuristic algorithm.
+    Simulation results obtained from a heuristic physical simulation.
 
-Parameter ``exhaustive_results``:
-    All valid charge distribution surfaces determined by ExGS.
+Parameter ``exact_results``:
+    Simulation results obtained from an exact physical simulation.
 
 Returns:
-    Returns `true` if the relative difference between the lowest
-    energies of the two sets is less than :math:`0.00001`, `false`
+    Returns `true` if the ground state is contained in the simulation
+    result provided by the heuristic physical simulation. `false`
     otherwise.)doc";
 
 static const char *__doc_fiction_is_hexagonal_layout = R"doc()doc";
@@ -15614,7 +15626,7 @@ algorithm, the physical parameters used in the simulation, and
 (optional) algorithm-specific named simulation parameters.
 
 Template parameter ``Lyt``:
-    Cell-level layout type.)doc";
+    SiDB cell-level layout type.)doc";
 
 static const char *__doc_fiction_sidb_simulation_result_additional_simulation_parameters =
 R"doc(Additional named simulation parameters. This is used to store
@@ -16621,7 +16633,7 @@ R"doc(This function determines the time-to-solution (TTS) and the accuracy
 (acc) of the *QuickSim* algorithm.
 
 Template parameter ``Lyt``:
-    Cell-level layout type.
+    SiDB cell-level layout type.
 
 Parameter ``lyt``:
     Layout that is used for the simulation.
@@ -16636,9 +16648,41 @@ Parameter ``ps``:
     Pointer to a struct where the results (time_to_solution, acc,
     single runtime) are stored.)doc";
 
+static const char *__doc_fiction_time_to_solution_for_given_simulation_results =
+R"doc(This function calculates the Time-to-Solution (TTS) by analyzing the
+simulation results of a heuristic algorithm in comparison to those of
+an exact algorithm. It provides further statistical metrics, including
+the accuracy of the heuristic algorithm, and individual runtimes.
+
+Template parameter ``Lyt``:
+    SiDB ell-level layout type.
+
+Parameter ``results_exact``:
+    Simulation results of the exact algorithm.
+
+Parameter ``results_heuristic``:
+    Simulation of the heuristic for which the TTS is determined.
+
+Parameter ``confidence_level``:
+    Confidence level for the TTS computation. The confidence level
+    represents the probability that the confidence interval calculated
+    from the simulation contains the true value. For example, a 95 %
+    (0.95) confidence level means that if the simulation were repeated
+    many times, approximately 95 out of 100 of the calculated
+    confidence intervals would contain the true value.
+
+Parameter ``ps``:
+    Pointer to a struct where the statistics of this function call
+    (time_to_solution, acc, single runtime) are to be stored.)doc";
+
 static const char *__doc_fiction_time_to_solution_params = R"doc()doc";
 
-static const char *__doc_fiction_time_to_solution_params_confidence_level = R"doc(Confidence level.)doc";
+static const char *__doc_fiction_time_to_solution_params_confidence_level =
+R"doc(The confidence level represents the probability that the confidence
+interval calculated from the simulation contains the true value. For
+example, a 99.7 % (0.997) confidence level means that if the
+simulation were repeated many times, approximately 997 out of 1000 of
+the calculated confidence intervals would contain the true value.)doc";
 
 static const char *__doc_fiction_time_to_solution_params_engine =
 R"doc(Exhaustive simulation algorithm used to simulate the ground state as
@@ -16655,10 +16699,10 @@ the average single simulation runtime of *QuickSim*, the single
 runtime of the exact simulator used, and the number of valid charge
 configurations found by the exact algorithm.)doc";
 
-static const char *__doc_fiction_time_to_solution_stats_acc = R"doc(Accuracy of the simulation.)doc";
+static const char *__doc_fiction_time_to_solution_stats_acc = R"doc(Accuracy of the simulation in %.)doc";
 
 static const char *__doc_fiction_time_to_solution_stats_algorithm =
-R"doc(Exhaustive simulation algorithm used to simulate the ground state as
+R"doc(Exact simulation algorithm used to simulate the ground state as
 reference.)doc";
 
 static const char *__doc_fiction_time_to_solution_stats_mean_single_runtime = R"doc(Average single simulation runtime in seconds.)doc";
@@ -16669,9 +16713,9 @@ R"doc(Print the results to the given output stream.
 Parameter ``out``:
     Output stream.)doc";
 
-static const char *__doc_fiction_time_to_solution_stats_single_runtime_exhaustive =
-R"doc(Single simulation runtime of the exhaustive ground state searcher in
-seconds.)doc";
+static const char *__doc_fiction_time_to_solution_stats_single_runtime_exact =
+R"doc(Single simulation runtime of the exact ground state simulation
+algorithm.)doc";
 
 static const char *__doc_fiction_time_to_solution_stats_time_to_solution = R"doc(Time-to-solution in seconds.)doc";
 

bindings/pyfiction/include/pyfiction/technology/charge_distribution_surface.hpp

@@ -164,18 +164,17 @@ void charge_distribution_surface_layout(pybind11::module& m, const std::string&
             "increase_charge_index_by_one",
             [](py_cds& cds, fiction::dependent_cell_mode dependent_cell_fixed,
                fiction::energy_calculation          recompute_system_energy,
-               fiction::charge_distribution_history consider_history, fiction::exhaustive_sidb_simulation_engine engine)
-            {
+               fiction::charge_distribution_history consider_history, fiction::exact_sidb_simulation_engine engine) {
                 return cds.increase_charge_index_by_one(dependent_cell_fixed, recompute_system_energy, consider_history,
                                                         engine);
             },
             "dependent_cell_fixed"_a    = fiction::dependent_cell_mode::FIXED,
             "recompute_system_energy"_a = fiction::energy_calculation::UPDATE_ENERGY,
             "consider_history"_a        = fiction::charge_distribution_history::NEGLECT,
-            "engine"_a                  = fiction::exhaustive_sidb_simulation_engine::EXGS)
+            "engine"_a                  = fiction::exact_sidb_simulation_engine::EXGS)
 
         .def("get_max_charge_index", &py_cds::get_max_charge_index)
-        .def("assign_charge_index", &py_cds::assign_charge_index, "charge_index"_a)
+        .def("assign_charge_index", &py_cds::assign_charge_index, "charge_index"_a, "cdc"_a)
         .def("adjacent_search", &py_cds::adjacent_search, "alpha"_a, "negative_indices"_a)
         .def("assign_global_external_potential", &py_cds::assign_global_external_potential, "potential_value"_a,
              "dependent_cell"_a = fiction::dependent_cell_mode::FIXED)
@@ -205,7 +204,7 @@ void charge_distribution_surface_layout(pybind11::module& m, const std::string&
              "dependent_cell_fixed"_a    = fiction::dependent_cell_mode::FIXED,
              "recompute_system_energy"_a = fiction::energy_calculation::UPDATE_ENERGY,
              "consider_history"_a        = fiction::charge_distribution_history::NEGLECT,
-             "engine"_a                  = fiction::exhaustive_sidb_simulation_engine::EXGS)
+             "engine"_a                  = fiction::exact_sidb_simulation_engine::EXGS)
         .def("assign_charge_index_by_gray_code", &py_cds::assign_charge_index_by_gray_code, "current_gray_code"_a,
              "previous_gray_code"_a, "dependent_cell"_a = fiction::dependent_cell_mode::FIXED,
              "energy_calc_mode"_a = fiction::energy_calculation::UPDATE_ENERGY,
@@ -293,6 +292,18 @@ inline void charge_distribution_surfaces(pybind11::module& m)
 
         ;
 
+    /**
+     * Charge distribution mode.
+     */
+    py::enum_<fiction::charge_distribution_mode>(m, "charge_distribution_mode", py::module_local(),
+                                                 DOC(fiction_charge_distribution_mode))
+        .value("UPDATE_CHARGE_DISTRIBUTION", fiction::charge_distribution_mode::UPDATE_CHARGE_DISTRIBUTION,
+               DOC(fiction_charge_distribution_mode_UPDATE_CHARGE_DISTRIBUTION))
+        .value("KEEP_CHARGE_DISTRIBUTION", fiction::charge_distribution_mode::KEEP_CHARGE_DISTRIBUTION,
+               DOC(fiction_charge_distribution_mode_KEEP_CHARGE_DISTRIBUTION))
+
+        ;
+
     /**
      * Charge index mode.
      */

bindings/pyfiction/test/algorithms/simulation/sidb/test_time_to_solution.py

@@ -1,6 +1,6 @@
 from mnt.pyfiction import *
 import unittest
-import os
+import math
 
 class TestTimeToSolution(unittest.TestCase):
 
@@ -12,7 +12,7 @@ def test_one_sidb_100_lattice(self):
         quicksim_parameter.simulation_parameters = sidb_simulation_parameters(3, -0.3)
 
         tts_params = time_to_solution_params()
-        tts_params.engine = exhaustive_sidb_simulation_engine.QUICKEXACT
+        tts_params.engine = exact_sidb_simulation_engine.QUICKEXACT
         stats = time_to_solution_stats()
 
         cds = charge_distribution_surface_100(layout)
@@ -31,7 +31,7 @@ def test_one_sidb_111_lattice(self):
         quicksim_parameter.simulation_parameters = sidb_simulation_parameters(3, -0.3)
 
         tts_params = time_to_solution_params()
-        tts_params.engine = exhaustive_sidb_simulation_engine.QUICKEXACT
+        tts_params.engine = exact_sidb_simulation_engine.QUICKEXACT
         stats = time_to_solution_stats()
 
         cds = charge_distribution_surface_111(layout)
@@ -42,5 +42,55 @@ def test_one_sidb_111_lattice(self):
         self.assertGreater(stats.time_to_solution, 0.0)
         self.assertGreater(stats.mean_single_runtime, 0.0)
 
+    def test_time_to_solution_with_simulation_results(self):
+        layout = sidb_100_lattice((0, 0))
+
+        # Assign SiDBs to the layout
+        layout.assign_cell_type((0, 0), sidb_technology.cell_type.NORMAL)
+        layout.assign_cell_type((1, 6, 0), sidb_technology.cell_type.NORMAL)
+        layout.assign_cell_type((3, 6, 0), sidb_technology.cell_type.NORMAL)
+        layout.assign_cell_type((5, 6, 0), sidb_technology.cell_type.NORMAL)
+        layout.assign_cell_type((10, 6, 0), sidb_technology.cell_type.NORMAL)
+        layout.assign_cell_type((15, 6, 0), sidb_technology.cell_type.NORMAL)
+        layout.assign_cell_type((18, 6, 0), sidb_technology.cell_type.NORMAL)
+
+        # Define simulation parameters
+        params = sidb_simulation_parameters(2, -0.32)
+        quicksim_params_inst = quicksim_params()
+        quicksim_params_inst.simulation_parameters = params
+
+        number_of_repetitions = 100
+        simulation_results_quicksim = []
+
+        # Run the QuickSim simulations
+        for _ in range(number_of_repetitions):
+            simulation_results_quicksim.append(quicksim(layout, quicksim_params_inst))
+
+        quickexact_params_inst = quickexact_params()
+        quickexact_params_inst.simulation_parameters = params
+        quickexact_params_inst.base_number_detection = automatic_base_number_detection.OFF
+        self.assertEqual(quickexact_params_inst.simulation_parameters.mu_minus, -0.32)
+        self.assertEqual(quickexact_params_inst.base_number_detection, automatic_base_number_detection.OFF)
+
+        # Run the QuickExact simulation
+        simulation_results_quickexact = quickexact(layout, quickexact_params_inst)
+
+        # Calculate time-to-solution using the simulation results
+        st = time_to_solution_stats()
+        time_to_solution_for_given_simulation_results(
+            simulation_results_quickexact, simulation_results_quicksim, 0.997, st)
+
+        self.assertGreater(st.time_to_solution, 0.0)
+        self.assertGreater(st.mean_single_runtime, 0.0)
+
+        if st.acc == 100:
+            tts_calculated = st.mean_single_runtime
+            self.assertAlmostEqual(st.time_to_solution - tts_calculated, 0.0, delta=1e-6)
+        elif st.acc != 0.0:
+            # To avoid division by zero, ensure st.acc is not 1.0
+            tts_calculated = (st.mean_single_runtime * math.log(1.0 - 0.997) /
+                              math.log(1.0 - st.acc / 100))
+            self.assertAlmostEqual(st.time_to_solution - tts_calculated, 0.0, delta=1e-6)
+
 if __name__ == '__main__':
     unittest.main()

docs/algorithms/sidb_simulation.rst

@@ -89,12 +89,12 @@ Engine Selectors
         **Header:** ``fiction/algorithms/simulation/sidb/sidb_simulation_engine.hpp``
 
         .. doxygenenum:: fiction::sidb_simulation_engine
-        .. doxygenenum:: fiction::exhaustive_sidb_simulation_engine
+        .. doxygenenum:: fiction::exact_sidb_simulation_engine
 
     .. tab:: Python
         .. autoclass:: mnt.pyfiction.sidb_simulation_engine
             :members:
-        .. autoclass:: mnt.pyfiction.exhaustive_sidb_simulation_engine
+        .. autoclass:: mnt.pyfiction.exact_sidb_simulation_engine
             :members:
 
 
@@ -187,13 +187,15 @@ Time-to-Solution (TTS) Statistics
         .. doxygenstruct:: fiction::time_to_solution_stats
            :members:
         .. doxygenfunction:: fiction::time_to_solution
+        .. doxygenfunction:: fiction::time_to_solution_for_given_simulation_results
 
     .. tab:: Python
         .. autoclass:: mnt.pyfiction.time_to_solution_params
             :members:
         .. autoclass:: mnt.pyfiction.time_to_solution_stats
             :members:
         .. autofunction:: mnt.pyfiction.time_to_solution
+        .. autofunction:: mnt.pyfiction.time_to_solution_for_given_simulation_results
 
 
 Random SiDB Layout Generator

docs/technology/simulation.rst

@@ -39,6 +39,7 @@ distributions of the SiDBs. Charge distribution surfaces are returned by the SiD
         .. doxygenenum:: fiction::energy_calculation
         .. doxygenenum:: fiction::charge_distribution_history
         .. doxygenenum:: fiction::charge_index_recomputation
+        .. doxygenenum:: fiction::charge_distribution_mode
         .. doxygenenum:: fiction::charge_index_mode
         .. doxygenclass:: fiction::charge_distribution_surface
            :members: