docs(ridfire)

Added more documentation, also moved all engine code into
gridfire::engine namespace to be more in line with other parts of teh
code base

src/include/gridfire/utils/formatters/formatters.h

@@ -0,0 +1,3 @@
+#pragma once
+
+#include "gridfire/utils/formatters/jacobian_format.h"

src/include/gridfire/utils/formatters/jacobian_format.h

@@ -0,0 +1,24 @@
+#pragma once
+
+#include <format>
+
+#include "gridfire/engine/types/jacobian.h"
+
+
+
+template <>
+struct std::formatter<gridfire::engine::NetworkJacobian> {
+    static constexpr auto parse(const std::format_parse_context& ctx) {
+        return ctx.begin();
+    }
+
+    static auto format(const gridfire::engine::NetworkJacobian& obj, std::format_context& ctx) {
+        return std::format_to(ctx.out(), "NetworkJacobian(shape=({}, {}), nnz={}, rank={}, singular={})",
+            std::get<0>(obj.shape()),
+            std::get<1>(obj.shape()),
+            obj.nnz(),
+            obj.rank(),
+            obj.singular() ? "True" : "False"
+        );
+    }
+};

src/include/gridfire/utils/logging.h

@@ -4,6 +4,7 @@
 #include "fourdst/composition/composition.h"
 
 #include <string>
+#include <functional>
 
 namespace gridfire::utils {
     /**
@@ -57,11 +58,46 @@ namespace gridfire::utils {
      * @endcode
      */
     std::string formatNuclearTimescaleLogString(
-        const DynamicEngine& engine,
+        const engine::DynamicEngine& engine,
         const fourdst::composition::Composition& composition,
         double T9,
         double rho
     );
 
+    template <typename T>
+    concept Streamable = requires(std::ostream& os, const T& value) {
+            { os << value } -> std::same_as<std::ostream&>;
+    };
+
+    template <
+        std::ranges::input_range Container,
+        typename Elem = std::ranges::range_reference_t<Container>,
+        typename Transform = std::identity,
+        typename Pred = bool(*)(const std::ranges::range_value_t<Container>&)
+    >
+    requires std::invocable<Transform, Elem> && Streamable<std::invoke_result_t<Transform, Elem>> && std::predicate<Pred, Elem>
+    static std::string iterable_to_delimited_string(
+        const Container& container,
+        const std::string_view delimiter = ", ",
+        Transform transform = {},
+        Pred pred = [](const auto&){ return true; }
+    ) noexcept {
+        std::ostringstream oss;
+        bool first = true;
+        for (auto&& item : container) {
+            if (!std::invoke(pred, item)) {
+                continue;
+            }
+            if (!first) {
+                oss << delimiter;
+            }
+            oss << std::invoke(transform, item);
+            first = false;
+        }
+        return oss.str();
+    }
+
+
+
 
 }

src/include/gridfire/utils/sundials.h

