docs(docs): asdded and cleaned up docs

src/include/gridfire/partition/composite/partition_composite.h

@@ -13,21 +13,92 @@
 
 
 namespace gridfire::partition {
-    class CompositePartitionFunction final : public PartitionFunction {
-    public:
-        explicit CompositePartitionFunction(const std::vector<BasePartitionType>& partitionFunctions);
-        CompositePartitionFunction(const CompositePartitionFunction& other);
-        [[nodiscard]] double evaluate(int z, int a, double T9) const override;
-        [[nodiscard]] double evaluateDerivative(int z, int a, double T9) const override;
-        [[nodiscard]] bool supports(int z, int a) const override;
-        [[nodiscard]] std::string type() const override;
-        [[nodiscard]] std::unique_ptr<PartitionFunction> clone() const override {
-            return std::make_unique<CompositePartitionFunction>(*this);
-        }
-    private:
-        quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log");
-        std::vector<std::unique_ptr<PartitionFunction>> m_partitionFunctions; ///< Set of partition functions to use in the composite partition function.
-    private:
-        std::unique_ptr<PartitionFunction> selectPartitionFunction(const BasePartitionType type) const;
-    };
-}
+    /**
+     * @class CompositePartitionFunction
+     * @brief Combines multiple PartitionFunction instances into a single composite strategy.
+     *
+     * Maintains an ordered list of sub-functions and delegates evaluation and derivative calls
+     * to the first function that supports the requested isotope.
+     *
+     * See partition_composite.cpp for details on sub-function selection and error logging.
+     *
+     * @throws std::runtime_error If no sub-function supports a given (z,a,T9) in evaluate or evaluateDerivative.
+     */
+     class CompositePartitionFunction final : public PartitionFunction {
+     public:
+        /**
+         * @brief Construct a composite function from specified types.
+         *
+         * Instantiates sub-functions according to the order of types provided.
+         * @param partitionFunctions List of BasePartitionType identifiers for sub-functions.
+         * @pre partitionFunctions must not be empty.
+         * @post m_partitionFunctions contains instances matching each type.
++         */
+         explicit CompositePartitionFunction(const std::vector<BasePartitionType>& partitionFunctions);
+        /**
+         * @brief Copy constructor.
+         *
+         * Creates deep clones of the sub-functions in another composite.
+         * @param other Existing composite to copy from.
+         * @post m_partitionFunctions contains clones of other's sub-functions.
++         */
+         CompositePartitionFunction(const CompositePartitionFunction& other);
+        /**
+         * @brief Evaluate the composite partition function.
+         *
+         * Calls evaluate on the first sub-function supporting the isotope.
+         * @param z Atomic number (>=1).
+         * @param a Mass number (>=z).
+         * @param T9 Temperature in 10^9 K.
+         * @return Partition function value from supporting sub-function.
+         * @throws std::runtime_error If no sub-function supports (z,a,T9).
++         */
+         [[nodiscard]] double evaluate(int z, int a, double T9) const override;
+        /**
+         * @brief Evaluate temperature derivative of the composite function.
+         *
+         * Delegates to the first supporting sub-function's derivative.
+         * @param z Atomic number.
+         * @param a Mass number.
+         * @param T9 Temperature in 10^9 K.
+         * @return d/dT9 of the partition function.
+         * @throws std::runtime_error If no sub-function supports (z,a,T9).
++         */
+         [[nodiscard]] double evaluateDerivative(int z, int a, double T9) const override;
+        /**
+         * @brief Check support across all sub-functions.
+         *
+         * @param z Atomic number.
+         * @param a Mass number.
+         * @return true if any sub-function supports (z,a); false otherwise.
++         */
+         [[nodiscard]] bool supports(int z, int a) const override;
+        /**
+         * @brief Get composite type identifier.
+         *
+         * Concatenates the type() strings of all sub-functions.
+         * @return A string like "CompositePartitionFunction(func1, func2, ...)".
++         */
+         [[nodiscard]] std::string type() const override;
+        /**
+         * @brief Clone this composite partition function.
+         *
+         * @return Unique pointer to a deep copy of this object.
++         */
+         [[nodiscard]] std::unique_ptr<PartitionFunction> clone() const override {
+             return std::make_unique<CompositePartitionFunction>(*this);
+         }
+     private:
+         quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log");
+         std::vector<std::unique_ptr<PartitionFunction>> m_partitionFunctions; ///< Set of partition functions to use in the composite partition function.
+     private:
+        /**
+         * @brief Instantiate a sub-function by its type.
+         *
+         * @param type Enumeration value selecting the desired function implementation.
+         * @return Unique pointer to a new PartitionFunction instance of the given type.
+         * @throws std::runtime_error If the given type is not recognized.
++         */
+         std::unique_ptr<PartitionFunction> selectPartitionFunction(const BasePartitionType type) const;
+     };
+ }

