💥 Introducing ClusterComplete: Exact SiDB Logic Simulation with well over 50 DBs

.github/workflows/clang-tidy-review.yml

@@ -35,6 +35,7 @@ jobs:
             -DFICTION_TEST=ON
             -DFICTION_BENCHMARK=OFF
             -DFICTION_EXPERIMENTS=ON
+            -DFICTION_ALGLIB=ON
             -DMOCKTURTLE_EXAMPLES=OFF
           build_dir: build
           apt_packages: "libreadline-dev,libtbb-dev"

.github/workflows/codeql-analysis.yml

@@ -128,6 +128,7 @@ jobs:
           -DFICTION_BENCHMARK=OFF
           -DFICTION_EXPERIMENTS=ON
           -DFICTION_Z3=ON
+          -DFICTION_ALGLIB=ON
           -DFICTION_ENABLE_MUGEN=ON
           -DFICTION_PROGRESS_BARS=OFF
           -DFICTION_WARNINGS_AS_ERRORS=OFF

.github/workflows/coverage.yml

@@ -101,6 +101,7 @@ jobs:
           -DFICTION_TEST=ON
           -DFICTION_BENCHMARK=OFF
           -DFICTION_Z3=ON
+          -DFICTION_ALGLIB=ON
           -DFICTION_ENABLE_MUGEN=ON
           -DFICTION_PROGRESS_BARS=OFF
           -DFICTION_WARNINGS_AS_ERRORS=OFF

.github/workflows/macos.yml

@@ -123,6 +123,7 @@ jobs:
           -DFICTION_BENCHMARK=OFF
           -DFICTION_EXPERIMENTS=ON
           -DFICTION_Z3=ON
+          -DFICTION_ALGLIB=ON
           -DFICTION_PROGRESS_BARS=OFF
           -DFICTION_WARNINGS_AS_ERRORS=OFF
           -DMOCKTURTLE_EXAMPLES=OFF
@@ -152,6 +153,7 @@ jobs:
           -DFICTION_BENCHMARK=OFF
           -DFICTION_EXPERIMENTS=ON
           -DFICTION_Z3=ON
+          -DFICTION_ALGLIB=ON
           -DFICTION_PROGRESS_BARS=OFF
           -DFICTION_WARNINGS_AS_ERRORS=OFF
           -DMOCKTURTLE_EXAMPLES=OFF

.github/workflows/pyfiction-docstring-generator.yml

@@ -39,6 +39,7 @@ jobs:
           -m pybind11_mkdoc
           -o ${{ github.workspace }}/bindings/mnt/pyfiction/include/pyfiction/pybind11_mkdoc_docstrings.hpp
           -D FICTION_Z3_SOLVER
+          -D FICTION_ALGLIB_ENABLED
           `find ${{ github.workspace }}/include/fiction -name "*.hpp" -print`
 
       - name: Upload docstrings as an artifact

.github/workflows/ubuntu.yml

@@ -123,6 +123,7 @@ jobs:
           -DFICTION_BENCHMARK=OFF
           -DFICTION_EXPERIMENTS=ON
           -DFICTION_Z3=ON
+          -DFICTION_ALGLIB=ON
           -DFICTION_ENABLE_MUGEN=ON
           -DFICTION_PROGRESS_BARS=OFF
           -DFICTION_WARNINGS_AS_ERRORS=OFF
@@ -154,6 +155,7 @@ jobs:
           -DFICTION_BENCHMARK=OFF
           -DFICTION_EXPERIMENTS=ON
           -DFICTION_Z3=ON
+          -DFICTION_ALGLIB=ON
           -DFICTION_ENABLE_MUGEN=ON
           -DFICTION_PROGRESS_BARS=OFF
           -DFICTION_WARNINGS_AS_ERRORS=OFF

.github/workflows/windows.yml

@@ -104,6 +104,7 @@ jobs:
           -DFICTION_BENCHMARK=OFF
           -DFICTION_EXPERIMENTS=ON
           -DFICTION_Z3=ON
+          -DFICTION_ALGLIB=ON
           -DFICTION_WARNINGS_AS_ERRORS=OFF
           -DMOCKTURTLE_EXAMPLES=OFF
 
@@ -132,6 +133,7 @@ jobs:
           -DFICTION_BENCHMARK=OFF
           -DFICTION_EXPERIMENTS=ON
           -DFICTION_Z3=ON
+          -DFICTION_ALGLIB=ON
           -DFICTION_WARNINGS_AS_ERRORS=OFF
           -DMOCKTURTLE_EXAMPLES=OFF
 

.gitmodules

@@ -20,3 +20,6 @@
 	path = libs/mockturtle
 	url = https://github.com/marcelwa/mockturtle.git
 	branch = mnt
