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

Loading...
Searching...
No Matches
Namespaces | Classes | Functions
fourdst::composition Namespace Reference

Utilities and types for representing and manipulating chemical compositions. More...

## Namespaces
namespace | exceptions
namespace | utils

## Classes
struct | CanonicalComposition
| Represents the canonical (X, Y, Z) composition of stellar material. More...
class | Composition
| Manages a collection of chemical species and their abundances. More...
class | CompositionAbstract
| Abstract base class for chemical composition representations. More...
class | CompositionDecorator
class | MaskedComposition

## Functions
bool | operator== (const Composition &a, const Composition &b) noexcept
Composition | buildCompositionFromMassFractions (const std::vector< std::string > &symbols, const std::vector< double > &massFractions)
| Build a Composition object from symbols and their corresponding mass fractions.
Composition | buildCompositionFromMassFractions (const std::vector< atomic::Species > &species, const std::vector< double > &massFractions)
| Build a Composition object from species and their corresponding mass fractions.
Composition | buildCompositionFromMassFractions (const std::set< atomic::Species > &species, const std::vector< double > &massFractions)
| Build a Composition object from species in a set and their corresponding mass fractions.
Composition | buildCompositionFromMassFractions (const std::unordered_map< atomic::Species, double > &massFractionsMap)
| Build a Composition object from a map of species to mass fractions.
Composition | buildCompositionFromMassFractions (const std::unordered_map< std::string, double > &massFractions)
| Build a Composition object from a map of species to mass fractions.
Composition | buildCompositionFromMassFractions (std::map< atomic::Species, double > massFractions)
| Build a Composition object from a map of species to mass fractions.
Composition | buildCompositionFromMassFractions (std::map< std::string, double > massFractions)
| Build a Composition object from a map of species to mass fractions.
std::ostream & | operator<< (std::ostream &os, const Composition &composition)
| OVERLOADS.

## Detailed Description

Utilities and types for representing and manipulating chemical compositions.

The composition module provides a small, but expressive, API for constructing and querying material compositions used throughout the 4D-STAR codebase. A Composition represents a collection of atomic species together with their molar abundances. From these molar abundances the module can compute derived quantities such as mass fractions, number fractions, canonical (X, Y, Z) composition, mean particle mass, and the electron abundance (Y_e).

Key concepts:

- Species and Symbols: Atomic isotopes are represented by the strongly-typed fourdst::atomic::Species values (see `fourdst/atomic/species.h`). Each species also has a human-readable string symbol (e.g. "H-1", "He-4") used by some constructors and convenience overloads.
- Molar abundances: The Composition API accepts and stores molar abundances (absolute mole counts). Many derived quantities (mass fraction, number fraction, mean particle mass) are computed from these molar abundances.
- Canonical composition: A CanonicalComposition (X, Y, Z) is provided which groups mass fractions into hydrogen (X), helium (Y), and metals (Z). A lightweight struct `CanonicalComposition` holds these values and provides an ostream operator for easy logging and testing.
- Caching: The concrete Composition implementation caches computed vectors and scalars to avoid repeated work. The cache is invalidated automatically when molar abundances or registered species are changed.

## Main types and functions

- Composition: The primary concrete class for building and interrogating compositions. It implements the CompositionAbstract interface and exposes methods to register symbols/species, set molar abundances, and query all commonly-needed derived quantities. Multiple constructors are provided for convenience (from vectors/sets of symbols or species, with optional molar-abundance initialization).

  Important member functions include:

  - registerSymbol / registerSpecies (single or many overloads)
  - setMolarAbundance (many overloads accepting symbols or species)
  - getMolarAbundance, getMassFraction, getNumberFraction (symbol and species overloads)
  - getMassFractionVector, getNumberFractionVector, getMolarAbundanceVector
  - getMeanParticleMass, getElectronAbundance
  - getCanonicalComposition
  - Iteration support (begin/end) which iterates species from lightest to heaviest because species ordering is defined by atomic mass.