src/include/gridfire/partition/partition_abstract.h

@@ -4,13 +4,75 @@
 #include <memory>
 
 namespace gridfire::partition {
+
+    /**
+     * @class PartitionFunction
+     * @brief Abstract interface for evaluating nuclear partition functions.
+     *
+     * Provides methods to compute the partition function and its temperature derivative
+     * for a given isotope, to query if the function supports that isotope, and to
+     * clone the function object. Concrete implementations must provide temperature-
+     * dependent statistical models.
+     */
     class PartitionFunction {
     public:
+        /**
+         * @brief Virtual destructor.
+         *
+         * Ensures proper cleanup in derived classes.
+         */
         virtual ~PartitionFunction() = default;
+
+        /**
+         * @brief Evaluate the partition function for a given isotope.
+         *
+         * @param z Proton number (atomic number) of the isotope; must be >= 1.
+         * @param a Mass number of the isotope; must be >= z.
+         * @param T9 Temperature in units of 10^9 K; must be > 0.
+         * @return Partition function value (dimensionless) at the specified temperature.
+         * @pre Derived implementation supports (z, a) and T9 > 0.
+         * @post No side effects; pure function.
+         */
         [[nodiscard]] virtual double evaluate(int z, int a, double T9) const = 0;
+
+        /**
+         * @brief Evaluate the temperature derivative of the partition function.
+         *
+         * Computes d/dT (partition function) at the given parameters.
+         *
+         * @param z Proton number (atomic number) of the isotope; must be >= 1.
+         * @param a Mass number of the isotope; must be >= z.
+         * @param T9 Temperature in units of 10^9 K; must be > 0.
+         * @return Temperature derivative of the partition function.
+         * @pre Derived implementation supports (z, a) and T9 > 0.
+         * @post No side effects; pure function.
+         */
         [[nodiscard]] virtual double evaluateDerivative(int z, int a, double T9) const = 0;
+
+        /**
+         * @brief Check if this partition function supports an isotope.
+         *
+         * @param z Proton number of the isotope.
+         * @param a Mass number of the isotope.
+         * @return true if evaluate and evaluateDerivative can be called for this isotope; false otherwise.
+         * @post No side effects.
+         */
         [[nodiscard]] virtual bool supports(int z, int a) const = 0;
+
+        /**
+         * @brief Get the human-readable type of this partition function.
+         *
+         * @return String identifier for the partition function implementation.
+         * @post No side effects.
+         */
         [[nodiscard]] virtual std::string type() const = 0;
+
+        /**
+         * @brief Create a deep copy of this PartitionFunction.
+         *
+         * @return Unique pointer to a new PartitionFunction instance with identical state.
+         * @post The caller owns the returned object and must manage its lifetime.
+         */
         [[nodiscard]] virtual std::unique_ptr<PartitionFunction> clone() const = 0;
     };
 }

src/include/gridfire/partition/partition_ground.h

