✨ Add function to detect if non-operational status is due to wire kink

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

@@ -13,7 +13,7 @@
 #include <pybind11/pybind11.h>
 #include <pybind11/stl.h>
 
-#include <string>
+#include <optional>
 
 namespace pyfiction
 {
@@ -32,6 +32,14 @@ void is_operational(pybind11::module& m)
 
     m.def("operational_input_patterns", &fiction::operational_input_patterns<Lyt, py_tt>, "lyt"_a, "spec"_a,
           "params"_a = fiction::is_operational_params{}, DOC(fiction_operational_input_patterns));
+
+    m.def("is_kink_induced_non_operational", &fiction::is_kink_induced_non_operational<Lyt, py_tt>, "lyt"_a, "spec"_a,
+          "params"_a = fiction::is_operational_params{}, "input_bdl_wire"_a = std::nullopt,
+          "output_bdl_wire"_a = std::nullopt, DOC(fiction_is_kink_induced_non_operational));
+
+    m.def("kink_induced_non_operational_input_patterns",
+          &fiction::kink_induced_non_operational_input_patterns<Lyt, py_tt>, "lyt"_a, "spec"_a,
+          "params"_a = fiction::is_operational_params{}, DOC(fiction_kink_induced_non_operational_input_patterns));
 }
 
 }  // namespace detail

bindings/pyfiction/include/pyfiction/pybind11_mkdoc_docstrings.hpp

@@ -6755,7 +6755,7 @@ Template parameter ``Lyt``:
     SiDB cell-level layout type.
 
 Template parameter ``TT``:
-    The type of the truth table specifying the gate behavior.)doc";
+    Type of the truth table.)doc";
 
 static const char *__doc_fiction_detail_is_operational_impl_bii = R"doc(Iterator that iterates over all possible input states.)doc";
 
@@ -6801,12 +6801,16 @@ Parameter ``current_input_index``:
     `true` if any output wire contains a kink (i.e., an unexpected
     charge state), `false` otherwise.)doc";
 
-static const char *__doc_fiction_detail_is_operational_impl_determine_operational_input_patterns =
-R"doc(Determines the input combinations yielding the correct output.
+static const char *__doc_fiction_detail_is_operational_impl_determine_non_operational_input_patterns_and_non_operationality_reason =
+R"doc(Determines the input combinations for which the layout is non-
+operational and the reason why the layout is non-operational.
 
 Returns:
-    All inputs (e.g. 2-input Boolean function: 00 ^= 0; 10 ^= 2) for
-    which the correct output is computed.)doc";
+    Vector of pairs where the first element of the pair is the input
+    pattern (e.g. 2-input Boolean function: 00 ^= 0; 10 ^= 2) for
+    which the layout is non-operational. The second entry indicates
+    the reason why the layout is non-operational
+    (`non_operationality_reason`) for the given input pattern.)doc";
 
 static const char *__doc_fiction_detail_is_operational_impl_encodes_bit_one =
 R"doc(This function returns `true` if `1` is encoded in the charge state of
@@ -6908,14 +6912,15 @@ This function executes the operational status checking algorithm for
 the gate layout and parameters provided during initialization.
 
 Returns:
-    The operational status of the gate layout (either `OPERATIONAL` or
-    `NON_OPERATIONAL`).)doc";
+    Pair with the first element indicating the operational status
+    (either `OPERATIONAL` or `NON_OPERATIONAL`) and the second element
+    indicating the reason if it is non-operational.)doc";
 
 static const char *__doc_fiction_detail_is_operational_impl_simulator_invocations = R"doc(Number of simulator invocations.)doc";
 
 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 =
+static const char *__doc_fiction_detail_is_operational_impl_verify_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.
 
@@ -6934,8 +6939,9 @@ Parameter ``input_pattern``:
     Input pattern represented by the position of perturbers.
 
 Returns:
-    Operational status indicating if the layout is `operational` or
-    `non-operational`.)doc";
+    Pair with the first element indicating the operational status
+    (either `OPERATIONAL` or `NON_OPERATIONAL`) and the second element
+    indicating the reason if it is non-operational.)doc";
 
 static const char *__doc_fiction_detail_jump_point_search_impl = R"doc()doc";
 
@@ -7188,6 +7194,14 @@ static const char *__doc_fiction_detail_new_gate_location_NONE = R"doc(Do not ch
 
 static const char *__doc_fiction_detail_new_gate_location_SRC = R"doc(Check if the source tile is empty.)doc";
 
