Manages a collection of chemical species and their abundances. More...

#include <composition.h>

Inheritance diagram for fourdst::composition::Composition:

Collaboration diagram for fourdst::composition::Composition:

Classes
struct	CompositionCache
	Caches computed properties of the composition to avoid redundant calculations. More...

Public Types
using	iterator = detail::CompositionIterator<false>

using	const_iterator = detail::CompositionIterator<true>

Public Types inherited from fourdst::composition::CompositionAbstract
using	iterator = detail::CompositionIterator<false>

using	const_iterator = detail::CompositionIterator<true>

Public Member Functions
	Composition ()=default
	Default constructor.

	~Composition () override=default
	Default destructor.

	Composition (const std::vector< std::string > &symbols)
	Constructs a Composition and registers the given symbols from a vector.

	Composition (const std::vector< atomic::Species > &species)
	Constructs a Composition and registers the given species from a vector.

	Composition (const std::set< std::string > &symbols)
	Constructs a Composition and registers the given symbols from a set.

	Composition (const std::set< atomic::Species > &species)
	Constructs a Composition and registers the given species from a set.

	Composition (const std::unordered_set< std::string > &symbols)

	Composition (const std::unordered_set< atomic::Species > &species)

	Composition (const std::vector< std::string > &symbols, const std::vector< double > &molarAbundances)
	Constructs a Composition from symbols and their corresponding molar abundances.

	Composition (const std::vector< atomic::Species > &species, const std::vector< double > &molarAbundances)
	Constructs a Composition from species and their corresponding molar abundances.

	Composition (const std::set< std::string > &symbols, const std::vector< double > &molarAbundances)
	Constructs a Composition from symbols in a set and their corresponding molar abundances.

	Composition (const std::unordered_map< std::string, double > &symbolMolarAbundances)

	Composition (const std::map< std::string, double > &symbolMolarAbundances)

	Composition (const std::unordered_map< atomic::Species, double > &speciesMolarAbundances)

	Composition (const std::map< atomic::Species, double > &speciesMolarAbundances)

	Composition (const Composition &composition)
	Constructs a Composition from another Composition.

	Composition (const CompositionAbstract &composition)

Composition &	operator= (Composition const &other)
	Assignment operator.

Composition &	operator= (const CompositionAbstract &other)

void	registerSymbol (const std::string &symbol)
	Registers a new symbol for inclusion in the composition.

void	registerSymbol (const std::vector< std::string > &symbols)
	Registers multiple new symbols.

void	registerSpecies (const atomic::Species &species) noexcept
	Registers a new species by extracting its symbol.

void	registerSpecies (const std::vector< atomic::Species > &species) noexcept
	Registers a vector of new species.

bool	contains (const atomic::Species &species) const noexcept override
	Checks if a given species is present in the composition.

bool	contains (const std::string &symbol) const override
	Checks if a given symbol is present in the composition.

size_t	size () const noexcept override
	Gets the number of registered species in the composition.

void	setMolarAbundance (const std::string &symbol, const double &molar_abundance)
	Sets the molar abundance for a given symbol.

void	setMolarAbundance (const atomic::Species &species, const double &molar_abundance)
	Sets the molar abundance for a given isotope.

void	setMolarAbundance (const std::vector< std::string > &symbols, const std::vector< double > &molar_abundances)
	Sets the molar abundances for a list of symbols.

void	setMolarAbundance (const std::vector< atomic::Species > &species, const std::vector< double > &molar_abundances)
	Sets the molar abundances for a list of isotopes.

void	setMolarAbundance (const std::set< std::string > &symbols, const std::vector< double > &molar_abundances)
	Sets the molar abundances for a set of symbols.

void	setMolarAbundance (const std::set< atomic::Species > &species, const std::vector< double > &molar_abundances)
	Sets the molar abundances for a set of isotopes.

std::set< std::string >	getRegisteredSymbols () const noexcept override
	Gets the registered symbols.

const std::vector< atomic::Species > &	getRegisteredSpecies () const noexcept override
	Get a set of all species that are registered in the composition.

std::unordered_map< atomic::Species, double >	getMassFraction () const noexcept override
	Gets the mass fractions of all species in the composition.

double	getMassFraction (const std::string &symbol) const override
	Gets the mass fraction for a given symbol. See the overload for species-based lookup for more details on how mass fractions are calculated.

double	getMassFraction (const atomic::Species &species) const override
	Gets the mass fraction for a given species.

double	getNumberFraction (const std::string &symbol) const override
	Gets the number fraction for a given symbol. See the overload for species-based lookup for more details on how number fractions are calculated.

double	getNumberFraction (const atomic::Species &species) const override
	Gets the number fraction for a given species.

std::unordered_map< atomic::Species, double >	getNumberFraction () const noexcept override
	Gets the number fractions of all species in the composition.

double	getMolarAbundance (const std::string &symbol) const override
	Gets the molar abundances of all species in the composition.

double	getMolarAbundance (const atomic::Species &species) const override
	Gets the molar abundance for a given species.

double	getMeanParticleMass () const noexcept override
	Compute the mean particle mass of the composition.

double	getElectronAbundance () const noexcept override
	Compute the electron abundance of the composition.

CanonicalComposition	getCanonicalComposition () const
	Compute the canonical composition (X, Y, Z) of the composition.

std::vector< double >	getMassFractionVector () const noexcept override
	Get a uniform vector representation of the mass fraction stored in the composition object sorted such that the lightest species is at index 0 and the heaviest is at the last index.

std::vector< double >	getNumberFractionVector () const noexcept override
	Get a uniform vector representation of the number fractions stored in the composition object sorted such that the lightest species is at index 0 and the heaviest is at the last index.

std::vector< double >	getMolarAbundanceVector () const noexcept override
	Get a uniform vector representation of the molar abundances stored in the composition object sorted such that the lightest species is at index 0 and the heaviest is at the last index.

