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/exceptions/error_debug.h

@@ -2,10 +2,25 @@
 
 #include <source_location>
 #include <string>
+#include <format>
 
 #include "gridfire/exceptions/error_gridfire.h"
 
 namespace gridfire::exceptions {
+    /**
+     * @brief Exception class for debug-only errors.
+     *
+     * This exception is intended to be used for errors that should only
+     * occur during development and debugging. In release builds, attempts
+     * to throw this exception will result in a compilation error.
+     *
+     * Example usage:
+     * @code
+     * if (debug_condition_failed) {
+     *     throw DebugException("Debug condition failed");
+     * }
+     * @endcode
+     */
     class DebugException final : public GridFireError{
     public:
     #ifdef NDEBUG

src/include/gridfire/exceptions/error_engine.h

@@ -3,46 +3,116 @@
 #include "gridfire/exceptions/error_gridfire.h"
 
 namespace gridfire::exceptions {
+    /**
+     * @brief Base class for engine-related exceptions.
+     *
+     * This class serves as the base for all exceptions specific to the
+     * reaction network engine in the GridFire library. It extends the
+     * GridFireError class and allows for custom error messages related
+     * to engine operations.
+     */
     class EngineError : public GridFireError {
         using GridFireError::GridFireError;
     };
 
+    /**
+     * @brief Exception for failures in partitioning the engine.
+     *
+     * This exception is thrown when the engine fails to partition
+     * the reaction network as required for certain calculations or
+     * optimizations.
+     */
     class FailedToPartitionEngineError final : public EngineError {
         using EngineError::EngineError;
     };
 
+    /**
+     * @brief Exception for errors during network resizing.
+     *
+     * This exception is thrown when the engine encounters an error
+     * while attempting to resize the reaction network, such as when
+     * adding or removing species or reactions.
+     */
     class NetworkResizedError final : public EngineError {
         using EngineError::EngineError;
     };
 
+    /**
+     * @brief Exception for failures in setting network reactions.
+     *
+     * This exception is thrown when the engine fails to properly
+     * set or initialize the reactions in the reaction network.
+     */
     class UnableToSetNetworkReactionsError final : public EngineError {
         using EngineError::EngineError;
     };
 
+    /**
+     * @brief Exception for invalid composition collection in the engine.
+     *
+     * This exception is thrown when the engine encounters an
+     * invalid state while trying to collect the composition from the entire engine stack
+     */
     class BadCollectionError final : public EngineError {
         using EngineError::EngineError;
     };
 
+    /**
+     * @brief Exception for invalid QSE solution in the engine.
+     *
+     * This exception is thrown when the engine computes an
+     * invalid solution while performing Quasi-Statistical Equilibrium (QSE) calculations.
+     */
     class InvalidQSESolutionError final : public EngineError {
         using EngineError::EngineError;
     };
 
+    /**
+     * @brief Exception for errors in calculating the right-hand side (RHS).
+     *
+     * This exception is thrown when the engine encounters an error
+     * while calculating the right-hand side of the reaction network equations.
+     */
     class BadRHSEngineError final : public EngineError {
         using EngineError::EngineError;
     };
 
+    /**
+     * @brief Base class for Jacobian-related exceptions.
+     *
+     * This class serves as the base for all exceptions specific to
+     * Jacobian matrix operations in the reaction network engine.
+     */
     class JacobianError : public EngineError {
         using EngineError::EngineError;
     };
 
+    /**
+     * @brief Exception for stale Jacobian matrix access.
+     *
+     * This exception is thrown when an attempt is made to access
+     * a Jacobian matrix that is stale and needs to be regenerated.
+     */
     class StaleJacobianError final : public JacobianError {
         using JacobianError::JacobianError;
     };
 
+    /**
+     * @brief Exception for uninitialized Jacobian matrix access.
+     *
+     * This exception is thrown when an attempt is made to access
+     * a Jacobian matrix that has not been initialized.
+     */
     class UninitializedJacobianError final: public JacobianError {
         using JacobianError::JacobianError;
     };
 
+    /**
+     * @brief Exception for unknown Jacobian matrix access.
+     *
+     * This exception is thrown when an attempt is made to access
+     * a Jacobian matrix that is unknown or not recognized by the engine.
+     */
     class UnknownJacobianError final : public JacobianError {
         using JacobianError::JacobianError;
     };

src/include/gridfire/exceptions/error_gridfire.h

@@ -4,6 +4,12 @@
 #include <string>
 
 namespace gridfire::exceptions {
+    /**
+     * @brief Base class for GridFire exceptions.
+     *
+     * This class serves as the base for all exceptions specific to the GridFire library.
+     * It extends the standard std::exception class and allows for custom error messages.
+     */
     class GridFireError : public std::exception {
     public:
         explicit GridFireError(std::string msg) : m_msg(std::move(msg)) {}

src/include/gridfire/exceptions/error_reaction.h

@@ -6,6 +6,13 @@
 #include "gridfire/exceptions/error_gridfire.h"
 
 namespace gridfire::exceptions {
+    /**
+     * @class ReactionError
+     * @brief Base class for all exceptions related to reaction operations.
+     *
+     * This exception is the parent for more specific reaction-related errors. Catching this
+     * type will catch any exception originating from reaction handling.
+     */
     class ReactionError : public GridFireError {
     private:
         std::string m_message;

src/include/gridfire/exceptions/error_solver.h

@@ -3,26 +3,68 @@
 #include "gridfire/exceptions/error_gridfire.h"
 
 namespace gridfire::exceptions {
+    /**
+     * @class SolverError
+     * @brief Base class for all exceptions related to solver operations.
+     *
+     * This exception is the parent for more specific solver-related errors. Catching this
+     * type will catch any exception originating from the solver system.
+     */
     class SolverError : public GridFireError {
         using GridFireError::GridFireError;
     };
 
+    /**
+     * @class SingularJacobianError
+     * @brief Exception thrown when the Jacobian matrix is singular.
+     *
+     * This exception is thrown when the solver encounters a singular Jacobian matrix,
+     * which prevents it from proceeding with the solution of the system.
+     */
     class SingularJacobianError final : public SolverError {
         using SolverError::SolverError;
     };
 
+    /**
+     * @class IllConditionedJacobianError
+     * @brief Exception thrown when the Jacobian matrix is ill-conditioned.
+     *
+     * This exception is thrown when the solver detects that the Jacobian matrix
+     * is ill-conditioned, which may lead to inaccurate or unstable solutions.
+     */
     class IllConditionedJacobianError final : public SolverError {
         using SolverError::SolverError;
     };
 
+    /**
+     * @class SUNDIALSError
+     * @brief Base class for exceptions related to SUNDIALS solver operations.
+     *
+     * This class serves as the base for all exceptions specific to
+     * SUNDIALS solver errors in the GridFire library.
+     */
     class SUNDIALSError : public SolverError {
         using SolverError::SolverError;
     };
 
+    /**
+     * @class CVODESolverFailureError
+     * @brief Exception for failures in the CVODE solver.
+     *
+     * This exception is thrown when the CVODE solver from the SUNDIALS suite
+     * encounters a failure during its operation.
+     */
     class CVODESolverFailureError final : public SUNDIALSError {
         using SUNDIALSError::SUNDIALSError;
     };
 
+    /**
+     * @class KINSolSolverFailureError
+     * @brief Exception for failures in the KINSOL solver.
+     *
+     * This exception is thrown when the KINSOL solver from the SUNDIALS suite
+     * encounters a failure during its operation.
+     */
     class KINSolSolverFailureError final : public SUNDIALSError {
         using SUNDIALSError::SUNDIALSError;
     };

src/include/gridfire/exceptions/error_utils.h

@@ -3,10 +3,20 @@
 #include "gridfire/exceptions/error_gridfire.h"
 
 namespace gridfire::exceptions {
+    /**
+     * @brief Base class for utility-related errors in GridFire.
+     *
+     * This class serves as a base for all exceptions related to utility functions
+     */
     class UtilityError : public GridFireError {
         using GridFireError::GridFireError;
     };
 
+    /**
+     * @brief Exception class for hashing-related errors in GridFire.
+     *
+     * This class is used to represent errors that occur during hashing operations.
+     */
     class HashingError final : public UtilityError {
         using UtilityError::UtilityError;
     };

src/include/gridfire/exceptions/exceptions.h

@@ -7,4 +7,14 @@
 #include "gridfire/exceptions/error_policy.h"
 #include "gridfire/exceptions/error_reaction.h"
 #include "gridfire/exceptions/error_solver.h"
-#include "gridfire/exceptions/error_utils.h"
+#include "gridfire/exceptions/error_utils.h"
+
+/**
+ * @namespace gridfire::exceptions
+ * @brief Namespace for GridFire exception classes. All custom exceptions
+ * defined in GridFire inherit from std::exception and are organized
+ * within this namespace for clarity and modularity.
+ *
+ * All GridFire exception classes derive from std::exception and then from gridfire::exceptions::GridFireError;
+ */
+namespace gridfire::exceptions{}