✨ 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

@@ -1844,6 +1844,14 @@ 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.)doc";
+
+static const char *__doc_fiction_charge_distribution_mode_KEEP_CHARGE_DISTRIBUTION =
+R"doc(The charge distribution is kept is not update based on the charge
+index.)doc";
+
+static const char *__doc_fiction_charge_distribution_mode_UPDATE_CHARGE_DISTRIBUTION = R"doc(The charge distribution is updated.)doc";
+
 static const char *__doc_fiction_charge_distribution_surface = R"doc()doc";
 
 static const char *__doc_fiction_charge_distribution_surface_2 = R"doc()doc";
@@ -8666,6 +8674,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
@@ -8729,17 +8748,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.
@@ -12127,8 +12135,7 @@ 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 ground state is found by the heuristic.
 
 Template parameter ``Lyt``:
     Cell-level layout type.
@@ -12137,7 +12144,7 @@ Parameter ``heuristic_results``:
     All found physically valid charge distribution surfaces obtained
     by a heuristic algorithm.
 
-Parameter ``exhaustive_results``:
+Parameter ``exact_results``:
     All valid charge distribution surfaces determined by ExGS.
 
 Returns:
@@ -15992,6 +15999,28 @@ 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``:
+    Cell-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
+
+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_params = R"doc()doc";
 
 static const char *__doc_fiction_time_to_solution_params_confidence_level = R"doc(Confidence level.)doc";
@@ -16014,7 +16043,7 @@ 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_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";
@@ -16025,9 +16054,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_DBs_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,62 @@ def test_one_DBs_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)
+
+        # Assertions
+        self.assertEqual(st.acc, 100.0)
+        self.assertGreater(st.time_to_solution, 0.0)
+        self.assertGreater(st.mean_single_runtime, 0.0)
+
+        print(st.acc)
+
+        if st.acc == 100:
+                tts_calculated = st.mean_single_runtime
+        else:
+            # 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))
+
+        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: