✨ H-Si(111)-1x1 surface support (#380)

* 🐛 correct input is used for computation.

* 🎨 add Si-111 support.

* 🐛 small bug fix.

* ✨ add function to determine the ground state cds from the simulation struct.

* 📝 update docu.

* 🎨 remove redundant line.

* 🎨 add or remove headers.

* 📝 update docu.

* ✨ novel layout type to store and access lattice orientation.

* ✨ include headers and renaming.

* 🎨 include missing headers

* 🎨 update code to support the new sidb lattice layout.

* 🎨 add costexpr.

* 🎨 update experiment due to change in the ``write_sqd_file`` function.

* 🎨 update experiment due to change in the ``write_sqd_file`` and ``read_sqd_file`` functions.

* 🎨 update experiment due to change in the ``write_sqd_file`` and ``read_sqd_file`` functions.

* ✅ update tests due to change in the ``write_sqd_file`` and ``read_sqd_file`` functions.

* 🎨 update functions to take the lattice orientation into account.

* ✨ new file to summarize si lattice orientations and lattice constants.

* ✨ add functions to change the tile size dimension.

* 🎨 update functions to use the sidb_lattice_layout.

* 🚧 WIP code.

* 🚧 Introduce lattice orientation as a template parameter to avoid runtime overhead.

* 🔥 delete skeleton files.

* 🔥 delete skeleton files.

* 🎨 add an additional line.

* ✅ add test for gate design.

* ✨ add 111 surface to print function.

* ✨ Si-111 support in CLI commands.

* 🎨 fix typo.

* 🎨 update experiments due to architectural changes

* 🎨 small updates here and there.

* 🎨 update print and convert function.

* 🎨 reformat code.

* 🎨 use one character for the flag.

* 🎨 update to correctly print cds after simulation via ``Quickexact`` and ``Quicksim``.

* 🎨 reformat code.

* 🎨 reformat code.

* 🎨 correct unit test and try again to reformat code.

* 🎨 correct unit test, update traits.

* 🎨 correct unit test.

* 📝 update docu.

* 👷 try to fix the issue on Windows.

* 🎨 delete unnecessary input.

* 👷 try to fix the Windows issue.

* 🎨 reformat code

* 🔀 fix merge issue.

* 🔀 resolve merge conflict.

* 🎨 delete redundant header.

* 🎨 reformat code.

* 🎨 delete redundant headers.

* ✅ update unittest.

* 🎨 Implementation of the first batch of Marcel's feedback and some additional changes.

* 🎨 update experiment script.

* 🎨 second batch of Marcel's feedback.

* 🎨 small change.

* 🎨 small fix.

* 🎨 check if a lattice layout already exists.

* 🎨 small fixes.

* 🐛 fix bugs in print and convert functions.

* 🎨 add template parameter to fix Windows issue.

* 🎨 delete superfluous header.

* 🎨 fix typo.

* 🐛 fix incorrect lattice naming.

* ✅ add unit test for ``number_of_operational_input_combinations``

* ✨ add ``stats`` to collect operational inputs.

* 🎨 small fix.

* 🎨 update ``convert_to_fiction_coordinates`` function to support defects and charge states.

* 🎨 add new types.

* 🎨 update layout convert functions.

* 🎨 Add or delete missing and redundant headers.

* 🎨 add template parameter for windows.

* 🎨 use ``has_get_sidb_defect_v`` instead of ``is_sidb_defect_surface_v`` to fix windows compile error.

* 🎨 add additional ``std::declval``.

* 🎨 use ``is_sidb_defect_surface_v`` again.

* 📝 update docu.

* 🎨 revert changes in experiments.

* 🎨 add ``#pragma``.

* 🎨 Implement the first batch of Marcel's comments.

* 🎨 small fix.

* 🎨 Implement the second batch of Marcel's comments.

* 🎨 small fix.

* 🎨 use ``\n`` for newline.

* 🎨 Implement Marcel's comments.

* 🎨 small fix.

* 🎨 fix typo.

cli/cmd/io/read.hpp

@@ -9,6 +9,7 @@
 #include <fiction/io/read_fgl_layout.hpp>
 #include <fiction/io/read_fqca_layout.hpp>
 #include <fiction/io/read_sqd_layout.hpp>
+#include <fiction/technology/sidb_lattice.hpp>
 #include <fiction/types.hpp>
 
 #include <alice/alice.hpp>
@@ -48,6 +49,7 @@ class read_command : public command
         add_option("topology", topology,
                    "Topology for gate-level layouts. Can be 'cartesian' or of the form "
                    "'<odd|even>_<row|column>_<cartesian|hex>'");
+        add_option("--lattice_orientation,-o", orientation, "Lattice orientation for SQD files to use {100, 111}");
         add_flag("--aig,-a", "Parse Verilog file as AIG");
         add_flag("--xag,-x", "Parse Verilog file as XAG");
         add_flag("--mig,-m", "Parse Verilog file as MIG");
@@ -215,10 +217,20 @@ class read_command : public command
                                 {
                                     const auto layout_name = std::filesystem::path{filename}.stem().string();
 
-                                    store<fiction::cell_layout_t>().extend() =
-                                        std::make_shared<fiction::sidb_cell_clk_lyt>(
-                                            fiction::read_sqd_layout<fiction::sidb_cell_clk_lyt>(filename,
-                                                                                                 layout_name));
+                                    if (orientation == "100")
+                                    {
+                                        const auto layout = fiction::read_sqd_layout<fiction::sidb_100_cell_clk_lyt>(
+                                            filename, layout_name);
+                                        store<fiction::cell_layout_t>().extend() =
+                                            std::make_shared<fiction::sidb_100_cell_clk_lyt>(layout);
+                                    }
+                                    else if (orientation == "111")
+                                    {
+                                        const auto layout = fiction::read_sqd_layout<fiction::sidb_111_cell_clk_lyt>(
+                                            filename, layout_name);
+                                        store<fiction::cell_layout_t>().extend() =
+                                            std::make_shared<fiction::sidb_111_cell_clk_lyt>(layout);
+                                    }
                                 }
                                 catch (const fiction::sqd_parsing_error& e)
                                 {
@@ -291,6 +303,10 @@ class read_command : public command
      * Flag to indicate that files should be sorted by file size.
      */
     bool sort = false;
+    /**
+     * Identifier of H-Si lattice orientation.
+     */
+    std::string orientation{"100"};
 };
 
 ALICE_ADD_COMMAND(read, "I/O")

cli/cmd/io/sqd.hpp

@@ -7,6 +7,7 @@
 
 #include <fiction/io/write_sqd_layout.hpp>
 #include <fiction/technology/cell_technologies.hpp>
+#include <fiction/technology/sidb_lattice.hpp>
 #include <fiction/traits.hpp>
 #include <fiction/types.hpp>
 #include <fiction/utils/name_utils.hpp>

cli/cmd/simulation/quickexact.hpp

@@ -57,18 +57,19 @@ class quickexact_command : public command
     void execute() override
     {
         // reset sim result
-        sim_result = {};
-        min_energy = std::numeric_limits<double>::infinity();
+        sim_result_100 = {};
+        sim_result_111 = {};
+        min_energy     = std::numeric_limits<double>::infinity();
 
         if (physical_params.epsilon_r <= 0)
         {
-            env->out() << "[e] epsilon_r must be positive" << std::endl;
+            env->out() << "[e] epsilon_r must be positive\n";
             reset_params();
             return;
         }
         if (physical_params.lambda_tf <= 0)
         {
-            env->out() << "[e] lambda_tf must be positive" << std::endl;
+            env->out() << "[e] lambda_tf must be positive\n";
             reset_params();
             return;
         }
@@ -78,7 +79,7 @@ class quickexact_command : public command
         // error case: empty cell layout store
         if (s.empty())
         {
-            env->out() << "[w] no cell layout in store" << std::endl;
+            env->out() << "[w] no cell layout in store\n";
             reset_params();
             return;
         }
@@ -94,36 +95,62 @@ class quickexact_command : public command
                 if constexpr (fiction::is_charge_distribution_surface_v<Lyt>)
                 {
                     env->out() << fmt::format(
-                                      "[w] {} already possesses a charge distribution; no simulation is conducted",
-                                      get_name(lyt_ptr))
-                               << std::endl;
+                        "[w] {} already possesses a charge distribution; no simulation is conducted\n",
+                        get_name(lyt_ptr));
                 }
                 else
                 {
-                    params.physical_parameters = physical_params;
+                    if constexpr (fiction::is_sidb_lattice_100_v<Lyt>)
+                    {
+                        params.physical_parameters = physical_params;
+                        sim_result_100             = fiction::quickexact(*lyt_ptr, params);
+                    }
+                    else if constexpr (fiction::is_sidb_lattice_111_v<Lyt>)
+                    {
+                        params.physical_parameters = physical_params;
+                        auto cps                   = convert_params<Lyt>(params);
+                        sim_result_111             = fiction::quickexact(*lyt_ptr, cps);
+                    }
 
-                    sim_result = fiction::quickexact(*lyt_ptr, params);
+                    else
+                    {
+                        env->out() << "[e] no valid lattice orientation\n";
+                        return;
+                    }
 
-                    if (sim_result.charge_distributions.empty())
+                    if (sim_result_100.charge_distributions.empty() && sim_result_111.charge_distributions.empty())
                     {
                         env->out() << fmt::format("[e] ground state of {} could not be determined", get_name(lyt_ptr))
                                    << std::endl;
                     }
                     else
                     {
-                        const auto min_energy_distr = fiction::minimum_energy_distribution(
-                            sim_result.charge_distributions.cbegin(), sim_result.charge_distributions.cend());
-
-                        min_energy = min_energy_distr->get_system_energy();
-
-                        store<fiction::cell_layout_t>().extend() =
-                            std::make_shared<fiction::cds_sidb_cell_clk_lyt>(*min_energy_distr);
+                        if constexpr (fiction::is_sidb_lattice_100_v<Lyt>)
+                        {
+                            const auto min_energy_distr =
+                                fiction::minimum_energy_distribution(sim_result_100.charge_distributions.cbegin(),
+                                                                     sim_result_100.charge_distributions.cend());
+
+                            min_energy = min_energy_distr->get_system_energy();
+                            store<fiction::cell_layout_t>().extend() =
+                                std::make_shared<fiction::cds_sidb_100_cell_clk_lyt>(*min_energy_distr);
+                        }
+                        else if constexpr (fiction::is_sidb_lattice_111_v<Lyt>)
+                        {
+                            const auto min_energy_distr =
+                                fiction::minimum_energy_distribution(sim_result_111.charge_distributions.cbegin(),
+                                                                     sim_result_111.charge_distributions.cend());
+
+                            min_energy = min_energy_distr->get_system_energy();
+                            store<fiction::cell_layout_t>().extend() =
+                                std::make_shared<fiction::cds_sidb_111_cell_clk_lyt>(*min_energy_distr);
+                        }
                     }
                 }
             }
             else
             {
-                env->out() << fmt::format("[e] {} is not an SiDB layout", get_name(lyt_ptr)) << std::endl;
+                env->out() << fmt::format("[e] {} is not an SiDB layout\n", get_name(lyt_ptr));
             }
         };
 
