\chapter{libcomposition\+: A Modern C++ Library for Chemical Compositions}
\hypertarget{index}{}\label{index}\index{libcomposition: A Modern C++ Library for Chemical Compositions@{libcomposition: A Modern C++ Library for Chemical Compositions}}
{\ttfamily libcomposition} 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.\hypertarget{index_autotoc_md0}{}\doxysubsubsection{\texorpdfstring{Key Features}{Key Features}}\label{index_autotoc_md0}
\begin{DoxyItemize}
\item{\bfseries{Dual-\/\+Mode Operation}}\+: Natively supports compositions defined by {\bfseries{mass fraction}} or {\bfseries{number fraction}}.
\item{\bfseries{Rich Atomic Database}}\+: Includes a comprehensive, header-\/only database of isotopic properties (mass, half-\/life, spin, etc.) generated from the AME2020 and NUBASE2020 evaluations.
\item{\bfseries{Type Safety and Error Handling}}\+: Utilizes a clear exception hierarchy to report errors, such as using an unregistered isotope or accessing data from a non-\/validated composition.
\item{\bfseries{Powerful Functionality}}\+: Core features include mixing, subsetting, and on-\/the-\/fly conversion between mass and number fractions.
\item{\bfseries{Easy Integration}}\+: Designed for seamless integration with other projects using the Meson build system and {\ttfamily pkg-\/config}.
{\ttfamily libcomposition} uses the Meson build system. A C++23 compatible compiler is required.\hypertarget{index_autotoc_md2}{}\doxysubsubsection{\texorpdfstring{Build Steps}{Build Steps}}\label{index_autotoc_md2}
{\bfseries{Setup the build directory\+:}}
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!
\begin{DoxyCode}{0}
\DoxyCodeLine{meson\ setup\ builddir}
\end{DoxyCode}
{\bfseries{Compile the library\+:}}
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).
You can enable the generation of a {\ttfamily pkg-\/config} 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).
\hypertarget{index_autotoc_md5}{}\doxysubsubsection{\texorpdfstring{Linking with pkg-\/config}{Linking with pkg-\/config}}\label{index_autotoc_md5}
If you installed {\ttfamily libcomposition} with the {\ttfamily pkg-\/config} option enabled, you can get the necessary compiler and linker flags easily\+:
\hypertarget{index_autotoc_md7}{}\doxysubsubsubsection{\texorpdfstring{1. Basic Mass Fraction Composition}{1. Basic Mass Fraction Composition}}\label{index_autotoc_md7}
The most common use case is defining a composition by mass fractions (X, Y, Z).
\hypertarget{index_autotoc_md8}{}\doxysubsubsubsection{\texorpdfstring{2. Number Fraction Composition and Mode Switching}{2. Number Fraction Composition and Mode Switching}}\label{index_autotoc_md8}
The library can also work with number (mole) fractions and switch between modes.
\hypertarget{index_autotoc_md9}{}\doxysubsubsubsection{\texorpdfstring{3. Mixing Two Compositions}{3. Mixing Two Compositions}}\label{index_autotoc_md9}
You can easily mix two compositions. The library handles the union of all species.
{\ttfamily libcomposition} is tested using the Google\+Test framework. The test suite provides high coverage of the library\textquotesingle{}s functionality.\hypertarget{index_autotoc_md13}{}\doxysubsubsection{\texorpdfstring{Test Coverage Includes\+:}{Test Coverage Includes\+:}}\label{index_autotoc_md13}
\begin{DoxyItemize}
\item{\bfseries{Atomic Data Validation}}\+: 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.
\item{\bfseries{Core {\ttfamily Composition} Workflow}}\+: 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.
\item{\bfseries{Finalization Logic}}\+: Ensures that {\ttfamily finalize()} is a required step before querying data. Tests the validation logic for compositions that sum to 1.\+0 and the auto-\/normalization feature ({\ttfamily finalize(true)}).
\item{\bfseries{Advanced Features}}\+: Dedicated tests for {\ttfamily mix()}, {\ttfamily subset()}, {\ttfamily set\+Composition\+Mode()}, and the calculation of derived quantities like {\ttfamily get\+Molar\+Abundance()} and {\ttfamily get\+Mean\+Atomic\+Number()}.
\item{\bfseries{Exception Handling}}\+: Confirms that invalid operations (e.\+g., using an unregistered symbol, mixing un-\/finalized compositions) correctly throw exceptions from the {\ttfamily\doxylink{namespacefourdst_1_1composition_1_1exceptions}{fourdst\+::composition\+::exceptions}} hierarchy.
For a complete list of all classes, methods, and functions, please see the \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}\href{namespaces.html}{\texttt{ Namespaces}}\texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*} and \texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*}\href{annotated.html}{\texttt{ Classes}}\texorpdfstring{$\ast$}{*}\texorpdfstring{$\ast$}{*} sections of this documentation.
