IsoSpecPy 2.5.0__py3-none-win_arm64.whl

IsoSpecPy/IsoSpec++/btrd.h

@@ -0,0 +1,206 @@
+/* This file was taken from Boost, as permitted by Boost licence,
+ * with slight modifications. The reason is: we don't want to introduce
+ * dependency on the whole Boost just for this one thing.
+ *
+ * Source: boost random/binomial_distribution.hpp header file, at version 1.71
+ *
+ * Copyright Steven Watanabe 2010
+ * Distributed under the Boost Software License, Version 1.0. (See
+ * accompanying file LICENSE_1_0.txt or copy at
+ * http://www.boost.org/LICENSE_1_0.txt)
+ *
+ * See http://www.boost.org for most recent version including documentation.
+ *
+ */
+
+#pragma once
+
+#include "isoMath.h"
+#include <cstdlib>
+#include <cstdint>
+#include <cmath>
+#include <limits>
+
+
+namespace IsoSpec {
+
+typedef double RealType;
+typedef int64_t IntType;
+
+
+static const RealType btrd_binomial_table[10] = {
+    0.08106146679532726,
+    0.04134069595540929,
+    0.02767792568499834,
+    0.02079067210376509,
+    0.01664469118982119,
+    0.01387612882307075,
+    0.01189670994589177,
+    0.01041126526197209,
+    0.009255462182712733,
+    0.008330563433362871
+};
+
+
+/**
+ * The binomial distribution is an integer valued distribution with
+ * two parameters, @c t and @c p.  The values of the distribution
+ * are within the range [0,t].
+ *
+ * The distribution function is
+ * \f$\displaystyle P(k) = {t \choose k}p^k(1-p)^{t-k}\f$.
+ *
+ * The algorithm used is the BTRD algorithm described in
+ *
+ *  @blockquote
+ *  "The generation of binomial random variates", Wolfgang Hormann,
+ *  Journal of Statistical Computation and Simulation, Volume 46,
+ *  Issue 1 & 2 April 1993 , pages 101 - 110
+ *  @endblockquote
+ */
+
+
+// computes the correction factor for the Stirling approximation
+// for log(k!)
+static RealType fc(IntType k)
+{
+    if(k < 10) { return btrd_binomial_table[k]; }
+    else
+    {
+        RealType ikp1 = RealType(1) / (k + 1);
+        return (RealType(1)/12
+             - (RealType(1)/360
+             - (RealType(1)/1260)*(ikp1*ikp1))*(ikp1*ikp1))*ikp1;
+    }
+}
+
+IntType btrd(IntType _t, RealType p, IntType m, std::mt19937& urng = random_gen)
+{
+    using std::floor;
+    using std::abs;
+    using std::log;
+
+    RealType btrd_r = p/(1-p);
+    RealType btrd_nr = (_t+1)*btrd_r;
+    RealType btrd_npq = _t*p*(1-p);
+    RealType sqrt_npq = sqrt(btrd_npq);
+    RealType btrd_b = 1.15 + 2.53 * sqrt_npq;
+    RealType btrd_a = -0.0873 + 0.0248*btrd_b + 0.01*p;
+    RealType btrd_c = _t*p + 0.5;
+    RealType btrd_alpha = (2.83 + 5.1/btrd_b) * sqrt_npq;
+    RealType btrd_v_r = 0.92 - 4.2/btrd_b;
+    RealType btrd_u_rv_r = 0.86*btrd_v_r;
+
+    while(true) {
+        RealType u;
+        RealType v = rdvariate_unif01(urng);
+        if(v <= btrd_u_rv_r) {
+            u = v/btrd_v_r - 0.43;
+            return static_cast<IntType>(floor(
+                (2*btrd_a/(0.5 - abs(u)) + btrd_b)*u + btrd_c));
+        }
+
+        if(v >= btrd_v_r) {
+            u = rdvariate_unif01(urng) - 0.5;
+        } else {
+            u = v/btrd_v_r - 0.93;
+            u = ((u < 0)? -0.5 : 0.5) - u;
+            v = rdvariate_unif01(urng) * btrd_v_r;
+        }
+
+        RealType us = 0.5 - abs(u);
+        IntType k = static_cast<IntType>(floor((2*btrd_a/us + btrd_b)*u + btrd_c));
+        if(k < 0 || k > _t) continue;
+        v = v*btrd_alpha/(btrd_a/(us*us) + btrd_b);
+        RealType km = abs(k - m);
+        if(km <= 15) {
+            RealType f = 1;
+            if(m < k) {
+                IntType i = m;
+                do {
+                    ++i;
+                    f = f*(btrd_nr/i - btrd_r);
+                } while(i != k);
+            } else if(m > k) {
+                IntType i = k;
+                do {
+                    ++i;
+                    v = v*(btrd_nr/i - btrd_r);
+                } while(i != m);
+            }
+            if(v <= f) return k;
+            else continue;
+        } else {
+            // final acceptance/rejection
+            v = log(v);
+            RealType rho =
+                (km/btrd_npq)*(((km/3. + 0.625)*km + 1./6)/btrd_npq + 0.5);
+            RealType t = -km*km/(2*btrd_npq);
+            if(v < t - rho) return k;
+            if(v > t + rho) continue;
+
+            IntType nm = _t - m + 1;
+            RealType h = (m + 0.5)*log((m + 1)/(btrd_r*nm))
+                       + fc(m) + fc(_t - m);
+
+            IntType nk = _t - k + 1;
+            if(v <= h + (_t+1)*log(static_cast<RealType>(nm)/nk)
+                      + (k + 0.5)*log(nk*btrd_r/(k+1))
+                      - fc(k)
+                      - fc(_t - k))
+            {
+                return k;
+            } else {
+                continue;
+            }
+        }
+    }
+}
+
+IntType invert(IntType t, RealType p, std::mt19937& urng = random_gen)
+{
+    RealType q = 1 - p;
+    RealType s = p / q;
+    RealType a = (t + 1) * s;
+    RealType r = pow((1 - p), static_cast<RealType>(t));
+    RealType u = rdvariate_unif01(urng);
+    IntType x = 0;
+    while(u > r) {
+        u = u - r;
+        ++x;
+        RealType r1 = ((a/x) - s) * r;
+        // If r gets too small then the round-off error
+        // becomes a problem.  At this point, p(i) is
+        // decreasing exponentially, so if we just call
+        // it 0, it's close enough.  Note that the
+        // minimum value of q_n is about 1e-7, so we
+        // may need to be a little careful to make sure that
+        // we don't terminate the first time through the loop
+        // for float.  (Hence the test that r is decreasing)
+        if(r1 < std::numeric_limits<RealType>::epsilon() && r1 < r) {
+            break;
+        }
+        r = r1;
+    }
+    return x;
+}
+
+
+IntType boost_binomial_distribution_variate(IntType t_arg, RealType p_arg, std::mt19937& urng = random_gen)
+{
+    bool other_side = p_arg > 0.5;
+    RealType fake_p = other_side ? 1.0 - p_arg : p_arg;
+    IntType m = static_cast<IntType>((t_arg+1)*fake_p);
+    IntType result;
+    if(m < 11)
+        result = invert(t_arg, fake_p, urng);
+    else
+        result = btrd(t_arg, fake_p, m, urng);
+
+    if(other_side)
+        return t_arg - result;
+    else
+        return result;
+}
+
+}  // namespace IsoSpec

