tboudreaux/libcomposition
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(libcomposition): added more docstrings

Browse Source
This commit is contained in:
Emily Boudreaux
2025-10-12 10:21:28 -04:00
parent 0ef3b1a195
commit 5baa671ddd
4 changed files with 321 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
src/composition/include/fourdst/composition/composition_abstract.h
View File

@@ -6,39 +6,177 @@
#include <unordered_map>
#include <set>
/**
* @brief Abstract base class for chemical composition representations.
*
* The purpose of this class is to define a standard interface for all composition types.
* Children of this class are responsible for implementing the setter methods, but any
* object that is a child of CompositionAbstract will always have these getter methods.
*
* This ensures that all derived composition classes provide a consistent API for querying
* composition properties, regardless of how the data is set or stored.
*
* @par Example
* @code
* class MyComposition : public CompositionAbstract {
* // ...implement all pure virtual methods...
* };
*
* MyComposition comp;
* if (comp.hasSymbol("H")) {
* double mf = comp.getMassFraction("H");
* }
* std::set<std::string> symbols = comp.getRegisteredSymbols();
* @endcode
*/
class CompositionAbstract {
public:
/**
* @brief Virtual destructor.
*/
virtual ~CompositionAbstract() = default;
/**
* @brief Check if a chemical symbol is registered in the composition.
* @param symbol The chemical symbol to check (e.g., "H", "He").
* @return True if the symbol is present, false otherwise.
*/
[[nodiscard]] virtual bool hasSymbol(const std::string& symbol) const = 0;
/**
* @brief Check if a species is registered in the composition.
* @param species The atomic species to check.
* @return True if the species is present, false otherwise.
*/
[[nodiscard]] virtual bool hasSpecies(const fourdst::atomic::Species& species) const = 0;
/**
* @brief Check if the composition contains the given species.
* @param species The atomic species to check.
* @return True if the species is contained, false otherwise.
*/
[[nodiscard]] virtual bool contains(const fourdst::atomic::Species& species) const = 0;
/**
* @brief Get all registered chemical symbols in the composition.
* @return A set of registered chemical symbols.
*/
[[nodiscard]] virtual std::set<std::string> getRegisteredSymbols() const = 0;
/**
* @brief Get all registered atomic species in the composition.
* @return A set of registered atomic species.
*/
[[nodiscard]] virtual std::set<fourdst::atomic::Species> getRegisteredSpecies() const = 0;
/**
* @brief Get the mass fraction for all registered symbols.
* @return An unordered map from symbol to mass fraction.
*/
[[nodiscard]] virtual std::unordered_map<std::string, double> getMassFraction() const = 0;
/**
* @brief Get the number fraction for all registered symbols.
* @return An unordered map from symbol to number fraction.
*/
[[nodiscard]] virtual std::unordered_map<std::string, double> getNumberFraction() const = 0;
/**
* @brief Get the mass fraction for a given symbol.
* @param symbol The chemical symbol.
* @return The mass fraction for the symbol.
*/
[[nodiscard]] virtual double getMassFraction(const std::string& symbol) const = 0;
/**
* @brief Get the mass fraction for a given species.
* @param species The atomic species.
* @return The mass fraction for the species.
*/
[[nodiscard]] virtual double getMassFraction(const fourdst::atomic::Species& species) const = 0;
/**
* @brief Get the number fraction for a given symbol.
* @param symbol The chemical symbol.
* @return The number fraction for the symbol.
*/
[[nodiscard]] virtual double getNumberFraction(const std::string& symbol) const = 0;
/**
* @brief Get the number fraction for a given species.
* @param species The atomic species.
* @return The number fraction for the species.
*/
[[nodiscard]] virtual double getNumberFraction(const fourdst::atomic::Species& species) const = 0;
/**
* @brief Get the molar abundance for a given symbol.
* @param symbol The chemical symbol.
* @return The molar abundance for the symbol.
*/
[[nodiscard]] virtual double getMolarAbundance(const std::string& symbol) const = 0;
/**
* @brief Get the molar abundance for a given species.
* @param species The atomic species.
* @return The molar abundance for the species.
*/
[[nodiscard]] virtual double getMolarAbundance(const fourdst::atomic::Species& species) const = 0;
/**
* @brief Get the mean particle mass of the composition.
* @return The mean particle mass.
*/
[[nodiscard]] virtual double getMeanParticleMass() const = 0;
/**
* @brief Get the mean atomic number of the composition.
* @return The mean atomic number.
*/
[[nodiscard]] virtual double getMeanAtomicNumber() const = 0;
/**
* @brief Get the electron abundance of the composition.
* @return The electron abundance.
*/
[[nodiscard]] virtual double getElectronAbundance() const = 0;
/**
* @brief Get the mass fraction as a vector.
* @return A vector of mass fractions for all species.
*/
[[nodiscard]] virtual std::vector<double> getMassFractionVector() const = 0;
/**
* @brief Get the number fraction as a vector.
* @return A vector of number fractions for all species.
*/
[[nodiscard]] virtual std::vector<double> getNumberFractionVector() const = 0;
/**
* @brief Get the molar abundance as a vector.
* @return A vector of molar abundances for all species.
*/
[[nodiscard]] virtual std::vector<double> getMolarAbundanceVector() const = 0;
/**
* @brief Get the index of a species by symbol.
* @param symbol The chemical symbol.
* @return The index of the species.
*/
[[nodiscard]] virtual size_t getSpeciesIndex(const std::string& symbol) const = 0;
/**
* @brief Get the index of a species.
* @param species The atomic species.
* @return The index of the species.
*/
[[nodiscard]] virtual size_t getSpeciesIndex(const fourdst::atomic::Species& species) const = 0;
/**
* @brief Get the species at a given index.
* @param index The index of the species.
* @return The atomic species at the specified index.
*/
[[nodiscard]] virtual fourdst::atomic::Species getSpeciesAtIndex(size_t index) const = 0;
};

31
src/composition/include/fourdst/composition/elements.h
View File

@@ -4,7 +4,27 @@
#include <cstdint>
#include <string>
/**
* @file elements.h
* @brief Provides mappings between atomic numbers and element symbols for the periodic table.
*
* This header defines lookup tables for converting between atomic numbers (Z) and their corresponding
* chemical element symbols, and vice versa. These maps are useful for parsing, displaying, or validating
* chemical compositions in scientific applications.
*/
namespace fourdst::atomic {
/**
* @brief Maps atomic number (Z) to element symbol.
*
* This map allows lookup of the chemical symbol for a given atomic number.
*
* @par Example
* @code
* std::string symbol = fourdst::atomic::element_symbol_map.at(8); // symbol == "O"
* @endcode
*/
static const std::unordered_map<uint8_t, std::string> element_symbol_map = {
{1u, "H"},
{2u, "He"},
@@ -125,6 +145,17 @@ namespace fourdst::atomic {
{117u, "Ts"},
{118u, "Og"}
};
/**
* @brief Maps element symbol to atomic number (Z).
*
* This map allows lookup of the atomic number for a given chemical symbol.
*
* @par Example
* @code
* uint8_t z = fourdst::atomic::symbol_element_map.at("Fe"); // z == 26
* @endcode
*/
static const std::unordered_map<std::string, uint8_t> symbol_element_map = {
{"H", 1u},
{"He", 2u},

25
src/composition/include/fourdst/composition/species.h
View File

@@ -3570,6 +3570,12 @@ namespace fourdst::atomic {
static const Species Og_295("Og-295", "Og", 59, 177, 118, 295, 7076.0, "B-", std::numeric_limits<double>::quiet_NaN(), 680.0, "", "~100", 295.216178, 703.0);
// Create a map from species name (e.g., "H-1") to a pointer to the species object.
/**
* @brief Map of species names to their corresponding Species objects.
*
* @details This unordered map allows for quick lookup of species by their string identifiers. All Species are stored
* as constant references to ensure immutability and efficient access.
*/
static const std::unordered_map<std::string, const Species&> species = {
{"n-1", n_1},
{"H-1", H_1},
@@ -7130,14 +7136,25 @@ namespace fourdst::atomic {
{"Og-294", Og_294},
{"Og-295", Og_295},
};
// Create an enum to represent possible error types when looking up species.
/**
* @brief Error types for species lookup.
* @par Types
* - ELEMENT_SYMBOL_NOT_FOUND: The element symbol corresponding to the provided atomic number (Z) was not found.
* - SPECIES_SYMBOL_NOT_FOUND: The species symbol constructed from the element symbol and mass was not found.
*/
enum class SpeciesErrorType {
ELEMENT_SYMBOL_NOT_FOUND,
SPECIES_SYMBOL_NOT_FOUND
};
// Function to look up a species by its atomic number (Z) and mass number (A).
/**
* @breif Convert atomic mass (A) and atomic number (Z) to a Species object.
* @param a The atomic mass number.
* @param z the atomic number.
* @return A std::expected containing the Species object if found, or a SpeciesErrorType error if not found.
* @note This function is noexcept and will not throw exceptions. The only possible exception is a bad_alloc from std::string operations and this is unrecoverable.
*/
inline std::expected<Species, SpeciesErrorType> az_to_species(const int a, const int z) noexcept {
if (!element_symbol_map.contains(static_cast<uint8_t>(z))) {
return std::unexpected(SpeciesErrorType::ELEMENT_SYMBOL_NOT_FOUND);