size_t	getSpeciesIndex (const std::string &symbol) const override
	get the index in the sorted vector representation for a given symbol

size_t	getSpeciesIndex (const atomic::Species &species) const override
	get the index in the sorted vector representation for a given symbol

atomic::Species	getSpeciesAtIndex (size_t index) const override
	Get the species at a given index in the sorted vector representation.

std::unique_ptr< CompositionAbstract >	clone () const override

iterator	begin () override
	Returns an iterator to the beginning of the molar abundance map.

const_iterator	begin () const override
	Returns a const iterator to the beginning of the molar abundance map.

detail::CompositionIterator< false >	end () override
	Returns an iterator to the end of the molar abundance map.

detail::CompositionIterator< true >	end () const override
	Returns a const iterator to the end of the molar abundance map.

std::size_t	hash () const override

Public Member Functions inherited from fourdst::composition::CompositionAbstract
virtual	~CompositionAbstract ()=default
	Virtual destructor.

Private Types
enum class	SpeciesIndexLookupError : uint8_t { NO_REGISTERED_SPECIES , SPECIES_NOT_FOUND }

Private Member Functions
std::expected< std::ptrdiff_t, SpeciesIndexLookupError >	findSpeciesIndex (const atomic::Species &species) const noexcept

Static Private Member Functions
static quill::Logger *	getLogger ()
	Gets the logger instance for the Composition class. This is static to ensure that all composition objects share the same logger instance.

static std::vector< atomic::Species >	symbolVectorToSpeciesVector (const std::vector< std::string > &symbols)

Private Attributes
std::vector< atomic::Species >	m_species

std::vector< double >	m_molarAbundances

CompositionCache	m_cache
	Cache for computed properties to avoid redundant calculations.

Friends
std::ostream &	operator<< (std::ostream &os, const Composition &composition)
	Overloaded output stream operator for Composition.

Detailed Description

Manages a collection of chemical species and their abundances.

This class is a primary interface for defining and manipulating material compositions. In order to use the Composition class a user must first register symbols or species. Symbols are the string representation of a species (i.e. deuterium would be "H-2" whereas Beryllium 7 would be "Be-7") and then set the molar abundances. Species are the data structure fourdst::atomic::Species version. Here Deuterium would be represented by the Species fourdst::atomic::H_2 whereas Beryllium 7 would be fourdst::atomic::Be_7. Once the symbols/species have been registered the user can then set molar abundances.

Once the Composition object has been populated the user can query mass fractions, number fractions, electron abundances, mean particle mass, molar abundance, and Canonical (X, Y, Z) composition.

Note: This class only accepts molar abundances as input. If you wish to construct a Composition using a vector of mass fractions, those must first be converted to molar abundances. There is a helper function fourdst::composition::buildCompositionFromMassFractions which wll facilitate just that.

Exceptions

This	class throws various exceptions from `fourdst::composition::exceptions` for invalid operations, such as using unregistered symbols or providing invalid abundances.

Basic Example:: Composition comp;

comp.registerSymbol("H-1");

comp.registerSymbol("He-4");

comp.setMolarAbundance("H-1", 0.75);

comp.setMolarAbundance("He-4", 0.25); // Note Molar Abundances do not need to sum to 1

fourdst::composition::Composition::Composition
Composition()=default
Default constructor.

fourdst::composition::Composition::setMolarAbundance
void setMolarAbundance(const std::string &symbol, const double &molar_abundance)
Sets the molar abundance for a given symbol.
Definition composition.cpp:321

fourdst::composition::Composition::registerSymbol
void registerSymbol(const std::string &symbol)
Registers a new symbol for inclusion in the composition.
Definition composition.cpp:234

Definition at line 99 of file composition.h.

Member Typedef Documentation

◆ const_iterator

using fourdst::composition::Composition::const_iterator = detail::CompositionIterator<true>

Definition at line 102 of file composition.h.

◆ iterator

using fourdst::composition::Composition::iterator = detail::CompositionIterator<false>

Definition at line 101 of file composition.h.

Member Enumeration Documentation

◆ SpeciesIndexLookupError

enum class fourdst::composition::Composition::SpeciesIndexLookupError : uint8_t

strongprivate

Enumerator
NO_REGISTERED_SPECIES
SPECIES_NOT_FOUND

Definition at line 146 of file composition.h.

Constructor & Destructor Documentation

◆ Composition() [1/16]

fourdst::composition::Composition::Composition ( )

default

Default constructor.

Creates an empty Composition object. No symbols or species are registered initially; however, the user can register symbols or species later using the provided methods.

◆ ~Composition()

fourdst::composition::Composition::~Composition ( )

overridedefault

Default destructor.

◆ Composition() [2/16]

fourdst::composition::Composition::Composition ( const std::vector< std::string > & symbols )

explicit

Constructs a Composition and registers the given symbols from a vector.

Parameters

symbols The symbols to register.

Exceptions

exceptions::UnknownSymbolError if any symbol is invalid. Symbols are invalid if they are not registered at compile time in the atomic species database (fourdst/atomic/species.h).

Example:: std::vector<std::string> symbols = {"H-1", "O-16"};

Composition comp(symbols);

fourdst::composition::Composition
Manages a collection of chemical species and their abundances.
Definition composition.h:99

Definition at line 81 of file composition.cpp.

◆ Composition() [3/16]

fourdst::composition::Composition::Composition ( const std::vector< atomic::Species > & species )

explicit

Constructs a Composition and registers the given species from a vector.

Parameters

species The species to register.

Example:: std::vector<fourdst::atomic::Species> species = {fourdst::atomic::H_1, fourdst::atomic::O_16};

Composition comp(species);

fourdst::atomic::H_1
static const Species H_1("H-1", "H", -1, 0, 1, 1, 0.0, "B-", std::numeric_limits< double >::quiet_NaN(), std::numeric_limits< double >::infinity(), "/2+*", "S=99.9855 78", 1.007825031898, 1.4e-05)

