Metadata-Version: 2.4
Name: x3cflux
Version: 3.1.0
Summary: Python interface for 13CFLUX
Keywords: 13C-MFA,metabolic flux analysis,isotope labeling experiments,mass-spectrometry,HPC
Author-Email: Anton Stratmann <info@13cflux.net>, Johann Fredrik Jadebeck <info@13cflux.net>, Martin Beyß <info@13cflux.net>, Katharina Nöh <info@13cflux.net>, Christoph Gerards <info@13cflux.net>, "Richard D. Paul" <info@13cflux.net>, Daniel Weilandt <info@13cflux.net>
License-Expression: AGPL-3.0-only
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
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: Operating System :: POSIX :: Linux
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Project-URL: documentation, https://x3cflux.readthedocs.io
Project-URL: homepage, https://13cflux.net
Project-URL: repository, https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: joblib
Requires-Dist: cvxpy
Requires-Dist: cyipopt
Requires-Dist: hopsy>=1.6.1
Requires-Dist: cobyqa>=1.1.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: rst2pdf; extra == "docs"
Requires-Dist: pypandoc-binary; extra == "docs"
Requires-Dist: matplotlib; extra == "docs"
Requires-Dist: pandas; extra == "docs"
Requires-Dist: arviz; extra == "docs"
Requires-Dist: pdfo; extra == "docs"
Requires-Dist: ipython; extra == "docs"
Description-Content-Type: text/markdown

<img src="https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/raw/main/docs/source/_static/images/banner.png" width=350 alt="13CFLUX">

[![Pipeline Status](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/badges/main/pipeline.svg)](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/pipelines?scope=all&page=1&ref=main)
[![Coverage Report](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/badges/main/coverage.svg)](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/commits/main)
[![Latest Release](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/badges/release.svg)](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/releases)
[![PyPI](https://img.shields.io/pypi/v/x3cflux.svg)](https://pypi.org/project/x3cflux/)
[![License](https://img.shields.io/pypi/l/x3cflux.svg)](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22109141.svg)](https://doi.org/10.5281/zenodo.22109141)

`13CFLUX` is a high-performance simulator for isotopically stationary and non-stationary simulation of isotope labeling
experiments. It is build on highly optimized C++ code, made available in Python through `pybind11`. It comprises the
following main functions:

- Read metabolic models and labeling data from standardized FluxML
- Simulation of labeling distributions and data residuals given fluxes and metabolite concentrations
- Fitting and statistical analysis (Frequentist and Bayesian) of <sup>13</sup>C labeling experiments

`13CFLUX` is being developed by the Modelling and Simulation group under the supervision of Katharina Nöh at the
IBG-1, Forschungszentrum Jülich, Germany.

## Data formats

Models and labeling data are read from [FluxML](https://github.com/modsim/FluxML), a standardized XML format for
13C metabolic flux analysis shared across the `13CFLUX` tool family (see the
[FluxML paper](https://doi.org/10.3389/fmicb.2019.01022) and the
[`libFluxML` documentation](https://github.com/modsim/FluxML) for the full schema).

Results (fluxes, residuals, covariances, sampling output, etc.) are returned as plain `numpy` arrays and Python
objects rather than written to a fixed file format, so they can be persisted or post-processed with whatever
tooling fits your pipeline, e.g.:

```python
import numpy as np
np.savetxt("fluxes.csv", fluxes, delimiter=",")
```

## Installation

The recommended way for practitioners to install `13CFLUX` is via `pip` from the Python Package Index (PyPI). It is
recommended to do this in a Python environment. Before installation, you should make sure to have `ipopt` installed
(either [directly](https://coin-or.github.io/Ipopt/INSTALL.html) or by installing
[cyipopt via conda](https://cyipopt.readthedocs.io/en/stable/install.html)). Then just run

```shell
pip install x3cflux
```

To verify the installation:

```shell
python -c "import x3cflux; print(x3cflux.__version__)"
```

To run the test suite and confirm the software produces correct results, clone the repository and run:

```shell
pip install ".[test]"
cd src/test
pytest python
```

Alternatively, a container image with `13CFLUX` pre-installed (built and pushed automatically from every `main`
commit) is available and requires no local build toolchain:

```shell
docker run --rm -it jugit-registry.fz-juelich.de/ibg-1/modsim/fluxomics/13cflux:latest
```

This drops you into a Python shell with `x3cflux` ready to `import`.

## Documentation

We provide a [Read The Docs documentation](https://x3cflux.readthedocs.io). Check it out!

## Getting help and contributing

For questions, troubleshooting, and modelling discussions, visit the [`13CFLUX` forum](https://forum.13cflux.net/).
Some categories are currently restricted and require free registration for full access.

Development takes place on [JuGit](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX), where we have access to powerful continuous integration and a Docker
registry. **Please report issues and request features only on JuGit.**

Contributions are welcome. [`CONTRIBUTING.md`](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/blob/main/CONTRIBUTING.md) covers how to get a JuGit account, how to
build and test from source, the branching model, and the formatting and metadata checks that run on every commit.
Participation is governed by our [Code of Conduct](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/blob/main/CODE_OF_CONDUCT.md), and contributions are accepted under
a [Contributor License Agreement](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/blob/main/CLA.md).

## Versioning

`13CFLUX` follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`). Pre-releases (e.g. towards a new
major version) are tagged with an `aN` suffix, e.g. `3.0.0a0`. The package version is not set manually; it is derived
automatically from the git tag of a release via `setuptools_scm`.

There are no long-term-support (LTS) branches; only the latest release receives fixes (see
[`SECURITY.md`](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/blob/main/SECURITY.md)). Every release has an entry in [`CHANGELOG.md`](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/blob/main/CHANGELOG.md). How releases
are prepared and cut is described in [`CONTRIBUTING.md`](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/blob/main/CONTRIBUTING.md#versioning-and-releases).

## Citation

Every release is also archived on Zenodo. The concept DOI below always resolves to the latest version; see
[`CITATION.cff`](https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX/-/blob/main/CITATION.cff) for how to cite a specific version:

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22109141.svg)](https://doi.org/10.5281/zenodo.22109141)

If you use this software, please also cite the paper describing it:

```
@article{Stratmann2025,
    author = {Stratmann, Anton and Beyß, Martin and Jadebeck, Johann F and Wiechert, Wolfgang and Nöh, Katharina},
    title = {13CFLUX — Third-generation high-performance engine for isotopically (non)stationary 13C metabolic flux analysis},
    journal = {Bioinformatics},
    pages = {btaf630},
    year = {2025},
    issn = {1367-4811},
    doi = {10.1093/bioinformatics/btaf630},
    url = {https://doi.org/10.1093/bioinformatics/btaf630},
}
```
