fourdst::libcomposition v2.0.1 Robust atomic species information library

Loading...
Searching...
No Matches
Classes | Public Member Functions | Static Private Member Functions | Private Attributes | Friends | List of all members
fourdst::composition::Composition Class Reference

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 Member Functions
| Composition ()=default
| Default constructor.
| ~Composition () override=default
| Default destructor.
| Composition (const std::vector< std::string > &symbols)
| Constructs a Composition and registers the given symbols from a vector.
| Composition (const std::vector< atomic::Species > &species)
| Constructs a Composition and registers the given species from a vector.
| Composition (const std::set< std::string > &symbols)
| Constructs a Composition and registers the given symbols from a set.
| Composition (const std::set< atomic::Species > &species)
| Constructs a Composition and registers the given species from a set.
| Composition (const std::vector< std::string > &symbols, const std::vector< double > &molarAbundances)
| Constructs a Composition from symbols and their corresponding molar abundances.
| Composition (const std::vector< atomic::Species > &species, const std::vector< double > &molarAbundances)
| Constructs a Composition from species and their corresponding molar abundances.
| Composition (const std::set< std::string > &symbols, const std::vector< double > &molarAbundances)
| Constructs a Composition from symbols in a set and their corresponding molar abundances.
| Composition (const Composition &composition)
| Constructs a Composition from another Composition.
Composition & | operator= (Composition const &other)
| Assignment operator.
void | registerSymbol (const std::string &symbol)
| Registers a new symbol for inclusion in the composition.
void | registerSymbol (const std::vector< std::string > &symbols)
| Registers multiple new symbols.
void | registerSpecies (const atomic::Species &species) noexcept
| Registers a new species by extracting its symbol.
void | registerSpecies (const std::vector< atomic::Species > &species) noexcept
| Registers a vector of new species.
bool | contains (const atomic::Species &species) const noexcept override
| Checks if a given species is present in the composition.
bool | contains (const std::string &symbol) const override
| Checks if a given symbol is present in the composition.
size_t | size () const noexcept override
| Gets the number of registered species in the composition.
void | setMolarAbundance (const std::string &symbol, const double &molar_abundance)
| Sets the molar abundance for a given symbol.
void | setMolarAbundance (const atomic::Species &species, const double &molar_abundance)
| Sets the molar abundance for a given isotope.
void | setMolarAbundance (const std::vector< std::string > &symbols, const std::vector< double > &molar_abundances)
| Sets the molar abundances for a list of symbols.
void | setMolarAbundance (const std::vector< atomic::Species > &species, const std::vector< double > &molar_abundances)
| Sets the molar abundances for a list of isotopes.
void | setMolarAbundance (const std::set< std::string > &symbols, const std::vector< double > &molar_abundances)
| Sets the molar abundances for a set of symbols.
void | setMolarAbundance (const std::set< atomic::Species > &species, const std::vector< double > &molar_abundances)
| Sets the molar abundances for a set of isotopes.
std::set< std::string > | getRegisteredSymbols () const noexcept override
| Gets the registered symbols.
const std::set< atomic::Species > & | getRegisteredSpecies () const noexcept override
| Get a set of all species that are registered in the composition.
std::unordered_map< atomic::Species, double > | getMassFraction () const noexcept override
| Gets the mass fractions of all species in the composition.
double | getMassFraction (const std::string &symbol) const override
| Gets the mass fraction for a given symbol. See the overload for species-based lookup for more details on how mass fractions are calculated.
double | getMassFraction (const atomic::Species &species) const override
| Gets the mass fraction for a given species.
double | getNumberFraction (const std::string &symbol) const override
| Gets the number fraction for a given symbol. See the overload for species-based lookup for more details on how number fractions are calculated.
double | getNumberFraction (const atomic::Species &species) const override
| Gets the number fraction for a given species.
std::unordered_map< atomic::Species, double > | getNumberFraction () const noexcept override
| Gets the number fractions of all species in the composition.
double | getMolarAbundance (const std::string &symbol) const override
| Gets the molar abundances of all species in the composition.
double | getMolarAbundance (const atomic::Species &species) const override
| Gets the molar abundance for a given species.
double | getMeanParticleMass () const noexcept override
| Compute the mean particle mass of the composition.
double | getElectronAbundance () const noexcept override
| Compute the electron abundance of the composition.
CanonicalComposition | getCanonicalComposition () const
| Compute the canonical composition (X, Y, Z) of the composition.
std::vector< double > | getMassFractionVector () const noexcept override
| Get a uniform vector representation of the mass fraction stored in the composition object sorted such that the lightest species is at index 0 and the heaviest is at the last index.
std::vector< double > | getNumberFractionVector () const noexcept override
| Get a uniform vector representation of the number fractions stored in the composition object sorted such that the lightest species is at index 0 and the heaviest is at the last index.
std::vector< double > | getMolarAbundanceVector () const noexcept override
| Get a uniform vector representation of the molar abundances stored in the composition object sorted such that the lightest species is at index 0 and the heaviest is at the last index.
size_t | getSpeciesIndex (const std::string &symbol) const override
| get the index in the sorted vector representation for a given symbol
size_t | getSpeciesIndex (const atomic::Species &species) const override
| get the index in the sorted vector representation for a given symbol
atomic::Species | getSpeciesAtIndex (size_t index) const override
| Get the species at a given index in the sorted vector representation.
auto | begin ()
| Returns an iterator to the beginning of the molar abundance map.
auto | begin () const
| Returns a const iterator to the beginning of the molar abundance map.
auto | end ()
| Returns an iterator to the end of the molar abundance map.
auto | end () const
| Returns a const iterator to the end of the molar abundance map.
Public Member Functions inherited from CompositionAbstract
virtual | ~CompositionAbstract ()=default
| Virtual destructor.

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