- CompositionAbstract: A compact abstract interface implemented by Composition which guarantees the presence of all getter/query methods. This allows other components to accept composition-like objects without depending on the concrete implementation.
- Utilities (fourdst::composition::buildCompositionFromMassFractions): Convenience helpers exist to construct a Composition from mass fractions (instead of molar abundances). Those helpers validate that the provided mass fractions sum to unity within a tight tolerance and convert them into the corresponding molar abundances before returning a populated Composition.
- Exceptions (namespace fourdst::composition::exceptions): The module defines a small hierarchy of exceptions for error handling:
  - CompositionError: Base class for composition-related errors.
  - InvalidCompositionError: Thrown when the composition is inconsistent or when mass fractions fail validation.
  - UnregisteredSymbolError: Thrown when an operation requires a symbol that hasn't been registered on the Composition object.
  - UnknownSymbolError: Thrown when a provided string symbol does not map to any known atomic species in the atomic species database.

## Usage examples

Example 1 – basic construction and queries:

#include "fourdst/composition/composition.h"
using namespace fourdst::composition;
Composition comp;
comp.registerSymbol("H-1");
comp.registerSymbol("He-4");
comp.setMolarAbundance("H-1", 1.0);
comp.setMolarAbundance("He-4", 0.5);
double X_h1 = comp.getMassFraction("H-1");
double meanA = comp.getMeanParticleMass();
CanonicalComposition canon = comp.getCanonicalComposition();
std::cout << canon << std::endl; // prints X, Y, Z
fourdst::composition::Composition
Manages a collection of chemical species and their abundances.
Definition composition.h:98
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:580
fourdst::composition::Composition::registerSymbol
void registerSymbol(const std::string &symbol)
Registers a new symbol for inclusion in the composition.
Definition composition.cpp:225
fourdst::composition::Composition::getMassFraction
std::unordered_map< atomic::Species, double > getMassFraction() const noexcept override
Gets the mass fractions of all species in the composition.
Definition composition.cpp:298
fourdst::composition::Composition::getCanonicalComposition
CanonicalComposition getCanonicalComposition() const
Compute the canonical composition (X, Y, Z) of the composition.
Definition composition.cpp:377
fourdst::composition::Composition::getMeanParticleMass
double getMeanParticleMass() const noexcept override
Compute the mean particle mass of the composition.
Definition composition.cpp:358
composition.h
fourdst::composition
Utilities and types for representing and manipulating chemical compositions.
fourdst::composition::CanonicalComposition
Represents the canonical (X, Y, Z) composition of stellar material.
Definition composition.h:45

Example 2 – constructing from mass fractions:

#include "fourdst/composition/utils.h"
std::vector<std::string> symbols = {"H-1", "He-4", "C-12"};
std::vector<double> massFractions = {0.70, 0.28, 0.02};
Composition comp = buildCompositionFromMassFractions(symbols, massFractions);
fourdst::composition::buildCompositionFromMassFractions
Composition buildCompositionFromMassFractions(const std::vector< std::string > &symbols, const std::vector< double > &massFractions)
Build a Composition object from symbols and their corresponding mass fractions.
Definition utils.cpp:84
utils.h

## Notes and remarks

- Molar abundances are the canonical input for the Composition class. When passing mass fractions, use the `buildCompositionFromMassFractions` helper which performs the safe conversion and validation.
- Many methods throw exceptions from the `fourdst::composition::exceptions` namespace on invalid usage (unknown symbols, unregistered species, or invalid abundance values). Callers should catch and handle these where appropriate.
- Floating point results (mass/number fractions, mean particle mass, Y_e) are computed as doubles and may have small numerical round-off. Callers comparing values in tests should use an appropriate tolerance.

## See also

- fourdst/atomic/species.h — canonical atomic species definitions and symbols.
- fourdst/composition/composition.h — concrete Composition implementation.
- fourdst/composition/composition_abstract.h — abstract composition interface.
- fourdst/composition/utils.h — helpers for constructing compositions from mass fractions.

## Function Documentation

## ◆ buildCompositionFromMassFractions() [1/7]

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

Build a Composition object from species in a set and their corresponding mass fractions.

Parameters

  species | The species to register.
  massFractions | The corresponding mass fractions for each species.

