✨ Sorting designed SiDB gates

bindings/pyfiction/include/pyfiction/algorithms/physical_design/design_sidb_gates.hpp

@@ -48,7 +48,7 @@ inline void design_sidb_gates(pybind11::module& m)
     /**
      * Design approach selector type.
      */
-    pybind11::enum_<typename fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::design_sidb_gates_mode>(
+    py::enum_<typename fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::design_sidb_gates_mode>(
         m, "design_sidb_gates_mode", DOC(fiction_design_sidb_gates_params_design_sidb_gates_mode))
         .value("QUICKCELL",
                fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::design_sidb_gates_mode::QUICKCELL,
@@ -60,6 +60,32 @@ inline void design_sidb_gates(pybind11::module& m)
         .value("RANDOM", fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::design_sidb_gates_mode::RANDOM,
                DOC(fiction_design_sidb_gates_params_design_sidb_gates_mode_RANDOM));
 
+    /**
+     * Termination condition selector type.
+     */
+    py::enum_<typename fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::termination_condition>(
+        m, "termination_condition", DOC(fiction_design_sidb_gates_params_termination_condition))
+        .value(
+            "AFTER_FIRST_SOLUTION",
+            fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::termination_condition::AFTER_FIRST_SOLUTION,
+            DOC(fiction_design_sidb_gates_params_termination_condition_AFTER_FIRST_SOLUTION))
+        .value("ALL_COMBINATIONS_ENUMERATED",
+               fiction::design_sidb_gates_params<
+                   fiction::offset::ucoord_t>::termination_condition::ALL_COMBINATIONS_ENUMERATED,
+               DOC(fiction_design_sidb_gates_params_termination_condition_ALL_COMBINATIONS_ENUMERATED));
+
+    /**
+     * Post-design processes selector type.
+     */
+    py::enum_<typename fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::post_design_mode>(
+        m, "post_design_mode", DOC(fiction_design_sidb_gates_params_post_design_mode))
+        .value("DO_NOTHING", fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::post_design_mode::DO_NOTHING,
+               DOC(fiction_design_sidb_gates_params_post_design_mode_DO_NOTHING))
+        .value("PREFER_ENERGETICALLY_ISOLATED_GROUND_STATES",
+               fiction::design_sidb_gates_params<
+                   fiction::offset::ucoord_t>::post_design_mode::PREFER_ENERGETICALLY_ISOLATED_GROUND_STATES,
+               DOC(fiction_design_sidb_gates_params_post_design_mode_PREFER_ENERGETICALLY_ISOLATED_GROUND_STATES));
+
     /**
      * Parameters.
      */
@@ -75,7 +101,13 @@ inline void design_sidb_gates(pybind11::module& m)
                        DOC(fiction_design_sidb_gates_params_canvas))
         .def_readwrite("number_of_sidbs",
                        &fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::number_of_sidbs,
-                       DOC(fiction_design_sidb_gates_params_number_of_sidbs));
+                       DOC(fiction_design_sidb_gates_params_number_of_sidbs))
+        .def_readwrite("termination_cond",
+                       &fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::termination_cond,
+                       DOC(fiction_design_sidb_gates_params_termination_cond))
+        .def_readwrite("post_design_process",
+                       &fiction::design_sidb_gates_params<fiction::offset::ucoord_t>::post_design_process,
+                       DOC(fiction_design_sidb_gates_params_post_design_process));
 
     detail::design_sidb_gates<py_sidb_100_lattice>(m);
     detail::design_sidb_gates<py_sidb_111_lattice>(m);

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

@@ -22,7 +22,7 @@ namespace detail
 {
 
 template <typename Lyt>
-void is_operational(pybind11::module& m)
+void is_operational(pybind11::module& m, const std::string& lattice = "")
 {
     using namespace pybind11::literals;
 
@@ -32,6 +32,15 @@ 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));
+
+    pybind11::class_<fiction::operational_status_assessment_stats<Lyt>>(
+        m, fmt::format("sidb_simulation_result{}", lattice).c_str(), DOC(fiction_operational_status_assessment_stats))
+        .def(pybind11::init<>())
+        .def_readwrite("simulation_results", &fiction::operational_status_assessment_stats<Lyt>::simulation_results,
+                       DOC(fiction_operational_status_assessment_stats_simulation_results))
+        .def_readwrite("number_of_simulator_invocations",
+                       &fiction::operational_status_assessment_stats<Lyt>::number_of_simulator_invocations,
+                       DOC(fiction_operational_status_assessment_stats_number_of_simulator_invocations));
 }
 
 }  // namespace detail