@@ -6,7 +6,11 @@
 #include "sundials/sundials_nvector.h"
 
 namespace gridfire::utils {
-    inline std::unordered_map<int, std::string> cvode_ret_code_map {
+    enum class SUNDIALS_RET_CODE_TYPES {
+        CVODE,
+        KINSOL
+    };
+    static inline std::unordered_map<int, std::string> cvode_ret_code_map {
         {0, "CV_SUCCESS: The solver succeeded."},
         {1, "CV_TSTOP_RETURN: The solver reached the specified stopping time."},
         {2, "CV_ROOT_RETURN: A root was found."},
@@ -40,6 +44,35 @@ namespace gridfire::utils {
         {-30, "CV_PROJFUNC_FAIL: The projection function failed in an unrecoverable manner."},
         {-31, "CV_REPTD_PROJFUNC_ERR: The projection function has repeated recoverable errors."}
     };
+    static inline std::unordered_map<int, std::string> kinsol_ret_code_map {
+        {0, "KIN_SUCCESS: The solver succeeded."},
+        {1, "KIN_STEP_LT_STPTOL: The solver step size became less than the stopping tolerance."},
+        {2, "KIN_RES_REPTD_ERR: The residual function repeatedly failed recoverably."},
+        {-1, "KIN_MEM_NULL: The KINSOL memory structure is NULL."},
+        {-2, "KIN_ILL_INPUT: An illegal input was detected."},
+        {-3, "KIN_NO_MALLOC: The KINSOL memory structure has not been allocated."},
+        {-4, "KIN_MEM_FAIL: Memory allocation failed."},
+        {-5, "KIN_LINIT_FAIL: The linear solver's initialization function failed."},
+        {-6, "KIN_LSETUP_FAIL: The linear solver's setup function failed."},
+        {-7, "KIN_LSOLVE_FAIL: The linear solver's solve function failed."},
+        {-8, "KIN_RESFUNC_FAIL: The residual function failed in an unrecoverable manner."},
+        {-9, "KIN_CONSTR_FAIL: The inequality constraint was violated and the solver was unable to recover."},
+        {-10, "KIN_NLS_INIT_FAIL: The nonlinear solver's initialization function failed."},
+        {-11, "KIN_NLS_SETUP_FAIL: The nonlinear solver's setup function failed."},
+        {-12, "KIN_NLS_FAIL: The nonlinear solver's solve function failed."}
+    };
+
+    inline const std::unordered_map<int, std::string>& sundials_retcode_map(const SUNDIALS_RET_CODE_TYPES type) {
+        switch (type) {
+            case SUNDIALS_RET_CODE_TYPES::CVODE:
+                return cvode_ret_code_map;
+            case SUNDIALS_RET_CODE_TYPES::KINSOL:
+                return kinsol_ret_code_map;
+            default:
+                throw exceptions::CVODESolverFailureError("Unknown SUNDIALS return code type.");
+        }
+
+    }
 
     inline void check_cvode_flag(const int flag, const std::string& func_name) {
         if (flag < 0) {

src/include/gridfire/utils/table_format.h

@@ -1,6 +1,5 @@
 #pragma once
 
-#include <iostream>
 #include <utility>
 #include <vector>
 #include <string>
@@ -9,11 +8,10 @@
 #include <algorithm>
 #include <numeric>
 #include <memory>
-#include <format>
 #include <print>
-#include <cstdlib>
 #include <cwchar>
-#include <clocale>
+
+#include "nlohmann/json.hpp"
 
 
 
@@ -23,15 +21,15 @@ namespace gridfire::utils {
         // for mbtowc and wcwidth to function correctly with the system's locale.
 
         size_t width = 0;
-        std::mbtowc(nullptr, 0, 0); // Reset multi-byte state
+        std::mbtowc(nullptr, nullptr, 0); // Reset multi-byte state
 
         const char* p = s.c_str();
         const char* end = s.c_str() + s.length();
 
         while (p < end) {
             wchar_t wc;
-            // Convert the next multi-byte char to a wide char
-            int byte_len = std::mbtowc(&wc, p, end - p);
+            // Convert the next multibyte char to a wide char
+            const int byte_len = std::mbtowc(&wc, p, end - p);
 
             if (byte_len <= 0) {
                 // Invalid byte sequence or null char.
@@ -387,4 +385,33 @@ namespace gridfire::utils {
     }
 
 
+    inline nlohmann::json to_json(const std::vector<std::unique_ptr<ColumnBase>>& columns) {
+        using json = nlohmann::json;
+        json j;
+        for (const auto& col : columns) {
+            std::vector<std::string> col_data;
+            const size_t row_count = col->getRowCount();
+            for (size_t i = 0; i < row_count; ++i) {
+                col_data.push_back(col->getCellData(i));
+            }
+            j[col->getHeader()] = col_data;
+        }
+        return j;
+    }
+
+    inline void to_json_file(const std::string& filename, const std::vector<std::vector<std::unique_ptr<ColumnBase>>> &tables, const std::vector<std::string>& tableNames) {
+        using json = nlohmann::json;
+        json j;
+        for (size_t t = 0; t < tables.size(); ++t) {
+            j[tableNames[t]] = to_json(tables[t]);
+        }
+        std::ofstream output(filename);
+        if (!output.is_open()) {
+            throw std::runtime_error("Failed to open file for writing: " + filename);
+        }
+        output << j.dump(4);
+        output.close();
+    }
+
+
 }

src/include/gridfire/utils/utils.h

@@ -0,0 +1,7 @@
+#pragma once
+
+#include "gridfire/utils/formatters/formatters.h"
+#include "gridfire/utils/hashing.h"
+#include "gridfire/utils/logging.h"
+#include "gridfire/utils/sundials.h"
+#include "gridfire/utils/table_format.h"