+[submodule "libs/alglib-cmake"]
+	path = libs/alglib-cmake
+	url = https://github.com/wlambooy/alglib-cmake.git

.readthedocs.yml

@@ -12,8 +12,8 @@ build:
     - cmake
   jobs:
     pre_build:
-      - echo "Reinstall pyfiction with Z3 enabled"
-      - z3="ON" python -m pip install --upgrade --upgrade-strategy eager --no-cache-dir .[docs]
+      - echo "Reinstall pyfiction with Z3 and ALGLIB enabled"
+      - z3="ON" alglib="ON" python -m pip install --upgrade --upgrade-strategy eager --no-cache-dir .[docs]
 
 sphinx:
   configuration: docs/conf.py

Dockerfile

@@ -53,6 +53,7 @@ RUN . venv/bin/activate \
       -DFICTION_TEST=OFF \
       -DFICTION_EXPERIMENTS=OFF \
       -DFICTION_Z3=ON \
+      -DFICTION_ALGLIB=ON \
       -DFICTION_ENABLE_MUGEN=OFF \
       -DFICTION_PROGRESS_BARS=ON \
       -DFICTION_WARNINGS_AS_ERRORS=OFF \

README.md

@@ -227,6 +227,7 @@ simulated using a physical model. Currently, the following simulation algorithms
 
 - Silicon Dangling Bonds (SiDBs)
   - Electrostatic Ground State Simulation
