<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>
<li><b>Type–Safe Species Representation</b>: Strongly typed isotopes (<code><aclass="el"href="structfourdst_1_1atomic_1_1_species.html"title="Represents an atomic species (isotope) with its fundamental physical properties.">fourdst::atomic::Species</a></code>) generated from evaluated nuclear data (AME2020 / NUBASE2020).</li>
<li><b>Molar Abundance Core</b>: Stores absolute molar abundances and derives all secondary quantities (mass / number fractions, mean particle mass, electron abundance) on demand, with internal caching.</li>
<li><b>Canonical Composition Support</b>: Direct computation of canonical (X: Hydrogen, Y: Helium, Z: Metals) mass fractions via <code>getCanonicalComposition()</code>.</li>
<li><b>Convenience Construction</b>: Helper utilities for constructing compositions from a vector or set of mass fractions (<code>buildCompositionFromMassFractions</code>).</li>
<li><b>Deterministic Ordering</b>: Species are always stored and iterated lightest→heaviest (ordering defined by atomic mass) enabling uniform vector interfaces.</li>
<li><b>Clear Exception Hierarchy</b>: Explicit error signaling for invalid symbols, unregistered species, and inconsistent input data.</li>
<li><b>Meson + pkg-config Integration</b>: Simple build, install, and consumption in external projects.</li>
<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>
<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>
<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>
<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_a262d7133035d4e6f45daa81827abf5e7"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#a262d7133035d4e6f45daa81827abf5e7">fourdst::composition::Composition::setMolarAbundance</a></div><divclass="ttdeci">void setMolarAbundance(const std::string &symbol, const double &molar_abundance)</div><divclass="ttdoc">Sets the molar abundance for a given symbol.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00529">composition.cpp:529</a></div></div>
<divclass="ttc"id="anamespacefourdst_1_1composition_html"><divclass="ttname"><ahref="namespacefourdst_1_1composition.html">fourdst::composition</a></div><divclass="ttdoc">Utilities and types for representing and manipulating chemical compositions.</div></div>
</div><!-- fragment --><h4><aclass="anchor"id="autotoc_md16"></a>
<divclass="ttc"id="anamespacefourdst_1_1atomic_html"><divclass="ttname"><ahref="namespacefourdst_1_1atomic.html">fourdst::atomic</a></div><divclass="ttdoc">Contains canonical information about atomic species and elements used by 4D-STAR.</div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1_composition_html_aac5b214a3d1278e127422224cb9cee50"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1_composition.html#aac5b214a3d1278e127422224cb9cee50">fourdst::composition::Composition::getCanonicalComposition</a></div><divclass="ttdeci">CanonicalComposition getCanonicalComposition() const</div><divclass="ttdoc">Compute the canonical composition (X, Y, Z) of the composition.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00330">composition.cpp:330</a></div></div>
<divclass="ttc"id="anamespacefourdst_1_1composition_html_aa90b1ef07d607c0c829bedccf381cf54"><divclass="ttname"><ahref="namespacefourdst_1_1composition.html#aa90b1ef07d607c0c829bedccf381cf54">fourdst::composition::buildCompositionFromMassFractions</a></div><divclass="ttdeci">Composition buildCompositionFromMassFractions(const std::vector< std::string >&symbols, const std::vector< double >&massFractions)</div><divclass="ttdoc">Build a Composition object from symbols and their corresponding mass fractions.</div><divclass="ttdef"><b>Definition</b><ahref="utils_8cpp_source.html#l00074">utils.cpp:74</a></div></div>
<divclass="line"><aclass="code hl_class"href="classfourdst_1_1composition_1_1_composition.html">Composition</a> comp({<spanclass="stringliteral">"H-1"</span>, <spanclass="stringliteral">"C-12"</span>, <spanclass="stringliteral">"He-4"</span>}); <spanclass="comment">// Internally sorted by mass (H < He < C)</span></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_1exceptions_1_1_invalid_composition_error_html"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1exceptions_1_1_invalid_composition_error.html">fourdst::composition::exceptions::InvalidCompositionError</a></div><divclass="ttdoc">Exception thrown when a composition is in an invalid or inconsistent state.</div><divclass="ttdef"><b>Definition</b><ahref="exceptions__composition_8h_source.html#l00041">exceptions_composition.h:41</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1exceptions_1_1_unknown_symbol_error_html"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1exceptions_1_1_unknown_symbol_error.html">fourdst::composition::exceptions::UnknownSymbolError</a></div><divclass="ttdoc">Exception thrown when an unknown symbol is encountered.</div><divclass="ttdef"><b>Definition</b><ahref="exceptions__composition_8h_source.html#l00077">exceptions_composition.h:77</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#l00051">exceptions_composition.h:51</a></div></div>
<p>The library surfaces errors through a focused hierarchy in <code><aclass="el"href="namespacefourdst_1_1composition_1_1exceptions.html">fourdst::composition::exceptions</a></code>:</p>
<tableclass="markdownTable">
<trclass="markdownTableHead">
<thclass="markdownTableHeadNone">Exception Type </th><thclass="markdownTableHeadNone">When It Occurs </th></tr>
<trclass="markdownTableRowOdd">
<tdclass="markdownTableBodyNone"><code>UnknownSymbolError</code></td><tdclass="markdownTableBodyNone">A string symbol does not correspond to any known isotope in the compiled species database. </td></tr>
<trclass="markdownTableRowEven">
<tdclass="markdownTableBodyNone"><code>UnregisteredSymbolError</code></td><tdclass="markdownTableBodyNone">A valid species/symbol is used before being registered with a Composition instance. </td></tr>
<trclass="markdownTableRowOdd">
<tdclass="markdownTableBodyNone"><code>InvalidCompositionError</code></td><tdclass="markdownTableBodyNone">Construction from mass fractions fails validation (sum deviates from unity beyond tolerance) or canonical (X+Y+Z) check fails. </td></tr>
<trclass="markdownTableRowEven">
<tdclass="markdownTableBodyNone"><code>CompositionError</code></td><tdclass="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>
<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>
<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><aclass="el"href="namespacefourdst_1_1composition.html"title="Utilities and types for representing and manipulating chemical compositions.">fourdst::composition</a></code>, <code><aclass="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><aclass="el"href="classfourdst_1_1composition_1_1_composition.html"title="Manages a collection of chemical species and their abundances.">fourdst::composition::Composition</a></code>, <code>fourdst::composition::CompositionAbstract</code></li>
<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>
