fourdst::composition::Composition Class Reference

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

#include <composition.h>

Public Member Functions
	Composition ()=default
	Default constructor.
	~Composition ()=default
	Default destructor.
bool	finalize (bool norm=false)
	Finalizes the composition, making it ready for querying.
	Composition (const std::vector< std::string > &symbols)
	Constructs a Composition and registers the given symbols.
	Composition (const std::set< std::string > &symbols)
	Constructs a Composition and registers the given symbols from a set.
	Composition (const std::vector< std::string > &symbols, const std::vector< double > &fractions, bool massFracMode=true)
	Constructs and finalizes a Composition with the given symbols and fractions.
	Composition (const Composition &composition)
	Constructs a Composition from another Composition.
Composition &	operator= (Composition const &other)
	Assignment operator.
void	registerSymbol (const std::string &symbol, bool massFracMode=true)
	Registers a new symbol for inclusion in the composition.
void	registerSymbol (const std::vector< std::string > &symbols, bool massFracMode=true)
	Registers multiple new symbols.
void	registerSpecies (const fourdst::atomic::Species &species, bool massFracMode=true)
	Registers a new species by extracting its symbol.
void	registerSpecies (const std::vector< fourdst::atomic::Species > &species, bool massFracMode=true)
	Registers a vector of new species.
std::set< std::string >	getRegisteredSymbols () const
	Gets the registered symbols.
std::set< fourdst::atomic::Species >	getRegisteredSpecies () const
	Get a set of all species that are registered in the composition.
double	setMassFraction (const std::string &symbol, const double &mass_fraction)
	Sets the mass fraction for a given symbol.
std::vector< double >	setMassFraction (const std::vector< std::string > &symbols, const std::vector< double > &mass_fractions)
	Sets the mass fraction for multiple symbols.
double	setMassFraction (const fourdst::atomic::Species &species, const double &mass_fraction)
	Sets the mass fraction for a given species.
std::vector< double >	setMassFraction (const std::vector< fourdst::atomic::Species > &species, const std::vector< double > &mass_fractions)
	Sets the mass fraction for multiple species.
double	setNumberFraction (const std::string &symbol, const double &number_fraction)
	Sets the number fraction for a given symbol.
std::vector< double >	setNumberFraction (const std::vector< std::string > &symbols, const std::vector< double > &number_fractions)
	Sets the number fraction for multiple symbols.
double	setNumberFraction (const fourdst::atomic::Species &species, const double &number_fraction)
	Sets the number fraction for a given species.
std::vector< double >	setNumberFraction (const std::vector< fourdst::atomic::Species > &species, const std::vector< double > &number_fractions)
	Sets the number fraction for multiple species.
Composition	mix (const Composition &other, double fraction) const
	Mixes this composition with another to produce a new composition.
std::unordered_map< std::string, double >	getMassFraction () const
	Gets the mass fractions of all species in the composition.
double	getMassFraction (const std::string &symbol) const
	Gets the mass fraction for a given symbol.
double	getMassFraction (const fourdst::atomic::Species &species) const
	Gets the mass fraction for a given isotope.
double	getNumberFraction (const std::string &symbol) const
	Gets the number fraction for a given symbol.
double	getNumberFraction (const fourdst::atomic::Species &species) const
	Gets the number fraction for a given isotope.
std::unordered_map< std::string, double >	getNumberFraction () const
	Gets the number fractions of all species in the composition.
double	getMolarAbundance (const std::string &symbol) const
	Gets the molar abundance (X_i / A_i) for a given symbol.
double	getMolarAbundance (const fourdst::atomic::Species &species) const
	Gets the molar abundance for a given isotope.
std::pair< CompositionEntry, GlobalComposition >	getComposition (const std::string &symbol) const
	Gets the composition entry and global composition data for a given symbol.
std::pair< CompositionEntry, GlobalComposition >	getComposition (const fourdst::atomic::Species &species) const
	Gets the composition entry and global composition data for a given species.
std::pair< std::unordered_map< std::string, CompositionEntry >, GlobalComposition >	getComposition () const
	Gets all composition entries and the global composition data.
double	getMeanParticleMass () const
	Compute the mean particle mass of the composition.
double	getMeanAtomicNumber () const
	Compute the mean atomic number of the composition.
