.. _cmp_funcs:

Analytic Compartment Functions
#################################

:numref:`table_cmp_funcs_cl` shows the inbuilt compartment functions that are available in the |derivatives| section using the '_cl' suffix:-

.. list-table:: Compartment Model Functions using '_cl'
    :name: table_cmp_funcs_cl
    :header-rows: 1
    
    * - Name
      - Parameters
      
    * - :ref:`@iv_one_cmp_cl`
      - dose/CL/V
      
    * - :ref:`@dep_one_cmp_cl`
      - dose/KA/CL/V
      
    * - :ref:`@iv_two_cmp_cl`
      - dose/CL/V1/Q/V2
      
    * - :ref:`@dep_two_cmp_cl`
      - dose/KA/CL/V1/Q/V2
      
    * - :ref:`@iv_three_cmp_cl`
      - dose/CL/V1/Q2/V2/Q3/V3
      
    * - :ref:`@dep_three_cmp_cl`
      - dose/KA/CL/V1/Q2/V2/Q3/V3
      
      
The '_cl' suffix means that elimination rates between compartments (K) are generally parameterised as follows:-

.. math::

    K = CL/V

|ie| the ratio of the |clear| and |vol|. 

.. _@iv_one_cmp_cl:

@iv_one_cmp_cl
================

Intra-venous one compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[CEN] = @iv_one_cmp_cl{
            dose: @bolus{amt:c[AMT]}, 
            CL: m[CL], V: m[V]}
            
This analytic model is equivalent to solving **numerically**:-

.. code-block:: pyml

    DERIVATIVES: |
        d[CEN] = @bolus{amt:c[AMT]} - s[CEN]*m[CL]/m[V]

See :ref:`iv_one_cmp_cl` for full example.

.. _@dep_one_cmp_cl:

@dep_one_cmp_cl
================

Depot and one compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[DEP,CEN] = @dep_one_cmp_cl{
            dose: @bolus{amt:c[AMT]}, 
            KA: m[KA], CL: m[CL], V: m[V]}

**Numerical** |ode| equivalent is:-

.. code-block:: pyml

    DERIVATIVES: |
        d[DEP] = @bolus{amt:c[AMT]} - s[DEP]*m[KA]
        d[CEN] = s[DEP]*m[KA] - s[CEN]*m[CL]/m[V]
            
See :ref:`dep_one_cmp_cl` for full example.

.. _@iv_two_cmp_cl:

@iv_two_cmp_cl
================

Intra-venous two compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[CEN,PERI] = @iv_two_cmp_cl{
            dose: @bolus{amt:c[AMT]}, 
            CL: m[CL], V1: m[V1], 
            Q: m[Q], V2: m[V2]}
            
**Numerical** |ode| equivalent is:-

.. code-block:: pyml

    DERIVATIVES: |
        d[CEN] = (
            @bolus{amt:c[AMT]} - s[CEN]*m[CL]/m[V1] 
            - s[CEN]*m[Q]/m[V1] + s[PERI]*m[Q]/m[V2]
        )
        d[PERI] = s[CEN]*m[Q]/m[V1] - s[PERI]*m[Q]/m[V2]

See :ref:`iv_two_cmp_cl` for full example.

  
.. _@dep_two_cmp_cl:

@dep_two_cmp_cl
==================

Depot and two compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[DEP,CEN,PERI] = @dep_two_cmp_cl{
            dose: @bolus{amt:c[AMT]}, 
            KA: m[KA], 
            CL: m[CL], V1: m[V1], 
            Q: m[Q], V2: m[V2]}

**Numerical** |ode| equivalent is:-

.. code-block:: pyml

    DERIVATIVES: |
        d[DEP] = @bolus{amt:c[AMT]} - s[DEP]*m[KA]
        d[CEN] = (
            s[DEP]*m[KA] - s[CEN]*m[CL]/m[V1] 
            - s[CEN]*m[Q]/m[V1] + s[PERI]*m[Q]/m[V2]
        )
        d[PERI] = s[CEN]*m[Q]/m[V1] - s[PERI]*m[Q]/m[V2]
            
