# fourdst::libcomposition: fourdst::composition::Composition Class Reference

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

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

`#include <composition.h>`

Inheritance diagram for fourdst::composition::Composition:

## Classes

struct | CompositionCache

## Public Member Functions

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

## Private Member Functions

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

## Static Private Member Functions

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

## Private Attributes

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

Key Rules and Workflow:

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

Exceptions

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

Mass Fraction Example:
  Composition comp;
  comp.registerSymbol("H-1");
  comp.registerSymbol("He-4");
  comp.setMassFraction("H-1", 0.75);
  comp.setMassFraction("He-4", 0.25);
  if (comp.finalize()) {
  double he_mass_frac = comp.getMassFraction("He-4"); // Returns 0.25
  }
  fourdst::composition::Composition::registerSymbol
  void registerSymbol(const std::string &symbol, bool massFracMode=true)
  Registers a new symbol for inclusion in the composition.
  Definition composition.cpp:255
  fourdst::composition::Composition::Composition
  Composition()=default
  Default constructor.
  fourdst::composition::Composition::setMassFraction
  double setMassFraction(const std::string &symbol, const double &mass_fraction)
  Sets the mass fraction for a given symbol.
  Definition composition.cpp:343
  fourdst::composition::Composition::finalize
  bool finalize(bool norm=false)
  Finalizes the composition, making it ready for querying.
  Definition composition.cpp:445
  fourdst::composition::Composition::getMassFraction
  std::unordered_map< std::string, double > getMassFraction() const override
  Gets the mass fractions of all species in the composition.
  Definition composition.cpp:601

Number Fraction Example:
  Composition comp;
  comp.registerSymbol("H-1", false); // Register in number fraction mode
  comp.registerSymbol("He-4", false);
  comp.setNumberFraction("H-1", 0.9);
  comp.setNumberFraction("He-4", 0.1);
  if (comp.finalize()) {
  double he_num_frac = comp.getNumberFraction("He-4"); // Returns 0.1
  }
  fourdst::composition::Composition::getNumberFraction
  double getNumberFraction(const std::string &symbol) const override
  Gets the number fraction for a given symbol.
  Definition composition.cpp:610
  fourdst::composition::Composition::setNumberFraction
  double setNumberFraction(const std::string &symbol, const double &number_fraction)
  Sets the number fraction for a given symbol.
  Definition composition.cpp:374

Definition at line 255 of file composition.h.

## Constructor & Destructor Documentation

## Composition() [1/5]

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

default

Default constructor.

## ~Composition()

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

overridedefault

Default destructor.

## Composition() [2/5]

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

explicit

Constructs a Composition and registers the given symbols.

Parameters

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

Exceptions

  exceptions::InvalidSymbolError | if any symbol is invalid.

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

Definition at line 187 of file composition.cpp.

## Composition() [3/5]

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

explicit

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

Parameters

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

Exceptions

  exceptions::InvalidSymbolError | if any symbol is invalid.

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

Definition at line 195 of file composition.cpp.

## Composition() [4/5]

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

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

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

Parameters

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

Exceptions

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

Postcondition
  The composition is immediately finalized.

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

Definition at line 203 of file composition.cpp.

## Composition() [5/5]

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

Constructs a Composition from another Composition.

Parameters

  composition | The Composition to copy.

Definition at line 234 of file composition.cpp.

## Member Function Documentation

## begin() [1/2]

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

inline

Returns an iterator to the beginning of the composition map.

Returns
  An iterator to the beginning.

Definition at line 864 of file composition.h.

## begin() [2/2]

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

inlinenodiscard

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

Returns
  A const iterator to the beginning.

Definition at line 872 of file composition.h.

## contains()

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

nodiscardoverridevirtual

Checks if a given isotope is present in the composition.

Precondition
  The composition must be finalized.

Parameters

  isotope | The isotope to check for.

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

Exceptions

  exceptions::CompositionNotFinalizedError | if the composition is not finalized.

Implements CompositionAbstract.

Definition at line 1038 of file composition.cpp.

## end() [1/2]

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

inline

Returns an iterator to the end of the composition map.

Returns
  An iterator to the end.

Definition at line 880 of file composition.h.

## end() [2/2]

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

inlinenodiscard

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

Returns
  A const iterator to the end.

Definition at line 888 of file composition.h.