fourdst::atomic::O_16
static const Species O_16("O-16", "O", 0, 8, 8, 16, 7976.2072, "B-", -15412.184, std::numeric_limits< double >::infinity(), "+", "S=99.757 11", 15.99491461926, 0.00032)

Note: Because species are strongly typed, this constructor does not need to check if the species is valid. that is to say that the compiler will only allow valid species to be passed in. Therefore, this constructor is marked noexcept and may therefore be slightly more performant than the symbol-based constructor.

Definition at line 85 of file composition.cpp.

◆ Composition() [4/16]

fourdst::composition::Composition::Composition ( const std::set< std::string > & symbols )

explicit

Constructs a Composition and registers the given symbols from a set.

Parameters

symbols The symbols to register.

Exceptions

exceptions::UnknownSymbolError if any symbol is invalid. Symbols are invalid if they are not registered at compile time in the atomic species database (fourdst/atomic/species.h).

Example:: std::set<std::string> symbols = {"H-1", "O-16"};

Composition comp(symbols);

Constructors without molar abundances /// These all delegate to the ctor /// vector<Species> ///

Definition at line 65 of file composition.cpp.

◆ Composition() [5/16]

fourdst::composition::Composition::Composition ( const std::set< atomic::Species > & species )

explicit

Constructs a Composition and registers the given species from a set.

Parameters

species The species to register.

Example:: std::set<fourdst::atomic::Species> species = {fourdst::atomic::H_1, fourdst::atomic::O_16};

Composition comp(species);

Note: Because species are strongly typed, this constructor does not need to check if the species is valid. that is to say that the compiler will only allow valid species to be passed in. Therefore, this constructor is marked noexcept and may therefore be slightly more performant than the symbol-based constructor.

Definition at line 69 of file composition.cpp.

◆ Composition() [6/16]

fourdst::composition::Composition::Composition ( const std::unordered_set< std::string > & symbols )

explicit

Definition at line 73 of file composition.cpp.

◆ Composition() [7/16]

fourdst::composition::Composition::Composition ( const std::unordered_set< atomic::Species > & species )

explicit

Definition at line 77 of file composition.cpp.

◆ Composition() [8/16]

fourdst::composition::Composition::Composition	(	const std::vector< std::string > &	symbols,
		const std::vector< double > &	molarAbundances )

Constructs a Composition from symbols and their corresponding molar abundances.

Parameters

symbols	The symbols to register.
molarAbundances	The corresponding molar abundances for each symbol.

Exceptions

exceptions::UnknownSymbolError	if any symbol is invalid. Symbols are invalid if they are not registered at compile time in the atomic species database (`fourdst/atomic/species.h`).
exceptions::InvalidCompositionError	if the number of symbols does not match the number of molar abundances.

Example:: std::vector<std::string> symbols = {"H-1", "O-16"};

std::vector<double> molarAbundances = {1.03, 0.6};

Composition comp(symbols, molarAbundances);

Note: Molar abundances do not need to sum to 1.0, they are an absolute quantity.

Constructors with molar abundances /// These all delegate to the ctor /// vector<Species, vector<double>> ///

Definition at line 105 of file composition.cpp.

◆ Composition() [9/16]

fourdst::composition::Composition::Composition	(	const std::vector< atomic::Species > &	species,
		const std::vector< double > &	molarAbundances )

Constructs a Composition from species and their corresponding molar abundances.

Parameters

species	The species to register.
molarAbundances	The corresponding molar abundances for each species.

Exceptions

exceptions::InvalidCompositionError if the number of species does not match the number of molar abundances.

Example:: std::vector<fourdst::atomic::Species> species = {fourdst::atomic::H_1, fourdst::atomic::O_16};

std::vector<double> molarAbundances = {1.03, 0.6};

Composition comp(species, molarAbundances);

Note: Molar abundances do not need to sum to 1.0, they are an absolute quantity.

Definition at line 144 of file composition.cpp.

◆ Composition() [10/16]

fourdst::composition::Composition::Composition	(	const std::set< std::string > &	symbols,
		const std::vector< double > &	molarAbundances )

Constructs a Composition from symbols in a set and their corresponding molar abundances.

Parameters

symbols	The symbols to register.
molarAbundances	The corresponding molar abundances for each symbol.

Exceptions

exceptions::UnknownSymbolError	if any symbol is invalid. Symbols are invalid if they are not registered at compile time in the atomic species database (`fourdst/atomic/species.h`).
exceptions::InvalidCompositionError	if the number of symbols does not match the number of molar abundances.

Example:: std::set<std::string> symbols = {"H-1", "O-16"};

std::vector<double> molarAbundances = {1.03, 0.6};

Composition comp(symbols, molarAbundances);

Note: Molar abundances do not need to sum to 1.0, they are an absolute quantity.

Definition at line 110 of file composition.cpp.

◆ Composition() [11/16]

fourdst::composition::Composition::Composition ( const std::unordered_map< std::string, double > & symbolMolarAbundances )

explicit

Definition at line 116 of file composition.cpp.

◆ Composition() [12/16]

fourdst::composition::Composition::Composition ( const std::map< std::string, double > & symbolMolarAbundances )

explicit

Definition at line 123 of file composition.cpp.

◆ Composition() [13/16]

fourdst::composition::Composition::Composition ( const std::unordered_map< atomic::Species, double > & speciesMolarAbundances )

explicit

Definition at line 130 of file composition.cpp.

◆ Composition() [14/16]

fourdst::composition::Composition::Composition ( const std::map< atomic::Species, double > & speciesMolarAbundances )

explicit

Definition at line 137 of file composition.cpp.

◆ Composition() [15/16]

fourdst::composition::Composition::Composition ( const Composition & composition )

Constructs a Composition from another Composition.

Copy and conversion constructors ///.

Parameters

composition The Composition to copy.

Definition at line 192 of file composition.cpp.

◆ Composition() [16/16]

fourdst::composition::Composition::Composition ( const CompositionAbstract & composition )