Composition	subset (const std::vector< std::string > &symbols, const std::string &method="norm") const
	Creates a new Composition object containing a subset of species from this one.
bool	hasSymbol (const std::string &symbol) const
	Checks if a symbol is registered in the composition.
bool	contains (const fourdst::atomic::Species &isotope) const
	Checks if a given isotope is present in the composition.
void	setCompositionMode (bool massFracMode)
	Sets the composition mode (mass fraction vs. number fraction).
CanonicalComposition	getCanonicalComposition (bool harsh=false) const
	Gets the current canonical composition (X, Y, Z).
std::vector< double >	getMassFractionVector () const
	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
	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
	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
	get the index in the sorted vector representation for a given symbol
size_t	getSpeciesIndex (const atomic::Species &species) const
	get the index in the sorted vector representation for a given symbol
atomic::Species	getSpeciesAtIndex (size_t index) const
	Get the species at a given index in the sorted vector representation.
Composition	operator+ (const Composition &other) const
	Overloads the + operator to mix two compositions with a 50/50 fraction.
auto	begin ()
	Returns an iterator to the beginning of the composition map.
auto	begin () const
	Returns a const iterator to the beginning of the composition map.
auto	end ()
	Returns an iterator to the end of the composition map.
auto	end () const
	Returns a const iterator to the end of the composition map.

Private Member Functions
bool	isValidComposition (const std::vector< double > &fractions) const
	Checks if the given fractions are valid (sum to ~1.0).
void	validateComposition (const std::vector< double > &fractions) const
	Validates the given fractions, throwing an exception on failure.
bool	finalizeMassFracMode (bool norm)
	Finalizes the composition in mass fraction mode.
bool	finalizeNumberFracMode (bool norm)
	Finalizes the composition in number fraction mode.

Static Private Member Functions
static bool	isValidSymbol (const std::string &symbol)
	Checks if the given symbol is valid by checking against the global species database.

Private Attributes
fourdst::config::Config &	m_config = fourdst::config::Config::getInstance()
fourdst::logging::LogManager &	m_logManager = fourdst::logging::LogManager::getInstance()
quill::Logger *	m_logger = m_logManager.getLogger("log")
bool	m_finalized = false
	True if the composition is finalized.
double	m_specificNumberDensity = 0.0
	The specific number density of the composition (\sum_{i} X_i m_i. Where X_i is the number fraction of the ith species and m_i is the mass of the ith species).
double	m_meanParticleMass = 0.0
	The mean particle mass of the composition (\sum_{i} \frac{n_i}{m_i}. where n_i is the number fraction of the ith species and m_i is the mass of the ith species).
bool	m_massFracMode = true
	True if mass fraction mode, false if number fraction mode.
std::set< std::string >	m_registeredSymbols
	The registered symbols.
std::unordered_map< std::string, CompositionEntry >	m_compositions
	The compositions.

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. It can operate in two modes: mass fraction or number fraction.

Key Rules and Workflow:

1. Registration: Before setting an abundance for a species, its symbol (e.g., "He-4") must be registered using registerSymbol() or registerSpecies(). All registered species must conform to the same abundance mode (mass or number fraction).
2. Setting Abundances: Use setMassFraction() or setNumberFraction() to define the composition.
3. Finalization: Before querying any compositional data (e.g., getMassFraction(), getMeanParticleMass()), the composition must be finalized by calling finalize(). This step validates the composition (abundances sum to ~1.0) and computes global properties.
4. Modification: Any modification to abundances after finalization will un-finalize the composition, requiring another call to finalize() before data can be retrieved again.
5. Construction: A pre-finalized composition can be created by providing symbols and valid, normalized abundances to the constructor.

Exceptions

This	class throws various exceptions from fourdst::composition::exceptions for invalid operations, such as using unregistered symbols, providing invalid abundances, or accessing data from a non-finalized composition.

Mass Fraction Example:

Composition comp;
comp.registerSymbol("H-1");
comp.registerSymbol("He-4");
comp.setMassFraction("H-1", 0.75);
comp.setMassFraction("He-4", 0.25);
if (comp.finalize()) {
    double he_mass_frac = comp.getMassFraction("He-4"); // Returns 0.25
}

Number Fraction Example:

Composition comp;
comp.registerSymbol("H-1", false); // Register in number fraction mode
comp.registerSymbol("He-4", false);
comp.setNumberFraction("H-1", 0.9);
comp.setNumberFraction("He-4", 0.1);
if (comp.finalize()) {
    double he_num_frac = comp.getNumberFraction("He-4"); // Returns 0.1
}

Definition at line 258 of file composition.h.

Constructor & Destructor Documentation

Composition() [1/5]

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

default

Default constructor.

~Composition()

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

default

Default destructor.

Composition() [2/5]

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

explicit

Constructs a Composition and registers the given symbols.

Parameters

symbols

The symbols to register. The composition will be in mass fraction mode by default.

Exceptions

exceptions::InvalidSymbolError

if any symbol is invalid.

Usage Example:

std::vector<std::string> symbols = {"H-1", "O-16"};
Composition comp(symbols);
comp.setMassFraction("H-1", 0.11);
comp.setMassFraction("O-16", 0.89);
comp.finalize();

Definition at line 176 of file composition.cpp.

Composition() [3/5]

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. The composition will be in mass fraction mode by default.

Exceptions

exceptions::InvalidSymbolError

if any symbol is invalid.

Usage Example:

std::set<std::string> symbols = {"H-1", "O-16"};
Composition comp(symbols);

Definition at line 182 of file composition.cpp.

Composition() [4/5]

fourdst::composition::Composition::Composition	(	const std::vector< std::string > &	symbols,
		const std::vector< double > &	fractions,
		bool	massFracMode = true )

Constructs and finalizes a Composition with the given symbols and fractions.

This constructor provides a convenient way to create a fully-formed, finalized composition in one step. The provided fractions must be valid and sum to 1.0.

Parameters

symbols	The symbols to initialize the composition with.
fractions	The fractions (mass or number) corresponding to the symbols.
massFracMode	True if fractions are mass fractions, false if they are number fractions. [Default: true]

Exceptions

exceptions::InvalidCompositionError	if the number of symbols and fractions do not match, or if the fractions do not sum to ~1.0.
exceptions::InvalidSymbolError	if any symbol is invalid.

Postcondition

The composition is immediately finalized.

Usage Example:

std::vector<std::string> symbols = {"H-1", "O-16"};
std::vector<double> mass_fractions = {0.1119, 0.8881};
Composition comp(symbols, mass_fractions); // Finalized on construction

Definition at line 188 of file composition.cpp.

Composition() [5/5]

fourdst::composition::Composition::Composition

(

const Composition &

composition

)

Constructs a Composition from another Composition.

Parameters

composition

The Composition to copy.

Definition at line 210 of file composition.cpp.

Member Function Documentation

begin() [1/2]

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

inline

Returns an iterator to the beginning of the composition map.

Returns

An iterator to the beginning.

Definition at line 821 of file composition.h.

begin() [2/2]

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

inlinenodiscard

Returns a const iterator to the beginning of the composition map.

Returns

A const iterator to the beginning.

Definition at line 829 of file composition.h.

contains()

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

nodiscard

Checks if a given isotope is present in the composition.

Precondition

The composition must be finalized.

Parameters

isotope

The isotope to check for.

Returns

True if the isotope is in the composition, false otherwise.

Exceptions

exceptions::CompositionNotFinalizedError

if the composition is not finalized.

Definition at line 906 of file composition.cpp.

end() [1/2]

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

inline

Returns an iterator to the end of the composition map.

Returns

An iterator to the end.

Definition at line 837 of file composition.h.

end() [2/2]

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

inlinenodiscard

Returns a const iterator to the end of the composition map.

Returns

A const iterator to the end.

Definition at line 845 of file composition.h.

finalize()

bool fourdst::composition::Composition::finalize

(

bool

norm = false

)

Finalizes the composition, making it ready for querying.

This method checks if the sum of all fractions (mass or number) is approximately 1.0. It also computes global properties like mean particle mass. This must be called before any get... method can be used.

Parameters

norm	If true, the composition will be normalized to sum to 1 before validation. [Default: false]

Returns

True if the composition is valid and successfully finalized, false otherwise.

Postcondition

If successful, m_finalized is true and global properties are computed.

Definition at line 414 of file composition.cpp.

finalizeMassFracMode()