See :ref:`dep_two_cmp_cl` for full example.


.. _@iv_three_cmp_cl:

@iv_three_cmp_cl
==================

Intra-venous three compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[CEN,PERI1,PERI2] = @iv_three_cmp_cl{
            dose: @bolus{amt:c[AMT]}, 
            CL: m[CL], V1: m[V1], 
            Q2: m[Q2], V2: m[V2], 
            Q3: m[Q3], V3: m[V3]
        }

**Numerical** |ode| equivalent is:-

.. code-block:: pyml

    DERIVATIVES: |
        d[CEN] = (
            @bolus{amt:c[AMT]}  - s[CEN]*m[CL]/m[V1] 
            - s[CEN]*m[Q2]/m[V1] + s[PERI1]*m[Q2]/m[V2]
            - s[CEN]*m[Q3]/m[V1] + s[PERI2]*m[Q3]/m[V3]
        )
        d[PERI1] = s[CEN]*m[Q2]/m[V1] - s[PERI1]*m[Q2]/m[V2]
        d[PERI2] = s[CEN]*m[Q3]/m[V1] - s[PERI2]*m[Q3]/m[V3]
        
See :ref:`iv_three_cmp_cl` for full example.


.. _@dep_three_cmp_cl:

@dep_three_cmp_cl
==================

Depot and three compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[DEP,CEN,PERI1,PERI2] = @dep_three_cmp_cl{
            dose: @bolus{amt:c[AMT]}, 
            KA: m[KA], 
            CL: m[CL], V1: m[V1], 
            Q2: m[Q2], V2: m[V2], 
            Q3: m[Q3], V3: m[V3]
        }

**Numerical** |ode| equivalent is:-
        
.. code-block:: pyml

    DERIVATIVES: |
        d[DEP] = @bolus{amt:c[AMT]} - s[DEP]*m[KA]
        d[CEN] = (
            s[DEP]*m[KA]  - s[CEN]*m[CL]/m[V1] 
            - s[CEN]*m[Q2]/m[V1] + s[PERI1]*m[Q2]/m[V2]
            - s[CEN]*m[Q3]/m[V1] + s[PERI2]*m[Q3]/m[V3]
        )
        d[PERI1] = s[CEN]*m[Q2]/m[V1] - s[PERI1]*m[Q2]/m[V2]
        d[PERI2] = s[CEN]*m[Q3]/m[V1] - s[PERI2]*m[Q3]/m[V3]
        
See :ref:`dep_three_cmp_cl` for full example.

It is also possible to parametrise the rates directly using the '_k' suffix, see :numref:`table_cmp_funcs_k`:-

.. _table_cmp_funcs_k:

.. list-table:: Compartment Model Functions using '_k'
    :header-rows: 1
    
    * - Name
      - Parameters
      
    * - :ref:`@iv_one_cmp_k`
      - dose/KE
     
    * - :ref:`@dep_one_cmp_k`
      - dose/KA/KE
        
    * - :ref:`@iv_two_cmp_k`
      - dose/KE/K12/K21
      
    * - :ref:`@dep_two_cmp_k`
      - dose/KA/KE/K12/K21
      
    * - :ref:`@iv_three_cmp_k`
      - dose/KE/K12/K21/K13/K31
      
    * - :ref:`@dep_three_cmp_cl`
      - dose/KA/KE/K12/K21/K13/K31
      
.. _@iv_one_cmp_k:

@iv_one_cmp_k
==================

Intra-venous one compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[CEN] = @iv_one_cmp_k{
            dose: @bolus{amt:c[AMT]}, 
            KE: m[KE]}

**Numerical** |ode| equivalent is:-

.. code-block:: pyml

    DERIVATIVES: |
        d[CEN] = @bolus{amt:c[AMT]} - s[CEN]*m[KE]
            