Returns
  A Composition object constructed from the provided species and mass fractions.

Exceptions

  exceptions::InvalidCompositionError | if the provided mass fractions do not sum to within one part in 10^10 of 1.0.
  exceptions::InvalidCompositionError | if the number of species does not match the number of mass fractions.

Note
  This is the version of the function which the other overloads ultimately call.

Definition at line 36 of file utils.cpp.

## ◆ buildCompositionFromMassFractions() [2/7]

Composition fourdst::composition::buildCompositionFromMassFractions | ( | const std::unordered_map< atomic::Species, double > & | massFractionsMap | ) |

Build a Composition object from a map of species to mass fractions.

Parameters

  massFractionsMap | The map of species to their corresponding mass fractions.

Returns
  A Composition object constructed from the provided species and mass fractions.

Exceptions

  exceptions::InvalidCompositionError | if the provided mass fractions do not sum to within one part in 10^10 of 1.0.

Definition at line 107 of file utils.cpp.

## ◆ buildCompositionFromMassFractions() [3/7]

Composition fourdst::composition::buildCompositionFromMassFractions | ( | const std::unordered_map< std::string, double > & | massFractions | ) |

Build a Composition object from a map of species to mass fractions.

Parameters

  massFractions | The map of species to their corresponding mass fractions.

Returns
  A Composition object constructed from the provided species and mass fractions.

Exceptions

  exceptions::InvalidCompositionError | if the provided mass fractions do not sum to within one part in 10^10 of 1.0.

Definition at line 170 of file utils.cpp.

## ◆ buildCompositionFromMassFractions() [4/7]

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

Build a Composition object from species and their corresponding mass fractions.

Parameters

  species | The species to register.
  massFractions | The corresponding mass fractions for each species.

Returns
  A Composition object constructed from the provided species and mass fractions.

Exceptions

  exceptions::InvalidCompositionError | if the provided mass fractions do not sum to within one part in 10^10 of 1.0.
  exceptions::InvalidCompositionError | if the number of species does not match the number of mass fractions.

Definition at line 70 of file utils.cpp.

## ◆ buildCompositionFromMassFractions() [5/7]

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

Build a Composition object from symbols and their corresponding mass fractions.

Parameters

  symbols | The symbols to register.
  massFractions | The corresponding mass fractions for each symbol.

Returns
  A Composition object constructed from the provided symbols and mass fractions.

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 provided mass fractions do not sum to within one part in 10^10 of 1.0.
  exceptions::InvalidCompositionError | if the number of symbols does not match the number of mass fractions.

Definition at line 84 of file utils.cpp.

## ◆ buildCompositionFromMassFractions() [6/7]

Composition fourdst::composition::buildCompositionFromMassFractions | ( | std::map< atomic::Species, double > | massFractions | ) |

Build a Composition object from a map of species to mass fractions.

Parameters

  massFractions | The map of species to their corresponding mass fractions.

Returns
  A Composition object constructed from the provided species and mass fractions.

Exceptions

  exceptions::InvalidCompositionError | if the provided mass fractions do not sum to within one part in 10^10 of 1.0.

Definition at line 127 of file utils.cpp.

## ◆ buildCompositionFromMassFractions() [7/7]

Composition fourdst::composition::buildCompositionFromMassFractions | ( | std::map< std::string, double > | massFractions | ) |

Build a Composition object from a map of species to mass fractions.

Parameters

  massFractions | The map of species to their corresponding mass fractions.

Returns
  A Composition object constructed from the provided species and mass fractions.

Exceptions

  exceptions::InvalidCompositionError | if the provided mass fractions do not sum to within one part in 10^10 of 1.0.

Definition at line 141 of file utils.cpp.

## ◆ operator<<()

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

OVERLOADS.

Overloaded output stream operator for Composition.

Parameters

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

Returns
  The output stream.

Definition at line 644 of file composition.cpp.

## ◆ operator==()

bool fourdst::composition::operator== | ( | const Composition & | a,
|  | const Composition & | b
| ) |  |
| inline noexcept

Definition at line 837 of file composition.h.