@@ -140,11 +167,15 @@ class quickexact_command : public command
     /**
      * QuickExact parameters.
      */
-    fiction::quickexact_params<fiction::sidb_cell_clk_lyt> params{};
+    fiction::quickexact_params<fiction::sidb_100_cell_clk_lyt> params{};
+    /**
+     * Simulation result for H-Si(100)-2x1 surface.
+     */
+    fiction::sidb_simulation_result<fiction::sidb_100_cell_clk_lyt> sim_result_100{};
     /**
-     * Simulation result.
+     * Simulation result for H-Si(111)-1x1 surface.
      */
-    fiction::sidb_simulation_result<fiction::sidb_cell_clk_lyt> sim_result{};
+    fiction::sidb_simulation_result<fiction::sidb_111_cell_clk_lyt> sim_result_111{};
     /**
      * Minimum energy.
      */
@@ -160,18 +191,18 @@ class quickexact_command : public command
         try
         {
             return nlohmann::json{
-                {"Algorithm name", sim_result.algorithm_name},
-                {"Simulation runtime", sim_result.simulation_runtime.count()},
+                {"Algorithm name", sim_result_100.algorithm_name},
+                {"Simulation runtime", sim_result_100.simulation_runtime.count()},
                 {"Physical parameters",
-                 {{"base", std::any_cast<uint64_t>(sim_result.additional_simulation_parameters.at(
+                 {{"base", std::any_cast<uint64_t>(sim_result_100.additional_simulation_parameters.at(
                                "base_number"))},  // fetch the automatically inferred base number
-                  {"epsilon_r", sim_result.physical_parameters.epsilon_r},
-                  {"lambda_tf", sim_result.physical_parameters.lambda_tf},
-                  {"mu_minus", sim_result.physical_parameters.mu_minus},
+                  {"epsilon_r", sim_result_100.physical_parameters.epsilon_r},
+                  {"lambda_tf", sim_result_100.physical_parameters.lambda_tf},
+                  {"mu_minus", sim_result_100.physical_parameters.mu_minus},
                   {"global_potential",
-                   std::any_cast<double>(sim_result.additional_simulation_parameters.at("global_potential"))}}},
+                   std::any_cast<double>(sim_result_100.additional_simulation_parameters.at("global_potential"))}}},
                 {"Ground state energy (eV)", min_energy},
-                {"Number of stable states", sim_result.charge_distributions.size()}};
+                {"Number of stable states", sim_result_100.charge_distributions.size()}};
         }
         catch (...)
         {
@@ -185,6 +216,20 @@ class quickexact_command : public command
     {
         physical_params = fiction::sidb_simulation_parameters{2, -0.32, 5.6, 5.0};
         params          = {};
+        sim_result_100  = {};
+        sim_result_111  = {};
+    }
+
+    template <typename LytDest, typename LytSrc>
+    [[nodiscard]] fiction::quickexact_params<LytDest>
+    convert_params(const fiction::quickexact_params<LytSrc>& ps_src) const noexcept
+    {
+        fiction::quickexact_params<LytDest> ps_dest{};
+
+        ps_dest.physical_parameters = ps_src.physical_parameters;
+        ps_dest.global_potential    = ps_src.global_potential;
+
+        return ps_dest;
     }
 };
 

