293 lines
24 KiB
TeX
293 lines
24 KiB
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. |