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

feat(python): added robust python bindings covering the entire codebase

Browse Source
This commit is contained in:
Emily Boudreaux
2025-07-23 16:26:30 -04:00
parent 6a22cb65b8
commit f20bffc411
134 changed files with 2202 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

479
src/include/gridfire/engine/views/engine_adaptive.h Normal file
View File

@@ -0,0 +1,479 @@
#pragma once
#include "gridfire/engine/engine_abstract.h"
#include "gridfire/engine/views/engine_view_abstract.h"
#include "gridfire/screening/screening_abstract.h"
#include "gridfire/screening/screening_types.h"
#include "gridfire/network.h"
#include "fourdst/composition/atomicSpecies.h"
#include "fourdst/config/config.h"
#include "fourdst/logging/logging.h"
#include "gridfire/engine/procedures/priming.h"
#include "gridfire/engine/procedures/construction.h"
#include "quill/Logger.h"
namespace gridfire {
/**
* @class AdaptiveEngineView
* @brief An engine view that dynamically adapts the reaction network based on runtime conditions.
*
* This class implements an EngineView that dynamically culls species and reactions from the
* full reaction network based on their reaction flow rates and connectivity. This allows for
* efficient simulation of reaction networks by focusing computational effort on the most
* important species and reactions.
*
* The AdaptiveEngineView maintains a subset of "active" species and reactions, and maps
* between the full network indices and the active subset indices. This allows the base engine
* to operate on the full network data, while the AdaptiveEngineView provides a reduced view
* for external clients.
*
* The adaptation process is driven by the `update()` method, which performs the following steps:
* 1. **Reaction Flow Calculation:** Calculates the molar reaction flow rate for each reaction
* in the full network based on the current temperature, density, and composition.
* 2. **Reaction Culling:** Culls reactions with flow rates below a threshold, determined by
* a relative culling threshold multiplied by the maximum flow rate.
* 3. **Connectivity Analysis:** Performs a connectivity analysis to identify species that are
* reachable from the initial fuel species through the culled reaction network.
* 4. **Species Culling:** Culls species that are not reachable from the initial fuel.
* 5. **Index Map Construction:** Constructs index maps to map between the full network indices
* and the active subset indices for species and reactions.
*
* @implements DynamicEngine
* @implements EngineView<DynamicEngine>
*
* @see engine_abstract.h
* @see engine_view_abstract.h
* @see AdaptiveEngineView::update()
*/
class AdaptiveEngineView final : public DynamicEngine, public EngineView<DynamicEngine> {
public:
/**
* @brief Constructs an AdaptiveEngineView.
*
* @param baseEngine The underlying DynamicEngine to which this view delegates calculations.
*
* Initializes the active species and reactions to the full network, and constructs the
* initial index maps.
*/
explicit AdaptiveEngineView(DynamicEngine& baseEngine);
/**
* @brief Updates the active species and reactions based on the current conditions.
*
* @param netIn The current network input, containing temperature, density, and composition.
*
* This method performs the reaction flow calculation, reaction culling, connectivity analysis,
* and index map construction steps described above.
*
* The culling thresholds are read from the configuration using the following keys:
* - `gridfire:AdaptiveEngineView:RelativeCullingThreshold` (default: 1e-75)
*
* @throws std::runtime_error If there is a mismatch between the active reactions and the base engine.
* @post The active species and reactions are updated, and the index maps are reconstructed.
* @see AdaptiveEngineView
* @see AdaptiveEngineView::constructSpeciesIndexMap()
* @see AdaptiveEngineView::constructReactionIndexMap()
*/
fourdst::composition::Composition update(const NetIn &netIn) override;
bool isStale(const NetIn& netIn) override;
/**
* @brief Gets the list of active species in the network.
* @return A const reference to the vector of active species.
*/
[[nodiscard]] const std::vector<fourdst::atomic::Species>& getNetworkSpecies() const override;
/**
* @brief Calculates the right-hand side (dY/dt) and energy generation for the active species.
*
* @param Y_culled 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.
*
* This method maps the culled abundances to the full network abundances, calls the base engine
* to calculate the RHS and energy generation, and then maps the full network derivatives back
* to the culled derivatives.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
* @see AdaptiveEngineView::update()
*/
[[nodiscard]] std::expected<StepDerivatives<double>, expectations::StaleEngineError> calculateRHSAndEnergy(
const std::vector<double> &Y_culled,
const double T9,
const double rho
) const override;
/**
* @brief Generates the Jacobian matrix for the active species.
*
* @param Y_dynamic 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.
*
* This method maps the culled abundances to the full network abundances and calls the base engine
* to generate the Jacobian matrix.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
* @see AdaptiveEngineView::update()
*/
void generateJacobianMatrix(
const std::vector<double> &Y_dynamic,
const double T9,
const double rho
) const override;
/**
* @brief Gets an entry from the Jacobian matrix for the active species.
*
* @param i_culled The row index (species index) in the culled matrix.
* @param j_culled The column index (species index) in the culled matrix.
* @return The value of the Jacobian matrix at (i_culled, j_culled).
*
* This method maps the culled indices to the full network indices and calls the base engine
* to get the Jacobian matrix entry.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
* @throws std::out_of_range If the culled index is out of bounds for the species index map.
* @see AdaptiveEngineView::update()
*/
[[nodiscard]] double getJacobianMatrixEntry(
const int i_culled,
const int j_culled
) const override;
/**
* @brief Generates the stoichiometry matrix for the active reactions and species.
*
* This method calls the base engine to generate the stoichiometry matrix.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
* @note The stoichiometry matrix generated by the base engine is assumed to be consistent with
* the active species and reactions in this view.
*/
void generateStoichiometryMatrix() override;
/**
* @brief Gets an entry from the stoichiometry matrix for the active species and reactions.
*
* @param speciesIndex_culled The index of the species in the culled species list.
* @param reactionIndex_culled The index of the reaction in the culled reaction list.
* @return The stoichiometric coefficient for the given species and reaction.
*
* This method maps the culled indices to the full network indices and calls the base engine
* to get the stoichiometry matrix entry.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
* @throws std::out_of_range If the culled index is out of bounds for the species or reaction index map.
* @see AdaptiveEngineView::update()
*/
[[nodiscard]] int getStoichiometryMatrixEntry(
const int speciesIndex_culled,
const int reactionIndex_culled
) 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_culled 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).
*
* This method maps the culled abundances to the full network abundances and calls the base engine
* to calculate the molar reaction flow.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
* @throws std::runtime_error If the reaction is not part of the active reactions in the adaptive engine view.
*/
[[nodiscard]] double calculateMolarReactionFlow(
const reaction::Reaction &reaction,
const std::vector<double> &Y_culled,
double T9,
double rho
) const override;
/**
* @brief Gets the set of active logical reactions in the network.
*
* @return Reference to the LogicalReactionSet containing all active reactions.
*/
[[nodiscard]] const reaction::LogicalReactionSet& getNetworkReactions() const override;
void setNetworkReactions(const reaction::LogicalReactionSet& reactions) override;
/**
* @brief Computes timescales for all active species in the network.
*
* @param Y_culled 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).
*
* This method maps the culled abundances to the full network abundances and calls the base engine
* to compute the species timescales.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
*/
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesTimescales(
const std::vector<double> &Y_culled,
double T9,
double rho
) const override;
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesDestructionTimescales(
const std::vector<double> &Y,
double T9,
double rho
) const override;
/**
* @brief Gets the base engine.
* @return A const reference to the base engine.
*/
[[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;
[[nodiscard]] int getSpeciesIndex(const fourdst::atomic::Species &species) const override;
[[nodiscard]] std::vector<double> mapNetInToMolarAbundanceVector(const NetIn &netIn) const override;
[[nodiscard]] PrimingReport primeEngine(const NetIn &netIn) 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:
/**
* @brief A struct to hold a reaction and its flow rate.
*/
struct ReactionFlow {
const reaction::LogicalReaction* reactionPtr;
double flowRate;
};
private:
/**
* @brief Constructs the species index map.
*
* @return A vector mapping culled 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()
*/
[[nodiscard]] std::vector<size_t> constructSpeciesIndexMap() const;
/**
* @brief Constructs the reaction index map.
*
* @return A vector mapping culled 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()
*/
[[nodiscard]] 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.
* @return A vector of abundances for the full network, with the abundances of the active
* species copied from the culled vector.
*/
[[nodiscard]] std::vector<double> mapCulledToFull(const std::vector<double>& culled) const;
/**
* @brief Maps a vector of full abundances to a vector of culled abundances.
*
* @param full A vector of abundances for the full network.
* @return A vector of abundances for the active species, with the abundances of the active
* species copied from the full vector.
*/
[[nodiscard]] std::vector<double> mapFullToCulled(const std::vector<double>& full) const;
/**
* @brief Maps a culled species index to a full species index.
*
* @param culledSpeciesIndex The index of the species in the culled 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.
*/
[[nodiscard]] size_t mapCulledToFullSpeciesIndex(size_t culledSpeciesIndex) const;
/**
* @brief Maps a culled reaction index to a full reaction index.
*
* @param culledReactionIndex The index of the reaction in the culled 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.
*/
[[nodiscard]] size_t mapCulledToFullReactionIndex(size_t culledReactionIndex) const;
/**
* @brief Validates that the AdaptiveEngineView is not stale.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
*/
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;
typedef std::pair<std::unordered_set<const reaction::LogicalReaction*>, std::unordered_set<fourdst::atomic::Species>> RescueSet;
[[nodiscard]] RescueSet rescueEdgeSpeciesDestructionChannel(
const std::vector<double>& Y_full,
const double T9,
const double rho,
const std::vector<fourdst::atomic::Species>& activeSpecies,
const reaction::LogicalReactionSet& activeReactions
) 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
);
};
}