+static const char *__doc_fiction_detail_non_operationality_reason = R"doc(Reason why a layout is non-operational.)doc";
+
+static const char *__doc_fiction_detail_non_operationality_reason_KINKS = R"doc(Kinks induced the layout to become non-operational.)doc";
+
+static const char *__doc_fiction_detail_non_operationality_reason_LOGIC_MISMATCH = R"doc(The layout is non-operational because of logic mismatch.)doc";
+
+static const char *__doc_fiction_detail_non_operationality_reason_NONE = R"doc(No reason for non-operationality could be determined.)doc";
+
 static const char *__doc_fiction_detail_on_the_fly_circuit_design_impl = R"doc()doc";
 
 static const char *__doc_fiction_detail_on_the_fly_circuit_design_impl_design_circuit_on_defective_surface = R"doc()doc";
@@ -13613,6 +13627,42 @@ Parameter ``exact_results``:
 
 static const char *__doc_fiction_is_hexagonal_layout = R"doc()doc";
 
+static const char *__doc_fiction_is_kink_induced_non_operational =
+R"doc(This function determines if the layout is only considered as non-
+operational because of kinks. This means that the layout would be
+considered as operational, if kinks were accepted.
+
+@note "Kink induced non-operational" refers to the non-operational
+status being exclusively caused by kinks with an otherwise correct
+logic match.
+
+Template parameter ``Lyt``:
+    SiDB cell-level layout type.
+
+Template parameter ``TT``:
+    Type of the truth table.
+
+Parameter ``lyt``:
+    The SiDB cell-level layout to be checked.
+
+Parameter ``spec``:
+    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.
+
+Returns:
+    Bool that indicates whether kinks induce the layout to become non-
+    operational. `true` if the layout is non-operational due to kinks,
+    `false` otherwise.)doc";
+
 static const char *__doc_fiction_is_linear_scheme =
 R"doc(Checks whether a given clocking scheme is registered as a cycle-free
 one. These currently are
@@ -13675,7 +13725,7 @@ Template parameter ``Lyt``:
     SiDB cell-level layout type.
 
 Template parameter ``TT``:
-    The type of the truth table specifying the layout behavior.
+    Type of the truth table.
 
 Parameter ``lyt``:
     The SiDB cell-level layout to be checked.
@@ -13693,9 +13743,6 @@ Parameter ``input_bdl_wire``:
 Parameter ``output_bdl_wire``:
     Optional BDL output wires of lyt.
 
-Parameter ``input_bdl_wire_direction``:
-    Optional BDL input wire directions of lyt.
-
 Returns:
     A pair containing the operational status of the gate layout
     (either `OPERATIONAL` or `NON_OPERATIONAL`) and the number of
@@ -13706,8 +13753,8 @@ static const char *__doc_fiction_is_operational_params = R"doc(Parameters for th
 static const char *__doc_fiction_is_operational_params_input_bdl_iterator_params = R"doc(Parameters for the BDL input iterator.)doc";
 
 static const char *__doc_fiction_is_operational_params_op_condition =
-R"doc(Condition which is used to decide if a layout is `operational` or
-`non-operational`.)doc";
+R"doc(Condition which is used to decide if a layout is operational or non-
+operational.)doc";
 
 static const char *__doc_fiction_is_operational_params_sim_engine =
 R"doc(The simulation engine to be used for the operational domain
@@ -13846,6 +13893,34 @@ Parameter ``dist_fn``:
     The shortest loop-less path in `layout` from `objective.source` to
     `objective.target`.)doc";
 
+static const char *__doc_fiction_kink_induced_non_operational_input_patterns =
+R"doc(This function determines all input combinations for which kinks induce
+the SiDB layout to become non-operational. This means that the layout
+is operational if kinks would be accepted.
+
+@note "Kink induced non-operational" refers to the non-operational
+status being exclusively caused by kinks with an otherwise correct
+logic match.
+
+Template parameter ``Lyt``:
+    SiDB cell-level layout type.
+
+Template parameter ``TT``:
+    Type of the truth table.
+
+Parameter ``lyt``:
+    The SiDB layout.
+
+Parameter ``spec``:
+    Vector of truth table specifications.
+
+Parameter ``params``:
+    Parameters for the `is_operational` algorithm.
+
+Returns:
+    The input combinations where kinks induce the SiDB layout to
+    become non-operational.)doc";
+
 static const char *__doc_fiction_layout_coordinate_path =
 R"doc(A path in a layout defined as an ordered sequence of coordinates.
 
