321 lines
34 KiB
HTML
321 lines
34 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"> v1.5.2</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 designed for the creation, manipulation, and analysis of chemical compositions, with a focus on astrophysical applications. It provides a robust and user-friendly interface for handling material compositions defined by mass or number fractions.</p>
|
|
<h3><a class="anchor" id="autotoc_md0"></a>
|
|
Key Features</h3>
|
|
<ul>
|
|
<li><b>Dual-Mode Operation</b>: Natively supports compositions defined by <b>mass fraction</b> or <b>number fraction</b>.</li>
|
|
<li><b>Rich Atomic Database</b>: Includes a comprehensive, header-only database of isotopic properties (mass, half-life, spin, etc.) generated from the AME2020 and NUBASE2020 evaluations.</li>
|
|
<li><b>Type Safety and Error Handling</b>: Utilizes a clear exception hierarchy to report errors, such as using an unregistered isotope or accessing data from a non-validated composition.</li>
|
|
<li><b>Powerful Functionality</b>: Core features include mixing, subsetting, and on-the-fly conversion between mass and number fractions.</li>
|
|
<li><b>Easy Integration</b>: Designed for seamless integration with other projects using the Meson build system and <code>pkg-config</code>.</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_md2"></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 seperated!</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 migth 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_md3"></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 orgestrator (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>
|
|
<h3><a class="anchor" id="autotoc_md5"></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 --><h3><a class="anchor" id="autotoc_md6"></a>
|
|
C++ Usage Examples</h3>
|
|
<h4><a class="anchor" id="autotoc_md7"></a>
|
|
1. Basic Mass Fraction Composition</h4>
|
|
<p>The most common use case is defining a composition by mass fractions (X, Y, Z).</p>
|
|
<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="comment">// 1. Create a composition object</span></div>
|
|
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">fourdst::composition::Composition</a> comp;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// 2. Register the symbols you want to use</span></div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a1bc2e64f87c12befdc2bc767e7405661">registerSymbol</a>(<span class="stringliteral">"H-1"</span>);</div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a1bc2e64f87c12befdc2bc767e7405661">registerSymbol</a>(<span class="stringliteral">"He-4"</span>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// 3. Set their mass fractions</span></div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a493224656aa3ade68389250720ef09af">setMassFraction</a>(<span class="stringliteral">"H-1"</span>, 0.75);</div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a493224656aa3ade68389250720ef09af">setMassFraction</a>(<span class="stringliteral">"He-4"</span>, 0.25);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// 4. Finalize the composition to validate it and compute global properties</span></div>
|
|
<div class="line"> <span class="keywordflow">if</span> (comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a72d063a74a9d2197065884a2cea57a14">finalize</a>()) {</div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"Composition finalized successfully!"</span> << std::endl;</div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"H-1 Mass Fraction: "</span> << comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#ad20bd541dd7c45274a2e586e6a0519a7">getMassFraction</a>(<span class="stringliteral">"H-1"</span>) << std::endl;</div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"Mean Particle Mass: "</span> << comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a66401fed7054172e9b1a2687e5cc8eff">getMeanParticleMass</a>() << <span class="stringliteral">" g/mol"</span> << std::endl;</div>
|
|
<div class="line"> } <span class="keywordflow">else</span> {</div>
|
|
<div class="line"> std::cerr << <span class="stringliteral">"Failed to finalize composition."</span> << std::endl;</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">return</span> 0;</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#l00258">composition.h:258</a></div></div>
|
|
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_a1bc2e64f87c12befdc2bc767e7405661"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#a1bc2e64f87c12befdc2bc767e7405661">fourdst::composition::Composition::registerSymbol</a></div><div class="ttdeci">void registerSymbol(const std::string &symbol, bool massFracMode=true)</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#l00208">composition.cpp:208</a></div></div>
|
|
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_a493224656aa3ade68389250720ef09af"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#a493224656aa3ade68389250720ef09af">fourdst::composition::Composition::setMassFraction</a></div><div class="ttdeci">double setMassFraction(const std::string &symbol, const double &mass_fraction)</div><div class="ttdoc">Sets the mass fraction for a given symbol.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00287">composition.cpp:287</a></div></div>
|
|
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_a66401fed7054172e9b1a2687e5cc8eff"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#a66401fed7054172e9b1a2687e5cc8eff">fourdst::composition::Composition::getMeanParticleMass</a></div><div class="ttdeci">double getMeanParticleMass() const</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#l00613">composition.cpp:613</a></div></div>
|
|
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_a72d063a74a9d2197065884a2cea57a14"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#a72d063a74a9d2197065884a2cea57a14">fourdst::composition::Composition::finalize</a></div><div class="ttdeci">bool finalize(bool norm=false)</div><div class="ttdoc">Finalizes the composition, making it ready for querying.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00389">composition.cpp:389</a></div></div>
|
|
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_ad20bd541dd7c45274a2e586e6a0519a7"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#ad20bd541dd7c45274a2e586e6a0519a7">fourdst::composition::Composition::getMassFraction</a></div><div class="ttdeci">std::unordered_map< std::string, double > getMassFraction() const</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#l00534">composition.cpp:534</a></div></div>
|
|
<div class="ttc" id="acomposition_8h_html"><div class="ttname"><a href="composition_8h.html">composition.h</a></div></div>
|
|
</div><!-- fragment --><h4><a class="anchor" id="autotoc_md8"></a>
|
|
2. Number Fraction Composition and Mode Switching</h4>
|
|
<p>The library can also work with number (mole) fractions and switch between modes.</p>
|
|
<div class="fragment"><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">void</span> number_fraction_example() {</div>
|
|
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">fourdst::composition::Composition</a> comp;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Register symbols in number fraction mode</span></div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a1bc2e64f87c12befdc2bc767e7405661">registerSymbol</a>(<span class="stringliteral">"H-1"</span>, <span class="keyword">false</span>); <span class="comment">// massFracMode = false</span></div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a1bc2e64f87c12befdc2bc767e7405661">registerSymbol</a>(<span class="stringliteral">"He-4"</span>, <span class="keyword">false</span>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a7d4d748f3ee25e68751fb143717ed080">setNumberFraction</a>(<span class="stringliteral">"H-1"</span>, 0.9);</div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a7d4d748f3ee25e68751fb143717ed080">setNumberFraction</a>(<span class="stringliteral">"He-4"</span>, 0.1);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">if</span> (comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a72d063a74a9d2197065884a2cea57a14">finalize</a>()) {</div>
|
|
<div class="line"> <span class="comment">// We can get number fractions directly</span></div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"He-4 Number Fraction: "</span> << comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a84fea38bc1c005e483910285f6800e15">getNumberFraction</a>(<span class="stringliteral">"He-4"</span>) << std::endl;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Or get the equivalent mass fraction</span></div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"He-4 Mass Fraction: "</span> << comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#ad20bd541dd7c45274a2e586e6a0519a7">getMassFraction</a>(<span class="stringliteral">"He-4"</span>) << std::endl;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Switch the entire composition to mass fraction mode</span></div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a0af981ed1074b26c237cf6cf35f82c9e">setCompositionMode</a>(<span class="keyword">true</span>); <span class="comment">// true for mass fraction mode</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Now, getting the mass fraction is a direct lookup</span></div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"He-4 Mass Fraction (after mode switch): "</span> << comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#ad20bd541dd7c45274a2e586e6a0519a7">getMassFraction</a>(<span class="stringliteral">"He-4"</span>) << std::endl;</div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_a0af981ed1074b26c237cf6cf35f82c9e"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#a0af981ed1074b26c237cf6cf35f82c9e">fourdst::composition::Composition::setCompositionMode</a></div><div class="ttdeci">void setCompositionMode(bool massFracMode)</div><div class="ttdoc">Sets the composition mode (mass fraction vs. number fraction).</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00669">composition.cpp:669</a></div></div>
|
|
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_a7d4d748f3ee25e68751fb143717ed080"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#a7d4d748f3ee25e68751fb143717ed080">fourdst::composition::Composition::setNumberFraction</a></div><div class="ttdeci">double setNumberFraction(const std::string &symbol, const double &number_fraction)</div><div class="ttdoc">Sets the number fraction for a given symbol.</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_1_composition_html_a84fea38bc1c005e483910285f6800e15"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#a84fea38bc1c005e483910285f6800e15">fourdst::composition::Composition::getNumberFraction</a></div><div class="ttdeci">double getNumberFraction(const std::string &symbol) const</div><div class="ttdoc">Gets the number fraction for a given symbol.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00543">composition.cpp:543</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><!-- fragment --><h4><a class="anchor" id="autotoc_md9"></a>
|
|
3. Mixing Two Compositions</h4>
|
|
<p>You can easily mix two compositions. The library handles the union of all species.</p>
|
|
<div class="fragment"><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">void</span> mixing_example() {</div>
|
|
<div class="line"> <span class="comment">// Composition 1: Pure Hydrogen</span></div>
|
|
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">fourdst::composition::Composition</a> comp1({<span class="stringliteral">"H-1"</span>}, {1.0});</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Composition 2: Pure Helium</span></div>
|
|
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">fourdst::composition::Composition</a> comp2({<span class="stringliteral">"He-4"</span>}, {1.0});</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Mix them with a 50/50 ratio using the '+' operator</span></div>
|
|
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">fourdst::composition::Composition</a> mixed = comp1 + comp2;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Mix them with a 75/25 ratio using the mix() method</span></div>
|
|
<div class="line"> <span class="comment">// 0.75 of comp1, 0.25 of comp2</span></div>
|
|
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">fourdst::composition::Composition</a> mixed2 = comp1.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a3aead72892606725a4149a5f65bd31ec">mix</a>(comp2, 0.75);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"50/50 Mix H-1: "</span> << mixed.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#ad20bd541dd7c45274a2e586e6a0519a7">getMassFraction</a>(<span class="stringliteral">"H-1"</span>) << std::endl; <span class="comment">// -> 0.5</span></div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"75/25 Mix H-1: "</span> << mixed2.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#ad20bd541dd7c45274a2e586e6a0519a7">getMassFraction</a>(<span class="stringliteral">"H-1"</span>) << std::endl; <span class="comment">// -> 0.75</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="aclassfourdst_1_1composition_1_1_composition_html_a3aead72892606725a4149a5f65bd31ec"><div class="ttname"><a href="classfourdst_1_1composition_1_1_composition.html#a3aead72892606725a4149a5f65bd31ec">fourdst::composition::Composition::mix</a></div><div class="ttdeci">Composition mix(const Composition &other, double fraction) const</div><div class="ttdoc">Mixes this composition with another to produce a new composition.</div><div class="ttdef"><b>Definition</b> <a href="composition_8cpp_source.html#l00473">composition.cpp:473</a></div></div>
|
|
</div><!-- fragment --><h4><a class="anchor" id="autotoc_md10"></a>
|
|
4. Error Handling</h4>
|
|
<p>The library uses exceptions to report errors. Always wrap calls in a <code>try-catch</code> block for robust code.</p>
|
|
<div class="fragment"><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">void</span> error_example() {</div>
|
|
<div class="line"> <a class="code hl_class" href="classfourdst_1_1composition_1_1_composition.html">fourdst::composition::Composition</a> comp;</div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a1bc2e64f87c12befdc2bc767e7405661">registerSymbol</a>(<span class="stringliteral">"H-1"</span>);</div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a493224656aa3ade68389250720ef09af">setMassFraction</a>(<span class="stringliteral">"H-1"</span>, 1.0);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">try</span> {</div>
|
|
<div class="line"> <span class="comment">// This will throw, because the composition is not finalized yet.</span></div>
|
|
<div class="line"> <span class="keywordtype">double</span> mass = comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#ad20bd541dd7c45274a2e586e6a0519a7">getMassFraction</a>(<span class="stringliteral">"H-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_composition_not_finalized_error.html">fourdst::composition::exceptions::CompositionNotFinalizedError</a>& e) {</div>
|
|
<div class="line"> std::cerr << <span class="stringliteral">"Caught expected error: "</span> << e.<a class="code hl_function" href="classfourdst_1_1composition_1_1exceptions_1_1_composition_error.html#ae44ceddb19da8a8cda7ee150b6826d08">what</a>() << std::endl;</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">try</span> {</div>
|
|
<div class="line"> <span class="comment">// This will throw, because "Li-6" was never registered.</span></div>
|
|
<div class="line"> comp.<a class="code hl_function" href="classfourdst_1_1composition_1_1_composition.html#a493224656aa3ade68389250720ef09af">setMassFraction</a>(<span class="stringliteral">"Li-6"</span>, 0.1);</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">fourdst::composition::exceptions::UnregisteredSymbolError</a>& e) {</div>
|
|
<div class="line"> std::cerr << <span class="stringliteral">"Caught expected error: "</span> << e.<a class="code hl_function" href="classfourdst_1_1composition_1_1exceptions_1_1_composition_error.html#ae44ceddb19da8a8cda7ee150b6826d08">what</a>() << std::endl;</div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</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_composition_not_finalized_error_html"><div class="ttname"><a href="classfourdst_1_1composition_1_1exceptions_1_1_composition_not_finalized_error.html">fourdst::composition::exceptions::CompositionNotFinalizedError</a></div><div class="ttdoc">Exception thrown when an operation is attempted on a composition that has not been finalized.</div><div class="ttdef"><b>Definition</b> <a href="exceptions__composition_8h_source.html#l00074">exceptions_composition.h:74</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#l00111">exceptions_composition.h:111</a></div></div>
|
|
</div><!-- fragment --><h4><a class="anchor" id="autotoc_md11"></a>
|
|
5. Accessing Atomic Data</h4>
|
|
<p>You can directly access the static database of all known species.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="species_8h.html">fourdst/composition/species.h</a>"</span> <span class="comment">// Provides static instances like H_1</span></div>
|
|
<div class="line"><span class="preprocessor">#include "<a class="code" href="atomic_species_8h.html">fourdst/composition/atomicSpecies.h</a>"</span> <span class="comment">// Provides the main 'species' map</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordtype">void</span> data_example() {</div>
|
|
<div class="line"> <span class="comment">// Access via the map</span></div>
|
|
<div class="line"> <span class="keyword">const</span> <span class="keyword">auto</span>& fe56 = <a class="code hl_variable" href="namespacefourdst_1_1atomic.html#a3f619cc8f8b2cd718a4082c6adb0de90">fourdst::atomic::species</a>.at(<span class="stringliteral">"Fe-56"</span>);</div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"Fe-56 mass: "</span> << fe56->mass() << std::endl;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Access via the static instance</span></div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"H-1 spin: "</span> << <a class="code hl_function" href="namespacefourdst_1_1atomic.html#a6766bc834fd656df51bdcf22f7d97877">fourdst::atomic::H_1</a>.spin() << std::endl;</div>
|
|
<div class="line"> std::cout << <span class="stringliteral">"F-18 half-life: "</span> << <a class="code hl_function" href="namespacefourdst_1_1atomic.html#a3c09ded079905f8c355f9ea87b6b191f">fourdst::atomic::F_18</a>.halfLife() << <span class="stringliteral">" s"</span> << std::endl;</div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="aatomic_species_8h_html"><div class="ttname"><a href="atomic_species_8h.html">atomicSpecies.h</a></div></div>
|
|
<div class="ttc" id="anamespacefourdst_1_1atomic_html_a3c09ded079905f8c355f9ea87b6b191f"><div class="ttname"><a href="namespacefourdst_1_1atomic.html#a3c09ded079905f8c355f9ea87b6b191f">fourdst::atomic::F_18</a></div><div class="ttdeci">static const Species F_18("F-18", "F", 0, 9, 9, 18, 7631.6383, "B-", -4444.5049, 6584.04, "+", "+=100", 18.000937324, 0.497)</div></div>
|
|
<div class="ttc" id="anamespacefourdst_1_1atomic_html_a3f619cc8f8b2cd718a4082c6adb0de90"><div class="ttname"><a href="namespacefourdst_1_1atomic.html#a3f619cc8f8b2cd718a4082c6adb0de90">fourdst::atomic::species</a></div><div class="ttdeci">static const std::unordered_map< std::string, const Species & > species</div><div class="ttdef"><b>Definition</b> <a href="species_8h_source.html#l03580">species.h:3580</a></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="aspecies_8h_html"><div class="ttname"><a href="species_8h.html">species.h</a></div></div>
|
|
</div><!-- fragment --><hr />
|
|
<h1><a class="anchor" id="test_sec"></a>
|
|
Testing</h1>
|
|
<p><code>libcomposition</code> is tested using the GoogleTest framework. The test suite provides high coverage of the library's functionality.</p>
|
|
<h3><a class="anchor" id="autotoc_md13"></a>
|
|
Test Coverage Includes:</h3>
|
|
<ul>
|
|
<li><b>Atomic Data Validation</b>: Spot checks on isotopic properties (mass, half-life, spin) for a wide range of elements to ensure the underlying data files are parsed and represented correctly.</li>
|
|
<li><b>Core <code>Composition</code> Workflow</b>: Verification of object construction, symbol registration (for both valid and invalid symbols), and the complete workflow of setting and getting both mass and number fractions.</li>
|
|
<li><b>Finalization Logic</b>: Ensures that <code>finalize()</code> is a required step before querying data. Tests the validation logic for compositions that sum to 1.0 and the auto-normalization feature (<code>finalize(true)</code>).</li>
|
|
<li><b>Advanced Features</b>: Dedicated tests for <code>mix()</code>, <code>subset()</code>, <code>setCompositionMode()</code>, and the calculation of derived quantities like <code>getMolarAbundance()</code> and <code>getMeanAtomicNumber()</code>.</li>
|
|
<li><b>Exception Handling</b>: Confirms that invalid operations (e.g., using an unregistered symbol, mixing un-finalized compositions) correctly throw exceptions from the <code><a class="el" href="namespacefourdst_1_1composition_1_1exceptions.html">fourdst::composition::exceptions</a></code> hierarchy.</li>
|
|
</ul>
|
|
<hr />
|
|
<h1><a class="anchor" id="api_sec"></a>
|
|
API Reference</h1>
|
|
<p>For a complete list of all classes, methods, and functions, please see the **<a href="namespaces.html">Namespaces</a>** and **<a href="annotated.html">Classes</a>** sections of this documentation. </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>
|