explicit

Definition at line 197 of file composition.cpp.

Member Function Documentation

◆ begin() [1/2]

const_iterator fourdst::composition::Composition::begin ( ) const

inlinenodiscardoverridevirtual

Returns a const iterator to the beginning of the molar abundance map.

Returns: A const iterator to the beginning.

Example:: Composition comp({"H-1", "He-4", "C-12"}, {1.02, 0.56, 0.02});

for (const auto& [sp, y] : comp) {

std::cout << "Species: " << sp << ", Molar Abundance: " << y << std::endl;

}

Note: Because we store molar abundances as a sorted map, keyed by species. And Because the < and > operators for species are defined based on their atomic mass. When iterating over the molar abundance map, species will be seen in order from lightest to heaviest.

Implements fourdst::composition::CompositionAbstract.

Definition at line 808 of file composition.h.

◆ begin() [2/2]

iterator fourdst::composition::Composition::begin ( )

inlinenodiscardoverridevirtual

Returns an iterator to the beginning of the molar abundance map.

Returns: An iterator to the beginning.

Example:: Composition comp({"H-1", "He-4", "C-12"}, {1.02, 0.56, 0.02});

for (const auto& [sp, y] : comp) {

std::cout << "Species: " << sp << ", Molar Abundance: " << y << std::endl;

}

Note: Because we store molar abundances as a sorted map, keyed by species. And Because the < and > operators for species are defined based on their atomic mass. When iterating over the molar abundance map, species will be seen in order from lightest to heaviest.

Implements fourdst::composition::CompositionAbstract.

Definition at line 787 of file composition.h.

◆ clone()

std::unique_ptr< CompositionAbstract > fourdst::composition::Composition::clone ( ) const

nodiscardoverridevirtual

Implements fourdst::composition::CompositionAbstract.

Definition at line 226 of file composition.cpp.

◆ contains() [1/2]

bool fourdst::composition::Composition::contains ( const atomic::Species & species ) const

nodiscardoverridevirtualnoexcept

Checks if a given species is present in the composition.

Parameters

species The isotope to check for.

Returns: True if the species is in the composition, false otherwise.

Implements fourdst::composition::CompositionAbstract.

Definition at line 693 of file composition.cpp.

◆ contains() [2/2]

bool fourdst::composition::Composition::contains ( const std::string & symbol ) const

nodiscardoverridevirtual

Checks if a given symbol is present in the composition.

Parameters

symbol The symbol to check for.

Returns: True if the symbol is in the composition, false otherwise.

Exceptions

exceptions::UnknownSymbolError if the symbol is not in the atomic species database.

Implements fourdst::composition::CompositionAbstract.

Definition at line 699 of file composition.cpp.

◆ end() [1/2]

detail::CompositionIterator< true > fourdst::composition::Composition::end ( ) const

inlinenodiscardoverridevirtual

Returns a const iterator to the end of the molar abundance map.

Returns: A const iterator to the end.

Example:: Composition comp({"H-1", "He-4", "C-12"}, {1.02, 0.56, 0.02});

for (const auto& [sp, y] : comp) {

std::cout << "Species: " << sp << ", Molar Abundance: " << y << std::endl;

}

Note: Because we store molar abundances as a sorted map, keyed by species. And Because the < and > operators for species are defined based on their atomic mass. When iterating over the molar abundance map, species will be seen in order from lightest to heaviest.

Implements fourdst::composition::CompositionAbstract.

Definition at line 850 of file composition.h.

◆ end() [2/2]

detail::CompositionIterator< false > fourdst::composition::Composition::end ( )

inlinenodiscardoverridevirtual

Returns an iterator to the end of the molar abundance map.

Returns: An iterator to the end.

Example:: Composition comp({"H-1", "He-4", "C-12"}, {1.02, 0.56, 0.02});

for (const auto& [sp, y] : comp) {

std::cout << "Species: " << sp << ", Molar Abundance: " << y << std::endl;

}

Note: Because we store molar abundances as a sorted map, keyed by species. And Because the < and > operators for species are defined based on their atomic mass. When iterating over the molar abundance map, species will be seen in order from lightest to heaviest.

Implements fourdst::composition::CompositionAbstract.

Definition at line 829 of file composition.h.

◆ findSpeciesIndex()

std::expected< std::ptrdiff_t, Composition::SpeciesIndexLookupError > fourdst::composition::Composition::findSpeciesIndex ( const atomic::Species & species ) const

nodiscardprivatenoexcept

Definition at line 713 of file composition.cpp.

◆ getCanonicalComposition()

CanonicalComposition fourdst::composition::Composition::getCanonicalComposition ( ) const

nodiscard

Compute the canonical composition (X, Y, Z) of the composition.

The canonical composition is defined as:

X: mass fraction of hydrogen ( $\sum_{i=1}^{7}X_{^{i}H}$ )
Y: mass fraction of helium ( $\sum_{i=3}^{10}X_{^{i}He}$ )
Z: mass fraction of all other elements (Everything else)

The canonical composition is computed by summing the mass fractions of all registered species in the composition according to their element type.

Returns: A CanonicalComposition struct containing the X, Y, and Z values.

Exceptions

exceptions::InvalidCompositionError if, after constructing the canonical composition, the sum X + Y + Z is not approximately equal to 1.0 (within a tolerance of 1e-16)

Definition at line 552 of file composition.cpp.

◆ getElectronAbundance()

double fourdst::composition::Composition::getElectronAbundance ( ) const

nodiscardoverridevirtualnoexcept

Compute the electron abundance of the composition.

The electron abundance is calculated using the formula:

$Y_e = \sum_i (Y_i \cdot Z_i)$

where:

is the molar abundance of species i.
is the atomic number (number of protons) of species i.

Returns: Ye (electron abundance).

Implements fourdst::composition::CompositionAbstract.

Definition at line 543 of file composition.cpp.

◆ getLogger()

static quill::Logger * fourdst::composition::Composition::getLogger ( )

