🎨 implement Marcel's suggestions.

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

@@ -95,7 +95,7 @@ struct critical_temperature_params
      */
     double confidence_level{0.99};
     /**
-     * Simulation stops at max_temperature (~ 126 °C by default).
+     * Simulation stops at max_temperature (~ 126 °C by default) (unit: K).
      */
     double max_temperature{400};
     /**
@@ -326,7 +326,7 @@ class critical_temperature_impl
                 (first_excited_state_energy - ground_state_energy) * 1000;
         }
 
-        std::vector<double> temp_values{};
+        std::vector<double> temp_values{};  // unit: K
         temp_values.reserve(static_cast<uint64_t>(parameter.max_temperature * 100));
 
         for (uint64_t i = 1; i <= static_cast<uint64_t>(parameter.max_temperature * 100); i++)
@@ -363,7 +363,7 @@ class critical_temperature_impl
      *
      * @param energy_and_state_type All energies of all physically valid charge distributions with the corresponding
      * state type (i.e. transparent, erroneous).
-     * @param min_energy Minimal energy of all physically valid charge distributions of a given layout.
+     * @param min_energy Minimal energy of all physically valid charge distributions of a given layout (unit: eV).
      * @return State type (i.e. transparent, erroneous) of the ground state is returned.
      */
     bool energy_between_ground_state_and_first_erroneous(const sidb_energy_and_state_type& energy_and_state_type,

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

@@ -17,10 +17,10 @@ namespace fiction
 {
 
 /**
- *  Data type to collect electrostatic potential energies of charge distributions with corresponding degeneracy (i.e.
- * how often a certain energy value occurs).
+ * Data type to collect electrostatic potential energies (unit: eV) of charge distributions with corresponding
+ * degeneracy (i.e. how often a certain energy value occurs).
  */
-using sidb_energy_distribution = std::map<double, uint64_t>;
+using sidb_energy_distribution = std::map<double, uint64_t>;  // unit: (eV, unitless)
 
 /**
  * This function takes in a vector of charge_distribution_surface objects and returns a map containing the system energy
@@ -38,7 +38,7 @@ energy_distribution(const std::vector<charge_distribution_surface<Lyt>>& input_v
     static_assert(is_cell_level_layout_v<Lyt>, "Lyt is not a cell-level layout");
     static_assert(has_sidb_technology_v<Lyt>, "Lyt is not an SiDB layout");
 
-    std::map<double, uint64_t> distribution{};
+    std::map<double, uint64_t> distribution{};  // unit: (eV, unitless)
 
     for (const auto& lyt : input_vec)
     {

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

@@ -39,7 +39,7 @@ namespace fiction
         return 0.0;
     }
 
-    auto min_energy = std::numeric_limits<double>::infinity();
+    auto min_energy = std::numeric_limits<double>::infinity();  // unit: eV
 
     // Determine the minimal energy.
     const auto [energy, state_type] = *std::min_element(energy_and_state_type.cbegin(), energy_and_state_type.cend(),
@@ -71,8 +71,8 @@ namespace fiction
  * This function computes the occupation probability of excited states (charge distributions with energy higher than the
  * ground state) at a given temperature.
  *
- * @param energy_distribution This contains the energies of all possible charge distributions with the degeneracy.
- * @param temperature System temperature to assume.
+ * @param energy_distribution This contains the energies in eV of all possible charge distributions with the degeneracy.
+ * @param temperature System temperature to assume (unit: K).
  * @return The total occupation probability of all excited states is returned.
  */
 [[nodiscard]] inline double occupation_probability_non_gate_based(const sidb_energy_distribution& energy_distribution,
@@ -88,7 +88,7 @@ namespace fiction
     auto min_energy = std::numeric_limits<double>::infinity();
 
     const auto& [energy, degeneracy] = *(energy_distribution.begin());
-    min_energy                       = energy;
+    min_energy                       = energy;  // unit: eV
 
     // The partition function is obtained by summing up all the Boltzmann factors.
     const double partition_function =

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

@@ -24,7 +24,7 @@ struct sidb_simulation_parameters
      *
      * @param base_number simulation can be conducted with 2 and 3 charge states. 2 = (Negative, Neutral), 3 =
      * (Negative, Neutral, Positive).
-     * @param mu_minus it is the energy transition level (0/-).
+     * @param mu_minus it is the energy transition level (0/-) in eV.
      * @param relative_permittivity it describes the electric field reduction due to polarization.
      * @param screening_distance also known as "Thomas-Fermi screening" and it describes the electric field screening
      * due to free charges in nm.

include/fiction/technology/charge_distribution_surface.hpp

@@ -59,15 +59,15 @@ class charge_distribution_surface<Lyt, false> : public Lyt
     {
       private:
         /**
-         * The distance matrix is a vector of vectors storing the euclidean distance.
+         * The distance matrix is a vector of vectors storing the euclidean distance in nm.
          */
         using distance_matrix = std::vector<std::vector<double>>;
         /**
-         * The potential matrix is a vector of vectors storing the electrostatic potentials.
+         * The potential matrix is a vector of vectors storing the chargless electrostatic potentials in Volt (V).
          */
         using potential_matrix = std::vector<std::vector<double>>;
         /**
-         * It is a vector that stores the local electrostatic potential.
+         * It is a vector that stores the local electrostatic potential in Volt (V).
          */
         using local_potential = std::vector<double>;
 
@@ -446,6 +446,22 @@ class charge_distribution_surface<Lyt, false> : public Lyt
                 std::exp(-strg->nm_dist_mat[index1][index2] / strg->phys_params.lambda_tf) *
                 physical_constants::ELEMENTARY_CHARGE);
     }
+    /**
+     * Calculates and returns the chargeless potential of a pair of cells based on their distance and simulation
+     * parameters.
+     *
+     * @param c1 The first cell.
+     * @param c2 The second cell.
+     * @return The potential between c1 and c2 (unit: eV).
+     */
+    [[nodiscard]] double chargeless_potential_between_sidbs(const typename Lyt::cell& c1,
+                                                            const typename Lyt::cell& c2) const noexcept
+    {
+        const auto index1 = static_cast<std::size_t>(cell_to_index(c1));
+        const auto index2 = static_cast<std::size_t>(cell_to_index(c2));
+
+        return chargeless_potential_between_sidbs_by_index(index1, index2);
+    }
     /**
      * Returns the chargeless electrostatic potential between two cells.
      *
@@ -454,7 +470,7 @@ class charge_distribution_surface<Lyt, false> : public Lyt
      *
      * @param c1 The first cell.
      * @param c2 The second cell.
-     * @return The chargeless electrostatic potential between `c1` and `c2`, i.e, \f$ \frac{V_{i,j}}{n_j} \f$.
+     * @return The chargeless electrostatic potential between `c1` and `c2`, i.e, \f$ \frac{V_{i,j}}{n_j} \f$ (unit: V).
      */
     [[nodiscard]] double get_chargeless_potential_between_sidbs(const typename Lyt::cell& c1,
                                                                 const typename Lyt::cell& c2) const noexcept
@@ -466,6 +482,17 @@ class charge_distribution_surface<Lyt, false> : public Lyt
 
         return 0.0;
     }
+    /**
+     * Calculates and returns the potential of two indices.
+     *
+     * @param index1 The first index.
+     * @param index2 The second index.
+     * @return The potential between `index1` and `index2` (unit: V).
+     */
+    [[nodiscard]] double get_chargless_potential_by_indices(const uint64_t index1, const uint64_t index2) const noexcept
+    {
+        return strg->pot_mat[index1][index2];
+    }
     /**
      * Calculates and returns the electrostatic potential at one cell (`c1`) generated by another cell (`c2`).
      *
@@ -474,7 +501,7 @@ class charge_distribution_surface<Lyt, false> : public Lyt
      *
      * @param c1 The first cell.
      * @param c2 The second cell.
-     * @return The electrostatic potential between `c1` and `c2`, i.e., \f$ V_{i,j} \f$.
+     * @return The electrostatic potential between `c1` and `c2`, i.e., \f$ V_{i,j} \f$ (unit: V).
      */
     [[nodiscard]] double get_potential_between_sidbs(const typename Lyt::cell& c1,
                                                      const typename Lyt::cell& c2) const noexcept
@@ -487,33 +514,6 @@ class charge_distribution_surface<Lyt, false> : public Lyt
 
         return 0.0;
     }
