<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_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>
<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_1Composition_html"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.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#l00098">composition.h:98</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1Composition_html_a262d7133035d4e6f45daa81827abf5e7"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.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#l00580">composition.cpp:580</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_1Composition_html_aac5b214a3d1278e127422224cb9cee50"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.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#l00377">composition.cpp:377</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#l00084">utils.cpp:84</a></div></div>
<divclass="line"><aclass="code hl_class"href="classfourdst_1_1composition_1_1Composition.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_1Composition_html_a0d94f62402bb90b5d12679faeaa8c5d7"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.html#a0d94f62402bb90b5d12679faeaa8c5d7">fourdst::composition::Composition::getSpeciesIndex</a></div><divclass="ttdeci">size_t getSpeciesIndex(const std::string &symbol) const override</div><divclass="ttdoc">get the index in the sorted vector representation for a given symbol</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00485">composition.cpp:485</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1Composition_html_abcb391f5fca2b636127e48e681e4c3ee"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.html#abcb391f5fca2b636127e48e681e4c3ee">fourdst::composition::Composition::getMolarAbundanceVector</a></div><divclass="ttdeci">std::vector< double > getMolarAbundanceVector() const noexcept override</div><divclass="ttdoc">Get a uniform vector representation of the molar abundances stored in the composition object sorted s...</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00463">composition.cpp:463</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1Composition_html_af4f44aaf8b7e0d63872a70b5e2131369"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.html#af4f44aaf8b7e0d63872a70b5e2131369">fourdst::composition::Composition::getMassFractionVector</a></div><divclass="ttdeci">std::vector< double > getMassFractionVector() const noexcept override</div><divclass="ttdoc">Get a uniform vector representation of the mass fraction stored in the composition object sorted such...</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00420">composition.cpp:420</a></div></div>
<divclass="line"><spanclass="keywordtype">double</span> Ye = comp.<aclass="code hl_function"href="classfourdst_1_1composition_1_1Composition.html#a90fc71d1fe03017ee4c7a1cac69d24fb">getElectronAbundance</a>();</div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1Composition_html_a34f71d4d8f0297c576fd62fabd490305"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.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#l00307">composition.cpp:307</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1Composition_html_a90fc71d1fe03017ee4c7a1cac69d24fb"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.html#a90fc71d1fe03017ee4c7a1cac69d24fb">fourdst::composition::Composition::getElectronAbundance</a></div><divclass="ttdeci">double getElectronAbundance() const noexcept override</div><divclass="ttdoc">Compute the electron abundance of the composition.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00368">composition.cpp:368</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1Composition_html_a9ea2b673341fdc67afeb0f0517a54c8c"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.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#l00298">composition.cpp:298</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1Composition_html_add67a92d73e3a57a2bbdb52bc9ca3bfe"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.html#add67a92d73e3a57a2bbdb52bc9ca3bfe">fourdst::composition::Composition::getMolarAbundance</a></div><divclass="ttdeci">double getMolarAbundance(const std::string &symbol) const override</div><divclass="ttdoc">Gets the molar abundances of all species in the composition.</div><divclass="ttdef"><b>Definition</b><ahref="composition_8cpp_source.html#l00338">composition.cpp:338</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1Composition_html_afbbb5e51ad5ae5c0fa6bc0094195aecd"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.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#l00358">composition.cpp:358</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1Composition_html_a3ab4dcda0bfd1a35b169bcc57fe66725"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1Composition.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#l00225">composition.cpp:225</a></div></div>
<divclass="ttc"id="aclassfourdst_1_1composition_1_1exceptions_1_1CompositionError_html_ae44ceddb19da8a8cda7ee150b6826d08"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1exceptions_1_1CompositionError.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_1InvalidCompositionError_html"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1exceptions_1_1InvalidCompositionError.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_1UnknownSymbolError_html"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1exceptions_1_1UnknownSymbolError.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_1UnregisteredSymbolError_html"><divclass="ttname"><ahref="classfourdst_1_1composition_1_1exceptions_1_1UnregisteredSymbolError.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_1Composition.html"title="Manages a collection of chemical species and their abundances.">fourdst::composition::Composition</a></code>, <code><aclass="el"href="classfourdst_1_1composition_1_1CompositionAbstract.html"title="Abstract base class for chemical composition representations.">fourdst::composition::CompositionAbstract</a></code></li>
<liclass="footer">Generated by <ahref="https://www.doxygen.org/index.html"><imgclass="footer"src="doxygen.svg"width="104"height="31"alt="doxygen"/></a> 1.9.8 </li>
