<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>
<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>
<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>
<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#l00097">composition.h:97</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a3ab4dcda0bfd1a35b169bcc57fe66725"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a3ab4dcda0bfd1a35b169bcc57fe66725">fourdst::composition::Composition::registerSymbol</a></div><divclass="ttdeci">void registerSymbol(const std::string &symbol)</div><divclass="ttdoc">Registers a new symbol for inclusion in the composition.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00178">composition.cpp:178</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a9ea2b673341fdc67afeb0f0517a54c8c"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a9ea2b673341fdc67afeb0f0517a54c8c">fourdst::composition::Composition::getMassFraction</a></div><divclass="ttdeci">std::unordered_map< atomic::Species, double > getMassFraction() const noexcept override</div><divclass="ttdoc">Gets the mass fractions of all species in the composition.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00251">composition.cpp:251</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_afbbb5e51ad5ae5c0fa6bc0094195aecd"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#afbbb5e51ad5ae5c0fa6bc0094195aecd">fourdst::composition::Composition::getMeanParticleMass</a></div><divclass="ttdeci">double getMeanParticleMass() const noexcept override</div><divclass="ttdoc">Compute the mean particle mass of the composition.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00311">composition.cpp:311</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_a34f71d4d8f0297c576fd62fabd490305"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a34f71d4d8f0297c576fd62fabd490305">fourdst::composition::Composition::getNumberFraction</a></div><divclass="ttdeci">double getNumberFraction(const std::string &symbol) const override</div><divclass="ttdoc">Gets the number fraction for a given symbol. See the overload for species-based lookup for more detai...</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00260">composition.cpp:260</a></div></div>
<divclass="line"><spanclass="keywordtype">double</span> mass = comp.<aclass="code hl_function"href="classfourdst_1_1composition_1_1_composition.html#a9ea2b673341fdc67afeb0f0517a54c8c">getMassFraction</a>(<spanclass="stringliteral">"H-1"</span>);</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#l00051">exceptions_composition.h:51</a></div></div>
</div><!-- fragment --><h4><aclass="anchor"id="autotoc_md21"></a>
<divclass="fragment"><divclass="line"><spanclass="preprocessor">#include "fourdst/composition/species.h"</span><spanclass="comment">// Provides static instances like H_1</span></div>
<divclass="line"><spanclass="preprocessor">#include "fourdst/composition/atomicSpecies.h"</span><spanclass="comment">// Provides the main 'species' map</span></div>
<divclass="ttc"id="anamespacefourdst_1_1atomic_html_a3f619cc8f8b2cd718a4082c6adb0de90"><divclass="ttname"><ahref="namespacefourdst_1_1atomic.html#a3f619cc8f8b2cd718a4082c6adb0de90">fourdst::atomic::species</a></div><divclass="ttdeci">static const std::unordered_map< std::string, const Species &> species</div><divclass="ttdoc">Map of species names to their corresponding Species objects.</div><divclass="ttdef"><b>Definition</b><ahref="species_8h_source.html#l03579">species.h:3579</a></div></div>
<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>
