✨ Restructured Critical Temperature simulation with kink control option (#573)

* ✨ support kink setting in critical temperature simulation.

* 📝 Update pyfiction docstrings

Signed-off-by: GitHub Actions <[email protected]>

* 🎨 Incorporated pre-commit fixes

* 🎨 small fix.

* 🎨 small fix.

* 🎨 small fix.

* 🎨 Incorporated pre-commit fixes

* 📝 Update pyfiction docstrings

Signed-off-by: GitHub Actions <[email protected]>

* 🎨 integrate Marcel's feedback.

* 📝 Update pyfiction docstrings

Signed-off-by: GitHub Actions <[email protected]>

* 📝 update docu.

* 🎨 Incorporated pre-commit fixes

* 🎨 implement Marcel's feedback.

* 🎨 Incorporated pre-commit fixes

* 📝 Update pyfiction docstrings

Signed-off-by: GitHub Actions <[email protected]>

* 🎨 small fix.

---------

Signed-off-by: GitHub Actions <[email protected]>
Co-authored-by: GitHub Actions <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

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

@@ -26,9 +26,15 @@ void calculate_energy_and_state_type(pybind11::module& m)
 {
     using namespace pybind11::literals;
 
-    m.def("calculate_energy_and_state_type", &fiction::calculate_energy_and_state_type<Lyt, py_tt>,
-          "energy_distribution"_a, "valid_charge_distributions"_a, "output_bdl_pairs"_a, "spec"_a, "input_index"_a,
-          DOC(fiction_calculate_energy_and_state_type));
+    m.def("calculate_energy_and_state_type_with_kinks_accepted",
+          &fiction::calculate_energy_and_state_type_with_kinks_accepted<Lyt, py_tt>, "energy_distribution"_a,
+          "valid_charge_distributions"_a, "output_bdl_pairs"_a, "spec"_a, "input_index"_a,
+          DOC(fiction_calculate_energy_and_state_type_with_kinks_accepted));
+
+    m.def("calculate_energy_and_state_type_with_kinks_rejected",
+          &fiction::calculate_energy_and_state_type_with_kinks_rejected<Lyt, py_tt>, "energy_distribution"_a,
+          "valid_charge_distributions"_a, "spec"_a, "input_index"_a, "input_bdl_wires"_a, "output_bdl_wires"_a,
+          DOC(fiction_calculate_energy_and_state_type_with_kinks_rejected));
 }
 
 }  // namespace detail

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

@@ -41,16 +41,6 @@ inline void critical_temperature(pybind11::module& m)
 {
     namespace py = pybind11;
 
-    /**
-     * Simulation engine.
-     */
-    py::enum_<fiction::critical_temperature_params::simulation_engine>(
-        m, "simulation_engine", DOC(fiction_critical_temperature_params_simulation_engine))
-        .value("EXACT", fiction::critical_temperature_params::simulation_engine::EXACT,
-               DOC(fiction_critical_temperature_params_simulation_engine_EXACT))
-        .value("APPROXIMATE", fiction::critical_temperature_params::simulation_engine::APPROXIMATE,
-               DOC(fiction_critical_temperature_params_simulation_engine_APPROXIMATE));
-
     /**
      * Critical temperature statistics.
      */
@@ -81,16 +71,12 @@ inline void critical_temperature(pybind11::module& m)
     py::class_<fiction::critical_temperature_params>(m, "critical_temperature_params",
                                                      DOC(fiction_critical_temperature_params))
         .def(py::init<>())
-        .def_readwrite("simulation_parameters", &fiction::critical_temperature_params::simulation_parameters,
+        .def_readwrite("operational_params", &fiction::critical_temperature_params::operational_params,
                        DOC(fiction_critical_temperature_params))
-        .def_readwrite("engine", &fiction::critical_temperature_params::engine,
-                       DOC(fiction_critical_temperature_params_engine))
         .def_readwrite("confidence_level", &fiction::critical_temperature_params::confidence_level,
                        DOC(fiction_critical_temperature_params_confidence_level))
         .def_readwrite("max_temperature", &fiction::critical_temperature_params::max_temperature,
-                       DOC(fiction_critical_temperature_params_max_temperature))
-        .def_readwrite("input_iterator_params", &fiction::critical_temperature_params::input_iterator_params,
-                       DOC(fiction_critical_temperature_params_input_iterator_params));
+                       DOC(fiction_critical_temperature_params_max_temperature));
 
     // NOTE be careful with the order of the following calls! Python will resolve the first matching overload!
 

bindings/pyfiction/include/pyfiction/pybind11_mkdoc_docstrings.hpp

@@ -1122,10 +1122,11 @@ static const char *__doc_fiction_bounding_box_2d_x_size = R"doc(The horizontal s
 
 static const char *__doc_fiction_bounding_box_2d_y_size = R"doc(The vertical size of the bounding box in layout coordinates.)doc";
 
-static const char *__doc_fiction_calculate_energy_and_state_type =
+static const char *__doc_fiction_calculate_energy_and_state_type_with_kinks_accepted =
 R"doc(This function takes in an SiDB energy distribution. For each charge
 distribution, the state type is determined (i.e. erroneous,
-transparent).
+transparent) while kinks are accepted, meaning a state with kinks is
+considered transparent.
 
 Template parameter ``Lyt``:
     SiDB cell-level layout type.
