<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><aclass="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><aclass="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><aclass="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><!-- 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><!-- fragment --><h3><aclass="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>
<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>
<divclass="fragment"><divclass="line"># Get compiler flags (include paths)</div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html">fourdst::composition::Composition</a></div><divclass="ttdoc">Manages a collection of chemical species and their abundances.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8h_source.html#l00258">composition.h:258</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a1bc2e64f87c12befdc2bc767e7405661"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a1bc2e64f87c12befdc2bc767e7405661">fourdst::composition::Composition::registerSymbol</a></div><divclass="ttdeci">void registerSymbol(const std::string &symbol, bool massFracMode=true)</div><divclass="ttdoc">Registers a new symbol for inclusion in the composition.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00233">composition.cpp:233</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a493224656aa3ade68389250720ef09af"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a493224656aa3ade68389250720ef09af">fourdst::composition::Composition::setMassFraction</a></div><divclass="ttdeci">double setMassFraction(const std::string &symbol, const double &mass_fraction)</div><divclass="ttdoc">Sets the mass fraction for a given symbol.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00312">composition.cpp:312</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a66401fed7054172e9b1a2687e5cc8eff"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a66401fed7054172e9b1a2687e5cc8eff">fourdst::composition::Composition::getMeanParticleMass</a></div><divclass="ttdeci">double getMeanParticleMass() const</div><divclass="ttdoc">Compute the mean particle mass of the composition.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00638">composition.cpp:638</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a72d063a74a9d2197065884a2cea57a14"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a72d063a74a9d2197065884a2cea57a14">fourdst::composition::Composition::finalize</a></div><divclass="ttdeci">bool finalize(bool norm=false)</div><divclass="ttdoc">Finalizes the composition, making it ready for querying.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00414">composition.cpp:414</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_ad20bd541dd7c45274a2e586e6a0519a7"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#ad20bd541dd7c45274a2e586e6a0519a7">fourdst::composition::Composition::getMassFraction</a></div><divclass="ttdeci">std::unordered_map< std::string, double > getMassFraction() const</div><divclass="ttdoc">Gets the mass fractions of all species in the composition.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00559">composition.cpp:559</a></div></div>
<divclass="line"><spanclass="comment">// We can get number fractions directly</span></div>
<divclass="line"> std::cout <<<spanclass="stringliteral">"He-4 Number Fraction: "</span><< comp.<aclass="code hl_function"href="classfourdst_1_1composition_1_1_composition.html#a84fea38bc1c005e483910285f6800e15">getNumberFraction</a>(<spanclass="stringliteral">"He-4"</span>) << std::endl;</div>
<divclass="line"></div>
<divclass="line"><spanclass="comment">// Or get the equivalent mass fraction</span></div>
<divclass="line"> std::cout <<<spanclass="stringliteral">"He-4 Mass Fraction: "</span><< comp.<aclass="code hl_function"href="classfourdst_1_1composition_1_1_composition.html#ad20bd541dd7c45274a2e586e6a0519a7">getMassFraction</a>(<spanclass="stringliteral">"He-4"</span>) << std::endl;</div>
<divclass="line"></div>
<divclass="line"><spanclass="comment">// Switch the entire composition to mass fraction mode</span></div>
<divclass="line"> comp.<aclass="code hl_function"href="classfourdst_1_1composition_1_1_composition.html#a0af981ed1074b26c237cf6cf35f82c9e">setCompositionMode</a>(<spanclass="keyword">true</span>); <spanclass="comment">// true for mass fraction mode</span></div>
<divclass="line"></div>
<divclass="line"><spanclass="comment">// Now, getting the mass fraction is a direct lookup</span></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a0af981ed1074b26c237cf6cf35f82c9e"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a0af981ed1074b26c237cf6cf35f82c9e">fourdst::composition::Composition::setCompositionMode</a></div><divclass="ttdeci">void setCompositionMode(bool massFracMode)</div><divclass="ttdoc">Sets the composition mode (mass fraction vs. number fraction).</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00694">composition.cpp:694</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a7d4d748f3ee25e68751fb143717ed080"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a7d4d748f3ee25e68751fb143717ed080">fourdst::composition::Composition::setNumberFraction</a></div><divclass="ttdeci">double setNumberFraction(const std::string &symbol, const double &number_fraction)</div><divclass="ttdoc">Sets the number fraction for a given symbol.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00363">composition.cpp:363</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a84fea38bc1c005e483910285f6800e15"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a84fea38bc1c005e483910285f6800e15">fourdst::composition::Composition::getNumberFraction</a></div><divclass="ttdeci">double getNumberFraction(const std::string &symbol) const</div><divclass="ttdoc">Gets the number fraction for a given symbol.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00568">composition.cpp:568</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a3aead72892606725a4149a5f65bd31ec"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a3aead72892606725a4149a5f65bd31ec">fourdst::composition::Composition::mix</a></div><divclass="ttdeci">Composition mix(const Composition &other, double fraction) const</div><divclass="ttdoc">Mixes this composition with another to produce a new composition.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00498">composition.cpp:498</a></div></div>
<divclass="line"><spanclass="comment">// This will throw, because the composition is not finalized yet.</span></div>
<divclass="line"><spanclass="keywordtype">double</span> mass = comp.<aclass="code hl_function"href="classfourdst_1_1composition_1_1_composition.html#ad20bd541dd7c45274a2e586e6a0519a7">getMassFraction</a>(<spanclass="stringliteral">"H-1"</span>);</div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1exceptions_1_1_composition_error_html_ae44ceddb19da8a8cda7ee150b6826d08"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1exceptions_1_1_composition_error.html#ae44ceddb19da8a8cda7ee150b6826d08">fourdst::composition::exceptions::CompositionError::what</a></div><divclass="ttdeci">const char * what() const noexcept override</div><divclass="ttdoc">Returns the error message.</div><divclass="ttdef"><b>Definition</b><ahref="exceptions__composition_8h_source.html#l00032">exceptions_composition.h:32</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1exceptions_1_1_composition_not_finalized_error_html"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1exceptions_1_1_composition_not_finalized_error.html">fourdst::composition::exceptions::CompositionNotFinalizedError</a></div><divclass="ttdoc">Exception thrown when an operation is attempted on a composition that has not been finalized.</div><divclass="ttdef"><b>Definition</b><ahref="exceptions__composition_8h_source.html#l00074">exceptions_composition.h:74</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1exceptions_1_1_unregistered_symbol_error_html"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1exceptions_1_1_unregistered_symbol_error.html">fourdst::composition::exceptions::UnregisteredSymbolError</a></div><divclass="ttdoc">Exception thrown when a symbol is used that has not been registered.</div><divclass="ttdef"><b>Definition</b><ahref="exceptions__composition_8h_source.html#l00111">exceptions_composition.h:111</a></div></div>
</div><!-- fragment --><h4><aclass="anchor"id="autotoc_md11"></a>
5. Accessing Atomic Data</h4>
<p>You can directly access the static database of all known species.</p>
<divclass="fragment"><divclass="line"><spanclass="preprocessor">#include "<aclass="code"href="species_8h.html">fourdst/composition/species.h</a>"</span><spanclass="comment">// Provides static instances like H_1</span></div>
<divclass="line"><spanclass="preprocessor">#include "<aclass="code"href="atomic_species_8h.html">fourdst/composition/atomicSpecies.h</a>"</span><spanclass="comment">// Provides the main 'species' map</span></div>
<p><code>libcomposition</code> is tested using the GoogleTest framework. The test suite provides high coverage of the library's functionality.</p>
<h3><aclass="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><aclass="el"href="namespacefourdst_1_1composition_1_1exceptions.html">fourdst::composition::exceptions</a></code> hierarchy.</li>
</ul>
<hr/>
<h1><aclass="anchor"id="api_sec"></a>
API Reference</h1>
<p>For a complete list of all classes, methods, and functions, please see the **<ahref="namespaces.html">Namespaces</a>** and **<ahref="annotated.html">Classes</a>** sections of this documentation. </p>
</div></div><!-- PageDoc -->
<ahref="doxygen_crawl.html"></a>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<divid="nav-path"class="navpath"><!-- id is needed for treeview function! -->
<ul>
<liclass="footer">Generated by <ahref="https://www.doxygen.org/index.html"><imgclass="footer"src="doxygen.svg"width="104"height="31"alt="doxygen"/></a> 1.13.2 </li>