## Private Attributes
std::set< atomic::Species > | m_registeredSpecies
| Set of registered species in the composition.
std::map< atomic::Species, double > | m_molarAbundances
| Map of species to their molar abundances.
CompositionCache | m_cache
| Cache for computed properties to avoid redundant calculations.

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

## Detailed Description

Manages a collection of chemical species and their abundances.

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

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

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

Exceptions

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

Basic Example:
  Composition comp;
  comp.registerSymbol("H-1");
  comp.registerSymbol("He-4");
  comp.setMolarAbundance("H-1", 0.75);
  comp.setMolarAbundance("He-4", 0.25); // Note Molar Abundances do not need to sum to 1
  fourdst::composition::Composition::Composition
  Composition()=default
  Default constructor.
  fourdst::composition::Composition::setMolarAbundance
  void setMolarAbundance(const std::string &symbol, const double &molar_abundance)
  Sets the molar abundance for a given symbol.
  Definition composition.cpp:529
  fourdst::composition::Composition::registerSymbol
  void registerSymbol(const std::string &symbol)
  Registers a new symbol for inclusion in the composition.
  Definition composition.cpp:178

Definition at line 97 of file composition.h.

## Constructor & Destructor Documentation

## ◆ Composition() [1/9]

fourdst::composition::Composition::Composition | ( |  | ) |
| default

Default constructor.

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

## ◆ ~Composition()

fourdst::composition::Composition::~Composition | ( |  | ) |
| override default

Default destructor.

## ◆ Composition() [2/9]

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

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

Parameters

  symbols | The symbols to register.

Exceptions

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

Example:
  std::vector<std::string> symbols = {"H-1", "O-16"};
  Composition comp(symbols);
  fourdst::composition::Composition
  Manages a collection of chemical species and their abundances.
  Definition composition.h:97

Definition at line 84 of file composition.cpp.

## ◆ Composition() [3/9]

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

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

Parameters

  species | The species to register.

