13CFLUX
=======

**A third‑generation, high‑performance simulator for isotopically
stationary and non‑stationary ¹³C metabolic flux analysis**

Open, extensible, fast, and accurate: enabling robust design, fitting,
and statistical analysis for modern, scalable \ :sup:`13`\C-MFA workflows.

Why 13CFLUX?
------------

-  **Universal**: Simulates any desired labeling state for isotopically
   stationary and non‑stationary (INST) experiments, supporting
   multi‑isotope tracers (e.g. \ :sup:`13`\C-\ :sup:`15`\N) and any measurement
   configuration, with shortcuts to MS, tandem MS, 1H and 13C-NMR.
-  **High performance**: Clean C++17 core with Eigen-based linear
   algebra and advanced ODE solvers with tunable precision; Python API
   for workflow automation.
-  **Flexible workflows**: Compose experimental design, multi‑start
   fitting, and uncertainty quantification (incl. Frequentist and
   Bayesian) with minimal coding; easy integration with NumPy/SciPy,
   Jupyter notebooks, and orchestration tools, e.g Apache Airflow.
-  **Reproducible & portable**: Ship and run via pip or Docker from
   laptop to HPC.

..
   TODO!
   New to \ :sup:`13`\C-MFA concepts?
   See the Guided Tutorial and Concepts pages
   for a gentle introduction. :doc:`Spiralus example <examples/spiralus>`

Quick install
-------------

-  **PyPI**

   -  ``conda install cyipopt``
   -  ``pip install x3cflux``
   -  Note: conda is used for a working ipopt/cyipopt (see
      :doc:`installation page <installation/from-package-managers>`)

-  **Docker**

   -  ``docker pull jugit-registry.fz-juelich.de/ibg-1/modsim/fluxomics/13cflux``
   -  Recommended for HPC
   -  :doc:`Further information <installation/docker-image>`

Alternatively, :doc:`manual installation <installation/from-sources>` is also possible.

1 minute quick start
--------------------

.. literalinclude:: _static/one_minute_quick_start.py
   :language: python

`📥 one_minute_quick_start.py <_static/one_minute_quick_start.py>`__       `📥 spiralus.fml <_static/spiralus.fml>`__

A more detailed version can be found at :doc:`examples/spiralus`.

Key features at a glance
------------------------

-  **State space**: Dual labeling state-space representations: automatic
   selection between EMU and cumomer systems with optimal? dimension
   reduction.
-  **Solver suite**: `eigen sparseLU <http://eigen.tuxfamily.org>`__
   solver for isotopic stationary systems; tuned BDF (`SUNDIALS
   CVODE <https://computing.llnl.gov/projects/sundials/cvode>`__) and
   SDIRK both with with adaptive step control for isotopically non
   stationary systems .
-  **Sensitivities & Jacobians**: analytically derived systems,
   numerically solved using `OpenMP <https://www.openmp.org/>`__
   parallelization.
-  **Workflow API**: high‑level Python facades for experimental design,
   multi‑start fitting, and statistics with easy `Apache
   Airflow <https://airflow.apache.org/>`__ integration.
-  **Errors & diagnostics**: clear, propagated exceptions from C++ to
   Python; comprehensive semantic, syntactic, logic, and numeric checks.
-  **Containers**: Docker image for reproducibility and scale.

Performance benchmark
---------------------

.. _benchmark_figure:

.. figure:: images/benchmark.png

   Due to its improved codebase and by exploiting the structure of the underlying mathematical system 13CFLUX(v3) is up to 40 times faster compared to its predecessor 13CFLUX2.


License & contributing
----------------------

-  13CFLUX is open-source software, distributed under the terms of
   the `GNU AGPL v3 
   <https://www.gnu.org/licenses/agpl-3.0.html.en>`__.
-  Issues & bug reports: Please report via our
   `Gitlab <https://jugit.fz-juelich.de/IBG-1/ModSim/Fluxomics/13CFLUX>`__.

How to cite
-----------

If you use 13CFLUX, please cite:

Stratmann, A., Beyß, M., Jadebeck, J. F., Wiechert, W., & Nöh, K. (2025). 
13CFLUX –- Third-generation high-performance engine for isotopically (non)stationary 13C metabolic flux analysis.
*Bioinformatics*, btaf630, https://doi.org/10.1093/bioinformatics/btaf630

.. code:: bibtex

   @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},
   }

.. toctree::
   :maxdepth: 1
   :hidden:
   :caption: Installation

   installation/from-package-managers
   installation/docker-image
   installation/from-sources

.. toctree::
   :maxdepth: 1
   :hidden:
   :caption: Examples

   examples/spiralus
   examples/simulator
   examples/interoperability

.. toctree::
   :maxdepth: 1
   :hidden:
   :caption: API

   api/optimization
   api/statistics
   api/experimental_design
   api/simulator
   api/data_objects
   api/utilities