IsoSpecPy 2.4.0__tar.gz → 2.6.0__tar.gz

isospecpy-2.6.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: IsoSpecPy
+Version: 2.6.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.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.9
+Requires-Dist: cffi
+Provides-Extra: testing
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: OldIsoSpecPy; extra == "testing"
+Description-Content-Type: text/markdown
+
+# IsoSpec
+
+IsoSpec is a fine-structure isotopic distribution calculator for chemical formulas — given a molecule, it computes the masses and probabilities of its isotopologues. It is fast enough to handle large molecules (proteins, oligonucleotides) where the full distribution has astronomically many configurations, and it returns provably-optimal subsets that cover a chosen fraction of the total probability mass.
+
+IsoSpec is primarily used as a library by mass spectrometry software. It is implemented in C++ (`src/IsoSpec++/`) and shipped with first-class bindings for Python (`IsoSpecPy`, on PyPI), R (`IsoSpecR`, on CRAN) and Rust (`isospec`, the crate in `rust/`).
+
+## Installation
+
+### Python
+
+```bash
+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.9.
+
+To build from source: `pip install .` from a checkout. A C++20 compiler is required.
+
+### R
+
+```r
+install.packages("IsoSpecR")
+```
+
+From source: `cd src && R CMD build IsoSpecR && R CMD INSTALL IsoSpecR_*.tar.gz`.
+
+### Rust
+
+```toml
+[dependencies]
+isospec = "0.1"
+```
+
+The build script compiles the bundled C++ library; a C++20 compiler is all that is needed. See `rust/README.md`.
+
+### C++ library
+
+```bash
+cd src/IsoSpec++
+make            # produces libIsoSpec++.so
+```
+
+Or via CMake from the repo root:
+
+```bash
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+sudo cmake --install build
+```
+
+Requires a C++20 compiler. CMake produces both shared and static libraries and installs headers under `${CMAKE_INSTALL_INCLUDEDIR}/IsoSpec++`.
+
+## Quick start
+
+The most common usage is `IsoTotalProb`: ask for the smallest set of isotopologues whose summed probability covers a chosen fraction of the spectrum (typically 0.99–0.9999). The result is a materialized envelope — arrays of masses and probabilities you can read directly.
+
+### Python
+
+```python
+import IsoSpecPy
+
+# Isotopologues covering at least 99.9% of the probability mass of water.
+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 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}
+```
+
+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++
+
+```cpp
+#include "IsoSpec++/isoSpec++.h"
+#include "IsoSpec++/fixedEnvelopes.h"
+
+using namespace IsoSpec;
+
+int main() {
+    FixedEnvelope iso = FixedEnvelope::FromTotalProb("H2O1", 0.999, true, true);
+
+    for (size_t i = 0; i < iso.confs_no(); ++i) {
+        std::cout << iso.mass(i) << '\t' << iso.prob(i) << '\n';
+    }
+}
+```
+
+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
+clang++ -std=c++20 water.cpp src/IsoSpec++/unity-build.cpp -o water
+```
+
+(`unity-build.cpp` is a single translation unit that `#include`s every source file — see `Examples/C++/COMPILING`.)
+
+### Rust
+
+```rust
+use isospec::{Iso, PeptideOptions};
+
+fn main() -> Result<(), isospec::Error> {
+    let iso = Iso::from_formula("H2O1")?;
+    for (mass, prob) in iso.envelope().total_prob(0.999)?.iter() {
+        println!("{mass}\t{prob}");
+    }
+
+    // A modified peptide; unlike Python's peptide_sequence=, the default
+    // here includes the terminal water.
+    let peptide = Iso::from_peptide("PEPTC[UNIMOD:4]DEK", &PeptideOptions::default())?;
+    println!("{}", peptide.monoisotopic_mass());
+    Ok(())
+}
+```
+
+See `rust/examples/` for binned spectra, generators with configurations, and labelled elements.
+
+### R
+
+```r
+library(IsoSpecR)
+water <- c(H = 2, O = 1)
+IsoSpecify(molecule = water, stopCondition = 0.999)
+```
+
+`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.
+
+The rest of the API takes the same named vector, and treats an envelope as what `IsoSpecify` returns, a matrix with columns `mass` and `prob`:
+
+```r
+insulin <- c(C = 254, H = 377, N = 65, O = 75, S = 6)
+IsoProperties(insulin)$averageMass            # also mono/lightest/heaviest/mode peaks, variance
+IsoBinned(insulin, binWidth = 1)              # unit-resolution distribution, computed directly
+IsoStochastic(insulin, ionicCurrent = 1e4, seed = 1)   # simulated, reproducible measurement
+wassersteinDistance(IsoSpecify(insulin, 0.999), IsoSpecify(c(C = 254, H = 377, N = 65, O = 74, S = 7), 0.999))
+```
+
+with `envelopeConvolve`, `envelopeLinearCombination`, `envelopeBin` and `envelopeResample` for envelope arithmetic, and `orientedWassersteinDistance`, `abyssalWassersteinDistance` and `wassersteinMatch` beside `wassersteinDistance`.
+
+See `Examples/R/` for radiolabelling, full-spectrum extraction, Unimod-annotated sequences, and binned, simulated and compared envelopes.
+
+## Advanced features
+
+- **Alternative algorithms** — for cases where `IsoTotalProb` isn't the right shape:
+  - `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/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, binning, resampling, Wasserstein distances.
+- **Reproducible sampling** — stochastic envelopes and resampling take a seed (`seed=` in Python and R, `seeded_rng()` in C++, `with_seed` in Rust); a seed gives the same counts on every platform and in every binding.
+- **Nominal-mass mode** — compute distributions over nucleon counts instead of real masses.
+- **Thread safety** — the library never parallelises its own work, but independent molecules and envelopes may be used from any number of threads, and a shared molecule or envelope may be read from several at once.
+- **Streaming generators (for performance)** — the tabulated functions above materialize the full envelope into arrays. For large molecules where that uses too much memory, or for pipelines that consume one configuration at a time (e.g. binning on the fly), use the generator classes instead: `IsoThresholdGenerator`, `IsoLayeredGenerator`, `IsoOrderedGenerator`, `IsoStochasticGenerator`. They yield one isotopologue per call to `advanceToNextConfiguration()` without ever storing the full set. `IsoOrderedGenerator` additionally streams in strict order of decreasing probability. Generators are in C++, Python and Rust; R has the materialized functions only.
+
+Algorithmic details are in the papers cited below; the Supporting Information of each is the better starting point for implementation specifics.
+
+## Repository layout
+
+```
+src/IsoSpec++/    C++ core library (the algorithms live here)
+src/IsoSpecPy/    Python binding, loaded via cffi
+src/IsoSpecR/     R binding, via Rcpp
+rust/             Rust crate (Cargo.toml at the repository root), via cxx
+Examples/         Working examples in each language
+tests/            C, C++, and Python test suites (R's are in src/IsoSpecR/tests, Rust's in rust/tests)
+skbuild/          scikit-build-core entry point used when installing the Python wheel
+```
+
+## Changes
+
+`CHANGELOG` lists the major changes in each release (the Rust crate keeps its own, `rust/CHANGELOG.md`).
+
+## Citation
+
+If IsoSpec is useful in your research, please cite:
+
+- Łącki, M. K.; Valkenborg, D.; Startek, M. P. *IsoSpec2: Ultrafast Fine Structure Calculator.* Analytical Chemistry **2020**, *92* (14), 9472–9475. <https://doi.org/10.1021/acs.analchem.0c00959>
+- Łącki, M. K.; Startek, M.; Valkenborg, D.; Gambin, A. *IsoSpec: Hyperfast Fine Structure Calculator.* Analytical Chemistry **2017**, *89* (6), 3272–3277. <https://doi.org/10.1021/acs.analchem.6b01459>
+
+The Supporting Information of each paper has the algorithmic detail.
+
+## License
+
+2-clause BSD (see `LICENCE`). If you need different licensing terms, contact the authors. The authors appreciate (but do not require) being told when IsoSpec is used in other software.

