Metadata-Version: 2.4
Name: nskinetics
Version: 0.5.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 — including microbial fermentation and enzyme kinetics — 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 ``KineticModel``, 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 kinetic model can then drive a `BioSTEAM <https://biosteam.readthedocs.io/en/latest/>`__ process unit through the ``NSKBatchReactor`` 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. The quickstart example below runs that full picture end to end.

One factory call builds a complete, industrially configured process around a real kinetic model: ``nskinetics.processes.create_sugar_prep_and_fermentation_system`` assembles the sugar-solution preparation and fed-batch fermentation section of an actual biorefinery model — a splitter feeding parallel initial-feed and spike-feed conditioning trains (multi-effect evaporator, pumps, dilution-water mixer, heat exchanger), a ``FermentationSaccharomycesEthanolIsobutanol`` fermentor driven by the shipped *S. cerevisiae* kinetic model, and a compressed-air aeration loop. This example runs it end to end: build, simulate, change the fed-batch strategy, and inspect the reactor. Total simulation time is a few seconds once the imports are loaded; every number and figure below is the output of the code shown.

**Step 1: Build the process**

The factory needs only a chemical set — ``set_thermo=True`` activates its
own, shipped set. One call builds the whole section on biosteam's main
flowsheet, with its two inlets (the saccharified sugar slurry and the seed
culture) created with default compositions matching the isobutanol
biorefinery's baseline simulation, ready to use as-is or overwrite:

.. code-block:: python

   import biosteam as bst
   import nskinetics as nsk

   sugar_ferm_sys = nsk.processes.create_sugar_prep_and_fermentation_system(
       set_thermo=True)
   f = bst.main_flowsheet
   sugar_ferm_sys.diagram()

.. figure:: docs/source/_static/images/examples/tutorial_01_quickstart_flowsheet.png
   :width: 700

   The factory's flowsheet: ``S301`` splits the slurry between the
   initial-feed train (``F301`` → ``M301`` → ``H301``) and the spike-feed
   train (``F302`` → ``M302`` → ``H302``), both feeding the ``V406``
   fermentor; ``K330``/``V330`` supply compressed air for aeration.

**Step 2: Simulate**

One call runs everything. The factory builds a fed-batch strategy — a
``FedBatchStrategySpecification`` wired to its own units, attached to the
fermentor as ``V406.fbs_spec`` — and ``sugar_ferm_sys.simulate()`` begins by
imposing it: the initial feed is conditioned to the spec's ``target_conc``
(220 g/L glucose), a fed-batch spike fires whenever the reactor's glucose
falls to ``threshold_conc`` (210 g/L), each spike draws from a concentrated
``spike_conc`` (600 g/L) feed, and the evaporators, dilution water, and
splitter are solved so the physical streams actually deliver those
concentrations. Then the flowsheet runs: ``V406`` hands its mixed feed to
the kinetic model, integrates the fed-batch fermentation over the full
``tau_max`` = 72 h window — spikes, aeration switching, and a spike-count
retry included — picks the harvest time ``tau`` where ethanol peaks,
converts that one time point into its effluent stream, and finishes by
re-simulating the aeration loop at the freshly computed air demand. Plotting
the reactor's kinetic trajectory shows the fermentation behind the process
result (the ``simulate()`` call emits a handful of biosteam
``CostWarning``/``DesignWarning`` messages — transient solver states outside
cost-correlation validity ranges — that are benign here):

.. code-block:: python

   sugar_ferm_sys.simulate()
   f.V406.plot_simulation_results()

.. figure:: docs/source/_static/images/examples/tutorial_01_quickstart_kinetics.png
   :width: 500

   The full kinetic trajectory. Early on, 9 spikes hold glucose
   (``[s_glu]``) in the 210–220 g/L band while aerobic growth builds cells
   (``[x]``); aeration ends at ~12 h, when the cell density passes its
   stage-1 cutoff. Glucose is then drawn down to ~0 as ethanol
   (``[s_EtOH]``) climbs to ~139.5 g/L, and the dashed ``fermentation end``
   line marks the selected harvest time ``tau`` ≈ 63.7 h.

**Step 3: Change the fed-batch strategy**

