Loading...
Searching...
No Matches
fourdst::composition::Composition Class Referencefinal

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

`#include <composition.h>`

Inheritance diagram for fourdst::composition::Composition:
[legend]
Collaboration diagram for fourdst::composition::Composition:
[legend]

## 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 ( )
- Y: mass fraction of helium ( )
- 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:

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:

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:

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:

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