bool fourdst::composition::Composition::finalizeMassFracMode ( bool norm )

private

Finalizes the composition in mass fraction mode.

Parameters

norm	If true, the composition will be normalized to sum to 1.

Returns

True if the composition is successfully finalized, false otherwise.

Definition at line 427 of file composition.cpp.

finalizeNumberFracMode()

bool fourdst::composition::Composition::finalizeNumberFracMode ( bool norm )

private

Finalizes the composition in number fraction mode.

Parameters

norm	If true, the composition will be normalized to sum to 1.

Returns

True if the composition is successfully finalized, false otherwise.

Definition at line 464 of file composition.cpp.

getCanonicalComposition()

CanonicalComposition fourdst::composition::Composition::getCanonicalComposition ( bool harsh = false ) const

nodiscard

Gets the current canonical composition (X, Y, Z).

Calculates the total mass fractions for H, He, and metals.

Precondition

The composition must be finalized.

Parameters

harsh

If true, this will throw an error if 1 - (X + Y) is not equal to the directly summed Z (within a tolerance). If false, it will only log a warning.

Returns

The CanonicalComposition struct.

Exceptions

exceptions::CompositionNotFinalizedError	if the composition is not finalized.
std::runtime_error	if harsh is true and the canonical composition is not self-consistent.

Definition at line 715 of file composition.cpp.

getComposition() [1/3]

std::pair< std::unordered_map< std::string, CompositionEntry >, GlobalComposition > fourdst::composition::Composition::getComposition ( ) const

nodiscard

Gets all composition entries and the global composition data.

Precondition

The composition must be finalized.

Returns

A pair containing an unordered map of all CompositionEntries and the GlobalComposition.

Exceptions

exceptions::CompositionNotFinalizedError

if the composition is not finalized.

Definition at line 630 of file composition.cpp.

getComposition() [2/3]

std::pair< CompositionEntry, GlobalComposition > fourdst::composition::Composition::getComposition ( const fourdst::atomic::Species & species ) const

nodiscard

Gets the composition entry and global composition data for a given species.

Precondition

The composition must be finalized.

Parameters

species

The species to get the composition for.

Returns

A pair containing the CompositionEntry and GlobalComposition for the given species.

Exceptions

exceptions::CompositionNotFinalizedError	if the composition is not finalized.
exceptions::UnregisteredSymbolError	if the species is not in the composition.

Definition at line 625 of file composition.cpp.

getComposition() [3/3]

std::pair< CompositionEntry, GlobalComposition > fourdst::composition::Composition::getComposition ( const std::string & symbol ) const

nodiscard

Gets the composition entry and global composition data for a given symbol.

Precondition

The composition must be finalized.

Parameters

symbol

The symbol to get the composition for.

Returns

A pair containing the CompositionEntry and GlobalComposition for the given symbol.

Exceptions

exceptions::CompositionNotFinalizedError	if the composition is not finalized.
exceptions::UnregisteredSymbolError	if the symbol is not in the composition.

Definition at line 613 of file composition.cpp.

getMassFraction() [1/3]

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

nodiscard

Gets the mass fractions of all species in the composition.

Precondition

The composition must be finalized.

Returns

An unordered map of symbols to their mass fractions.

Exceptions

exceptions::CompositionNotFinalizedError

if the composition is not finalized.

Definition at line 559 of file composition.cpp.

getMassFraction() [2/3]

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

nodiscard

Gets the mass fraction for a given isotope.

Precondition

The composition must be finalized.

Parameters

species

The isotope to get the mass fraction for.

Returns

The mass fraction for the given isotope.

Exceptions

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

Definition at line 555 of file composition.cpp.

getMassFraction() [3/3]

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

nodiscard

Gets the mass fraction for a given symbol.

Precondition

The composition must be finalized.

Parameters

symbol

The symbol to get the mass fraction for.

Returns

The mass fraction for the given symbol.

Exceptions

exceptions::CompositionNotFinalizedError	if the composition is not finalized.
exceptions::UnregisteredSymbolError	if the symbol is not in the composition.

Definition at line 528 of file composition.cpp.

getMassFractionVector()

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

nodiscard

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

Precondition

The composition must be finalized.

Exceptions

exceptions::CompositionNotFinalizedError

if the composition is not finalized.