@@ -51,6 +60,15 @@ inline void is_operational(pybind11::module& m)
         .value("REJECT_KINKS", fiction::operational_condition::REJECT_KINKS,
                DOC(fiction_operational_condition_REJECT_KINKS));
 
+    py::enum_<typename fiction::is_operational_params::simulation_results_mode>(
+        m, "simulation_results_mode", DOC(fiction_is_operational_params_simulation_results_mode))
+        .value("KEEP_SIMULATION_RESULTS",
+               fiction::is_operational_params::simulation_results_mode::KEEP_SIMULATION_RESULTS,
+               DOC(fiction_is_operational_params_simulation_results_mode_KEEP_SIMULATION_RESULTS))
+        .value("DISCARD_SIMULATION_RESULTS",
+               fiction::is_operational_params::simulation_results_mode::DISCARD_SIMULATION_RESULTS,
+               DOC(fiction_is_operational_params_simulation_results_mode_DISCARD_SIMULATION_RESULTS));
+
     py::class_<fiction::is_operational_params>(m, "is_operational_params", DOC(fiction_is_operational_params))
         .def(py::init<>())
         .def_readwrite("simulation_parameters", &fiction::is_operational_params::simulation_parameters,
@@ -63,8 +81,8 @@ inline void is_operational(pybind11::module& m)
                        DOC(fiction_is_operational_params_op_condition));
 
     // NOTE be careful with the order of the following calls! Python will resolve the first matching overload!
-    detail::is_operational<py_sidb_100_lattice>(m);
-    detail::is_operational<py_sidb_111_lattice>(m);
+    detail::is_operational<py_sidb_100_lattice>(m, "_100");
+    detail::is_operational<py_sidb_111_lattice>(m, "_111");
 }
 
 }  // namespace pyfiction

bindings/pyfiction/include/pyfiction/pybind11_mkdoc_docstrings.hpp

@@ -3816,6 +3816,20 @@ static const char *__doc_fiction_design_sidb_gates_params_number_of_sidbs = R"do
 
 static const char *__doc_fiction_design_sidb_gates_params_operational_params = R"doc(Parameters for the `is_operational` function.)doc";
 
+static const char *__doc_fiction_design_sidb_gates_params_post_design_mode = R"doc(Selector for the available post-design processes.)doc";
+
+static const char *__doc_fiction_design_sidb_gates_params_post_design_mode_DO_NOTHING = R"doc(No post-design operation is performed.)doc";
+
+static const char *__doc_fiction_design_sidb_gates_params_post_design_mode_PREFER_ENERGETICALLY_ISOLATED_GROUND_STATES =
+R"doc(The designed gates are sorted by how energetically isolated the ground
+state is from the first excited state.)doc";
+
+static const char *__doc_fiction_design_sidb_gates_params_post_design_process =
+R"doc(After the design process, the returned gates are not sorted.
+
+@note This parameter has no effect unless the gate design is
+exhaustive and all combinations are enumerated.)doc";
+
 static const char *__doc_fiction_design_sidb_gates_params_termination_cond =
 R"doc(The design process is terminated after a valid SiDB gate design is
 found.
@@ -4803,6 +4817,19 @@ Parameter ``layout``:
 Parameter ``input_index``:
     The index representing the current input pattern.)doc";
 
+static const char *__doc_fiction_detail_design_sidb_gates_impl_set_simulation_results_retention_accordingly =
+R"doc(This function makes sure that the underlying parameters for
+`is_operational` allow simulation results to be used when the given
+parameter set indicates the use for it.
+
+Parameter ``Parameters``:
+    and settings for the gate designer.
+
+Returns:
+    Parameters and settings for the gate designer for which the
+    simulation results retention of the underlying parameter for
+    operational status assessment is set accordingly.)doc";
+
 static const char *__doc_fiction_detail_design_sidb_gates_impl_skeleton_layout =
 R"doc(The skeleton layout serves as a starting layout to which SiDBs are
 added to create unique SiDB layouts and, if possible, working gates.
@@ -4819,6 +4846,19 @@ Parameter ``cell_indices``:
     A copy of the original layout (`skeleton_layout`) with SiDB cells
     added at specified indices.)doc";
 
+static const char *__doc_fiction_detail_design_sidb_gates_impl_sort_designed_gate_layouts_by_ground_state_isolation =
+R"doc(Performs a sorting operation on the designed gate layouts, putting
+those in front for which the energetic gap between the ground state
+and the first excited state is larger. For each designed gate layout,
+the minimum energetic gap is taken over each input.
+
+Parameter ``designed_gate_layouts``:
+    A vector of designed gate layouts to sort in place.
+
+Parameter ``sim_results_per_input_for_each_gate_design``:
+    The simulation results for each input of each designed gate
+    layout.)doc";
+
 static const char *__doc_fiction_detail_design_sidb_gates_impl_stats = R"doc(The statistics of the gate design.)doc";
 
 static const char *__doc_fiction_detail_design_sidb_gates_impl_truth_table = R"doc(Truth table of the given gate.)doc";