277
src/include/gridfire/engine/views/engine_defined.h Normal file
View File

@@ -0,0 +1,277 @@
#pragma once
#include "gridfire/engine/views/engine_view_abstract.h"
#include "gridfire/engine/engine_abstract.h"
#include "gridfire/io/network_file.h"
#include "gridfire/network.h"
#include "fourdst/config/config.h"
#include "fourdst/logging/logging.h"
#include "quill/Logger.h"
#include <string>
namespace gridfire{
class DefinedEngineView : public DynamicEngine, public EngineView<DynamicEngine> {
public:
DefinedEngineView(const std::vector<std::string>& peNames, DynamicEngine& baseEngine);
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()`).
*/
std::expected<StepDerivatives<double>, expectations::StaleEngineError> 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_dynamic 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_dynamic,
const double T9,
const double rho
) const 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;
void setNetworkReactions(const reaction::LogicalReactionSet& reactions) 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.
*/
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesTimescales(
const std::vector<double>& Y_defined,
const double T9,
const double rho
) const override;
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesDestructionTimescales(
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.
*/
fourdst::composition::Composition update(const NetIn &netIn) override;
bool isStale(const NetIn& netIn) override;
/**
* @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;
[[nodiscard]] int getSpeciesIndex(const fourdst::atomic::Species &species) const override;
[[nodiscard]] std::vector<double> mapNetInToMolarAbundanceVector(const NetIn &netIn) const override;
[[nodiscard]] PrimingReport primeEngine(const NetIn &netIn) override;
protected:
bool m_isStale = true;
DynamicEngine& m_baseEngine;
private:
quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log"); ///< Logger instance for trace and debug information.
///< Active species in the defined engine.
std::vector<fourdst::atomic::Species> m_activeSpecies;
///< Active reactions in the defined engine.
reaction::LogicalReactionSet m_activeReactions;
///< 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;
private:
/**
* @brief Constructs the species index map.
*
* @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.
*
* @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 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.
*
* @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 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 defined vector.
*/
std::vector<double> mapViewToFull(const std::vector<double>& defined) const;
/**
* @brief Maps a vector of full abundances to a vector of culled abundances.
*
* @param full A vector of abundances for the full network.
* @return A vector of abundances for the active species, with the abundances of the active
* species copied from the full vector.
*/
std::vector<double> mapFullToView(const std::vector<double>& full) const;
/**
* @brief Maps a culled species index to a full species index.
*
* @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 defined index is out of bounds for the species index map.
*/
size_t mapViewToFullSpeciesIndex(size_t definedSpeciesIndex) const;
/**
* @brief Maps a culled reaction index to a full reaction index.
*
* @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 defined index is out of bounds for the reaction index map.
*/
size_t mapViewToFullReactionIndex(size_t definedReactionIndex) const;
void validateNetworkState() const;
void collect(const std::vector<std::string>& peNames);
};
class FileDefinedEngineView final: public DefinedEngineView {
public:
explicit FileDefinedEngineView(
DynamicEngine& baseEngine,
const std::string& fileName,
const io::NetworkFileParser& parser
);
std::string getNetworkFile() const { return m_fileName; }
const io::NetworkFileParser& getParser() const { return m_parser; }
private:
using Config = fourdst::config::Config;
using LogManager = fourdst::logging::LogManager;
Config& m_config = Config::getInstance();
quill::Logger* m_logger = LogManager::getInstance().getLogger("log");
std::string m_fileName;
///< Parser for the network file.
const io::NetworkFileParser& m_parser;
};
}

392
src/include/gridfire/engine/views/engine_multiscale.h Normal file
View File

@@ -0,0 +1,392 @@
#pragma once
#include "gridfire/engine/engine_abstract.h"
#include "gridfire/engine/views/engine_view_abstract.h"
#include "gridfire/engine/engine_graph.h"
#include "unsupported/Eigen/NonLinearOptimization"
namespace gridfire {
struct QSECacheConfig {
double T9_tol; ///< Absolute tolerance to produce the same hash for T9.
double rho_tol; ///< Absolute tolerance to produce the same hash for rho.
double Yi_tol; ///< Absolute tolerance to produce the same hash for species abundances.
};
struct QSECacheKey {
double m_T9;
double m_rho;
std::vector<double> m_Y; ///< Note that the ordering of Y must match the dynamic species indices in the view.
std::size_t m_hash = 0; ///< Precomputed hash value for this key.
// TODO: We should probably sort out how to adjust these from absolute to relative tolerances.
QSECacheConfig m_cacheConfig = {
1e-3, // Default tolerance for T9
1e-1, // Default tolerance for rho
1e-3 // Default tolerance for species abundances
};
QSECacheKey(
const double T9,
const double rho,
const std::vector<double>& Y
);
size_t hash() const;
static long bin(double value, double tol);
bool operator==(const QSECacheKey& other) const;
};
}
// Needs to be in this order (splitting gridfire namespace up) to avoid some issues with forward declarations and the () operator.
namespace std {
template <>
struct hash<gridfire::QSECacheKey> {
/**
* @brief Computes the hash of a QSECacheKey.
* @param key The QSECacheKey to hash.
* @return The pre-computed hash value of the key.
*/
size_t operator()(const gridfire::QSECacheKey& key) const noexcept {
// The hash is pre-computed, so we just return it.
return key.m_hash;
}
};
} // namespace std
namespace gridfire {
class MultiscalePartitioningEngineView final: public DynamicEngine, public EngineView<DynamicEngine> {
typedef std::tuple<std::vector<fourdst::atomic::Species>, std::vector<size_t>, std::vector<fourdst::atomic::Species>, std::vector<size_t>> QSEPartition;
public:
explicit MultiscalePartitioningEngineView(GraphEngine& baseEngine);
[[nodiscard]] const std::vector<fourdst::atomic::Species> & getNetworkSpecies() const override;
[[nodiscard]] std::expected<StepDerivatives<double>, expectations::StaleEngineError> calculateRHSAndEnergy(
const std::vector<double> &Y_full,
double T9,
double rho
) const override;
void generateJacobianMatrix(
const std::vector<double> &Y_full,
double T9,
double rho
) const override;
[[nodiscard]] double getJacobianMatrixEntry(
int i_full,
int j_full
) const override;
void generateStoichiometryMatrix() override;
[[nodiscard]] int getStoichiometryMatrixEntry(
int speciesIndex,
int reactionIndex
) const override;
[[nodiscard]] double calculateMolarReactionFlow(
const reaction::Reaction &reaction,
const std::vector<double> &Y_full,
double T9,
double rho
) const override;
[[nodiscard]] const reaction::LogicalReactionSet & getNetworkReactions() const override;
void setNetworkReactions(
const reaction::LogicalReactionSet &reactions
) override;
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesTimescales(
const std::vector<double> &Y,
double T9,
double rho
) const override;
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesDestructionTimescales(
const std::vector<double> &Y,
double T9,
double rho
) const override;
fourdst::composition::Composition update(
const NetIn &netIn
) override;
bool isStale(const NetIn& netIn) override;
void setScreeningModel(
screening::ScreeningType model
) override;
[[nodiscard]] screening::ScreeningType getScreeningModel() const override;
const DynamicEngine & getBaseEngine() const override;
std::vector<std::vector<size_t>> analyzeTimescalePoolConnectivity(
const std::vector<std::vector<size_t>> &timescale_pools,
const std::vector<double> &Y,
double T9,
double rho
) const;
void partitionNetwork(
const std::vector<double>& Y,
double T9,
double rho
);
void partitionNetwork(
const NetIn& netIn
);
void exportToDot(
const std::string& filename,
const std::vector<double>& Y,
const double T9,
const double rho
) const;
[[nodiscard]] int getSpeciesIndex(const fourdst::atomic::Species &species) const override;
[[nodiscard]] std::vector<double> mapNetInToMolarAbundanceVector(const NetIn &netIn) const override;
[[nodiscard]] PrimingReport primeEngine(const NetIn &netIn) override;
[[nodiscard]] std::vector<fourdst::atomic::Species> getFastSpecies() const;
[[nodiscard]] const std::vector<fourdst::atomic::Species>& getDynamicSpecies() const;
fourdst::composition::Composition equilibrateNetwork(
const std::vector<double> &Y,
double T9,
double rho
);
fourdst::composition::Composition equilibrateNetwork(
const NetIn &netIn
);
private:
struct QSEGroup {
std::set<size_t> species_indices; ///< Indices of all species in this group.
bool is_in_equilibrium = false; ///< Flag set by flux analysis.
std::set<size_t> algebraic_indices; ///< Indices of algebraic species in this group.
std::set<size_t> seed_indices; ///< Indices of dynamic species in this group.
double mean_timescale; ///< Mean timescale of the group.
bool operator<(const QSEGroup& other) const;
bool operator>(const QSEGroup& other) const;
bool operator==(const QSEGroup& other) const;
bool operator!=(const QSEGroup& other) const;
friend std::ostream& operator<<(std::ostream& os, const QSEGroup& group) {
os << "QSEGroup(species_indices: [";
int count = 0;
for (const auto& idx : group.species_indices) {
os << idx;
if (count < group.species_indices.size() - 1) {
os << ", ";
}
count++;
}
count = 0;
os << "], is_in_equilibrium: " << group.is_in_equilibrium
<< ", mean_timescale: " << group.mean_timescale
<< " s, algebraic_indices: [";
for (const auto& idx : group.algebraic_indices) {
os << idx;
if (count < group.algebraic_indices.size() - 1) {
os << ", ";
}
count++;
}
count = 0;
os << "], seed_indices: [";
for (const auto& idx : group.seed_indices) {
os << idx;
if (count < group.seed_indices.size() - 1) {
os << ", ";
}
count++;
}
os << "])";
return os;
}
};
struct EigenFunctor {
using InputType = Eigen::Matrix<double, Eigen::Dynamic, 1>;
using OutputType = Eigen::Matrix<double, Eigen::Dynamic, 1>;
using JacobianType = Eigen::Matrix<double, Eigen::Dynamic, Eigen::Dynamic>;
enum {
InputsAtCompileTime = Eigen::Dynamic,
ValuesAtCompileTime = Eigen::Dynamic
};
MultiscalePartitioningEngineView* m_view;
const std::vector<size_t>& m_qse_solve_indices;
const std::vector<double>& m_Y_full_initial;
const double m_T9;
const double m_rho;
const Eigen::VectorXd& m_Y_scale;
EigenFunctor(
MultiscalePartitioningEngineView& view,
const std::vector<size_t>& qse_solve_indices,
const std::vector<double>& Y_full_initial,
const double T9,
const double rho,
const Eigen::VectorXd& Y_scale
) :
m_view(&view),
m_qse_solve_indices(qse_solve_indices),
m_Y_full_initial(Y_full_initial),
m_T9(T9),
m_rho(rho),
m_Y_scale(Y_scale) {}
[[nodiscard]] int values() const { return m_qse_solve_indices.size(); }
[[nodiscard]] int inputs() const { return m_qse_solve_indices.size(); }
int operator()(const InputType& v_qse, OutputType& f_qse) const;
int df(const InputType& v_qse, JacobianType& J_qse) const;
};
struct CacheStats {
enum class operators {
CalculateRHSAndEnergy,
GenerateJacobianMatrix,
CalculateMolarReactionFlow,
GetSpeciesTimescales,
GetSpeciesDestructionTimescales,
Other,
All
};
std::map<operators, std::string> operatorsNameMap = {
{operators::CalculateRHSAndEnergy, "calculateRHSAndEnergy"},
{operators::GenerateJacobianMatrix, "generateJacobianMatrix"},
{operators::CalculateMolarReactionFlow, "calculateMolarReactionFlow"},
{operators::GetSpeciesTimescales, "getSpeciesTimescales"},
{operators::GetSpeciesDestructionTimescales, "getSpeciesDestructionTimescales"},
{operators::Other, "other"}
};
size_t m_hit = 0;
size_t m_miss = 0;
std::map<operators, size_t> m_operatorHits = {
{operators::CalculateRHSAndEnergy, 0},
{operators::GenerateJacobianMatrix, 0},
{operators::CalculateMolarReactionFlow, 0},
{operators::GetSpeciesTimescales, 0},
{operators::GetSpeciesDestructionTimescales, 0},
{operators::Other, 0}
};
friend std::ostream& operator<<(std::ostream& os, const CacheStats& stats) {
os << "CacheStats(hit: " << stats.m_hit << ", miss: " << stats.m_miss << ")";
return os;
}
void hit(const operators op=operators::Other) {
if (op==operators::All) {
throw std::invalid_argument("Cannot use 'All' as an operator for hit/miss.");
}
m_hit++;
m_operatorHits[op]++;
}
void miss(const operators op=operators::Other) {
if (op==operators::All) {
throw std::invalid_argument("Cannot use 'All' as an operator for hit/miss.");
}
m_miss++;
m_operatorHits[op]++;
}
[[nodiscard]] size_t hits(const operators op=operators::All) const {
if (op==operators::All) {
return m_hit;
}
return m_operatorHits.at(op);
}
[[nodiscard]] size_t misses(const operators op=operators::All) const {
if (op==operators::All) {
return m_miss;
}
return m_operatorHits.at(op);
}
};
private:
quill::Logger* m_logger = LogManager::getInstance().getLogger("log");
GraphEngine& m_baseEngine; ///< The base engine to which this view delegates calculations.
std::vector<QSEGroup> m_qse_groups; ///< The list of identified equilibrium groups.
std::vector<fourdst::atomic::Species> m_dynamic_species; ///< The simplified set of species presented to the solver.
std::vector<size_t> m_dynamic_species_indices; ///< Indices mapping the dynamic species back to the master engine's list.
std::vector<fourdst::atomic::Species> m_algebraic_species; ///< Species that are algebraic in the QSE groups.
std::vector<size_t> m_algebraic_species_indices; ///< Indices of algebraic species in the full network.
std::vector<size_t> m_activeSpeciesIndices; ///< Indices of active species in the full network.
std::vector<size_t> m_activeReactionIndices; ///< Indices of active reactions in the full network.
// TODO: Enhance the hashing for the cache to consider not just T and rho but also the current abundance in some careful way that automatically ignores small changes (i.e. network should only be repartitioned sometimes)
std::unordered_map<QSECacheKey, std::vector<double>> m_qse_abundance_cache; ///< Cache for QSE abundances based on T9 and rho.
mutable CacheStats m_cacheStats; ///< Statistics for the QSE abundance cache.
private:
std::vector<std::vector<size_t>> partitionByTimescale(
const std::vector<double> &Y_full,
double T9,
double rho
) const;
std::unordered_map<size_t, std::vector<size_t>> buildConnectivityGraph(
const std::unordered_set<size_t> &fast_reaction_indices
) const;
std::vector<QSEGroup> validateGroupsWithFluxAnalysis(
const std::vector<QSEGroup> &candidate_groups,
const std::vector<double>& Y,
double T9,
double rho
) const;
std::vector<double> solveQSEAbundances(
const std::vector<double> &Y_full,
double T9,
double rho
);
size_t identifyMeanSlowestPool(
const std::vector<std::vector<size_t>>& pools,
const std::vector<double> &Y,
double T9,
double rho
) const;
std::unordered_map<size_t, std::vector<size_t>> buildConnectivityGraph(
const std::vector<size_t>& species_pool
) const;
std::vector<QSEGroup> constructCandidateGroups(
const std::vector<std::vector<size_t>>& candidate_pools,
const std::vector<double>& Y,
double T9, double rho
) const;
};
}

35
src/include/gridfire/engine/views/engine_priming.h Normal file
View File

@@ -0,0 +1,35 @@
#pragma once
#include "gridfire/engine/engine_abstract.h"
#include "gridfire/engine/views/engine_defined.h"
#include "gridfire/network.h"
#include "fourdst/logging/logging.h"
#include "fourdst/composition/atomicSpecies.h"
#include "fourdst/composition/composition.h"
#include "quill/Logger.h"
#include <vector>
#include <string>
namespace gridfire {
class NetworkPrimingEngineView final : public DefinedEngineView {
public:
NetworkPrimingEngineView(const std::string& primingSymbol, DynamicEngine& baseEngine);
NetworkPrimingEngineView(const fourdst::atomic::Species& primingSpecies, DynamicEngine& baseEngine);
private:
quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log");
fourdst::atomic::Species m_primingSpecies; ///< The priming species, if specified.
private:
std::vector<std::string> constructPrimingReactionSet(
const fourdst::atomic::Species& primingSpecies,
const DynamicEngine& baseEngine
) const;
};
}

98
src/include/gridfire/engine/views/engine_view_abstract.h Normal file
View File

@@ -0,0 +1,98 @@
#pragma once
#include "gridfire/engine/engine_abstract.h"
/**
* @file engine_view_abstract.h
* @brief Abstract interfaces for engine "views" in GridFire.
*
* This header defines the abstract base classes and concepts for "views" of reaction network engines.
* The primary purpose of an EngineView is to enable dynamic or adaptive network topologies
* (such as species/reaction culling, masking, or remapping) without modifying the underlying
* physics engine or its implementation. Engine views act as a flexible interface layer,
* allowing the network structure to be changed at runtime while preserving the core
* physics and solver logic in the base engine.
*
* Typical use cases include:
* - Adaptive or reduced networks for computational efficiency.
* - Dynamic masking or culling of species/reactions based on runtime criteria.
* - Providing a filtered or remapped view of the network for integration or analysis.
* - Supporting dynamic network reconfiguration in multi-zone or multi-physics contexts.
*
* The base engine types referenced here are defined in @ref engine_abstract.h.
*
* @author
* Emily M. Boudreaux
*/
namespace gridfire {
/**
* @brief Concept for types allowed as engine bases in EngineView.
*
* This concept restricts template parameters to types derived from either
* gridfire::Engine or gridfire::DynamicEngine, as defined in engine_abstract.h.
*
* Example usage:
* @code
* static_assert(EngineType<MyEngine>);
* @endcode
*/
template<typename EngineT>
concept EngineType = std::is_base_of_v<Engine, EngineT> || std::is_base_of_v<DynamicEngine, EngineT>;
/**
* @brief Abstract base class for a "view" of a reaction network engine.
*
* @tparam EngineT The engine type being viewed (must satisfy EngineType).
*
* EngineView provides an interface for accessing an underlying engine instance,
* while presenting a potentially modified or reduced network structure to the user.
* This enables dynamic or adaptive network topologies (e.g., culling, masking, or
* remapping of species and reactions) without altering the core physics engine.
*
* Intended usage: Derive from this class to implement a custom view or wrapper
* that manages a dynamic or adaptive network structure, delegating core calculations
* to the base engine. The contract is that getBaseEngine() must return a reference
* to the underlying engine instance, which remains responsible for the full physics.
*
* Example (see also AdaptiveEngineView):
* @code
* class MyAdaptiveView : public gridfire::EngineView<DynamicEngine> {
* public:
* MyAdaptiveView(DynamicEngine& engine) : engine_(engine) {}
* const DynamicEngine& getBaseEngine() const override { return engine_; }
* // Implement dynamic masking/culling logic...
* private:
* DynamicEngine& engine_;
* };
* @endcode
*
* @see gridfire::AdaptiveEngineView for a concrete example of dynamic culling.
*/
template<EngineType EngineT>
class EngineView {
public:
/**
* @brief Virtual destructor.
*/
virtual ~EngineView() = default;
/**
* @brief Access the underlying engine instance.
*
* @return Const reference to the underlying engine.
*
* This method must be implemented by derived classes to provide access
* to the base engine. The returned reference should remain valid for the
* lifetime of the EngineView.
*
* Example:
* @code
* const DynamicEngine& engine = myView.getBaseEngine();
* @endcode
*/
virtual const EngineT& getBaseEngine() const = 0;
};
}

7
src/include/gridfire/engine/views/engine_views.h Normal file
View File

@@ -0,0 +1,7 @@
#pragma once
#include "gridfire/engine/views/engine_adaptive.h"
#include "gridfire/engine/views/engine_defined.h"
#include "gridfire/engine/views/engine_multiscale.h"
#include "gridfire/engine/views/engine_priming.h"
#include "gridfire/engine/views/engine_view_abstract.h"