IsoSpecPy 2.4.0__tar.gz → 2.5.0__tar.gz

{isospecpy-2.4.0 → isospecpy-2.5.0}/PKG-INFO

@@ -1,19 +1,27 @@
 Metadata-Version: 2.4
 Name: IsoSpecPy
-Version: 2.4.0
+Version: 2.5.0
 Summary: IsoSpecPy is a Python library for computing isotopic distributions of molecules.
 Keywords: isotopic distribution,mass spectrometry,chemistry,isotopic envelope,isotopologues
 Author: Michał Startek, Mateusz Łącki
 License-Expression: BSD-2-Clause
 License-File: LICENCE
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Operating System :: OS Independent
 Project-URL: Homepage, https://github.com/MatteoLacki/IsoSpec
 Project-URL: Repository, https://github.com/MatteoLacki/IsoSpec
-Requires-Python: >=3.6
+Requires-Python: >=3.9
 Requires-Dist: cffi
 Provides-Extra: testing
 Requires-Dist: pytest; extra == "testing"
@@ -34,7 +42,7 @@ IsoSpec is primarily used as a library by mass spectrometry software. It is impl
 pip install IsoSpecPy
 ```
 
-The wheel bundles the C++ library — no separate native install required. Compatible with CPython and PyPy on Linux, macOS, Windows, and Cygwin/MinGW. Python ≥ 3.6.
+The wheel bundles the C++ library — no separate native install required. Compatible with CPython and PyPy on Linux, macOS, Windows, and Cygwin/MinGW. Python ≥ 3.9.
 
 To build from source: `pip install .` from a checkout. A C++20 compiler is required.
 
@@ -78,12 +86,33 @@ iso = IsoSpecPy.IsoTotalProb(formula="H2O1", prob_to_cover=0.999)
 for mass, prob in zip(iso.masses, iso.probs):
     print(mass, prob)
 
-# From an amino-acid FASTA sequence:
-iso = IsoSpecPy.IsoTotalProb(fasta="AAAPPGQAAC", prob_to_cover=0.999)
+# From an amino-acid sequence:
+iso = IsoSpecPy.IsoTotalProb(peptide_sequence="AAAPPGQAAC", prob_to_cover=0.999)
 print(list(zip(iso.masses, iso.probs)))
+
+# ...optionally carrying [UNIMOD:<id>] modification tags (the notation this
+# monorepo's SAGE search-engine fork writes: [UNIMOD:<id>]-SEQUENCE prefix
+# for an N-terminal mod, X[UNIMOD:<id>] inline for an internal one,
+# SEQUENCE-[UNIMOD:<id>] suffix for a C-terminal one):
+iso = IsoSpecPy.IsoTotalProb(peptide_sequence="PEPTC[UNIMOD:4]DEK", prob_to_cover=0.999)
+print(list(zip(iso.masses, iso.probs)))
+
+# Mind the water: peptide_sequence= yields the *residue* composition, without
+# the terminal H2O of a free peptide, so the masses above are 18.0106 Da
+# lighter than the neutral molecule. Add it explicitly for the real peptide
+# (the C++ Iso::FromFASTAWithMods below adds it by default -- the two APIs
+# differ here, and this is the older Python behaviour kept for compatibility):
+iso = IsoSpecPy.IsoTotalProb(peptide_sequence="PEPTC[UNIMOD:4]DEK", formula="H2O1",
+                             prob_to_cover=0.999)
+
+# Or get just the composition (element -> atom count), no envelope:
+composition = IsoSpecPy.ParsePeptideSequence("PEPTC[UNIMOD:4]DEK")
+print(dict(composition))  # {'H': 60, 'C': 39, 'N': 10, 'O': 16, 'S': 1}
 ```
 
