362 lines
41 KiB
HTML
362 lines
41 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.9.8"/>
|
||
<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>
|
||
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="resize.js"></script>
|
||
<script type="text/javascript" src="navtreedata.js"></script>
|
||
<script type="text/javascript" src="navtree.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.2.1</span>
|
||
</div>
|
||
<div id="projectbrief">Robust atomic species information library</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<!-- end header part -->
|
||
<!-- Generated by Doxygen 1.9.8 -->
|
||
<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" 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');
|
||
$(document).ready(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 */
|
||
$(document).ready(function(){initNavTree('index.html',''); initResizable(); });
|
||
/* @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_1Species.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_1Composition.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_1Composition.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_1Composition_html"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.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#l00098">composition.h:98</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1Composition_html_a262d7133035d4e6f45daa81827abf5e7"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.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#l00580">composition.cpp:580</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_1Composition.html">Composition</a> comp(std::vector<Species>{H_1, He_4, O_16});</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1Composition.html#a262d7133035d4e6f45daa81827abf5e7">setMolarAbundance</a>(H_1, 5.0);</div>
|
||
<div class="line"> comp.setMolarAbundance(He_4, 2.5);</div>
|
||
<div class="line"> comp.setMolarAbundance(O_16, 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="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_1Composition.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_1Composition.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_1Composition_html_aac5b214a3d1278e127422224cb9cee50"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.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#l00377">composition.cpp:377</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#l00084">utils.cpp:84</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_1Composition.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_1Composition.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.<a class="code hl_function" href="classfourdst_1_1composition_1_1Composition.html#abcb391f5fca2b636127e48e681e4c3ee">getMolarAbundanceVector</a>();</div>
|
||
<div class="line"> <span class="keyword">auto</span> massVec = comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1Composition.html#af4f44aaf8b7e0d63872a70b5e2131369">getMassFractionVector</a>();</div>
|
||
<div class="line"> </div>
|
||
<div class="line"> <span class="keywordtype">size_t</span> idx_he4 = comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1Composition.html#a0d94f62402bb90b5d12679faeaa8c5d7">getSpeciesIndex</a>(<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 class="ttc" id="aclassfourdst_1_1composition_1_1Composition_html_a0d94f62402bb90b5d12679faeaa8c5d7"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.html#a0d94f62402bb90b5d12679faeaa8c5d7">fourdst::composition::Composition::getSpeciesIndex</a></div><div class="ttdeci">size_t getSpeciesIndex(const std::string &symbol) const override</div><div class="ttdoc">get the index in the sorted vector representation for a given symbol</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00485">composition.cpp:485</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1Composition_html_abcb391f5fca2b636127e48e681e4c3ee"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.html#abcb391f5fca2b636127e48e681e4c3ee">fourdst::composition::Composition::getMolarAbundanceVector</a></div><div class="ttdeci">std::vector< double > getMolarAbundanceVector() const noexcept override</div><div class="ttdoc">Get a uniform vector representation of the molar abundances stored in the composition object sorted s...</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00463">composition.cpp:463</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1Composition_html_af4f44aaf8b7e0d63872a70b5e2131369"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.html#af4f44aaf8b7e0d63872a70b5e2131369">fourdst::composition::Composition::getMassFractionVector</a></div><div class="ttdeci">std::vector< double > getMassFractionVector() const noexcept override</div><div class="ttdoc">Get a uniform vector representation of the mass fraction stored in the composition object sorted such...</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00420">composition.cpp:420</a></div></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.<a class="code hl_function" href="classfourdst_1_1composition_1_1Composition.html#a9ea2b673341fdc67afeb0f0517a54c8c">getMassFraction</a>(<span class="stringliteral">"C-12"</span>);</div>
|
||
<div class="line"><span class="keywordtype">double</span> nf_c12 = comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1Composition.html#a34f71d4d8f0297c576fd62fabd490305">getNumberFraction</a>(<span class="stringliteral">"C-12"</span>);</div>
|
||
<div class="line"><span class="keywordtype">double</span> mol_c12 = comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1Composition.html#add67a92d73e3a57a2bbdb52bc9ca3bfe">getMolarAbundance</a>(<span class="stringliteral">"C-12"</span>);</div>
|
||
<div class="line"><span class="keywordtype">double</span> meanA = comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1Composition.html#afbbb5e51ad5ae5c0fa6bc0094195aecd">getMeanParticleMass</a>();</div>
|
||
<div class="line"><span class="keywordtype">double</span> Ye = comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1Composition.html#a90fc71d1fe03017ee4c7a1cac69d24fb">getElectronAbundance</a>();</div>
|
||
<div class="line"><span class="keyword">auto</span> canon = comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1Composition.html#aac5b214a3d1278e127422224cb9cee50">getCanonicalComposition</a>();</div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1Composition_html_a34f71d4d8f0297c576fd62fabd490305"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.html#a34f71d4d8f0297c576fd62fabd490305">fourdst::composition::Composition::getNumberFraction</a></div><div class="ttdeci">double getNumberFraction(const std::string &symbol) const override</div><div class="ttdoc">Gets the number fraction for a given symbol. See the overload for species-based lookup for more detai...</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00307">composition.cpp:307</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1Composition_html_a90fc71d1fe03017ee4c7a1cac69d24fb"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.html#a90fc71d1fe03017ee4c7a1cac69d24fb">fourdst::composition::Composition::getElectronAbundance</a></div><div class="ttdeci">double getElectronAbundance() const noexcept override</div><div class="ttdoc">Compute the electron abundance of the composition.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00368">composition.cpp:368</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1Composition_html_a9ea2b673341fdc67afeb0f0517a54c8c"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.html#a9ea2b673341fdc67afeb0f0517a54c8c">fourdst::composition::Composition::getMassFraction</a></div><div class="ttdeci">std::unordered_map< atomic::Species, double > getMassFraction() const noexcept override</div><div class="ttdoc">Gets the mass fractions of all species in the composition.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00298">composition.cpp:298</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1Composition_html_add67a92d73e3a57a2bbdb52bc9ca3bfe"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.html#add67a92d73e3a57a2bbdb52bc9ca3bfe">fourdst::composition::Composition::getMolarAbundance</a></div><div class="ttdeci">double getMolarAbundance(const std::string &symbol) const override</div><div class="ttdoc">Gets the molar abundances of all species in the composition.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00338">composition.cpp:338</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1Composition_html_afbbb5e51ad5ae5c0fa6bc0094195aecd"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.html#afbbb5e51ad5ae5c0fa6bc0094195aecd">fourdst::composition::Composition::getMeanParticleMass</a></div><div class="ttdeci">double getMeanParticleMass() const noexcept override</div><div class="ttdoc">Compute the mean particle mass of the composition.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00358">composition.cpp:358</a></div></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_1Composition.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_1Composition.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_1UnknownSymbolError.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_1SpeciesError.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_1Composition.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_1Composition.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_1UnregisteredSymbolError.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_1CompositionError.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_1Composition.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_1Composition.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_1InvalidCompositionError.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_1CompositionError.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_1Composition.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_1InvalidCompositionError.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_1CompositionError.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_1Composition_html_a3ab4dcda0bfd1a35b169bcc57fe66725"><div class="ttname"><a href="classfourdst_1_1composition_1_1Composition.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#l00225">composition.cpp:225</a></div></div>
|
||
<div class="ttc" id="aclassfourdst_1_1composition_1_1exceptions_1_1CompositionError_html_ae44ceddb19da8a8cda7ee150b6826d08"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1CompositionError.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_1InvalidCompositionError_html"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1InvalidCompositionError.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_1SpeciesError_html_af0c63f7e05d0c65157b960c654d09b67"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1SpeciesError.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_1UnknownSymbolError_html"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1UnknownSymbolError.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_1UnregisteredSymbolError_html"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1UnregisteredSymbolError.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_1Composition.html" title="Manages a collection of chemical species and their abundances.">fourdst::composition::Composition</a></code>, <code><a class="el" href="classfourdst_1_1composition_1_1CompositionAbstract.html" title="Abstract base class for chemical composition representations.">fourdst::composition::CompositionAbstract</a></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 -->
|
||
</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.9.8 </li>
|
||
</ul>
|
||
</div>
|
||
</body>
|
||
</html>
|