@@ -1153,6 +1154,44 @@ Parameter ``input_index``:
     Electrostatic potential energy of all charge distributions with
     state type.)doc";
 
+static const char *__doc_fiction_calculate_energy_and_state_type_with_kinks_rejected =
+R"doc(This function takes in an SiDB energy distribution. For each charge
+distribution, the state type is determined (i.e. erroneous,
+transparent) while kinks are rejected, meaning a state with kinks is
+considered erroneous.
+
+Template parameter ``Lyt``:
+    SiDB cell-level layout type.
+
+Template parameter ``TT``:
+    The type of the truth table specifying the gate behavior.
+
+Parameter ``energy_distribution``:
+    Energy distribution.
+
+Parameter ``valid_charge_distributions``:
+    Physically valid charge distributions.
+
+Parameter ``output_bdl_pairs``:
+    Output BDL pairs.
+
+Parameter ``spec``:
+    Expected Boolean function of the layout given as a multi-output
+    truth table.
+
+Parameter ``input_index``:
+    The index of the current input configuration.
+
+Parameter ``input_bdl_wires``:
+    Input BDL wires.
+
+Parameter ``output_bdl_wires``:
+    Output BDL wires.
+
+Returns:
+    Electrostatic potential energy of all charge distributions with
+    state type.)doc";
+
 static const char *__doc_fiction_can_positive_charges_occur =
 R"doc(This algorithm determines if positively charged SiDBs can occur in a
 given SiDB cell-level layout due to strong electrostatic interaction.
@@ -3428,10 +3467,6 @@ probability of less than the given percentage, is determined to be the
 critical temperature. For gate-based simulation, this is the
 probability of erroneous calculations of the gate.)doc";
 
-static const char *__doc_fiction_critical_temperature_params_engine = R"doc(Simulation mode to determine the *Critical Temperature*.)doc";
-
-static const char *__doc_fiction_critical_temperature_params_input_iterator_params = R"doc(Parameters for the BDL input iterator.)doc";
-
 static const char *__doc_fiction_critical_temperature_params_iteration_steps =
 R"doc(Number of iteration steps for the *QuickSim* algorithm (only
 applicable if engine == APPROXIMATE).)doc";
@@ -3440,21 +3475,9 @@ static const char *__doc_fiction_critical_temperature_params_max_temperature =
 R"doc(Maximum simulation temperature beyond which no simulation will be
 conducted (~ 126 °C by default) (unit: K).)doc";
 