inlinestaticprivate

Gets the logger instance for the Composition class. This is static to ensure that all composition objects share the same logger instance.

Returns: pointer to the logger instance.

Definition at line 156 of file composition.h.

◆ getMassFraction() [1/3]

std::unordered_map< atomic::Species, double > fourdst::composition::Composition::getMassFraction ( ) const

nodiscardoverridevirtualnoexcept

Gets the mass fractions of all species in the composition.

Returns: An unordered map of symbols to their mass fractions.

Note: This method will construct a new unordered map each time it is called.

Implements fourdst::composition::CompositionAbstract.

Definition at line 460 of file composition.cpp.

◆ getMassFraction() [2/3]

double fourdst::composition::Composition::getMassFraction ( const atomic::Species & species ) const

nodiscardoverridevirtual

Gets the mass fraction for a given species.

The mass fraction X_i for a species is calculated using the formula:

$X_i = \frac{(Y_i \cdot A_i)}{\sum_j (Y_j \cdot A_j)}$

where:

is the molar abundance of species i.
is the atomic mass of species i.
The denominator sums over all species j in the composition.

This formula ensures that the mass fractions of all species sum to 1.0.

Parameters

species The species to get the mass fraction for.

Returns: The mass fraction for the given isotope.

Exceptions

exceptions::UnregisteredSymbolError if the isotope is not registered in the composition.

Implements fourdst::composition::CompositionAbstract.

Definition at line 440 of file composition.cpp.

◆ getMassFraction() [3/3]

double fourdst::composition::Composition::getMassFraction ( const std::string & symbol ) const

nodiscardoverridevirtual

Gets the mass fraction for a given symbol. See the overload for species-based lookup for more details on how mass fractions are calculated.

Parameters

symbol The symbol to get the mass fraction for.

Returns: The mass fraction for the given symbol.

Exceptions

exceptions::UnknownSymbolError	if the symbol is not in the atomic species database.
exceptions::UnregisteredSymbolError	if the symbol is not in the composition.

Implements fourdst::composition::CompositionAbstract.

Definition at line 432 of file composition.cpp.

◆ getMassFractionVector()

std::vector< double > fourdst::composition::Composition::getMassFractionVector ( ) const

nodiscardoverridevirtualnoexcept

Get a uniform vector representation of the mass fraction stored in the composition object sorted such that the lightest species is at index 0 and the heaviest is at the last index.

This is primarily useful for external libraries which need to ensure that vector representation uniformity is maintained

Returns: the vector of mass fractions sorted by species mass (lightest to heaviest).

Implements fourdst::composition::CompositionAbstract.

Definition at line 596 of file composition.cpp.

◆ getMeanParticleMass()

double fourdst::composition::Composition::getMeanParticleMass ( ) const

nodiscardoverridevirtualnoexcept

Compute the mean particle mass of the composition.

The mean particle mass is calculated using the formula:

$\bar{A} = \frac{\sum_i (Y_i \cdot A_i)}{\sum_j Y_j}$

where:

is the molar abundance of species i.
is the atomic mass of species i.
The sums run over all species i in the composition.

Returns: Mean particle mass in atomic mass units (g/mol).

Implements fourdst::composition::CompositionAbstract.

Definition at line 530 of file composition.cpp.

◆ getMolarAbundance() [1/2]

double fourdst::composition::Composition::getMolarAbundance ( const atomic::Species & species ) const

nodiscardoverridevirtual

Gets the molar abundance for a given species.

Parameters

species The species to get the molar abundance for.

Returns: The molar abundance for the given isotope.

Exceptions

exceptions::UnregisteredSymbolError if the isotope is not registered in the composition.

Note: These are the most performant quantities to retrieve since they are stored directly in the composition object and require no computation.

Implements fourdst::composition::CompositionAbstract.

Definition at line 515 of file composition.cpp.

◆ getMolarAbundance() [2/2]

double fourdst::composition::Composition::getMolarAbundance ( const std::string & symbol ) const

nodiscardoverridevirtual

Gets the molar abundances of all species in the composition.

Exceptions

exceptions::UnknownSymbolError	if any symbol is not in the atomic species database.
exceptions::UnregisteredSymbolError	if any symbol is not in the composition.

Returns: The molar abundance of the symbol.

Note: These are the most performant quantities to retrieve since they are stored directly in the composition object and require no computation. This overload is slightly less performant than the species-based overload since it needs to validate the symbol exists in the atomic species database.

Implements fourdst::composition::CompositionAbstract.

Definition at line 504 of file composition.cpp.

◆ getMolarAbundanceVector()

std::vector< double > fourdst::composition::Composition::getMolarAbundanceVector ( ) const

nodiscardoverridevirtualnoexcept

Get a uniform vector representation of the molar abundances stored in the composition object sorted such that the lightest species is at index 0 and the heaviest is at the last index.

This is primarily useful for external libraries which need to ensure that vector representation uniformity is maintained

Returns: the vector of molar abundances sorted by species mass (lightest to heaviest).

Implements fourdst::composition::CompositionAbstract.

Definition at line 631 of file composition.cpp.

◆ getNumberFraction() [1/3]

std::unordered_map< atomic::Species, double > fourdst::composition::Composition::getNumberFraction ( ) const

nodiscardoverridevirtualnoexcept

Gets the number fractions of all species in the composition.

Returns: An unordered map of symbols to their number fractions.

Note: This method will construct a new unordered map each time it is called.

Implements fourdst::composition::CompositionAbstract.

Definition at line 496 of file composition.cpp.

◆ getNumberFraction() [2/3]

double fourdst::composition::Composition::getNumberFraction ( const atomic::Species & species ) const

nodiscardoverridevirtual

Gets the number fraction for a given species.

The number fraction Y_i for a species is calculated using the formula:

$X_i = \frac{Y_i}{\sum_j Y_j}$

where:

is the molar abundance of species i.
The denominator sums over all species j in the composition.