-    /**
-     * Calculates and returns the potential of two indices.
-     *
-     * @param index1 The first index.
-     * @param index2 The second index.
-     * @return The potential between `index1` and `index2`.
-     */
-    [[nodiscard]] double get_electrostatic_potential_by_indices(const uint64_t index1,
-                                                                const uint64_t index2) const noexcept
-    {
-        return strg->pot_mat[index1][index2];
-    }
-    /**
-     * Calculates and returns the potential of a pair of cells based on their distance and simulation parameters.
-     *
-     * @param c1 The first cell.
-     * @param c2 The second cell.
-     * @return The potential between c1 and c2.
-     */
-    [[nodiscard]] double potential_between_sidbs(const typename Lyt::cell& c1,
-                                                 const typename Lyt::cell& c2) const noexcept
-    {
-        const auto index1 = static_cast<std::size_t>(cell_to_index(c1));
-        const auto index2 = static_cast<std::size_t>(cell_to_index(c2));
-
-        return chargeless_potential_between_sidbs_by_index(index1, index2);
-    }
     /**
      * The function calculates the electrostatic potential for each SiDB position (local).
      */
@@ -533,11 +533,11 @@ class charge_distribution_surface<Lyt, false> : public Lyt
         }
     }
     /**
-     * The function returns the local electrostatic potential at a given SiDB position.
+     * The function returns the local electrostatic potential at a given SiDB position in V.
      *
      * @param c The cell defining the SiDB position.
      * @return Local potential at given cell position. If there is no SiDB at the given cell, `std::nullopt` is
-     * returned.
+     * returned (unit: V).
      */
     std::optional<double> get_local_potential(const typename Lyt::cell& c) const noexcept
     {
@@ -549,11 +549,11 @@ class charge_distribution_surface<Lyt, false> : public Lyt
         return std::nullopt;
     }
     /**
-     * The function returns the local electrostatic potential at a given index position.
+     * The function returns the local electrostatic potential at a given index position in V.
      *
      * @param index The index defining the SiDB position.
      * @return local potential at given index position. If there is no SiDB at the given index (which corresponds to a
-     * unique cell), `std::nullopt` is returned.
+     * unique cell), `std::nullopt` is returned (unit: V).
      */
     [[nodiscard]] std::optional<double> get_local_potential_by_index(const uint64_t index) const noexcept
     {
@@ -584,9 +584,9 @@ class charge_distribution_surface<Lyt, false> : public Lyt
         strg->system_energy = total_potential;
     }
     /**
-     * Return the currently stored system's total electrostatic potential energy.
+     * Return the currently stored system's total electrostatic potential energy in eV.
      *
-     * @return The system's total electrostatic potential energy.
+     * @return The system's total electrostatic potential energy (unit: eV).
      */
     [[nodiscard]] double get_system_energy() const noexcept
     {
@@ -828,7 +828,7 @@ class charge_distribution_surface<Lyt, false> : public Lyt
 
             for (uint64_t i = 0u; i < strg->pot_mat.size(); ++i)
             {
-                strg->loc_pot[i] += -(this->get_electrostatic_potential_by_indices(i, random_element));
+                strg->loc_pot[i] += -(this->get_chargless_potential_by_indices(i, random_element));
             }
         }
     }