## finalize()

bool fourdst::composition::Composition::finalize | ( | bool | norm = false | ) |

nodiscard

Finalizes the composition, making it ready for querying.

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

Parameters

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

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

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

Definition at line 445 of file composition.cpp.

## finalizeMassFracMode()

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

private

Finalizes the composition in mass fraction mode.

Parameters

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

Returns
  True if the composition is successfully finalized, false otherwise.

Definition at line 453 of file composition.cpp.

## finalizeNumberFracMode()

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

private

Finalizes the composition in number fraction mode.

Parameters

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

Returns
  True if the composition is successfully finalized, false otherwise.

Definition at line 489 of file composition.cpp.

## getCanonicalComposition()

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

nodiscard

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

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

Precondition
  The composition must be finalized.

Parameters

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

Returns
  The `CanonicalComposition` struct.

Exceptions

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

Definition at line 785 of file composition.cpp.

## getComposition() [1/3]

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

nodiscard

Gets all composition entries and the global composition data.

Precondition
  The composition must be finalized.

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

Exceptions

  exceptions::CompositionNotFinalizedError | if the composition is not finalized.

Definition at line 682 of file composition.cpp.

## getComposition() [2/3]

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

nodiscard

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

Precondition
  The composition must be finalized.

Parameters

  species | The species to get the composition for.

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

Exceptions

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

Definition at line 676 of file composition.cpp.

## getComposition() [3/3]

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

nodiscard

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

Precondition
  The composition must be finalized.

Parameters

  symbol | The symbol to get the composition for.

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

Exceptions

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

Definition at line 662 of file composition.cpp.

## getElectronAbundance()

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

nodiscardoverridevirtual

Compute the electron abundance of the composition.

Ye is defined as the sum over all species of (Z_i * X_i / A_i), where Z_i is the atomic number, X_i is the mass fraction, and A_i is the atomic mass of species i.

Returns
  Ye (electron abundance).

Precondition
  The composition must be finalized.

Implements CompositionAbstract.

Definition at line 716 of file composition.cpp.

## getMassFraction() [1/3]

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

nodiscardoverridevirtual

Gets the mass fractions of all species in the composition.

Precondition
  The composition must be finalized.

Returns
  An unordered map of symbols to their mass fractions.

Exceptions

  exceptions::CompositionNotFinalizedError | if the composition is not finalized.

Implements CompositionAbstract.

Definition at line 601 of file composition.cpp.

## getMassFraction() [2/3]

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

nodiscardoverridevirtual

Gets the mass fraction for a given isotope.

Precondition
  The composition must be finalized.

Parameters

  species | The isotope to get the mass fraction for.

Returns
  The mass fraction for the given isotope.

Exceptions

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

Implements CompositionAbstract.

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

Precondition
  The composition must be finalized.

Parameters

  symbol | The symbol to get the mass fraction for.

Returns
  The mass fraction for the given symbol.

Exceptions

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

Implements CompositionAbstract.

Definition at line 568 of file composition.cpp.

## getMassFractionVector()

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

nodiscardoverridevirtual

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

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

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

Precondition
  The composition must be finalized.

Exceptions

  exceptions::CompositionNotFinalizedError | if the composition is not finalized.

Implements CompositionAbstract.

Definition at line 840 of file composition.cpp.

## getMeanAtomicNumber()

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

nodiscardoverridevirtual

Compute the mean atomic number of the composition.

Precondition
  The composition must be finalized.

Returns
  Mean atomic number <Z>.

Exceptions

  exceptions::CompositionNotFinalizedError | if the composition is not finalized.

Implements CompositionAbstract.

Definition at line 698 of file composition.cpp.

## getMeanParticleMass()

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

nodiscardoverridevirtual

Compute the mean particle mass of the composition.

Precondition
  The composition must be finalized.

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

Exceptions

  exceptions::CompositionNotFinalizedError | if the composition is not finalized.

Implements CompositionAbstract.

Definition at line 690 of file composition.cpp.

## getMolarAbundance() [1/2]

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

nodiscardoverridevirtual

Gets the molar abundance for a given isotope.

Precondition
  The composition must be finalized.

Parameters

  species | The isotope to get the molar abundance for.

Returns
  The molar abundance for the given isotope.

Exceptions

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

Implements CompositionAbstract.

Definition at line 656 of file composition.cpp.