Definition at line 762 of file composition.cpp.

getMeanAtomicNumber()

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

nodiscard

Compute the mean atomic number of the composition.

Precondition

The composition must be finalized.

Returns

Mean atomic number <Z>.

Exceptions

exceptions::CompositionNotFinalizedError

if the composition is not finalized.

Definition at line 646 of file composition.cpp.

getMeanParticleMass()

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

nodiscard

Compute the mean particle mass of the composition.

Precondition

The composition must be finalized.

Returns

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

Exceptions

exceptions::CompositionNotFinalizedError

if the composition is not finalized.

Definition at line 638 of file composition.cpp.

getMolarAbundance() [1/2]

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

nodiscard

Gets the molar abundance for a given isotope.

Precondition

The composition must be finalized.

Parameters

species

The isotope to get the molar abundance for.

Returns

The molar abundance for the given isotope.

Exceptions

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

Definition at line 609 of file composition.cpp.

getMolarAbundance() [2/2]

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

nodiscard

Gets the molar abundance (X_i / A_i) for a given symbol.

Precondition

The composition must be finalized.

Parameters

symbol

The symbol to get the molar abundance for.

Returns

The molar abundance for the given symbol.

Exceptions

exceptions::CompositionNotFinalizedError	if the composition is not finalized.
exceptions::UnregisteredSymbolError	if the symbol is not in the composition.

Definition at line 596 of file composition.cpp.

getMolarAbundanceVector()

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

nodiscard

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

Precondition

The composition must be finalized.

Exceptions

exceptions::CompositionNotFinalizedError

if the composition is not finalized.

Definition at line 803 of file composition.cpp.

getNumberFraction() [1/3]

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

nodiscard

Gets the number fractions of all species in the composition.

Precondition

The composition must be finalized.

Returns

An unordered map of symbols to their number fractions.

Exceptions

exceptions::CompositionNotFinalizedError

if the composition is not finalized.

Definition at line 588 of file composition.cpp.

getNumberFraction() [2/3]

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

nodiscard

Gets the number fraction for a given isotope.

Precondition

The composition must be finalized.

Parameters

species

The isotope to get the number fraction for.

Returns

The number fraction for the given isotope.

Exceptions

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

Definition at line 584 of file composition.cpp.

getNumberFraction() [3/3]

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

nodiscard

Gets the number fraction for a given symbol.

Precondition

The composition must be finalized.

Parameters

symbol

The symbol to get the number fraction for.

Returns

The number fraction for the given symbol.

Exceptions

exceptions::CompositionNotFinalizedError	if the composition is not finalized.
exceptions::UnregisteredSymbolError	if the symbol is not in the composition.

Definition at line 568 of file composition.cpp.

getNumberFractionVector()

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

nodiscard

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

Precondition

The composition must be finalized.

Exceptions

exceptions::CompositionNotFinalizedError

if the composition is not finalized.

Definition at line 783 of file composition.cpp.

getRegisteredSpecies()

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

nodiscard

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

Returns

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

Definition at line 280 of file composition.cpp.

getRegisteredSymbols()

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

nodiscard

Gets the registered symbols.

Returns

A set of registered symbols.

Definition at line 276 of file composition.cpp.

getSpeciesAtIndex()

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

nodiscard

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

Precondition

The composition must be finalized.

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

exceptions::CompositionNotFinalizedError	if the composition is not finalized.
std::out_of_range	if the index is out of range.

Returns

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

Definition at line 873 of file composition.cpp.

getSpeciesIndex() [1/2]

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

nodiscard

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

Precondition

The composition must be finalized.

symbol must be registered in the composition

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::CompositionNotFinalizedError	if the composition is not finalized.
exceptions::UnregisteredSymbolError	if the symbol is not registered in the composition

Returns

The index of the symbol in the sorted vector representation.

Definition at line 848 of file composition.cpp.

getSpeciesIndex() [2/2]

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

nodiscard

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

Precondition

The composition must be finalized.

symbol must be registered in the composition

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::CompositionNotFinalizedError	if the composition is not finalized.
exceptions::UnregisteredSymbolError	if the symbol is not registered in the composition

Returns

The index of the symbol in the sorted vector representation.

Definition at line 823 of file composition.cpp.

hasSymbol()

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

nodiscard

