Metadata-Version: 2.5
Name: cellifex
Version: 0.0.1
Summary: Cellifex — an AI/ML-native cell-state dynamics foundation model
Author: Mahdi Shafiei
License: MIT License
        
        Copyright (c) 2026 Mahdi Shafiei
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: bioinformatics,cell-biology,differentiable-biology,foundation-model,jax,metabolism,neural-ode,systems-biology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: <3.14,>=3.12
Requires-Dist: avitai-artifex>=0.1.6
Requires-Dist: calibrax>=0.1.5
Requires-Dist: cobra>=0.29
Requires-Dist: datarax>=0.1.8
Requires-Dist: diffbio>=0.1.3
Requires-Dist: diffrax>=0.6
Requires-Dist: equinox>=0.13
Requires-Dist: flax>=0.12.9
Requires-Dist: jax>=0.11.1
Requires-Dist: jaxtyping>=0.2.20
Requires-Dist: lineax>=0.1
Requires-Dist: numpy>=1.26
Requires-Dist: opifex>=0.2.3
Requires-Dist: optax>=0.2.8
Requires-Dist: orbax-checkpoint>=0.11
Requires-Dist: pandas>=2
Requires-Dist: pyyaml>=6
Requires-Dist: scipy>=1.13
Requires-Dist: substrax>=0.1.5
Requires-Dist: tomli-w>=1
Provides-Extra: all-cpu
Requires-Dist: bandit[toml]>=1.8.0; extra == 'all-cpu'
Requires-Dist: blackjax>=1.2; extra == 'all-cpu'
Requires-Dist: build>=1.0.3; extra == 'all-cpu'
Requires-Dist: deadcode>=2.4.1; extra == 'all-cpu'
Requires-Dist: deptry>=0.23.0; extra == 'all-cpu'
Requires-Dist: efmtool>=0.2; extra == 'all-cpu'
Requires-Dist: equilibrator-api<0.7,>=0.6; extra == 'all-cpu'
Requires-Dist: equilibrator-pathway>=0.6; extra == 'all-cpu'
Requires-Dist: griffe>=1.7.3; extra == 'all-cpu'
Requires-Dist: hippogriffe>=0.2; extra == 'all-cpu'
Requires-Dist: import-linter>=2.0; extra == 'all-cpu'
Requires-Dist: interrogate>=1.5; extra == 'all-cpu'
Requires-Dist: ipykernel>=6.29.5; extra == 'all-cpu'
Requires-Dist: jupytext>=1.16.0; extra == 'all-cpu'
Requires-Dist: memote>=0.17; extra == 'all-cpu'
Requires-Dist: mkdocs-include-exclude-files>=0.1; extra == 'all-cpu'
Requires-Dist: mkdocs-ipynb>=0.1; extra == 'all-cpu'
Requires-Dist: mkdocs-jupyter>=0.24; extra == 'all-cpu'
Requires-Dist: mkdocs-material>=9.6.7; extra == 'all-cpu'
Requires-Dist: mkdocs<2.0,>=1.6.1; extra == 'all-cpu'
Requires-Dist: mkdocstrings-python>=1.1.2; extra == 'all-cpu'
Requires-Dist: mkdocstrings>=0.28.3; extra == 'all-cpu'
Requires-Dist: mpax>=0.2; extra == 'all-cpu'
Requires-Dist: pre-commit>=4.3.0; extra == 'all-cpu'
Requires-Dist: pygments<3.0,>=2.20; extra == 'all-cpu'
Requires-Dist: pylint>=3.0; extra == 'all-cpu'
Requires-Dist: pymdown-extensions>=10.14.3; extra == 'all-cpu'
Requires-Dist: pyright>=1.1.336; extra == 'all-cpu'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all-cpu'
Requires-Dist: pytest-cov>=6.1.1; extra == 'all-cpu'
Requires-Dist: pytest-env>=1.0.1; extra == 'all-cpu'
Requires-Dist: pytest-json-report>=1.5.0; extra == 'all-cpu'
Requires-Dist: pytest-randomly>=3.15; extra == 'all-cpu'
Requires-Dist: pytest-timeout>=2.1; extra == 'all-cpu'
Requires-Dist: pytest-xdist>=3.6; extra == 'all-cpu'
Requires-Dist: pytest>=8.3.5; extra == 'all-cpu'
Requires-Dist: radon>=6.0; extra == 'all-cpu'
Requires-Dist: ruff>=0.14; extra == 'all-cpu'
Requires-Dist: scikit-learn>=1.5; extra == 'all-cpu'
Requires-Dist: shellcheck-py>=0.10; extra == 'all-cpu'
Requires-Dist: straindesign>=1.18; extra == 'all-cpu'
Requires-Dist: tellurium>=2.2; extra == 'all-cpu'
Requires-Dist: toml-sort>=0.23; extra == 'all-cpu'
Requires-Dist: vulture>=2.14; extra == 'all-cpu'
Requires-Dist: wemake-python-styleguide>=1.0; extra == 'all-cpu'
Requires-Dist: xenon>=0.9; extra == 'all-cpu'
Provides-Extra: all-gpu
Requires-Dist: bandit[toml]>=1.8.0; extra == 'all-gpu'
Requires-Dist: blackjax>=1.2; extra == 'all-gpu'
Requires-Dist: build>=1.0.3; extra == 'all-gpu'
Requires-Dist: deadcode>=2.4.1; extra == 'all-gpu'
Requires-Dist: deptry>=0.23.0; extra == 'all-gpu'
Requires-Dist: efmtool>=0.2; extra == 'all-gpu'
Requires-Dist: equilibrator-api<0.7,>=0.6; extra == 'all-gpu'
Requires-Dist: equilibrator-pathway>=0.6; extra == 'all-gpu'
Requires-Dist: griffe>=1.7.3; extra == 'all-gpu'
Requires-Dist: hippogriffe>=0.2; extra == 'all-gpu'
Requires-Dist: import-linter>=2.0; extra == 'all-gpu'
Requires-Dist: interrogate>=1.5; extra == 'all-gpu'
Requires-Dist: ipykernel>=6.29.5; extra == 'all-gpu'
Requires-Dist: jax[cuda12]>=0.6.1; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: jupytext>=1.16.0; extra == 'all-gpu'
Requires-Dist: memote>=0.17; extra == 'all-gpu'
Requires-Dist: mkdocs-include-exclude-files>=0.1; extra == 'all-gpu'
Requires-Dist: mkdocs-ipynb>=0.1; extra == 'all-gpu'
Requires-Dist: mkdocs-jupyter>=0.24; extra == 'all-gpu'
Requires-Dist: mkdocs-material>=9.6.7; extra == 'all-gpu'
Requires-Dist: mkdocs<2.0,>=1.6.1; extra == 'all-gpu'
Requires-Dist: mkdocstrings-python>=1.1.2; extra == 'all-gpu'
Requires-Dist: mkdocstrings>=0.28.3; extra == 'all-gpu'
Requires-Dist: mpax>=0.2; extra == 'all-gpu'
Requires-Dist: nvidia-cublas-cu12>=12.6; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-cuda-cupti-cu12>=12.6; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-cuda-nvcc-cu12>=12.6; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-cuda-nvrtc-cu12>=12.6; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-cuda-runtime-cu12>=12.6; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-cudnn-cu12>=9.1; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-cufft-cu12>=11.4; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-curand-cu12>=10.3; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-cusolver-cu12>=11.7; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-cusparse-cu12>=12.3; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-nccl-cu12>=2.20; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-nvjitlink-cu12>=12.6; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: nvidia-nvtx-cu12>=12.6; (sys_platform == 'linux') and extra == 'all-gpu'
Requires-Dist: pre-commit>=4.3.0; extra == 'all-gpu'
Requires-Dist: pygments<3.0,>=2.20; extra == 'all-gpu'
Requires-Dist: pylint>=3.0; extra == 'all-gpu'
Requires-Dist: pymdown-extensions>=10.14.3; extra == 'all-gpu'
Requires-Dist: pyright>=1.1.336; extra == 'all-gpu'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all-gpu'
Requires-Dist: pytest-cov>=6.1.1; extra == 'all-gpu'
Requires-Dist: pytest-env>=1.0.1; extra == 'all-gpu'
Requires-Dist: pytest-json-report>=1.5.0; extra == 'all-gpu'
Requires-Dist: pytest-randomly>=3.15; extra == 'all-gpu'
Requires-Dist: pytest-timeout>=2.1; extra == 'all-gpu'
Requires-Dist: pytest-xdist>=3.6; extra == 'all-gpu'
Requires-Dist: pytest>=8.3.5; extra == 'all-gpu'
Requires-Dist: radon>=6.0; extra == 'all-gpu'
Requires-Dist: ruff>=0.14; extra == 'all-gpu'
Requires-Dist: scikit-learn>=1.5; extra == 'all-gpu'
Requires-Dist: shellcheck-py>=0.10; extra == 'all-gpu'
Requires-Dist: straindesign>=1.18; extra == 'all-gpu'
Requires-Dist: tellurium>=2.2; extra == 'all-gpu'
Requires-Dist: toml-sort>=0.23; extra == 'all-gpu'
Requires-Dist: vulture>=2.14; extra == 'all-gpu'
Requires-Dist: wemake-python-styleguide>=1.0; extra == 'all-gpu'
Requires-Dist: xenon>=0.9; extra == 'all-gpu'
Provides-Extra: all-macos
Requires-Dist: bandit[toml]>=1.8.0; extra == 'all-macos'
Requires-Dist: blackjax>=1.2; extra == 'all-macos'
Requires-Dist: build>=1.0.3; extra == 'all-macos'
Requires-Dist: deadcode>=2.4.1; extra == 'all-macos'
Requires-Dist: deptry>=0.23.0; extra == 'all-macos'
Requires-Dist: efmtool>=0.2; extra == 'all-macos'
Requires-Dist: equilibrator-api<0.7,>=0.6; extra == 'all-macos'
Requires-Dist: equilibrator-pathway>=0.6; extra == 'all-macos'
Requires-Dist: griffe>=1.7.3; extra == 'all-macos'
Requires-Dist: hippogriffe>=0.2; extra == 'all-macos'
Requires-Dist: import-linter>=2.0; extra == 'all-macos'
Requires-Dist: interrogate>=1.5; extra == 'all-macos'
Requires-Dist: ipykernel>=6.29.5; extra == 'all-macos'
Requires-Dist: jax-metal>=0.1.0; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'all-macos'
Requires-Dist: jupytext>=1.16.0; extra == 'all-macos'
Requires-Dist: memote>=0.17; extra == 'all-macos'
Requires-Dist: mkdocs-include-exclude-files>=0.1; extra == 'all-macos'
Requires-Dist: mkdocs-ipynb>=0.1; extra == 'all-macos'
Requires-Dist: mkdocs-jupyter>=0.24; extra == 'all-macos'
Requires-Dist: mkdocs-material>=9.6.7; extra == 'all-macos'
Requires-Dist: mkdocs<2.0,>=1.6.1; extra == 'all-macos'
Requires-Dist: mkdocstrings-python>=1.1.2; extra == 'all-macos'
Requires-Dist: mkdocstrings>=0.28.3; extra == 'all-macos'
Requires-Dist: mpax>=0.2; extra == 'all-macos'
Requires-Dist: pre-commit>=4.3.0; extra == 'all-macos'
Requires-Dist: pygments<3.0,>=2.20; extra == 'all-macos'
Requires-Dist: pylint>=3.0; extra == 'all-macos'
Requires-Dist: pymdown-extensions>=10.14.3; extra == 'all-macos'
Requires-Dist: pyright>=1.1.336; extra == 'all-macos'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all-macos'
Requires-Dist: pytest-cov>=6.1.1; extra == 'all-macos'
Requires-Dist: pytest-env>=1.0.1; extra == 'all-macos'
Requires-Dist: pytest-json-report>=1.5.0; extra == 'all-macos'
Requires-Dist: pytest-randomly>=3.15; extra == 'all-macos'
Requires-Dist: pytest-timeout>=2.1; extra == 'all-macos'
Requires-Dist: pytest-xdist>=3.6; extra == 'all-macos'
Requires-Dist: pytest>=8.3.5; extra == 'all-macos'
Requires-Dist: radon>=6.0; extra == 'all-macos'
Requires-Dist: ruff>=0.14; extra == 'all-macos'
Requires-Dist: scikit-learn>=1.5; extra == 'all-macos'
Requires-Dist: shellcheck-py>=0.10; extra == 'all-macos'
Requires-Dist: straindesign>=1.18; extra == 'all-macos'
Requires-Dist: tellurium>=2.2; extra == 'all-macos'
Requires-Dist: toml-sort>=0.23; extra == 'all-macos'
Requires-Dist: vulture>=2.14; extra == 'all-macos'
Requires-Dist: wemake-python-styleguide>=1.0; extra == 'all-macos'
Requires-Dist: xenon>=0.9; extra == 'all-macos'
Provides-Extra: cuda-dev
Requires-Dist: bandit[toml]>=1.8.0; extra == 'cuda-dev'
Requires-Dist: build>=1.0.3; extra == 'cuda-dev'
Requires-Dist: deadcode>=2.4.1; extra == 'cuda-dev'
Requires-Dist: deptry>=0.23.0; extra == 'cuda-dev'
Requires-Dist: import-linter>=2.0; extra == 'cuda-dev'
Requires-Dist: interrogate>=1.5; extra == 'cuda-dev'
Requires-Dist: ipykernel>=6.29.5; extra == 'cuda-dev'
Requires-Dist: jax[cuda12]>=0.6.1; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: jupytext>=1.16.0; extra == 'cuda-dev'
Requires-Dist: nvidia-cublas-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-cuda-cupti-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-cuda-nvcc-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-cuda-nvrtc-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-cuda-runtime-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-cudnn-cu12>=9.1; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-cufft-cu12>=11.4; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-curand-cu12>=10.3; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-cusolver-cu12>=11.7; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-cusparse-cu12>=12.3; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-nccl-cu12>=2.20; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-nvjitlink-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: nvidia-nvtx-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda-dev'
Requires-Dist: pre-commit>=4.3.0; extra == 'cuda-dev'
Requires-Dist: pylint>=3.0; extra == 'cuda-dev'
Requires-Dist: pyright>=1.1.336; extra == 'cuda-dev'
Requires-Dist: radon>=6.0; extra == 'cuda-dev'
Requires-Dist: ruff>=0.14; extra == 'cuda-dev'
Requires-Dist: shellcheck-py>=0.10; extra == 'cuda-dev'
Requires-Dist: toml-sort>=0.23; extra == 'cuda-dev'
Requires-Dist: vulture>=2.14; extra == 'cuda-dev'
Requires-Dist: wemake-python-styleguide>=1.0; extra == 'cuda-dev'
Requires-Dist: xenon>=0.9; extra == 'cuda-dev'
Provides-Extra: cuda12
Requires-Dist: jax[cuda12]>=0.6.1; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-cublas-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-cuda-cupti-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-cuda-nvcc-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-cuda-nvrtc-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-cuda-runtime-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-cudnn-cu12>=9.1; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-cufft-cu12>=11.4; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-curand-cu12>=10.3; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-cusolver-cu12>=11.7; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-cusparse-cu12>=12.3; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-nccl-cu12>=2.20; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-nvjitlink-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda12'
Requires-Dist: nvidia-nvtx-cu12>=12.6; (sys_platform == 'linux') and extra == 'cuda12'
Provides-Extra: dev
Requires-Dist: bandit[toml]>=1.8.0; extra == 'dev'
Requires-Dist: build>=1.0.3; extra == 'dev'
Requires-Dist: deadcode>=2.4.1; extra == 'dev'
Requires-Dist: deptry>=0.23.0; extra == 'dev'
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: interrogate>=1.5; extra == 'dev'
Requires-Dist: ipykernel>=6.29.5; extra == 'dev'
Requires-Dist: jupytext>=1.16.0; extra == 'dev'
Requires-Dist: pre-commit>=4.3.0; extra == 'dev'
Requires-Dist: pylint>=3.0; extra == 'dev'
Requires-Dist: pyright>=1.1.336; extra == 'dev'
Requires-Dist: radon>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.14; extra == 'dev'
Requires-Dist: shellcheck-py>=0.10; extra == 'dev'
Requires-Dist: toml-sort>=0.23; extra == 'dev'
Requires-Dist: vulture>=2.14; extra == 'dev'
Requires-Dist: wemake-python-styleguide>=1.0; extra == 'dev'
Requires-Dist: xenon>=0.9; extra == 'dev'
Provides-Extra: docs
Requires-Dist: griffe>=1.7.3; extra == 'docs'
Requires-Dist: hippogriffe>=0.2; extra == 'docs'
Requires-Dist: mkdocs-include-exclude-files>=0.1; extra == 'docs'
Requires-Dist: mkdocs-ipynb>=0.1; extra == 'docs'
Requires-Dist: mkdocs-jupyter>=0.24; extra == 'docs'
Requires-Dist: mkdocs-material>=9.6.7; extra == 'docs'
Requires-Dist: mkdocs<2.0,>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings-python>=1.1.2; extra == 'docs'
Requires-Dist: mkdocstrings>=0.28.3; extra == 'docs'
Requires-Dist: pygments<3.0,>=2.20; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.14.3; extra == 'docs'
Provides-Extra: inference
Requires-Dist: blackjax>=1.2; extra == 'inference'
Requires-Dist: efmtool>=0.2; extra == 'inference'
Requires-Dist: equilibrator-api<0.7,>=0.6; extra == 'inference'
Requires-Dist: equilibrator-pathway>=0.6; extra == 'inference'
Requires-Dist: memote>=0.17; extra == 'inference'
Requires-Dist: mpax>=0.2; extra == 'inference'
Requires-Dist: scikit-learn>=1.5; extra == 'inference'
Requires-Dist: straindesign>=1.18; extra == 'inference'
Requires-Dist: tellurium>=2.2; extra == 'inference'
Provides-Extra: metal
Requires-Dist: jax-metal>=0.1.0; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'metal'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest-cov>=6.1.1; extra == 'test'
Requires-Dist: pytest-env>=1.0.1; extra == 'test'
Requires-Dist: pytest-json-report>=1.5.0; extra == 'test'
Requires-Dist: pytest-randomly>=3.15; extra == 'test'
Requires-Dist: pytest-timeout>=2.1; extra == 'test'
Requires-Dist: pytest-xdist>=3.6; extra == 'test'
Requires-Dist: pytest>=8.3.5; extra == 'test'
Description-Content-Type: text/markdown