-static const char *__doc_fiction_critical_temperature_params_simulation_engine =
-R"doc(An enumeration of simulation modes (exact vs. approximate) to use for
-the *Critical Temperature* Simulation.)doc";
-
-static const char *__doc_fiction_critical_temperature_params_simulation_engine_APPROXIMATE =
-R"doc(This simulation engine quickly calculates the *Critical Temperature*.
-However, there may be deviations from the exact *Critical
-Temperature*. This mode is recommended for larger layouts (> 40
-SiDBs).)doc";
-
-static const char *__doc_fiction_critical_temperature_params_simulation_engine_EXACT =
-R"doc(This simulation engine computes *Critical Temperature* values with 100
-% accuracy.)doc";
-
-static const char *__doc_fiction_critical_temperature_params_simulation_parameters = R"doc(All parameters for physical SiDB simulations.)doc";
+static const char *__doc_fiction_critical_temperature_params_operational_params =
+R"doc(The parameters used to determine if a layout is `operational` or `non-
+operational`.)doc";
 
 static const char *__doc_fiction_critical_temperature_stats = R"doc(This struct stores the result of the temperature simulation.)doc";
 
@@ -4531,7 +4554,7 @@ given Boolean function.)doc";
 
 static const char *__doc_fiction_detail_critical_temperature_impl_params = R"doc(Parameters for the critical_temperature algorithm.)doc";
 
-static const char *__doc_fiction_detail_critical_temperature_impl_physical_simulation_of_layout =
+static const char *__doc_fiction_detail_critical_temperature_impl_physical_simulation_of_bdl_iterator =
 R"doc(This function conducts physical simulation of the given layout (gate
 layout with certain input combination). The simulation results are
 stored in the `sim_result_100` variable.
@@ -6844,21 +6867,18 @@ R"doc(Constructor to initialize the algorithm with a layout and parameters.
 Parameter ``lyt``:
     The SiDB cell-level layout to be checked.
 
-Parameter ``spec``:
+Parameter ``tt``:
     Expected Boolean function of the layout given as a multi-output
     truth table.
 
 Parameter ``params``:
     Parameters for the `is_operational` algorithm.
 
-Parameter ``input_bdl_wire``:
-    Optional BDL input wires of lyt.
-
-Parameter ``output_bdl_wire``:
-    Optional BDL output wires of lyt.
+Parameter ``input_wires``:
+    BDL input wires of lyt.
 
-Parameter ``input_bdl_wire_direction``:
-    Optional BDL input wire directions of lyt.)doc";
+Parameter ``output_wires``:
+    BDL output wires of lyt.)doc";
 
 static const char *__doc_fiction_detail_is_operational_impl_layout = R"doc(SiDB cell-level layout.)doc";
 
@@ -6895,6 +6915,28 @@ static const char *__doc_fiction_detail_is_operational_impl_simulator_invocation
 
 static const char *__doc_fiction_detail_is_operational_impl_truth_table = R"doc(The specification of the layout.)doc";
 
+static const char *__doc_fiction_detail_is_operational_impl_verifiy_logic_match_of_cds =
+R"doc(Checks if the given charge distribution correctly encodes the expected
+logic for the given input pattern, based on a provided truth table.
+
+Example: In the ground state charge distribution of an AND gate, kinks
+are rejected for the gate to be considered operational. Given an input
+pattern of `01`, this function will: - Verify that the left input wire
+encodes `0`. - Verify that the right input wire encodes `1`. - Verify
+that the output wire encodes `0`. Determines if the given charge
+distribution fulfills the correct logic based on the provided charge
+index and truth table.
+
+Parameter ``given_cds``:
+    The charge distribution surface to be checked for operation.
+
+Parameter ``input_pattern``:
+    Input pattern represented by the position of perturbers.
+
+Returns:
+    Operational status indicating if the layout is `operational` or
+    `non-operational`.)doc";
+
 static const char *__doc_fiction_detail_jump_point_search_impl = R"doc()doc";
 
 static const char *__doc_fiction_detail_jump_point_search_impl_closed_list = R"doc(Closed list that acts as a set of already visited coordinates.)doc";
@@ -18211,6 +18253,50 @@ Template parameter ``Lyt``:
 Returns:
     USE clocking scheme.)doc";
 
+static const char *__doc_fiction_verify_logic_match =
+R"doc(Checks if a given charge distribution correctly encodes the expected
+logic for a specified input pattern, based on a provided truth table.
+
+@note Kinks are rejected.
+
+Example: In the ground state charge distribution of an AND gate, kinks
+are rejected for the gate to be considered operational. Given an input
+pattern of `01`, this function will: - Verify that the left input wire
+encodes `0`. - Verify that the right input wire encodes `1`. - Verify
+that the output wire encodes `0`.
+
+Template parameter ``Lyt``:
+    SiDB cell-level layout type.
+
+Template parameter ``TT``:
+    Truth table type.
+
+Parameter ``cds``:
+    Charge distribution surface, containing charge state information
+    for each SiDB.
+
+Parameter ``params``:
+    The parameters used to determine if a layout is `operational` or
+    `non-operational`.
+
+Parameter ``spec``:
+    Expected Boolean function of the layout given as a multi-output
+    truth table.
+
+Parameter ``input_pattern``:
+    The specific input pattern of the given charge distribution
+    surface.
+
+Parameter ``input_wires``:
+    Input BDL wires.
+
+Parameter ``output_wires``:
+    Output BDL wires.
+
+Returns:
+    The operational status indicating if the charge distribution
+    matches the logic for the given input pattern.)doc";
+
 static const char *__doc_fiction_vertex_coloring =
 R"doc(A vertex coloring is simply a hash map from vertex IDs to Color types
 where Color should be constructible/convertible from int.

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

@@ -15,7 +15,8 @@ def test_perturber_and_DB_pair_100(self):
         layout.assign_cell_type((6, 1), sidb_technology.cell_type.NORMAL)
 
         params = critical_temperature_params()
-        params.engine = simulation_engine.EXACT
+
+        params.operational_params.sim_engine = sidb_simulation_engine.QUICKEXACT
 
         stats = critical_temperature_stats()
 
@@ -33,7 +34,8 @@ def test_perturber_and_DB_pair_111(self):
         layout.assign_cell_type((6, 1), sidb_technology.cell_type.NORMAL)
 
         params = critical_temperature_params()
-        params.engine = simulation_engine.EXACT
+
+        params.operational_params.sim_engine = sidb_simulation_engine.QUICKEXACT
 
         stats = critical_temperature_stats()
 
@@ -47,8 +49,10 @@ def test_perturber_and_DB_pair_111(self):
     def test_gate_based_simulation(self):
         layout = read_sqd_layout_100(dir_path + "/../../../resources/hex_21_inputsdbp_xor_v1.sqd", "xor_gate")
         params = critical_temperature_params()
-        params.simulation_parameters.base = 2
-        params.engine = simulation_engine.EXACT
+
+        params.operational_params.simulation_parameters.base = 2
+
+        params.operational_params.sim_engine = sidb_simulation_engine.QUICKEXACT
 
         stats = critical_temperature_stats()
 
@@ -64,7 +68,8 @@ def test_bestagon_inv(self):
                                      "inverter_input_0")
 
         params = critical_temperature_params()
-        params.engine = simulation_engine.APPROXIMATE
+
+        params.operational_params.sim_engine = sidb_simulation_engine.QUICKSIM
 
         stats = critical_temperature_stats()
 
@@ -81,10 +86,10 @@ def test_bestagon_inv_with_different_mu(self):
                                      "inverter_input_0")
 
         params = critical_temperature_params()
-        params.simulation_parameters.base = 2
-        params.simulation_parameters.mu_minus = -0.2
+        params.operational_params.simulation_parameters.base = 2
+        params.operational_params.simulation_parameters.mu_minus = -0.2
 
-        params.engine = simulation_engine.EXACT
+        params.operational_params.sim_engine = sidb_simulation_engine.QUICKEXACT
 
         stats = critical_temperature_stats()
 

cli/cmd/simulation/temp.hpp

@@ -129,7 +129,7 @@ class temp_command : public command
                 }
                 else
                 {
-                    params.simulation_parameters = physical_params;
+                    params.operational_params.simulation_parameters = physical_params;
 
                     if (is_set("gate_based"))
                     {

docs/algorithms/sidb_simulation.rst

@@ -149,7 +149,8 @@ Temperature Behavior
         **Header:** ``fiction/algorithms/simulation/sidb/calculate_energy_and_state_type.hpp``
 
         .. doxygentypedef:: fiction::sidb_energy_and_state_type
-        .. doxygenfunction:: fiction::calculate_energy_and_state_type
+        .. doxygenfunction:: fiction::calculate_energy_and_state_type_with_kinks_accepted
+        .. doxygenfunction:: fiction::calculate_energy_and_state_type_with_kinks_rejected
 
     .. tab:: Python
         .. autoclass:: mnt.pyfiction.simulation_engine
@@ -162,7 +163,8 @@ Temperature Behavior
         .. autofunction:: mnt.pyfiction.occupation_probability_gate_based
         .. autofunction:: mnt.pyfiction.occupation_probability_non_gate_based
 
-        .. autofunction:: mnt.pyfiction.calculate_energy_and_state_type
+        .. autofunction:: mnt.pyfiction.calculate_energy_and_state_type_with_kinks_accepted
+        .. autofunction:: mnt.pyfiction.calculate_energy_and_state_type_with_kinks_rejected
 
 
 Maximum Defect Influence Distance
@@ -259,6 +261,10 @@ Operational Domain Computation
            :members:
         .. doxygenfunction:: fiction::compute_operational_ratio
 
+        **Header:** ``fiction/algorithms/simulation/sidb/verify_logic_match.hpp``
+
+        .. doxygenfunction:: fiction::verify_logic_match
+
     .. tab:: Python
         .. autoclass:: mnt.pyfiction.operational_status
             :members:

experiments/sidb_simulation/temperature/critical_temperature_simulation_siqad.cpp

@@ -45,7 +45,7 @@ int main()  // NOLINT
     // Quantum Dot Circuits\" by Samuel Sze Hang Ng, Jacob Retallick, Hsi Nien Chiu, Robert Lupoiu, Lucian Livadaru,
     // Taleana Huff, Mohammad Rashidi, Wyatt Vine, Thomas Dienel, Robert A. Wolkow, and Konrad Walus in IEEE
     // TRANSACTIONS ON NANOTECHNOLOGY, Volume 19, 2020. (https://ieeexplore.ieee.org/abstract/document/8963859)
-    ct_params.input_iterator_params.input_bdl_config =
+    ct_params.operational_params.input_bdl_iterator_params.input_bdl_config =
         bdl_input_iterator_params::input_bdl_configuration::PERTURBER_ABSENCE_ENCODED;
 
     for (const auto& [gate, truth_table] : gates)