# fourdst::libcomposition: src/composition/include/fourdst/composition/composition.h Source File

Loading...
Searching...
No Matches
composition.h
Go to the documentation of this file.
/* ***********************************************************************
//
// Copyright (C) 2025 -- The 4D-STAR Collaboration
// File Author: Emily Boudreaux
// Last Modified: March 26, 2025
//
// 4DSSE is free software; you can use it and/or modify
// it under the terms and restrictions the GNU General Library Public
// License version 3 (GPLv3) as published by the Free Software Foundation.
//
// 4DSSE is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
// See the GNU Library General Public License for more details.
//
// You should have received a copy of the GNU Library General Public License
// along with this software; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
//
// *********************************************************************** */
#pragma once
#include <string>
#include <unordered_map>
#include <set>
#include <utility>
#include "fourdst/config/config.h"
#include "fourdst/logging/logging.h"
#include "fourdst/composition/composition_abstract.h"
#include "fourdst/composition/atomicSpecies.h"
namespace fourdst::composition {
struct CanonicalComposition {
double X = 0.0;
double Y = 0.0;
double Z = 0.0;
friend std::ostream& operator<<(std::ostream& os, const CanonicalComposition& composition) {
os << "<CanonicalComposition: "
<< "X = " << composition.X << ", "
<< "Y = " << composition.Y << ", "
<< "Z = " << composition.Z << ">";
return os;
}
};
struct GlobalComposition {
double specificNumberDensity;
double meanParticleMass;
// Overload the output stream operator for GlobalComposition
friend std::ostream& operator<<(std::ostream& os, const GlobalComposition& comp);
};
struct CompositionEntry {
std::string m_symbol;
atomic::Species m_isotope;
bool m_massFracMode = true;
double m_massFraction = 0.0;
double m_numberFraction = 0.0;
double m_relAbundance = 0.0;
double m_molesPerMass = 0.0;
double m_cachedNumberFraction = 0.0;
bool m_initialized = false;
CompositionEntry();
explicit CompositionEntry(const std::string& symbol, bool massFracMode=true);
CompositionEntry(const CompositionEntry& entry);
void setSpecies(const std::string& symbol);
[[nodiscard]] std::string symbol() const;
[[nodiscard]] double mass_fraction() const;
[[nodiscard]] double number_fraction() const;
[[nodiscard]] double number_fraction(double totalMolesPerMass) const;
[[nodiscard]] double rel_abundance() const;
[[nodiscard]] atomic::Species isotope() const;
[[nodiscard]] bool getMassFracMode() const;
void setMassFraction(double mass_fraction);
void setNumberFraction(double number_fraction);
bool setMassFracMode(double meanMolarMass);
bool setNumberFracMode(double totalMolesPerMass);
friend std::ostream& operator<<(std::ostream& os, const CompositionEntry& entry);
};
class Composition : public CompositionAbstract {
private:
struct CompositionCache {
std::optional<GlobalComposition> globalComp;
std::optional<CanonicalComposition> canonicalComp;
std::optional<std::vector<double>> massFractions;
std::optional<std::vector<double>> numberFractions;
std::optional<std::vector<double>> molarAbundances;
std::optional<std::vector<atomic::Species>> sortedSpecies;
std::optional<std::vector<std::string>> sortedSymbols;
std::optional<double> Ye;
void clear() {
globalComp = std::nullopt;
canonicalComp = std::nullopt;
massFractions = std::nullopt;
numberFractions = std::nullopt;
molarAbundances = std::nullopt;
sortedSymbols = std::nullopt;
sortedSpecies = std::nullopt;
Ye = std::nullopt;
}
[[nodiscard]] bool is_clear() const {
return !globalComp.has_value() && !canonicalComp.has_value() && !massFractions.has_value() &&
!numberFractions.has_value() && !molarAbundances.has_value() && !sortedSymbols.has_value() &&
!Ye.has_value() && !sortedSpecies.has_value();
}
};
private:
config::Config& m_config = config::Config::getInstance();
logging::LogManager& m_logManager = logging::LogManager::getInstance();
quill::Logger* m_logger = m_logManager.getLogger("log");
bool m_finalized = false;
double m_specificNumberDensity = 0.0;
double m_meanParticleMass = 0.0;
bool m_massFracMode = true;
std::set<std::string> m_registeredSymbols;
std::unordered_map<std::string, CompositionEntry> m_compositions;
mutable CompositionCache m_cache;
static bool isValidSymbol(const std::string& symbol);
[[nodiscard]] bool isValidComposition(const std::vector<double>& fractions) const;
void validateComposition(const std::vector<double>& fractions) const;
bool finalizeMassFracMode(bool norm);
bool finalizeNumberFracMode(bool norm);
public:
Composition() = default;
~Composition() override = default;
[[nodiscard]] bool finalize(bool norm=false);
explicit Composition(const std::vector<std::string>& symbols);
explicit Composition(const std::set<std::string>& symbols);
Composition(const std::vector<std::string>& symbols, const std::vector<double>& fractions, bool massFracMode=true);
Composition(const Composition& composition);
Composition& operator=(Composition const& other);
void registerSymbol(const std::string& symbol, bool massFracMode=true);
void registerSymbol(const std::vector<std::string>& symbols, bool massFracMode=true);
void registerSpecies(const fourdst::atomic::Species& species, bool massFracMode=true);
void registerSpecies(const std::vector<fourdst::atomic::Species>& species, bool massFracMode=true);
[[nodiscard]] std::set<std::string> getRegisteredSymbols() const override;
[[nodiscard]] std::set<fourdst::atomic::Species> getRegisteredSpecies() const override;
double setMassFraction(const std::string& symbol, const double& mass_fraction);
std::vector<double> setMassFraction(const std::vector<std::string>& symbols, const std::vector<double>& mass_fractions);
double setMassFraction(const fourdst::atomic::Species& species, const double& mass_fraction);
std::vector<double> setMassFraction(const std::vector<fourdst::atomic::Species>& species, const std::vector<double>& mass_fractions);
double setNumberFraction(const std::string& symbol, const double& number_fraction);
std::vector<double> setNumberFraction(const std::vector<std::string>& symbols, const std::vector<double>& number_fractions);
double setNumberFraction(const fourdst::atomic::Species& species, const double& number_fraction);
std::vector<double> setNumberFraction(const std::vector<fourdst::atomic::Species>& species, const std::vector<double>& number_fractions);
[[nodiscard]] Composition mix(const Composition& other, double fraction) const;
[[nodiscard]] std::unordered_map<std::string, double> getMassFraction() const override;
[[nodiscard]] double getMassFraction(const std::string& symbol) const override;
[[nodiscard]] double getMassFraction(const fourdst::atomic::Species& species) const override;
[[nodiscard]] double getNumberFraction(const std::string& symbol) const override;
[[nodiscard]] double getNumberFraction(const fourdst::atomic::Species& species) const override;
[[nodiscard]] std::unordered_map<std::string, double> getNumberFraction() const override;
[[nodiscard]] double getMolarAbundance(const std::string& symbol) const override;
[[nodiscard]] double getMolarAbundance(const fourdst::atomic::Species& species) const override;
[[nodiscard]] std::pair<CompositionEntry, GlobalComposition> getComposition(const std::string& symbol) const;
[[nodiscard]] std::pair<CompositionEntry, GlobalComposition> getComposition(const fourdst::atomic::Species& species) const;
[[nodiscard]] std::pair<std::unordered_map<std::string, CompositionEntry>, GlobalComposition> getComposition() const;
[[nodiscard]] double getMeanParticleMass() const override;
[[nodiscard]] double getMeanAtomicNumber() const override;
[[nodiscard]] double getElectronAbundance() const override;
[[nodiscard]] Composition subset(const std::vector<std::string>& symbols, const std::string& method="norm") const;
[[nodiscard]] bool hasSymbol(const std::string& symbol) const override;
[[nodiscard]] bool hasSpecies(const fourdst::atomic::Species &species) const override;
[[nodiscard]] bool contains(const atomic::Species& isotope) const override;
void setCompositionMode(bool massFracMode);
[[nodiscard]] CanonicalComposition getCanonicalComposition(bool harsh=false) const;
[[nodiscard]] std::vector<double> getMassFractionVector() const override;
[[nodiscard]] std::vector<double> getNumberFractionVector() const override;
[[nodiscard]] std::vector<double> getMolarAbundanceVector() const override;
[[nodiscard]] size_t getSpeciesIndex(const std::string& symbol) const override;
[[nodiscard]] size_t getSpeciesIndex(const atomic::Species& species) const override;
[[nodiscard]] atomic::Species getSpeciesAtIndex(size_t index) const override;
friend std::ostream& operator<<(std::ostream& os, const Composition& composition);
Composition operator+(const Composition& other) const;
auto begin() {
return m_compositions.begin();
}
[[nodiscard]] auto begin() const {
return m_compositions.cbegin();
}
auto end() {
return m_compositions.end();
}
[[nodiscard]] auto end() const {
return m_compositions.cend();
}
};
}; // namespace fourdst::composition
atomicSpecies.h
CompositionAbstract
Abstract base class for chemical composition representations.
Definition composition_abstract.h:32
fourdst::composition::Composition::m_cache
CompositionCache m_cache
Cache for computed properties to avoid redundant calculations.
Definition composition.h:297
fourdst::composition::Composition::~Composition
~Composition() override=default
Default destructor.
fourdst::composition::Composition::setCompositionMode
void setCompositionMode(bool massFracMode)
Sets the composition mode (mass fraction vs. number fraction).
Definition composition.cpp:762
fourdst::composition::Composition::getSpeciesIndex
size_t getSpeciesIndex(const std::string &symbol) const override
get the index in the sorted vector representation for a given symbol
Definition composition.cpp:917
fourdst::composition::Composition::getComposition
std::pair< std::unordered_map< std::string, CompositionEntry >, GlobalComposition > getComposition() const
Gets all composition entries and the global composition data.
Definition composition.cpp:682
fourdst::composition::Composition::subset
Composition subset(const std::vector< std::string > &symbols, const std::string &method="norm") const
Creates a new Composition object containing a subset of species from this one.
Definition composition.cpp:734
fourdst::composition::Composition::registerSymbol
void registerSymbol(const std::string &symbol, bool massFracMode=true)
Registers a new symbol for inclusion in the composition.
Definition composition.cpp:255
fourdst::composition::Composition::m_config
config::Config & m_config
Definition composition.h:285
fourdst::composition::Composition::Composition
Composition()=default
Default constructor.
fourdst::composition::Composition::operator+
Composition operator+(const Composition &other) const
Overloads the + operator to mix two compositions with a 50/50 fraction.
Definition composition.cpp:1054
fourdst::composition::Composition::operator<<
friend std::ostream & operator<<(std::ostream &os, const Composition &composition)
Overloaded output stream operator for Composition.
Definition composition.cpp:1078
fourdst::composition::Composition::m_registeredSymbols
std::set< std::string > m_registeredSymbols
The registered symbols.
Definition composition.h:294
fourdst::composition::Composition::mix
Composition mix(const Composition &other, double fraction) const
Mixes this composition with another to produce a new composition.
Definition composition.cpp:533
fourdst::composition::Composition::getRegisteredSymbols
std::set< std::string > getRegisteredSymbols() const override
Gets the registered symbols.
Definition composition.cpp:309
fourdst::composition::Composition::m_logManager
logging::LogManager & m_logManager
Definition composition.h:286
fourdst::composition::Composition::finalizeNumberFracMode
bool finalizeNumberFracMode(bool norm)
Finalizes the composition in number fraction mode.
Definition composition.cpp:489
fourdst::composition::Composition::setMassFraction
double setMassFraction(const std::string &symbol, const double &mass_fraction)
Sets the mass fraction for a given symbol.
Definition composition.cpp:343
fourdst::composition::Composition::getNumberFractionVector
std::vector< double > getNumberFractionVector() const override
Get a uniform vector representation of the number fractions stored in the composition object sorted s...
Definition composition.cpp:866
fourdst::composition::Composition::m_meanParticleMass
double m_meanParticleMass
The mean particle mass of the composition (\sum_{i} \frac{n_i}{m_i}. where n_i is the number fraction...
Definition composition.h:291
fourdst::composition::Composition::registerSpecies
void registerSpecies(const fourdst::atomic::Species &species, bool massFracMode=true)
Registers a new species by extracting its symbol.
Definition composition.cpp:293
fourdst::composition::Composition::operator=
Composition & operator=(Composition const &other)
Assignment operator.
Definition composition.cpp:243
fourdst::composition::Composition::hasSpecies
bool hasSpecies(const fourdst::atomic::Species &species) const override
Checks if a species is registered in the composition.
Definition composition.cpp:1029
fourdst::composition::Composition::getElectronAbundance
double getElectronAbundance() const override
Compute the electron abundance of the composition.
Definition composition.cpp:716
fourdst::composition::Composition::m_massFracMode
bool m_massFracMode
True if mass fraction mode, false if number fraction mode.
Definition composition.h:292
fourdst::composition::Composition::finalize
bool finalize(bool norm=false)
Finalizes the composition, making it ready for querying.
Definition composition.cpp:445
fourdst::composition::Composition::getMeanParticleMass
double getMeanParticleMass() const override
Compute the mean particle mass of the composition.
Definition composition.cpp:690
fourdst::composition::Composition::setNumberFraction
double setNumberFraction(const std::string &symbol, const double &number_fraction)
Sets the number fraction for a given symbol.
Definition composition.cpp:374
fourdst::composition::Composition::contains
bool contains(const atomic::Species &isotope) const override
Checks if a given isotope is present in the composition.
Definition composition.cpp:1038
fourdst::composition::Composition::getMassFractionVector
std::vector< double > getMassFractionVector() const override
Get a uniform vector representation of the mass fraction stored in the composition object sorted such...
Definition composition.cpp:840
fourdst::composition::Composition::validateComposition
void validateComposition(const std::vector< double > &fractions) const
Validates the given fractions, throwing an exception on failure.
Definition composition.cpp:327
fourdst::composition::Composition::finalizeMassFracMode
bool finalizeMassFracMode(bool norm)
Finalizes the composition in mass fraction mode.
Definition composition.cpp:453
fourdst::composition::Composition::isValidSymbol
static bool isValidSymbol(const std::string &symbol)
Checks if the given symbol is valid by checking against the global species database.
Definition composition.cpp:321
fourdst::composition::Composition::m_finalized
bool m_finalized
True if the composition is finalized.
Definition composition.h:289
fourdst::composition::Composition::m_compositions
std::unordered_map< std::string, CompositionEntry > m_compositions
The compositions.
Definition composition.h:295
fourdst::composition::Composition::getMassFraction
std::unordered_map< std::string, double > getMassFraction() const override
Gets the mass fractions of all species in the composition.
Definition composition.cpp:601
fourdst::composition::Composition::begin
auto begin()
Returns an iterator to the beginning of the composition map.
Definition composition.h:864
fourdst::composition::Composition::m_logger
quill::Logger * m_logger
Definition composition.h:287
fourdst::composition::Composition::getMolarAbundanceVector
std::vector< double > getMolarAbundanceVector() const override
Get a uniform vector representation of the molar abundances stored in the composition object sorted s...
Definition composition.cpp:891
fourdst::composition::Composition::hasSymbol
bool hasSymbol(const std::string &symbol) const override
Checks if a symbol is registered in the composition.
Definition composition.cpp:1023
fourdst::composition::Composition::getCanonicalComposition
CanonicalComposition getCanonicalComposition(bool harsh=false) const
Gets the current canonical composition (X, Y, Z).
Definition composition.cpp:785
fourdst::composition::Composition::getMolarAbundance
double getMolarAbundance(const std::string &symbol) const override
Gets the molar abundance (X_i / A_i) for a given symbol.
Definition composition.cpp:641
fourdst::composition::Composition::m_specificNumberDensity
double m_specificNumberDensity
The specific number density of the composition (\sum_{i} X_i m_i. Where X_i is the number fraction of...
Definition composition.h:290
fourdst::composition::Composition::isValidComposition
bool isValidComposition(const std::vector< double > &fractions) const
Checks if the given fractions are valid (sum to ~1.0).
Definition composition.cpp:334
fourdst::composition::Composition::end
auto end()
Returns an iterator to the end of the composition map.
Definition composition.h:880
fourdst::composition::Composition::begin
auto begin() const
Returns a const iterator to the beginning of the composition map.
Definition composition.h:872
fourdst::composition::Composition::getNumberFraction
std::unordered_map< std::string, double > getNumberFraction() const override
Gets the number fractions of all species in the composition.
Definition composition.cpp:633
fourdst::composition::Composition::getSpeciesAtIndex
atomic::Species getSpeciesAtIndex(size_t index) const override
Get the species at a given index in the sorted vector representation.
Definition composition.cpp:993
fourdst::composition::Composition::end
auto end() const
Returns a const iterator to the end of the composition map.
Definition composition.h:888
fourdst::composition::Composition::getRegisteredSpecies
std::set< fourdst::atomic::Species > getRegisteredSpecies() const override
Get a set of all species that are registered in the composition.
Definition composition.cpp:313
fourdst::composition::Composition::getMeanAtomicNumber
double getMeanAtomicNumber() const override
Compute the mean atomic number of the composition.
Definition composition.cpp:698
composition_abstract.h
fourdst::composition
Definition composition.h:34
fourdst::atomic::Species
Represents an atomic species (isotope) with its fundamental physical properties.
Definition atomicSpecies.h:51
fourdst::composition::CanonicalComposition
Represents the canonical (X, Y, Z) composition of stellar material.
Definition composition.h:44
fourdst::composition::CanonicalComposition::operator<<
friend std::ostream & operator<<(std::ostream &os, const CanonicalComposition &composition)
Overloads the stream insertion operator for easy printing.
Definition composition.h:55
fourdst::composition::CanonicalComposition::Y
double Y
Mass fraction of Helium.
Definition composition.h:46
fourdst::composition::CanonicalComposition::X
double X
Mass fraction of Hydrogen.
Definition composition.h:45
fourdst::composition::CanonicalComposition::Z
double Z
Mass fraction of Metals.
Definition composition.h:47
fourdst::composition::Composition::CompositionCache
Definition composition.h:257
fourdst::composition::Composition::CompositionCache::sortedSpecies
std::optional< std::vector< atomic::Species > > sortedSpecies
Cached vector of sorted species (by mass).
Definition composition.h:263
fourdst::composition::Composition::CompositionCache::numberFractions
std::optional< std::vector< double > > numberFractions
Cached vector of number fractions.
Definition composition.h:261
fourdst::composition::Composition::CompositionCache::canonicalComp
std::optional< CanonicalComposition > canonicalComp
Cached canonical composition data.
Definition composition.h:259
fourdst::composition::Composition::CompositionCache::globalComp
std::optional< GlobalComposition > globalComp
Cached global composition data.
Definition composition.h:258
fourdst::composition::Composition::CompositionCache::molarAbundances
std::optional< std::vector< double > > molarAbundances
Cached vector of molar abundances.
Definition composition.h:262
fourdst::composition::Composition::CompositionCache::sortedSymbols
std::optional< std::vector< std::string > > sortedSymbols
Cached vector of sorted species (by mass).
Definition composition.h:264
fourdst::composition::Composition::CompositionCache::clear
void clear()
Definition composition.h:267
fourdst::composition::Composition::CompositionCache::massFractions
std::optional< std::vector< double > > massFractions
Cached vector of mass fractions.
Definition composition.h:260
fourdst::composition::Composition::CompositionCache::Ye
std::optional< double > Ye
Cached electron abundance.
Definition composition.h:265
fourdst::composition::Composition::CompositionCache::is_clear
bool is_clear() const
Definition composition.h:278
fourdst::composition::CompositionEntry::setNumberFracMode
bool setNumberFracMode(double totalMolesPerMass)
Switches the mode to number fraction mode.
Definition composition.cpp:171
fourdst::composition::CompositionEntry::m_relAbundance
double m_relAbundance
The relative abundance, used internally for conversions. For mass fraction mode, this is X_i / A_i; f...
Definition composition.h:91
fourdst::composition::CompositionEntry::getMassFracMode
bool getMassFracMode() const
Gets the mode of the composition entry.
Definition composition.cpp:183
fourdst::composition::CompositionEntry::CompositionEntry
CompositionEntry()
Default constructor. Initializes a default entry (H-1), but in an uninitialized state.
Definition composition.cpp:69
fourdst::composition::CompositionEntry::m_massFracMode
bool m_massFracMode
The mode of the composition entry. True if mass fraction, false if number fraction.
Definition composition.h:87
fourdst::composition::CompositionEntry::m_numberFraction
double m_numberFraction
The number fraction (mole fraction) of the species. Valid only if m_massFracMode is false.
Definition composition.h:90
fourdst::composition::CompositionEntry::number_fraction
double number_fraction() const
Gets the number fraction of the species.
Definition composition.cpp:110
fourdst::composition::CompositionEntry::CompositionEntry
CompositionEntry(const CompositionEntry &entry)
Copy constructor.
fourdst::composition::CompositionEntry::m_initialized
bool m_initialized
True if the composition entry has been initialized with a valid species.
Definition composition.h:96
fourdst::composition::CompositionEntry::m_cachedNumberFraction
double m_cachedNumberFraction
Cached number fraction for conversions when in mass fraction mode.
Definition composition.h:93
fourdst::composition::CompositionEntry::setMassFracMode
bool setMassFracMode(double meanMolarMass)
Switches the mode to mass fraction mode.
Definition composition.cpp:159
fourdst::composition::CompositionEntry::setMassFraction
void setMassFraction(double mass_fraction)
Sets the mass fraction of the species.
Definition composition.cpp:134
fourdst::composition::CompositionEntry::symbol
std::string symbol() const
Gets the chemical symbol of the species.
Definition composition.cpp:98
fourdst::composition::CompositionEntry::setSpecies
void setSpecies(const std::string &symbol)
Sets the species for the composition entry. This can only be done once.
Definition composition.cpp:86
fourdst::composition::CompositionEntry::mass_fraction
double mass_fraction() const
Gets the mass fraction of the species.
Definition composition.cpp:102
fourdst::composition::CompositionEntry::m_isotope
atomic::Species m_isotope
The atomic::Species object containing detailed isotope data.
Definition composition.h:86
fourdst::composition::CompositionEntry::setNumberFraction
void setNumberFraction(double number_fraction)
Sets the number fraction of the species.
Definition composition.cpp:148
fourdst::composition::CompositionEntry::rel_abundance
double rel_abundance() const
Gets the relative abundance of the species.
Definition composition.cpp:126
fourdst::composition::CompositionEntry::m_symbol
std::string m_symbol
The chemical symbol of the species (e.g., "H-1", "Fe-56").
Definition composition.h:85
fourdst::composition::CompositionEntry::m_molesPerMass
double m_molesPerMass
Definition composition.h:92
fourdst::composition::CompositionEntry::m_massFraction
double m_massFraction
The mass fraction of the species. Valid only if m_massFracMode is true.
Definition composition.h:89
fourdst::composition::CompositionEntry::operator<<
friend std::ostream & operator<<(std::ostream &os, const CompositionEntry &entry)
Overloaded output stream operator for CompositionEntry.
Definition composition.cpp:1070
fourdst::composition::CompositionEntry::isotope
atomic::Species isotope() const
Gets the isotope data for the species.
Definition composition.cpp:130
fourdst::composition::GlobalComposition
Represents global properties of a finalized composition.
Definition composition.h:70
fourdst::composition::GlobalComposition::specificNumberDensity
double specificNumberDensity
The specific number density (moles per unit mass, sum of X_i/M_i), where X_i is mass fraction and M_i...
Definition composition.h:71
fourdst::composition::GlobalComposition::operator<<
friend std::ostream & operator<<(std::ostream &os, const GlobalComposition &comp)
Definition composition.cpp:1060
fourdst::composition::GlobalComposition::meanParticleMass
double meanParticleMass
The mean mass per particle (inverse of specific number density). Units: g/mol.
Definition composition.h:72