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

docs(ridfire)

Browse Source 
Added more documentation, also moved all engine code into
gridfire::engine namespace to be more in line with other parts of teh
code base
This commit is contained in:
Emily Boudreaux
2025-11-24 09:07:49 -05:00
parent 15ed7f70b1
commit 9fab4fbfae
64 changed files with 2506 additions and 848 deletions
Download Patch File Download Diff File Expand all files Collapse all files

256
src/include/gridfire/policy/chains.h
View File

@@ -23,32 +23,117 @@
#include <memory>
namespace gridfire::policy {
/**
* @brief Base class for reaction chain policies that are active only within specific temperature ranges.
*
* Such chains may only operate effectively within certain temperature regimes, reflecting
* the physical conditions required for the reactions to proceed. This class allows defining
* such temperature-dependent behavior. This is one of the locations where domain specific knowledge is allowed
* within GridFire.
*/
class TemperatureDependentChainPolicy : public ReactionChainPolicy {
public:
/**
* @brief Construct a new Temperature Dependent Chain Policy object
* @param reactionIDs Vector of reaction IDs that comprise the chain
*
* @note The chain is considered active at all temperatures if no min/max T9 are provided.
*/
explicit TemperatureDependentChainPolicy(const std::vector<std::string>& reactionIDs);
/**
* @brief Construct a new Temperature Dependent Chain Policy object
* @param reactionIDs Vector of reaction IDs that comprise the chain
* @param minT9 Minimum temperature (in T9) for which the chain is active
*
* @note The chain is considered active at all temperatures above minT9.
*/
explicit TemperatureDependentChainPolicy(const std::vector<std::string>& reactionIDs, std::optional<double> minT9);
/**
* @brief Construct a new Temperature Dependent Chain Policy object
* @param reactionIDs Vector of reaction IDs that comprise the chain
* @param minT9 Minimum temperature (in T9) for which the chain is active
* @param maxT9 Maximum temperature (in T9) for which the chain is active
*/
explicit TemperatureDependentChainPolicy(const std::vector<std::string>& reactionIDs, std::optional<double> minT9, std::optional<double> maxT9);
/**
* @brief Virtual destructor
*/
~TemperatureDependentChainPolicy() override = default;
/**
* @brief Get the reactions that comprise the chain
* @return The set of reactions comprising the chain
*/
[[nodiscard]] const reaction::ReactionSet& get_reactions() const override;
/**
* @brief Check if a reaction or reaction ID is part of the chain
* @param id The reaction ID to check
* @return True if the reaction ID is part of the chain, false otherwise
*/
[[nodiscard]] bool contains(const std::string& id) const override;
/**
* @brief Check if a reaction is part of the chain
* @param reaction The reaction to check
* @return True if the reaction is part of the chain, false otherwise
*/
[[nodiscard]] bool contains(const reaction::Reaction& reaction) const override;
/**
* @brief Generate the hash for the reaction chain policy
* @param seed Seed value for the hash
* @return Unique hash representing the reaction chain policy. XXHash64 is used internally for speed and collision resistance.
*/
[[nodiscard]] uint64_t hash(uint64_t seed) const override;
/**
* @brief Equality operator
* @param other The other ReactionChainPolicy to compare against
* @return True if the two policies are equal, false otherwise
*/
[[nodiscard]] bool operator==(const ReactionChainPolicy& other) const override;
/**
* @brief Inequality operator
* @param other The other ReactionChainPolicy to compare against
* @return True if the two policies are not equal, false otherwise
*/
[[nodiscard]] bool operator!=(const ReactionChainPolicy& other) const override;
/**
* @brief Check if the reaction chain is active at a given temperature
* @param T9 Temperature in billions of Kelvin (T9)
* @return True if the chain is active at the given temperature, false otherwise
*/
[[nodiscard]] bool is_active(double T9) const;
protected:
/**
* @brief Struct to hold the active temperature range for the reaction chain
*/
struct ActiveTempRange {
std::optional<double> minT9;
std::optional<double> maxT9;
std::optional<double> minT9; ///< Minimum temperature (in T9) for which the chain is active
std::optional<double> maxT9; ///< Maximum temperature (in T9) for which the chain is active
};
ActiveTempRange m_tempRange;
std::vector<std::string> m_reactionIDs;
reaction::ReactionSet m_reactions;
ActiveTempRange m_tempRange; ///< Active temperature range for the reaction chain
std::vector<std::string> m_reactionIDs; ///< Vector of reaction IDs that comprise the chain
reaction::ReactionSet m_reactions; ///< Set of reactions that comprise the chain
};
/**
* @brief Proton-Proton I Chain Policy
*
* This class implements the Proton-Proton I chain of nuclear reactions. This chain's minimum temperature is
* set to T9=0.001 (or 1e6K). This chain includes reactions:
* - p(p,e+)d
* - d(p,g)he3
* - he3(he3,2p)he4
*/
class ProtonProtonIChainPolicy final: public TemperatureDependentChainPolicy {
public:
ProtonProtonIChainPolicy();
@@ -58,6 +143,17 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief Proton-Proton II Chain Policy
*
* This class implements the Proton-Proton II chain of nuclear reactions. This chain's minimum temperature is
* set to T9=0.001 (or 1e6K). This chain includes reactions:
* - p(p,e+)d
* - d(p,g)he3
* - he4(he3,g)be7
* - be7(e-,)li7
* - li7(p,a)he4
*/
class ProtonProtonIIChainPolicy final: public TemperatureDependentChainPolicy {
public:
ProtonProtonIIChainPolicy();
@@ -67,6 +163,17 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief Proton-Proton III Chain Policy
*
* This class implements the Proton-Proton III chain of nuclear reactions. This chain's minimum temperature is
* set to T9=0.001 (or 1e6K). This chain includes reactions:
* - p(p,e+)d
* - d(p,g)he3
* - he4(he3,g)be7
* - be7(p,g)b8
* - b8(,e+ a)he4
*/
class ProtonProtonIIIChainPolicy final: public TemperatureDependentChainPolicy {
public:
ProtonProtonIIIChainPolicy();
@@ -76,6 +183,17 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief Proton-Proton Chain Policy
*
* This class implements the overall Proton-Proton chain of nuclear reactions, combining the
* Proton-Proton I, II, and III chains. Enforcing this chain in the policy will ensure that all the
* Proton-Proton reactions are included in the network.
*
* @see ProtonProtonIChainPolicy
* @see ProtonProtonIIChainPolicy
* @see ProtonProtonIIIChainPolicy
*/
class ProtonProtonChainPolicy final : public MultiReactionChainPolicy {
public:
ProtonProtonChainPolicy();
@@ -84,6 +202,18 @@ namespace gridfire::policy {
std::vector<std::unique_ptr<ReactionChainPolicy>> m_chain_policies;
};
/**
* @brief CNO I Chain Policy
*
* This class implements the CNO I cycle of nuclear reactions. This chain's minimum temperature is
* set to T9=0.001 (or 1e6K). This chain includes reactions:
* - c12(p,g)n13
* - n13(,e+)c13
* - c13(p,g)n14
* - n14(p,g)o15
* - o15(,e+)n15
* - n15(p,a)c12
*/
class CNOIChainPolicy final : public TemperatureDependentChainPolicy {
public:
CNOIChainPolicy();
@@ -92,6 +222,18 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief CNO II Chain Policy
*
* This class implements the CNO II cycle of nuclear reactions. This chain's minimum temperature is
* set to T9=0.001 (or 1e6K). This chain includes reactions:
* - n15(p,g)o16
* - o16(p,g)f17
* - f17(p,g)ne18
* - ne18(,e+)f18
* - f18(p,a)o15
* - o15(,e+)n15
*/
class CNOIIChainPolicy final : public TemperatureDependentChainPolicy {
public:
CNOIIChainPolicy();
@@ -100,6 +242,18 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief CNO III Chain Policy
*
* This class implements the CNO III cycle of nuclear reactions. This chain's minimum temperature is
* set to T9=0.001 (or 1e6K). This chain includes reactions:
* - o17(p,g)f18
* - f18(,e+)o18
* - o18(p,a)n15
* - n15(p,g)o16
* - o16(p,g)f17
* - f17(,e+)o17
*/
class CNOIIIChainPolicy final : public TemperatureDependentChainPolicy {
public:
CNOIIIChainPolicy();
@@ -108,6 +262,18 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief CNO IV Chain Policy
*
* This class implements the CNO IV cycle of nuclear reactions. This chain's minimum temperature is
* set to T9=0.001 (or 1e6K). This chain includes reactions:
* - o18(p,g)f19
* - f19(p,a)o16
* - o16(p,g)f17
* - f17(,e+)o17
* - o17(p,g)f18
* - f18(,e+)o18
*/
class CNOIVChainPolicy final : public TemperatureDependentChainPolicy {
public:
CNOIVChainPolicy();
@@ -116,12 +282,36 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief CNO Chain Policy
*
* This class implements the overall CNO cycle of nuclear reactions, combining the
* CNO I, II, III, and IV chains. Enforcing this chain in the policy will ensure that all the
* CNO reactions are included in the network.
*
* @see CNOIChainPolicy
* @see CNOIIChainPolicy
* @see CNOIIIChainPolicy
* @see CNOIVChainPolicy
*/
class CNOChainPolicy final : public MultiReactionChainPolicy {
public:
CNOChainPolicy();
[[nodiscard]] std::string name() const override;
};
/**
* @brief Hot CNO I Chain Policy
*
* This class implements the Hot CNO I cycle of nuclear reactions. This chain's minimum temperature is
* set to T9=0.1 (or 1e8K). This chain includes reactions:
* - c12(p,g)n13
* - n13(p,g)o14
* - o14(,e+)n14
* - n14(p,g)o15
* - o15(,e+)n15
* - n15(p,a)c12
*/
class HotCNOIChainPolicy final : public TemperatureDependentChainPolicy {
public:
HotCNOIChainPolicy();
@@ -129,6 +319,18 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief Hot CNO II Chain Policy
*
* This class implements the Hot CNO II cycle of nuclear reactions. This chain's minimum temperature is
* set to T9=0.1 (or 1e8K). This chain includes reactions:
* - n15(p,g)o16
* - o16(p,g)f17
* - f17(p,g)ne18
* - ne18(,e+)f18
* - f18(p,a)o15
* - o15(,e+)n15
*/
class HotCNOIIChainPolicy final : public TemperatureDependentChainPolicy {
public:
HotCNOIIChainPolicy();
@@ -136,6 +338,18 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief Hot CNO III Chain Policy
*
* This class implements the Hot CNO III cycle of nuclear reactions. This chain's minimum temperature is
* set to T9=0.1 (or 1e8K). This chain includes reactions:
* - f18(p,g)ne19
* - ne19(,e+)f19
* - f19(p,a)o16
* - o16(p,g)f17
* - f17(p,g)ne18
* - ne18(,e+)f18
*/
class HotCNOIIIChainPolicy final : public TemperatureDependentChainPolicy {
public:
HotCNOIIIChainPolicy();
@@ -143,12 +357,31 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief Hot CNO Chain Policy
*
* This class implements the overall Hot CNO cycle of nuclear reactions, combining the
* Hot CNO I, II, and III chains. Enforcing this chain in the policy will ensure that all the
* Hot CNO reactions are included in the network.
*
* @see HotCNOIChainPolicy
* @see HotCNOIIChainPolicy
* @see HotCNOIIIChainPolicy
*/
class HotCNOChainPolicy final : public MultiReactionChainPolicy {
public:
HotCNOChainPolicy();
[[nodiscard]] std::string name() const override;
};
/**
* @brief Triple-Alpha Chain Policy
*
* This class implements the Triple-Alpha process of nuclear reactions. This chain's minimum temperature is
* set to T9=0.01 (or 1e7K). This chain includes reactions:
* - he4(he4,a)be8
* - be8(he4,g)c12
*/
class TripleAlphaChainPolicy final : public TemperatureDependentChainPolicy {
public:
TripleAlphaChainPolicy();
@@ -158,7 +391,16 @@ namespace gridfire::policy {
[[nodiscard]] std::string name() const override;
};
/**
* @brief Main Sequence Reaction Chain Policy
*
* This class implements the main sequence reaction chains, combining the
* Proton-Proton chain and the CNO cycle. Enforcing this chain in the policy will ensure that all the
* primary reactions for main sequence stars are included in the network.
*
* @see ProtonProtonChainPolicy
* @see CNOChainPolicy
*/
class MainSequenceReactionChainPolicy final : public MultiReactionChainPolicy {
public:
MainSequenceReactionChainPolicy();

6
src/include/gridfire/policy/policy.h
View File

@@ -0,0 +1,6 @@
#pragma once
#include "gridfire/policy/policy_abstract.h"
#include "gridfire/policy/policy_logical.h"
#include "gridfire/policy/chains.h"
#include "gridfire/policy/stellar_policy.h"

12
src/include/gridfire/policy/policy_abstract.h
View File

@@ -11,12 +11,6 @@
* example:
* - gridfire/policy/stellar_policy.h (concrete stellar network policy used in many examples)
* - gridfire/policy/chains.h (reaction-chain helper policies such as proton-proton, CNO)
*
* An example of using a concrete policy to construct and run an engine is available at:
* - tests/graphnet_sandbox/main.cpp
*
* @note Doxygen comments on public methods include @par Example usage blocks. Methods that may
* throw in concrete implementations include @throws tags.
*/
#pragma once
@@ -145,7 +139,7 @@ namespace gridfire::policy {
* NetOut out = solver.evaluate(netIn, true);
* @endcode
*/
[[nodiscard]] virtual DynamicEngine& construct() = 0;
[[nodiscard]] virtual engine::DynamicEngine& construct() = 0;
/**
* @brief Returns the current verification/construction status of the policy.
@@ -161,9 +155,9 @@ namespace gridfire::policy {
*/
[[nodiscard]] virtual NetworkPolicyStatus getStatus() const = 0;
[[nodiscard]] virtual const std::vector<std::unique_ptr<DynamicEngine>> &get_engine_stack() const = 0;
[[nodiscard]] virtual const std::vector<std::unique_ptr<engine::DynamicEngine>> &get_engine_stack() const = 0;
[[nodiscard]] virtual std::vector<EngineTypes> get_engine_types_stack() const = 0;
[[nodiscard]] virtual std::vector<engine::EngineTypes> get_engine_types_stack() const = 0;
[[nodiscard]] virtual const std::unique_ptr<partition::PartitionFunction>& get_partition_function() const = 0;
};

185
src/include/gridfire/policy/policy_logical.h
View File

@@ -22,30 +22,211 @@ namespace gridfire::policy {
*/
class MultiReactionChainPolicy : public ReactionChainPolicy {
public:
/**
* @brief Constructs a MultiReactionChainPolicy from a vector of ReactionChainPolicy instances.
*
* The provided chain policies are moved into the new MultiReactionChainPolicy instance.
*
* @param chain_policies vector of unique_ptr to ReactionChainPolicy instances.
*
* @par Example
* @code
* std::vector<std::unique_ptr<ReactionChainPolicy>> chains;
* chains.push_back(std::make_unique<ProtonProtonChainPolicy>());
* chains.push_back(std::make_unique<CNOChainPolicy>());
* MultiReactionChainPolicy multi(std::move(chains));
* @endcode
*/
explicit MultiReactionChainPolicy(std::vector<std::unique_ptr<ReactionChainPolicy>>&& chain_policies);
/**
* @brief Returns the vector of child ReactionChainPolicy instances.
*
* @return const std::vector<std::unique_ptr<ReactionChainPolicy>>& reference to the child chain policies.
*
* @par Example
* @code
* const auto &chains = multi.get_chain_policies();
* for (const auto &ch : chains) { std::cout << ch->get_reactions().size() << " reactions\n"; }
* @endcode
*/
[[nodiscard]] const std::vector<std::unique_ptr<ReactionChainPolicy>>& get_chain_policies() const;
/**
* @brief Returns the combined ReactionSet of all child chain policies.
*
* @return const reaction::ReactionSet& reference to the combined reactions.
*
* @par Example
* @code
* const auto &reactions = multi.get_reactions();
* std::cout << "Multi chain contains " << reactions.size() << " reactions\n";
* @endcode
*/
[[nodiscard]] const reaction::ReactionSet& get_reactions() const override;
/**
* @brief Checks if the MultiReactionChainPolicy contains a reaction by ID
*
* @param id the reaction ID to check for.
* @return true if the reaction ID is present in the combined ReactionSet, false otherwise.
*
* @par Example
* @code
* bool has_pp = multi.contains("p(p,e+)d");
* @endcode
*/
[[nodiscard]] bool contains(const std::string &id) const override;
/**
* @brief Checks if the MultiReactionChainPolicy contains a specific reaction.
*
* @param reaction the Reaction to check for.
* @return true if the reaction is present in the combined ReactionSet, false otherwise.
*
* @par Example
* @code
* reaction::Reaction r = ...; // obtain a Reaction instance
* bool has_reaction = multi.contains(r);
* @endcode
*/
[[nodiscard]] bool contains(const reaction::Reaction &reaction) const override;
/**
* @brief Creates a deep copy of the MultiReactionChainPolicy.
*
* @return std::unique_ptr<ReactionChainPolicy> unique pointer to the cloned instance.
*
* @par Example
* @code
* std::unique_ptr<ReactionChainPolicy> clone = multi.clone();
* @endcode
*/
[[nodiscard]] std::unique_ptr<ReactionChainPolicy> clone() const override;
/**
* @brief Returns the name of the MultiReactionChainPolicy.
*
* @return std::string the name of the policy.
*
* @par Example
* @code
* std::string n = multi.name();
* std::cout << "Using policy: " << n << std::endl;
* @endcode
*/
[[nodiscard]] std::string name() const override;
/**
* @brief Computes a hash value for the MultiReactionChainPolicy.
*
* @param seed the seed value for the hash computation.
* @return uint64_t the computed hash value.
*
* @par Example
* @code
* uint64_t h = multi.hash(0);
* std::cout << "Policy hash: " << h << std::endl;
* @endcode
*/
[[nodiscard]] uint64_t hash(uint64_t seed) const override;
/**
* @brief Equality comparison operator.
*
* @param other the other ReactionChainPolicy to compare against.
* @return true if the policies are equal, false otherwise.
*
* @par Example
* @code
* bool equal = (multi1 == multi2);
* @endcode
*/
[[nodiscard]] bool operator==(const ReactionChainPolicy& other) const override;
/**
* @brief Inequality comparison operator.
*
* @param other the other ReactionChainPolicy to compare against.
* @return true if the policies are not equal, false otherwise.
*
* @par Example
* @code
* bool not_equal = (multi1 != multi2);
* @endcode
*/
[[nodiscard]] bool operator!=(const ReactionChainPolicy& other) const override;
/**
* @brief Returns the number of child ReactionChainPolicy instances.
*
* @return size_t the number of child chain policies.
*
* @par Example
* @code
* size_t n = multi.size();
* std::cout << "Multi chain has " << n << " child policies\n";
* @endcode
*/
[[nodiscard]] size_t size() const;
/**
* @brief Returns iterator to the beginning of the child ReactionChainPolicy instances.
*
* @return iterator to the beginning.
*
* @par Example
* @code
* for (auto it = multi.begin(); it != multi.end(); ++it) {
* std::cout << (*it)->name() << std::endl;
* }
* @endcode
*/
auto begin() { return m_chain_policies.begin(); }
/**
* @brief Returns const iterator to the beginning of the child ReactionChainPolicy instances.
*
* @return const iterator to the beginning.
*
* @par Example
* @code
* for (auto it = multi.begin(); it != multi.end(); ++it) {
* std::cout << (*it)->name() << std::endl;
* }
* @endcode
*/
[[nodiscard]] auto begin() const { return m_chain_policies.cbegin(); }
/**
* @brief Returns iterator to the end of the child ReactionChainPolicy instances.
*
* @return iterator to the end.
*
* @par Example
* @code
* for (auto it = multi.begin(); it != multi.end(); ++it) {
* std::cout << (*it)->name() << std::endl;
* }
* @endcode
*/
auto end() { return m_chain_policies.end(); }
/**
* @brief Returns const iterator to the end of the child ReactionChainPolicy instances.
*
* @return const iterator to the end.
*
* @par Example
* @code
* for (auto it = multi.begin(); it != multi.end(); ++it) {
* std::cout << (*it)->name() << std::endl;
* }
* @endcode
*/
[[nodiscard]] auto end() const { return m_chain_policies.cend(); }
protected:
std::vector<std::unique_ptr<ReactionChainPolicy>> m_chain_policies{};
reaction::ReactionSet m_reactions;
std::vector<std::unique_ptr<ReactionChainPolicy>> m_chain_policies{}; ///< Child chain policies
reaction::ReactionSet m_reactions; ///< Combined reactions from all child policies
};
}

18
src/include/gridfire/policy/stellar_policy.h
View File

@@ -135,7 +135,7 @@ namespace gridfire::policy {
* // ... run solver ...
* @endcode
*/
DynamicEngine& construct() override;
engine::DynamicEngine& construct() override;
/**
* @brief Gets the current status of the policy.
@@ -143,20 +143,20 @@ namespace gridfire::policy {
*/
[[nodiscard]] NetworkPolicyStatus getStatus() const override;
[[nodiscard]] const std::vector<std::unique_ptr<DynamicEngine>> &get_engine_stack() const override;
[[nodiscard]] const std::vector<std::unique_ptr<engine::DynamicEngine>> &get_engine_stack() const override;
[[nodiscard]] std::vector<EngineTypes> get_engine_types_stack() const override;
[[nodiscard]] std::vector<engine::EngineTypes> get_engine_types_stack() const override;
[[nodiscard]] const std::unique_ptr<partition::PartitionFunction>& get_partition_function() const override;
private:
std::set<fourdst::atomic::Species> m_seed_species;
std::set<fourdst::atomic::Species> m_seed_species; ///< The set of seed species required by this policy. These are H-1, He-3, He-4, C-12, N-14, O-16, Ne-20, Mg-24.
std::unique_ptr<ReactionChainPolicy> m_reaction_policy = std::make_unique<MainSequenceReactionChainPolicy>();
fourdst::composition::Composition m_initializing_composition;
std::unique_ptr<partition::PartitionFunction> m_partition_function;
std::vector<std::unique_ptr<DynamicEngine>> m_network_stack;
std::unique_ptr<ReactionChainPolicy> m_reaction_policy = std::make_unique<MainSequenceReactionChainPolicy>(); ///< The composed reaction chain policy (PP-chain + CNO-cycle).
fourdst::composition::Composition m_initializing_composition; ///< The initial composition used to build the network.
std::unique_ptr<partition::PartitionFunction> m_partition_function; ///< The partition function used in network construction.
std::vector<std::unique_ptr<engine::DynamicEngine>> m_network_stack; ///< The stack of dynamic engines constructed by the policy.
NetworkPolicyStatus m_status = NetworkPolicyStatus::UNINITIALIZED;
NetworkPolicyStatus m_status = NetworkPolicyStatus::UNINITIALIZED; ///< The current status of the policy.
private:
static std::unique_ptr<partition::PartitionFunction> build_partition_function();
[[nodiscard]] NetworkPolicyStatus check_status() const;