tboudreaux/GridFire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(docs): added extensive docs

Browse Source
This commit is contained in:
Emily Boudreaux
2025-07-01 15:06:22 -04:00
parent 5b4db3ea43
commit 131f61c9e7
134 changed files with 5101 additions and 2191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
src/network/include/gridfire/screening/screening_abstract.h
View File

@@ -9,11 +9,67 @@
#include <vector>
namespace gridfire::screening {
/**
* @class ScreeningModel
* @brief An abstract base class for plasma screening models.
*
* This class defines the interface for models that calculate the enhancement
* factor for nuclear reaction rates due to the electrostatic screening of
* interacting nuclei by the surrounding plasma. Concrete implementations of
* this class will provide specific screening prescriptions (e.g., WEAK,
* BARE, STRONG, etc.).
*
* The interface provides methods for calculating screening factors for both
* standard double-precision inputs and for CppAD's automatic differentiation
* types, allowing the screening contributions to be included in Jacobian
* calculations.
*/
class ScreeningModel {
public:
/// @brief Alias for CppAD Automatic Differentiation type for double precision.
using ADDouble = CppAD::AD<double>;
/**
* @brief Virtual destructor.
*
* Ensures that derived class destructors are called correctly.
*/
virtual ~ScreeningModel() = default;
/**
* @brief Calculates screening factors for a set of reactions.
*
* This is a pure virtual function that must be implemented by derived
* classes. It computes the screening enhancement factor for each reaction
* in the provided set based on the given plasma conditions.
*
* @param reactions The set of logical reactions in the network.
* @param species A vector of all atomic species involved in the network.
* @param Y A vector of the molar abundances (mol/g) for each species.
* @param T9 The temperature in units of 10^9 K.
* @param rho The plasma density in g/cm^3.
* @return A vector of screening factors (dimensionless), one for each reaction
* in the `reactions` set, in the same order.
*
* @b Pre-conditions
* - The size of the `Y` vector must match the size of the `species` vector.
* - `T9` and `rho` must be positive.
*
* @b Post-conditions
* - The returned vector will have the same size as the `reactions` set.
* - Each element in the returned vector will be >= 1.0.
*
* @b Usage
* @code
* // Assume 'model' is a std::unique_ptr<ScreeningModel> to a concrete implementation
* // and other parameters (reactions, species, Y, T9, rho) are initialized.
* std::vector<double> screening_factors = model->calculateScreeningFactors(
* reactions, species, Y, T9, rho
* );
* for (size_t i = 0; i < reactions.size(); ++i) {
* // ... use screening_factors[i] ...
* }
* @endcode
*/
virtual std::vector<double> calculateScreeningFactors(
const reaction::LogicalReactionSet& reactions,
const std::vector<fourdst::atomic::Species>& species,
@@ -22,6 +78,25 @@ namespace gridfire::screening {
const double rho
) const = 0;
/**
* @brief Calculates screening factors using CppAD types for automatic differentiation.
*
* This is a pure virtual function that provides an overload of
* `calculateScreeningFactors` for use with CppAD. It allows the derivatives
* of the screening factors with respect to abundances, temperature, and
* density to be computed automatically.
*
* @param reactions The set of logical reactions in the network.
* @param species A vector of all atomic species involved in the network.
* @param Y A vector of the molar abundances (mol/g) for each species, as AD types.
* @param T9 The temperature in units of 10^9 K, as an AD type.
* @param rho The plasma density in g/cm^3, as an AD type.
* @return A vector of screening factors (dimensionless), as AD types.
*
* @b Note
* This method is essential for including the effects of screening in the
* Jacobian matrix of the reaction network.
*/
virtual std::vector<ADDouble> calculateScreeningFactors(
const reaction::LogicalReactionSet& reactions,
const std::vector<fourdst::atomic::Species>& species,

87
src/network/include/gridfire/screening/screening_bare.h
View File

@@ -6,9 +6,51 @@
#include "cppad/cppad.hpp"
namespace gridfire::screening {
/**
* @class BareScreeningModel
* @brief A screening model that applies no screening effect.
*
* This class implements the `ScreeningModel` interface but returns a
* screening factor of 1.0 for all reactions, regardless of the plasma
* conditions. It represents the case of bare, unscreened nuclei and serves
* as a baseline or can be used when screening effects are negligible or
* intentionally ignored.
*
* @implements ScreeningModel
*/
class BareScreeningModel final : public ScreeningModel {
/// @brief Alias for CppAD Automatic Differentiation type for double precision.
using ADDouble = CppAD::AD<double>;
public:
/**
* @brief Calculates screening factors, which are always 1.0.
*
* This implementation returns a vector of screening factors where every
* element is 1.0, effectively applying no screening correction to the
* reaction rates.
*
* @param reactions The set of logical reactions in the network.
* @param species A vector of all atomic species (unused).
* @param Y A vector of the molar abundances (unused).
* @param T9 The temperature (unused).
* @param rho The plasma density (unused).
* @return A vector of doubles, with each element being 1.0, of the same
* size as the `reactions` set.
*
* @b Algorithm
* The function simply creates and returns a `std::vector<double>` of the
* same size as the input `reactions` set, with all elements initialized to 1.0.
*
* @b Usage
* @code
* BareScreeningModel bare_model;
* // ... (initialize reactions, species, Y, T9, rho)
* std::vector<double> factors = bare_model.calculateScreeningFactors(
* reactions, species, Y, T9, rho
* );
* // 'factors' will contain [1.0, 1.0, ...]
* @endcode
*/
[[nodiscard]] std::vector<double> calculateScreeningFactors(
const reaction::LogicalReactionSet& reactions,
const std::vector<fourdst::atomic::Species>& species,
@@ -17,6 +59,21 @@ namespace gridfire::screening {
const double rho
) const override;
/**
* @brief Calculates screening factors for AD types, which are always 1.0.
*
* This implementation returns a vector of AD-typed screening factors where
* every element is 1.0. This is the automatic differentiation-compatible
* version.
*
* @param reactions The set of logical reactions in the network.
* @param species A vector of all atomic species (unused).
* @param Y A vector of the molar abundances as AD types (unused).
* @param T9 The temperature as an AD type (unused).
* @param rho The plasma density as an AD type (unused).
* @return A vector of ADDouble, with each element being 1.0, of the same
* size as the `reactions` set.
*/
[[nodiscard]] std::vector<ADDouble> calculateScreeningFactors(
const reaction::LogicalReactionSet& reactions,
const std::vector<fourdst::atomic::Species>& species,
@@ -25,6 +82,21 @@ namespace gridfire::screening {
const ADDouble rho
) const override;
private:
/**
* @brief Template implementation for calculating screening factors.
*
* This private helper function contains the core logic for both the `double`
* and `ADDouble` versions of `calculateScreeningFactors`. It is templated
* to handle both numeric types seamlessly.
*
* @tparam T The numeric type, either `double` or `CppAD::AD<double>`.
* @param reactions The set of reactions for which to calculate factors.
* @param species A vector of all atomic species (unused).
* @param Y A vector of molar abundances (unused).
* @param T9 The temperature (unused).
* @param rho The density (unused).
* @return A vector of type `T` with all elements initialized to 1.0.
*/
template <typename T>
[[nodiscard]] std::vector<T> calculateFactors_impl(
const reaction::LogicalReactionSet& reactions,
@@ -35,6 +107,21 @@ namespace gridfire::screening {
) const;
};
/**
* @brief Template implementation for the bare screening model.
*
* This function provides the actual implementation for `calculateFactors_impl`.
* It creates a vector of the appropriate numeric type (`T`) and size, and
* initializes all its elements to 1.0, representing no screening.
*
* @tparam T The numeric type, either `double` or `CppAD::AD<double>`.
* @param reactions The set of reactions, used to determine the size of the output vector.
* @param species Unused parameter.
* @param Y Unused parameter.
* @param T9 Unused parameter.
* @param rho Unused parameter.
* @return A `std::vector<T>` of the same size as `reactions`, with all elements set to 1.0.
*/
template<typename T>
std::vector<T> BareScreeningModel::calculateFactors_impl(
const reaction::LogicalReactionSet &reactions,

60
src/network/include/gridfire/screening/screening_types.h
View File

@@ -5,10 +5,66 @@
#include <memory>
namespace gridfire::screening {
/**
* @enum ScreeningType
* @brief Enumerates the available plasma screening models.
*
* This enum provides a set of identifiers for the different screening
* prescriptions that can be used in the reaction rate calculations.
*/
enum class ScreeningType {
BARE, ///< No screening applied
WEAK, ///< Weak screening model
BARE, ///< No screening applied. The screening factor is always 1.0.
/**
* @brief Weak screening model (Salpeter, 1954).
*
* This model is suitable for non-degenerate, non-relativistic plasmas
* where the electrostatic potential energy between ions is small compared
* to their thermal kinetic energy. The screening enhancement factor is
* calculated as `exp(H_12)`.
*
* @b Algorithm
* 1. A composition-dependent term, `ζ = ∑(Z_i^2 + Z_i) * Y_i`, is calculated,
* where Z_i is the charge and Y_i is the molar abundance of each species.
* 2. A prefactor is computed: `prefactor = 0.188 * sqrt(ρ / T₇³) * sqrt(ζ)`,
* where ρ is the density and T₇ is the temperature in 10^7 K.
* 3. For a reaction between two nuclei with charges Z₁ and Z₂, the enhancement
* term is `H_12 = prefactor * Z₁ * Z₂`.
* 4. The final screening factor is `exp(H_12)`.
* A special calculation is performed for the triple-alpha reaction.
*/
WEAK,
};
/**
* @brief A factory function to select and create a screening model.
*
* This function returns a `std::unique_ptr` to a concrete implementation of
* the `ScreeningModel` abstract base class, based on the specified `ScreeningType`.
* This allows for easy switching between different screening prescriptions at runtime.
*
* @param type The `ScreeningType` enum value specifying which model to create.
* @return A `std::unique_ptr<ScreeningModel>` holding an instance of the
* requested screening model.
*
* @b Algorithm
* The function uses a `switch` statement to determine which concrete model to
* instantiate. If the provided `type` does not match a known case, it defaults
* to creating a `BareScreeningModel` to ensure safe behavior.
*
* @b Post-conditions
* - A non-null `std::unique_ptr<ScreeningModel>` is always returned.
*
* @b Usage
* @code
* // Select the weak screening model
* auto screening_model = gridfire::screening::selectScreeningModel(gridfire::screening::ScreeningType::WEAK);
*
* // Use the model to calculate screening factors
* // (assuming other parameters are initialized)
* std::vector<double> factors = screening_model->calculateScreeningFactors(
* reactions, species, Y, T9, rho
* );
* @endcode
*/
std::unique_ptr<ScreeningModel> selectScreeningModel(ScreeningType type);
}

96
src/network/include/gridfire/screening/screening_weak.h
View File

@@ -10,8 +10,43 @@
#include "cppad/cppad.hpp"
namespace gridfire::screening {
/**
* @class WeakScreeningModel
* @brief Implements the weak screening model based on the Debye-Hückel approximation.
*
* This class provides a concrete implementation of the `ScreeningModel`
* interface for the weak screening regime, following the formulation of
* Salpeter (1954). This approach applies the Debye-Hückel theory to model the
* electrostatic shielding of nuclei in a plasma. It is applicable to
* non-degenerate, non-relativistic plasmas where thermal energy dominates
* the electrostatic potential energy.
*
* @implements ScreeningModel
*/
class WeakScreeningModel final : public ScreeningModel {
public:
/**
* @brief Calculates weak screening factors for a set of reactions.
*
* This method computes the screening enhancement factor for each reaction
* based on the Salpeter (1954) formula.
*
* @param reactions The set of logical reactions in the network.
* @param species A vector of all atomic species involved in the network.
* @param Y A vector of the molar abundances (mol/g) for each species.
* @param T9 The temperature in units of 10^9 K.
* @param rho The plasma density in g/cm^3.
* @return A vector of screening factors (dimensionless), one for each reaction.
*
* @b Usage
* @code
* WeakScreeningModel weak_model;
* // ... (initialize reactions, species, Y, T9, rho)
* std::vector<double> factors = weak_model.calculateScreeningFactors(
* reactions, species, Y, T9, rho
* );
* @endcode
*/
[[nodiscard]] std::vector<double> calculateScreeningFactors(
const reaction::LogicalReactionSet& reactions,
const std::vector<fourdst::atomic::Species>& species,
@@ -20,6 +55,20 @@ namespace gridfire::screening {
const double rho
) const override;
/**
* @brief Calculates weak screening factors using CppAD types.
*
* This is the automatic differentiation-compatible version of the method.
* It allows the derivatives of the screening factors to be computed with
* respect to plasma conditions.
*
* @param reactions The set of logical reactions in the network.
* @param species A vector of all atomic species involved in the network.
* @param Y A vector of the molar abundances as AD types.
* @param T9 The temperature as an AD type.
* @param rho The plasma density as an AD type.
* @return A vector of screening factors as AD types.
*/
[[nodiscard]] std::vector<CppAD::AD<double>> calculateScreeningFactors(
const reaction::LogicalReactionSet& reactions,
const std::vector<fourdst::atomic::Species>& species,
@@ -28,9 +77,25 @@ namespace gridfire::screening {
const CppAD::AD<double> rho
) const override;
private:
/// @brief Logger instance for recording trace and debug information.
quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log");
private:
/**
* @brief Template implementation for calculating weak screening factors.
*
* This private helper function contains the core logic for calculating
* weak screening factors. It is templated to handle both `double` and
* `CppAD::AD<double>` numeric types, avoiding code duplication.
*
* @tparam T The numeric type, either `double` or `CppAD::AD<double>`.
* @param reactions The set of reactions.
* @param species A vector of all species in the network.
* @param Y A vector of molar abundances.
* @param T9 The temperature in 10^9 K.
* @param rho The density in g/cm^3.
* @return A vector of screening factors of type `T`.
*/
template <typename T>
[[nodiscard]] std::vector<T> calculateFactors_impl(
const reaction::LogicalReactionSet& reactions,
@@ -41,6 +106,37 @@ namespace gridfire::screening {
) const;
};
/**
* @brief Core implementation of the weak screening calculation (Debye-Hückel model).
*
* This function calculates the screening factor `exp(H_12)` for each reaction,
* based on the Debye-Hückel approximation as formulated by Salpeter (1954).
*
* @tparam T The numeric type (`double` or `CppAD::AD<double>`).
* @param reactions The set of reactions to be screened.
* @param species The list of all species in the network.
* @param Y The molar abundances of the species.
* @param T9 The temperature in 10^9 K.
* @param rho The density in g/cm^3.
* @return A vector of screening factors, one for each reaction.
*
* @b Algorithm
* 1. **Low-Temperature Cutoff**: If T9 is below a small threshold (1e-9),
* screening is effectively turned off to prevent numerical instability.
* 2. **Zeta Factor (ζ)**: A composition-dependent term is calculated:
* `ζ = ∑(Z_i² + Z_i) * Y_i`, where Z_i is the charge and Y_i is the
* molar abundance of species i.
* 3. **Prefactor**: A key prefactor is computed:
* `prefactor = 0.188 * sqrt(ρ / T₇³) * sqrt(ζ)`,
* where T₇ is the temperature in units of 10^7 K.
* 4. **Screening Term (H_12)**: For each reaction, the term H_12 is calculated:
* - For a two-body reaction (reactants Z₁ and Z₂): `H_12 = prefactor * Z₁ * Z₂`.
* - For the triple-alpha reaction (3 * He4): `H_12 = 3 * (prefactor * Z_α * Z_α)`.
* - For one-body reactions (decays), H_12 is 0, so the factor is 1.
* 5. **Capping**: The value of H_12 is capped at 2.0 to prevent excessively large
* and unphysical screening factors (exp(2) ≈ 7.4).
* 6. **Final Factor**: The screening factor for the reaction is `exp(H_12)`.
*/
template <typename T>
std::vector<T> WeakScreeningModel::calculateFactors_impl(
const reaction::LogicalReactionSet& reactions,