Checks if a symbol is registered in the composition.

Parameters

symbol

The symbol to check.

Returns

True if the symbol is registered, false otherwise.

Definition at line 902 of file composition.cpp.

isValidComposition()

bool fourdst::composition::Composition::isValidComposition ( const std::vector< double > & fractions ) const

nodiscardprivate

Checks if the given fractions are valid (sum to ~1.0).

Parameters

fractions

The fractions to check.

Returns

True if the fractions are valid, false otherwise.

Definition at line 295 of file composition.cpp.

isValidSymbol()

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

staticprivate

Checks if the given symbol is valid by checking against the global species database.

Parameters

symbol

The symbol to check.

Returns

True if the symbol is valid, false otherwise.

Definition at line 308 of file composition.cpp.

mix()

Composition fourdst::composition::Composition::mix ( const Composition & other, double fraction ) const

nodiscard

Mixes this composition with another to produce a new composition.

The mixing is performed linearly on the mass fractions. The formula for each species is: new_X_i = fraction * this_X_i + (1 - fraction) * other_X_i. The resulting composition is automatically finalized.

Parameters

other	The other composition to mix with.
fraction	The mixing fraction. A value of 1.0 means the new composition is 100% this, 0.0 means 100% other.

Returns

A new, finalized Composition object representing the mixture.

Precondition

Both this and other compositions must be finalized.

Exceptions

exceptions::CompositionNotFinalizedError	if either composition is not finalized.
exceptions::InvalidCompositionError	if the fraction is not between 0 and 1.

Definition at line 498 of file composition.cpp.

operator+()

Composition fourdst::composition::Composition::operator+

(

const Composition &

other

)

const

Overloads the + operator to mix two compositions with a 50/50 fraction.

OVERLOADS.

This is a convenience operator that calls mix(other, 0.5).

Parameters

other

The other composition to mix with.

Returns

The new, mixed composition.

Precondition

Both compositions must be finalized.

Exceptions

See	mix() for exceptions.

Definition at line 921 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 219 of file composition.cpp.

registerSpecies() [1/2]

void fourdst::composition::Composition::registerSpecies	(	const fourdst::atomic::Species &	species,
		bool	massFracMode = true )

Registers a new species by extracting its symbol.

Parameters

species	The species to register.
massFracMode	True for mass fraction mode, false for number fraction mode.

Exceptions

exceptions::InvalidSymbolError	if the species' symbol is invalid.
exceptions::CompositionModeError	if the mode conflicts.

Usage Example:

#include "fourdst/composition/species.h" // Assuming species like H1 are defined here
Composition comp;
comp.registerSpecies(fourdst::atomic::species.at("H-1"));

Definition at line 266 of file composition.cpp.

registerSpecies() [2/2]

void fourdst::composition::Composition::registerSpecies	(	const std::vector< fourdst::atomic::Species > &	species,
		bool	massFracMode = true )

Registers a vector of new species.

Parameters

species	The vector of species to register.
massFracMode	True for mass fraction mode, false for number fraction mode.

Exceptions

exceptions::InvalidSymbolError	if any species' symbol is invalid.
exceptions::CompositionModeError	if the mode conflicts.

Usage Example:

#include "fourdst/composition/species.h"
Composition comp;
std::vector<fourdst::atomic::Species> my_species = { ... };
comp.registerSpecies(my_species, false); // Number fraction mode

Definition at line 270 of file composition.cpp.

registerSymbol() [1/2]

void fourdst::composition::Composition::registerSymbol	(	const std::string &	symbol,
		bool	massFracMode = true )

Registers a new symbol for inclusion in the composition.

A symbol must be registered before its abundance can be set. The first registration sets the mode (mass/number fraction) for the entire composition.

Parameters

symbol	The symbol to register (e.g., "Fe-56").
massFracMode	True for mass fraction mode, false for number fraction mode. This is only effective for the first symbol registered.

Exceptions

exceptions::InvalidSymbolError	if the symbol is not in the atomic species database.
exceptions::CompositionModeError	if attempting to register with a mode that conflicts with the existing mode.

Usage Example:

Composition comp;
comp.registerSymbol("H-1"); // Now in mass fraction mode
comp.registerSymbol("He-4"); // Must also be mass fraction mode

Definition at line 233 of file composition.cpp.

