libcomposition/docs/latex/index.tex

\chapter{libcomposition\+: A Modern C++ Library for Chemical Compositions}
\hypertarget{index}{}\label{index}\index{libcomposition: A Modern C++ Library for Chemical Compositions@{libcomposition: A Modern C++ Library for Chemical Compositions}}
\hypertarget{index_intro_sec}{}\doxysection{\texorpdfstring{Introduction}{Introduction}}\label{index_intro_sec}
{\ttfamily libcomposition} is a modern, C++23 library, for the creation, manipulation, and analysis of astrophysical chemical compositions. It provides a robust and type‑safe interface for assembling a set of isotopes together with their molar abundances and for deriving commonly used bulk properties (mass fractions, number fractions, canonical X/\+Y/Z, mean particle mass, and electron abundance). {\ttfamily libcomposition} is designed to be tighly integrated into SERiF and related projects such as Grid\+Fire.\hypertarget{index_autotoc_md10}{}\doxysubsubsection{\texorpdfstring{Key Features}{Key Features}}\label{index_autotoc_md10}

\begin{DoxyItemize}
\item {\bfseries{Type–\+Safe Species Representation}}\+: Strongly typed isotopes ({\ttfamily \doxylink{structfourdst_1_1atomic_1_1Species}{fourdst\+::atomic\+::\+Species}}) generated from evaluated nuclear data (AME2020 / NUBASE2020).
\item {\bfseries{Molar Abundance Core}}\+: Stores absolute molar abundances and derives all secondary quantities (mass / number fractions, mean particle mass, electron abundance) on demand, with internal caching.
\item {\bfseries{Canonical Composition Support}}\+: Direct computation of canonical (X\+: Hydrogen, Y\+: Helium, Z\+: Metals) mass fractions via {\ttfamily get\+Canonical\+Composition()}.
\item {\bfseries{Convenience Construction}}\+: Helper utilities for constructing compositions from a vector or set of mass fractions ({\ttfamily build\+Composition\+From\+Mass\+Fractions}).
\item {\bfseries{Deterministic Ordering}}\+: Species are always stored and iterated lightest→heaviest (ordering defined by atomic mass) enabling uniform vector interfaces.
\item {\bfseries{Clear Exception Hierarchy}}\+: Explicit error signaling for invalid symbols, unregistered species, and inconsistent input data.
\item {\bfseries{Meson + pkg-\/config Integration}}\+: Simple build, install, and consumption in external projects.
\end{DoxyItemize}

\DoxyHorRuler{0}
\hypertarget{index_install_sec}{}\doxysection{\texorpdfstring{Installation}{Installation}}\label{index_install_sec}
{\ttfamily libcomposition} uses the Meson build system. A C++23 compatible compiler is required.\hypertarget{index_autotoc_md12}{}\doxysubsubsection{\texorpdfstring{Build Steps}{Build Steps}}\label{index_autotoc_md12}
{\bfseries{Setup the build directory\+:}}

The first step is to use meson to set up an out of source build. Note that this means that you can have multiple builds configured and cleanly separated!


\begin{DoxyCode}{0}
\DoxyCodeLine{meson\ setup\ builddir}

\end{DoxyCode}


{\bfseries{Compile the library\+:}}

meson by default uses ninja to compile so it should be very fast; however, gcc is very slow when compiling the species database so that might take some time (clang tends to be very fast for this).


\begin{DoxyCode}{0}
\DoxyCodeLine{meson\ compile\ -\/C\ builddir}

\end{DoxyCode}


{\bfseries{Install the library\+:}}

This will also install a pkg-\/config file!


\begin{DoxyCode}{0}
\DoxyCodeLine{sudo\ meson\ install\ -\/C\ builddir}

\end{DoxyCode}
\hypertarget{index_autotoc_md13}{}\doxysubsubsection{\texorpdfstring{Build Options}{Build Options}}\label{index_autotoc_md13}
You can enable the generation of a {\ttfamily pkg-\/config} file during the setup step, which simplifies linking the library in other projects. By default this is true; it can be useful to disable this when using some build system orchestrator (such as meson-\/python).


\begin{DoxyCode}{0}
\DoxyCodeLine{\#\ Enable\ pkg-\/config\ file\ generation}
\DoxyCodeLine{meson\ setup\ builddir\ -\/Dpkg-\/config=true}

\end{DoxyCode}


\DoxyHorRuler{0}
\hypertarget{index_usage_sec}{}\doxysection{\texorpdfstring{Usage}{Usage}}\label{index_usage_sec}
Below are focused examples illustrating the current API. All examples assume headers are available via pkg-\/config or your include path.\hypertarget{index_autotoc_md15}{}\doxyparagraph{\texorpdfstring{1. Constructing a Composition from Symbols}{1. Constructing a Composition from Symbols}}\label{index_autotoc_md15}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ <iostream>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ "{}\mbox{\hyperlink{composition_8h}{fourdst/composition/composition.h}}"{}}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ main()\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{using\ namespace\ }\mbox{\hyperlink{namespacefourdst_1_1composition}{fourdst::composition}};}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Register\ symbols\ upon\ construction\ (no\ molar\ abundances\ yet\ -\/>\ default\ 0.0)}}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{classfourdst_1_1composition_1_1Composition}{Composition}}\ comp(\{\textcolor{stringliteral}{"{}H-\/1"{}},\ \textcolor{stringliteral}{"{}He-\/4"{}},\ \textcolor{stringliteral}{"{}C-\/12"{}}\});}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Set\ molar\ abundances\ (absolute\ counts;\ they\ need\ not\ sum\ to\ 1.0)}}
\DoxyCodeLine{\ \ \ \ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a262d7133035d4e6f45daa81827abf5e7}{setMolarAbundance}}(\textcolor{stringliteral}{"{}H-\/1"{}},\ 10.0);}
\DoxyCodeLine{\ \ \ \ comp.setMolarAbundance(\textcolor{stringliteral}{"{}He-\/4"{}},\ 3.0);}
\DoxyCodeLine{\ \ \ \ comp.setMolarAbundance(\textcolor{stringliteral}{"{}C-\/12"{}},\ 0.25);}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Query\ derived\ properties}}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{double}\ x\_h1\ =\ comp.getMassFraction(\textcolor{stringliteral}{"{}H-\/1"{}});}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{double}\ y\_he4\ =\ comp.getNumberFraction(\textcolor{stringliteral}{"{}He-\/4"{}});}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ canon\ =\ comp.getCanonicalComposition();\ \textcolor{comment}{//\ X,\ Y,\ Z\ mass\ fractions}}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ std::cout\ <<\ \textcolor{stringliteral}{"{}H-\/1\ mass\ fraction:\ "{}}\ <<\ x\_h1\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};}
\DoxyCodeLine{\ \ \ \ std::cout\ <<\ \textcolor{stringliteral}{"{}He-\/4\ number\ fraction:\ "{}}\ <<\ y\_he4\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};}
\DoxyCodeLine{\ \ \ \ std::cout\ <<\ canon\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};\ \textcolor{comment}{//\ <CanonicalComposition:\ X=...,\ Y=...,\ Z=...>}}
\DoxyCodeLine{\}}

\end{DoxyCode}
\hypertarget{index_autotoc_md16}{}\doxyparagraph{\texorpdfstring{2. Constructing from Strongly Typed Species}{2. Constructing from Strongly Typed Species}}\label{index_autotoc_md16}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ <iostream>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ "{}\mbox{\hyperlink{composition_8h}{fourdst/composition/composition.h}}"{}}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ "{}\mbox{\hyperlink{species_8h}{fourdst/atomic/species.h}}"{}}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ main()\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{using\ namespace\ }\mbox{\hyperlink{namespacefourdst_1_1composition}{fourdst::composition}};}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{using\ namespace\ }\mbox{\hyperlink{namespacefourdst_1_1atomic}{fourdst::atomic}};}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Build\ directly\ from\ species\ constants}}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{classfourdst_1_1composition_1_1Composition}{Composition}}\ comp(std::vector<Species>\{H\_1,\ He\_4,\ O\_16\});}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a262d7133035d4e6f45daa81827abf5e7}{setMolarAbundance}}(H\_1,\ 5.0);}
\DoxyCodeLine{\ \ \ \ comp.setMolarAbundance(He\_4,\ 2.5);}
\DoxyCodeLine{\ \ \ \ comp.setMolarAbundance(O\_16,\ 0.1);}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ std::cout\ <<\ \textcolor{stringliteral}{"{}Mean\ particle\ mass:\ "{}}\ <<\ comp.getMeanParticleMass()\ <<\ \textcolor{stringliteral}{"{}\ g/mol\(\backslash\)n"{}};}
\DoxyCodeLine{\ \ \ \ std::cout\ <<\ \textcolor{stringliteral}{"{}Electron\ abundance\ (Ye):\ "{}}\ <<\ comp.getElectronAbundance()\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};}
\DoxyCodeLine{\}}

\end{DoxyCode}
\hypertarget{index_autotoc_md17}{}\doxyparagraph{\texorpdfstring{3. Building from Mass Fractions (\+Helper Utility)}{3. Building from Mass Fractions (Helper Utility)}}\label{index_autotoc_md17}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ <iostream>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ "{}\mbox{\hyperlink{utils_8h}{fourdst/composition/utils.h}}"{}}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ main()\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{using\ namespace\ }\mbox{\hyperlink{namespacefourdst_1_1composition}{fourdst::composition}};}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ std::vector<std::string>\ symbols\ =\ \{\textcolor{stringliteral}{"{}H-\/1"{}},\ \textcolor{stringliteral}{"{}He-\/4"{}},\ \textcolor{stringliteral}{"{}C-\/12"{}}\};}
\DoxyCodeLine{\ \ \ \ std::vector<double>\ mf\ \ \ \ \ \ \ =\ \{0.70,\ 0.28,\ 0.02\};\ \textcolor{comment}{//\ Must\ sum\ to\ \string~1\ within\ tolerance}}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{classfourdst_1_1composition_1_1Composition}{Composition}}\ comp\ =\ \mbox{\hyperlink{namespacefourdst_1_1composition_aa90b1ef07d607c0c829bedccf381cf54}{buildCompositionFromMassFractions}}(symbols,\ mf);}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ canon\ =\ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_aac5b214a3d1278e127422224cb9cee50}{getCanonicalComposition}}();}
\DoxyCodeLine{\ \ \ \ std::cout\ <<\ canon\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};}
\DoxyCodeLine{\}}

\end{DoxyCode}
\hypertarget{index_autotoc_md18}{}\doxyparagraph{\texorpdfstring{4. Iterating and Sorted Vector Interfaces}{4. Iterating and Sorted Vector Interfaces}}\label{index_autotoc_md18}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ <iostream>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ "{}\mbox{\hyperlink{composition_8h}{fourdst/composition/composition.h}}"{}}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ main()\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{using\ namespace\ }\mbox{\hyperlink{namespacefourdst_1_1composition}{fourdst::composition}};}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{classfourdst_1_1composition_1_1Composition}{Composition}}\ comp(\{\textcolor{stringliteral}{"{}H-\/1"{}},\ \textcolor{stringliteral}{"{}C-\/12"{}},\ \textcolor{stringliteral}{"{}He-\/4"{}}\});\ \textcolor{comment}{//\ Internally\ sorted\ by\ mass\ (H\ <\ He\ <\ C)}}
\DoxyCodeLine{\ \ \ \ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a262d7133035d4e6f45daa81827abf5e7}{setMolarAbundance}}(\{\textcolor{stringliteral}{"{}H-\/1"{}},\ \textcolor{stringliteral}{"{}He-\/4"{}},\ \textcolor{stringliteral}{"{}C-\/12"{}}\},\ \{10.0,\ 3.0,\ 0.25\});}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Ordered\ iteration\ (lightest\ -\/>\ heaviest)}}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{for}\ (\textcolor{keyword}{const}\ \textcolor{keyword}{auto}\ \&[sp,\ y]\ :\ comp)\ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ std::cout\ <<\ sp\ <<\ \textcolor{stringliteral}{"{}:\ molar\ =\ "{}}\ <<\ y\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};}
\DoxyCodeLine{\ \ \ \ \}}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Vector\ access\ (index\ corresponds\ to\ ordering\ by\ atomic\ mass)}}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ molarVec\ =\ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_abcb391f5fca2b636127e48e681e4c3ee}{getMolarAbundanceVector}}();}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{auto}\ massVec\ \ =\ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_af4f44aaf8b7e0d63872a70b5e2131369}{getMassFractionVector}}();}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{size\_t}\ idx\_he4\ =\ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a0d94f62402bb90b5d12679faeaa8c5d7}{getSpeciesIndex}}(\textcolor{stringliteral}{"{}He-\/4"{}});}
\DoxyCodeLine{\ \ \ \ std::cout\ <<\ \textcolor{stringliteral}{"{}He-\/4\ index:\ "{}}\ <<\ idx\_he4\ <<\ \textcolor{stringliteral}{"{},\ molar\ abundance\ at\ index:\ "{}}\ <<\ molarVec[idx\_he4]\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};}
\DoxyCodeLine{\}}

\end{DoxyCode}
\hypertarget{index_autotoc_md19}{}\doxyparagraph{\texorpdfstring{5. Accessing Specific Derived Quantities}{5. Accessing Specific Derived Quantities}}\label{index_autotoc_md19}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{//\ Assume\ 'comp'\ is\ already\ populated.}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{double}\ mf\_c12\ \ \ =\ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a9ea2b673341fdc67afeb0f0517a54c8c}{getMassFraction}}(\textcolor{stringliteral}{"{}C-\/12"{}});}
\DoxyCodeLine{\textcolor{keywordtype}{double}\ nf\_c12\ \ \ =\ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a34f71d4d8f0297c576fd62fabd490305}{getNumberFraction}}(\textcolor{stringliteral}{"{}C-\/12"{}});}
\DoxyCodeLine{\textcolor{keywordtype}{double}\ mol\_c12\ \ =\ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_add67a92d73e3a57a2bbdb52bc9ca3bfe}{getMolarAbundance}}(\textcolor{stringliteral}{"{}C-\/12"{}});}
\DoxyCodeLine{\textcolor{keywordtype}{double}\ meanA\ \ \ \ =\ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_afbbb5e51ad5ae5c0fa6bc0094195aecd}{getMeanParticleMass}}();}
\DoxyCodeLine{\textcolor{keywordtype}{double}\ Ye\ \ \ \ \ \ \ =\ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a90fc71d1fe03017ee4c7a1cac69d24fb}{getElectronAbundance}}();}
\DoxyCodeLine{\textcolor{keyword}{auto}\ \ \ canon\ \ \ \ =\ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_aac5b214a3d1278e127422224cb9cee50}{getCanonicalComposition}}();}

\end{DoxyCode}
\hypertarget{index_autotoc_md20}{}\doxyparagraph{\texorpdfstring{6. Exception Handling Examples}{6. Exception Handling Examples}}\label{index_autotoc_md20}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ <iostream>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ "{}\mbox{\hyperlink{composition_8h}{fourdst/composition/composition.h}}"{}}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include\ "{}\mbox{\hyperlink{exceptions__composition_8h}{fourdst/composition/exceptions/exceptions\_composition.h}}"{}}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int}\ main()\ \{}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{using\ namespace\ }\mbox{\hyperlink{namespacefourdst_1_1composition}{fourdst::composition}};}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{using\ namespace\ }\mbox{\hyperlink{namespacefourdst_1_1composition_1_1exceptions}{fourdst::composition::exceptions}};}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{classfourdst_1_1composition_1_1Composition}{Composition}}\ comp;}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{try}\ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{//\ Unknown\ symbol\ (not\ in\ species\ database)}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a3ab4dcda0bfd1a35b169bcc57fe66725}{registerSymbol}}(\textcolor{stringliteral}{"{}Xx-\/999"{}});}
\DoxyCodeLine{\ \ \ \ \}\ \textcolor{keywordflow}{catch}\ (\textcolor{keyword}{const}\ \mbox{\hyperlink{classfourdst_1_1composition_1_1exceptions_1_1UnknownSymbolError}{UnknownSymbolError}}\ \&e)\ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ std::cerr\ <<\ \textcolor{stringliteral}{"{}Caught\ UnknownSymbolError:\ "{}}\ <<\ e.\mbox{\hyperlink{classfourdst_1_1composition_1_1exceptions_1_1SpeciesError_af0c63f7e05d0c65157b960c654d09b67}{what}}()\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};}
\DoxyCodeLine{\ \ \ \ \}}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a3ab4dcda0bfd1a35b169bcc57fe66725}{registerSymbol}}(\textcolor{stringliteral}{"{}H-\/1"{}});}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{try}\ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{//\ Unregistered\ symbol\ used\ in\ a\ setter}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a262d7133035d4e6f45daa81827abf5e7}{setMolarAbundance}}(\textcolor{stringliteral}{"{}He-\/4"{}},\ 1.0);\ \textcolor{comment}{//\ He-\/4\ not\ registered\ yet}}
\DoxyCodeLine{\ \ \ \ \}\ \textcolor{keywordflow}{catch}\ (\textcolor{keyword}{const}\ \mbox{\hyperlink{classfourdst_1_1composition_1_1exceptions_1_1UnregisteredSymbolError}{UnregisteredSymbolError}}\ \&e)\ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ std::cerr\ <<\ \textcolor{stringliteral}{"{}Caught\ UnregisteredSymbolError:\ "{}}\ <<\ e.\mbox{\hyperlink{classfourdst_1_1composition_1_1exceptions_1_1CompositionError_ae44ceddb19da8a8cda7ee150b6826d08}{what}}()\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};}
\DoxyCodeLine{\ \ \ \ \}}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a3ab4dcda0bfd1a35b169bcc57fe66725}{registerSymbol}}(\textcolor{stringliteral}{"{}He-\/4"{}});}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{try}\ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ comp.\mbox{\hyperlink{classfourdst_1_1composition_1_1Composition_a262d7133035d4e6f45daa81827abf5e7}{setMolarAbundance}}(\textcolor{stringliteral}{"{}H-\/1"{}},\ -\/3.0);}
\DoxyCodeLine{\ \ \ \ \}\ \textcolor{keywordflow}{catch}\ (\textcolor{keyword}{const}\ \mbox{\hyperlink{classfourdst_1_1composition_1_1exceptions_1_1InvalidCompositionError}{InvalidCompositionError}}\ \&e)\ \{\ }
\DoxyCodeLine{\ \ \ \ \ \ \ \ std::cerr\ <<\ \textcolor{stringliteral}{"{}Caught\ InvalidCompositionError:\ "{}}\ <<\ e.\mbox{\hyperlink{classfourdst_1_1composition_1_1exceptions_1_1CompositionError_ae44ceddb19da8a8cda7ee150b6826d08}{what}}()\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};}
\DoxyCodeLine{\ \ \ \ \}}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Mass\ fraction\ construction\ validation}}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{try}\ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \mbox{\hyperlink{classfourdst_1_1composition_1_1Composition}{Composition}}\ bad\ =\ \mbox{\hyperlink{namespacefourdst_1_1composition_aa90b1ef07d607c0c829bedccf381cf54}{buildCompositionFromMassFractions}}(\{\textcolor{stringliteral}{"{}H-\/1"{}},\ \textcolor{stringliteral}{"{}He-\/4"{}}\},\ \{0.6,\ 0.5\});\ \textcolor{comment}{//\ sums\ to\ 1.1}}
\DoxyCodeLine{\ \ \ \ \}\ \textcolor{keywordflow}{catch}\ (\textcolor{keyword}{const}\ \mbox{\hyperlink{classfourdst_1_1composition_1_1exceptions_1_1InvalidCompositionError}{InvalidCompositionError}}\ \&e)\ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ std::cerr\ <<\ \textcolor{stringliteral}{"{}Caught\ InvalidCompositionError:\ "{}}\ <<\ e.\mbox{\hyperlink{classfourdst_1_1composition_1_1exceptions_1_1CompositionError_ae44ceddb19da8a8cda7ee150b6826d08}{what}}()\ <<\ \textcolor{stringliteral}{"{}\(\backslash\)n"{}};}
\DoxyCodeLine{\ \ \ \ \}}
\DoxyCodeLine{\}}

\end{DoxyCode}


\DoxyHorRuler{0}
\hypertarget{index_exceptions_sec}{}\doxysection{\texorpdfstring{Possible Exception States}{Possible Exception States}}\label{index_exceptions_sec}
The library surfaces errors through a focused hierarchy in {\ttfamily \doxylink{namespacefourdst_1_1composition_1_1exceptions}{fourdst\+::composition\+::exceptions}}\+:

\tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{2}{|X[-1]}|}
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Exception Type   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ When It Occurs    }\\\cline{1-2}
\endfirsthead
\hline
\endfoot
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Exception Type   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ When It Occurs    }\\\cline{1-2}
\endhead
{\ttfamily Unknown\+Symbol\+Error}   &A string symbol does not correspond to any known isotope in the compiled species database.    \\\cline{1-2}
{\ttfamily Unregistered\+Symbol\+Error}   &A valid species/symbol is used before being registered with a Composition instance.    \\\cline{1-2}
{\ttfamily Invalid\+Composition\+Error}   &Construction from mass fractions fails validation (sum deviates from unity beyond tolerance) or canonical (X+\+Y+Z) check fails.    \\\cline{1-2}
{\ttfamily Composition\+Error}   &Base class; may be thrown for generic composition-\/level issues (e.\+g. negative abundances via the documented {\ttfamily Invalid\+Abundance\+Error} contract).   \\\cline{1-2}
\end{longtabu}


Recommended patterns\+:
\begin{DoxyItemize}
\item Validate externally provided symbol lists before calling bulk registration.
\item Use species‑based overloads (strongly typed) where possible for slightly lower overhead (no symbol resolution).
\item Wrap construction from mass fractions in a try/catch to surface normalization issues early.
\end{DoxyItemize}

\DoxyHorRuler{0}
\hypertarget{index_api_sec}{}\doxysection{\texorpdfstring{Linking and Integration}{Linking and Integration}}\label{index_api_sec}
\hypertarget{index_autotoc_md23}{}\doxysubsubsection{\texorpdfstring{Linking with pkg-\/config}{Linking with pkg-config}}\label{index_autotoc_md23}
If you installed {\ttfamily libcomposition} with the {\ttfamily pkg-\/config} option enabled, you can get the necessary compiler and linker flags easily\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\#\ Get\ compiler\ flags\ (include\ paths)}
\DoxyCodeLine{pkg-\/config\ -\/-\/cflags\ fourdst\_composition}
\DoxyCodeLine{}
\DoxyCodeLine{\#\ Get\ linker\ flags\ (library\ paths\ and\ names)}
\DoxyCodeLine{pkg-\/config\ -\/-\/libs\ fourdst\_composition}

\end{DoxyCode}


{\bfseries{Example compilation command\+:}} 
\begin{DoxyCode}{0}
\DoxyCodeLine{g++\ my\_app.cpp\ \$(pkg-\/config\ -\/-\/cflags\ -\/-\/libs\ fourdst\_composition)\ -\/o\ my\_app}

\end{DoxyCode}


\DoxyHorRuler{0}
\hypertarget{index_api_ref_sec}{}\doxysection{\texorpdfstring{API Reference}{API Reference}}\label{index_api_ref_sec}
For a complete list of all classes, methods, and functions, see the {\bfseries{Namespaces}} and {\bfseries{Classes}} sections of this generated documentation.


\begin{DoxyItemize}
\item Namespace overview\+: {\ttfamily \doxylink{namespacefourdst_1_1composition}{fourdst\+::composition}}, {\ttfamily \doxylink{namespacefourdst_1_1atomic}{fourdst\+::atomic}}
\item Core classes\+: {\ttfamily \doxylink{classfourdst_1_1composition_1_1Composition}{fourdst\+::composition\+::\+Composition}}, {\ttfamily \doxylink{classfourdst_1_1composition_1_1CompositionAbstract}{fourdst\+::composition\+::\+Composition\+Abstract}}
\item Helper utilities\+: {\ttfamily build\+Composition\+From\+Mass\+Fractions}
\item Exception hierarchy\+: {\ttfamily \doxylink{namespacefourdst_1_1composition_1_1exceptions}{fourdst\+::composition\+::exceptions}}
\end{DoxyItemize}

\DoxyHorRuler{0}
\hypertarget{index_test_sec}{}\doxysection{\texorpdfstring{Testing Overview}{Testing Overview}}\label{index_test_sec}
The test suite (Google\+Test) exercises\+:
\begin{DoxyItemize}
\item Species database integrity (selected property spot checks).
\item Registration and abundance setting (symbols vs species overloads).
\item Mass fraction utility construction and validation tolerances.
\item Canonical composition correctness (X + Y + Z ≈ 1.\+0).
\item Vector interface ordering and index lookup consistency.
\item Exception pathways for unknown/unregistered symbols and invalid compositions.
\end{DoxyItemize}

Use tolerances (e.\+g. 1e-\/12–1e-\/14) when comparing floating‑point derived quantities in custom tests.