## getMolarAbundance() [2/2]

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

nodiscardoverridevirtual

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

Precondition
  The composition must be finalized.

Parameters

  symbol | The symbol to get the molar abundance for.

Returns
  The molar abundance for the given symbol.

Exceptions

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

Implements CompositionAbstract.

Definition at line 641 of file composition.cpp.

## getMolarAbundanceVector()

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

nodiscardoverridevirtual

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

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

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

Precondition
  The composition must be finalized.

Exceptions

  exceptions::CompositionNotFinalizedError | if the composition is not finalized.

Implements CompositionAbstract.

Definition at line 891 of file composition.cpp.

## getNumberFraction() [1/3]

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

nodiscardoverridevirtual

Gets the number fractions of all species in the composition.

Precondition
  The composition must be finalized.

Returns
  An unordered map of symbols to their number fractions.

Exceptions

  exceptions::CompositionNotFinalizedError | if the composition is not finalized.

Implements CompositionAbstract.

Definition at line 633 of file composition.cpp.

## getNumberFraction() [2/3]

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

nodiscardoverridevirtual

Gets the number fraction for a given isotope.

Precondition
  The composition must be finalized.

Parameters

  species | The isotope to get the number fraction for.

Returns
  The number fraction for the given isotope.

Exceptions

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

Implements CompositionAbstract.

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

Precondition
  The composition must be finalized.

Parameters

  symbol | The symbol to get the number fraction for.

Returns
  The number fraction for the given symbol.

Exceptions

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

Implements CompositionAbstract.

Definition at line 610 of file composition.cpp.

## getNumberFractionVector()

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

nodiscardoverridevirtual

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

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

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

Precondition
  The composition must be finalized.

Exceptions

  exceptions::CompositionNotFinalizedError | if the composition is not finalized.

Implements CompositionAbstract.

Definition at line 866 of file composition.cpp.

## getRegisteredSpecies()

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

nodiscardoverridevirtual

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

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

Implements CompositionAbstract.

Definition at line 313 of file composition.cpp.

## getRegisteredSymbols()

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

nodiscardoverridevirtual

Gets the registered symbols.

Returns
  A set of registered symbols.

Implements CompositionAbstract.

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

Precondition
  The composition must be finalized.

Parameters

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

Exceptions

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

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

Implements CompositionAbstract.

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

Precondition
  The composition must be finalized.
  symbol must be registered in the composition

Parameters

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

Exceptions

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

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

Implements CompositionAbstract.

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

Precondition
  The composition must be finalized.
  symbol must be registered in the composition

Parameters

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

Exceptions

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

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

Implements CompositionAbstract.

Definition at line 917 of file composition.cpp.

## hasSpecies()

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

nodiscardoverridevirtual

Checks if a species is registered in the composition.

Parameters

  species | The species to check.

Returns
  True if the species is registered, false otherwise.

Implements CompositionAbstract.

Definition at line 1029 of file composition.cpp.

## hasSymbol()

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

nodiscardoverridevirtual

Checks if a symbol is registered in the composition.

Parameters

  symbol | The symbol to check.

Returns
  True if the symbol is registered, false otherwise.

Implements CompositionAbstract.

Definition at line 1023 of file composition.cpp.

## isValidComposition()

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

nodiscardprivate

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

Parameters

  fractions | The fractions to check.

Returns
  True if the fractions are valid, false otherwise.

Definition at line 334 of file composition.cpp.

## isValidSymbol()

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

staticprivate

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

Parameters

  symbol | The symbol to check.

Returns
  True if the symbol is valid, false otherwise.

Definition at line 321 of file composition.cpp.

## mix()

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

nodiscard

Mixes this composition with another to produce a new composition.

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

Parameters

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

Returns
  A new, finalized `Composition` object representing the mixture.

Precondition
  Both `this` and `other` compositions must be finalized.

Exceptions

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

Definition at line 533 of file composition.cpp.

## operator+()

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

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

OVERLOADS.

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

Parameters

  other | The other composition to mix with.

Returns
  The new, mixed composition.

Precondition
  Both compositions must be finalized.

Exceptions

  See | `mix()` for exceptions.

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

## registerSpecies() [1/2]

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

Registers a new species by extracting its symbol.

Parameters

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

Exceptions

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