IsoSpecPy/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

IsoSpecPy/IsoSpec++/conf.h

@@ -0,0 +1,38 @@
+/*
+ *   Copyright (C) 2015-2020 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
+
+namespace IsoSpec
+{
+
+typedef int* Conf;
+
+struct ProbAndConfPtr
+{
+    // For some reason std::pair isn't trivially copyable...
+    double first;
+    Conf second;
+
+    ProbAndConfPtr(double p, Conf c) : first(p), second(c) {}
+
+    bool operator<(const ProbAndConfPtr& other) const
+    {
+        return first < other.first;
+    }
+};
+
+}  // namespace IsoSpec

IsoSpecPy/IsoSpec++/cwrapper.h

@@ -0,0 +1,271 @@
+/*
+ *   Copyright (C) 2015-2020 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 "platform.h"
+
+#define ISOSPEC_ALGO_LAYERED 0
+#define ISOSPEC_ALGO_ORDERED 1
+#define ISOSPEC_ALGO_THRESHOLD_ABSOLUTE 2
+#define ISOSPEC_ALGO_THRESHOLD_RELATIVE 3
+#define ISOSPEC_ALGO_LAYERED_ESTIMATE 4
+
+
+// Error reporting across the C ABI: these functions never let a C++ exception
+// escape (that would be undefined behaviour for a C / cffi caller). On bad input
+// or out-of-memory they instead return an out-of-band error value:
+//   * functions returning a handle/pointer return NULL,
+//   * functions returning a double return NaN,
+//   * functions returning an integer/bool return 0 / false.
+// Callers should check the returned handle for NULL before using it.
+
+#ifdef __cplusplus
+extern "C" {
+#else
+#include <stdbool.h>
+#endif
+
+ISOSPEC_C_API void * setupIso(int             dimNumber,
+                const int*      isotopeNumbers,
+                const int*      atomCounts,
+                const double*   isotopeMasses,
+                const double*   isotopeProbabilities);
+
+ISOSPEC_C_API void * isoFromFasta(const char* fasta, bool use_nominal_masses, bool add_water);
+
+ISOSPEC_C_API double getLightestPeakMassIso(void* iso);
+ISOSPEC_C_API double getLightestPeakLProbIso(void* iso);
+ISOSPEC_C_API void getLightestPeakSignature(void* iso, int* space);
+ISOSPEC_C_API double getHeaviestPeakMassIso(void* iso);
+ISOSPEC_C_API double getHeaviestPeakLProbIso(void* iso);
+ISOSPEC_C_API void getHeaviestPeakSignature(void* iso, int* space);
+ISOSPEC_C_API double getMonoisotopicPeakMassIso(void* iso);
+ISOSPEC_C_API double getMonoisotopicPeakLProbIso(void* iso);
+ISOSPEC_C_API void getMonoisotopicPeakSignature(void* iso, int* space);
+ISOSPEC_C_API double getModeLProbIso(void* iso);
+ISOSPEC_C_API double getModeMassIso(void* iso);
+ISOSPEC_C_API double getTheoreticalAverageMassIso(void* iso);
+ISOSPEC_C_API double getIsoVariance(void* iso);
+ISOSPEC_C_API double getIsoStddev(void* iso);
+ISOSPEC_C_API double* getMarginalLogSizeEstimates(void* iso, double target_total_prob);
+
+
+ISOSPEC_C_API void deleteIso(void* iso);
+
+
+// ______________________________________________________THRESHOLD GENERATOR
+ISOSPEC_C_API void* setupIsoThresholdGenerator(void* iso,
+                                 double threshold,
+                                 bool _absolute,
+                                 int _tabSize,
+                                 int _hashSize,
+                                 bool reorder_marginals);
+ISOSPEC_C_API double massIsoThresholdGenerator(void* generator);
+ISOSPEC_C_API double lprobIsoThresholdGenerator(void* generator);
+ISOSPEC_C_API double probIsoThresholdGenerator(void* generator);
+ISOSPEC_C_API void get_conf_signatureIsoThresholdGenerator(void* generator, int* space);
+ISOSPEC_C_API bool advanceToNextConfigurationIsoThresholdGenerator(void* generator);
+ISOSPEC_C_API void deleteIsoThresholdGenerator(void* generator);
+
+
+// ______________________________________________________LAYERED GENERATOR
+ISOSPEC_C_API void* setupIsoLayeredGenerator(void* iso,
+                               int _tabSize,
+                               int _hashSize,
+                               bool reorder_marginals,
+                               double t_prob_hint);
+ISOSPEC_C_API double massIsoLayeredGenerator(void* generator);
+ISOSPEC_C_API double lprobIsoLayeredGenerator(void* generator);
+ISOSPEC_C_API double probIsoLayeredGenerator(void* generator);
+ISOSPEC_C_API void get_conf_signatureIsoLayeredGenerator(void* generator, int* space);
+ISOSPEC_C_API bool advanceToNextConfigurationIsoLayeredGenerator(void* generator);
+ISOSPEC_C_API void deleteIsoLayeredGenerator(void* generator);
+
+// ______________________________________________________ORDERED GENERATOR
+ISOSPEC_C_API void* setupIsoOrderedGenerator(void* iso,
+                               int _tabSize,
+                               int _hashSize);
+ISOSPEC_C_API double massIsoOrderedGenerator(void* generator);
+ISOSPEC_C_API double lprobIsoOrderedGenerator(void* generator);
+ISOSPEC_C_API double probIsoOrderedGenerator(void* generator);
+ISOSPEC_C_API void get_conf_signatureIsoOrderedGenerator(void* generator, int* space);
+ISOSPEC_C_API bool advanceToNextConfigurationIsoOrderedGenerator(void* generator);
+ISOSPEC_C_API void deleteIsoOrderedGenerator(void* generator);
+
+// ______________________________________________________STOCHASTIC GENERATOR
+ISOSPEC_C_API void* setupIsoStochasticGenerator(void* iso,
+                                   size_t no_molecules,
+                                   double precision,
+                                   double beta_bias);
+ISOSPEC_C_API double massIsoStochasticGenerator(void* generator);
+ISOSPEC_C_API double lprobIsoStochasticGenerator(void* generator);
+ISOSPEC_C_API double probIsoStochasticGenerator(void* generator);
+ISOSPEC_C_API void get_conf_signatureIsoStochasticGenerator(void* generator, int* space);
+ISOSPEC_C_API bool advanceToNextConfigurationIsoStochasticGenerator(void* generator);
+ISOSPEC_C_API void deleteIsoStochasticGenerator(void* generator);
+
+ISOSPEC_C_API void* setupThresholdFixedEnvelope(void* iso,
+                              double threshold,
+                              bool absolute,
+                              bool get_confs);
+
+ISOSPEC_C_API void* setupTotalProbFixedEnvelope(void* iso,
+                              double taget_coverage,
+                              bool optimize,
+                              bool get_confs);
+
+ISOSPEC_C_API void* setupStochasticFixedEnvelope(void* iso,
+                              size_t no_molecules,
+                              double precision,
+                              double beta_bias,
+                              bool get_confs);
+
+ISOSPEC_C_API void* setupBinnedFixedEnvelope(void* iso,
+                    double target_total_prob,
+                    double bin_width,
+                    double bin_middle);
+
+ISOSPEC_C_API void freeReleasedArray(void* array);
+
+ISOSPEC_C_API void array_add(double* array, size_t N, double what);
+ISOSPEC_C_API void array_mul(double* array, size_t N, double what);
+ISOSPEC_C_API void array_fma(double* array, size_t N, double mul, double add);
+
+ISOSPEC_C_API void* setupFixedEnvelope(double* masses, double* probs, size_t size, bool mass_sorted, bool prob_sorted, double total_prob);
+ISOSPEC_C_API void* setupFixedEnvelopeWithConfs(double* masses, double* probs, int* confs, size_t size, int allDim, bool mass_sorted, bool prob_sorted, double total_prob);
+ISOSPEC_C_API void* copyFixedEnvelope(void* other);
+ISOSPEC_C_API void deleteFixedEnvelope(void* tabulator, bool releaseEverything);
+
+/* These three hand the envelope's array over to the caller, who must free() it
+   (with freeReleasedArray) once done. That costs a copy of the whole array
+   whenever the envelope did not allocate it with plain malloc() -- which is the
+   normal case now that everything the library produces is SIMD-aligned, and one
+   that grew large enough is mapped straight from the OS. Prefer the *WithDeleter
+   variants below, which never copy. */
+ISOSPEC_C_API const double* massesFixedEnvelope(void* tabulator);
+ISOSPEC_C_API const double* probsFixedEnvelope(void* tabulator);
+ISOSPEC_C_API const int*    confsFixedEnvelope(void* tabulator);
+ISOSPEC_C_API size_t confs_noFixedEnvelope(void* tabulator);
+
+/* How a buffer obtained from one of the *WithDeleter entry points below has to
+   be given back: deleter(array, size), exactly once, with the very size that
+   came out alongside the pointer. free() is not, in general, the right answer.
+   Call it through freeReleasedArrayWithDeleter() rather than directly, so
+   callers that cannot invoke a raw function pointer (cffi, say) need not. */
+typedef void (*IsoSpecArrayDeleter)(void* array, size_t size);
+
+/* Zero-copy counterparts of the three getters above: each yields the array's
+   pointer and writes out the (size, deleter) pair needed to release it. Both
+   out-parameters may be NULL if not wanted -- but then the array can only be
+   leaked. A NULL return means either an empty envelope or an error. */
+ISOSPEC_C_API double* massesFixedEnvelopeWithDeleter(void* tabulator, size_t* size_out, IsoSpecArrayDeleter* deleter_out);
+ISOSPEC_C_API double* probsFixedEnvelopeWithDeleter(void* tabulator, size_t* size_out, IsoSpecArrayDeleter* deleter_out);
+ISOSPEC_C_API int*    confsFixedEnvelopeWithDeleter(void* tabulator, size_t* size_out, IsoSpecArrayDeleter* deleter_out);
+
+ISOSPEC_C_API void freeReleasedArrayWithDeleter(void* array, size_t size, IsoSpecArrayDeleter deleter);
+
+ISOSPEC_C_API double empiricAverageMass(void* tabulator);
+ISOSPEC_C_API double empiricVariance(void* tabulator);
+ISOSPEC_C_API double empiricStddev(void* tabulator);
+
+ISOSPEC_C_API double wassersteinDistance(void* tabulator1, void* tabulator2);
+ISOSPEC_C_API double orientedWassersteinDistance(void* tabulator1, void* tabulator2);
+ISOSPEC_C_API double abyssalWassersteinDistance(void* tabulator1, void* tabulator2, double abyss_depth, double other_scale);
+// ISOSPEC_C_API double abyssalWassersteinDistanceGrad(void* const* envelopes, const double* scales, double* ret_gradient, size_t N, double abyss_depth_exp, double abyss_depth_the);
+
+struct ws_match_res{
+double res1;
+double res2;
+double flow;
+};
+
+ISOSPEC_C_API struct ws_match_res wassersteinMatch(void* tabulator1, void* tabulator2, double flow_dist, double other_scale);
+
+ISOSPEC_C_API void* addEnvelopes(void* tabulator1, void* tabulator2);
+ISOSPEC_C_API void* convolveEnvelopes(void* tabulator1, void* tabulator2);
+
+ISOSPEC_C_API double getTotalProbOfEnvelope(void* envelope);
+ISOSPEC_C_API void scaleEnvelope(void* envelope, double factor);
+ISOSPEC_C_API void normalizeEnvelope(void* envelope);
+ISOSPEC_C_API void shiftMassEnvelope(void* envelope, double d_mass);
+ISOSPEC_C_API void resampleEnvelope(void* envelope, size_t ionic_current, double beta_bias);
+ISOSPEC_C_API void* binnedEnvelope(void* envelope, double width, double middle);
+ISOSPEC_C_API void* linearCombination(void* const * const envelopes, const double* intensities, size_t count);
+
+ISOSPEC_C_API void sortEnvelopeByMass(void* envelope);
+ISOSPEC_C_API void sortEnvelopeByProb(void* envelope);
+
+ISOSPEC_C_API void parse_fasta_c(const char* fasta, int atomCounts[6]);
+
+/* Unimod-modification-aware peptide sequence parsing (fasta_mods.h/unimod.h):
+   recognizes [UNIMOD:<id>] brackets in N-terminal ("[id]-SEQ"), internal
+   ("X[id]"), and C-terminal ("SEQ-[id]") placement -- see docs/ai/unimod.md.
+   unimod_db_path == NULL or "" selects the compile-time embedded default
+   table; any other path is loaded and cached (see unimod_table_for_path).
+   NULL on error (malformed bracket, unknown/excluded id) -- callers must
+   NULL-check like every other handle-returning function here. */
+ISOSPEC_C_API void* isoFromFastaWithMods(const char* sequence, bool use_nominal_masses, bool add_water, const char* unimod_db_path);
+
+/* Opaque parsed-composition handle: NULL_UNIMOD_db_path selects the embedded
+   default table, same as above. NULL return on error. */
+ISOSPEC_C_API void* parseFastaWithModsC(const char* sequence, const char* unimod_db_path);
+ISOSPEC_C_API size_t compositionSizeC(void* composition);
+/* Element symbols, e.g. "C", "H", "Se" -- static strings (elem_table_symbol),
+   must NOT be freed individually; only the returned array belongs to the
+   handle, freed by deleteCompositionC. */
+ISOSPEC_C_API const char* const* compositionSymbolsC(void* composition);
+ISOSPEC_C_API const int* compositionCountsC(void* composition);
+ISOSPEC_C_API void deleteCompositionC(void* composition);
+
+/* Composition -> the flat per-isotope arrays setupIso takes, with the
+   isotopes resolved from the library's own element tables (see
+   composition.h's expand_composition_into, the single implementation).
+
+   This is the rung between setupIso -- which requires the caller to already
+   know every isotope mass and probability, i.e. to carry its own copy of the
+   periodic table -- and isoFromFasta/isoFromFastaWithMods, which accept
+   nothing but a sequence. A binding holding a composition (symbol, count)
+   has one of those, not the other, and this is what it should call.
+
+   `symbols` are element symbols spelled as in elem_table_symbol ("C", "H",
+   "Se"), `size` entries, paired positionally with `counts`. Element order is
+   preserved throughout, so a caller can match the outputs back up by index.
+
+   Counts may be negative: a composition is not yet a molecule, and rejecting
+   that is the caller's job at the point it builds one (see composition.h).
+   NULL on an unknown element symbol or OOM. */
+ISOSPEC_C_API void* expandCompositionC(const char* const* symbols, const int* counts, size_t size, bool use_nominal_masses);
+/* `size` entries each, in the input's element order. */
+ISOSPEC_C_API const int* expandedIsotopeNumbersC(void* expanded);
+ISOSPEC_C_API const int* expandedAtomCountsC(void* expanded);
+/* sum(expandedIsotopeNumbersC) entries each, element-major. Exactly what
+   setupIso's isotopeMasses/isotopeProbabilities arguments want. */
+ISOSPEC_C_API const double* expandedIsotopeMassesC(void* expanded);
+ISOSPEC_C_API const double* expandedIsotopeProbabilitiesC(void* expanded);
+/* All four arrays above belong to the handle and die with it. */
+ISOSPEC_C_API void deleteExpandedCompositionC(void* expanded);
+
+/* What the library's batched kernels are vectorised to on this machine, as a
+   stable lowercase token: "scalar", "sse2", "avx", "avx2", "avx512", "neon", or
+   "simd" for a vector unit with no name here. Never NULL; a static string, so
+   it must NOT be freed. See active_simd_level() in isa_kernels.h. */
+ISOSPEC_C_API const char* activeSimdLevel(void);
+
+
+#ifdef __cplusplus
+}
+#endif