docs(docs): added extensive docs
This commit is contained in:
@@ -225,23 +225,59 @@ namespace gridfire {
|
||||
*/
|
||||
[[nodiscard]] const DynamicEngine& getBaseEngine() const override { return m_baseEngine; }
|
||||
|
||||
/**
|
||||
* @brief Sets the screening model for the base engine.
|
||||
*
|
||||
* This method delegates the call to the base engine to set the electron screening model.
|
||||
*
|
||||
* @param model The electron screening model to set.
|
||||
*
|
||||
* @par Usage Example:
|
||||
* @code
|
||||
* AdaptiveEngineView engineView(...);
|
||||
* engineView.setScreeningModel(screening::ScreeningType::WEAK);
|
||||
* @endcode
|
||||
*
|
||||
* @post The screening model of the base engine is updated.
|
||||
*/
|
||||
void setScreeningModel(screening::ScreeningType model) override;
|
||||
|
||||
/**
|
||||
* @brief Gets the screening model from the base engine.
|
||||
*
|
||||
* This method delegates the call to the base engine to get the screening model.
|
||||
*
|
||||
* @return The current screening model type.
|
||||
*
|
||||
* @par Usage Example:
|
||||
* @code
|
||||
* AdaptiveEngineView engineView(...);
|
||||
* screening::ScreeningType model = engineView.getScreeningModel();
|
||||
* @endcode
|
||||
*/
|
||||
[[nodiscard]] screening::ScreeningType getScreeningModel() const override;
|
||||
private:
|
||||
using Config = fourdst::config::Config;
|
||||
using LogManager = fourdst::logging::LogManager;
|
||||
/** @brief A reference to the singleton Config instance, used for retrieving configuration parameters. */
|
||||
Config& m_config = Config::getInstance();
|
||||
/** @brief A pointer to the logger instance, used for logging messages. */
|
||||
quill::Logger* m_logger = LogManager::getInstance().getLogger("log");
|
||||
|
||||
/** @brief The underlying engine to which this view delegates calculations. */
|
||||
DynamicEngine& m_baseEngine;
|
||||
|
||||
/** @brief The set of species that are currently active in the network. */
|
||||
std::vector<fourdst::atomic::Species> m_activeSpecies;
|
||||
/** @brief The set of reactions that are currently active in the network. */
|
||||
reaction::LogicalReactionSet m_activeReactions;
|
||||
|
||||
/** @brief A map from the indices of the active species to the indices of the corresponding species in the full network. */
|
||||
std::vector<size_t> m_speciesIndexMap;
|
||||
/** @brief A map from the indices of the active reactions to the indices of the corresponding reactions in the full network. */
|
||||
std::vector<size_t> m_reactionIndexMap;
|
||||
|
||||
/** @brief A flag indicating whether the view is stale and needs to be updated. */
|
||||
bool m_isStale = true;
|
||||
|
||||
private:
|
||||
@@ -322,19 +358,92 @@ namespace gridfire {
|
||||
*/
|
||||
void validateState() const;
|
||||
|
||||
/**
|
||||
* @brief Calculates the molar reaction flow rate for all reactions in the full network.
|
||||
*
|
||||
* This method iterates through all reactions in the base engine's network and calculates
|
||||
* their molar flow rates based on the provided network input conditions (temperature, density,
|
||||
* and composition). It also constructs a vector of molar abundances for all species in the
|
||||
* full network.
|
||||
*
|
||||
* @param netIn The current network input, containing temperature, density, and composition.
|
||||
* @param out_Y_Full A vector that will be populated with the molar abundances of all species in the full network.
|
||||
* @return A vector of ReactionFlow structs, each containing a pointer to a reaction and its calculated flow rate.
|
||||
*
|
||||
* @par Algorithm:
|
||||
* 1. Clears and reserves space in `out_Y_Full`.
|
||||
* 2. Iterates through all species in the base engine's network.
|
||||
* 3. For each species, it retrieves the molar abundance from `netIn.composition`. If the species is not found, its abundance is set to 0.0.
|
||||
* 4. Converts the temperature from Kelvin to T9.
|
||||
* 5. Iterates through all reactions in the base engine's network.
|
||||
* 6. For each reaction, it calls the base engine's `calculateMolarReactionFlow` to get the flow rate.
|
||||
* 7. Stores the reaction pointer and its flow rate in a `ReactionFlow` struct and adds it to the returned vector.
|
||||
*/
|
||||
std::vector<ReactionFlow> calculateAllReactionFlows(
|
||||
const NetIn& netIn,
|
||||
std::vector<double>& out_Y_Full
|
||||
) const;
|
||||
/**
|
||||
* @brief Finds all species that are reachable from the initial fuel through the reaction network.
|
||||
*
|
||||
* This method performs a connectivity analysis to identify all species that can be produced
|
||||
* starting from the initial fuel species. A species is considered part of the initial fuel if its
|
||||
* mass fraction is above a certain threshold (`ABUNDANCE_FLOOR`).
|
||||
*
|
||||
* @param netIn The current network input, containing the initial composition.
|
||||
* @return An unordered set of all reachable species.
|
||||
*
|
||||
* @par Algorithm:
|
||||
* 1. Initializes a set `reachable` and a queue `to_visit` with the initial fuel species.
|
||||
* 2. Iteratively processes the reaction network until no new species can be reached.
|
||||
* 3. In each pass, it iterates through all reactions in the base engine's network.
|
||||
* 4. If all reactants of a reaction are in the `reachable` set, all products of that reaction are added to the `reachable` set.
|
||||
* 5. The process continues until a full pass over all reactions does not add any new species to the `reachable` set.
|
||||
*/
|
||||
[[nodiscard]] std::unordered_set<fourdst::atomic::Species> findReachableSpecies(
|
||||
const NetIn& netIn
|
||||
) const;
|
||||
/**
|
||||
* @brief Culls reactions from the network based on their flow rates.
|
||||
*
|
||||
* This method filters the list of all reactions, keeping only those with a flow rate
|
||||
* above an absolute culling threshold. The threshold is calculated by multiplying the
|
||||
* maximum flow rate by a relative culling threshold read from the configuration.
|
||||
*
|
||||
* @param allFlows A vector of all reactions and their flow rates.
|
||||
* @param reachableSpecies A set of all species reachable from the initial fuel.
|
||||
* @param Y_full A vector of molar abundances for all species in the full network.
|
||||
* @param maxFlow The maximum reaction flow rate in the network.
|
||||
* @return A vector of pointers to the reactions that have been kept after culling.
|
||||
*
|
||||
* @par Algorithm:
|
||||
* 1. Retrieves the `RelativeCullingThreshold` from the configuration.
|
||||
* 2. Calculates the `absoluteCullingThreshold` by multiplying `maxFlow` with the relative threshold.
|
||||
* 3. Iterates through `allFlows`.
|
||||
* 4. A reaction is kept if its `flowRate` is greater than the `absoluteCullingThreshold`.
|
||||
* 5. The pointers to the kept reactions are stored in a vector and returned.
|
||||
*/
|
||||
[[nodiscard]] std::vector<const reaction::LogicalReaction*> cullReactionsByFlow(
|
||||
const std::vector<ReactionFlow>& allFlows,
|
||||
const std::unordered_set<fourdst::atomic::Species>& reachableSpecies,
|
||||
const std::vector<double>& Y_full,
|
||||
double maxFlow
|
||||
) const;
|
||||
/**
|
||||
* @brief Finalizes the set of active species and reactions.
|
||||
*
|
||||
* This method takes the final list of culled reactions and populates the
|
||||
* `m_activeReactions` and `m_activeSpecies` members. The active species are
|
||||
* determined by collecting all reactants and products from the final reactions.
|
||||
* The active species list is then sorted by mass.
|
||||
*
|
||||
* @param finalReactions A vector of pointers to the reactions to be included in the active set.
|
||||
*
|
||||
* @post
|
||||
* - `m_activeReactions` is cleared and populated with the reactions from `finalReactions`.
|
||||
* - `m_activeSpecies` is cleared and populated with all unique species present in `finalReactions`.
|
||||
* - `m_activeSpecies` is sorted by atomic mass.
|
||||
*/
|
||||
void finalizeActiveSet(
|
||||
const std::vector<const reaction::LogicalReaction*>& finalReactions
|
||||
);
|
||||
|
||||
@@ -13,8 +13,45 @@
|
||||
#include <string>
|
||||
|
||||
namespace gridfire{
|
||||
/**
|
||||
* @class FileDefinedEngineView
|
||||
* @brief An engine view that uses a user-defined reaction network from a file.
|
||||
*
|
||||
* This class implements an EngineView that restricts the reaction network to a specific set of
|
||||
* reactions defined in an external file. It acts as a filter or a view on a larger, more
|
||||
* comprehensive base engine. The file provides a list of reaction identifiers, and this view
|
||||
* will only consider those reactions and the species involved in them.
|
||||
*
|
||||
* This is useful for focusing on a specific sub-network for analysis, debugging, or performance
|
||||
* reasons, without modifying the underlying full network.
|
||||
*
|
||||
* The view maintains mappings between the indices of its active (defined) species and reactions
|
||||
* and the corresponding indices in the full network of the base engine. All calculations are
|
||||
* delegated to the base engine after mapping the inputs from the view's context to the full
|
||||
* network context, and the results are mapped back.
|
||||
*
|
||||
* @implements DynamicEngine
|
||||
* @implements EngineView<DynamicEngine>
|
||||
*/
|
||||
class FileDefinedEngineView final: public DynamicEngine, public EngineView<DynamicEngine> {
|
||||
public:
|
||||
/**
|
||||
* @brief Constructs a FileDefinedEngineView.
|
||||
*
|
||||
* @param baseEngine The underlying DynamicEngine to which this view delegates calculations.
|
||||
* @param fileName The path to the file that defines the reaction network for this view.
|
||||
* @param parser A reference to a parser object capable of parsing the network file.
|
||||
*
|
||||
* @par Usage Example:
|
||||
* @code
|
||||
* MyParser parser;
|
||||
* DynamicEngine baseEngine(...);
|
||||
* FileDefinedEngineView view(baseEngine, "my_network.net", parser);
|
||||
* @endcode
|
||||
*
|
||||
* @post The view is initialized with the reactions and species from the specified file.
|
||||
* @throws std::runtime_error If a reaction from the file is not found in the base engine.
|
||||
*/
|
||||
explicit FileDefinedEngineView(
|
||||
DynamicEngine& baseEngine,
|
||||
const std::string& fileName,
|
||||
@@ -22,104 +59,246 @@ namespace gridfire{
|
||||
);
|
||||
|
||||
// --- EngineView Interface ---
|
||||
/**
|
||||
* @brief Gets the base engine.
|
||||
* @return A const reference to the base engine.
|
||||
*/
|
||||
const DynamicEngine& getBaseEngine() const override;
|
||||
|
||||
// --- Engine Interface ---
|
||||
/**
|
||||
* @brief Gets the list of active species in the network defined by the file.
|
||||
* @return A const reference to the vector of active species.
|
||||
*/
|
||||
const std::vector<fourdst::atomic::Species>& getNetworkSpecies() const override;
|
||||
|
||||
// --- DynamicEngine Interface ---
|
||||
/**
|
||||
* @brief Calculates the right-hand side (dY/dt) and energy generation for the active species.
|
||||
*
|
||||
* @param Y_defined A vector of abundances for the active species.
|
||||
* @param T9 The temperature in units of 10^9 K.
|
||||
* @param rho The density in g/cm^3.
|
||||
* @return A StepDerivatives struct containing the derivatives of the active species and the
|
||||
* nuclear energy generation rate.
|
||||
*
|
||||
* @throws std::runtime_error If the view is stale (i.e., `update()` has not been called after `setNetworkFile()`).
|
||||
*/
|
||||
StepDerivatives<double> calculateRHSAndEnergy(
|
||||
const std::vector<double>& Y_defined,
|
||||
const double T9,
|
||||
const double rho
|
||||
) const override;
|
||||
/**
|
||||
* @brief Generates the Jacobian matrix for the active species.
|
||||
*
|
||||
* @param Y_defined A vector of abundances for the active species.
|
||||
* @param T9 The temperature in units of 10^9 K.
|
||||
* @param rho The density in g/cm^3.
|
||||
*
|
||||
* @throws std::runtime_error If the view is stale.
|
||||
*/
|
||||
void generateJacobianMatrix(
|
||||
const std::vector<double>& Y_defined,
|
||||
const double T9,
|
||||
const double rho
|
||||
) override;
|
||||
/**
|
||||
* @brief Gets an entry from the Jacobian matrix for the active species.
|
||||
*
|
||||
* @param i_defined The row index (species index) in the defined matrix.
|
||||
* @param j_defined The column index (species index) in the defined matrix.
|
||||
* @return The value of the Jacobian matrix at (i_defined, j_defined).
|
||||
*
|
||||
* @throws std::runtime_error If the view is stale.
|
||||
* @throws std::out_of_range If an index is out of bounds.
|
||||
*/
|
||||
double getJacobianMatrixEntry(
|
||||
const int i_defined,
|
||||
const int j_defined
|
||||
) const override;
|
||||
/**
|
||||
* @brief Generates the stoichiometry matrix for the active reactions and species.
|
||||
*
|
||||
* @throws std::runtime_error If the view is stale.
|
||||
*/
|
||||
void generateStoichiometryMatrix() override;
|
||||
/**
|
||||
* @brief Gets an entry from the stoichiometry matrix for the active species and reactions.
|
||||
*
|
||||
* @param speciesIndex_defined The index of the species in the defined species list.
|
||||
* @param reactionIndex_defined The index of the reaction in the defined reaction list.
|
||||
* @return The stoichiometric coefficient for the given species and reaction.
|
||||
*
|
||||
* @throws std::runtime_error If the view is stale.
|
||||
* @throws std::out_of_range If an index is out of bounds.
|
||||
*/
|
||||
int getStoichiometryMatrixEntry(
|
||||
const int speciesIndex_defined,
|
||||
const int reactionIndex_defined
|
||||
) const override;
|
||||
/**
|
||||
* @brief Calculates the molar reaction flow for a given reaction in the active network.
|
||||
*
|
||||
* @param reaction The reaction for which to calculate the flow.
|
||||
* @param Y_defined Vector of current abundances for the active species.
|
||||
* @param T9 Temperature in units of 10^9 K.
|
||||
* @param rho Density in g/cm^3.
|
||||
* @return Molar flow rate for the reaction (e.g., mol/g/s).
|
||||
*
|
||||
* @throws std::runtime_error If the view is stale or if the reaction is not in the active set.
|
||||
*/
|
||||
double calculateMolarReactionFlow(
|
||||
const reaction::Reaction& reaction,
|
||||
const std::vector<double>& Y_defined,
|
||||
const double T9,
|
||||
const double rho
|
||||
) const override;
|
||||
/**
|
||||
* @brief Gets the set of active logical reactions in the network.
|
||||
*
|
||||
* @return Reference to the LogicalReactionSet containing all active reactions.
|
||||
*
|
||||
* @throws std::runtime_error If the view is stale.
|
||||
*/
|
||||
const reaction::LogicalReactionSet& getNetworkReactions() const override;
|
||||
/**
|
||||
* @brief Computes timescales for all active species in the network.
|
||||
*
|
||||
* @param Y_defined Vector of current abundances for the active species.
|
||||
* @param T9 Temperature in units of 10^9 K.
|
||||
* @param rho Density in g/cm^3.
|
||||
* @return Map from Species to their characteristic timescales (s).
|
||||
*
|
||||
* @throws std::runtime_error If the view is stale.
|
||||
*/
|
||||
std::unordered_map<fourdst::atomic::Species, double> getSpeciesTimescales(
|
||||
const std::vector<double>& Y_defined,
|
||||
const double T9,
|
||||
const double rho
|
||||
) const override;
|
||||
|
||||
/**
|
||||
* @brief Updates the engine view if it is marked as stale.
|
||||
*
|
||||
* This method checks if the view is stale (e.g., after `setNetworkFile` was called).
|
||||
* If it is, it rebuilds the active network from the currently set file.
|
||||
* The `netIn` parameter is not used by this implementation but is required by the interface.
|
||||
*
|
||||
* @param netIn The current network input (unused).
|
||||
*
|
||||
* @post If the view was stale, it is rebuilt and is no longer stale.
|
||||
*/
|
||||
void update(const NetIn &netIn) override;
|
||||
|
||||
/**
|
||||
* @brief Sets a new network file to define the active reactions.
|
||||
*
|
||||
* @param fileName The path to the new network definition file.
|
||||
*
|
||||
* @par Usage Example:
|
||||
* @code
|
||||
* view.setNetworkFile("another_network.net");
|
||||
* view.update(netIn); // Must be called before using the view again
|
||||
* @endcode
|
||||
*
|
||||
* @post The view is marked as stale. `update()` must be called before further use.
|
||||
*/
|
||||
void setNetworkFile(const std::string& fileName);
|
||||
|
||||
/**
|
||||
* @brief Sets the screening model for the base engine.
|
||||
*
|
||||
* @param model The screening model to set.
|
||||
*/
|
||||
void setScreeningModel(screening::ScreeningType model) override;
|
||||
|
||||
/**
|
||||
* @brief Gets the screening model from the base engine.
|
||||
*
|
||||
* @return The current screening model type.
|
||||
*/
|
||||
[[nodiscard]] screening::ScreeningType getScreeningModel() const override;
|
||||
private:
|
||||
using Config = fourdst::config::Config;
|
||||
using LogManager = fourdst::logging::LogManager;
|
||||
/** @brief A reference to the singleton Config instance. */
|
||||
Config& m_config = Config::getInstance();
|
||||
/** @brief A pointer to the logger instance. */
|
||||
quill::Logger* m_logger = LogManager::getInstance().getLogger("log");
|
||||
|
||||
/** @brief The underlying engine to which this view delegates calculations. */
|
||||
DynamicEngine& m_baseEngine;
|
||||
std::string m_fileName; ///< Name of the file defining the reaction set considered by the engine view.
|
||||
const io::NetworkFileParser& m_parser; ///< Parser for the network file.
|
||||
///< Name of the file defining the reaction set considered by the engine view.
|
||||
std::string m_fileName;
|
||||
///< Parser for the network file.
|
||||
const io::NetworkFileParser& m_parser;
|
||||
|
||||
std::vector<fourdst::atomic::Species> m_activeSpecies; ///< Active species in the defined engine.
|
||||
reaction::LogicalReactionSet m_activeReactions; ///< Active reactions in the defined engine.
|
||||
///< Active species in the defined engine.
|
||||
std::vector<fourdst::atomic::Species> m_activeSpecies;
|
||||
///< Active reactions in the defined engine.
|
||||
reaction::LogicalReactionSet m_activeReactions;
|
||||
|
||||
std::vector<size_t> m_speciesIndexMap; ///< Maps indices of active species to indices in the full network.
|
||||
std::vector<size_t> m_reactionIndexMap; ///< Maps indices of active reactions to indices in the full network.
|
||||
///< Maps indices of active species to indices in the full network.
|
||||
std::vector<size_t> m_speciesIndexMap;
|
||||
///< Maps indices of active reactions to indices in the full network.
|
||||
std::vector<size_t> m_reactionIndexMap;
|
||||
|
||||
/** @brief A flag indicating whether the view is stale and needs to be updated. */
|
||||
bool m_isStale = true;
|
||||
|
||||
private:
|
||||
/**
|
||||
* @brief Builds the active species and reaction sets from a file.
|
||||
*
|
||||
* This method uses the provided parser to read reaction names from the given file.
|
||||
* It then finds these reactions in the base engine's full network and populates
|
||||
* the `m_activeReactions` and `m_activeSpecies` members. Finally, it constructs
|
||||
* the index maps for the active sets.
|
||||
*
|
||||
* @param fileName The path to the network definition file.
|
||||
*
|
||||
* @post
|
||||
* - `m_activeReactions` and `m_activeSpecies` are populated.
|
||||
* - `m_speciesIndexMap` and `m_reactionIndexMap` are constructed.
|
||||
* - `m_isStale` is set to false.
|
||||
*
|
||||
* @throws std::runtime_error If a reaction from the file is not found in the base engine.
|
||||
*/
|
||||
void buildFromFile(const std::string& fileName);
|
||||
|
||||
/**
|
||||
* @brief Constructs the species index map.
|
||||
*
|
||||
* @return A vector mapping culled species indices to full species indices.
|
||||
* @return A vector mapping defined species indices to full species indices.
|
||||
*
|
||||
* This method creates a map from the indices of the active species to the indices of the
|
||||
* corresponding species in the full network.
|
||||
*
|
||||
* @see AdaptiveEngineView::update()
|
||||
* @throws std::runtime_error If an active species is not found in the base engine's species list.
|
||||
*/
|
||||
std::vector<size_t> constructSpeciesIndexMap() const;
|
||||
|
||||
/**
|
||||
* @brief Constructs the reaction index map.
|
||||
*
|
||||
* @return A vector mapping culled reaction indices to full reaction indices.
|
||||
* @return A vector mapping defined reaction indices to full reaction indices.
|
||||
*
|
||||
* This method creates a map from the indices of the active reactions to the indices of the
|
||||
* corresponding reactions in the full network.
|
||||
*
|
||||
* @see AdaptiveEngineView::update()
|
||||
* @throws std::runtime_error If an active reaction is not found in the base engine's reaction list.
|
||||
*/
|
||||
std::vector<size_t> constructReactionIndexMap() const;
|
||||
|
||||
/**
|
||||
* @brief Maps a vector of culled abundances to a vector of full abundances.
|
||||
*
|
||||
* @param culled A vector of abundances for the active species.
|
||||
* @param defined A vector of abundances for the active species.
|
||||
* @return A vector of abundances for the full network, with the abundances of the active
|
||||
* species copied from the culled vector.
|
||||
* species copied from the defined vector.
|
||||
*/
|
||||
std::vector<double> mapViewToFull(const std::vector<double>& culled) const;
|
||||
std::vector<double> mapViewToFull(const std::vector<double>& defined) const;
|
||||
|
||||
/**
|
||||
* @brief Maps a vector of full abundances to a vector of culled abundances.
|
||||
@@ -133,23 +312,28 @@ namespace gridfire{
|
||||
/**
|
||||
* @brief Maps a culled species index to a full species index.
|
||||
*
|
||||
* @param culledSpeciesIndex The index of the species in the culled species list.
|
||||
* @param definedSpeciesIndex The index of the species in the defined species list.
|
||||
* @return The index of the corresponding species in the full network.
|
||||
*
|
||||
* @throws std::out_of_range If the culled index is out of bounds for the species index map.
|
||||
* @throws std::out_of_range If the defined index is out of bounds for the species index map.
|
||||
*/
|
||||
size_t mapViewToFullSpeciesIndex(size_t culledSpeciesIndex) const;
|
||||
size_t mapViewToFullSpeciesIndex(size_t definedSpeciesIndex) const;
|
||||
|
||||
/**
|
||||
* @brief Maps a culled reaction index to a full reaction index.
|
||||
*
|
||||
* @param culledReactionIndex The index of the reaction in the culled reaction list.
|
||||
* @param definedReactionIndex The index of the reaction in the defined reaction list.
|
||||
* @return The index of the corresponding reaction in the full network.
|
||||
*
|
||||
* @throws std::out_of_range If the culled index is out of bounds for the reaction index map.
|
||||
* @throws std::out_of_range If the defined index is out of bounds for the reaction index map.
|
||||
*/
|
||||
size_t mapViewToFullReactionIndex(size_t culledReactionIndex) const;
|
||||
size_t mapViewToFullReactionIndex(size_t definedReactionIndex) const;
|
||||
|
||||
/**
|
||||
* @brief Validates that the FileDefinedEngineView is not stale.
|
||||
*
|
||||
* @throws std::runtime_error If the view is stale (i.e., `update()` has not been called after the view was made stale).
|
||||
*/
|
||||
void validateNetworkState() const;
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user