.. symbolic-compartmental-model documentation master file, created by
   sphinx-quickstart on Wed Apr  2 18:16:43 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to symbolic-compartmental-model's documentation!
========================================================

For installation instructions (for ``pip``, ``docker``, or the command-line interface), please see :ref:`SCM Installation Guidelines`.

Overview
--------
Symbolic Compartmental Model is a python package for constructing, simulating, and fitting
compartmental models. It is based on the symbolic calculations package ``sympy`` but can
also perform numerical calculations.

Current features
----------------

* Defining a CM based on the contributed turnovers (:math:`\mathbf{M}`-matrix) and observed pool sizes
* Optionally include symbolic parameters and set their bounds for later fitting
* Several fitting functions, including single/multiple pools and mass balance constraints (optional)
* Both numerical and symbolic outputs for dynamic parameters: age, residence time, decay rate, etc.
* Plotting of simulated data


Getting started
---------------

* For **installing** the package in your current python environment, you can simply ``pip install symbolic-compartmental-model`` or use one of the other options listed in :ref:`Software`.
* For all **newcomers** using the package for the first time, we recommend reading the :ref:`Introduction to Dynamic Labeling Analysis`.
* When you are ready to **start coding**, you can check out the examples below or our didactic :ref:`Coding examples` and :ref:`API Reference` pages.
* The **source code** can be found on `GitLab <https://gitlab.com/elad.noor/symbolic-compartmental-model/>`__.


Quick examples
--------------

**Basic Model Creation:**

.. code-block:: python

   from symbolic_compartmental_model import SymbolicCompartmentalModel

   # Create a 2-state model
   cm = SymbolicCompartmentalModel(n_states=2)
   cm.contributed_turnovers = [[-0.5, 0], [1.0, -1.0]]
   cm.observed_pool_weights = [0.3, 0.7]

   # Simulate labeling curve
   import numpy as np
   t = np.linspace(0, 5, 100)
   f_values = cm.f()(t)


**Parameter Fitting:**

.. code-block:: python

   # Add parameters and fit to data
   k1 = cm.add_parameter(symbol="k1", lb=0.1, ub=10.0)
   k2 = cm.add_parameter(symbol="k2", lb=0.1, ub=10.0)
   cm.contributed_turnovers = [[-k1, 0], [k2, -k2]]

   # Experimental data
   t_data = [1, 2, 3, 4]
   y_data = [0.7, 0.4, 0.2, 0.1]

   # Fit model
   results = cm.fit(t_data, y_data)
   print(f"Best fit: k1={results.popt[0]:.3f}, k2={results.popt[1]:.3f}")


**Symbolic Analysis:**

.. code-block:: python

   # Get symbolic expressions
   mean_age_expr = cm.as_symbolic("mean_age")
   residence_time_expr = cm.as_symbolic("mean_residence_time") 

   # Plot age distribution
   cm.plot("age_pdf", x=[2.0, 1.0])  # With parameters k1=2, k2=1


.. toctree::
   :hidden:
   :numbered:
   :maxdepth: 2
   :caption: Contents:

   introduction
   notebooks
   software
   api



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`