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

docs(docs): asdded and cleaned up docs

Browse Source
This commit is contained in:
Emily Boudreaux
2025-07-24 11:10:45 -04:00
parent cc3708fda5
commit ba9b3e2392
808 changed files with 140326 additions and 9346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
src/include/gridfire/engine/procedures/construction.h
View File

@@ -9,6 +9,27 @@
namespace gridfire {
/**
* @brief Builds a nuclear reaction network from the Reaclib library based on an initial composition.
*
* Constructs a layered reaction network by collecting reactions up to the specified depth
* from the Reaclib dataset. Starting species are those with non-zero mass fractions in the input
* composition. Layers expand by including products of collected reactions until the depth limit.
* Optionally selects reverse reactions instead of forward.
*
* See implementation in construction.cpp for details on the layering algorithm, logging, and performance.
*
* @param composition Mapping of isotopic species to their mass fractions; species with positive
* mass fraction seed the network.
* @param maxLayers Variant specifying either a predefined NetworkBuildDepth or a custom integer depth;
* negative depth (Full) collects all reactions, zero is invalid.
* @param reverse If true, collects reverse reactions (decays or back-reactions); if false, uses forward reactions.
* @pre composition must have at least one species with positive mass fraction.
* @pre Resolved integer depth from maxLayers must not be zero.
* @post Returned network includes only reactions satisfying the depth and reverse criteria.
* @return A LogicalReactionSet encapsulating the collected reactions for graph-based engines.
* @throws std::logic_error If the resolved network depth is zero (no reactions can be collected).
*/
reaction::LogicalReactionSet build_reaclib_nuclear_network(
const fourdst::composition::Composition &composition,
BuildDepthType maxLayers = NetworkBuildDepth::Full,

85
src/include/gridfire/engine/procedures/priming.h
View File

@@ -13,25 +13,70 @@
namespace gridfire {
/**
* @brief Primes absent species in the network to their equilibrium abundances.
*
* Executes a network priming algorithm that iteratively rebuilds the reaction network,
* calculates equilibrium mass fractions for species with zero initial abundance,
* and applies mass transfers based on reaction flows.
*
* Refer to priming.cpp for implementation details on logging, algorithmic steps, and error handling.
*
* @param netIn Input network data containing initial composition, temperature, and density.
* @param engine DynamicEngine used to build and evaluate the reaction network.
* @pre netIn.composition defines species and their mass fractions; engine is constructed with a valid network.
* @post engine.networkReactions restored to its initial state; returned report contains primedComposition,
* massFractionChanges for each species, success flag, and status code.
* @return PrimingReport encapsulating the results of the priming operation.
*/
PrimingReport primeNetwork(
const NetIn&,
DynamicEngine& engine
);
PrimingReport primeNetwork(
const NetIn&,
DynamicEngine& engine
);
/**
* @brief Computes the destruction rate constant for a specific species.
*
* Calculates the sum of molar reaction flows for all reactions where the species
* is a reactant (negative stoichiometry) after scaling its abundance to unity.
*
* @param engine Engine providing the current set of network reactions and flow calculations.
* @param species The atomic species whose destruction rate is computed.
* @param Y Vector of molar abundances for all species in the engine.
* @param T9 Temperature in units of 10^9 K.
* @param rho Density of the medium.
* @pre Y.size() matches engine.getNetworkReactions().size() mapping species order.
* @post Returned rate constant is non-negative.
* @return Sum of absolute stoichiometry-weighted destruction flows for the species.
*/
double calculateDestructionRateConstant(
const DynamicEngine& engine,
const fourdst::atomic::Species& species,
const std::vector<double>& Y,
double T9,
double rho
);
double calculateDestructionRateConstant(
const DynamicEngine& engine,
const fourdst::atomic::Species& species,
const std::vector<double>& Y,
double T9,
double rho
);
double calculateCreationRate(
const DynamicEngine& engine,
const fourdst::atomic::Species& species,
const std::vector<double>& Y,
double T9,
double rho
);
}
/**
* @brief Computes the creation rate for a specific species.
*
* Sums molar reaction flows for all reactions where the species
* appears as a product (positive stoichiometry).
*
* @param engine Engine providing the current set of network reactions and flow calculations.
* @param species The atomic species whose creation rate is computed.
* @param Y Vector of molar abundances for all species in the engine.
* @param T9 Temperature in units of 10^9 K.
* @param rho Density of the medium.
* @pre Y.size() matches engine.getNetworkReactions().size() mapping species order.
* @post Returned creation rate is non-negative.
* @return Sum of stoichiometry-weighted creation flows for the species.
*/
double calculateCreationRate(
const DynamicEngine& engine,
const fourdst::atomic::Species& species,
const std::vector<double>& Y,
double T9,
double rho
);
}

23
src/include/gridfire/engine/types/building.h
View File

@@ -3,6 +3,21 @@
#include <variant>
namespace gridfire {
/**
* @enum NetworkBuildDepth
* @brief Specifies supported depths for building the reaction network.
*
* Values:
* - Full: Build the complete network (infinite depth).
* - Shallow: Build only direct reactions (depth = 1).
* - SecondOrder: Include reactions up to second order (depth = 2).
* - ThirdOrder: Include reactions up to third order (depth = 3).
* - FourthOrder: Include reactions up to fourth order (depth = 4).
* - FifthOrder: Include reactions up to fifth order (depth = 5).
*
* @note For custom build depths, see BuildDepthType.
*/
enum class NetworkBuildDepth {
Full = -1,
Shallow = 1,
@@ -12,5 +27,13 @@ namespace gridfire {
FifthOrder = 5
};
/**
* @typedef BuildDepthType
* @brief Variant specifying either a predefined NetworkBuildDepth or a custom integer depth.
*
* @pre If using the integer alternative, the value must be >= 0 or -1 to indicate a full build.
* @post The network builder will interpret and apply the specified depth to control reaction expansion.
*/
using BuildDepthType = std::variant<NetworkBuildDepth, int>;
}

58
src/include/gridfire/engine/types/reporting.h
View File

@@ -3,8 +3,31 @@
#include <map>
#include <string>
#include <ranges>
// Required for PrimingReport fields and streaming
#include <vector>
#include <utility>
#include <ostream>
#include <sstream>
#include "fourdst/composition/composition.h"
#include "fourdst/composition/atomicSpecies.h"
namespace gridfire {
/**
* @enum PrimingReportStatus
* @brief Enumerates outcome codes for a network priming operation.
*
* These status codes indicate the reason for success or failure of the priming process:
* - FULL_SUCCESS: Priming completed successfully with all species processed.
* - NO_SPECIES_TO_PRIME: There were no species eligible for priming.
* - MAX_ITERATIONS_REACHED: The algorithm reached its iteration limit without converging.
* - FAILED_TO_FINALIZE_COMPOSITION: Unable to build a valid Composition object at end.
* - FAILED_TO_FIND_CREATION_CHANNEL: No reaction path found to create the priming species.
* - FAILED_TO_FIND_PRIMING_REACTIONS: No reactions containing the priming species were found.
* - BASE_NETWORK_TOO_SHALLOW: The provided base network depth was insufficient for priming.
*
* @see PrimingReport for data associated with each status.
*/
enum class PrimingReportStatus {
FULL_SUCCESS = 0,
NO_SPECIES_TO_PRIME = 1,
@@ -15,6 +38,12 @@ namespace gridfire {
BASE_NETWORK_TOO_SHALLOW = 6
};
/**
* @brief Mapping from PrimingReportStatus codes to human-readable strings.
*
* Used when formatting or logging the priming status. No preconditions.
* The map contains entries for all PrimingReportStatus values.
*/
inline std::map<PrimingReportStatus, std::string> PrimingReportStatusStrings = {
{PrimingReportStatus::FULL_SUCCESS, "Full Success"},
{PrimingReportStatus::NO_SPECIES_TO_PRIME, "No Species to Prime"},
@@ -25,12 +54,38 @@ namespace gridfire {
{PrimingReportStatus::BASE_NETWORK_TOO_SHALLOW, "Base Network Too Shallow"}
};
/**
* @struct PrimingReport
* @brief Captures the result of a network priming operation.
*
* Contains the finalized composition, the changes in mass fractions for species,
* a success flag, and a detailed status code.
*
* @pre A priming algorithm must be executed before constructing a valid report.
* @post All fields reflect the outcome of the priming run.
*/
struct PrimingReport {
/** Finalized composition after priming. */
fourdst::composition::Composition primedComposition;
std::vector<std::pair<fourdst::atomic::Species, double>> massFractionChanges; ///< Species and their destruction/creation rates
/**
* List of pairs (species, rate change) representing destruction (<0)
* or creation (>0) rates of species during priming.
*/
std::vector<std::pair<fourdst::atomic::Species, double>> massFractionChanges;
/** True if priming completed without error. */
bool success;
/** Detailed status code indicating the result. */
PrimingReportStatus status;
/**
* @brief Serialize the report to a stream.
*
* Formats the success flag and status string into the output stream.
* @param os Output stream to write to.
* @param report Report to serialize.
* @return Reference to the modified output stream.
* @post The stream contains a textual representation of the report.
*/
friend std::ostream& operator<<(std::ostream& os, const PrimingReport& report) {
std::stringstream ss;
const std::string successStr = report.success ? "true" : "false";
@@ -39,4 +94,5 @@ namespace gridfire {
return os << ss.str();
}
};
}

40
src/include/gridfire/engine/views/engine_priming.h
View File

@@ -16,9 +16,39 @@
namespace gridfire {
/**
* @class NetworkPrimingEngineView
* @brief Provides a view of a DynamicEngine filtered to reactions involving a specified priming species.
*
* This view constructs a subset of the network reactions from the base engine that
* contain the given priming species and delegates all engine operations to the underlying engine.
*
* See implementation in engine_priming.cpp for details on reaction set construction.
*
* @note Throws std::runtime_error if no priming reactions are found for the species.
*/
class NetworkPrimingEngineView final : public DefinedEngineView {
public:
/**
* @brief Constructs the view by looking up the priming species by symbol.
*
* @param primingSymbol Symbol string of the species to prime.
* @param baseEngine Reference to the base DynamicEngine to wrap.
* @pre primingSymbol must correspond to a valid species in atomic::species registry.
* @post The view will contain only reactions that involve the priming species.
* @throws std::out_of_range If primingSymbol is not found in the species registry.
* @throws std::runtime_error If no reactions contain the priming species.
*/
NetworkPrimingEngineView(const std::string& primingSymbol, DynamicEngine& baseEngine);
/**
* @brief Constructs the view using an existing Species object.
*
* @param primingSpecies The species object to prime.
* @param baseEngine Reference to the base DynamicEngine to wrap.
* @pre primingSpecies must be valid and present in the network of baseEngine.
* @post The view will contain only reactions that involve the priming species.
* @throws std::runtime_error If no reactions contain the priming species.
*/
NetworkPrimingEngineView(const fourdst::atomic::Species& primingSpecies, DynamicEngine& baseEngine);
@@ -26,6 +56,16 @@ namespace gridfire {
quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log");
fourdst::atomic::Species m_primingSpecies; ///< The priming species, if specified.
private:
/**
* @brief Constructs the set of reaction names that involve the priming species.
*
* @param primingSpecies Species for which to collect priming reactions.
* @param baseEngine Base engine containing the full network of reactions.
* @pre baseEngine.getNetworkReactions() returns a valid iterable set of reactions.
* @post Returns a vector of unique reaction name strings containing the priming species.
* @return Vector of reaction name strings containing the priming species.
* @throws std::runtime_error If no reactions involve the priming species.
*/
std::vector<std::string> constructPrimingReactionSet(
const fourdst::atomic::Species& primingSpecies,
const DynamicEngine& baseEngine