The strategy imposed above is held by the specification the factory attached
to the fermentor, ``f.V406.fbs_spec`` (alias
``fed_batch_strategy_specification``). Calling its ``load_specifications()``
with new values re-imposes the strategy immediately — writing the
concentrations into the kinetic model and re-solving the evaporators,
dilution water, and splitter so the physical streams deliver them — and the
values persist on the spec, so every later ``simulate()`` keeps the new
strategy. Dropping the initial-feed target to 200 g/L and letting glucose
fall to 180 g/L between spikes:

.. code-block:: python

   f.V406.fbs_spec.load_specifications(target_conc=200, threshold_conc=180,
                                       spike_conc=600)
   sugar_ferm_sys.simulate()
   f.V406.plot_simulation_results()

.. figure:: docs/source/_static/images/examples/tutorial_01_quickstart_kinetics_retuned.png
   :width: 500

   The same fermentation under the retuned strategy. The batch now starts at
   200 g/L glucose (the re-solved initial-feed evaporator delivers
   ~200.1 g/L), and the wider 180–200 g/L band means fewer, larger spikes —
   5 instead of 9 — so less total glucose is fed: it is exhausted by ~45 h,
   ethanol peaks earlier and slightly lower (~133.5 g/L), and the selected
   harvest time drops to ``tau`` ≈ 47.1 h.

**Step 4: Inspect the reactor**

The same simulation drives a real process unit. ``show()`` lists the
fermentor's inlet and outlet streams — the effluent carries the kinetic
result at the harvest time, mapped onto biosteam chemicals — and
``results()`` is biosteam's standard design-and-cost table, sized and costed
from the kinetic ``tau``. Both reflect the retuned strategy simulated above:

.. code-block:: python

   f.V406.show(N=100)
   print(f.V406.results())

.. code-block:: text

   FermentationSaccharomycesEthanolIsobutanol: V406
   ins...
   [0] glucose_initial_feed  from  HXutility-H301
       phase: 'l', T: 305.15 K, P: 101325 Pa
       flow (kmol/hr): Water    5.83e+03
                       Glucose  117
                       NH3      6.71
   [1] seed
       phase: 'l', T: 298.15 K, P: 101325 Pa
       flow (kmol/hr): Water  0.633
                       Yeast  0.0243
   [2] glucose_spike_feed  from  HXutility-H302
       phase: 'l', T: 305.15 K, P: 101325 Pa
       flow (kmol/hr): Water    1.61e+03
                       Glucose  97.2
                       NH3      5.56
   [3] s5  from  IsenthalpicValve-V330
       phase: 'g', T: 305.15 K, P: 101325 Pa
       flow (kmol/hr): O2  11.3
                       N2  42.4
   outs...
   [0] fermentation_vent
       phase: 'g', T: 305.15 K, P: 101325 Pa
       flow (kmol/hr): Water       17.7
                       AceticAcid  0.0093
                       CO2         419
                       O2          5.64
                       N2          42.4
   [1] fermentation_effluent
       phase: 'l', T: 305.15 K, P: 101325 Pa
       flow (kmol/hr): Water       7.43e+03
                       Ethanol     391
                       AceticAcid  2.16
                       Glucose     6.33e-17
                       Yeast       81.4
   FermentationSaccharomycesEthanolIsobutanol         Units      V406
   Electricity         Power                             kW       473
                       Cost                          USD/hr        37
   Chilled water       Duty                           kJ/hr -5.26e+07
                       Flow                         kmol/hr  3.52e+04
                       Cost                          USD/hr       263
   Design              Reactor volume                    m3  8.85e+03
                       Batch time                        hr       100
                       Loading time                      hr      50.1
                       Number of reactors                           2
                       Recirculation flow rate        m3/hr      79.4
                       Reactor duty                   kJ/hr -1.75e+07
                       Cleaning and unloading time       hr         3
                       Working volume fraction                    0.9
   Purchase cost       Heat exchangers (x2)             USD  4.59e+04
                       Reactors (x2)                    USD  2.81e+06
                       Agitators (x2)                   USD  1.75e+05
                       Cleaning in place                USD  7.62e+05
                       Recirculation pumps (x2)         USD  1.05e+05
   Total purchase cost                                  USD  3.89e+06
   Utility cost                                      USD/hr       300

See the `full tutorial <https://nskinetics.readthedocs.io/en/latest/tutorial/index.html>`__ for the rest of the workflow — writing and simulating a kinetic model from scratch, the ``Event``/``FeedSpike`` API used inside the fermentor here, a tour of the shipped *S. cerevisiae* kinetic model, and the kinetics-to-biosteam bridge behind ``V406``.


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>`__.