isospecpy-2.6.0/README.md

@@ -0,0 +1,239 @@
+# IsoSpec
+
+IsoSpec is a fine-structure isotopic distribution calculator for chemical formulas — given a molecule, it computes the masses and probabilities of its isotopologues. It is fast enough to handle large molecules (proteins, oligonucleotides) where the full distribution has astronomically many configurations, and it returns provably-optimal subsets that cover a chosen fraction of the total probability mass.
+
+IsoSpec is primarily used as a library by mass spectrometry software. It is implemented in C++ (`src/IsoSpec++/`) and shipped with first-class bindings for Python (`IsoSpecPy`, on PyPI), R (`IsoSpecR`, on CRAN) and Rust (`isospec`, the crate in `rust/`).
+
+## Installation
+
+### Python
+
+```bash
+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.9.
+
+To build from source: `pip install .` from a checkout. A C++20 compiler is required.
+
+### R
+
+```r
+install.packages("IsoSpecR")
+```
+
+From source: `cd src && R CMD build IsoSpecR && R CMD INSTALL IsoSpecR_*.tar.gz`.
+
+### Rust
+
+```toml
+[dependencies]
+isospec = "0.1"
+```
+
+The build script compiles the bundled C++ library; a C++20 compiler is all that is needed. See `rust/README.md`.
+
+### C++ library
+
+```bash
+cd src/IsoSpec++
+make            # produces libIsoSpec++.so
+```
+
+Or via CMake from the repo root:
+
+```bash
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+sudo cmake --install build
+```
+
+Requires a C++20 compiler. CMake produces both shared and static libraries and installs headers under `${CMAKE_INSTALL_INCLUDEDIR}/IsoSpec++`.
+
+## Quick start
+
+The most common usage is `IsoTotalProb`: ask for the smallest set of isotopologues whose summed probability covers a chosen fraction of the spectrum (typically 0.99–0.9999). The result is a materialized envelope — arrays of masses and probabilities you can read directly.
+
+### Python
+
+```python
+import IsoSpecPy
+
+# Isotopologues covering at least 99.9% of the probability mass of water.
+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 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}
+```
+
+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++
+
+```cpp
+#include "IsoSpec++/isoSpec++.h"
+#include "IsoSpec++/fixedEnvelopes.h"
+
+using namespace IsoSpec;
+
+int main() {
+    FixedEnvelope iso = FixedEnvelope::FromTotalProb("H2O1", 0.999, true, true);
+
+    for (size_t i = 0; i < iso.confs_no(); ++i) {
+        std::cout << iso.mass(i) << '\t' << iso.prob(i) << '\n';
+    }
+}
+```
+
+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
+clang++ -std=c++20 water.cpp src/IsoSpec++/unity-build.cpp -o water
+```
+
+(`unity-build.cpp` is a single translation unit that `#include`s every source file — see `Examples/C++/COMPILING`.)
+
+### Rust
+
+```rust
+use isospec::{Iso, PeptideOptions};
+
+fn main() -> Result<(), isospec::Error> {
+    let iso = Iso::from_formula("H2O1")?;
+    for (mass, prob) in iso.envelope().total_prob(0.999)?.iter() {
+        println!("{mass}\t{prob}");
+    }
+
+    // A modified peptide; unlike Python's peptide_sequence=, the default
+    // here includes the terminal water.
+    let peptide = Iso::from_peptide("PEPTC[UNIMOD:4]DEK", &PeptideOptions::default())?;
+    println!("{}", peptide.monoisotopic_mass());
+    Ok(())
+}
+```
+
+See `rust/examples/` for binned spectra, generators with configurations, and labelled elements.
+
+### R
+
+```r
+library(IsoSpecR)
+water <- c(H = 2, O = 1)
+IsoSpecify(molecule = water, stopCondition = 0.999)
+```
+
+`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.
+
+The rest of the API takes the same named vector, and treats an envelope as what `IsoSpecify` returns, a matrix with columns `mass` and `prob`:
+
+```r
+insulin <- c(C = 254, H = 377, N = 65, O = 75, S = 6)
+IsoProperties(insulin)$averageMass            # also mono/lightest/heaviest/mode peaks, variance
+IsoBinned(insulin, binWidth = 1)              # unit-resolution distribution, computed directly
+IsoStochastic(insulin, ionicCurrent = 1e4, seed = 1)   # simulated, reproducible measurement
+wassersteinDistance(IsoSpecify(insulin, 0.999), IsoSpecify(c(C = 254, H = 377, N = 65, O = 74, S = 7), 0.999))
+```
+
+with `envelopeConvolve`, `envelopeLinearCombination`, `envelopeBin` and `envelopeResample` for envelope arithmetic, and `orientedWassersteinDistance`, `abyssalWassersteinDistance` and `wassersteinMatch` beside `wassersteinDistance`.
+
+See `Examples/R/` for radiolabelling, full-spectrum extraction, Unimod-annotated sequences, and binned, simulated and compared envelopes.
+
+## Advanced features
+
+- **Alternative algorithms** — for cases where `IsoTotalProb` isn't the right shape:
+  - `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/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, binning, resampling, Wasserstein distances.
+- **Reproducible sampling** — stochastic envelopes and resampling take a seed (`seed=` in Python and R, `seeded_rng()` in C++, `with_seed` in Rust); a seed gives the same counts on every platform and in every binding.
+- **Nominal-mass mode** — compute distributions over nucleon counts instead of real masses.
+- **Thread safety** — the library never parallelises its own work, but independent molecules and envelopes may be used from any number of threads, and a shared molecule or envelope may be read from several at once.
+- **Streaming generators (for performance)** — the tabulated functions above materialize the full envelope into arrays. For large molecules where that uses too much memory, or for pipelines that consume one configuration at a time (e.g. binning on the fly), use the generator classes instead: `IsoThresholdGenerator`, `IsoLayeredGenerator`, `IsoOrderedGenerator`, `IsoStochasticGenerator`. They yield one isotopologue per call to `advanceToNextConfiguration()` without ever storing the full set. `IsoOrderedGenerator` additionally streams in strict order of decreasing probability. Generators are in C++, Python and Rust; R has the materialized functions only.
+
+Algorithmic details are in the papers cited below; the Supporting Information of each is the better starting point for implementation specifics.
+
+## Repository layout
+
+```
+src/IsoSpec++/    C++ core library (the algorithms live here)
+src/IsoSpecPy/    Python binding, loaded via cffi
+src/IsoSpecR/     R binding, via Rcpp
+rust/             Rust crate (Cargo.toml at the repository root), via cxx
+Examples/         Working examples in each language
+tests/            C, C++, and Python test suites (R's are in src/IsoSpecR/tests, Rust's in rust/tests)
+skbuild/          scikit-build-core entry point used when installing the Python wheel
+```
+
+## Changes
+
+`CHANGELOG` lists the major changes in each release (the Rust crate keeps its own, `rust/CHANGELOG.md`).
+
+## Citation
+
+If IsoSpec is useful in your research, please cite:
+
+- Łącki, M. K.; Valkenborg, D.; Startek, M. P. *IsoSpec2: Ultrafast Fine Structure Calculator.* Analytical Chemistry **2020**, *92* (14), 9472–9475. <https://doi.org/10.1021/acs.analchem.0c00959>
+- Łącki, M. K.; Startek, M.; Valkenborg, D.; Gambin, A. *IsoSpec: Hyperfast Fine Structure Calculator.* Analytical Chemistry **2017**, *89* (6), 3272–3277. <https://doi.org/10.1021/acs.analchem.6b01459>
+
+The Supporting Information of each paper has the algorithmic detail.
+
+## License
+
+2-clause BSD (see `LICENCE`). If you need different licensing terms, contact the authors. The authors appreciate (but do not require) being told when IsoSpec is used in other software.

isospecpy-2.6.0/VERSION

@@ -0,0 +1 @@
+2.6.0

{isospecpy-2.4.0 → isospecpy-2.6.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",