Example:
  std::vector<fourdst::atomic::Species> species = {fourdst::atomic::H_1, fourdst::atomic::O_16};
  Composition comp(species);
  fourdst::atomic::H_1
  static const Species H_1("H-1", "H", -1, 0, 1, 1, 0.0, "B-", std::numeric_limits< double >::quiet_NaN(), std::numeric_limits< double >::infinity(), "/2+*", "S=99.9855 78", 1.007825031898, 1.4e-05)
  fourdst::atomic::O_16
  static const Species O_16("O-16", "O", 0, 8, 8, 16, 7976.2072, "B-", -15412.184, std::numeric_limits< double >::infinity(), "+", "S=99.757 11", 15.99491461926, 0.00032)

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

Definition at line 100 of file composition.cpp.

## ◆ Composition() [4/9]

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

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

Parameters

  symbols | The symbols to register.

Exceptions

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

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

Definition at line 92 of file composition.cpp.

## ◆ Composition() [5/9]

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

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

Parameters

  species | The species to register.

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

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

Definition at line 108 of file composition.cpp.

## ◆ Composition() [6/9]

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

Constructs a Composition from symbols and their corresponding molar abundances.

Parameters

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

Exceptions

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

Example:
  std::vector<std::string> symbols = {"H-1", "O-16"};
  std::vector<double> molarAbundances = {1.03, 0.6};
  Composition comp(symbols, molarAbundances);

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

Definition at line 116 of file composition.cpp.

## ◆ Composition() [7/9]

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

Constructs a Composition from species and their corresponding molar abundances.

Parameters

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

Exceptions

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

Example:
  std::vector<fourdst::atomic::Species> species = {fourdst::atomic::H_1, fourdst::atomic::O_16};
  std::vector<double> molarAbundances = {1.03, 0.6};
  Composition comp(species, molarAbundances);

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

Definition at line 131 of file composition.cpp.

## ◆ Composition() [8/9]

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

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

Parameters

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

Exceptions

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

Example:
  std::set<std::string> symbols = {"H-1", "O-16"};
  std::vector<double> molarAbundances = {1.03, 0.6};
  Composition comp(symbols, molarAbundances);

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

Definition at line 146 of file composition.cpp.

## ◆ Composition() [9/9]

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

Constructs a Composition from another Composition.

Parameters

  composition | The Composition to copy.

Definition at line 161 of file composition.cpp.

## Member Function Documentation

## ◆ begin() [1/2]

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

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

Returns
  An iterator to the beginning.

Example:
  Composition comp({"H-1", "He-4", "C-12"}, {1.02, 0.56, 0.02});
  for (const auto& [sp, y] : comp) {
  std::cout << "Species: " << sp << ", Molar Abundance: " << y << std::endl;
  }

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

Definition at line 753 of file composition.h.

## ◆ begin() [2/2]

auto fourdst::composition::Composition::begin | ( |  | ) | const
| inline nodiscard

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

Returns
  A const iterator to the beginning.

Example:
  Composition comp({"H-1", "He-4", "C-12"}, {1.02, 0.56, 0.02});
  for (const auto& [sp, y] : comp) {
  std::cout << "Species: " << sp << ", Molar Abundance: " << y << std::endl;
  }

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

Definition at line 774 of file composition.h.

## ◆ contains() [1/2]

bool fourdst::composition::Composition::contains | ( | const atomic::Species & | species | ) | const
| nodiscard override virtual noexcept

Checks if a given species is present in the composition.

Parameters

  species | The isotope to check for.

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

Implements CompositionAbstract.

Definition at line 509 of file composition.cpp.

## ◆ contains() [2/2]

bool fourdst::composition::Composition::contains | ( | const std::string & | symbol | ) | const
| nodiscard override virtual

Checks if a given symbol is present in the composition.

Parameters

  symbol | The symbol to check for.

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

Exceptions

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

Implements CompositionAbstract.

Definition at line 515 of file composition.cpp.

## ◆ end() [1/2]

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

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

Returns
  An iterator to the end.

