mgrowthctrl 0.1.0

mgrowthctrl is a software package for modeling, visualization, and control of microbiome growth dynamics. It provides tools to simulate microbial community dynamics, fit predictive models to experimental data, and steer community composition using control and optimization methods.

mgrowthctrl

A Python package for parameter inference, mechanistic microbiome modeling, and control, based on a consumer–resource model (CRM).

Detailed documentation is available at Documentation.

Key features of mgrowthctrl include:

• An API for defining and simulating ODE-based microbiome dynamics.
• A data loader that allows users to retrieve data from mGrowthDB.
• A parameter estimation backend offering both least-squares and Markov Chain Monte Carlo (MCMC) optimization.
• Built-in visualization utilities for evaluating trajectories and analyzing posteriors.
• A controller framework based on neural ODEs.
• A modular architecture designed to facilitate the extension and integration of custom models, controllers, and data processing workflows.

Features

Models

• An implementation of a CRM (CRModel).
• Scalable design supporting both single-species and multi-species systems.
• A unified engine (BaseODEModel) with NumPy and PyTorch backends.
• Extensible base classes enabling straightforward implementation of custom ODE models.

Controllers

• BaseController provides an abstract interface with simulate and fit methods.
• OpenLoopNeuralController implements time-dependent control functions.
• ClosedLoopNeuralController implements state-dependent control functions.

Fitting Backend

• Least-squares parameter optimization (crm_fit_mechanistic).
• Bayesian parameter inference through MCMC sampling (crm_fit_mcmc).

Plotting

• Tools for visualizing coupled metabolite and species population dynamics.
• Plots of empirical data, spline interpolations, and simulated trajectories.
• Integration of MCMC outputs to show credible intervals.

Code Structure

src/mgrowthctrl/
│
├── backends/
│   ├── array.py        # Array backend interfaces for NumPy and PyTorch
│   └── __init__.py
│
├── controllers/
│   ├── base.py         # BaseController interface with simulate and fit methods
│   ├── closed_loop.py  # ClosedLoopNeuralController
│   └── open_loop.py    # OpenLoopNeuralController
│
├── models/
│   ├── base.py         # ODE base class (uses dependency injection)
│   └── crm/
│       ├── fit.py      # LSQ + MCMC fitting engine
│       ├── model.py    # Mechanistic CRM using BaseODEModel
│       └── utils.py    # Shared utilities
│
├── utils/
│   ├── data.py         # Data loading functions with a public DataLoader-style API
│   ├── plot.py         # Plotting utilities
│   ├── save.py         # Saving / loading utilities
│   └── __init__.py
│
└── __init__.py