Metadata-Version: 2.4
Name: nskinetics
Version: 0.3.0
Summary: Simulation of Non-Steady state enzyme Kinetics and inhibitory phenomena
Home-page: https://github.com/sarangbhagwat/nskinetics
Download-URL: https://github.com/sarangbhagwat/nskinetics.git
Author: Sarang S. Bhagwat
Author-email: sarangbhagwat.developer@gmail.com
License: MIT
Keywords: reaction kinetics,biocatalysis,biomanufacturing,bioprocess engineering,mass and energy balance,process simulation,biorefinery,biofuel,bioproducts
Platform: Windows
Platform: Mac
Platform: Linux
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: BSD
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Education
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: IPython>=7.9.0
Requires-Dist: numpy<2.0.0,>=1.26.4
Requires-Dist: numba<1.0.0,>=0.60.0
Requires-Dist: scipy<2.0.0,>=1.13.1
Requires-Dist: matplotlib<4.0.0,>=3.5.2
Requires-Dist: xlsxwriter<4.0.0,>=3.2.5
Requires-Dist: scikit-learn
Requires-Dist: pandas<3.0.0,>=2.2.2
Requires-Dist: tellurium
Requires-Dist: biosteam==2.47.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

.. image:: docs/source/_static/images/logo/logo_nskinetics_light_white-circle.png
  :width: 250

===============================================================
The (Non-)Steady state Kinetics simulation package (NSKinetics)
===============================================================

.. image:: http://img.shields.io/pypi/v/nskinetics.svg?style=flat
   :target: https://pypi.python.org/pypi/nskinetics
   :alt: Version_status
.. image:: http://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat
   :target: https://nskinetics.readthedocs.io/en/latest/
   :alt: Documentation
.. image:: http://img.shields.io/badge/license-MIT-blue.svg?style=flat
   :target: https://github.com/sarangbhagwat/nskinetics/blob/main/LICENSE
   :alt: license
.. image:: https://img.shields.io/pypi/pyversions/nskinetics.svg
   :target: https://pypi.python.org/pypi/nskinetics
   :alt: Supported_versions
.. image:: https://coveralls.io/repos/github/sarangbhagwat/nskinetics/badge.svg?cachebuster=202507072
   :target: https://coveralls.io/github/sarangbhagwat/nskinetics?branch=main

**Contents**

.. contents::
   :local:

What is NSKinetics?
-------------------

NSKinetics is a fast, flexible, and convenient package in Python for simulating steady- and non-steady-state reaction kinetics — especially enzyme kinetics and inhibitory phenomena — and connecting them to techno-economic analysis (TEA) and life-cycle assessment (LCA) under uncertainty. Kinetic models are declared as SBML — most easily authored as `Antimony <https://tellurium.readthedocs.io/en/latest/antimony.html>`__ text, or imported from an existing SBML file — and wrapped in a ``TelluriumReactionSystem``, which adds unit-aware value access and a Python event API on top of a Tellurium RoadRunner engine that performs the actual ODE integration. ``Event`` covers a single trigger/assignment pair (a parameter switch, a control action); the higher-level ``FeedSpike`` builds on it for fed-batch feeding, topping a species back up to a target concentration whenever it drops below a threshold. The same reaction system can then drive a `BioSTEAM <https://biosteam.readthedocs.io/en/latest/>`__ process unit through the ``NSKFermentation`` bridge, coupling kinetics directly to TEA.

Installation
------------

Get the latest version of NSKinetics from `PyPI <https://pypi.org/project/nskinetics/>`__. If you have an installation of Python with pip, simply install it with:

.. code-block:: bash

    $ pip install nskinetics

To get the git version, run:

.. code-block:: bash

    $ git clone git://github.com/sarangbhagwat/nskinetics

For help on common installation issues, please visit the `documentation <https://nskinetics.readthedocs.io/en/latest/>`__.

Documentation
-------------

NSKinetic's `full documentation <https://nskinetics.readthedocs.io/en/latest/>`__ includes a staged tutorial, starting from a minimal model and building up to a full process/TEA-coupled fed-batch fermentation. Here are three stages to get started:

**Example 1: Build and simulate a minimal model**

Kinetic models are declared as SBML; the easiest way to author one by hand is Antimony, a compact text syntax that Tellurium compiles to SBML. Here, species ``S`` decays into ``P`` inside a compartment ``env``, with mass-action rate constant ``k``. Wrapping the resulting RoadRunner object in a ``TelluriumReactionSystem`` adds unit-aware value access; simulation itself always runs through the underlying RoadRunner object:

.. code-block:: python

    import numpy as np
    import tellurium as te
    import nskinetics as nsk

    model = """
    model demo()
      compartment env; species S in env, P in env;
      S = 10; P = 0; env = 1; k = 0.3;
      J: S => P; k*S*env;
    end
    """
    r = te.loadAntimonyModel(model)
    trs = nsk.TelluriumReactionSystem(r, units={'time': 'h', 'conc': 'g/L'})
    trs.validate_units()
    trs.reset()

    result = np.array(r.simulate(0, 10, 101, ['time', 'S', 'P']))
    print('t=10:', result[-1])

This prints, in the ``HP_2024`` environment:

.. code-block:: text

    t=10: [10.     0.498  9.502]

``S`` has decayed from its initial concentration of 10 g/L to about 0.498 g/L by ``t=10`` h, while ``P`` has risen to about 9.502 g/L — the stoichiometric (1:1) conversion of ``S`` into ``P`` under first-order decay with ``k=0.3``.