@@ -10,33 +10,99 @@
 #include "quill/Logger.h"
 
 namespace gridfire::partition {
-    class GroundStatePartitionFunction final : public PartitionFunction {
-    public:
-        GroundStatePartitionFunction();
-        double evaluate(
-            const int z,
-            const int a,
-            const double T9
-        ) const override;
-        double evaluateDerivative(
-            const int z,
-            const int a,
-            const double T9
-        ) const override;
-        bool supports(
-            const int z,
-            const int a
-        ) const override;
-        std::string type() const override { return "GroundState"; }
-        std::unique_ptr<PartitionFunction> clone() const override {
-            return std::make_unique<GroundStatePartitionFunction>(*this);
-        }
-    private:
-        quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log");
-        std::unordered_map<int, double> m_ground_state_spin;
-        static constexpr int make_key(
-            const int z,
-        const int a);
-    };
+    /**
+     * @class GroundStatePartitionFunction
+     * @brief Partition function implementation for nuclear ground states.
+     *
+     * Computes the partition function as (2J + 1) based on the ground state spin J of each isotope.
+     * The temperature derivative is always zero. Ground state spins are loaded from the
+     * fourdst::atomic::species registry at construction.
+     * @see partition_ground.cpp for implementation details.
+     */
+     class GroundStatePartitionFunction final : public PartitionFunction {
+     public:
+        /**
+         * @brief Construct and populate the ground state spin map.
++         *
+         * Loads spins for all isotopes from the atomic species registry into m_ground_state_spin.
+         * @pre atomic::species registry is initialized and non-empty.
+         * @post m_ground_state_spin contains entries for each isotope.
++         */
+         GroundStatePartitionFunction();
+        /**
+         * @brief Evaluate the ground state partition function.
++         *
+         * @param z Proton number (atomic number) of the isotope; must be >= 1.
+         * @param a Mass number of the isotope; must be >= z.
+         * @param T9 Temperature in units of 10^9 K; unused for ground state.
+         * @pre supports(z,a) returns true.
+         * @post No side effects.
+         * @return Dimensionless partition function value = 2*spin + 1.
+         * @throws std::out_of_range If the isotope key is not found in m_ground_state_spin.
++         */
+         double evaluate(
+             const int z,
+             const int a,
+             const double T9
+         ) const override;
+        /**
+         * @brief Evaluate the temperature derivative of the ground state partition function.
++         *
+         * Always returns zero as ground state has no temperature dependence.
+         * @param z Proton number of the isotope; must be supported.
+         * @param a Mass number of the isotope; must be supported.
+         * @param T9 Temperature in units of 10^9 K; unused.
+         * @pre supports(z,a) returns true.
+         * @post No side effects.
+         * @return Zero.
+         * @throws std::out_of_range If the isotope key is not found.
++         */
+         double evaluateDerivative(
+             const int z,
+             const int a,
+             const double T9
+         ) const override;
+        /**
+         * @brief Check if ground state data exists for the given isotope.
++         *
+         * @param z Proton number of the isotope.
+         * @param a Mass number of the isotope.
+         * @return True if m_ground_state_spin contains the key; false otherwise.
+         * @post No side effects.
++         */
+         bool supports(
+             const int z,
+             const int a
+         ) const override;
+        /**
+         * @brief Get the type identifier of this partition function.
+         * @return The string literal "GroundState".
+         * @post No side effects.
++         */
+         std::string type() const override { return "GroundState"; }
+        /**
+         * @brief Create a deep copy of this partition function.
+         * @return Unique_ptr to a new GroundStatePartitionFunction cloned from this object.
+         * @post Caller owns the returned instance.
++         */
+         std::unique_ptr<PartitionFunction> clone() const override {
+             return std::make_unique<GroundStatePartitionFunction>(*this);
+         }
+     private:
+         quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log");
+         std::unordered_map<int, double> m_ground_state_spin;
+        /**
+         * @brief Generate a unique lookup key for an isotope.
++         *
+         * Combines atomic number z and mass number a into a single integer.
+         * @param z Proton number of the isotope.
+         * @param a Mass number of the isotope; should be < 1000 to avoid collisions.
+         * @pre a < 1000.
+         * @return Integer key = z * 1000 + a.
++         */
+         static constexpr int make_key(
+             const int z,
+         const int a);
+     };
 
-}
+ }

