Merge branch 'main' into pyml

# Conflicts:
#	docs/algorithms/sidb_simulation.rst
#	libs/pybind11

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

@@ -14,7 +14,7 @@ jobs:
     steps:
       # Download the artifact uploaded by the lint action
       - name: Download Clang-Tidy artifact
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
         with:
           script: |
             const artifacts = await github.rest.actions.listWorkflowRunArtifacts({

docs/algorithms/sidb_simulation.rst

@@ -265,3 +265,24 @@ Binary-dot Logic (BDL) Pair Detection
         .. autoclass:: fiction.pyfiction.detect_bdl_pairs_params
             :members:
         .. autofunction:: fiction.pyfiction.detect_bdl_pairs
+
+
+Assess Population Stability
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Header:** ``fiction/algorithms/simulation/sidb/assess_physical_population_stability.hpp``
+
+.. doxygenenum:: fiction::transition_type
+.. doxygenstruct:: fiction::population_stability_information
+   :members:
+.. doxygenstruct:: fiction::assess_physical_population_stability_params
+   :members:
+.. doxygenfunction:: fiction::assess_physical_population_stability
+
+
+Convert Potential to Distance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Header:** ``fiction/algorithms/simulation/sidb/convert_potential_to_distance.hpp``
+
+.. doxygenfunction:: fiction::convert_potential_to_distance

include/fiction/algorithms/simulation/sidb/convert_potential_to_distance.hpp

@@ -0,0 +1,64 @@
+//
+// Created by Jan Drewniok on 10.11.23.
+//
+
+#ifndef FICTION_CONVERT_POTENTIAL_TO_DISTANCE_HPP
+#define FICTION_CONVERT_POTENTIAL_TO_DISTANCE_HPP
+
+#include "fiction/algorithms/simulation/sidb/sidb_simulation_parameters.hpp"
+#include "fiction/technology/physical_constants.hpp"
+
+#include <cmath>
+#include <cstdint>
+#include <limits>
+#include <vector>
+
+namespace fiction
+{
+
+/**
+ * The electrostatic potential on hydrogen-passivated silicon is typically modeled using a screened Coulomb potential.
+ * This electrostatic potential is commonly employed to determine the electrostatic potential for a given distance
+ * (between SiDB and point under consideration) and given physical parameters. However, the function provided here
+ * serves the inverse purpose by calculating the distance for a given potential and given physical parameters.
+ *
+ * @note Runtime depends exponentially on the provided precision.
+ *
+ * @param params The physical parameters for a given hydrogen-passivated silicon surface.
+ * @param potential The electrostatic potential (unit: V) to be converted to a distance.
+ * @param precision The precision level for the conversion, specifying the number of decimal places.
+ * @return The distance (unit: nm) corresponding to the given electrostatic potential.
+ */
+[[nodiscard]] inline double
+convert_potential_to_distance(const double                      potential,
+                              const sidb_simulation_parameters& params    = sidb_simulation_parameters{},
+                              const uint64_t                    precision = 2) noexcept
+{
+    // function to calculate the electrostatic potential for a given distance and given physical parameters on the H-Si
+    // surface
+    const auto calculate_potential_for_given_distance = [&params](const double distance) noexcept
+    {
+        return params.k() * params.epsilon_r / params.epsilon_r / (distance * 1e-9) *
+               std::exp(-distance / params.lambda_tf) * physical_constants::ELEMENTARY_CHARGE;
+    };
+
+    // calculate the step size based on the precision
+    const double step_size = std::pow(10, -static_cast<double>(precision));
+
+    // initialize distance and potential for the initial step
+    double distance                     = step_size;
+    double potential_for_given_distance = calculate_potential_for_given_distance(distance);
+
+    // as long as the electrostatic potential is still larger than the given potential, the distance is increased
+    while (potential_for_given_distance > potential)
+    {
+        distance += step_size;
+        potential_for_given_distance = calculate_potential_for_given_distance(distance);
+    }
+
+    return distance;
+}
+
+}  // namespace fiction
+
+#endif  // FICTION_CONVERT_POTENTIAL_TO_DISTANCE_HPP

include/fiction/algorithms/simulation/sidb/operational_domain.hpp

@@ -871,7 +871,7 @@ class operational_domain_impl
         const auto decr_x = (x > 0) ? x - 1 : x;
         const auto incr_x = (x + 1 < x_indices.size()) ? x + 1 : x;
         const auto decr_y = (y > 0) ? y - 1 : y;
-        const auto incr_y = (y + 1 < x_indices.size()) ? y + 1 : y;
+        const auto incr_y = (y + 1 < y_indices.size()) ? y + 1 : y;
 
         // add neighbors in clockwise direction
 

include/fiction/algorithms/simulation/sidb/quickexact.hpp

@@ -86,7 +86,7 @@ class quickexact_impl
 {
   public:
     quickexact_impl(const Lyt& lyt, const quickexact_params<Lyt>& parameter) :
-            layout{lyt},
+            layout{lyt.clone()},
             charge_lyt{lyt},
             params{parameter}
     {
@@ -345,22 +345,14 @@ class quickexact_impl
 
             if (charge_layout.is_physically_valid())
             {
-                charge_distribution_surface<Lyt> charge_lyt_copy{charge_layout};
-                charge_lyt_copy.recompute_system_energy();
+                charge_distribution_surface<Lyt> charge_lyt_copy{charge_lyt};
 
-                // The pre-assigned negatively-charged SiDBs are added to the final layout.
-                for (const auto& cell : preassigned_negative_sidbs)
-                {
-                    charge_lyt_copy.add_sidb(cell, sidb_charge_state::NEGATIVE);
-                }
+                charge_layout.foreach_cell(
+                    [&charge_lyt_copy, &charge_layout](const auto& c)
+                    { charge_lyt_copy.assign_charge_state(c, charge_layout.get_charge_state(c)); });
 
-                if constexpr (has_get_sidb_defect_v<Lyt>)
-                {
-                    for (const auto& [cell, defect] : real_placed_defects)
-                    {
-                        charge_lyt_copy.assign_sidb_defect(cell, defect);
-                    }
-                }
+                charge_lyt_copy.update_after_charge_change();
+                charge_lyt_copy.recompute_system_energy();
                 result.charge_distributions.push_back(charge_lyt_copy);
             }
         }
@@ -398,23 +390,14 @@ class quickexact_impl
             {
                 if (charge_layout.is_physically_valid())
                 {
-                    charge_distribution_surface<Lyt> charge_lyt_copy{charge_layout};
-                    charge_lyt_copy.recompute_system_energy();
-
-                    // The pre-assigned negatively-charged SiDBs are added to the final layout.
-                    for (const auto& cell : preassigned_negative_sidbs)
-                    {
-                        charge_lyt_copy.add_sidb(cell, sidb_charge_state::NEGATIVE);
-                    }
+                    charge_distribution_surface<Lyt> charge_lyt_copy{charge_lyt};
 
-                    if constexpr (has_get_sidb_defect_v<Lyt>)
-                    {
-                        for (const auto& [cell, defect] : real_placed_defects)
-                        {
-                            charge_lyt_copy.assign_sidb_defect(cell, defect);
-                        }
-                    }
+                    charge_layout.foreach_cell(
+                        [&charge_lyt_copy, &charge_layout](const auto& c)
+                        { charge_lyt_copy.assign_charge_state(c, charge_layout.get_charge_state(c)); });
 
+                    charge_lyt_copy.update_after_charge_change();
+                    charge_lyt_copy.recompute_system_energy();
                     result.charge_distributions.push_back(charge_lyt_copy);
                 }
 
@@ -428,22 +411,14 @@ class quickexact_impl
 
             if (charge_layout.is_physically_valid())
             {
-                charge_distribution_surface<Lyt> charge_lyt_copy{charge_layout};
-                charge_lyt_copy.recompute_system_energy();
+                charge_distribution_surface<Lyt> charge_lyt_copy{charge_lyt};
 
-                for (const auto& cell : preassigned_negative_sidbs)
-                {
-                    charge_lyt_copy.add_sidb(cell, sidb_charge_state::NEGATIVE);
-                }
-
-                if constexpr (has_get_sidb_defect_v<Lyt>)
-                {
-                    for (const auto& [cell, defect] : real_placed_defects)
-                    {
-                        charge_lyt_copy.assign_sidb_defect(cell, defect);
-                    }
-                }
+                charge_layout.foreach_cell(
+                    [&charge_lyt_copy, &charge_layout](const auto& c)
+                    { charge_lyt_copy.assign_charge_state(c, charge_layout.get_charge_state(c)); });
 
+                charge_lyt_copy.update_after_charge_change();
+                charge_lyt_copy.recompute_system_energy();
                 result.charge_distributions.push_back(charge_lyt_copy);
             }
 
@@ -465,23 +440,15 @@ class quickexact_impl
         {
             if (charge_layout.is_physically_valid())
             {
-                charge_distribution_surface<Lyt> charge_lyt_copy{charge_layout};
-                charge_lyt_copy.recompute_system_energy();
+                charge_distribution_surface<Lyt> charge_lyt_copy{charge_lyt};
 
-                // The pre-assigned negatively-charged SiDBs are added to the final layout.
-                for (const auto& cell : preassigned_negative_sidbs)
-                {
-                    charge_lyt_copy.add_sidb(cell, sidb_charge_state::NEGATIVE);
-                }
-
-                if constexpr (has_get_sidb_defect_v<Lyt>)
-                {
-                    for (const auto& [cell, defect] : real_placed_defects)
-                    {
-                        charge_lyt_copy.assign_sidb_defect(cell, defect);
-                    }
-                }
+                charge_layout.foreach_cell(
+                    [&charge_lyt_copy, &charge_layout](const auto& c)
+                    { charge_lyt_copy.assign_charge_state(c, charge_layout.get_charge_state(c)); });
 
+                charge_lyt_copy.update_after_charge_change();
+                charge_lyt_copy.recompute_system_energy();
+                charge_lyt_copy.charge_distribution_to_index_general();
                 result.charge_distributions.push_back(charge_lyt_copy);
             }
 
@@ -492,21 +459,14 @@ class quickexact_impl
 
         if (charge_layout.is_physically_valid())
         {
-            charge_distribution_surface<Lyt> charge_lyt_copy{charge_layout};
+            charge_distribution_surface<Lyt> charge_lyt_copy{charge_lyt};
 
-            for (const auto& cell : preassigned_negative_sidbs)
-            {
-                charge_lyt_copy.add_sidb(cell, sidb_charge_state::NEGATIVE);
-            }
-
-            if constexpr (has_get_sidb_defect_v<Lyt>)
-            {
-                for (const auto& [cell, defect] : real_placed_defects)
-                {
-                    charge_lyt_copy.assign_sidb_defect(cell, defect);
-                }
-            }
+            charge_layout.foreach_cell([&charge_lyt_copy, &charge_layout](const auto& c)
+                                       { charge_lyt_copy.assign_charge_state(c, charge_layout.get_charge_state(c)); });
 
+            charge_lyt_copy.update_after_charge_change();
+            charge_lyt_copy.recompute_system_energy();
+            charge_lyt_copy.charge_distribution_to_index_general();
             result.charge_distributions.push_back(charge_lyt_copy);
         }
 

include/fiction/technology/charge_distribution_surface.hpp

@@ -1282,11 +1282,14 @@ class charge_distribution_surface<Lyt, false> : public Lyt
     void assign_global_external_potential(const double        potential_value,
                                           dependent_cell_mode dependent_cell = dependent_cell_mode::FIXED) noexcept
     {
-        this->foreach_cell(
-            [this, &potential_value](const auto& c) {
-                strg->local_external_pot.insert({c, potential_value});
-            });
-        this->update_after_charge_change(dependent_cell);
+        if (potential_value != 0.0)
+        {
+            this->foreach_cell(
+                [this, &potential_value](const auto& c) {
+                    strg->local_external_pot.insert({c, potential_value});
+                });
+            this->update_after_charge_change(dependent_cell);
+        }
     }
     /**
      * This function determines if given layout has to be simulated with three states since positively charged SiDBs can
@@ -1769,6 +1772,23 @@ class charge_distribution_surface<Lyt, false> : public Lyt
     {
         strg->cell_charge.push_back(charge);
         strg->sidb_order.push_back(c);
+
+        // sort sidbs by the relation given by the coordinates and sort charge vector accordingly
+        std::vector<std::pair<typename Lyt::cell, sidb_charge_state>> combined_vector{};
+        combined_vector.reserve(strg->cell_charge.size());
+
+        for (size_t i = 0; i < strg->sidb_order.size(); i++)
+        {
+            combined_vector.emplace_back(strg->sidb_order[i], strg->cell_charge[i]);
+        }
+
+        std::sort(combined_vector.begin(), combined_vector.end());
+
+        for (size_t i = 0; i < combined_vector.size(); i++)
+        {
+            strg->sidb_order[i]  = combined_vector[i].first;
+            strg->cell_charge[i] = combined_vector[i].second;
+        }
     }
 
   private: