mxlpy 0.63.0__tar.gz → 0.64.0__tar.gz

mxlpy-0.64.0/.github/workflows/e2e.yml

@@ -0,0 +1,23 @@
+name: e2e
+
+# Cross-repo end-to-end tests of the mxl codegen pipeline
+# (https://github.com/Computational-Biology-Aachen/mxl-e2e).
+# Advisory for now: not a required status check.
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  e2e:
+    uses: Computational-Biology-Aachen/mxl-e2e/.github/workflows/e2e.yml@main
+    with:
+      repo: ${{ github.repository }}
+      ref: ${{ github.event.pull_request.head.sha || github.sha }}

mxlpy-0.64.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: mxlpy
+Version: 0.64.0
+Summary: A package to build metabolic models
+Author-email: Marvin van Aalst <marvin.vanaalst@gmail.com>
+Maintainer-email: Marvin van Aalst <marvin.vanaalst@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: metabolic,modelling,ode
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Requires-Dist: dill>=0.3.9
+Requires-Dist: kiwisolver>=1.5
+Requires-Dist: latexify-py>=0.4.4
+Requires-Dist: lazy-import>=0.2.2
+Requires-Dist: loky>=3.4
+Requires-Dist: matplotlib>=3.9.2
+Requires-Dist: mike>=2.1.3
+Requires-Dist: more-itertools>=10.5.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: numpy>=2.1.2
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: parameteriser>=0.1.0
+Requires-Dist: pillow>=12.1.1
+Requires-Dist: pysbml>=0.3.0
+Requires-Dist: python-libsbml>=5.20.4
+Requires-Dist: rpds-py>=0.30.0
+Requires-Dist: salib>=1.5.1
+Requires-Dist: scipy>=1.14.1
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: symbtools>=0.4.0
+Requires-Dist: sympy>=1.13.1
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: tqdm>=4.66.6
+Requires-Dist: typing-extensions>=4.12.2
+Requires-Dist: wadler-lindig>=0.1.7
+Provides-Extra: jax
+Requires-Dist: diffrax>=0.7.0; extra == 'jax'
+Requires-Dist: equinox>=0.13; extra == 'jax'
+Requires-Dist: optax>=0.2.5; extra == 'jax'
+Requires-Dist: sympy2jax>=0.0.7; extra == 'jax'
+Provides-Extra: keras
+Requires-Dist: keras>=3.9.2; extra == 'keras'
+Provides-Extra: sr
+Requires-Dist: pysr>=1.5.9; extra == 'sr'
+Provides-Extra: tensorflow
+Requires-Dist: tensorflow>=2.19.0; extra == 'tensorflow'
+Provides-Extra: torch
+Requires-Dist: torch>=2.5.1; extra == 'torch'
+Description-Content-Type: text/markdown
+
+<p align="center">
+    <img src="https://raw.githubusercontent.com/Computational-Biology-Aachen/MxlPy/refs/heads/main/docs/assets/logo-diagram.png" width="600px" alt='mxlpy-logo'>
+</p>
+
+
+
+# MxlPy
+
+[docs-badge]: https://img.shields.io/badge/docs-main-green.svg?style=flat-square
+[docs]: https://computational-biology-aachen.github.io/MxlPy/latest/index.html
+
+[![pypi](https://img.shields.io/pypi/v/mxlpy.svg)](https://pypi.python.org/pypi/mxlpy)
+[![docs][docs-badge]][docs]
+![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)
+![Coverage](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fgist.github.com%2Fmarvinvanaalst%2F98ab3ce1db511de42f9871e91d85e4cd%2Fraw%2Fcoverage.json&query=%24.message&label=Coverage&color=%24.color&suffix=%20%25)
+[![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)
+[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![PyPI Downloads](https://static.pepy.tech/badge/mxlpy)](https://pepy.tech/projects/mxlpy)
+
+MxlPy (pronounced "em axe el pie") is a Python package for mechanistic learning (Mxl) - the combination of mechanistic modeling and machine learning to deliver explainable, data-informed solutions.
+
+## Documentation
+
+You can find extensive documentation directly here on [github][docs]
+
+## Installation
+
+You can install mxlpy using pip: `pip install mxlpy`.
+
+Due to their sizes, the machine learning packages are optional dependencies. You can install them using
+
+```shell
+# One of them respectively
+pip install mxlpy[torch]
+pip install mxlpy[tensorflow]
+pip install mxlpy[keras]
+pip install mxlpy[jax]
+pip install mxlpy[sr]
+
+# together
+pip install mxlpy[torch, tensorflow, keras, jax, sr]
+```
+
+If you want access to the sundials solver suite via the [assimulo](https://jmodelica.org/assimulo/) package, we recommend setting up a virtual environment via [pixi](https://pixi.sh/) or [mamba / conda](https://mamba.readthedocs.io/en/latest/) using the [conda-forge](https://conda-forge.org/) channel.
+
+```bash
+pixi init
+pixi add python assimulo
+pixi add --pypi mxlpy
+```
+
+## How to cite
+
+If you use this software in your scientific work, please cite [this article](https://doi.org/10.1101/2025.05.06.652335):
+
+- [doi](https://doi.org/10.1101/2025.05.06.652335)
+- [bibtex file](https://github.com/Computational-Biology-Aachen/MxlPy/citation.bibtex)
+
+
+## Development setup
+
+You have two choices here, using `uv` (pypi-only) or using `pixi` (conda-forge, including assimulo)
+
+### uv
+
+- Install `uv` as described in [the docs](https://docs.astral.sh/uv/getting-started/installation/).
+- Run `uv sync --all-extras --all-groups` to install dependencies locally
+
+### pixi
+
+- Install `pixi` as described in [the docs](https://pixi.sh/latest/#installation)
+- Run `pixi install --frozen`
+
+
+## LLMs
+
+We support the [llms.txt](https://llmstxt.org/) convention for making documentation available to large language models and the applications that make use of them. It is located at [docs/llms.txt](https://github.com/Computational-Biology-Aachen/MxlPy/tree/main/docs/llms.txt)
+
+## Tool family 🏠
+
+`MxlPy` is part of a larger family of tools that are designed with a similar set of abstractions. Check them out!
+
+- [MxlBricks](https://github.com/Computational-Biology-Aachen/mxl-bricks) is built on top of `MxlPy` to build mechanistic models composed of pre-defined reactions (bricks)
+- [MxlModels](https://github.com/Computational-Biology-Aachen/mxl-models) supplies flat, single-file versions of MxlBricks models for easy inspection
+- [MxlWeb](https://github.com/Computational-Biology-Aachen/mxl-web) brings simulation of mechanistic models to the browser!
+- [pysbml](https://github.com/Computational-Biology-Aachen/pysbml) simplifies SBML models for import/export with MxlPy
+- [Parameteriser](https://gitlab.com/marvin.vanaalst/parameteriser) looks up kinetic parameters from BRENDA and other databases

mxlpy-0.64.0/pyproject.toml

@@ -0,0 +1,224 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[dependency-groups]
+dev = [
+    "coverage>=7.6.4",
+    "jupyter>=1.1.1",
+    "line-profiler>=5.0.0",
+    "mkdocs-jupyter>=0.25.1",
+    "mkdocs-material>=9.5.42",
+    "mkdocs>=1.6.1,<2.0.0",
+    "pre-commit>=4.0.1",
+    "pyright>=1.1.403",
+    "pytest-cov>=5.0.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
+    "pytest>=8.3.3",
+    "requests>=2.32.3",
+    "ruff>=0.15.11",
+    "ssort>=0.13.0",
+    "toml-sort>=0.23.1",
+]
+
+[project]
+authors = [{ email = "marvin.vanaalst@gmail.com", name = "Marvin van Aalst" }]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: OS Independent",
+    "Operating System :: POSIX",
+    "Operating System :: Unix",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "dill>=0.3.9",
+    "kiwisolver>=1.5",           # only to get 3.14 build to work
+    "latexify-py>=0.4.4",
+    "lazy-import>=0.2.2",
+    "loky>=3.4",
+    "matplotlib>=3.9.2",
+    "mike>=2.1.3",
+    "more-itertools>=10.5.0",
+    "networkx>=3.0",
+    "numpy>=2.1.2",
+    "pandas>=2.2.3",
+    "parameteriser>=0.1.0",
+    "pillow>=12.1.1",            # only to get 3.14 build to work
+    "pysbml>=0.3.0",
+    "python-libsbml>=5.20.4",
+    "rpds-py>=0.30.0",           # only to get 3.14 build to work
+    "salib>=1.5.1",
+    "scipy>=1.14.1",
+    "seaborn>=0.13.2",
+    "symbtools>=0.4.0",
+    "sympy>=1.13.1",
+    "tabulate>=0.9.0",
+    "toml>=0.10.2",
+    "tqdm>=4.66.6",
+    "typing-extensions>=4.12.2",
+    "wadler-lindig>=0.1.7",
+]
+description = "A package to build metabolic models"
+keywords = ["metabolic", "modelling", "ode"]
+license = "MIT"
+maintainers = [
+    { email = "marvin.vanaalst@gmail.com", name = "Marvin van Aalst" },
+]
+name = "mxlpy"
+readme = "README.md"
+requires-python = ">=3.12"
+version = "0.64.0"
+
+[project.optional-dependencies]
+jax = ["diffrax>=0.7.0", "equinox>=0.13", "optax>=0.2.5", "sympy2jax>=0.0.7"]
+keras = ["keras>=3.9.2"]
+sr = ["pysr>=1.5.9"]
+tensorflow = ["tensorflow>=2.19.0"]
+torch = ["torch>=2.5.1"]
+
+[tool.bandit]
+skips = ["B101", "B301", "B403", "B404", "B603", "B607"]
+
+[tool.hatchling]
+from = "src"
+include = ["example_models", "mxlpy"]
+
+[tool.hatchling.extras]
+examples = ["example_models"]
+
+[tool.pyright]
+deprecateTypingAliases = true
+exclude = [
+    "**/.*",
+    "**/__pycache__",
+    "**/node_modules",
+    ".venv",
+    "tests/sbml/assets",
+    "tmp",
+]
+include = ["docs", "src", "tests", 'publication-figures']
+pythonVersion = "3.12"
+reportMissingModuleSource = "none"
+strict = []
+
+[tool.pytest.ini_options]
+timeout = 60
+addopts = ["-n", "auto"]
+markers = [
+    "all_versions: test each case against every available SBML version file (default: preferred version only)",
+]
+
+[tool.ruff]
+# verbatim output of other tools (e.g. mxlweb-core codegen), kept as generated
+extend-exclude = ["tests/assets"]
+force-exclude = true  # also when pre-commit passes the file explicitly
+indent-width = 4
+line-length = 88
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+ignore = [
+    "ANN401",  # any
+    "C901",    # too complex
+    "COM812",  # missing trailing comma  # "D", # all of documentation
+    "D105",    # magic methods
+    "D203",    # blank line before docstring
+    "D213",    # multi-line summary first line
+    "D401",    # first line should be in imperative mood
+    "E501",    # line-too-long
+    "ERA001",  # commented-out code
+    "FIX001",  # line contains FIXME
+    "ISC001",  # single line implicit string concat
+    "N806",    # non-lowercase variable
+    "N818",    # Exception should end in "Error"
+    "PD010",   # pivot table
+    "PGH003",  # specific rule type ignore
+    "PLR0911", # too many statements
+    "PLR0912", # too many branches
+    "PLR0913", # max num of arguments
+    "PLR0915", # too many lines
+    "PT011",   # pytest.raises is too broad
+    "RUF022",  # unsorted all
+    "S110",    # try-except-pass
+    "S301",    # pickle usage
+    "TC006",   # cast("type")
+    "TD001",   # invalid todo tag
+    "TD002",   # missing todo author
+    "TD003",   # missing todo link
+    "TD004",   # missing todo version
+    "TD005",   # missing todo date
+    "TRY003",  # raise vanilla args
+]
+select = ["ALL"]
+
+[tool.ruff.lint.per-file-ignores]
+"*.ipynb" = [
+    "D",    # all of documentation
+    "T201", # print statements
+]
+"tests/*" = [
+    "D",       # all of documentation
+    "PD901",   # "df" name
+    "PLR2004", # magic comparisons
+    "S101",    # assert
+    "SLF",
+]
+"tests/sbml/assets/**" = [
+    "ARG001", # generated rate functions take unused compartment args
+    "E743",   # generated function names mirror SBML ids
+    "INP001",
+    "N802",   # lowercase name
+    "N803",   # lowercase name
+]
+"tmp/*" = [
+    "D",    # all of documentation
+    "I001", # unsorted imports
+    "N",    # all of naming
+    "S101", # assert
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.tomlsort]
+spaces_before_inline_comment = 2
+spaces_indent_inline_array = 2
+trailing_comma_inline_array = true
+
+[tool.uv]
+package = true
+exclude-newer = "3 days"
+
+[[tool.uv.index]]
+explicit = true
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+
+[tool.uv.sources]
+mxlpy = { workspace = true }
+# Plain PyPI torch on Linux resolves to the CUDA build, which unconditionally
+# depends on triton — triton's native module segfaults on GitHub Actions'
+# GPU-less runners the instant torch.optim.Optimizer.__init__ lazily imports
+# it (see the ci workflow fix commit for the full trace). macOS/Windows PyPI
+# wheels don't have this problem, so only Linux is redirected.
+#
+# This only pins resolution for this repo's own dev environment (and thus
+# CI, which runs `uv sync` against this same lockfile) — it is a uv-local
+# override, not published project metadata, so `pip install mxlpy[torch]`
+# (or `uv add mxlpy[torch]` from another project) is unaffected and still
+# resolves plain `torch>=2.5.1` however the installer normally would
+# (the CUDA build on Linux, unless the end user configures otherwise).
+torch = [{ index = "pytorch-cpu", marker = "sys_platform == 'linux'" }]

mxlpy-0.64.0/src/mxlpy/__init__.py

@@ -0,0 +1,262 @@
+# Copyright 2025 Marvin van Aalst, Anna Matuszyńska
+
+"""mxlpy: A Python Package for Metabolic Modeling and Analysis.
+
+This package provides tools for creating, simulating and analyzing metabolic models
+with features including:
+
+Key Features:
+    - Model creation and manipulation
+    - Steady state and time-series simulations
+    - Parameter fitting and optimization
+    - Monte Carlo analysis
+    - Metabolic Control Analysis (MCA)
+    - SBML import/export support
+    - Visualization tools
+
+Core Components:
+    Model: Core class for metabolic model representation
+    Simulator: Handles model simulation and integration
+    DefaultIntegrator: Standard ODE solver implementation
+    LabelMapper: Maps between model components and labels
+    Cache: Performance optimization through result caching
+
+Simulation Features:
+    - Steady state calculations
+    - Time course simulations
+    - Parameter scanning
+    - Surrogate modeling with PyTorch
+
+Analysis Tools:
+    - Parameter fitting to experimental data
+    - Monte Carlo methods for uncertainty analysis
+    - Metabolic Control Analysis
+    - Custom visualization functions
+
+"""
+
+from __future__ import annotations
+
+import contextlib
+import itertools as it
+import logging
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+# dsl imported after fns and model to avoid circular-import ordering issues
+from . import (
+    compare,
+    databases,
+    distributions,
+    dsl,
+    experimental,
+    fit,
+    fns,
+    fuzzy,
+    mc,
+    mca,
+    plot,
+    qa,
+    report,
+    sbml,
+    scan,
+    sensitivity,
+    units,
+)
+from ._kinetic_builder import KineticModelBuilder
+from ._ode_builder import OdeModelBuilder
+from ._steady_state_builder import SteadyStateModelBuilder
+from .composition import compose
+from .dsl import from_dsl
+from .integrators import DefaultIntegrator, Scipy
+from .integrators.abstract import AbstractIntegrator, IntegratorProtocol
+from .label_map import LabelMapper
+from .linear_label_map import LinearLabelMapper
+from .mc import Cache
+from .minimizers.abstract import AbstractMinimizer, MinimizerProtocol
+from .npe.abstract import AbstractEstimator, EstimatorProtocol
+from .serialize import load, save
+from .simulation import Simulation
+from .simulator import Simulator
+from .surrogates.abstract import AbstractSurrogate, SurrogateProtocol
+from .surrogates.abstract_ode import AbstractOdeSurrogate, OdeSurrogateProtocol
+from .symbolic import SymbolicModel, to_symbolic_model
+from .types import (
+    Annotation,
+    Derived,
+    Event,
+    InitialAssignment,
+    OscillationDetected,
+    Parameter,
+    Slider,
+    Variable,
+)
+from .unit_inference import Conflict, UnitInference
+
+with contextlib.suppress(ImportError):
+    from .integrators import Assimulo
+with contextlib.suppress(ImportError):
+    from .integrators import Diffrax
+
+if TYPE_CHECKING:
+    from mxlpy.types import ArrayLike
+
+    from . import nn, npe, surrogates
+else:
+    from lazy_import import lazy_module
+
+    nn = lazy_module("mxlpy.nn")
+    npe = lazy_module("mxlpy.npe")
+    surrogates = lazy_module("mxlpy.surrogates")
+
+# Alias for backward compatability
+Model = KineticModelBuilder
+
+__all__ = [
+    "AbstractEstimator",
+    "AbstractIntegrator",
+    "AbstractMinimizer",
+    "AbstractOdeSurrogate",
+    "AbstractSurrogate",
+    "Annotation",
+    "Assimulo",
+    "Cache",
+    "Conflict",
+    "DefaultIntegrator",
+    "Derived",
+    "Diffrax",
+    "EstimatorProtocol",
+    "Event",
+    "InitialAssignment",
+    "IntegratorProtocol",
+    "KineticModelBuilder",
+    "LabelMapper",
+    "LinearLabelMapper",
+    "MinimizerProtocol",
+    "Model",
+    "OdeModelBuilder",
+    "OdeSurrogateProtocol",
+    "OscillationDetected",
+    "Parameter",
+    "Scipy",
+    "Simulation",
+    "Simulator",
+    "Slider",
+    "SteadyStateModelBuilder",
+    "SurrogateProtocol",
+    "SymbolicModel",
+    "UnitInference",
+    "Variable",
+    "cartesian_product",
+    "compare",
+    "compose",
+    "configure_default_logging",
+    "databases",
+    "distributions",
+    "dsl",
+    "experimental",
+    "fit",
+    "fns",
+    "from_dsl",
+    "fuzzy",
+    "load",
+    "make_protocol",
+    "mc",
+    "mca",
+    "nn",
+    "npe",
+    "plot",
+    "qa",
+    "report",
+    "save",
+    "sbml",
+    "scan",
+    "sensitivity",
+    "surrogates",
+    "symbolic",
+    "to_symbolic_model",
+    "units",
+]
+
+
+def cartesian_product(parameters: dict[str, ArrayLike]) -> pd.DataFrame:
+    """Generate a cartesian product of the parameter values.
+
+    Parameters
+    ----------
+    parameters
+        Dictionary containing parameter names and values.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame containing the cartesian product of the parameter values.
+
+    """
+    return pd.DataFrame(
+        it.product(*parameters.values()),
+        columns=list(parameters),
+    )
+
+
+def make_protocol(steps: list[tuple[float, dict[str, float]]]) -> pd.DataFrame:
+    """Create protocol DataFrame from a dictionary of steps.
+
+    Parameters
+    ----------
+    steps
+        dictionary of steps, where each key is the duration of
+        the step in seconds and the value is a dictionary of all
+        parameter values during that step.
+
+    Examples
+    --------
+        >>> make_protocol([
+        ...     (1, {"k1": 1.0}),
+        ...     (2, {"k1": 2.0}),
+        ...     (3, {"k1": 1.0}),
+        ... ])
+
+        | Timedelta       |   k1 |
+        |:----------------|-----:|
+        | 0 days 00:00:01 |  1.0 |
+        | 0 days 00:00:03 |  2.0 |
+        | 0 days 00:00:06 |  1.0 |
+
+        >>> make_protocol([
+        ...     (1, {"k1": 1.0, "k2": 2.0}),
+        ...     (2, {"k1": 2.0, "k2": 3.0}),
+        ...     (3, {"k1": 1.0, "k2": 2.0}),
+        ... ])
+
+        | Timedelta       |   k1 |   k2 |
+        |:----------------|-----:|-----:|
+        | 0 days 00:00:01 |    1 |    2 |
+        | 0 days 00:00:03 |    2 |    3 |
+        | 0 days 00:00:06 |    1 |    2 |
+
+    """
+    data = {}
+    t0 = pd.Timedelta(0)
+    for step, pars in steps:
+        t0 += pd.Timedelta(seconds=step)
+        data[t0] = pars
+    protocol = pd.DataFrame(data).T
+    protocol.index.name = "Timedelta"
+    return protocol
+
+
+def configure_default_logging(
+    fmt: str = "%(levelname)s:%(name)s:%(message)s",
+    level: logging._Level = logging.DEBUG,
+) -> None:
+    """Create a default logging config."""
+    logger = logging.getLogger("mxlpy")
+    if logger.handlers:
+        return
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter(fmt))
+    logger.addHandler(handler)
+    logger.setLevel(level)