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 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::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 Composition &composition)
	Constructs a Composition from another Composition.

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

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::set< 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.

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

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

auto	end ()
	Returns an iterator to the end of the molar abundance map.

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

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

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.

Private Attributes
std::set< atomic::Species >	m_registeredSpecies
	Set of registered species in the composition.

std::map< atomic::Species, double >	m_molarAbundances
	Map of species to their molar abundances.

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:529

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

Definition at line 97 of file composition.h.

Constructor & Destructor Documentation

◆ Composition() [1/9]

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/9]

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:97

Definition at line 84 of file composition.cpp.

◆ Composition() [3/9]

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 100 of file composition.cpp.

◆ Composition() [4/9]

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);

Definition at line 92 of file composition.cpp.

◆ Composition() [5/9]

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 108 of file composition.cpp.

◆ Composition() [6/9]

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.

Definition at line 116 of file composition.cpp.

◆ Composition() [7/9]

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 131 of file composition.cpp.

◆ Composition() [8/9]

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 146 of file composition.cpp.

◆ Composition() [9/9]

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

Constructs a Composition from another Composition.

Parameters

composition The Composition to copy.

Definition at line 161 of file composition.cpp.

Member Function Documentation

◆ begin() [1/2]

auto fourdst::composition::Composition::begin ( )

inline

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.

Definition at line 753 of file composition.h.

◆ begin() [2/2]

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

inlinenodiscard

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.

Definition at line 774 of file composition.h.

◆ 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 CompositionAbstract.

Definition at line 509 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 CompositionAbstract.

Definition at line 515 of file composition.cpp.

◆ end() [1/2]

auto fourdst::composition::Composition::end ( )

inline

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.

Definition at line 795 of file composition.h.

◆ end() [2/2]

auto fourdst::composition::Composition::end ( ) const

inlinenodiscard

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.

Definition at line 816 of file composition.h.

◆ 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 330 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 CompositionAbstract.

Definition at line 321 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 144 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 CompositionAbstract.

Definition at line 251 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 CompositionAbstract.

Definition at line 235 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 CompositionAbstract.

Definition at line 227 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 CompositionAbstract.

Definition at line 373 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 CompositionAbstract.

Definition at line 311 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 CompositionAbstract.

Definition at line 302 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 CompositionAbstract.

Definition at line 291 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 CompositionAbstract.

Definition at line 416 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 CompositionAbstract.

Definition at line 283 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 CompositionAbstract.

Definition at line 270 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 CompositionAbstract.

Definition at line 260 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 CompositionAbstract.

Definition at line 395 of file composition.cpp.

◆ getRegisteredSpecies()

const std::set< 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 CompositionAbstract.

Definition at line 222 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 CompositionAbstract.

Definition at line 214 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 CompositionAbstract.

Definition at line 483 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 CompositionAbstract.

Definition at line 449 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 CompositionAbstract.

Definition at line 438 of file composition.cpp.

◆ operator=()

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 168 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:197

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 197 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 206 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 178 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 189 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 541 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 582 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 573 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 529 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 564 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});

Definition at line 555 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 CompositionAbstract.

Definition at line 525 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 593 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 152 of file composition.h.

◆ m_molarAbundances

std::map<atomic::Species, double> fourdst::composition::Composition::m_molarAbundances

private

Map of species to their molar abundances.

Definition at line 150 of file composition.h.

◆ m_registeredSpecies

std::set<atomic::Species> fourdst::composition::Composition::m_registeredSpecies

private

Set of registered species in the composition.

Definition at line 149 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 Member Functions

Static Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Composition() [1/9]

◆ ~Composition()

◆ Composition() [2/9]

◆ Composition() [3/9]

◆ Composition() [4/9]

◆ Composition() [5/9]

◆ Composition() [6/9]

◆ Composition() [7/9]

◆ Composition() [8/9]

◆ Composition() [9/9]

Member Function Documentation

◆ begin() [1/2]

◆ begin() [2/2]

◆ contains() [1/2]

◆ contains() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ 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]

◆ operator=()

◆ 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]

◆ size()

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation

◆ m_cache

◆ m_molarAbundances

◆ m_registeredSpecies