Example:
  Composition comp({"H-1", "He-4", "C-12"}, {1.02, 0.56, 0.02});
  for (const auto& [sp, y] : comp) {
  std::cout << "Species: " << sp << ", Molar Abundance: " << y << std::endl;
  }

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

Definition at line 795 of file composition.h.

## ◆ end() [2/2]

auto fourdst::composition::Composition::end | ( |  | ) | const
| inline nodiscard

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

Returns
  A const iterator to the end.

Example:
  Composition comp({"H-1", "He-4", "C-12"}, {1.02, 0.56, 0.02});
  for (const auto& [sp, y] : comp) {
  std::cout << "Species: " << sp << ", Molar Abundance: " << y << std::endl;
  }

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

Definition at line 816 of file composition.h.

## ◆ getCanonicalComposition()

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

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

The canonical composition is defined as:

- X: mass fraction of hydrogen ( )
- 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 330 of file composition.cpp.

## ◆ getElectronAbundance()

double fourdst::composition::Composition::getElectronAbundance | ( |  | ) | const
| nodiscard override virtual noexcept

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

Definition at line 321 of file composition.cpp.

## ◆ getLogger()

static quill::Logger * fourdst::composition::Composition::getLogger | ( |  | ) |
| inline static private

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

Returns
  pointer to the logger instance.

Definition at line 144 of file composition.h.

## ◆ getMassFraction() [1/3]

std::unordered_map< atomic::Species, double > fourdst::composition::Composition::getMassFraction | ( |  | ) | const
| nodiscard override virtual noexcept

Gets the mass fractions of all species in the composition.

Returns
  An unordered map of symbols to their mass fractions.

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

Implements CompositionAbstract.

Definition at line 251 of file composition.cpp.

## ◆ getMassFraction() [2/3]

double fourdst::composition::Composition::getMassFraction | ( | const atomic::Species & | species | ) | const
| nodiscard override virtual

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

Definition at line 235 of file composition.cpp.

## ◆ getMassFraction() [3/3]

double fourdst::composition::Composition::getMassFraction | ( | const std::string & | symbol | ) | const
| nodiscard override virtual

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

Parameters

  symbol | The symbol to get the mass fraction for.

Returns
  The mass fraction for the given symbol.

Exceptions

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

Implements CompositionAbstract.

Definition at line 227 of file composition.cpp.

## ◆ getMassFractionVector()

std::vector< double > fourdst::composition::Composition::getMassFractionVector | ( |  | ) | const
| nodiscard override virtual noexcept

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

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

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

Implements CompositionAbstract.

Definition at line 373 of file composition.cpp.

## ◆ getMeanParticleMass()

double fourdst::composition::Composition::getMeanParticleMass | ( |  | ) | const
| nodiscard override virtual noexcept

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

Definition at line 311 of file composition.cpp.

## ◆ getMolarAbundance() [1/2]

double fourdst::composition::Composition::getMolarAbundance | ( | const atomic::Species & | species | ) | const
| nodiscard override virtual

Gets the molar abundance for a given species.

Parameters

  species | The species to get the molar abundance for.

Returns
  The molar abundance for the given isotope.

Exceptions

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

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

Implements CompositionAbstract.

Definition at line 302 of file composition.cpp.

## ◆ getMolarAbundance() [2/2]

double fourdst::composition::Composition::getMolarAbundance | ( | const std::string & | symbol | ) | const
| nodiscard override virtual

Gets the molar abundances of all species in the composition.

Exceptions

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

Returns
  The molar abundance of the symbol.

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

Implements CompositionAbstract.

Definition at line 291 of file composition.cpp.

## ◆ getMolarAbundanceVector()

std::vector< double > fourdst::composition::Composition::getMolarAbundanceVector | ( |  | ) | const
| nodiscard override virtual noexcept

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

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

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

Implements CompositionAbstract.

Definition at line 416 of file composition.cpp.

## ◆ getNumberFraction() [1/3]