+    - [_ClusterComplete_](https://fiction.readthedocs.io/en/latest/algorithms/sidb_simulation.html#_CPPv4I0EN7fiction15clustercompleteE22sidb_simulation_resultI3LytERK3LytRK22clustercomplete_paramsI4cellI3LytEE)
     - [_QuickExact_](https://arxiv.org/abs/2308.04487)
     - [_QuickSim_](https://ieeexplore.ieee.org/document/10231266)
     - [Exhaustive _(ExGS)_](https://open.library.ubc.ca/soa/cIRcle/collections/ubctheses/24/items/1.0392909)

bindings/mnt/__init__.py

@@ -2,10 +2,13 @@
 import sys
 from pathlib import Path
 
-if sys.platform == "win32" and "Z3_ROOT" in os.environ:
-    lib_path = Path(os.environ["Z3_ROOT"]) / "lib"
-    if lib_path.exists():
-        os.add_dll_directory(str(lib_path))
-    bin_path = Path(os.environ["Z3_ROOT"]) / "bin"
-    if bin_path.exists():
-        os.add_dll_directory(str(bin_path))
+if sys.platform == "win32":
+    if "Z3_ROOT" in os.environ:
+        lib_path = Path(os.environ["Z3_ROOT"]) / "lib"
+        if lib_path.exists():
+            os.add_dll_directory(str(lib_path))
+        bin_path = Path(os.environ["Z3_ROOT"]) / "bin"
+        if bin_path.exists():
+            os.add_dll_directory(str(bin_path))
+    if "ALGLIB_DIR" in os.environ:
+        os.add_dll_directory(str(os.environ["ALGLIB_DIR"]))

bindings/mnt/pyfiction/__init__.py

@@ -8,13 +8,16 @@
 import sys
 from pathlib import Path
 
-if sys.platform == "win32" and "Z3_ROOT" in os.environ:
-    lib_path = Path(os.environ["Z3_ROOT"]) / "lib"
-    if lib_path.exists():
-        os.add_dll_directory(str(lib_path))
-    bin_path = Path(os.environ["Z3_ROOT"]) / "bin"
-    if bin_path.exists():
-        os.add_dll_directory(str(bin_path))
+if sys.platform == "win32":
+    if "Z3_ROOT" in os.environ:
+        lib_path = Path(os.environ["Z3_ROOT"]) / "lib"
+        if lib_path.exists():
+            os.add_dll_directory(str(lib_path))
+        bin_path = Path(os.environ["Z3_ROOT"]) / "bin"
+        if bin_path.exists():
+            os.add_dll_directory(str(bin_path))
+    if "ALGLIB_DIR" in os.environ:
+        os.add_dll_directory(str(os.environ["ALGLIB_DIR"]))
 
 from .pyfiction import (  # type: ignore[import-not-found]
     __compiled_date__,
@@ -64,6 +67,8 @@
     clocked_cartesian_layout,
     clocked_hexagonal_layout,
     clocked_shifted_cartesian_layout,
+    clustercomplete,
+    clustercomplete_params,
     color_mode,
     color_routing,
     color_routing_params,
@@ -155,8 +160,10 @@
     graph_oriented_layout_design,
     graph_oriented_layout_design_params,
     graph_oriented_layout_design_stats,
+    ground_state_space_reporting,
     groundstate_from_simulation_result,
     has_high_degree_fanin_nodes,
+    heuristic_sidb_simulation_engine,
     hexagonal_gate_layout,
     hexagonal_layout,
     hexagonal_obstruction_layout,
@@ -258,6 +265,7 @@
     sidb_nm_distance_111,
     sidb_nm_position,
     sidb_simulation_engine,
+    sidb_simulation_engine_name,
     sidb_simulation_parameters,
     sidb_simulation_result_100,
     sidb_simulation_result_111,
@@ -366,6 +374,8 @@
     "clocked_cartesian_layout",
     "clocked_hexagonal_layout",
     "clocked_shifted_cartesian_layout",
+    "clustercomplete",
+    "clustercomplete_params",
     "color_mode",
     "color_routing",
     "color_routing_params",
@@ -457,8 +467,10 @@
     "graph_oriented_layout_design",
     "graph_oriented_layout_design_params",
     "graph_oriented_layout_design_stats",
+    "ground_state_space_reporting",
     "groundstate_from_simulation_result",
     "has_high_degree_fanin_nodes",
+    "heuristic_sidb_simulation_engine",
     "hexagonal_gate_layout",
     "hexagonal_layout",
     "hexagonal_obstruction_layout",
@@ -560,6 +572,7 @@
     "sidb_nm_distance_111",
     "sidb_nm_position",
     "sidb_simulation_engine",
+    "sidb_simulation_engine_name",
     "sidb_simulation_parameters",
     "sidb_simulation_result_100",
     "sidb_simulation_result_111",

bindings/mnt/pyfiction/include/pyfiction/algorithms/simulation/sidb/clustercomplete.hpp

@@ -0,0 +1,103 @@
+//
+// Created by marcel on 21.11.23.
+//
+
+#ifndef PYFICTION_CLUSTERCOMPLETE_HPP
+#define PYFICTION_CLUSTERCOMPLETE_HPP
+
+#if (FICTION_ALGLIB_ENABLED)
+
+#include "pyfiction/documentation.hpp"
+#include "pyfiction/types.hpp"
+
+#include <fiction/algorithms/simulation/sidb/clustercomplete.hpp>
+#include <fiction/layouts/coordinates.hpp>
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+namespace pyfiction
+{
+
+namespace detail
+{
+
+template <typename Lyt>
+void clustercomplete(pybind11::module& m)
+{
+    namespace py = pybind11;
+
+    m.def("clustercomplete", &fiction::clustercomplete<Lyt>, py::arg("lyt"),
+          py::arg("params") = fiction::clustercomplete_params<fiction::offset::ucoord_t>{},
+          DOC(fiction_clustercomplete));
+}
+
+}  // namespace detail
+
+inline void clustercomplete(pybind11::module& m)
+{
+    // NOTE be careful with the order of the following calls! Python will resolve the first matching overload!
+    namespace py = pybind11;
+
+    /**
+     * Report *Ground State Space* stats.
+     */
+    py::enum_<fiction::ground_state_space_reporting>(m, "ground_state_space_reporting",
+                                                     DOC(fiction_ground_state_space_reporting))
+        .value("ENABLED", fiction::ground_state_space_reporting::ENABLED,
+               DOC(fiction_ground_state_space_reporting_ENABLED))
+        .value("DISABLED", fiction::ground_state_space_reporting::DISABLED,
+               DOC(fiction_ground_state_space_reporting_DISABLED));
+
+    /**
+     * ClusterComplete parameters.
+     */
+    py::class_<fiction::clustercomplete_params<fiction::offset::ucoord_t>>(m, "clustercomplete_params",
+                                                                           DOC(fiction_clustercomplete_params))
+        .def(py::init<>())
+        .def_readwrite("simulation_parameters",
+                       &fiction::clustercomplete_params<fiction::offset::ucoord_t>::simulation_parameters,
+                       DOC(fiction_clustercomplete_params_simulation_parameters))
+        .def_readwrite("local_external_potential",
+                       &fiction::clustercomplete_params<fiction::offset::ucoord_t>::local_external_potential,
+                       DOC(fiction_clustercomplete_params_local_external_potential))
+        .def_readwrite("global_potential",
+                       &fiction::clustercomplete_params<fiction::offset::ucoord_t>::global_potential,
+                       DOC(fiction_clustercomplete_params_global_potential))
+        .def_readwrite("validity_witness_partitioning_max_cluster_size_gss",
+                       &fiction::clustercomplete_params<
+                           fiction::offset::ucoord_t>::validity_witness_partitioning_max_cluster_size_gss,
+                       DOC(fiction_clustercomplete_params_validity_witness_partitioning_max_cluster_size_gss))
+        .def_readwrite("num_overlapping_witnesses_limit_gss",
+                       &fiction::clustercomplete_params<fiction::offset::ucoord_t>::num_overlapping_witnesses_limit_gss,
+                       DOC(fiction_clustercomplete_params_num_overlapping_witnesses_limit_gss))
+        .def_readwrite("available_threads",
+                       &fiction::clustercomplete_params<fiction::offset::ucoord_t>::available_threads,
+                       DOC(fiction_clustercomplete_params_available_threads))
+        .def_readwrite("report_gss_stats",
+                       &fiction::clustercomplete_params<fiction::offset::ucoord_t>::report_gss_stats,
+                       DOC(fiction_clustercomplete_params_report_gss_stats));
+
+    detail::clustercomplete<py_sidb_100_lattice>(m);
+    detail::clustercomplete<py_sidb_111_lattice>(m);
+}
+
+}  // namespace pyfiction
+
+#else  // FICTION_ALGLIB_ENABLED
+
+#include <pybind11/pybind11.h>
+
+namespace pyfiction
+{
+
+/**
+ * Disable ClusterComplete.
+ */
+inline void clustercomplete([[maybe_unused]] pybind11::module& m) {}
+
+}  // namespace pyfiction
+
+#endif  // FICTION_ALGLIB_ENABLED
+
+#endif  // PYFICTION_CLUSTERCOMPLETE_HPP

bindings/mnt/pyfiction/include/pyfiction/algorithms/simulation/sidb/quickexact.hpp

@@ -52,7 +52,7 @@ inline void quickexact(pybind11::module& m)
         .def(py::init<>())
         .def_readwrite("simulation_parameters",
                        &fiction::quickexact_params<fiction::offset::ucoord_t>::simulation_parameters,
-                       DOC(fiction_quickexact_params))
+                       DOC(fiction_quickexact_params_simulation_parameters))
         .def_readwrite("base_number_detection",
                        &fiction::quickexact_params<fiction::offset::ucoord_t>::base_number_detection,
                        DOC(fiction_quickexact_params_base_number_detection))

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

@@ -11,9 +11,27 @@
 
 #include <pybind11/pybind11.h>
 
+#include <string>
+
 namespace pyfiction
 {
 
+namespace detail
+{
+
+template <typename EngineType>
+void sidb_simulation_engine_name(pybind11::module& m)
+{
+    namespace py = pybind11;
+
+    m.def(
+        "sidb_simulation_engine_name",
+        [](const EngineType& engine) -> std::string { return fiction::sidb_simulation_engine_name(engine); },
+        py::arg("engine"), DOC(fiction_sidb_simulation_engine_name));
+}
+
+}  // namespace detail
+
 inline void sidb_simulation_engine(pybind11::module& m)
 {
     namespace py = pybind11;
@@ -23,6 +41,8 @@ inline void sidb_simulation_engine(pybind11::module& m)
         .value("QUICKSIM", fiction::sidb_simulation_engine::QUICKSIM, DOC(fiction_sidb_simulation_engine_QUICKSIM))
         .value("QUICKEXACT", fiction::sidb_simulation_engine::QUICKEXACT,
                DOC(fiction_sidb_simulation_engine_QUICKEXACT))
+        .value("CLUSTERCOMPLETE", fiction::sidb_simulation_engine::CLUSTERCOMPLETE,
+               DOC(fiction_sidb_simulation_engine_CLUSTERCOMPLETE))
 
         ;
 
@@ -31,8 +51,21 @@ inline void sidb_simulation_engine(pybind11::module& m)
         .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))
+        .value("CLUSTERCOMPLETE", fiction::exact_sidb_simulation_engine::CLUSTERCOMPLETE,
+               DOC(fiction_exact_sidb_simulation_engine_CLUSTERCOMPLETE))
+
+        ;
+
+    py::enum_<fiction::heuristic_sidb_simulation_engine>(m, "heuristic_sidb_simulation_engine",
+                                                         DOC(fiction_heuristic_sidb_simulation_engine))
+        .value("QUICKSIM", fiction::heuristic_sidb_simulation_engine::QUICKSIM,
+               DOC(fiction_heuristic_sidb_simulation_engine_QUICKSIM))
 
         ;
+
+    detail::sidb_simulation_engine_name<fiction::sidb_simulation_engine>(m);
+    detail::sidb_simulation_engine_name<fiction::exact_sidb_simulation_engine>(m);
+    detail::sidb_simulation_engine_name<fiction::heuristic_sidb_simulation_engine>(m);
 }
 
 }  // namespace pyfiction