.. _@dep_one_cmp_k:

@dep_one_cmp_k
==================

Depot and one compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[DEP,CEN] = @dep_one_cmp_k{
            dose: @bolus{amt:c[AMT]}, 
            KA: m[KA], KE: m[KE]}

**Numerical** |ode| equivalent is:-

.. code-block:: pyml
            
    DERIVATIVES: |
        d[DEP] = @bolus{amt:c[AMT]} - s[DEP]*m[KA]
        d[CEN] = s[DEP]*m[KA] - s[CEN]*m[KE]
            
.. _@iv_two_cmp_k:

@iv_two_cmp_k
==================

Intra-venous two compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[CEN,PERI] = @iv_two_cmp_k{
            dose: @bolus{amt:c[AMT]}, 
            KE: m[KE], K12: m[K12], K21: m[K21]}

**Numerical** |ode| equivalent is:-

.. code-block:: pyml

    DERIVATIVES: |
        d[CEN] = (
            @bolus{amt:c[AMT]} - s[CEN]*m[KE]
            - s[CEN]*m[K12] + s[PERI]*m[K21]
        )
        d[PERI] = s[CEN]*m[K12] - s[PERI]*m[K21]
        
        
.. _@dep_two_cmp_k:

@dep_two_cmp_k
==================

Depot and two compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[DEP,CEN,PERI] = @dep_two_cmp_k{
            dose: @bolus{amt:c[AMT]}, 
            KA: m[KA], KE: m[KE], 
            K12: m[K12], K21: m[K21]}

**Numerical** |ode| equivalent is:-

.. code-block:: pyml

    DERIVATIVES: |
        d[DEP] = @bolus{amt:c[AMT]} - s[DEP]*m[KA]
        d[CEN] = (
            s[DEP]*m[KA] - s[CEN]*m[KE]
            - s[CEN]*m[K12] + s[PERI]*m[K21]
        )
        d[PERI] = s[CEN]*m[K12] - s[PERI]*m[K21]
            
.. _@iv_three_cmp_k:

@iv_three_cmp_k
==================

Intra-venous three compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[CEN,PERI1,PERI2] = @iv_three_cmp_k{
            dose: @bolus{amt:c[AMT]}, 
            KE: m[KE], 
            K12: m[K12], K21: m[K21], 
            K13: m[K13], K31: m[K31]}

**Numerical** |ode| equivalent is:-

.. code-block:: pyml

    DERIVATIVES: |
        d[CEN] = (
            @bolus{amt:c[AMT]} - s[CEN]*m[KE]
            - s[CEN]*m[K12] + s[PERI1]*m[K21]
            - s[CEN]*m[K13] + s[PERI2]*m[K31]
        )
        d[PERI1] = s[CEN]*m[K12] - s[PERI1]*m[K21]
        d[PERI2] = s[CEN]*m[K13] - s[PERI2]*m[K31]
            
.. _@dep_three_cmp_k:

@dep_three_cmp_k
==================

Depot and three compartment model:-

.. code-block:: pyml

    DERIVATIVES: |
        s[DEP,CEN,PERI1,PERI2] = @dep_three_cmp_k{
            dose: @bolus{amt:c[AMT]}, 
            KA: m[KA], KE: m[KE], 
            K12: m[K12], K21: m[K21], 
            K13: m[K13], K31: m[K31]}

**Numerical** |ode| equivalent is:-

.. code-block:: pyml

    DERIVATIVES: |
        d[DEP] = @bolus{amt:c[AMT]} - s[DEP]*m[KA]
        d[CEN] = (
            s[DEP]*m[KA] - s[CEN]*m[KE]
            - s[CEN]*m[K12] + s[PERI1]*m[K21]
            - s[CEN]*m[K13] + s[PERI2]*m[K31]
        )
        d[PERI1] = s[CEN]*m[K12] - s[PERI1]*m[K21]
        d[PERI2] = s[CEN]*m[K13] - s[PERI2]*m[K31]