This formula ensures that the number fractions of all species sum to 1.0.

Parameters

species The species to get the number fraction for.

Returns: The number fraction for the given isotope.

Exceptions

exceptions::UnregisteredSymbolError if the isotope is not registered in the composition.

Implements fourdst::composition::CompositionAbstract.

Definition at line 479 of file composition.cpp.

◆ getNumberFraction() [3/3]

double fourdst::composition::Composition::getNumberFraction ( const std::string & symbol ) const

nodiscardoverridevirtual

Gets the number fraction for a given symbol. See the overload for species-based lookup for more details on how number fractions are calculated.

Parameters

symbol The symbol to get the number fraction for.

Returns: The number fraction for the given symbol.

Exceptions

exceptions::UnknownSymbolError	if the symbol is not in the atomic species database.
exceptions::UnregisteredSymbolError	if the symbol is not in the composition.

Implements fourdst::composition::CompositionAbstract.

Definition at line 469 of file composition.cpp.

◆ getNumberFractionVector()

std::vector< double > fourdst::composition::Composition::getNumberFractionVector ( ) const

nodiscardoverridevirtualnoexcept

Get a uniform vector representation of the number fractions stored in the composition object sorted such that the lightest species is at index 0 and the heaviest is at the last index.

This is primarily useful for external libraries which need to ensure that vector representation uniformity is maintained

Returns: the vector of number fractions sorted by species mass (lightest to heaviest).

Implements fourdst::composition::CompositionAbstract.

Definition at line 614 of file composition.cpp.

◆ getRegisteredSpecies()

const std::vector< atomic::Species > & fourdst::composition::Composition::getRegisteredSpecies ( ) const

nodiscardoverridevirtualnoexcept

Get a set of all species that are registered in the composition.

Returns: A set of atomic::Species objects registered in the composition.

Note: This will return a constant reference to the internal m_registeredSpecies set, therefore the return value of this method will only be valid as long as the Composition object is valid (i.e. it cannot outlive the Composition object it was called on).

Implements fourdst::composition::CompositionAbstract.

Definition at line 312 of file composition.cpp.

◆ getRegisteredSymbols()

std::set< std::string > fourdst::composition::Composition::getRegisteredSymbols ( ) const

nodiscardoverridevirtualnoexcept

Gets the registered symbols.

Returns: A set of registered symbols.

Note: This method will construct a new set each time it is called. If you need just need access to the registered species, consider using getRegisteredSpecies() instead which returns a constant reference to the internal set.

Implements fourdst::composition::CompositionAbstract.

Definition at line 304 of file composition.cpp.

◆ getSpeciesAtIndex()

atomic::Species fourdst::composition::Composition::getSpeciesAtIndex ( size_t index ) const

nodiscardoverridevirtual

Get the species at a given index in the sorted vector representation.

This is primarily useful for external libraries which need to ensure that vector representation uniformity is maintained

Parameters

index The index in the sorted vector representation for which to return the species. Must be in [0, N-1] where N is the number of registered species.

Exceptions

std::out_of_range if the index is out of range.

Returns: The species at the given index in the sorted vector representation.

Implements fourdst::composition::CompositionAbstract.

Definition at line 668 of file composition.cpp.

◆ getSpeciesIndex() [1/2]

size_t fourdst::composition::Composition::getSpeciesIndex ( const atomic::Species & species ) const

nodiscardoverridevirtual

get the index in the sorted vector representation for a given symbol

This is primarily useful for external libraries which need to ensure that vector representation uniformity is maintained

Parameters

species the species to look up the index for. Note that this is the index species data will be at if you were to call getMolarAbundanceVector(), getMassFractionVector(), or getNumberFractionVector()

Exceptions

exceptions::UnregisteredSymbolError if the symbol is not registered in the composition

Returns: The index of the symbol in the sorted vector representation.

Implements fourdst::composition::CompositionAbstract.

Definition at line 650 of file composition.cpp.

◆ getSpeciesIndex() [2/2]

size_t fourdst::composition::Composition::getSpeciesIndex ( const std::string & symbol ) const

nodiscardoverridevirtual

get the index in the sorted vector representation for a given symbol

This is primarily useful for external libraries which need to ensure that vector representation uniformity is maintained

Parameters

symbol the symbol to look up the index for. Note that this is the index species data will be at if you were to call getMolarAbundanceVector(), getMassFractionVector(), or getNumberFractionVector()

Exceptions

exceptions::UnknownSymbolError	if the symbol is not in the atomic species database.
exceptions::UnregisteredSymbolError	if the symbol is not registered in the composition

Returns: The index of the symbol in the sorted vector representation.

Implements fourdst::composition::CompositionAbstract.

Definition at line 639 of file composition.cpp.

◆ hash()

std::size_t fourdst::composition::Composition::hash ( ) const

nodiscardoverridevirtual

Implements fourdst::composition::CompositionAbstract.

Definition at line 684 of file composition.cpp.

◆ operator=() [1/2]

Composition & fourdst::composition::Composition::operator= ( Composition const & other )

Assignment operator.

Parameters

other The Composition to assign from.

Returns: A reference to this Composition.

Definition at line 204 of file composition.cpp.

◆ operator=() [2/2]

Composition & fourdst::composition::Composition::operator= ( const CompositionAbstract & other )

Definition at line 215 of file composition.cpp.

◆ registerSpecies() [1/2]

void fourdst::composition::Composition::registerSpecies ( const atomic::Species & species )

noexcept

Registers a new species by extracting its symbol.

Parameters

species The species to register.

Example:: #include "fourdst/composition/species.h"

Composition comp;

comp.registerSpecies(fourdst::atomic::C_12);

fourdst::composition::Composition::registerSpecies
void registerSpecies(const atomic::Species &species) noexcept
Registers a new species by extracting its symbol.
Definition composition.cpp:251

