284 lines
10 KiB
Markdown
284 lines
10 KiB
Markdown
@mainpage libcomposition: A Modern C++ Library for Chemical Compositions
|
||
|
||
@section intro_sec Introduction
|
||
|
||
`libcomposition` 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). `libcomposition` is designed to be tighly integrated into SERiF and related
|
||
projects such as GridFire.
|
||
|
||
### Key Features
|
||
|
||
- **Type–Safe Species Representation**: Strongly typed isotopes (`fourdst::atomic::Species`) generated from evaluated nuclear data (AME2020 / NUBASE2020).
|
||
- **Molar Abundance Core**: Stores absolute molar abundances and derives all secondary quantities (mass / number fractions, mean particle mass, electron abundance) on demand, with internal caching.
|
||
- **Canonical Composition Support**: Direct computation of canonical (X: Hydrogen, Y: Helium, Z: Metals) mass fractions via `getCanonicalComposition()`.
|
||
- **Convenience Construction**: Helper utilities for constructing compositions from a vector or set of mass fractions (`buildCompositionFromMassFractions`).
|
||
- **Deterministic Ordering**: Species are always stored and iterated lightest→heaviest (ordering defined by atomic mass) enabling uniform vector interfaces.
|
||
- **Clear Exception Hierarchy**: Explicit error signaling for invalid symbols, unregistered species, and inconsistent input data.
|
||
- **Meson + pkg-config Integration**: Simple build, install, and consumption in external projects.
|
||
|
||
---
|
||
|
||
@section install_sec Installation
|
||
|
||
`libcomposition` uses the Meson build system. A C++23 compatible compiler is required.
|
||
|
||
### Build Steps
|
||
|
||
**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 separated!
|
||
|
||
```bash
|
||
meson setup builddir
|
||
```
|
||
|
||
**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 might take some time (clang tends to be very fast for this).
|
||
|
||
```bash
|
||
meson compile -C builddir
|
||
```
|
||
|
||
**Install the library:**
|
||
|
||
This will also install a pkg-config file!
|
||
|
||
```bash
|
||
sudo meson install -C builddir
|
||
```
|
||
|
||
### Build Options
|
||
|
||
You can enable the generation of a `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 orchestrator (such as meson-python).
|
||
|
||
```bash
|
||
# Enable pkg-config file generation
|
||
meson setup builddir -Dpkg-config=true
|
||
```
|
||
|
||
---
|
||
|
||
@section usage_sec Usage
|
||
|
||
Below are focused examples illustrating the current API. All examples assume headers are available via pkg-config or your include path.
|
||
|
||
#### 1. Constructing a Composition from Symbols
|
||
|
||
```cpp
|
||
#include <iostream>
|
||
#include "fourdst/composition/composition.h"
|
||
|
||
int main() {
|
||
using namespace fourdst::composition;
|
||
|
||
// Register symbols upon construction (no molar abundances yet -> default 0.0)
|
||
Composition comp({"H-1", "He-4", "C-12"});
|
||
|
||
// Set molar abundances (absolute counts; they need not sum to 1.0)
|
||
comp.setMolarAbundance("H-1", 10.0);
|
||
comp.setMolarAbundance("He-4", 3.0);
|
||
comp.setMolarAbundance("C-12", 0.25);
|
||
|
||
// Query derived properties
|
||
double x_h1 = comp.getMassFraction("H-1");
|
||
double y_he4 = comp.getNumberFraction("He-4");
|
||
auto canon = comp.getCanonicalComposition(); // X, Y, Z mass fractions
|
||
|
||
std::cout << "H-1 mass fraction: " << x_h1 << "\n";
|
||
std::cout << "He-4 number fraction: " << y_he4 << "\n";
|
||
std::cout << canon << "\n"; // <CanonicalComposition: X=..., Y=..., Z=...>
|
||
}
|
||
```
|
||
|
||
#### 2. Constructing from Strongly Typed Species
|
||
|
||
```cpp
|
||
#include <iostream>
|
||
#include "fourdst/composition/composition.h"
|
||
#include "fourdst/atomic/species.h"
|
||
|
||
int main() {
|
||
using namespace fourdst::composition;
|
||
using namespace fourdst::atomic;
|
||
|
||
// Build directly from species constants
|
||
Composition comp(std::vector<Species>{H_1, He_4, O_16});
|
||
|
||
comp.setMolarAbundance(H_1, 5.0);
|
||
comp.setMolarAbundance(He_4, 2.5);
|
||
comp.setMolarAbundance(O_16, 0.1);
|
||
|
||
std::cout << "Mean particle mass: " << comp.getMeanParticleMass() << " g/mol\n";
|
||
std::cout << "Electron abundance (Ye): " << comp.getElectronAbundance() << "\n";
|
||
}
|
||
```
|
||
|
||
#### 3. Building from Mass Fractions (Helper Utility)
|
||
|
||
```cpp
|
||
#include <iostream>
|
||
#include "fourdst/composition/utils.h"
|
||
|
||
int main() {
|
||
using namespace fourdst::composition;
|
||
|
||
std::vector<std::string> symbols = {"H-1", "He-4", "C-12"};
|
||
std::vector<double> mf = {0.70, 0.28, 0.02}; // Must sum to ~1 within tolerance
|
||
|
||
Composition comp = buildCompositionFromMassFractions(symbols, mf);
|
||
|
||
auto canon = comp.getCanonicalComposition();
|
||
std::cout << canon << "\n";
|
||
}
|
||
```
|
||
|
||
#### 4. Iterating and Sorted Vector Interfaces
|
||
|
||
```cpp
|
||
#include <iostream>
|
||
#include "fourdst/composition/composition.h"
|
||
|
||
int main() {
|
||
using namespace fourdst::composition;
|
||
|
||
Composition comp({"H-1", "C-12", "He-4"}); // Internally sorted by mass (H < He < C)
|
||
comp.setMolarAbundance({"H-1", "He-4", "C-12"}, {10.0, 3.0, 0.25});
|
||
|
||
// Ordered iteration (lightest -> heaviest)
|
||
for (const auto &[sp, y] : comp) {
|
||
std::cout << sp << ": molar = " << y << "\n";
|
||
}
|
||
|
||
// Vector access (index corresponds to ordering by atomic mass)
|
||
auto molarVec = comp.getMolarAbundanceVector();
|
||
auto massVec = comp.getMassFractionVector();
|
||
|
||
size_t idx_he4 = comp.getSpeciesIndex("He-4");
|
||
std::cout << "He-4 index: " << idx_he4 << ", molar abundance at index: " << molarVec[idx_he4] << "\n";
|
||
}
|
||
```
|
||
|
||
#### 5. Accessing Specific Derived Quantities
|
||
|
||
```cpp
|
||
// Assume 'comp' is already populated.
|
||
|
||
double mf_c12 = comp.getMassFraction("C-12");
|
||
double nf_c12 = comp.getNumberFraction("C-12");
|
||
double mol_c12 = comp.getMolarAbundance("C-12");
|
||
double meanA = comp.getMeanParticleMass();
|
||
double Ye = comp.getElectronAbundance();
|
||
auto canon = comp.getCanonicalComposition();
|
||
```
|
||
|
||
#### 6. Exception Handling Examples
|
||
|
||
```cpp
|
||
#include <iostream>
|
||
#include "fourdst/composition/composition.h"
|
||
#include "fourdst/composition/exceptions/exceptions_composition.h"
|
||
|
||
int main() {
|
||
using namespace fourdst::composition;
|
||
using namespace fourdst::composition::exceptions;
|
||
|
||
Composition comp;
|
||
|
||
try {
|
||
// Unknown symbol (not in species database)
|
||
comp.registerSymbol("Xx-999");
|
||
} catch (const UnknownSymbolError &e) {
|
||
std::cerr << "Caught UnknownSymbolError: " << e.what() << "\n";
|
||
}
|
||
|
||
comp.registerSymbol("H-1");
|
||
try {
|
||
// Unregistered symbol used in a setter
|
||
comp.setMolarAbundance("He-4", 1.0); // He-4 not registered yet
|
||
} catch (const UnregisteredSymbolError &e) {
|
||
std::cerr << "Caught UnregisteredSymbolError: " << e.what() << "\n";
|
||
}
|
||
|
||
comp.registerSymbol("He-4");
|
||
try {
|
||
comp.setMolarAbundance("H-1", -3.0);
|
||
} catch (const InvalidCompositionError &e) {
|
||
std::cerr << "Caught InvalidCompositionError: " << e.what() << "\n";
|
||
}
|
||
|
||
// Mass fraction construction validation
|
||
try {
|
||
Composition bad = buildCompositionFromMassFractions({"H-1", "He-4"}, {0.6, 0.5}); // sums to 1.1
|
||
} catch (const InvalidCompositionError &e) {
|
||
std::cerr << "Caught InvalidCompositionError: " << e.what() << "\n";
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
@section exceptions_sec Possible Exception States
|
||
|
||
The library surfaces errors through a focused hierarchy in `fourdst::composition::exceptions`:
|
||
|
||
| Exception Type | When It Occurs |
|
||
|----------------|----------------|
|
||
| `UnknownSymbolError` | A string symbol does not correspond to any known isotope in the compiled species database. |
|
||
| `UnregisteredSymbolError` | A valid species/symbol is used before being registered with a Composition instance. |
|
||
| `InvalidCompositionError` | Construction from mass fractions fails validation (sum deviates from unity beyond tolerance) or canonical (X+Y+Z) check fails. |
|
||
| `CompositionError` | Base class; may be thrown for generic composition-level issues (e.g. negative abundances via the documented `InvalidAbundanceError` contract). |
|
||
|
||
Recommended patterns:
|
||
- Validate externally provided symbol lists before calling bulk registration.
|
||
- Use species‑based overloads (strongly typed) where possible for slightly lower overhead (no symbol resolution).
|
||
- Wrap construction from mass fractions in a try/catch to surface normalization issues early.
|
||
|
||
---
|
||
|
||
@section api_sec Linking and Integration
|
||
|
||
### Linking with pkg-config
|
||
|
||
If you installed `libcomposition` with the `pkg-config` option enabled, you can get the necessary compiler and linker flags easily:
|
||
|
||
```bash
|
||
# Get compiler flags (include paths)
|
||
pkg-config --cflags fourdst_composition
|
||
|
||
# Get linker flags (library paths and names)
|
||
pkg-config --libs fourdst_composition
|
||
```
|
||
|
||
**Example compilation command:**
|
||
```bash
|
||
g++ my_app.cpp $(pkg-config --cflags --libs fourdst_composition) -o my_app
|
||
```
|
||
|
||
---
|
||
|
||
@section api_ref_sec API Reference
|
||
|
||
For a complete list of all classes, methods, and functions, see the **Namespaces** and **Classes** sections of this generated documentation.
|
||
|
||
- Namespace overview: `fourdst::composition`, `fourdst::atomic`
|
||
- Core classes: `fourdst::composition::Composition`, `fourdst::composition::CompositionAbstract`
|
||
- Helper utilities: `buildCompositionFromMassFractions`
|
||
- Exception hierarchy: `fourdst::composition::exceptions`
|
||
|
||
---
|
||
|
||
@section test_sec Testing Overview
|
||
|
||
The test suite (GoogleTest) exercises:
|
||
- Species database integrity (selected property spot checks).
|
||
- Registration and abundance setting (symbols vs species overloads).
|
||
- Mass fraction utility construction and validation tolerances.
|
||
- Canonical composition correctness (X + Y + Z ≈ 1.0).
|
||
- Vector interface ordering and index lookup consistency.
|
||
- Exception pathways for unknown/unregistered symbols and invalid compositions.
|
||
|
||
Use tolerances (e.g. 1e-12–1e-14) when comparing floating‑point derived quantities in custom tests.
|