cli/cmd/simulation/quicksim.hpp

@@ -59,8 +59,9 @@ class quicksim_command : public command
     void execute() override
     {
         // reset sim result
-        sim_result = {};
-        min_energy = std::numeric_limits<double>::infinity();
+        sim_result_100 = {};
+        sim_result_111 = {};
+        min_energy     = std::numeric_limits<double>::infinity();
 
         if (physical_params.epsilon_r <= 0)
         {
@@ -110,23 +111,49 @@ class quicksim_command : public command
                 {
                     params.phys_params = physical_params;
 
-                    sim_result = fiction::quicksim(*lyt_ptr, params);
+                    if constexpr (fiction::is_sidb_lattice_100_v<Lyt>)
+                    {
+                        sim_result_100 = fiction::quicksim(*lyt_ptr, params);
+                    }
+                    else if constexpr (fiction::is_sidb_lattice_111_v<Lyt>)
+                    {
+                        sim_result_111 = fiction::quicksim(*lyt_ptr, params);
+                    }
+
+                    else
+                    {
+                        env->out() << "[e] no valid lattice orientation" << std::endl;
+                        return;
+                    }
 
-                    if (sim_result.charge_distributions.empty())
+                    if (sim_result_100.charge_distributions.empty() && sim_result_111.charge_distributions.empty())
                     {
                         env->out() << fmt::format("[e] no stable charge distribution could be determined for {}",
                                                   get_name(lyt_ptr))
                                    << std::endl;
                     }
                     else
                     {
-                        const auto min_energy_distr = fiction::minimum_energy_distribution(
-                            sim_result.charge_distributions.cbegin(), sim_result.charge_distributions.cend());
-
-                        min_energy = min_energy_distr->get_system_energy();
-
-                        store<fiction::cell_layout_t>().extend() =
-                            std::make_shared<fiction::cds_sidb_cell_clk_lyt>(*min_energy_distr);
+                        if constexpr (fiction::is_sidb_lattice_100_v<Lyt>)
+                        {
+                            const auto min_energy_distr =
+                                fiction::minimum_energy_distribution(sim_result_100.charge_distributions.cbegin(),
+                                                                     sim_result_100.charge_distributions.cend());
+
+                            min_energy = min_energy_distr->get_system_energy();
+                            store<fiction::cell_layout_t>().extend() =
+                                std::make_shared<fiction::cds_sidb_100_cell_clk_lyt>(*min_energy_distr);
+                        }
+                        else if constexpr (fiction::is_sidb_lattice_111_v<Lyt>)
+                        {
+                            const auto min_energy_distr =
+                                fiction::minimum_energy_distribution(sim_result_111.charge_distributions.cbegin(),
+                                                                     sim_result_111.charge_distributions.cend());
+
+                            min_energy = min_energy_distr->get_system_energy();
+                            store<fiction::cell_layout_t>().extend() =
+                                std::make_shared<fiction::cds_sidb_111_cell_clk_lyt>(*min_energy_distr);
+                        }
                     }
                 }
             }
@@ -151,9 +178,13 @@ class quicksim_command : public command
      */
     fiction::quicksim_params params{};
     /**
-     * Simulation result.
+     * Simulation result for H-Si(100)-2x1 surface.
+     */
+    fiction::sidb_simulation_result<fiction::sidb_100_cell_clk_lyt> sim_result_100{};
+    /**
+     * Simulation result for H-Si(111)-1x1 surface.
      */
-    fiction::sidb_simulation_result<fiction::sidb_cell_clk_lyt> sim_result{};
+    fiction::sidb_simulation_result<fiction::sidb_111_cell_clk_lyt> sim_result_111{};
     /**
      * Minimum energy.
      */
@@ -169,17 +200,17 @@ class quicksim_command : public command
         try
         {
             return nlohmann::json{
-                {"Algorithm name", sim_result.algorithm_name},
-                {"Simulation runtime", sim_result.simulation_runtime.count()},
+                {"Algorithm name", sim_result_100.algorithm_name},
+                {"Simulation runtime", sim_result_100.simulation_runtime.count()},
                 {"Physical parameters",
-                 {{"epsilon_r", sim_result.physical_parameters.epsilon_r},
-                  {"lambda_tf", sim_result.physical_parameters.lambda_tf},
-                  {"mu_minus", sim_result.physical_parameters.mu_minus}}},
+                 {{"epsilon_r", sim_result_100.physical_parameters.epsilon_r},
+                  {"lambda_tf", sim_result_100.physical_parameters.lambda_tf},
+                  {"mu_minus", sim_result_100.physical_parameters.mu_minus}}},
                 {"Lowest state energy (eV)", min_energy},
-                {"Number of stable states", sim_result.charge_distributions.size()},
+                {"Number of stable states", sim_result_100.charge_distributions.size()},
                 {"Iteration steps",
-                 std::any_cast<uint64_t>(sim_result.additional_simulation_parameters.at("iteration_steps"))},
-                {"alpha", std::any_cast<double>(sim_result.additional_simulation_parameters.at("alpha"))}};
+                 std::any_cast<uint64_t>(sim_result_100.additional_simulation_parameters.at("iteration_steps"))},
+                {"alpha", std::any_cast<double>(sim_result_100.additional_simulation_parameters.at("alpha"))}};
         }
         catch (...)
         {

cli/cmd/simulation/temp.hpp

@@ -197,7 +197,7 @@ class temp_command : public command
     /**
      * Critical temperature statistics.
      */
-    fiction::critical_temperature_stats<fiction::sidb_cell_clk_lyt> stats{};
+    fiction::critical_temperature_stats stats{};
 
     /**
      * Logs the resulting information in a log file.

cli/cmd/technology/cell.hpp

@@ -129,16 +129,16 @@ class cell_command : public command
         }
         else if (library == "BESTAGON")
         {
-            const auto apply_sidb_bestagon = [](auto&& lyt_ptr) -> std::optional<fiction::sidb_cell_clk_lyt_ptr>
+            const auto apply_sidb_bestagon = [](auto&& lyt_ptr) -> std::optional<fiction::sidb_100_cell_clk_lyt_ptr>
             {
                 using Lyt = typename std::decay_t<decltype(lyt_ptr)>::element_type;
 
                 if constexpr (fiction::is_hexagonal_layout_v<Lyt>)
                 {
                     if constexpr (fiction::has_pointy_top_hex_orientation_v<Lyt>)
                     {
-                        return std::make_shared<fiction::sidb_cell_clk_lyt>(
-                            fiction::apply_gate_library<fiction::sidb_cell_clk_lyt, fiction::sidb_bestagon_library>(
+                        return std::make_shared<fiction::sidb_100_cell_clk_lyt>(
+                            fiction::apply_gate_library<fiction::sidb_100_cell_clk_lyt, fiction::sidb_bestagon_library>(
                                 *lyt_ptr));
                     }
                     else

docs/algorithms/sidb_simulation.rst

@@ -86,6 +86,11 @@ Energy Calculation
 .. doxygenfunction:: fiction::check_simulation_results_for_equivalence
 
 
+**Header:** ``fiction/algorithms/simulation/sidb/determine_groundstate_from_simulation_results.hpp``
+
+.. doxygenfunction:: fiction::determine_groundstate_from_simulation_results
+
+
 Temperature Behavior
 ####################
 
@@ -153,6 +158,7 @@ Operational Domain Computation
 .. doxygenstruct:: fiction::is_operational_params
    :members:
 .. doxygenfunction:: fiction::is_operational
+.. doxygenfunction:: fiction::operational_input_patterns
 
 **Header:** ``fiction/algorithms/simulation/sidb/operational_domain.hpp``