std::unordered_map< atomic::Species, double > fourdst::composition::Composition::getNumberFraction | ( |  | ) | const
| nodiscard override virtual noexcept

Gets the number fractions of all species in the composition.

Returns
  An unordered map of symbols to their number fractions.

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

Implements CompositionAbstract.

Definition at line 283 of file composition.cpp.

## ◆ getNumberFraction() [2/3]

double fourdst::composition::Composition::getNumberFraction | ( | const atomic::Species & | species | ) | const
| nodiscard override virtual

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

Definition at line 270 of file composition.cpp.

## ◆ getNumberFraction() [3/3]

double fourdst::composition::Composition::getNumberFraction | ( | const std::string & | symbol | ) | const
| nodiscard override virtual

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

Parameters

  symbol | The symbol to get the number fraction for.

Returns
  The number fraction for the given symbol.

Exceptions

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

Implements CompositionAbstract.

Definition at line 260 of file composition.cpp.

## ◆ getNumberFractionVector()

std::vector< double > fourdst::composition::Composition::getNumberFractionVector | ( |  | ) | const
| nodiscard override virtual noexcept

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

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

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

Implements CompositionAbstract.

Definition at line 395 of file composition.cpp.

## ◆ getRegisteredSpecies()

const std::set< atomic::Species > & fourdst::composition::Composition::getRegisteredSpecies | ( |  | ) | const
| nodiscard override virtual noexcept

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

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

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

Implements CompositionAbstract.

Definition at line 222 of file composition.cpp.

## ◆ getRegisteredSymbols()

std::set< std::string > fourdst::composition::Composition::getRegisteredSymbols | ( |  | ) | const
| nodiscard override virtual noexcept

Gets the registered symbols.

Returns
  A set of registered symbols.

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

Implements CompositionAbstract.

Definition at line 214 of file composition.cpp.

## ◆ getSpeciesAtIndex()

atomic::Species fourdst::composition::Composition::getSpeciesAtIndex | ( | size_t | index | ) | const
| nodiscard override virtual

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

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

Parameters

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

Exceptions

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

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

Implements CompositionAbstract.

Definition at line 483 of file composition.cpp.

## ◆ getSpeciesIndex() [1/2]

size_t fourdst::composition::Composition::getSpeciesIndex | ( | const atomic::Species & | species | ) | const
| nodiscard override virtual

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

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

Parameters

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

Exceptions

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

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

Implements CompositionAbstract.

Definition at line 449 of file composition.cpp.

## ◆ getSpeciesIndex() [2/2]

size_t fourdst::composition::Composition::getSpeciesIndex | ( | const std::string & | symbol | ) | const
| nodiscard override virtual

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

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

Parameters

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

Exceptions

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

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

Implements CompositionAbstract.

Definition at line 438 of file composition.cpp.

## ◆ operator=()

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

Assignment operator.

Parameters

  other | The Composition to assign from.

Returns
  A reference to this Composition.

Definition at line 168 of file composition.cpp.

## ◆ registerSpecies() [1/2]

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

Registers a new species by extracting its symbol.

Parameters

  species | The species to register.

Example:
  #include "fourdst/composition/species.h"
  Composition comp;
  comp.registerSpecies(fourdst::atomic::C_12);
  fourdst::composition::Composition::registerSpecies
  void registerSpecies(const atomic::Species &species) noexcept
  Registers a new species by extracting its symbol.
  Definition composition.cpp:197
  fourdst::atomic::C_12
  static const Species C_12("C-12", "C", 0, 6, 6, 12, 7680.1446, "B-", -17338.0681, std::numeric_limits< double >::infinity(), "+", "S=98.94 6", 12.0, 0.0)

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

Definition at line 197 of file composition.cpp.

## ◆ registerSpecies() [2/2]

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

Registers a vector of new species.

Parameters

  species | The vector of species to register.

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

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

Definition at line 206 of file composition.cpp.