registerSymbol() [2/2]

void fourdst::composition::Composition::registerSymbol	(	const std::vector< std::string > &	symbols,
		bool	massFracMode = true )

Registers multiple new symbols.

Parameters

symbols	The symbols to register.
massFracMode	True for mass fraction mode, false for number fraction mode.

Exceptions

exceptions::InvalidSymbolError	if any symbol is invalid.
exceptions::CompositionModeError	if the mode conflicts with an already set mode.

Usage Example:

std::vector<std::string> symbols = {"H-1", "O-16"};
Composition comp;
comp.registerSymbol(symbols);

Definition at line 260 of file composition.cpp.

setCompositionMode()

void fourdst::composition::Composition::setCompositionMode

(

bool

massFracMode

)

Sets the composition mode (mass fraction vs. number fraction).

This function converts all entries in the composition to the specified mode.

Precondition

The composition must be finalized before the mode can be switched.

Parameters

massFracMode

True to switch to mass fraction mode, false for number fraction mode.

Exceptions

exceptions::CompositionNotFinalizedError	if the composition is not finalized.
std::runtime_error	if the conversion fails for an unknown reason.

Definition at line 694 of file composition.cpp.

setMassFraction() [1/4]

double fourdst::composition::Composition::setMassFraction	(	const fourdst::atomic::Species &	species,
		const double &	mass_fraction )

Sets the mass fraction for a given species.

Parameters

species	The species to set the mass fraction for.
mass_fraction	The mass fraction to set.

Returns

The previous mass fraction that was set for the species.

Exceptions

exceptions::UnregisteredSymbolError	if the species is not registered.
exceptions::CompositionModeError	if the composition is in number fraction mode.
exceptions::InvalidCompositionError	if the mass fraction is not between 0 and 1.

Definition at line 349 of file composition.cpp.

setMassFraction() [2/4]

double fourdst::composition::Composition::setMassFraction	(	const std::string &	symbol,
		const double &	mass_fraction )

Sets the mass fraction for a given symbol.

Parameters

symbol	The symbol to set the mass fraction for.
mass_fraction	The mass fraction to set (must be in [0, 1]).

Returns

The previous mass fraction that was set for the symbol.

Exceptions

exceptions::UnregisteredSymbolError	if the symbol is not registered.
exceptions::CompositionModeError	if the composition is in number fraction mode.
exceptions::InvalidCompositionError	if the mass fraction is not between 0 and 1.

Postcondition

The composition is marked as not finalized.

Usage Example:

Composition comp;
comp.registerSymbol("H-1");
comp.setMassFraction("H-1", 0.7);

Definition at line 312 of file composition.cpp.

setMassFraction() [3/4]

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

Sets the mass fraction for multiple species.

Parameters

species	The vector of species to set the mass fractions for.
mass_fractions	The vector of mass fractions corresponding to the species.

Returns

A vector of the previous mass fractions that were set.

Exceptions

See	setMassFraction(const std::vector<std::string>&, const std::vector<double>&) for exceptions.

Definition at line 353 of file composition.cpp.

setMassFraction() [4/4]

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

Sets the mass fraction for multiple symbols.

Parameters

symbols	The symbols to set the mass fractions for.
mass_fractions	The mass fractions corresponding to the symbols.

Returns

A vector of the previous mass fractions that were set.

Exceptions

exceptions::InvalidCompositionError	if symbol and fraction counts differ.
See	setMassFraction(const std::string&, const double&) for other exceptions.

Postcondition

The composition is marked as not finalized.

Definition at line 335 of file composition.cpp.

setNumberFraction() [1/4]

double fourdst::composition::Composition::setNumberFraction	(	const fourdst::atomic::Species &	species,
		const double &	number_fraction )

Sets the number fraction for a given species.

Parameters

species	The species to set the number fraction for.
number_fraction	The number fraction to set for the species.

Returns

The previous number fraction that was set for the species.

Exceptions

exceptions::UnregisteredSymbolError	if the species is not registered.
exceptions::CompositionModeError	if the composition is in mass fraction mode.
exceptions::InvalidCompositionError	if the number fraction is not between 0 and 1.

Definition at line 400 of file composition.cpp.

setNumberFraction() [2/4]