@@ -14462,16 +14537,16 @@ Parameter ``n``:
     Irregular clocking scheme.)doc";
 
 static const char *__doc_fiction_operational_condition =
-R"doc(Condition which is used to decide if a layout is `operational` or
-`non-operational`.)doc";
+R"doc(Condition which is used to decide if a layout is operational or non-
+operational.)doc";
 
 static const char *__doc_fiction_operational_condition_REJECT_KINKS =
 R"doc(The I/O pins are not allowed to show kinks. If kinks exist, the layout
-is considered as `non-operational`.)doc";
+is considered as non-operational.)doc";
 
 static const char *__doc_fiction_operational_condition_TOLERATE_KINKS =
 R"doc(Even if the I/O pins show kinks, the layout is still considered as
-`operational`.)doc";
+operational.)doc";
 
 static const char *__doc_fiction_operational_domain =
 R"doc(An operational domain is a set of simulation parameter values for
@@ -14777,12 +14852,11 @@ static const char *__doc_fiction_operational_domain_value_range_min = R"doc(The
 static const char *__doc_fiction_operational_domain_value_range_step = R"doc(The step size of the dimension sweep.)doc";
 
 static const char *__doc_fiction_operational_input_patterns =
-R"doc(This function determines the input combinations for which the SiDB-
-based logic, represented by the provided layout (`lyt`) and truth
-table specifications (`spec`), produces the correct output.
+R"doc(This function determines the input combinations for which the layout
+is operational.
 
 Template parameter ``Lyt``:
-    Type of the cell-level layout.
+    SiDB cell-level layout type.
 
 Template parameter ``TT``:
     Type of the truth table.

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

@@ -5,7 +5,6 @@
 dir_path = os.path.dirname(os.path.realpath(__file__))
 
 class TestIsOperational(unittest.TestCase):
-
     def test_is_operational(self):
         lyt = sidb_100_lattice()
 
@@ -56,6 +55,29 @@ def test_and_gate_kinks(self):
 
         self.assertEqual(op_status, operational_status.NON_OPERATIONAL)
 
+
+    def test_and_gate_non_operational_due_to_kinks(self):
+
+        lyt = read_sqd_layout_100(dir_path + "/../../../resources/AND_mu_032_kinks.sqd")
+
+        params = is_operational_params()
+        params.simulation_parameters = sidb_simulation_parameters(2, -0.32)
+
+        result = is_kink_induced_non_operational(lyt, [create_and_tt()], params)
+
+        self.assertTrue(result)
+
+    def test_and_gate_non_operational_input_patterns_due_to_kinks(self):
+
+        lyt = read_sqd_layout_100(dir_path + "/../../../resources/AND_mu_032_kinks.sqd")
+
+        params = is_operational_params()
+        params.simulation_parameters = sidb_simulation_parameters(2, -0.32)
+
+        non_operational_pattern_kinks = kink_induced_non_operational_input_patterns(lyt, [create_and_tt()], params)
+
+        self.assertEqual(non_operational_pattern_kinks, {1, 2})
+
     def test_and_gate_111_lattice_11_input_pattern(self):
         lyt = read_sqd_layout_111(dir_path + "/../../../resources/AND_mu_032_111_surface.sqd")
 

docs/algorithms/sidb_simulation.rst

@@ -235,6 +235,8 @@ Operational Domain Computation
            :members:
         .. doxygenfunction:: fiction::is_operational
         .. doxygenfunction:: fiction::operational_input_patterns
+        .. doxygenfunction:: fiction::is_kink_induced_non_operational
+        .. doxygenfunction:: fiction::kink_induced_non_operational_input_patterns
 
         **Header:** ``fiction/algorithms/simulation/sidb/operational_domain.hpp``
 
@@ -274,6 +276,8 @@ Operational Domain Computation
             :members:
         .. autofunction:: mnt.pyfiction.is_operational
         .. autofunction:: mnt.pyfiction.operational_input_patterns
+        .. autofunction:: mnt.pyfiction.is_kink_induced_non_operational
+        .. autofunction:: mnt.pyfiction.kink_induced_non_operational_input_patterns
 
         .. autoclass:: mnt.pyfiction.sweep_parameter
             :members:

docs/changelog.rst

@@ -12,6 +12,7 @@ Added
 #####
 - Algorithms:
     - Simulation:
+        - Added option to determine if kinks induce layout to become non-operational
         - Kink control option for critical temperature simulation of SiDB layouts
 - Python bindings:
     - Support for Python 3.13 (including GIL-free multi-threading)