**Example 2: Add an event**

Real kinetic models often need to change mid-run — a parameter switches at a fixed time, a control action fires when a species crosses a threshold. ``Event`` mirrors a native SBML event: a trigger expression (``when``) paired with one or more variable assignments (``do``) that fire once the trigger becomes true. Here, species ``s`` decays at rate ``k`` while a ``flag`` parameter is nonzero, and an event flips ``flag`` off at ``time >= 5``:

.. code-block:: python

    import numpy as np, tellurium as te, nskinetics as nsk

    model = """
    model decay()
      species s; s = 100; k = 1; flag = 1;
      s' = -k*flag*s;
    end
    """
    r = te.loadAntimonyModel(model)
    trs = nsk.TelluriumReactionSystem(r, units={'time': 'h', 'conc': 'g/L'})
    trs.add_event(nsk.Event(when='time >= 5', do={'flag': '0'}, name='stop_decay'))
    trs.compile_events()   # regenerates the model; set ICs AFTER this
    trs.reset()

    res = np.array(r.simulate(0, 10, 11, ['time', 's', 'flag']))
    print(res)

This prints, in the ``HP_2024`` environment:

.. code-block:: text

    [[  0.    100.      1.   ]
     [  1.     36.788   1.   ]
     [  2.     13.534   1.   ]
     [  3.      4.979   1.   ]
     [  4.      1.832   1.   ]
     [  5.      0.674   0.   ]
     [  6.      0.674   0.   ]
     [  7.      0.674   0.   ]
     [  8.      0.674   0.   ]
     [  9.      0.674   0.   ]
     [ 10.      0.674   0.   ]]

``flag`` is ``1`` for every row before ``t=5`` and ``0`` from ``t=5`` onward, exactly matching the event's trigger; ``s`` decays exponentially while ``flag=1`` drives the rate law, then freezes at ``0.674`` for the rest of the run once the event zeroes ``flag``.

**Example 3: Fed-batch feeding with FeedSpike**

``FeedSpike`` is a higher-level convenience built on ``Event``: it watches one species and, whenever it drops to a trigger condition, adds enough feed (at a known feed concentration) to bring it back up to a target concentration — while growing the working volume by the amount of feed added. Here, ``s_glu`` starts at 100 g/L and decays at ``k=1``; it would cross the ``threshold`` of 10 g/L repeatedly over 40 h, but ``max_count=2`` (``n_max``) caps it at two spikes:

.. code-block:: python

    import numpy as np, tellurium as te, nskinetics as nsk

    model = """
    model spiker()
      compartment env; species s_glu in env;
      s_glu = 100; env = 1; k = 1;
      threshold = 10; target = 100; feed_conc = 600;
      n_spk = 0; n_max = 2; last_vol = 0; tot_vol = 0; dly = 0;
      n_spk has dimensionless; n_max has dimensionless;
      s_glu' = -k*s_glu;
    end
    """
    r = te.loadAntimonyModel(model)
    trs = nsk.TelluriumReactionSystem(r, units={'time': 'h', 'conc': 'g/L'})
    fs = nsk.FeedSpike(species='s_glu', when='s_glu <= threshold',
                       target='target', feed_conc='feed_conc', volume_var='env',
                       max_count='n_max', count_var='n_spk',
                       last_vol_var='last_vol', tot_vol_var='tot_vol',
                       delay='dly', priority=5, name='spk')
    for e in fs.expand():
        trs.add_event(e)
    trs.compile_events()
    trs.reset()
    res = np.array(r.simulate(0, 40, 401, ['time', 's_glu', 'n_spk']))
    print('max spikes:', res[:, 2].max(), 'final s_glu:', res[-1, 1])

This prints, in the ``HP_2024`` environment:

.. code-block:: text

    max spikes: 2.0 final s_glu: -6.19487843009339e-12

``max spikes: 2.0`` confirms the cap was reached — exactly two spikes fired. After the second spike, no further trigger fires, so ``s_glu`` decays freely for the rest of the 40 h window, reaching essentially zero (``-6.19e-12`` g/L is floating-point noise).

See the `full tutorial <https://nskinetics.readthedocs.io/en/latest/tutorial/index.html>`__ for the rest of the workflow, including loading real, shipped SBML models and coupling a reaction system to a BioSTEAM process unit for TEA.


Bug reports
-----------

To report bugs, please use NSKinetics's Bug Tracker at:

    https://github.com/sarangbhagwat/nskinetics

Contributing
------------
For guidelines on how to contribute, visit:

    [link to be added]


License information
-------------------

See ``LICENSE.txt`` for information on the terms & conditions for usage
of this software, and a DISCLAIMER OF ALL WARRANTIES.

Although not required by the NSKinetics license, if it is convenient for you,
please cite NSKinetics if used in your work. Please also consider contributing
any changes you make back, and benefit the community.


About the authors
-----------------

NSKinetics was created and developed by `Sarang S. Bhagwat <https://github.com/sarangbhagwat>`__ as part of the `Scown Group <https://cscown.com/>`__ and the `Energy & Biosciences Institute <https://energybiosciencesinstitute.org/>`__ at the `University of California, Berkeley (UC Berkeley) <https://www.berkeley.edu/>`__. 


References
----------
.. [1] ` To be added <link to be added>`__.


