***********************
Consumer-Resource Model
***********************

In this section, we provide background information on the equations used in the mechanistic :class:`~mgrowthctrl.models.crm.model.CRModel`. There exist several variants of consumer-resource models in the literature, see the references below. The consumer–resource model we use is inspired by Niehaus et al. (2019) and builds on Monod kinetics, extending it to multi-species, multi-resource systems.

Assumptions
===========
1.  **Biomass Growth**: Bacterial growth follows Monod kinetics, limited by resource availability.
2.  **Resource Consumption**: Resources are consumed proportional to growth (yield).
3.  **Metabolic Production**: Bacteria secrete byproducts proportional to biomass.
4.  **Well-Mixed**: The system is a chemostat or batch reactor with homogeneous concentrations.

Species Dynamics
================

Let :math:`X_i` be the biomass of species :math:`i` and :math:`S_j` be the concentration of resource :math:`j`.

The specific growth rate :math:`\mu_{ij}` of species :math:`i` on resource :math:`j` is

.. math::

   \mu_{ij}(S_j) = r_{ij} \frac{S_j}{K_{ij} + S_j}\,,

where :math:`r_{ij}` is the maximum growth rate and :math:`K_{ij}` is the half-saturation constant.

The total growth rate of species :math:`i` is the sum over all resources. That is,

.. math::

   \mu_i(\mathbf{S}) = \sum_{j=1}^{m} \mu_{ij}(S_j)\,.

Including the death rate of species :math:`i`, :math:`k_i`, and dilution :math:`D`, yields

.. math::

   \frac{\mathrm{d}X_i}{\mathrm{d}t} = X_i (\mu_i(\mathbf{S}) - k_i - D)= X_i \left( \sum_{j=1}^{m} r_{ij} \mu_{ij}(S_j) - k_i - D \right)\,.

In the :class:`~mgrowthctrl.models.crm.model.CRModel` implementation, the dilution :math:`D` can be either constant or time-dependent.

Resource Dynamics
=================
Resource :math:`j` is affected by three main processes:

1. **Inflow and Outflow**: Described by :math:`D(S_j^{\mathrm{in}} - S_j)`, representing the dilution of the resource due to inflow and outflow.

2. **Resource Consumption**: Proportional to microbial growth, where :math:`a_{ij}` denotes the amount of :math:`S_j` consumed per unit growth of :math:`X_i` (inverse yield).

3. **Byproduct Secretion**: Proportional to biomass, where :math:`b_{ij}` denotes the production rate of :math:`S_j` by :math:`X_i`.

The resulting evolution equation of :math:`S_j` is

.. math::

   \frac{\mathrm{d}S_j}{\mathrm{d}t} = \sum_{i=1}^{n} X_i b_{ij} - \sum_{i=1}^{n} a_{ij} X_i \mu_{ij}(S_j) +  D(S_j^{\mathrm{in}} - S_j)\,.

Example
=======

We construct a simple one-species, one-resource system and initialize the corresponding model parameters.

.. code-block:: python

   from mgrowthctrl.models import CRModel, CRModelParams
   from mgrowthctrl.models.base import ModelNames

   params = CRModelParams.from_shapes(n=1, m=1)
   print(params.r.shape)
   print(params.K_ij.shape)
   print(params.k.shape)

   names = ModelNames(["biomass"], ["substrate"])
   model = CRModel(names=names, params=params)

Next, we specify a minimal set of parameter values for growth, uptake, and death rates.

.. code-block:: python

   model.r[0][0] = 1
   model.a[0][0] = 1
   model.k[0] = 0.1

We can use the :meth:`model.get_params() <mgrowthctrl.models.crm.model.CRModel.get_params>` function to verify that the model has loaded the specified parameters.

We then simulate the system over a given time horizon starting from initial conditions for biomass and substrate.

.. code-block:: python

   import numpy as np

   t_sim = np.linspace(0, 120, 200)

   sim = model.simulate([0.1, 10], t_sim)

Finally, we visualize the resulting biomass and substrate trajectories.

.. code-block:: python

   import matplotlib.pyplot as plt

   plt.figure(figsize=(6, 3.2))
   plt.plot(sim.t, sim.X[0, :], label="biomass")
   plt.plot(sim.t, sim.S[0, :], label="substrate")
   plt.xlabel("time (a.u.)")
   plt.ylabel("concentration (a.u.)")
   plt.legend()
   plt.tight_layout()
   plt.savefig("crm_simple_example.png")
   plt.show()

Here's what the simulation result look like:

.. image:: ../_static/crm_simple_example.png
   :alt: Simple CRM example
   :align: center

API Documentation
=================

.. automodule:: mgrowthctrl.models.crm.model
   :members:
   :member-order: bysource
   :undoc-members:
   :show-inheritance:

References
==========

- Levins, R. (1968). *Evolution in changing environments: some theoretical explorations* (No. 2). Princeton University Press.
- MacArthur, R. (1970). Species packing and competitive equilibrium for many species. *Theoretical Population Biology*, 1(1), 1-11.
- Niehaus, L., Boland, I., Liu, M., Chen, K., Fu, D., Henckel, C., ... & Momeni, B. (2019). Microbial coexistence through chemical-mediated interactions. *Nature Communications*, 10(1), 2052.
- Butler, S., & O’Dwyer, J. P. (2018). Stability criteria for complex microbial communities. *Nature Communications*, 9(1), 2970.