## ◆ registerSymbol() [1/2]

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

Registers a new symbol for inclusion in the composition.

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

Parameters

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

Exceptions

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

Example:
  Composition comp;
  comp.registerSymbol("H-1");
  comp.registerSymbol("He-4");

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

Definition at line 178 of file composition.cpp.

## ◆ registerSymbol() [2/2]

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

Registers multiple new symbols.

Parameters

  symbols | The symbols to register.

Exceptions

  exceptions::UnknownSymbolError | if any symbol is invalid.

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

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

Definition at line 189 of file composition.cpp.

## ◆ setMolarAbundance() [1/6]

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

Sets the molar abundance for a given isotope.

Parameters

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

Exceptions

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

Example:
  #include "fourdst/composition/species.h"
  Composition comp({fourdst::atomic::H_1, fourdst::atomic::He_4});
  comp.setMolarAbundance(fourdst::atomic::H_1, 1.0);
  comp.setMolarAbundance(fourdst::atomic::He_4, 0.5);
  fourdst::atomic::He_4
  static const Species He_4("He-4", "He", 0, 2, 2, 4, 7073.9156, "B-", -22898.274, std::numeric_limits< double >::infinity(), "+", "S=99.9998 2", 4.00260325413, 0.00016)

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

Definition at line 541 of file composition.cpp.

## ◆ setMolarAbundance() [2/6]

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

Sets the molar abundances for a set of isotopes.

Parameters

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

Exceptions

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

Example:
  #include "fourdst/composition/species.h"
  std::set<fourdst::atomic::Species> species = {fourdst::atomic::H_1, fourdst::atomic::He_4};
  Composition comp(species);
  comp.setMolarAbundance(species, {1.0, 0.5});

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

Definition at line 582 of file composition.cpp.

## ◆ setMolarAbundance() [3/6]

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

Sets the molar abundances for a set of symbols.

Parameters

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

Exceptions

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

Example:
  std::set<std::string> symbols = {"H-1", "He-4"};
  Composition comp(symbols);
  comp.setMolarAbundance(symbols, {1.0, 0.5});

Definition at line 573 of file composition.cpp.

## ◆ setMolarAbundance() [4/6]

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

Sets the molar abundance for a given symbol.

Parameters

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

Exceptions

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

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

Definition at line 529 of file composition.cpp.

## ◆ setMolarAbundance() [5/6]

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

Sets the molar abundances for a list of isotopes.

Parameters

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

Exceptions

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

Example:
  #include "fourdst/composition/species.h"
  Composition comp({fourdst::atomic::H_1, fourdst::atomic::He_4});
  comp.setMolarAbundance({fourdst::atomic::H_1, fourdst::atomic::He_4}, {1.0, 0.5});

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

Definition at line 564 of file composition.cpp.

## ◆ setMolarAbundance() [6/6]

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

Sets the molar abundances for a list of symbols.

Parameters

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

Exceptions

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

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

Definition at line 555 of file composition.cpp.

## ◆ size()

size_t fourdst::composition::Composition::size | ( |  | ) | const
| nodiscard override virtual noexcept

Gets the number of registered species in the composition.

Returns
  The number of registered species.

Implements CompositionAbstract.

Definition at line 525 of file composition.cpp.

## Friends And Related Symbol Documentation

## ◆ operator<<

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

Overloaded output stream operator for Composition.

Parameters

  os | The output stream.
  composition | The Composition to output.

Returns
  The output stream.

Definition at line 593 of file composition.cpp.

## Member Data Documentation

## ◆ m_cache

CompositionCache fourdst::composition::Composition::m_cache
| mutable private

Cache for computed properties to avoid redundant calculations.

Definition at line 152 of file composition.h.

## ◆ m_molarAbundances

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

Map of species to their molar abundances.

Definition at line 150 of file composition.h.

## ◆ m_registeredSpecies

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

Set of registered species in the composition.

Definition at line 149 of file composition.h.

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

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