double fourdst::composition::Composition::setNumberFraction	(	const std::string &	symbol,
		const double &	number_fraction )

Sets the number fraction for a given symbol.

Parameters

symbol	The symbol to set the number fraction for.
number_fraction	The number fraction to set (must be in [0, 1]).

Returns

The previous number fraction that was set.

Exceptions

exceptions::UnregisteredSymbolError	if the symbol is not registered.
exceptions::CompositionModeError	if the composition is in mass fraction mode.
exceptions::InvalidCompositionError	if the number fraction is not between 0 and 1.

Postcondition

The composition is marked as not finalized.

Definition at line 363 of file composition.cpp.

setNumberFraction() [3/4]

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

Sets the number fraction for multiple species.

Parameters

species	The vector of species to set the number fractions for.
number_fractions	The vector of number fractions corresponding to the species.

Returns

The vector of the previous number fractions that were set.

Exceptions

See	setNumberFraction(const std::vector<std::string>&, const std::vector<double>&) for exceptions.

Definition at line 404 of file composition.cpp.

setNumberFraction() [4/4]

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

Sets the number fraction for multiple symbols.

Parameters

symbols	The symbols to set the number fractions for.
number_fractions	The number fractions corresponding to the symbols.

Returns

A vector of the previous number fractions that were set.

Exceptions

exceptions::InvalidCompositionError	if symbol and fraction counts differ.
See	setNumberFraction(const std::string&, const double&) for other exceptions.

Definition at line 386 of file composition.cpp.

subset()

Composition fourdst::composition::Composition::subset ( const std::vector< std::string > & symbols, const std::string & method = "norm" ) const

nodiscard

Creates a new Composition object containing a subset of species from this one.

Parameters

symbols	The symbols to include in the subset.
method	The method for handling the abundances of the new subset. Can be "norm" (normalize abundances to sum to 1) or "none" (keep original abundances).

Returns

A new Composition object containing the subset.

Exceptions

exceptions::UnregisteredSymbolError	if any requested symbol is not in the original composition.
exceptions::InvalidMixingMode	if an invalid method is provided.
exceptions::FailedToFinalizeCompositionError	if normalization fails.

Definition at line 665 of file composition.cpp.

validateComposition()

void fourdst::composition::Composition::validateComposition ( const std::vector< double > & fractions ) const

private

Validates the given fractions, throwing an exception on failure.

Parameters

fractions

The fractions to validate.

Exceptions

exceptions::InvalidCompositionError

if the fractions are invalid.

Definition at line 288 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 937 of file composition.cpp.

Member Data Documentation

m_compositions

std::unordered_map<std::string, CompositionEntry> fourdst::composition::Composition::m_compositions

private

The compositions.

Definition at line 270 of file composition.h.

m_config

fourdst::config::Config& fourdst::composition::Composition::m_config = fourdst::config::Config::getInstance()

private

Definition at line 260 of file composition.h.

m_finalized

bool fourdst::composition::Composition::m_finalized = false

private

True if the composition is finalized.

Definition at line 264 of file composition.h.

m_logger

quill::Logger* fourdst::composition::Composition::m_logger = m_logManager.getLogger("log")

private

Definition at line 262 of file composition.h.

m_logManager

fourdst::logging::LogManager& fourdst::composition::Composition::m_logManager = fourdst::logging::LogManager::getInstance()

private

Definition at line 261 of file composition.h.

m_massFracMode

bool fourdst::composition::Composition::m_massFracMode = true

private

True if mass fraction mode, false if number fraction mode.

Definition at line 267 of file composition.h.

m_meanParticleMass

double fourdst::composition::Composition::m_meanParticleMass = 0.0

private

The mean particle mass of the composition (\sum_{i} \frac{n_i}{m_i}. where n_i is the number fraction of the ith species and m_i is the mass of the ith species).

Definition at line 266 of file composition.h.

m_registeredSymbols

std::set<std::string> fourdst::composition::Composition::m_registeredSymbols

private

The registered symbols.

Definition at line 269 of file composition.h.

m_specificNumberDensity

double fourdst::composition::Composition::m_specificNumberDensity = 0.0

private

The specific number density of the composition (\sum_{i} X_i m_i. Where X_i is the number fraction of the ith species and m_i is the mass of the ith species).

Definition at line 265 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