Usage Example:
  #include "fourdst/composition/species.h" // Assuming species like H1 are defined here
  Composition comp;
  comp.registerSpecies(fourdst::atomic::species.at("H-1"));
  fourdst::composition::Composition::registerSpecies
  void registerSpecies(const fourdst::atomic::Species &species, bool massFracMode=true)
  Registers a new species by extracting its symbol.
  Definition composition.cpp:293
  fourdst::atomic::species
  static const std::unordered_map< std::string, const Species & > species
  Map of species names to their corresponding Species objects.
  Definition species.h:3579
  species.h

Definition at line 293 of file composition.cpp.

## registerSpecies() [2/2]

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

Registers a vector of new species.

Parameters

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

Exceptions

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

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

Definition at line 300 of file composition.cpp.

## registerSymbol() [1/2]

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

Registers a new symbol for inclusion in the composition.

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

Parameters

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

Exceptions

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

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

Definition at line 255 of file composition.cpp.

## registerSymbol() [2/2]

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

Registers multiple new symbols.

Parameters

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

Exceptions

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

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

Definition at line 284 of file composition.cpp.

## setCompositionMode()

void fourdst::composition::Composition::setCompositionMode | ( | bool | massFracMode | ) |

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

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

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

Parameters

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

Exceptions

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

Definition at line 762 of file composition.cpp.

## setMassFraction() [1/4]

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

Sets the mass fraction for a given species.

Parameters

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

Returns
  The previous mass fraction that was set for the species.

Exceptions

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

Definition at line 411 of file composition.cpp.

## setMassFraction() [2/4]

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

Sets the mass fraction for a given symbol.

Parameters

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

Returns
  The previous mass fraction that was set for the symbol.

Exceptions

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

Postcondition
  The composition is marked as not finalized.

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

Definition at line 343 of file composition.cpp.

## setMassFraction() [3/4]

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

Sets the mass fraction for multiple species.

Parameters

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

Returns
  A vector of the previous mass fractions that were set.

Exceptions

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

Definition at line 418 of file composition.cpp.

## setMassFraction() [4/4]

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

Sets the mass fraction for multiple symbols.

Parameters

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

Returns
  A vector of the previous mass fractions that were set.

Exceptions

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

Postcondition
  The composition is marked as not finalized.

Definition at line 362 of file composition.cpp.

## setNumberFraction() [1/4]

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

Sets the number fraction for a given species.

Parameters

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

Returns
  The previous number fraction that was set for the species.

Exceptions

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

Definition at line 428 of file composition.cpp.

## setNumberFraction() [2/4]

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

Sets the number fraction for a given symbol.

Parameters

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

Returns
  The previous number fraction that was set.

Exceptions

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

Postcondition
  The composition is marked as not finalized.

Definition at line 374 of file composition.cpp.

## setNumberFraction() [3/4]

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

Sets the number fraction for multiple species.

Parameters

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

Returns
  The vector of the previous number fractions that were set.

Exceptions

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

Definition at line 435 of file composition.cpp.

## setNumberFraction() [4/4]

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

Sets the number fraction for multiple symbols.

Parameters

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

Returns
  A vector of the previous number fractions that were set.

Exceptions

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

Definition at line 396 of file composition.cpp.

## subset()

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

nodiscard

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

Parameters

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

Returns
  A new `Composition` object containing the subset.

Exceptions

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

Definition at line 734 of file composition.cpp.

## validateComposition()

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

private

Validates the given fractions, throwing an exception on failure.

Parameters

  fractions | The fractions to validate.

Exceptions

  exceptions::InvalidCompositionError | if the fractions are invalid.

Definition at line 327 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 1078 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 297 of file composition.h.

## m_compositions

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

private

The compositions.

Definition at line 295 of file composition.h.

## m_config

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

private

Definition at line 285 of file composition.h.

## m_finalized

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

private

True if the composition is finalized.

Definition at line 289 of file composition.h.

## m_logger

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

private

Definition at line 287 of file composition.h.

## m_logManager

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

private

Definition at line 286 of file composition.h.

## m_massFracMode

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

private

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

Definition at line 292 of file composition.h.

## m_meanParticleMass

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

private

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

Definition at line 291 of file composition.h.

## m_registeredSymbols

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

private

The registered symbols.

Definition at line 294 of file composition.h.

## m_specificNumberDensity

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

private

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

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