✨ Added an SiDB simulation file writer

docs/algorithms/sidb_simulation.rst

@@ -8,13 +8,21 @@ are a crucial step in the physical design flow of SiDB layouts, as they are used
 Physical Parameters
 ###################
 
-
 **Header:** ``fiction/algorithms/simulation/sidb/sidb_simulation_parameters.hpp``
 
 .. doxygenstruct:: fiction::sidb_simulation_parameters
    :members:
 
 
+Simulation Result
+#################
+
+**Header:** ``fiction/algorithms/simulation/sidb/sidb_simulation_result.hpp``
+
+.. doxygenstruct:: fiction::sidb_simulation_result
+   :members:
+
+
 Heuristic Ground State Simulation
 #################################
 
@@ -31,7 +39,6 @@ Heuristic Ground State Simulation
 Exhaustive Ground State Simulation
 ##################################
 
-
 **Header:** ``fiction/algorithms/simulation/sidb/exhaustive_ground_state_simulation.hpp``
 
 .. doxygenfunction:: fiction::exhaustive_ground_state_simulation

docs/io/physical_simulation.rst

@@ -59,6 +59,11 @@ SiQAD
 .. doxygenfunction:: fiction::write_sqd_layout(const Lyt& lyt, std::ostream& os)
 .. doxygenfunction:: fiction::write_sqd_layout(const Lyt& lyt, const std::string_view& filename)
 
+**Header:** ``fiction/io/write_sqd_sim_result.hpp``
+
+.. doxygenfunction:: fiction::write_sqd_sim_result(const sidb_simulation_result<Lyt>& sim_result, std::ostream& os)
+.. doxygenfunction:: fiction::write_sqd_sim_result(const sidb_simulation_result<Lyt>& sim_result, const std::string_view& filename)
+
 **Header:** ``fiction/io/read_sqd_layout.hpp``
 
 .. doxygenfunction:: fiction::read_sqd_layout(std::istream& is, const std::string_view& name = "")

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

@@ -0,0 +1,67 @@
+//
+// Created by marcel on 05.04.23.
+//
+
+#ifndef FICTION_SIDB_SIMULATION_RESULT_HPP
+#define FICTION_SIDB_SIMULATION_RESULT_HPP
+
+#include "fiction/algorithms/simulation/sidb/sidb_simulation_parameters.hpp"
+#include "fiction/technology/charge_distribution_surface.hpp"
+
+#include <any>
+#include <chrono>
+#include <cstdint>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace fiction
+{
+
+/**
+ * This struct defines a unified return type for all SiDB simulation algorithms. It contains the name of the algorithm,
+ * the total simulation runtime, the charge distributions determined by the algorithm, the physical parameters used in
+ * the simulation, and (optional) algorithm-specific named simulation parameters.
+ *
+ * @tparam Lyt Cell-level layout type.
+ */
+template <typename Lyt>
+struct sidb_simulation_result
+{
+    /**
+     * Default constructor. It only exists to allow for the use of `static_assert` statements that restrict the type of
+     * `Lyt`.
+     */
+    sidb_simulation_result() noexcept
+    {
+        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");
+    }
+    /**
+     * Name of the algorithm used to determine the charge distributions.
+     */
+    std::string algorithm_name{};
+    /**
+     * Total simulation runtime.
+     */
+    std::chrono::duration<double> simulation_runtime{};
+    /**
+     * Charge distributions determined by the algorithm.
+     */
+    std::vector<charge_distribution_surface<Lyt>> charge_distributions{};
+    /**
+     * Physical parameters used in the simulation.
+     */
+    sidb_simulation_parameters physical_parameters{};
+    /**
+     * Additional named simulation parameters. This is used to store algorithm-dependent parameters that are not part of
+     * the `physical_parameters` struct.
+     *
+     * The first element of the pair is the name of the parameter, the second element is the value of the parameter.
+     */
+    std::vector<std::pair<std::string, std::any>> additional_simulation_parameters{};
+};
+
+}  // namespace fiction
+
+#endif  // FICTION_SIMULATION_RESULT_HPP

include/fiction/io/write_sqd_layout.hpp

@@ -31,7 +31,7 @@ namespace detail
 namespace siqad
 {
 
-inline constexpr const char* XML_HEADER    = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
+inline constexpr const char* SQD_HEADER    = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
 inline constexpr const char* OPEN_SIQAD    = "<siqad>\n";
 inline constexpr const char* CLOSE_SIQAD   = "</siqad>\n";
 inline constexpr const char* PROGRAM_BLOCK = "    <program>\n"
@@ -168,7 +168,7 @@ class write_sqd_layout_impl
     {
         std::stringstream header{}, gui{}, design{};
 
-        header << siqad::XML_HEADER << siqad::OPEN_SIQAD;
+        header << siqad::SQD_HEADER << siqad::OPEN_SIQAD;
 
         const auto time_str = fmt::format("{:%Y-%m-%d %H:%M:%S}", fmt::localtime(std::time(nullptr)));
 
@@ -293,7 +293,7 @@ class write_sqd_layout_impl
  * Writes a cell-level SiDB or QCA layout to an sqd file that is used by SiQAD (https://github.com/siqad/siqad),
  * a physical simulator for the SiDB technology platform.
  *
- * If The provided cell-level layout type can represent SiDB defects, they will be written to the file as well.
+ * If the provided cell-level layout type can represent SiDB defects, they will be written to the file as well.
  *
  * This overload uses an output stream to write into.
  *
@@ -315,9 +315,9 @@ void write_sqd_layout(const Lyt& lyt, std::ostream& os)
  * Writes a cell-level SiDB or QCA layout to an sqd file that is used by SiQAD (https://github.com/siqad/siqad),
  * a physical simulator for the SiDB technology platform.
  *
- * If The provided cell-level layout type can represent SiDB defects, they will be written to the file as well.
+ * If the provided cell-level layout type can represent SiDB defects, they will be written to the file as well.
  *
- * This overload uses file name to create and write into.
+ * This overload uses a file name to create and write into.
  *
  * @tparam Lyt Cell-level SiDB or QCA layout type.
  * @param lyt The layout to be written.