# Cellifex

<div align="center">

## An AI/ML-native cell-state dynamics foundation model built on JAX/Flax NNX

*From Latin "cellifex" — cell-maker, craftsman of cells*

[Documentation](https://cellifex.readthedocs.io/en/latest/) • [Architecture](https://cellifex.readthedocs.io/en/latest/architecture/) • [Roadmap](https://cellifex.readthedocs.io/en/latest/roadmap/) • [Experiments](https://cellifex.readthedocs.io/en/latest/experiments/) • [Benchmarks](https://cellifex.readthedocs.io/en/latest/benchmarks/v2.0/delta_v1.9/)

</div>

---

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/)
[![JAX](https://img.shields.io/badge/JAX-0.11.1+-green.svg)](https://github.com/google/jax)
[![Flax NNX](https://img.shields.io/badge/Flax-NNX-orange.svg)](https://flax.readthedocs.io/en/latest/nnx)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

> **⚠️ Early Development — API Unstable**
>
> Cellifex is in active alpha development. Public interfaces may change without
> deprecation warnings; gate tolerances continue to tighten as new parity
> tests land. Pin to a specific commit if
> reproducibility is required.
>
> | Area | Status | Current expectation |
> |------|--------|---------------------|
> | **API surface** | Unstable | Breaking changes are preferred over preserving bad interfaces; the layered-architecture contract (domain → service → infrastructure) is the stable boundary. |
> | **Differentiable cores** | Active | FBA / dFBA / RBA / ec-FBA / GECKO / SKiMpy / regulation-CRN / signalling all hold tight SOTA-parity. The JAX-native QP / LP solver framework (`jax_qp`) is bit-exact with cobra HiGHS and `jit`/`vmap`/`grad`-composable end-to-end. |
> | **Learned gates** | Active | All five genome-scale learned MLP gates (MEMOTE, OptKnock, FVA, MFA, DGPrime) have training-loop convergence tests. OptKnock, FVA, MFA and DGPrime have held-out parity tests against reference tools; on MEMOTE's own scores the MEMOTE gate does not yet generalise across hosts (see the held-out table). |
> | **Docs & tests** | Maintained | Pre-commit blocks docstring coverage below 80%, layered-architecture violations and security findings. The test suite exercises every dynamics, gate and scenario module. |

---

## Overview

Cellifex treats the cell as a **differentiable dynamical system**. Every dynamics, constraint, loss, and surrogate module is **JAX-native**: fully `jax.jit`-traceable and `jax.grad`-differentiable. Classical constraint-based (FBA, dFBA, RBA) and kinetic (Michaelis–Menten, lin-log, COBRApy) simulators live strictly under `cellifex.baselines` as data-generation sources and SOTA comparison references — they never appear in the differentiable import chain, enforced by `import-linter` contracts.

The core thesis: traditional cell-state modelling splits into two non-interoperable worlds — rigid mechanistic simulators (accurate but non-differentiable) and surrogate ML models (fast but ungrounded). Cellifex unifies them. Every classical mechanism gets a jittable, differentiable replacement registered behind a six-gate module contract: I/O typing, accuracy spec, gradient cleanness, feasibility, UQ, and registered identity. The result is a single composable surface that supports gradient-based pathway design, end-to-end Bayesian inference, and sub-millisecond inference loops on genome-scale models.

### Why Cellifex?

- **Differentiable through the whole stack** — From metabolite uptake to biomass to pathway score, every layer flows `jax.grad`. No callouts to scipy solvers in the critical path; `jax_qp` provides the LP/QP forward + OptNet KKT-IFT backward as pure JAX.
- **SOTA-parity verified, not just executable** — Each replacement module has held-out parity tests against the current leading open-source tool (`cobra`, `straindesign`, `memote`, `mfapy`, `equilibrator-api`, `efmtool`, `equilibrator-pathway`, `tellurium`, `sklearn` Lasso). The test contracts use empirical-floor thresholds with documented headroom margins.
- **8 host configurations out of the box** — *E. coli* (core + iJO1366), *S. cerevisiae* (iMM904, standing in for Yeast9), *B. subtilis*, *K. phaffii*, *Y. lipolytica*, *C. glutamicum*, *P. putida*. Five GEMs are committed under `models/`; `iJO1366` comes from cobra's bundled models, and `iMM904` and `iYO844` are downloaded from BiGG on first use.
- **Six-gate module contract** — Every public dynamics or gate module exposes (1) typed I/O, (2) accuracy spec, (3) clean `jax.grad`, (4) feasibility invariant, (5) UQ surface, (6) registered identity. The contract is type-checked at the protocol layer and grad-checked at runtime.
- **Layered architecture enforced statically** — `domain` → `service` → `infrastructure` import direction is enforced by `import-linter`; baselines live in a sealed compartment by a second `import-linter` contract. Bad-layer imports break CI.

## Features

### Differentiable cell-process modules

| Module | Replaces |
|---|---|
| `DifferentiableFBA` | `cobra.flux_balance_analysis` |
| `DifferentiableCRN` (regulation) | `bioscrape.py_simulate_model` |
| `DifferentiableRBAFull` | scipy-HiGHS bilevel Scott-Hwa |
| `DifferentiableGECKO` | scipy-HiGHS ec-FBA |
| `DifferentiableSkimpy` | reversible-MM + Haldane closure |
| `DifferentiableDFBA` | COBRApy dFBA Mahadevan loop |
| `DifferentiableECFBA` | cobra `solve_ec_fba` |
| `DifferentiableSignalling` | tellurium / libRoadRunner BIOMD0000000010 MAPK cascade |
| `KineticDynamics` | tellurium / libRoadRunner symbolic MM rate-rule evaluation (also matches SKiMpy reversible-MM at zero product) |

### Learned MLP gates (sub-millisecond inference)

| Gate | Replaces |
|---|---|
| `MemoteLearnedGate` | `memote.suite.api.test_model` |
| `OptKnockLearnedGate` | `straindesign.compute_strain_designs` (Burgard-Maranas bilevel MILP) |
| `FVALearnedGate` | `cobra.flux_variability_analysis` |
| `MfaLearnedGate` | `mfapy.metabolicmodel.fitting_flux` |
| `DGPrimeLearnedGate` | `equilibrator_api.standard_dg_prime` |
| `RetrosynthRerankerGate` | aizynthfinder `StateScorer` |

All five genome-scale gates consume the typed **22-dim v2 GEM-feature surface** from `cellifex.data.gem_features.GEMFeaturesV2`; `jax.grad` and `nnx.grad` flow cleanly through every gate.

### Neural-operator + generative backbones

- **Neural operators** — FNO (1D-heat operator parity), DeepONet (antiderivative-operator parity), StandardPINN (1D-Poisson parity)
- **Generative families** — VAE, Flow (RealNVP), DDPM via `artifex.generative_models.factory`; wrapper-drift parity tests at `atol=1e-6` against the raw sibling implementations
- **L2O** — `LearnToOptimize` via `opifex.optimization.meta_optimization`
- **Neural-ODE / SDE / CDE** — diffrax-based with `nnx.Module` wrapping
- **SINDy** — symbolic regression via `opifex.discovery.sindy` with numpy `lstsq` parity

### JAX-native differentiable QP / LP solver

`cellifex.dynamics.metabolism.jax_qp` ships a fully JAX-compatible QP/LP solver framework. Forward: MPAX r²HPDHG (Lu-Yang 2023; bit-exact with cobra HiGHS at FBA scale) plus a pure-JAX Chambolle-Pock PDHG fallback. Backward: OptNet KKT-IFT via Murty iterative-refinement active-set polish + `lineax.AutoLinearSolver` adjoint solve. Reverse-mode `jax.grad` composes with `jit`/`vmap` end-to-end. No scipy callbacks — fully GPU-native.

### Proteome-economics gates (analytical + learned)

`MDF`, `ECM`, `EFM`, `cMCS`, `Dekel–Alon ridge` — both analytical and learned variants. MDF gate matches `equilibrator-pathway` within `1e-3 kJ/mol` on the Beber 2022 CCM fixture; EFM gate matches `efmtool` top-k ranking on a 4-metabolite × 6-reaction branched network.

### Closed-loop DBTL

Real **JBEI Flaviolin multi-cycle yield data** (241 rows × 5 cycles, Zenodo `10.5281/zenodo.15093363`) drives scenario I; scenario J adds human-in-the-loop gate review through the `ai-for-science-hub` bridge.

## Parity & held-out verification

> This section lists the tests that compare cellifex's implementations with external reference tools. Without such a comparison a differentiable replacement only shows that it runs; with it, the module is checked against the reference tool's output while staying composable through `jax.grad` / `jit` / `vmap`.

Each module below is compared with the **current leading open-source tool** for its task. The SOTA tools are not selected once and frozen — they are tracked: if the canonical reference for a task moves (e.g. OptKnock's open-source SOTA shifted from the COBRApy single-deletion proxy to `straindesign`'s bilevel MILP), the cellifex reference moves with it. Tests are `pytest.importorskip`-gated on the reference package so the suite still runs when an extra is not installed. CI runs them in a separate reference-tools job that installs the `inference` extra and the `mfapy` group; bioscrape is not part of that extra, so its parity tests still skip there.

### SOTA parity per module

Forward parity: the cellifex module's output is compared against the SOTA reference on a fixed input fixture and asserted within a documented tolerance.

| Module | SOTA reference | Tolerance |
|---|---|---|
| `DifferentiableFBA` | `cobra.flux_balance_analysis` | flux MSE < 1%, biomass rel-err < 0.5% across 60 conditions |
| `DifferentiableCRN` | `bioscrape.py_simulate_model` | per-timepoint rel-err < 5% across all dynamic species |
| `DifferentiableRBAFull` | scipy-HiGHS bilevel Scott-Hwa | inner-LP biomass < 1%; μ\* < 1e-3 h⁻¹ |
| `DifferentiableGECKO` | scipy-HiGHS ec-FBA | biomass rel-err < 1% with real BRENDA k_cats |
| `DifferentiableDFBA` | COBRApy dFBA Mahadevan loop | biomass rel-L2 < 2% |
| `DifferentiableECFBA` | cobra `solve_ec_fba` | per-condition rel-err < 1% across 5 enzyme levels; envelope-theorem gradient non-zero in binding regime, zero in saturated |
| `DifferentiableSignalling` | tellurium / libRoadRunner | endpoint and trajectory rel-err < 5% on BIOMD0000000010 |
| `KineticDynamics` | tellurium / libRoadRunner | per-reaction rate rel-err < 1e-12 on a 3-reaction MM cascade (A→B→C→D) |
| `MemoteLearnedGate` | MEMOTE snapshot-report score (`memote.suite.reporting.SnapshotReport`) | default-init gate score within 0.05 of the fixture's MEMOTE total |
| `OptKnockLearnedGate` | `straindesign.compute_strain_designs` | every SOTA design dominates wildtype target flux; gate finite + bounded on every design mask |
| `FVALearnedGate` | `cobra.flux_variability_analysis` | per-reaction bias-calibrated parity within 1e-2 mmol/gDW/h |
| `MfaLearnedGate` | synthetic stand-in fixture (pFBA mean, 10% sigma; mfapy cannot fit e_coli_core) | per-reaction `(flux_mean, flux_sigma)` bias-calibrated parity within 1e-3 |
| `DGPrimeLearnedGate` | `equilibrator_api.standard_dg_prime` | per-reaction ΔG'° bias-calibrated parity within 1e-3 kJ/mol |
| `mdf_gate` | `equilibrator_pathway.ThermodynamicModel.mdf_analysis` | within 1e-3 kJ/mol on the Beber 2022 CCM fixture |
| `efm_gate` | `efmtool.calculate_efms` | top-k ranking matches enumerated EFMs on a 4-met × 6-rxn branched network |
| Surrogate backbone wrappers | raw `artifex` / `opifex` reference modules | per-seed `wrapped(x) == direct(x)` at `atol=1e-6` |
| FNO (`neural_operators.py`) | analytical 1D-heat operator (α=0.01, T=0.1) | held-out RMSE < 0.1 after 300 epochs on 64 analytical training pairs |
| DeepONet (`neural_operators.py`) | analytical antiderivative operator (Lu 2021 sin/cos family) | held-out RMSE < 0.05 after 1500 Adam steps |
| StandardPINN (`pinns.py`) | analytical 1D-Poisson solution | max-abs error < 0.05 after 1500 Adam steps |

### Held-out generalisation

Held-out parity goes **deeper than forward parity**: the learned gate is trained end-to-end on **N − 1** conditions and verified on the **N-th** held-out condition, against the SOTA tool's output at that held-out condition. This is the test that distinguishes "gate matches the training data" from "gate generalises across the natural perturbation axis the gate is designed for". A gate can pass forward parity at a single calibration point yet fail to generalise — held-out tests catch that gap.

| Gate | Perturbation axis | Held-out test | SOTA baseline | Tolerance |
|---|---|---|---|---|
| `FVALearnedGate` | `biomass_fraction` ∈ {0.5, 0.8, 0.95, 0.99} | leave-one-out at α = 0.8 (interior) | `cobra.flux_variability_analysis` per α | p95 per-reaction abs-err < 15 mmol/gDW/h |
| `DGPrimeLearnedGate` | `(pH, ionic_strength, T, pMg)` (4 tuples) | leave-one-out at physiological standard | `equilibrator_api.standard_dg_prime` per tuple | p95 per-reaction ΔG_mean < 5 kJ/mol; ΔG_sigma < 1 kJ/mol |
| `OptKnockLearnedGate` | multi-knockout design space | 4-fold cross-validation on 39 SOTA bilevel-MILP designs | `straindesign.compute_strain_designs` succinate target | mean held-out abs-err < 1.5 mmol/gDW/h |
| `MemoteLearnedGate` | host organism (8-host sweep) | leave-one-host-out with L1-regularised training | `sklearn.linear_model.Lasso` (small-data sparse linear regression) | target: gate mean abs-err ≤ 110% of Lasso. Not met on memote 0.17.0 scores (gate 0.232, Lasso 0.156, training-mean predictor 0.216); the test is a strict expected failure |

Training-loop convergence tests (10-step descent + 500-1500 step Adam fit) verify that the loss surface, gradient computation, and optimizer configuration work correctly end-to-end for each learned gate.

The shared `tests/_gate_training.py::train_for_n_steps` helper exposes an optional `l1_strength` kwarg for small-data sparse-regression training; both the L1 regularizer and the Adam loop run inside `nnx.jit` for fully JAX-native training. The SOTA baseline does not need to be JAX-compatible (e.g. `sklearn.linear_model.Lasso` for MEMOTE held-out); only the gate's own forward and training do.

## Installation

Cellifex uses [`uv`](https://github.com/astral-sh/uv) exclusively for dependency management. Conda, pip, and poetry are not supported.

```bash
# Linux / macOS CPU
uv pip install -e ".[all-cpu]"

# Linux GPU (CUDA 12 local)
uv pip install -e ".[all-gpu]"

# macOS Apple Silicon (Metal)
uv pip install -e ".[all-macos]"

# Inference extras (memote, straindesign, equilibrator-api, ...)
uv pip install -e ".[inference]"

# mfapy, the 13C-MFA reference, is published only on GitHub, so it is a uv
# dependency group rather than an extra
uv sync --extra inference --group mfapy
```

For first-time setup from a source checkout:

```bash
# One-time GPU-enabled venv setup
bash setup.sh
source activate.sh
uv pip install -e ".[dev,inference]"
```

The setup script:

- Creates a `.venv` with `uv` and a CUDA 12 backend if a GPU is detected
- Pins JAX to the matching backend automatically
- Writes a generated `.cellifex.env` and leaves `.env` for user-owned overrides

`source activate.sh` is required every shell session; it refreshes the managed backend state before applying user overrides.

## Quickstart

### Run the test suite

```bash
source activate.sh
uv run pytest -x
```

The tests exercise every dynamics module, learned gate, scenario, and held-out parity contract.

### Solve a forward FBA

```python
from flax import nnx
from cellifex.dynamics.metabolism.diff_fba import DifferentiableFBA, FBASolverConfig

# Load E. coli core and build a jittable FBA module.
module = DifferentiableFBA.from_host_id(
    "ecoli_core",
    rngs=nnx.Rngs(0),
    config=FBASolverConfig(strategy="relaxed_qp"),
)

# Forward solve — sub-millisecond on e_coli_core.
result = module()
print(f"biomass flux = {result['biomass']:.4f} h^-1")
```

### Run a learned gate

```python
import jax.numpy as jnp
from flax import nnx
from cellifex.gates.memote_learned import MemoteLearnedGate
from cellifex.data.gem_features import extract_gem_features_v2, gem_features_v2_to_mlp_input
from cellifex.hosts import HOSTS

# 22-dim v2 GEM features for e_coli_core.
model = HOSTS["ecoli_core"].load_model()
features = gem_features_v2_to_mlp_input(extract_gem_features_v2(model))

gate = MemoteLearnedGate(rngs=nnx.Rngs(0), reference_score=0.5)
score = float(gate(jnp.asarray(features)))
print(f"predicted MEMOTE total score = {score:.4f}")
```

### Regenerate a benchmark report

The reports list the host and backbone roster of a version; every metric is marked not measured.

```bash
uv run python scripts/run_benchmark_sweep.py --backbones 14 --output docs/benchmarks/v2.0
```

### Run the JBEI HITL review loop

```bash
uv run python scripts/run_scenario_j.py
```

## Documentation

### Start here

- **[Architecture](https://cellifex.readthedocs.io/en/latest/architecture/)** — Three-tier layered design (domain / service / infrastructure), import contracts, six-gate module contract.
- **[Roadmap](https://cellifex.readthedocs.io/en/latest/roadmap/)** — Module catalogue, baseline-replacement trajectory, current status table.
- **[Index](https://cellifex.readthedocs.io/en/latest/)** — Top-level feature tour with cards.

### Domain references

- **[Host profiles](https://cellifex.readthedocs.io/en/latest/host_profiles/)** — Eight host organism configs with GEM source provenance.
- **[Experiments](https://cellifex.readthedocs.io/en/latest/experiments/)** — Nine reference scenarios (A–F, H–J) mapped to strain-design workflow steps.
- **[Strain-design alignment](https://cellifex.readthedocs.io/en/latest/strain_design_alignment/)** — DBTL-step ↔ cellifex-module mapping.
- **[Proteome economics](https://cellifex.readthedocs.io/en/latest/proteome_economics/)** — MDF / ECM / EFM / cMCS / Dekel–Alon gates.
- **[Coupling contracts](https://cellifex.readthedocs.io/en/latest/coupling-contracts/)** — Module ↔ module typed interfaces.

### API reference

- **[Index](https://cellifex.readthedocs.io/en/latest/api-reference/)** • **[Dynamics](https://cellifex.readthedocs.io/en/latest/api-reference/dynamics/)** • **[Gates](https://cellifex.readthedocs.io/en/latest/api-reference/gates/)** • **[Surrogates](https://cellifex.readthedocs.io/en/latest/api-reference/surrogates/)**
- **[Hosts](https://cellifex.readthedocs.io/en/latest/api-reference/hosts/)** • **[Composers](https://cellifex.readthedocs.io/en/latest/api-reference/composers/)** • **[Adapters](https://cellifex.readthedocs.io/en/latest/api-reference/adapters/)** • **[Schema](https://cellifex.readthedocs.io/en/latest/api-reference/schema/)** • **[Baselines](https://cellifex.readthedocs.io/en/latest/api-reference/baselines/)**

### Ecosystem

- **[Ecosystem](https://cellifex.readthedocs.io/en/latest/ecosystem/)** — Sibling-repo dependency graph + contribution-back contract.
- **[Sibling pinning](https://cellifex.readthedocs.io/en/latest/sibling_pinning/)** — Pin policy for cross-repo deps.
- **[Benchmarks](https://cellifex.readthedocs.io/en/latest/benchmarks/v2.0/delta_v1.9/)** — Host and backbone roster per version (metrics not measured yet).

## Architecture

```text
cellifex/
├── src/cellifex/
│   ├── dynamics/             # Differentiable cell processes (FBA, dFBA, RBA, GECKO, signalling, ...)
│   │   └── metabolism/jax_qp/   # JAX-native QP / LP solver (MPAX + OptNet KKT-IFT)
│   ├── gates/                # Analytical + learned gate modules (MEMOTE, OptKnock, FVA, MFA, ΔG'°, ...)
│   ├── surrogates/           # Backbones (Neural-ODE, FNO, DeepONet, PINN, SINDy, generative, L2O) + registry
│   ├── schema/               # Typed state, protocols, contracts (cross-cutting domain-layer)
│   ├── losses/               # Biology-informed + composite loss functions
│   ├── constraints/          # Mass-balance, thermodynamic, proteome-economic relaxations
│   ├── derivers/             # Domain-layer derived quantities
│   ├── hosts/                # Eight organism configs
│   ├── data/                 # Concentration contracts, GEM features (v2), provenance enum
│   ├── composers/            # Service-layer assemblies (ec_core_cell, full_cell)
│   ├── engines/              # Rollout + active-learning drivers
│   ├── metrics/              # Flux + trajectory metrics
│   ├── baselines/            # Sealed SynBio 1.0 + SOTA references (isolated via import-linter)
│   ├── adapters/             # Sibling-repo bridges (artifex, opifex, datarax, calibrax, hub)
│   ├── io/                   # Dataset readers / writers
│   └── monitoring.py         # Profiler wrapper
├── docs/                     # Public documentation
├── tests/                    # Unit, integration, scenario, parity tests
├── scripts/                  # Operational entry points (benchmark sweep, regen, audit)
├── notebooks/                # Demo + walkthrough notebooks
└── models/                   # Committed SBML + COBRA models
```

See [Architecture](https://cellifex.readthedocs.io/en/latest/architecture/) for the layered import map and module contracts.

## Sibling repositories

Cellifex is part of the **Avitai Bio** ecosystem and consumes stable primitives from eight sibling packages. Every cross-repo dependency is pinned in `pyproject.toml` and its role is documented in [`docs/ecosystem.md`](https://cellifex.readthedocs.io/en/latest/ecosystem/).

| Sibling | Role in cellifex |
|---|---|
| [datarax](https://github.com/avitai/datarax) | Dataset + DAG pipeline primitives (`Element`, `Batch`, `Source`, `Pipeline`) |
| [artifex](https://github.com/avitai/artifex) | Generative-model factory (VAE / Flow / DDPM backbones, MLP, Trainer) |
| [opifex](https://github.com/avitai/opifex) | Neural operators, PINNs, SINDy, L2O, Neural-ODE adapters |
| [calibrax](https://github.com/avitai/calibrax) | Metrics + benchmark composition (`Metric`, `MetricSuite`, `Comparison`) |
| [DiffBio](https://github.com/avitai/DiffBio) | Differentiable bioinformatics operators + `soft_ops` (soft argmax / quantile / sort) |
| ai-for-science-hub | HITL review queue + LLM-completion bridge for scenario J |
| playground | Monitoring profiler + neural-vitai species embedding service |
| avitai-knowledge | Knowledge-base lookups (kinetic priors, kcat tables) |

## Development

### Pre-commit gates

19 hooks block any commit that fails. The non-trivial ones:

```bash
uv run pre-commit run --all-files
```

- `ruff` linter + `ruff format` formatter
- `pyright` type checker (zero errors enforced on `src/`)
- `bandit` security scanner (no medium/high findings)
- `import-linter` layered-architecture contracts (domain ≠ infrastructure; baselines isolated)
- `interrogate` docstring coverage (≥ 80%)
- `shellcheck` for `bash` / `sh` scripts
- A custom Ruff config blocking print statements, mutable defaults, bare `except`, and other SWE-bans

### Test suite

```bash
uv run pytest                                    # full suite (about 17 min on a CI runner)
uv run pytest -x --ignore=tests/test_jax_qp.py   # fast path (~30 s)
uv run pytest tests/test_memote_learned.py       # single module
```

The tests cover:

- Per-module unit tests (forward shape, grad finiteness, registered identity)
- Per-module SOTA-parity tests (`importorskip`-gated when extras absent)
- Scenario regression tests (A–J)
- Strict `jit`+`grad` smoke tests across every public module
- Held-out parity tests against the current leading open-source SOTA tool per module

### Engineering principles

Cellifex follows the avitai-ecosystem-wide standards:

1. **Zero tech debt** — refactor toward the better design now, never defer.
2. **TDD mandatory** — tests first; thresholds set from empirical floors; never loosen to make a failing test pass.
3. **DRY essential** — extract on the third occurrence; centralise constants; one source of truth per knowledge.
4. **No backward compatibility constraints** — breaking changes are preferred when they produce cleaner foundations.

See [Architecture](https://cellifex.readthedocs.io/en/latest/architecture/) and [Coupling contracts](https://cellifex.readthedocs.io/en/latest/coupling-contracts/) for the design framework these principles operate within.

## Project status

Cellifex is in **active alpha**.

- Installation, quickstart, and developer-guide docs are built with `mkdocs build --strict` in CI.
- CI runs the test suite on every push to main and on pull requests; the tests that compare against reference tools, including the held-out parity tests, run in the reference-tools job.
- Public API surfaces evolve when a simpler or more truthful runtime design requires it. There is no LTS branch.

Use [Architecture](https://cellifex.readthedocs.io/en/latest/architecture/), [Roadmap](https://cellifex.readthedocs.io/en/latest/roadmap/), and [Ecosystem](https://cellifex.readthedocs.io/en/latest/ecosystem/) as the current source of truth for supported workflows.

## Contributing

Cellifex accepts contributions through the standard repository workflow:

1. Clone the repository and run `bash setup.sh`.
2. Activate the environment: `source activate.sh`.
3. Create a feature branch.
4. Add or update tests first (TDD); document any new public surface.
5. Run `uv run pytest` and `uv run pre-commit run --all-files`.
6. Open a PR. CI runs the test suite, `pre-commit`, `pyright`, and `import-linter`.

New public modules document the literature formulation they implement, the reference tool their parity tests compare against, and their differentiability contract.

## Citation

If you use Cellifex in research, please cite:

```bibtex
@software{cellifex_2026,
  title = {Cellifex: An AI/ML-Native Cell-State Dynamics Foundation Model},
  author = {Shafiei, Mahdi and contributors},
  year = {2026},
  url = {https://github.com/avitai/cellifex},
  version = {0.0.1}
}
```

## License

This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.

## Acknowledgments

Cellifex builds on several strong open-source projects:

- [JAX](https://github.com/google/jax) — Numerical computing and transformations
- [Flax](https://github.com/google/flax) — Neural network modules with NNX support
- [Optax](https://github.com/deepmind/optax) — Optimization utilities
- [Orbax](https://github.com/google/orbax) — Checkpointing
- [diffrax](https://github.com/patrick-kidger/diffrax) — ODE / SDE / CDE solvers in JAX
- [lineax](https://github.com/patrick-kidger/lineax) — JAX-native linear solves (adjoint backward in `jax_qp`)
- [MPAX](https://github.com/MIT-Lu-Lab/MPAX) — JAX-native r²HPDHG LP solver (forward in `jax_qp`)
- [equinox](https://github.com/patrick-kidger/equinox) — Library backbones for `jax_qp/_pdhg_solver.py`
- [COBRApy](https://github.com/opencobra/cobrapy) — Reference FBA / FVA / dFBA implementations
- [memote](https://github.com/opencobra/memote) — SOTA GEM quality scoring
- [straindesign](https://gitlab.com/cnapy-org/StrainDesign) — SOTA bilevel-MILP OptKnock (Schneider 2022)
- [mfapy](https://github.com/fumiomatsuda/mfapy) — Canonical 13C-MFA SLSQP reference
- [equilibrator-api](https://gitlab.com/equilibrator/equilibrator-api) — eQuilibrator-CC ΔG'° (Beber 2022)
- [efmtool](https://github.com/CSBSchildPrivate/efmtool-python) — Schuster 2000 EFM enumeration
- [BlackJAX](https://github.com/blackjax-devs/blackjax) — Bayesian flux posterior inference
- [tellurium](https://github.com/sys-bio/tellurium) — libRoadRunner SBML reference simulator

---

<div align="center">

**[Documentation](https://cellifex.readthedocs.io/en/latest/)** • **[GitHub](https://github.com/avitai/cellifex)** • **[Issues](https://github.com/avitai/cellifex/issues)**

</div>