-See `Examples/Python/` for radiolabelling, custom elements, binned spectra, and FASTA modifications.
+Resolves against a table of ~980 Unimod entries embedded in the library (isotope-labelled and glycan/derivatization "brick" modifications are excluded -- they aren't representable as a pure elemental delta). Pass `unimod_db_path="/path/to/table.csv"` to either function to resolve against a different table instead (same `id,name,mono_mass,composition` CSV shape as the embedded default).
+
+See `Examples/Python/` for radiolabelling, custom elements, binned spectra, and FASTA/Unimod modifications.
 
 ### C++
 
@@ -102,6 +131,27 @@ int main() {
 }
 ```
 
+From a peptide sequence, optionally carrying `[UNIMOD:<id>]` modification tags (`fasta_mods.h`; same notation as the Python/R examples above):
+
+```cpp
+#include "IsoSpec++/isoSpec++.h"
+#include "IsoSpec++/fasta_mods.h"
+#include "IsoSpec++/fixedEnvelopes.h"
+
+using namespace IsoSpec;
+
+int main() {
+    FixedEnvelope iso = FixedEnvelope::FromTotalProb(
+        Iso::FromFASTAWithMods("PEPTC[UNIMOD:4]DEK"), 0.999, true, true);
+
+    for (size_t i = 0; i < iso.confs_no(); ++i) {
+        std::cout << iso.mass(i) << '\t' << iso.prob(i) << '\n';
+    }
+}
+```
+
+`Iso::FromFASTAWithMods` takes an optional trailing `unimod_db_path` argument to resolve against a different Unimod table instead of the one embedded at compile time. For just the composition, no envelope, call `parse_fasta_with_mods`/`parse_fasta_with_mods_full` directly (or the allocation-free `_into` forms, for a hot loop over many sequences) — see `fasta_mods.h`.
+
 Quickest way to build:
 
 ```bash
@@ -118,7 +168,18 @@ water <- c(H = 2, O = 1)
 IsoSpecify(molecule = water, stopCondition = 0.999)
 ```
 
-See `Examples/R/` for radiolabelling and full-spectrum extraction.
+`IsoSpecify` only ever takes a raw named-integer-vector `molecule` -- it has no sequence-string parameter -- so a `[UNIMOD:<id>]`-annotated peptide sequence takes two calls instead of one: `RParsePeptideSequence()` to resolve the sequence into a composition, then `IsoSpecify()` as above.
+
+```r
+composition <- RParsePeptideSequence("PEPTC[UNIMOD:4]DEK")
+print(composition)  #  H  C  N  O  S
+                     # 60 39 10 16  1
+IsoSpecify(molecule = composition, stopCondition = 0.999)
+```
+
+Like the Python `ParsePeptideSequence`, this returns the residue composition without a free peptide's terminal H2O -- add `c(H = 2, O = 1)` to it for the neutral molecule. A modification whose delta removes more atoms of an element than the bare sequence provides gives a negative count (`"G[UNIMOD:11]"` nets `H -1`, `S -1`); `IsoSpecify` rejects such a vector rather than quietly dropping those elements.
+
+See `Examples/R/` for radiolabelling, full-spectrum extraction, and Unimod-annotated sequences.
 
 ## Advanced features
 
@@ -126,7 +187,7 @@ See `Examples/R/` for radiolabelling and full-spectrum extraction.
   - `IsoThreshold` — all isotopologues with probability above a fixed threshold.
   - `IsoStochastic` — simulate a measured spectrum by sampling integer ion counts.
   - `IsoBinned` — histogram-style envelope at a chosen bin width.
-- **FASTA support** — build an `Iso` directly from an amino-acid sequence; optionally include the N/C-terminal water.
+- **FASTA/peptide-sequence support** — build an `Iso` directly from an amino-acid sequence, with `[UNIMOD:<id>]` modification tags recognized inline; optionally include the N/C-terminal water.
 - **Custom isotopic tables** — override natural abundances per element (e.g. for radio- or stable-isotope labelling). See `Examples/*/radiolabelling.*`.
 - **Fixed-envelope arithmetic** — addition, normalization, convolution, Wasserstein distance.
 - **Nominal-mass mode** — compute distributions over nucleon counts instead of real masses.

{isospecpy-2.4.0 → isospecpy-2.5.0}/README.md

@@ -12,7 +12,7 @@ IsoSpec is primarily used as a library by mass spectrometry software. It is impl
 pip install IsoSpecPy
 ```
 
-The wheel bundles the C++ library — no separate native install required. Compatible with CPython and PyPy on Linux, macOS, Windows, and Cygwin/MinGW. Python ≥ 3.6.
+The wheel bundles the C++ library — no separate native install required. Compatible with CPython and PyPy on Linux, macOS, Windows, and Cygwin/MinGW. Python ≥ 3.9.
 
 To build from source: `pip install .` from a checkout. A C++20 compiler is required.
 
@@ -56,12 +56,33 @@ iso = IsoSpecPy.IsoTotalProb(formula="H2O1", prob_to_cover=0.999)
 for mass, prob in zip(iso.masses, iso.probs):
     print(mass, prob)
 
-# From an amino-acid FASTA sequence:
-iso = IsoSpecPy.IsoTotalProb(fasta="AAAPPGQAAC", prob_to_cover=0.999)
+# From an amino-acid sequence:
+iso = IsoSpecPy.IsoTotalProb(peptide_sequence="AAAPPGQAAC", prob_to_cover=0.999)
 print(list(zip(iso.masses, iso.probs)))
+
+# ...optionally carrying [UNIMOD:<id>] modification tags (the notation this
+# monorepo's SAGE search-engine fork writes: [UNIMOD:<id>]-SEQUENCE prefix
+# for an N-terminal mod, X[UNIMOD:<id>] inline for an internal one,
+# SEQUENCE-[UNIMOD:<id>] suffix for a C-terminal one):
+iso = IsoSpecPy.IsoTotalProb(peptide_sequence="PEPTC[UNIMOD:4]DEK", prob_to_cover=0.999)
+print(list(zip(iso.masses, iso.probs)))
+
+# Mind the water: peptide_sequence= yields the *residue* composition, without
+# the terminal H2O of a free peptide, so the masses above are 18.0106 Da
+# lighter than the neutral molecule. Add it explicitly for the real peptide
+# (the C++ Iso::FromFASTAWithMods below adds it by default -- the two APIs
+# differ here, and this is the older Python behaviour kept for compatibility):
+iso = IsoSpecPy.IsoTotalProb(peptide_sequence="PEPTC[UNIMOD:4]DEK", formula="H2O1",
+                             prob_to_cover=0.999)
+
+# Or get just the composition (element -> atom count), no envelope:
+composition = IsoSpecPy.ParsePeptideSequence("PEPTC[UNIMOD:4]DEK")
+print(dict(composition))  # {'H': 60, 'C': 39, 'N': 10, 'O': 16, 'S': 1}
 ```
 
-See `Examples/Python/` for radiolabelling, custom elements, binned spectra, and FASTA modifications.
+Resolves against a table of ~980 Unimod entries embedded in the library (isotope-labelled and glycan/derivatization "brick" modifications are excluded -- they aren't representable as a pure elemental delta). Pass `unimod_db_path="/path/to/table.csv"` to either function to resolve against a different table instead (same `id,name,mono_mass,composition` CSV shape as the embedded default).
+
+See `Examples/Python/` for radiolabelling, custom elements, binned spectra, and FASTA/Unimod modifications.
 
 ### C++
 
@@ -80,6 +101,27 @@ int main() {
 }
 ```
 
+From a peptide sequence, optionally carrying `[UNIMOD:<id>]` modification tags (`fasta_mods.h`; same notation as the Python/R examples above):
+
+```cpp
+#include "IsoSpec++/isoSpec++.h"
+#include "IsoSpec++/fasta_mods.h"
+#include "IsoSpec++/fixedEnvelopes.h"
+
+using namespace IsoSpec;
+
+int main() {
+    FixedEnvelope iso = FixedEnvelope::FromTotalProb(
+        Iso::FromFASTAWithMods("PEPTC[UNIMOD:4]DEK"), 0.999, true, true);
+
+    for (size_t i = 0; i < iso.confs_no(); ++i) {
+        std::cout << iso.mass(i) << '\t' << iso.prob(i) << '\n';
+    }
+}
+```
+
+`Iso::FromFASTAWithMods` takes an optional trailing `unimod_db_path` argument to resolve against a different Unimod table instead of the one embedded at compile time. For just the composition, no envelope, call `parse_fasta_with_mods`/`parse_fasta_with_mods_full` directly (or the allocation-free `_into` forms, for a hot loop over many sequences) — see `fasta_mods.h`.
+
 Quickest way to build:
 
 ```bash
@@ -96,7 +138,18 @@ water <- c(H = 2, O = 1)
 IsoSpecify(molecule = water, stopCondition = 0.999)
 ```
 
-See `Examples/R/` for radiolabelling and full-spectrum extraction.
+`IsoSpecify` only ever takes a raw named-integer-vector `molecule` -- it has no sequence-string parameter -- so a `[UNIMOD:<id>]`-annotated peptide sequence takes two calls instead of one: `RParsePeptideSequence()` to resolve the sequence into a composition, then `IsoSpecify()` as above.
+
+```r
+composition <- RParsePeptideSequence("PEPTC[UNIMOD:4]DEK")
+print(composition)  #  H  C  N  O  S
+                     # 60 39 10 16  1
+IsoSpecify(molecule = composition, stopCondition = 0.999)
+```
+
+Like the Python `ParsePeptideSequence`, this returns the residue composition without a free peptide's terminal H2O -- add `c(H = 2, O = 1)` to it for the neutral molecule. A modification whose delta removes more atoms of an element than the bare sequence provides gives a negative count (`"G[UNIMOD:11]"` nets `H -1`, `S -1`); `IsoSpecify` rejects such a vector rather than quietly dropping those elements.
+
+See `Examples/R/` for radiolabelling, full-spectrum extraction, and Unimod-annotated sequences.
 
 ## Advanced features
 
@@ -104,7 +157,7 @@ See `Examples/R/` for radiolabelling and full-spectrum extraction.
   - `IsoThreshold` — all isotopologues with probability above a fixed threshold.
   - `IsoStochastic` — simulate a measured spectrum by sampling integer ion counts.
   - `IsoBinned` — histogram-style envelope at a chosen bin width.
-- **FASTA support** — build an `Iso` directly from an amino-acid sequence; optionally include the N/C-terminal water.
+- **FASTA/peptide-sequence support** — build an `Iso` directly from an amino-acid sequence, with `[UNIMOD:<id>]` modification tags recognized inline; optionally include the N/C-terminal water.
 - **Custom isotopic tables** — override natural abundances per element (e.g. for radio- or stable-isotope labelling). See `Examples/*/radiolabelling.*`.
 - **Fixed-envelope arithmetic** — addition, normalization, convolution, Wasserstein distance.
 - **Nominal-mass mode** — compute distributions over nucleon counts instead of real masses.

isospecpy-2.5.0/VERSION

@@ -0,0 +1 @@
+2.5.0

{isospecpy-2.4.0 → isospecpy-2.5.0}/pyproject.toml

@@ -13,6 +13,15 @@ regex = "^\\s*(?P<value>[0-9]+(?:\\.[0-9]+)*)"
 
 [tool.scikit-build]
 cmake.source-dir = "skbuild"
+# The compiled part is not a Python extension module: it is a plain C-ABI
+# shared library that isoFFI.py dlopen()s through cffi's ABI mode, and it never
+# includes Python.h or links libpython. So the wheel is tagged py3-none-<plat>
+# rather than per-interpreter (cp3XX) or Stable ABI (abi3): one binary per
+# platform serves every CPython -- free-threaded builds included, which abi3
+# does not cover -- and PyPy too. cibuildwheel builds it once per platform and
+# only *tests* it under each remaining interpreter. Should the library ever
+# start using the CPython API, this must go back to per-interpreter tags.
+wheel.py-api = "py3"
 
 [project]
 name = "IsoSpecPy"
@@ -23,10 +32,18 @@ license = "BSD-2-Clause"
 license-files = ["LICENCE"]
 authors = [{name = "Michał Startek"}, {name = "Mateusz Łącki"}]
 readme = "README.md"
-requires-python = ">=3.6"
+requires-python = ">=3.9"
 classifiers = [
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.6",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Development Status :: 5 - Production/Stable",
     "Operating System :: OS Independent",

{isospecpy-2.4.0 → isospecpy-2.5.0}/src/IsoSpec++/aligned_ptr.h

@@ -1,3 +1,19 @@
+/*
+ *   Copyright (C) 2026 Mateusz Łącki and Michał Startek.
+ *
+ *   This file is part of IsoSpec.
+ *
+ *   IsoSpec is free software: you can redistribute it and/or modify
+ *   it under the terms of the Simplified ("2-clause") BSD licence.
+ *
+ *   IsoSpec is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ *   You should have received a copy of the Simplified BSD Licence
+ *   along with IsoSpec.  If not, see <https://opensource.org/licenses/BSD-2-Clause>.
+ */
+
 #pragma once
 
 #include <cstddef>      // std::size_t, std::nullptr_t
@@ -311,7 +327,7 @@ inline void vm_resize(vm_region& r, std::size_t new_bytes)
 
 template<class T, std::size_t Alignment>
 class aligned_unique_ptr {
-    static_assert((Alignment & (Alignment - 1)) == 0); // meaning: Alignment is a power of two
+    static_assert((Alignment & (Alignment - 1)) == 0);  // meaning: Alignment is a power of two
     static_assert(Alignment >= alignof(T));
     static_assert(Alignment <= 4096, "Alignment must not exceed the smallest page size assumed across supported platforms");
     // Storage is acquired/released as raw bytes (aligned_alloc/free, or
@@ -396,7 +412,7 @@ class aligned_unique_ptr {
         free_small(p);
     }
 
-public:
+ public:
     static constexpr std::size_t alignment = Alignment;
 
     // Returned by release_with_deleter(): the raw pointer plus everything

{isospecpy-2.4.0 → isospecpy-2.5.0}/src/IsoSpec++/btrd.h

@@ -93,7 +93,7 @@ IntType btrd(IntType _t, RealType p, IntType m, std::mt19937& urng = random_gen)
 
     while(true) {
         RealType u;
-        RealType v = stdunif(urng);
+        RealType v = rdvariate_unif01(urng);
         if(v <= btrd_u_rv_r) {
             u = v/btrd_v_r - 0.43;
             return static_cast<IntType>(floor(
@@ -101,11 +101,11 @@ IntType btrd(IntType _t, RealType p, IntType m, std::mt19937& urng = random_gen)
         }
 
         if(v >= btrd_v_r) {
-            u = stdunif(urng) - 0.5;
+            u = rdvariate_unif01(urng) - 0.5;
         } else {
             u = v/btrd_v_r - 0.93;
             u = ((u < 0)? -0.5 : 0.5) - u;
-            v = stdunif(urng) * btrd_v_r;
+            v = rdvariate_unif01(urng) * btrd_v_r;
         }
 
         RealType us = 0.5 - abs(u);
@@ -163,7 +163,7 @@ IntType invert(IntType t, RealType p, std::mt19937& urng = random_gen)
     RealType s = p / q;
     RealType a = (t + 1) * s;
     RealType r = pow((1 - p), static_cast<RealType>(t));
-    RealType u = stdunif(urng);
+    RealType u = rdvariate_unif01(urng);
     IntType x = 0;
     while(u > r) {
         u = u - r;

isospecpy-2.5.0/src/IsoSpec++/composition.cpp

@@ -0,0 +1,85 @@
+/*
+ *   Copyright (C) 2015-2026 Mateusz Łącki and Michał Startek.
+ *
+ *   This file is part of IsoSpec.
+ *
+ *   IsoSpec is free software: you can redistribute it and/or modify
+ *   it under the terms of the Simplified ("2-clause") BSD licence.
+ *
+ *   IsoSpec is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ *   You should have received a copy of the Simplified BSD Licence
+ *   along with IsoSpec.  If not, see <https://opensource.org/licenses/BSD-2-Clause>.
+ */
+
+#include "composition.h"
+
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+#include "element_lookup.h"
+#include "element_tables.h"
+
+namespace IsoSpec {
+
+void expand_composition_into(const ElementComposition& composition, ExpandedComposition& out,
+                             bool use_nominal_masses) {
+    out.clear();
+
+    const size_t dimNumber = composition.element_first_index.size();
+    const double* masses_table = use_nominal_masses ? elem_table_massNo : elem_table_mass;
+
+    out.isotopeNumbers.reserve(dimNumber);
+    out.atomCounts.reserve(dimNumber);
+
+    for (size_t i = 0; i < dimNumber; i++) {
+        const int first_idx = composition.element_first_index[i];
+        const int num_isotopes = element_isotope_count(first_idx);
+        out.isotopeNumbers.push_back(num_isotopes);
+        out.atomCounts.push_back(composition.count[i]);
+        for (int k = 0; k < num_isotopes; k++) {
+            out.isotope_masses.push_back(masses_table[first_idx + k]);
+            out.isotope_probabilities.push_back(elem_table_probability[first_idx + k]);
+        }
+    }
+}
+
+void reject_negative_counts(const ElementComposition& composition) {
+    std::string offenders;
+    for (size_t i = 0; i < composition.count.size(); i++) {
+        if (composition.count[i] < 0) {
+            if (!offenders.empty())
+                offenders += ", ";
+            offenders += elem_table_symbol[composition.element_first_index[i]];
+        }
+    }
+
+    if (offenders.empty())
+        return;
+
+    throw std::invalid_argument(
+        "Negative atom count for element(s): " + offenders +
+        " -- a molecule can't contain a negative number of atoms. Signed counts are only "
+        "meaningful for a modification's composition delta (where a mod may remove more of an "
+        "element than the rest of the molecule provides), never for a molecule itself.");
+}
+
+Iso build_iso_from_composition(const ElementComposition& composition, bool use_nominal_masses) {
+    // Checked here rather than in expand_composition_into: a negative count is
+    // a perfectly good intermediate in a composition (a modification's delta
+    // can outweigh the bare sequence), and only becomes an error where the
+    // composition becomes a molecule -- which is here.
+    reject_negative_counts(composition);
+
+    ExpandedComposition expanded;
+    expand_composition_into(composition, expanded, use_nominal_masses);
+
+    return Iso(static_cast<int>(expanded.atomCounts.size()), expanded.isotopeNumbers.data(),
+               expanded.atomCounts.data(), expanded.isotope_masses.data(),
+               expanded.isotope_probabilities.data());
+}
+
+}  // namespace IsoSpec

isospecpy-2.5.0/src/IsoSpec++/composition.h

@@ -0,0 +1,126 @@
+/*
+ *   Copyright (C) 2015-2026 Mateusz Łącki and Michał Startek.
+ *
+ *   This file is part of IsoSpec.
+ *
+ *   IsoSpec is free software: you can redistribute it and/or modify
+ *   it under the terms of the Simplified ("2-clause") BSD licence.
+ *
+ *   IsoSpec is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ *   You should have received a copy of the Simplified BSD Licence
+ *   along with IsoSpec.  If not, see <https://opensource.org/licenses/BSD-2-Clause>.
+ */
+
+// The library's vocabulary for "a molecule as element counts", and the one
+// implementation of turning that into the isotope masses and probabilities an
+// Iso is built from.
+//
+// This lives in its own header because three unrelated things need it: the
+// formula parser (isoSpec++.cpp), the peptide-sequence parsers (fasta_mods.h),
+// and the C ABI (cwrapper.cpp). It used to sit inside fasta_mods.h, which
+// meant the core formula path could only share the resolution by including a
+// peptide-modification header -- backwards, so it didn't, and kept its own
+// copy instead. See docs/ai/composition_expansion.md.
+
+#pragma once
+
+#include <vector>
+
+#include "isoSpec++.h"
+
+namespace IsoSpec {
+
+//! A resolved elemental composition: parallel arrays of
+//! (element_table_first_index, count) pairs, one per element actually
+//! present (non-zero net count).
+//!
+//! Counts are *signed*, and parse_fasta_with_mods/_full really can return a
+//! negative one: a modification's composition delta may remove more atoms of
+//! some element than the bare sequence provides ("G[UNIMOD:11]" nets H-1
+//! S-1). That is a legitimate intermediate -- adding a second modification
+//! could bring it back up -- so the parser does not reject it. The
+//! non-negativity check belongs at the point a composition becomes a
+//! molecule, and lives in build_iso_from_composition; anything else
+//! consuming an ElementComposition directly (the C ABI's
+//! parseFastaWithModsC, R's RParsePeptideSequence) must do its own check
+//! before handing the counts to an Iso.
+struct ElementComposition {
+    std::vector<int> element_first_index;
+    std::vector<int> count;
+
+    //! Empties both vectors without releasing their capacity -- a caller
+    //! that reuses one ElementComposition across many parse_fasta_with_mods_into
+    //! calls (e.g. building a cache over millions of peptides) pays for the
+    //! underlying heap allocation at most a handful of times total (until
+    //! capacity reaches this feature's real ceiling, ~30 elements), not once
+    //! per call the way the value-returning parse_fasta_with_mods does.
+    void clear() {
+        element_first_index.clear();
+        count.clear();
+    }
+};
+
+//! A composition expanded to the flat, per-isotope form the generic
+//! Iso(dimNumber, isotopeNumbers, atomCounts, masses, probs) constructor
+//! takes: one isotopeNumbers/atomCounts entry per element of the
+//! composition, and one isotope_masses/isotope_probabilities entry per
+//! isotope, element-major, in the composition's own order. Exactly the
+//! layout the C ABI's setupIso expects, since that constructor is what it
+//! forwards to.
+struct ExpandedComposition {
+    std::vector<int> isotopeNumbers;
+    std::vector<int> atomCounts;
+    std::vector<double> isotope_masses;
+    std::vector<double> isotope_probabilities;
+
+    //! Empties all four vectors without releasing their capacity -- same
+    //! reuse contract, for the same reason, as ElementComposition::clear
+    //! above.
+    void clear() {
+        isotopeNumbers.clear();
+        atomCounts.clear();
+        isotope_masses.clear();
+        isotope_probabilities.clear();
+    }
+};
+
+//! Resolves each element of `composition` to its isotopes' masses and
+//! probabilities from element_tables.h, filling a caller-owned `out`
+//! (cleared first).
+//!
+//! The single implementation of that resolution. Everything that turns
+//! element counts into an Iso goes through here: parse_formula (the formula
+//! string path), build_iso_from_composition (the peptide-sequence path), and
+//! cwrapper.h's expandCompositionC -- which exists so that a binding
+//! language need not carry its own copy of the periodic table either.
+//! IsoSpecPy did carry one (IsoParamsFromDict, walking PeriodicTbl's
+//! symbol->isotopes dicts) until that entry point existed.
+//!
+//! Counts are copied through unchanged, negatives included: expanding a
+//! composition is not the same as making a molecule out of one, and the
+//! non-negativity check belongs at the latter -- see ElementComposition's
+//! note above, and build_iso_from_composition, which does check.
+void expand_composition_into(const ElementComposition& composition, ExpandedComposition& out,
+                             bool use_nominal_masses = false);
+
+//! Throws std::invalid_argument if any of `composition`'s counts is
+//! negative, naming the offending elements. The check every path from a
+//! composition to an Iso has to make: a negative atom count reaching Iso's
+//! constructor is not merely a wrong answer but undefined behaviour --
+//! Marginal::computeModeConf() sizes its configuration buffer from the count
+//! and writeInitialConfiguration then walks off the end of it (ASan catches
+//! it as a heap-buffer-overflow).
+void reject_negative_counts(const ElementComposition& composition);
+
+//! Resolves a composition (as returned by parse_fasta_with_mods[_full]) into
+//! an Iso via the same generic Iso(dimNumber, isotopeNumbers, atomCounts,
+//! masses, probs) constructor parse_formula uses. Throws
+//! std::invalid_argument if any accumulated element count is negative (a
+//! modification set that removes more atoms of some element than the base
+//! sequence plus other modifications provide).
+Iso build_iso_from_composition(const ElementComposition& composition, bool use_nominal_masses = false);
+
+}  // namespace IsoSpec