.. _states:

STATES
#######

An optional :term:`verbatim` section that defines initial |sx| variables for the |derivatives| block. The |ode| model in |popy| is typically a :term:`initial value problem`. The |states| section defines the **initial values**.

Note the |states| section is optional. If it is not provided, then by default all |sx| variables are initialised to zero. In |pk| problems this is often sufficient, but a |states| section is often required for |pd| models.

The |states| section takes as input the previously defined |mx| and |cx| variables and computes the initial |sx| variables. The |states| function is run on the first row of each individual and for every **reset** row in the |data_file|. The |states| section is available in the following scripts:-

* :ref:`tut_script`
* :ref:`gen_script`
* :ref:`fit_script`
* :ref:`sim_script`
* :ref:`mtut_script`
* :ref:`mgen_script`
* :ref:`mfit_script`
* :ref:`msim_script`

|ie| Any script that contains a |derivatives| |ode| model.

.. _example_states_pk:

Example STATES for PK Model
=========================================

In :ref:`builtin_fit_example`, a null states section is used:-

.. code-block:: pyml

    STATES: |
    
This is equivalent to just removing the |states| section altogether. It is also equivalent to writing this:-

.. code-block:: pyml

    STATES: |
        s[DEPOT] = 0.0
        s[CENTRAL] = 0.0
        s[PERI] = 0.0
    
The form of the |states| section is very dependent on the |derivatives| section that it is initialising. The |sx| variables that  are defined in |states| **must** exist in the |derivatives| section.
    
.. literalinclude:: 
    /_autogen/quick_start/builtin_fit_example/fit_sections/DERIVATIVES.pyml
    :language: pyml
    
Setting all amounts to zero in the |pk| compartments is fairly common. As before any dose is administered no drug is expected to be present in the body.

The steady state is therefore zero. The amounts in each compartment only become positive after a dose is administered. As the drug is excreted from the body the amount of drug in each compartment converges back to zero.

Note a **reset** row in the |data_file| short cuts the wash out process by removing all of the drug from the body, by calling the null |states| function above.

.. _example_states_pd:

Example STATES for PD Model
====================================

See :ref:`sum_link_direct_pd_tut` for example :ref:`tut_script`, using the following |states| and |derivatives| sections for a |pd| model:-

.. literalinclude:: 
    /_autogen/indiv_examples/pd_models/direct_pd/fit_sections/STATES.pyml
    :language: pyml
    
.. literalinclude:: 
    /_autogen/indiv_examples/pd_models/direct_pd/fit_sections/DERIVATIVES.pyml
    :language: pyml

.. comment
    .. code-block:: pyml

        STATES: |
            s[CENTRAL] = 0.0
            s[MARKER] = m[BASE]
        DERIVATIVES: |
            d[CENTRAL] = @bolus{amt:c[AMT]} - s[CENTRAL]*c[CL]/c[V]
            d[MARKER] = m[BASE]*m[KOUT] - (1+s[CENTRAL]/c[V])*m[KOUT]*s[MARKER]
   
In this example the :pyml:`s[MARKER]` initial value is set to :pyml:`m[BASE]`. This is in order to make sure that the 'MARKER' |pd| compartment is at equilibrium, when the 'CENTRAL' |pk| compartment is zero.

You can usually deduce the equilibrium conditions for a |pd| compartment by setting the |dx| variables to zero and solving for |sx|, with the |pk| compartments set to zero.

For example in this case, setting :pyml:`d[CENTRAL]` to zero:-

.. code-block:: pyml

    0.0 = -s[CENTRAL]*c[CL]/c[V]
    
implies:-

    s[CENTRAL] = 0.0
       
Then setting :pyml:`d[MARKER]` to zero:-

.. code-block:: pyml

    0.0 = m[BASE]*m[KOUT] - (1+0.0)*m[KOUT]*s[MARKER]

implies:-

.. code-block:: pyml

    s[MARKER] = m[BASE]
    
These **equilibrium** conditions ensures that the amounts in 'CENTRAL' and 'MARKER' are fixed until the system is disrupted by a drug dose being administered. As the drug is washed out of the system, the system should smoothly return back to equilibrium. 

Alternatively if a **reset** row is encountered in the |data_file| then the system is jolted back to the equilibrium by running the |states| function.

The non-zero equilibrium value of :pyml:`s[MARKER]` is meant to model the endogenous amount of a substance within the body. |ie| a substance that is naturally present without drug intervention. This biological fact makes |pd| models inherently more complex than |pk| models and they usually require a more complex |states| section.
    
.. _rules_states:
    
Rules for STATES section
=======================================

Like all :term:`verbatim` sections the |states| section of the config file accepts free form |python| :term:`pseudocode`, but there are some rules regarding which variables are allowed in a |states| section as follows:- 

* **Only** |sx| and local variables can be defined on the |lhs| 
* |sx| variables defined on the |lhs| **must** also exist in the |derivatives| section
* |sx| variables present in |derivatives| but |not| in |states| are initialised to zero.
* |cx| and |mx| are only allowed on the |rhs| of expressions
* |cx| must be defined in the |data_file| or created in the |preprocess| section in a :ref:`fit_script` 
* |cx| must be defined within the |level_params| in a :ref:`gen_script` or :ref:`tut_script`.
* |mx| must be defined in the |model_params|

You can |not| use |dx|, |px|, |rx|, |fx| or |tx| |etc| variables at all in this section. 

Like all :term:`verbatim` sections it is possible to introduce syntax errors by writing malformed |python|. Coding errors will be reported when |popy| attempts to compile or run the |states| function as a temporary .py file.