fourdst::atomic::C_12
static const Species C_12("C-12", "C", 0, 6, 6, 12, 7680.1446, "B-", -17338.0681, std::numeric_limits< double >::infinity(), "+", "S=98.94 6", 12.0, 0.0)

Note: Because species are strongly typed, this method does not need to check if the species is valid. that is to say that the compiler will only allow valid species to be passed in. Therefore, this method is marked noexcept and may therefore be slightly more performant than the symbol-based method.; upon registering a species, its molar abundance is initialized to 0.0.; All species are in the fourdst/atomic/species.h header file. These can be accessed directly through their fully qualified names (e.g., fourdst::atomic::C_12 for Carbon-12). Alternatively, these can also be accessed through a string-indexed map located in fourdst/atomic/species.h called fourdst::atomic::species ( e.g., fourdst::atomic::species.at("C-12") for Carbon-12).

Definition at line 251 of file composition.cpp.

◆ registerSpecies() [2/2]

void fourdst::composition::Composition::registerSpecies ( const std::vector< atomic::Species > & species )

noexcept

Registers a vector of new species.

Parameters

species The vector of species to register.

Example:: #include "fourdst/composition/species.h"

Composition comp;

std::vector<fourdst::atomic::Species> my_species = { ... };

comp.registerSpecies(my_species);

Note: upon registering a species, its molar abundance is initialized to 0.0. Therefore, registering a vector of species will initialize all their molar abundances to 0.0.; All species are in the fourdst/atomic/species.h header file. These can be accessed directly through their fully qualified names (e.g., fourdst::atomic::C_12 for Carbon-12). Alternatively, these can also be accessed through a string-indexed map located in fourdst/atomic/species.h called fourdst::atomic::species ( e.g., fourdst::atomic::species.at("C-12") for Carbon-12).

Definition at line 262 of file composition.cpp.

◆ registerSymbol() [1/2]

void fourdst::composition::Composition::registerSymbol ( const std::string & symbol )

Registers a new symbol for inclusion in the composition.

A symbol must be registered before its abundance can be set.

Parameters

symbol The symbol to register (e.g., "Fe-56").

Exceptions

exceptions::UnknownSymbolError if the symbol is not in the atomic species database.

Example:: Composition comp;

comp.registerSymbol("H-1");

comp.registerSymbol("He-4");

Note: upon registering a symbol, its molar abundance is initialized to 0.0.

Definition at line 234 of file composition.cpp.

◆ registerSymbol() [2/2]

void fourdst::composition::Composition::registerSymbol ( const std::vector< std::string > & symbols )

Registers multiple new symbols.

Parameters

symbols The symbols to register.

Exceptions

exceptions::UnknownSymbolError if any symbol is invalid.

Example:: std::vector<std::string> symbols = {"H-1", "O-16"};

Composition comp;

comp.registerSymbol(symbols);

Note: upon registering a symbol, its molar abundance is initialized to 0.0. Therefore, registering a vector of symbols will initialize all their molar abundances to 0.0.

Definition at line 245 of file composition.cpp.

◆ setMolarAbundance() [1/6]

void fourdst::composition::Composition::setMolarAbundance	(	const atomic::Species &	species,
		const double &	molar_abundance )

Sets the molar abundance for a given isotope.

Parameters

species	The isotope to set the molar abundance for.
molar_abundance	The molar abundance to set.

Exceptions

exceptions::UnregisteredSymbolError	if the isotope is not registered in the composition.
exceptions::InvalidCompositionError	if the molar abundance is negative.

Example:: #include "fourdst/composition/species.h"

Composition comp({fourdst::atomic::H_1, fourdst::atomic::He_4});

comp.setMolarAbundance(fourdst::atomic::H_1, 1.0);

comp.setMolarAbundance(fourdst::atomic::He_4, 0.5);

fourdst::atomic::He_4
static const Species He_4("He-4", "He", 0, 2, 2, 4, 7073.9156, "B-", -22898.274, std::numeric_limits< double >::infinity(), "+", "S=99.9998 2", 4.00260325413, 0.00016)

Note: Since this method does not need to validate the species exists in the database, it will generally be slightly more performant than the symbol-based method.

Definition at line 333 of file composition.cpp.

◆ setMolarAbundance() [2/6]

void fourdst::composition::Composition::setMolarAbundance	(	const std::set< atomic::Species > &	species,
		const std::vector< double > &	molar_abundances )

Sets the molar abundances for a set of isotopes.

Parameters

species	The isotopes to set the molar abundances for.
molar_abundances	The molar abundances to set.

Exceptions

exceptions::UnregisteredSymbolError	if any isotope is not registered in the composition.
exceptions::InvalidCompositionError	if any molar abundance is negative.

Example:: #include "fourdst/composition/species.h"

std::set<fourdst::atomic::Species> species = {fourdst::atomic::H_1, fourdst::atomic::He_4};

Composition comp(species);

comp.setMolarAbundance(species, {1.0, 0.5});

Note: Since this method does not need to validate the species exists in the database, it will generally be slightly more performant than the symbol-based method.

Definition at line 373 of file composition.cpp.

◆ setMolarAbundance() [3/6]

void fourdst::composition::Composition::setMolarAbundance	(	const std::set< std::string > &	symbols,
		const std::vector< double > &	molar_abundances )

Sets the molar abundances for a set of symbols.

Parameters

symbols	The symbols to set the molar abundances for.
molar_abundances	The molar abundances to set.

Exceptions

exceptions::UnknownSymbolError	if any symbol is not in the atomic species database.
exceptions::UnregisteredSymbolError	if any symbol is not in the composition.
exceptions::InvalidCompositionError	if any molar abundance is negative.

Example:: std::set<std::string> symbols = {"H-1", "He-4"};

Composition comp(symbols);

comp.setMolarAbundance(symbols, {1.0, 0.5});

Definition at line 366 of file composition.cpp.

◆ setMolarAbundance() [4/6]

void fourdst::composition::Composition::setMolarAbundance	(	const std::string &	symbol,
		const double &	molar_abundance )