src/include/gridfire/partition/partition_rauscher_thielemann.h

@@ -12,29 +12,95 @@
 #include <memory>
 
 namespace gridfire::partition {
+
+    /**
+     * @class RauscherThielemannPartitionFunction
+     * @brief Partition function using Rauscher-Thielemann tabulated normalized G-values.
+     *
+     * Loads isotope partition data from embedded records and computes values by
+     * selecting boundary data or interpolating between grid points on a fixed T9 grid.
+     * Implementation in partition_rauscher_thielemann.cpp.
+     *
+     * @throws std::out_of_range If requested isotope data is missing.
+     */
     class RauscherThielemannPartitionFunction final : public PartitionFunction {
     public:
+        /**
+         * @brief Construct and populate partition data.
+         *
+         * Reads embedded RT partition data records and fills m_partitionData.
+         * @pre Embedded data arrays are available and non-empty.
+         * @post m_partitionData contains entries for all isotopes in data.
+         */
         RauscherThielemannPartitionFunction();
+        /**
+         * @brief Evaluate partition function for isotope at temperature.
+         *
+         * Retrieves boundary or interpolated normalized G-value and scales by (2J+1).
+         * @param z Atomic number of the isotope (>=1).
+         * @param a Mass number of the isotope (>=z).
+         * @param T9 Temperature in units of 10^9 K.
+         * @return Dimensionless partition function.
+         * @pre supports(z,a) returns true.
+         * @post No side effects.
+         * @throws std::out_of_range If isotope key not found in m_partitionData.
+         */
         double evaluate(int z, int a, double T9) const override;
+        /**
+         * @brief Evaluate temperature derivative of partition function.
+         *
+         * Zero at grid extremes; otherwise derivative of linear interpolation.
+         * @param z Atomic number (>=1).
+         * @param a Mass number (>=z).
+         * @param T9 Temperature in 10^9 K.
+         * @return d(PartitionFunction)/dT9.
+         * @pre supports(z,a) returns true.
+         * @post No side effects.
+         * @throws std::out_of_range If isotope data is missing.
+         */
         double evaluateDerivative(int z, int a, double T9) const override;
+        /**
+         * @brief Check if partition data exists for given isotope.
+         * @param z Atomic number.
+         * @param a Mass number.
+         * @return true if data available; false otherwise.
+         * @post No side effects.
+         */
         bool supports(int z, int a) const override;
+        /**
+         * @brief Get type identifier for this partition function.
+         * @return Literal string "RauscherThielemann".
+         * @post No side effects.
+         */
         std::string type() const override { return "RauscherThielemann"; }
+        /**
+         * @brief Clone this partition function instance.
+         * @return Unique pointer to a copy of this object.
+         * @post Caller owns the returned object.
+         */
+        std::unique_ptr<PartitionFunction> clone() const override {
+            return std::make_unique<RauscherThielemannPartitionFunction>(*this);
+        }
     private:
+        /**
+         * @enum Bounds
+         * @brief Indicator for temperature grid bound position.
+         */
         enum Bounds {
-            FRONT,
-            BACK,
-            MIDDLE
+            FRONT,  ///< Below first grid point
+            BACK,   ///< Above last grid point
+            MIDDLE  ///< Between grid points
         };
     private:
         struct IsotopeData {
-            double ground_state_spin;
-            std::array<double, 24> normalized_g_values;
+            double ground_state_spin;        ///< Spin of the isotope ground state
+            std::array<double, 24> normalized_g_values; ///< Normalized G values on RT grid
         };
         struct InterpolationPoints {
-            double T9_high;
-            double G_norm_high;
-            double T9_low;
-            double G_norm_low;
+            double T9_high;     ///< Upper temperature bound
+            double G_norm_high; ///< Normalized G at upper bound
+            double T9_low;      ///< Lower temperature bound
+            double G_norm_low;  ///< Normalized G at lower bound
         };
         struct IdentifiedIsotope {
             Bounds bound;
@@ -42,19 +108,38 @@ namespace gridfire::partition {
             size_t upperIndex;
             size_t lowerIndex;
         };
-        std::unique_ptr<PartitionFunction> clone() const override {
-            return std::make_unique<RauscherThielemannPartitionFunction>(*this);
-        }
     private:
         quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log");
-        std::unordered_map<int, IsotopeData> m_partitionData;
+        std::unordered_map<int, IsotopeData> m_partitionData; ///< Map of isotope key to data
     private:
+        /**
+         * @brief Get interpolation points from normalized G array.
+         * @param upper_index Index of upper grid point.
+         * @param lower_index Index of lower grid point.
+         * @param normalized_g_values Array of normalized G values.
+         * @return InterpolationPoints containing bounds and G values.
+         */
         static InterpolationPoints get_interpolation_points(
             const size_t upper_index,
             const size_t lower_index,
             const std::array<double, 24>& normalized_g_values
         );
+        /**
+         * @brief Identify isotope entry and grid indices for given T9.
+         * @param z Atomic number of isotope.
+         * @param a Mass number of isotope.
+         * @param T9 Temperature in 10^9 K.
+         * @return IdentifiedIsotope with data reference and indices.
+         * @throws std::out_of_range If isotope not found in m_partitionData.
+         */
         IdentifiedIsotope find(int z, int a, double T9) const;
+        /**
+         * @brief Generate integer key for isotope (z,a).
+         * @param z Atomic number.
+         * @param a Mass number (<1000).
+         * @return Key computed as z*1000 + a.
+         */
         static constexpr int make_key(int z, int a);
     };
+
 }

src/include/gridfire/partition/partition_types.h

@@ -4,18 +4,44 @@
 #include <string>
 
 namespace gridfire::partition {
+
+    /**
+     * @enum BasePartitionType
+     * @brief Enumerates available partition function implementations.
+     *
+     * RauscherThielemann: Uses tabulated normalized G-values and linear interpolation.
+     * GroundState: Uses ground state spin (J) to compute partition function as 2J+1.
+     */
     enum BasePartitionType {
         RauscherThielemann, ///< Rauscher-Thielemann partition function
         GroundState,        ///< Ground state partition function
     };
 
+    /**
+     * @brief Mapping from BasePartitionType enum to human-readable string.
+     *
+     * Used for logging, reporting, or serialization. Ensure that all enum values
+     * are represented in this map.
+     * @pre Contains entries for all values of BasePartitionType.
+     * @post Can convert BasePartitionType to corresponding string.
+     */
     inline std::unordered_map<BasePartitionType, std::string> basePartitionTypeToString = {
         {RauscherThielemann, "RauscherThielemann"},
         {GroundState, "GroundState"}
     };
 
+    /**
+     * @brief Mapping from string to BasePartitionType enum.
+     *
+     * Used for parsing configuration or user input. Strings must match exactly
+     * to one of the defined partition types.
+     * @pre Uses keys that exactly match the outputs of basePartitionTypeToString.
+     * @post Can convert valid string identifiers back to BasePartitionType.
+     * @throws std::out_of_range if accessed with a non-existing key via at().
+     */
     inline std::unordered_map<std::string, BasePartitionType> stringToBasePartitionType = {
         {"RauscherThielemann", RauscherThielemann},
         {"GroundState", GroundState}
     };
+
 }

src/include/gridfire/partition/rauscher_thielemann_partition_data_record.h

@@ -4,6 +4,16 @@
 
 namespace gridfire::partition::record {
 #pragma pack(push, 1)
+/**
+ * @struct RauscherThielemannPartitionDataRecord
+ * @brief Packed binary record of Rauscher-Thielemann partition function data for an isotope.
+ *
+ * Each record stores the atomic number (Z), mass number (A), ground state spin J,
+ * and an array of 24 normalized G-values corresponding to fixed temperature grid points.
+ * This struct is read directly from embedded binary data and must remain tightly packed.
+ *
+ * @note Alignment is set to 1 byte to match the binary layout.
+ */
     struct RauscherThielemannPartitionDataRecord {
         uint32_t z; ///< Atomic number
         uint32_t a; ///< Mass number