@@ -6823,11 +6863,12 @@ Parameter ``bdl``:
 Returns:
     `true` if `0` is encoded, `false` otherwise.)doc";
 
-static const char *__doc_fiction_detail_is_operational_impl_get_number_of_simulator_invocations =
-R"doc(Returns the total number of simulator invocations.
+static const char *__doc_fiction_detail_is_operational_impl_get_operational_status_assessment_stats =
+R"doc(Returns auxiliary results from the operational status assessment,
+including the number of simulator invocations.
 
 Returns:
-    The number of simulator invocations.)doc";
+    Auxiliary results from the operational status assessment.)doc";
 
 static const char *__doc_fiction_detail_is_operational_impl_input_bdl_wires = R"doc(Input BDL wires.)doc";
 
@@ -6897,7 +6938,9 @@ the gate layout and parameters provided during initialization.
     The operational status of the gate layout (either `OPERATIONAL` or
     `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_stats =
+R"doc(Auxiliary results from the operational status assessment, including
+the number of simulator invocations.)doc";
 
 static const char *__doc_fiction_detail_is_operational_impl_truth_table = R"doc(The specification of the layout.)doc";
 
@@ -13610,16 +13653,16 @@ Parameter ``input_bdl_wire_direction``:
 
 Returns:
     A pair containing the operational status of the gate layout
-    (either `OPERATIONAL` or `NON_OPERATIONAL`) and the number of
-    input combinations tested.)doc";
+    (either `OPERATIONAL` or `NON_OPERATIONAL`) along with auxiliary
+    statistics.)doc";
 
 static const char *__doc_fiction_is_operational_params = R"doc(Parameters for the `is_operational` algorithm.)doc";
 
 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 that 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
@@ -13629,6 +13672,20 @@ static const char *__doc_fiction_is_operational_params_simulation_parameters =
 R"doc(The simulation parameters for the physical simulation of the ground
 state.)doc";
 
+static const char *__doc_fiction_is_operational_params_simulation_results_mode = R"doc(Selector for the different ways to handle obtained simulation results.)doc";
+
+static const char *__doc_fiction_is_operational_params_simulation_results_mode_DISCARD_SIMULATION_RESULTS =
+R"doc(The simulation results are discarded after the operational status was
+assessed.)doc";
+
+static const char *__doc_fiction_is_operational_params_simulation_results_mode_KEEP_SIMULATION_RESULTS =
+R"doc(The simulation results for each input pattern are returned for
+operational gates.)doc";
+
+static const char *__doc_fiction_is_operational_params_simulation_results_retention =
+R"doc(Simulation results that are used to certify the status `OPERATIONAL`
+are not kept by default.)doc";
+
 static const char *__doc_fiction_is_positively_charged_defect =
 R"doc(Checks whether the given defect has a positive charge value assigned
 to it. This function is irrespective of the associated defect type.
@@ -13877,7 +13934,7 @@ Template parameter ``InputIt``:
     Must meet the requirements of `LegacyInputIterator`.
 
 Parameter ``first``:
-    Begin of the range to examime.
+    Begin of the range to examine.
 
 Parameter ``last``:
     End of the range to examine.
@@ -13895,7 +13952,7 @@ Template parameter ``InputIt``:
     Must meet the requirements of `LegacyInputIterator`.
 
 Parameter ``first``:
-    Begin of the range to examime.
+    Begin of the range to examine.
 
 Parameter ``last``:
     End of the range to examine.
@@ -14717,6 +14774,20 @@ static const char *__doc_fiction_operational_status_NON_OPERATIONAL = R"doc(The
 
 static const char *__doc_fiction_operational_status_OPERATIONAL = R"doc(The layout is operational.)doc";
 
+static const char *__doc_fiction_operational_status_assessment_stats =
+R"doc(This struct is used to collect auxiliary results from the operational
+status assessment.
+
+Template parameter ``SiDB``:
+    cell-level layout type.)doc";
+
+static const char *__doc_fiction_operational_status_assessment_stats_number_of_simulator_invocations = R"doc(The number of input combinations tested.)doc";
+
+static const char *__doc_fiction_operational_status_assessment_stats_simulation_results =
+R"doc(The charge distributions obtained for each input combination tested,
+sorted by the binary representation of the respectively associated
+input combinations.)doc";
+
 static const char *__doc_fiction_orthogonal =
 R"doc(A scalable placement & routing approach based on orthogonal graph
 drawing as originally proposed in \"Scalable Design for Field-coupled