Sets the molar abundance for a given symbol.

Parameters

symbol	The symbol to set the molar abundance for.
molar_abundance	The molar abundance to set.

Exceptions

exceptions::UnknownSymbolError	if the symbol is not in the atomic species database.
exceptions::UnregisteredSymbolError	if the symbol is not in the composition.
exceptions::InvalidCompositionError	if the molar abundance is negative.

Example:: Composition comp({"H-1", "He-4"});

comp.setMolarAbundance("H-1", 1.0);

comp.setMolarAbundance("He-4", 0.5);

Definition at line 321 of file composition.cpp.

◆ setMolarAbundance() [5/6]

void fourdst::composition::Composition::setMolarAbundance	(	const std::vector< atomic::Species > &	species,
		const std::vector< double > &	molar_abundances )

Sets the molar abundances for a list of isotopes.

Parameters

species	The isotopes to set the molar abundances for.
molar_abundances	The molar abundances to set.

Exceptions

exceptions::UnregisteredSymbolError	if any isotope is not registered in the composition.
exceptions::InvalidCompositionError	if any molar abundance is negative.

Example:: #include "fourdst/composition/species.h"

Composition comp({fourdst::atomic::H_1, fourdst::atomic::He_4});

comp.setMolarAbundance({fourdst::atomic::H_1, fourdst::atomic::He_4}, {1.0, 0.5});

Note: Since this method does not need to validate the species exists in the database, it will generally be slightly more performant than the symbol-based method.

Definition at line 380 of file composition.cpp.

◆ setMolarAbundance() [6/6]

void fourdst::composition::Composition::setMolarAbundance	(	const std::vector< std::string > &	symbols,
		const std::vector< double > &	molar_abundances )

Sets the molar abundances for a list of symbols.

Parameters

symbols	The symbols to set the molar abundances for.
molar_abundances	The molar abundances to set.

Exceptions

exceptions::UnknownSymbolError	if any symbol is not in the atomic species database.
exceptions::UnregisteredSymbolError	if any symbol is not in the composition.
exceptions::InvalidCompositionError	if any molar abundance is negative.

Example:: Composition comp({"H-1", "He-4"});

comp.setMolarAbundance({"H-1", "He-4"}, {1.0, 0.5});

Methods which set multiple molar abundances

delegate to vector<Species>, vector<double>

Definition at line 359 of file composition.cpp.

◆ size()

size_t fourdst::composition::Composition::size ( ) const

nodiscardoverridevirtualnoexcept

Gets the number of registered species in the composition.

Returns: The number of registered species.

Implements fourdst::composition::CompositionAbstract.

Definition at line 709 of file composition.cpp.

◆ symbolVectorToSpeciesVector()

std::vector< atomic::Species > fourdst::composition::Composition::symbolVectorToSpeciesVector ( const std::vector< std::string > & symbols )

staticnodiscardprivate

Definition at line 725 of file composition.cpp.

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		const Composition &	composition )

friend

Overloaded output stream operator for Composition.

Parameters

os	The output stream.
composition	The Composition to output.

Returns: The output stream.

Definition at line 746 of file composition.cpp.

Member Data Documentation

◆ m_cache

CompositionCache fourdst::composition::Composition::m_cache

mutableprivate

Cache for computed properties to avoid redundant calculations.

Definition at line 167 of file composition.h.

◆ m_molarAbundances

std::vector<double> fourdst::composition::Composition::m_molarAbundances

private

Definition at line 165 of file composition.h.

◆ m_species

std::vector<atomic::Species> fourdst::composition::Composition::m_species

private

Definition at line 164 of file composition.h.

The documentation for this class was generated from the following files:

src/composition/include/fourdst/composition/composition.h
src/composition/lib/composition.cpp

Classes

Public Types

Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ iterator

Member Enumeration Documentation

◆ SpeciesIndexLookupError

Constructor & Destructor Documentation

◆ Composition() [1/16]

◆ ~Composition()

◆ Composition() [2/16]

◆ Composition() [3/16]

◆ Composition() [4/16]

◆ Composition() [5/16]

◆ Composition() [6/16]

◆ Composition() [7/16]

◆ Composition() [8/16]

◆ Composition() [9/16]

◆ Composition() [10/16]

◆ Composition() [11/16]

◆ Composition() [12/16]

◆ Composition() [13/16]

◆ Composition() [14/16]

◆ Composition() [15/16]

◆ Composition() [16/16]

Member Function Documentation

◆ begin() [1/2]

◆ begin() [2/2]

◆ clone()

◆ contains() [1/2]

◆ contains() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ findSpeciesIndex()

◆ getCanonicalComposition()

◆ getElectronAbundance()

◆ getLogger()

◆ getMassFraction() [1/3]

◆ getMassFraction() [2/3]

◆ getMassFraction() [3/3]

◆ getMassFractionVector()

◆ getMeanParticleMass()

◆ getMolarAbundance() [1/2]

◆ getMolarAbundance() [2/2]

◆ getMolarAbundanceVector()

◆ getNumberFraction() [1/3]

◆ getNumberFraction() [2/3]

◆ getNumberFraction() [3/3]

◆ getNumberFractionVector()

◆ getRegisteredSpecies()

◆ getRegisteredSymbols()

◆ getSpeciesAtIndex()

◆ getSpeciesIndex() [1/2]

◆ getSpeciesIndex() [2/2]

◆ hash()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ registerSpecies() [1/2]

◆ registerSpecies() [2/2]

◆ registerSymbol() [1/2]

◆ registerSymbol() [2/2]

◆ setMolarAbundance() [1/6]

◆ setMolarAbundance() [2/6]

◆ setMolarAbundance() [3/6]

◆ setMolarAbundance() [4/6]

◆ setMolarAbundance() [5/6]

◆ setMolarAbundance() [6/6]

delegate to vector<Species>, vector<double>

◆ size()

◆ symbolVectorToSpeciesVector()

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation