365 lines
37 KiB
HTML
365 lines
37 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
||
<meta name="generator" content="Doxygen 1.13.2"/>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
<title>fourdst::libcomposition: libcomposition: A Modern C++ Library for Chemical Compositions</title>
|
||
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="jquery.js"></script>
|
||
<script type="text/javascript" src="dynsections.js"></script>
|
||
<script type="text/javascript" src="clipboard.js"></script>
|
||
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="navtreedata.js"></script>
|
||
<script type="text/javascript" src="navtree.js"></script>
|
||
<script type="text/javascript" src="resize.js"></script>
|
||
<script type="text/javascript" src="cookie.js"></script>
|
||
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="search/searchdata.js"></script>
|
||
<script type="text/javascript" src="search/search.js"></script>
|
||
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
|
||
<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
|
||
</head>
|
||
<body>
|
||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
<div id="titlearea">
|
||
<table cellspacing="0" cellpadding="0">
|
||
<tbody>
|
||
<tr id="projectrow">
|
||
<td id="projectalign">
|
||
<div id="projectname">fourdst::libcomposition<span id="projectnumber"> v2.0.1</span>
|
||
</div>
|
||
<div id="projectbrief">Robust atomic species information library</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<!-- end header part -->
|
||
<!-- Generated by Doxygen 1.13.2 -->
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
||
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
||
/* @license-end */
|
||
</script>
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
||
$(function() { codefold.init(0); });
|
||
/* @license-end */
|
||
</script>
|
||
<script type="text/javascript" src="menudata.js"></script>
|
||
<script type="text/javascript" src="menu.js"></script>
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
||
$(function() {
|
||
initMenu('',true,false,'search.php','Search',true);
|
||
$(function() { init_search(); });
|
||
});
|
||
/* @license-end */
|
||
</script>
|
||
<div id="main-nav"></div>
|
||
</div><!-- top -->
|
||
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
||
<div id="nav-tree">
|
||
<div id="nav-tree-contents">
|
||
<div id="nav-sync" class="sync"></div>
|
||
</div>
|
||
</div>
|
||
<div id="splitbar" style="-moz-user-select:none;"
|
||
class="ui-resizable-handle">
|
||
</div>
|
||
</div>
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
||
$(function(){initNavTree('index.html',''); initResizable(true); });
|
||
/* @license-end */
|
||
</script>
|
||
<div id="doc-content">
|
||
<!-- window showing the filter options -->
|
||
<div id="MSearchSelectWindow"
|
||
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||
</div>
|
||
|
||
<!-- iframe showing the search results (closed by default) -->
|
||
<div id="MSearchResultsWindow">
|
||
<div id="MSearchResults">
|
||
<div class="SRPage">
|
||
<div id="SRIndex">
|
||
<div id="SRResults"></div>
|
||
<div class="SRStatus" id="Loading">Loading...</div>
|
||
<div class="SRStatus" id="Searching">Searching...</div>
|
||
<div class="SRStatus" id="NoMatches">No Matches</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div><div class="header">
|
||
<div class="headertitle"><div class="title">libcomposition: A Modern C++ Library for Chemical Compositions </div></div>
|
||
</div><!--header-->
|
||
<div class="contents">
|
||
<div class="textblock"><h1><a class="anchor" id="intro_sec"></a>
|
||
Introduction</h1>
|
||
<p><code>libcomposition</code> 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). <code>libcomposition</code> is designed to be tighly integrated into SERiF and related projects such as GridFire.</p>
|
||
<h3><a class="anchor" id="autotoc_md10"></a>
|
||
Key Features</h3>
|
||
<ul>
|
||
<li><b>Type–Safe Species Representation</b>: Strongly typed isotopes (<code><a class="el" href="structfourdst_1_1atomic_1_1_species.html" title="Represents an atomic species (isotope) with its fundamental physical properties.">fourdst::atomic::Species</a></code>) generated from evaluated nuclear data (AME2020 / NUBASE2020).</li>
|
||
<li><b>Molar Abundance Core</b>: Stores absolute molar abundances and derives all secondary quantities (mass / number fractions, mean particle mass, electron abundance) on demand, with internal caching.</li>
|
||
<li><b>Canonical Composition Support</b>: Direct computation of canonical (X: Hydrogen, Y: Helium, Z: Metals) mass fractions via <code>getCanonicalComposition()</code>.</li>
|
||
<li><b>Convenience Construction</b>: Helper utilities for constructing compositions from a vector or set of mass fractions (<code>buildCompositionFromMassFractions</code>).</li>
|
||
<li><b>Deterministic Ordering</b>: Species are always stored and iterated lightest→heaviest (ordering defined by atomic mass) enabling uniform vector interfaces.</li>
|
||
<li><b>Clear Exception Hierarchy</b>: Explicit error signaling for invalid symbols, unregistered species, and inconsistent input data.</li>
|
||
<li><b>Meson + pkg-config Integration</b>: Simple build, install, and consumption in external projects.</li>
|
||
</ul>
|
||
<hr />
|
||
<h1><a class="anchor" id="install_sec"></a>
|
||
Installation</h1>
|
||
<p><code>libcomposition</code> uses the Meson build system. A C++23 compatible compiler is required.</p>
|
||
<h3><a class="anchor" id="autotoc_md12"></a>
|
||
Build Steps</h3>
|
||
<p><b>Setup the build directory:</b></p>
|
||
<p>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!</p>
|
||
<div class="fragment"><div class="line">meson setup builddir</div>
|
||
</div><!-- fragment --><p><b>Compile the library:</b></p>
|
||
<p>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).</p>
|
||
<div class="fragment"><div class="line">meson compile -C builddir</div>
|
||
</div><!-- fragment --><p><b>Install the library:</b></p>
|
||
<p>This will also install a pkg-config file!</p>
|
||
<div class="fragment"><div class="line">sudo meson install -C builddir</div>
|
||
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md13"></a>
|
||
Build Options</h3>
|
||
<p>You can enable the generation of a <code>pkg-config</code> 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).</p>
|
||
<div class="fragment"><div class="line"># Enable pkg-config file generation</div>
|
||
<div class="line">meson setup builddir -Dpkg-config=true</div>
|
||
</div><!-- fragment --><hr />
|
||
<h1><a class="anchor" id="usage_sec"></a>
|
||
Usage</h1>
|
||
<p>Below are focused examples illustrating the current API. All examples assume headers are available via pkg-config or your include path.</p>
|
||
<h4><a class="anchor" id="autotoc_md15"></a>
|
||
1. Constructing a Composition from Symbols</h4>
|
||
<div class="fragment"><div class="line"><span class="preprocessor">#include <iostream></span></div>
|
||
<div class="line"><span class="preprocessor">#include "<a class="code" href="composition_8h.html">fourdst/composition/composition.h</a>"</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="keywordtype">int</span> main() {</div>
|
||
<div class="line"> <span class="keyword">using namespace </span><a class="code hl_namespace" href="namespacefourdst_1_1composition.html">fourdst::composition</a>;</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="comment">// Register symbols upon construction (no molar abundances yet -> default 0.0)</span></div>
|
||
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">Composition</a> comp({<span class="stringliteral">"H-1"</span>, <span class="stringliteral">"He-4"</span>, <span class="stringliteral">"C-12"</span>});</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="comment">// Set molar abundances (absolute counts; they need not sum to 1.0)</span></div>
|
||
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a262d7133035d4e6f45daa81827abf5e7">setMolarAbundance</a>(<span class="stringliteral">"H-1"</span>, 10.0);</div>
|
||
<div class="line"> comp.setMolarAbundance(<span class="stringliteral">"He-4"</span>, 3.0);</div>
|
||
<div class="line"> comp.setMolarAbundance(<span class="stringliteral">"C-12"</span>, 0.25);</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="comment">// Query derived properties</span></div>
|
||
<div class="line"> <span class="keywordtype">double</span> x_h1 = comp.getMassFraction(<span class="stringliteral">"H-1"</span>);</div>
|
||
<div class="line"> <span class="keywordtype">double</span> y_he4 = comp.getNumberFraction(<span class="stringliteral">"He-4"</span>);</div>
|
||
<div class="line"> <span class="keyword">auto</span> canon = comp.getCanonicalComposition(); <span class="comment">// X, Y, Z mass fractions</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"> std::cout << <span class="stringliteral">"H-1 mass fraction: "</span> << x_h1 << <span class="stringliteral">"\n"</span>;</div>
|
||
<div class="line"> std::cout << <span class="stringliteral">"He-4 number fraction: "</span> << y_he4 << <span class="stringliteral">"\n"</span>;</div>
|
||
<div class="line"> std::cout << canon << <span class="stringliteral">"\n"</span>; <span class="comment">// <CanonicalComposition: X=..., Y=..., Z=...></span></div>
|
||
<div class="line">}</div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html">fourdst::composition::Composition</a></div><div class="ttdoc">Manages a collection of chemical species and their abundances.</div><div class="ttdef"><b>Definition</b> <a href="composition_8h_source.html#l00097">composition.h:97</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_a262d7133035d4e6f45daa81827abf5e7"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#a262d7133035d4e6f45daa81827abf5e7">fourdst::composition::Composition::setMolarAbundance</a></div><div class="ttdeci">void setMolarAbundance(const std::string &symbol, const double &molar_abundance)</div><div class="ttdoc">Sets the molar abundance for a given symbol.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00529">composition.cpp:529</a></div></div>
|
||
<div class="ttc" id="acomposition_8h_html"><div class="ttname"><a href="composition_8h.html">composition.h</a></div></div>
|
||
<div class="ttc" id="anamespacefourdst_1_1composition_html"><div class="ttname"><a href="namespacefourdst_1_1composition.html">fourdst::composition</a></div><div class="ttdoc">Utilities and types for representing and manipulating chemical compositions.</div></div>
|
||
</div><!-- fragment --><h4><a class="anchor" id="autotoc_md16"></a>
|
||
2. Constructing from Strongly Typed Species</h4>
|
||
<div class="fragment"><div class="line"><span class="preprocessor">#include <iostream></span></div>
|
||
<div class="line"><span class="preprocessor">#include "<a class="code" href="composition_8h.html">fourdst/composition/composition.h</a>"</span></div>
|
||
<div class="line"><span class="preprocessor">#include "<a class="code" href="species_8h.html">fourdst/atomic/species.h</a>"</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="keywordtype">int</span> main() {</div>
|
||
<div class="line"> <span class="keyword">using namespace </span><a class="code hl_namespace" href="namespacefourdst_1_1composition.html">fourdst::composition</a>;</div>
|
||
<div class="line"> <span class="keyword">using namespace </span><a class="code hl_namespace" href="namespacefourdst_1_1atomic.html">fourdst::atomic</a>;</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="comment">// Build directly from species constants</span></div>
|
||
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">Composition</a> comp(std::vector<Species>{<a class="code hl_function" href="namespacefourdst_1_1atomic.html#a6766bc834fd656df51bdcf22f7d97877">H_1</a>, <a class="code hl_function" href="namespacefourdst_1_1atomic.html#ab665e3014e2a805624227350699f141a">He_4</a>, <a class="code hl_function" href="namespacefourdst_1_1atomic.html#af2588b97ce949e37c193d6a3e5cb84a0">O_16</a>});</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a262d7133035d4e6f45daa81827abf5e7">setMolarAbundance</a>(<a class="code hl_function" href="namespacefourdst_1_1atomic.html#a6766bc834fd656df51bdcf22f7d97877">H_1</a>, 5.0);</div>
|
||
<div class="line"> comp.setMolarAbundance(<a class="code hl_function" href="namespacefourdst_1_1atomic.html#ab665e3014e2a805624227350699f141a">He_4</a>, 2.5);</div>
|
||
<div class="line"> comp.setMolarAbundance(<a class="code hl_function" href="namespacefourdst_1_1atomic.html#af2588b97ce949e37c193d6a3e5cb84a0">O_16</a>, 0.1);</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> std::cout << <span class="stringliteral">"Mean particle mass: "</span> << comp.getMeanParticleMass() << <span class="stringliteral">" g/mol\n"</span>;</div>
|
||
<div class="line"> std::cout << <span class="stringliteral">"Electron abundance (Ye): "</span> << comp.getElectronAbundance() << <span class="stringliteral">"\n"</span>;</div>
|
||
<div class="line">}</div>
|
||
<div class="ttc" id="anamespacefourdst_1_1atomic_html"><div class="ttname"><a href="namespacefourdst_1_1atomic.html">fourdst::atomic</a></div><div class="ttdoc">Contains canonical information about atomic species and elements used by 4D-STAR.</div></div>
|
||
<div class="ttc" id="anamespacefourdst_1_1atomic_html_a6766bc834fd656df51bdcf22f7d97877"><div class="ttname"><a href="namespacefourdst_1_1atomic.html#a6766bc834fd656df51bdcf22f7d97877">fourdst::atomic::H_1</a></div><div class="ttdeci">static const Species H_1("H-1", "H", -1, 0, 1, 1, 0.0, "B-", std::numeric_limits< double >::quiet_NaN(), std::numeric_limits< double >::infinity(), "/2+*", "S=99.9855 78", 1.007825031898, 1.4e-05)</div></div>
|
||
<div class="ttc" id="anamespacefourdst_1_1atomic_html_ab665e3014e2a805624227350699f141a"><div class="ttname"><a href="namespacefourdst_1_1atomic.html#ab665e3014e2a805624227350699f141a">fourdst::atomic::He_4</a></div><div class="ttdeci">static const Species He_4("He-4", "He", 0, 2, 2, 4, 7073.9156, "B-", -22898.274, std::numeric_limits< double >::infinity(), "+", "S=99.9998 2", 4.00260325413, 0.00016)</div></div>
|
||
<div class="ttc" id="anamespacefourdst_1_1atomic_html_af2588b97ce949e37c193d6a3e5cb84a0"><div class="ttname"><a href="namespacefourdst_1_1atomic.html#af2588b97ce949e37c193d6a3e5cb84a0">fourdst::atomic::O_16</a></div><div class="ttdeci">static const Species O_16("O-16", "O", 0, 8, 8, 16, 7976.2072, "B-", -15412.184, std::numeric_limits< double >::infinity(), "+", "S=99.757 11", 15.99491461926, 0.00032)</div></div>
|
||
<div class="ttc" id="aspecies_8h_html"><div class="ttname"><a href="species_8h.html">species.h</a></div></div>
|
||
</div><!-- fragment --><h4><a class="anchor" id="autotoc_md17"></a>
|
||
3. Building from Mass Fractions (Helper Utility)</h4>
|
||
<div class="fragment"><div class="line"><span class="preprocessor">#include <iostream></span></div>
|
||
<div class="line"><span class="preprocessor">#include "<a class="code" href="utils_8h.html">fourdst/composition/utils.h</a>"</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="keywordtype">int</span> main() {</div>
|
||
<div class="line"> <span class="keyword">using namespace </span><a class="code hl_namespace" href="namespacefourdst_1_1composition.html">fourdst::composition</a>;</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> std::vector<std::string> symbols = {<span class="stringliteral">"H-1"</span>, <span class="stringliteral">"He-4"</span>, <span class="stringliteral">"C-12"</span>};</div>
|
||
<div class="line"> std::vector<double> mf = {0.70, 0.28, 0.02}; <span class="comment">// Must sum to ~1 within tolerance</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">Composition</a> comp = <a class="code hl_function" href="namespacefourdst_1_1composition.html#aa90b1ef07d607c0c829bedccf381cf54">buildCompositionFromMassFractions</a>(symbols, mf);</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="keyword">auto</span> canon = comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#aac5b214a3d1278e127422224cb9cee50">getCanonicalComposition</a>();</div>
|
||
<div class="line"> std::cout << canon << <span class="stringliteral">"\n"</span>;</div>
|
||
<div class="line">}</div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_aac5b214a3d1278e127422224cb9cee50"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#aac5b214a3d1278e127422224cb9cee50">fourdst::composition::Composition::getCanonicalComposition</a></div><div class="ttdeci">CanonicalComposition getCanonicalComposition() const</div><div class="ttdoc">Compute the canonical composition (X, Y, Z) of the composition.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00330">composition.cpp:330</a></div></div>
|
||
<div class="ttc" id="anamespacefourdst_1_1composition_html_aa90b1ef07d607c0c829bedccf381cf54"><div class="ttname"><a href="namespacefourdst_1_1composition.html#aa90b1ef07d607c0c829bedccf381cf54">fourdst::composition::buildCompositionFromMassFractions</a></div><div class="ttdeci">Composition buildCompositionFromMassFractions(const std::vector< std::string > &symbols, const std::vector< double > &massFractions)</div><div class="ttdoc">Build a Composition object from symbols and their corresponding mass fractions.</div><div class="ttdef"><b>Definition</b> <a href="utils_8cpp_source.html#l00074">utils.cpp:74</a></div></div>
|
||
<div class="ttc" id="autils_8h_html"><div class="ttname"><a href="utils_8h.html">utils.h</a></div></div>
|
||
</div><!-- fragment --><h4><a class="anchor" id="autotoc_md18"></a>
|
||
4. Iterating and Sorted Vector Interfaces</h4>
|
||
<div class="fragment"><div class="line"><span class="preprocessor">#include <iostream></span></div>
|
||
<div class="line"><span class="preprocessor">#include "<a class="code" href="composition_8h.html">fourdst/composition/composition.h</a>"</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="keywordtype">int</span> main() {</div>
|
||
<div class="line"> <span class="keyword">using namespace </span><a class="code hl_namespace" href="namespacefourdst_1_1composition.html">fourdst::composition</a>;</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">Composition</a> comp({<span class="stringliteral">"H-1"</span>, <span class="stringliteral">"C-12"</span>, <span class="stringliteral">"He-4"</span>}); <span class="comment">// Internally sorted by mass (H < He < C)</span></div>
|
||
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a262d7133035d4e6f45daa81827abf5e7">setMolarAbundance</a>({<span class="stringliteral">"H-1"</span>, <span class="stringliteral">"He-4"</span>, <span class="stringliteral">"C-12"</span>}, {10.0, 3.0, 0.25});</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="comment">// Ordered iteration (lightest -> heaviest)</span></div>
|
||
<div class="line"> <span class="keywordflow">for</span> (<span class="keyword">const</span> <span class="keyword">auto</span> &[sp, y] : comp) {</div>
|
||
<div class="line"> std::cout << sp << <span class="stringliteral">": molar = "</span> << y << <span class="stringliteral">"\n"</span>;</div>
|
||
<div class="line"> }</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="comment">// Vector access (index corresponds to ordering by atomic mass)</span></div>
|
||
<div class="line"> <span class="keyword">auto</span> molarVec = comp.getMolarAbundanceVector();</div>
|
||
<div class="line"> <span class="keyword">auto</span> massVec = comp.getMassFractionVector();</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="keywordtype">size_t</span> idx_he4 = comp.getSpeciesIndex(<span class="stringliteral">"He-4"</span>);</div>
|
||
<div class="line"> std::cout << <span class="stringliteral">"He-4 index: "</span> << idx_he4 << <span class="stringliteral">", molar abundance at index: "</span> << molarVec[idx_he4] << <span class="stringliteral">"\n"</span>;</div>
|
||
<div class="line">}</div>
|
||
</div><!-- fragment --><h4><a class="anchor" id="autotoc_md19"></a>
|
||
5. Accessing Specific Derived Quantities</h4>
|
||
<div class="fragment"><div class="line"><span class="comment">// Assume 'comp' is already populated.</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="keywordtype">double</span> mf_c12 = comp.getMassFraction(<span class="stringliteral">"C-12"</span>);</div>
|
||
<div class="line"><span class="keywordtype">double</span> nf_c12 = comp.getNumberFraction(<span class="stringliteral">"C-12"</span>);</div>
|
||
<div class="line"><span class="keywordtype">double</span> mol_c12 = comp.getMolarAbundance(<span class="stringliteral">"C-12"</span>);</div>
|
||
<div class="line"><span class="keywordtype">double</span> meanA = comp.getMeanParticleMass();</div>
|
||
<div class="line"><span class="keywordtype">double</span> Ye = comp.getElectronAbundance();</div>
|
||
<div class="line"><span class="keyword">auto</span> canon = comp.getCanonicalComposition();</div>
|
||
</div><!-- fragment --><h4><a class="anchor" id="autotoc_md20"></a>
|
||
6. Exception Handling Examples</h4>
|
||
<div class="fragment"><div class="line"><span class="preprocessor">#include <iostream></span></div>
|
||
<div class="line"><span class="preprocessor">#include "<a class="code" href="composition_8h.html">fourdst/composition/composition.h</a>"</span></div>
|
||
<div class="line"><span class="preprocessor">#include "<a class="code" href="exceptions__composition_8h.html">fourdst/composition/exceptions/exceptions_composition.h</a>"</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="keywordtype">int</span> main() {</div>
|
||
<div class="line"> <span class="keyword">using namespace </span><a class="code hl_namespace" href="namespacefourdst_1_1composition.html">fourdst::composition</a>;</div>
|
||
<div class="line"> <span class="keyword">using namespace </span><a class="code hl_namespace" href="namespacefourdst_1_1composition_1_1exceptions.html">fourdst::composition::exceptions</a>;</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">Composition</a> comp;</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="keywordflow">try</span> {</div>
|
||
<div class="line"> <span class="comment">// Unknown symbol (not in species database)</span></div>
|
||
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a3ab4dcda0bfd1a35b169bcc57fe66725">registerSymbol</a>(<span class="stringliteral">"Xx-999"</span>);</div>
|
||
<div class="line"> } <span class="keywordflow">catch</span> (<span class="keyword">const</span> <a class="code hl_class" href="classfourdst_1_1composition_1_1exceptions_1_1_unknown_symbol_error.html">UnknownSymbolError</a> &e) {</div>
|
||
<div class="line"> std::cerr << <span class="stringliteral">"Caught UnknownSymbolError: "</span> << e.<a class="code hl_function" href="classfourdst_1_1composition_1_1exceptions_1_1_species_error.html#af0c63f7e05d0c65157b960c654d09b67">what</a>() << <span class="stringliteral">"\n"</span>;</div>
|
||
<div class="line"> }</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a3ab4dcda0bfd1a35b169bcc57fe66725">registerSymbol</a>(<span class="stringliteral">"H-1"</span>);</div>
|
||
<div class="line"> <span class="keywordflow">try</span> {</div>
|
||
<div class="line"> <span class="comment">// Unregistered symbol used in a setter</span></div>
|
||
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a262d7133035d4e6f45daa81827abf5e7">setMolarAbundance</a>(<span class="stringliteral">"He-4"</span>, 1.0); <span class="comment">// He-4 not registered yet</span></div>
|
||
<div class="line"> } <span class="keywordflow">catch</span> (<span class="keyword">const</span> <a class="code hl_class" href="classfourdst_1_1composition_1_1exceptions_1_1_unregistered_symbol_error.html">UnregisteredSymbolError</a> &e) {</div>
|
||
<div class="line"> std::cerr << <span class="stringliteral">"Caught UnregisteredSymbolError: "</span> << e.<a class="code hl_function" href="classfourdst_1_1composition_1_1exceptions_1_1_composition_error.html#ae44ceddb19da8a8cda7ee150b6826d08">what</a>() << <span class="stringliteral">"\n"</span>;</div>
|
||
<div class="line"> }</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a3ab4dcda0bfd1a35b169bcc57fe66725">registerSymbol</a>(<span class="stringliteral">"He-4"</span>);</div>
|
||
<div class="line"> <span class="keywordflow">try</span> {</div>
|
||
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a262d7133035d4e6f45daa81827abf5e7">setMolarAbundance</a>(<span class="stringliteral">"H-1"</span>, -3.0);</div>
|
||
<div class="line"> } <span class="keywordflow">catch</span> (<span class="keyword">const</span> <a class="code hl_class" href="classfourdst_1_1composition_1_1exceptions_1_1_invalid_composition_error.html">InvalidCompositionError</a> &e) { </div>
|
||
<div class="line"> std::cerr << <span class="stringliteral">"Caught InvalidCompositionError: "</span> << e.<a class="code hl_function" href="classfourdst_1_1composition_1_1exceptions_1_1_composition_error.html#ae44ceddb19da8a8cda7ee150b6826d08">what</a>() << <span class="stringliteral">"\n"</span>;</div>
|
||
<div class="line"> }</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="comment">// Mass fraction construction validation</span></div>
|
||
<div class="line"> <span class="keywordflow">try</span> {</div>
|
||
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">Composition</a> bad = <a class="code hl_function" href="namespacefourdst_1_1composition.html#aa90b1ef07d607c0c829bedccf381cf54">buildCompositionFromMassFractions</a>({<span class="stringliteral">"H-1"</span>, <span class="stringliteral">"He-4"</span>}, {0.6, 0.5}); <span class="comment">// sums to 1.1</span></div>
|
||
<div class="line"> } <span class="keywordflow">catch</span> (<span class="keyword">const</span> <a class="code hl_class" href="classfourdst_1_1composition_1_1exceptions_1_1_invalid_composition_error.html">InvalidCompositionError</a> &e) {</div>
|
||
<div class="line"> std::cerr << <span class="stringliteral">"Caught InvalidCompositionError: "</span> << e.<a class="code hl_function" href="classfourdst_1_1composition_1_1exceptions_1_1_composition_error.html#ae44ceddb19da8a8cda7ee150b6826d08">what</a>() << <span class="stringliteral">"\n"</span>;</div>
|
||
<div class="line"> }</div>
|
||
<div class="line">}</div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_a3ab4dcda0bfd1a35b169bcc57fe66725"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#a3ab4dcda0bfd1a35b169bcc57fe66725">fourdst::composition::Composition::registerSymbol</a></div><div class="ttdeci">void registerSymbol(const std::string &symbol)</div><div class="ttdoc">Registers a new symbol for inclusion in the composition.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00178">composition.cpp:178</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1exceptions_1_1_composition_error_html_ae44ceddb19da8a8cda7ee150b6826d08"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1_composition_error.html#ae44ceddb19da8a8cda7ee150b6826d08">fourdst::composition::exceptions::CompositionError::what</a></div><div class="ttdeci">const char * what() const noexcept override</div><div class="ttdoc">Returns the error message.</div><div class="ttdef"><b>Definition</b> <a href="exceptions__composition_8h_source.html#l00032">exceptions_composition.h:32</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1exceptions_1_1_invalid_composition_error_html"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1_invalid_composition_error.html">fourdst::composition::exceptions::InvalidCompositionError</a></div><div class="ttdoc">Exception thrown when a composition is in an invalid or inconsistent state.</div><div class="ttdef"><b>Definition</b> <a href="exceptions__composition_8h_source.html#l00041">exceptions_composition.h:41</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1exceptions_1_1_species_error_html_af0c63f7e05d0c65157b960c654d09b67"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1_species_error.html#af0c63f7e05d0c65157b960c654d09b67">fourdst::composition::exceptions::SpeciesError::what</a></div><div class="ttdeci">const char * what() const noexcept override</div><div class="ttdef"><b>Definition</b> <a href="exceptions__composition_8h_source.html#l00066">exceptions_composition.h:66</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1exceptions_1_1_unknown_symbol_error_html"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1_unknown_symbol_error.html">fourdst::composition::exceptions::UnknownSymbolError</a></div><div class="ttdoc">Exception thrown when an unknown symbol is encountered.</div><div class="ttdef"><b>Definition</b> <a href="exceptions__composition_8h_source.html#l00077">exceptions_composition.h:77</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1exceptions_1_1_unregistered_symbol_error_html"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1_unregistered_symbol_error.html">fourdst::composition::exceptions::UnregisteredSymbolError</a></div><div class="ttdoc">Exception thrown when a symbol is used that has not been registered.</div><div class="ttdef"><b>Definition</b> <a href="exceptions__composition_8h_source.html#l00051">exceptions_composition.h:51</a></div></div>
|
||
<div class="ttc" id="aexceptions__composition_8h_html"><div class="ttname"><a href="exceptions__composition_8h.html">exceptions_composition.h</a></div></div>
|
||
<div class="ttc" id="anamespacefourdst_1_1composition_1_1exceptions_html"><div class="ttname"><a href="namespacefourdst_1_1composition_1_1exceptions.html">fourdst::composition::exceptions</a></div><div class="ttdef"><b>Definition</b> <a href="exceptions__composition_8h_source.html#l00006">exceptions_composition.h:6</a></div></div>
|
||
</div><!-- fragment --><hr />
|
||
<h1><a class="anchor" id="exceptions_sec"></a>
|
||
Possible Exception States</h1>
|
||
<p>The library surfaces errors through a focused hierarchy in <code><a class="el" href="namespacefourdst_1_1composition_1_1exceptions.html">fourdst::composition::exceptions</a></code>:</p>
|
||
<table class="markdownTable">
|
||
<tr class="markdownTableHead">
|
||
<th class="markdownTableHeadNone">Exception Type </th><th class="markdownTableHeadNone">When It Occurs </th></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><code>UnknownSymbolError</code> </td><td class="markdownTableBodyNone">A string symbol does not correspond to any known isotope in the compiled species database. </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><code>UnregisteredSymbolError</code> </td><td class="markdownTableBodyNone">A valid species/symbol is used before being registered with a Composition instance. </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><code>InvalidCompositionError</code> </td><td class="markdownTableBodyNone">Construction from mass fractions fails validation (sum deviates from unity beyond tolerance) or canonical (X+Y+Z) check fails. </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><code>CompositionError</code> </td><td class="markdownTableBodyNone">Base class; may be thrown for generic composition-level issues (e.g. negative abundances via the documented <code>InvalidAbundanceError</code> contract). </td></tr>
|
||
</table>
|
||
<p>Recommended patterns:</p><ul>
|
||
<li>Validate externally provided symbol lists before calling bulk registration.</li>
|
||
<li>Use species‑based overloads (strongly typed) where possible for slightly lower overhead (no symbol resolution).</li>
|
||
<li>Wrap construction from mass fractions in a try/catch to surface normalization issues early.</li>
|
||
</ul>
|
||
<hr />
|
||
<h1><a class="anchor" id="api_sec"></a>
|
||
Linking and Integration</h1>
|
||
<h3><a class="anchor" id="autotoc_md23"></a>
|
||
Linking with pkg-config</h3>
|
||
<p>If you installed <code>libcomposition</code> with the <code>pkg-config</code> option enabled, you can get the necessary compiler and linker flags easily:</p>
|
||
<div class="fragment"><div class="line"># Get compiler flags (include paths)</div>
|
||
<div class="line">pkg-config --cflags fourdst_composition</div>
|
||
<div class="line"> </div>
|
||
<div class="line"># Get linker flags (library paths and names)</div>
|
||
<div class="line">pkg-config --libs fourdst_composition</div>
|
||
</div><!-- fragment --><p><b>Example compilation command:</b> </p><div class="fragment"><div class="line">g++ my_app.cpp $(pkg-config --cflags --libs fourdst_composition) -o my_app</div>
|
||
</div><!-- fragment --><hr />
|
||
<h1><a class="anchor" id="api_ref_sec"></a>
|
||
API Reference</h1>
|
||
<p>For a complete list of all classes, methods, and functions, see the <b>Namespaces</b> and <b>Classes</b> sections of this generated documentation.</p>
|
||
<ul>
|
||
<li>Namespace overview: <code><a class="el" href="namespacefourdst_1_1composition.html" title="Utilities and types for representing and manipulating chemical compositions.">fourdst::composition</a></code>, <code><a class="el" href="namespacefourdst_1_1atomic.html" title="Contains canonical information about atomic species and elements used by 4D-STAR.">fourdst::atomic</a></code></li>
|
||
<li>Core classes: <code><a class="el" href="classfourdst_1_1composition_1_1_composition.html" title="Manages a collection of chemical species and their abundances.">fourdst::composition::Composition</a></code>, <code>fourdst::composition::CompositionAbstract</code></li>
|
||
<li>Helper utilities: <code>buildCompositionFromMassFractions</code></li>
|
||
<li>Exception hierarchy: <code><a class="el" href="namespacefourdst_1_1composition_1_1exceptions.html">fourdst::composition::exceptions</a></code></li>
|
||
</ul>
|
||
<hr />
|
||
<h1><a class="anchor" id="test_sec"></a>
|
||
Testing Overview</h1>
|
||
<p>The test suite (GoogleTest) exercises:</p><ul>
|
||
<li>Species database integrity (selected property spot checks).</li>
|
||
<li>Registration and abundance setting (symbols vs species overloads).</li>
|
||
<li>Mass fraction utility construction and validation tolerances.</li>
|
||
<li>Canonical composition correctness (X + Y + Z ≈ 1.0).</li>
|
||
<li>Vector interface ordering and index lookup consistency.</li>
|
||
<li>Exception pathways for unknown/unregistered symbols and invalid compositions.</li>
|
||
</ul>
|
||
<p>Use tolerances (e.g. 1e-12–1e-14) when comparing floating‑point derived quantities in custom tests. </p>
|
||
</div></div><!-- PageDoc -->
|
||
<a href="doxygen_crawl.html"></a>
|
||
</div><!-- contents -->
|
||
</div><!-- doc-content -->
|
||
<!-- start footer part -->
|
||
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||
<ul>
|
||
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.13.2 </li>
|
||
</ul>
|
||
</div>
|
||
</body>
|
||
</html>
|