include/fiction/technology/sidb_defects.hpp

@@ -48,9 +48,9 @@ struct sidb_defect
     /**
      * Standard constructor.
      */
-    constexpr explicit sidb_defect(const sidb_defect_type defect_type = sidb_defect_type::UNKNOWN,
-                                   const int64_t electric_charge = 0.0, const double relative_permittivity = 0.0,
-                                   const double screening_distance = 0.0) noexcept :
+    explicit sidb_defect(const sidb_defect_type defect_type = sidb_defect_type::UNKNOWN,
+                         const int64_t electric_charge = 0.0, const double relative_permittivity = 0.0,
+                         const double screening_distance = 0.0) noexcept :
             type{defect_type},
             charge{electric_charge},
             epsilon_r{relative_permittivity},
@@ -66,11 +66,11 @@ struct sidb_defect
      */
     const sidb_defect_type type;
     /**
-     * Electrical charge in units of the elementary charge e (e.g., 1*e, -2*e).
+     * Electrical charge in units of the elementary charge e (e.g., 1 ^= 1*e, -2 ^= -2*e).
      */
     const int64_t charge;
     /**
-     * Electric permittivity.
+     * Electric permittivity (unitless).
      */
     const double epsilon_r;
     /**

include/fiction/utils/math_utils.hpp

@@ -14,8 +14,7 @@ namespace fiction
 {
 
 /**
- * Rounds a number to a specified number of decimal
- * places.
+ * Rounds a number to a specified number of decimal places.
  *
  * @tparam T The type of the number to round.
  * @param number The number to round.

test/technology/charge_distribution_surface.cpp

@@ -124,12 +124,13 @@ TEMPLATE_TEST_CASE(
         charge_layout.set_all_charge_states(sidb_charge_state::POSITIVE);
 
         // calculate potential between two sidbs (charge sign not included)
-        CHECK(charge_layout.potential_between_sidbs({5, 4}, {5, 5}) > 0.0);
-        CHECK_THAT(charge_layout.potential_between_sidbs({5, 4}, {5, 4}), Catch::Matchers::WithinAbs(0.0, 0.00001));
-        CHECK(charge_layout.potential_between_sidbs({5, 4}, {5, 6}) > 0);
-        CHECK(charge_layout.potential_between_sidbs({5, 5}, {5, 6}) > 0);
-        CHECK_THAT(charge_layout.potential_between_sidbs({5, 6}, {5, 5}) -
-                       charge_layout.potential_between_sidbs({5, 5}, {5, 6}),
+        CHECK(charge_layout.chargeless_potential_between_sidbs({5, 4}, {5, 5}) > 0.0);
+        CHECK_THAT(charge_layout.chargeless_potential_between_sidbs({5, 4}, {5, 4}),
+                   Catch::Matchers::WithinAbs(0.0, 0.00001));
+        CHECK(charge_layout.chargeless_potential_between_sidbs({5, 4}, {5, 6}) > 0);
+        CHECK(charge_layout.chargeless_potential_between_sidbs({5, 5}, {5, 6}) > 0);
+        CHECK_THAT(charge_layout.chargeless_potential_between_sidbs({5, 6}, {5, 5}) -
+                       charge_layout.chargeless_potential_between_sidbs({5, 5}, {5, 6}),
                    Catch::Matchers::WithinAbs(0.0, 0.00001));
         // read SiDBs' charge states
         CHECK(charge_layout.get_charge_state({5, 4}) == sidb_charge_state::POSITIVE);