tep-studio 0.1.0__tar.gz

tep_studio-0.1.0/LICENSE

@@ -0,0 +1,52 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Khalid
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+================================================================================
+Bundled third-party code
+================================================================================
+
+This package bundles the numerical model of the modified Tennessee Eastman
+Process in `temexd_mod/temexd_mod.c` and `temexd_mod/teprob_mod.h`. That model is
+the work of third parties and is redistributed here for research and educational
+use, with its original source headers retained:
+
+  - Original Tennessee Eastman process control test problem by James J. Downs and
+    Ernest F. Vogel (Eastman Chemical Company), "A Plant-Wide Industrial Process
+    Control Problem", Computers & Chemical Engineering 17(3), 1993.
+
+  - Revised C model ("temexd_mod") by Andreas Bathelt and N. Lawrence Ricker, with
+    Mohieddine Jelali, "Revision of the Tennessee Eastman Process Model",
+    IFAC-PapersOnLine (ADCHEM) 48(8), 2015.
+
+The BSD 3-Clause license above covers this Python package (the schema-driven
+wrapper, control, interface, dataset, validation, and tooling code). It does not
+purport to grant rights in the bundled upstream model beyond those provided by its
+authors. Retain these attributions in any redistribution.

tep_studio-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+# The native extension is compiled from temexd_mod/ at build time (see
+# src/tep_studio/simulation/_cffi_build.py), so the sdist must ship those C sources;
+# without them `pip install` from the sdist (no prebuilt wheel) cannot build.
+graft temexd_mod
+# Validation reference data (read by the validation suite from a source checkout).
+include example.doc
+# Trim build noise from the sdist.
+global-exclude *.so *.pyc __pycache__/*

tep_studio-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: tep-studio
+Version: 0.1.0
+Summary: Schema-driven Python simulator for the modified Tennessee Eastman Process.
+Author-email: Khalid <wa3id.km@gmail.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, Khalid
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its contributors
+           may be used to endorse or promote products derived from this software without
+           specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+        ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+        
+        ================================================================================
+        Bundled third-party code
+        ================================================================================
+        
+        This package bundles the numerical model of the modified Tennessee Eastman
+        Process in `temexd_mod/temexd_mod.c` and `temexd_mod/teprob_mod.h`. That model is
+        the work of third parties and is redistributed here for research and educational
+        use, with its original source headers retained:
+        
+          - Original Tennessee Eastman process control test problem by James J. Downs and
+            Ernest F. Vogel (Eastman Chemical Company), "A Plant-Wide Industrial Process
+            Control Problem", Computers & Chemical Engineering 17(3), 1993.
+        
+          - Revised C model ("temexd_mod") by Andreas Bathelt and N. Lawrence Ricker, with
+            Mohieddine Jelali, "Revision of the Tennessee Eastman Process Model",
+            IFAC-PapersOnLine (ADCHEM) 48(8), 2015.
+        
+        The BSD 3-Clause license above covers this Python package (the schema-driven
+        wrapper, control, interface, dataset, validation, and tooling code). It does not
+        purport to grant rights in the bundled upstream model beyond those provided by its
+        authors. Retain these attributions in any redistribution.
+        
+Project-URL: Homepage, https://github.com/khalidlabs/tep-studio
+Project-URL: Documentation, https://khalidlabs.com/tep-studio/
+Project-URL: Source, https://github.com/khalidlabs/tep-studio
+Project-URL: Issues, https://github.com/khalidlabs/tep-studio/issues
+Keywords: tennessee-eastman,process-control,chemical-engineering,reinforcement-learning,gymnasium,simulation,control-systems,benchmark
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cffi>=1.15
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=1.5
+Requires-Dist: gymnasium>=0.29
+Requires-Dist: matplotlib>=3.6
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Provides-Extra: ui
+Requires-Dist: dash[diskcache]>=2.16; extra == "ui"
+Requires-Dist: plotly>=5.9; extra == "ui"
+Requires-Dist: pyarrow>=14; extra == "ui"
+Requires-Dist: comm>=0.2; extra == "ui"
+Dynamic: license-file
+
+---
+title: TEP Studio
+emoji: 🏭
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+short_description: Interactive Tennessee Eastman Process simulation studio (Dash + Plotly)
+---
+
+# TEP Studio
+
+This repository contains a schema-driven Python implementation of the modified Tennessee Eastman Process in `temexd_mod`. Simulation code lives in `src/tep_studio/simulation/`; `src/tep_studio/__init__.py` re-exports the public API.
+
+The Python package keeps the original `temexd_mod.c` equations as the numerical source of truth by compiling a native CFFI extension, then exposes process-aware Python contracts for:
+
+- process-core use through `TennesseeEastmanProcess`
+- Gymnasium RL/control interaction through `GymTEPEnv`
+- causal trajectory datasets through `TrajectoryDataset`
+- deterministic rollout and finite-difference optimization through `OptimizationAdapter`
+- closed-loop decentralized control through `ClosedLoopSimulation` and `RickerMultiLoopController`
+- an interactive Dash + Plotly interface for runs, step tests, and dataset generation (`tep_studio.ui`)
+
+## Quickstart
+
+```bash
+pip install tep-studio            # add [ui] for the web Simulation Studio
+```
+
+```python
+import tep_studio as tep
+tep.quickstart()                                  # short closed-loop smoke run
+
+import gymnasium                                   # a registered RL environment
+env = gymnasium.make("TennesseeEastman-v0", horizon=24.0)
+
+from tep_studio import ClosedLoopSimulation     # the stabilized closed loop
+result = ClosedLoopSimulation(horizon=24.0).run()
+```
+
+Or from the terminal: `tep run --horizon 24 --idv idv_01@1.0`, `tep list disturbances`,
+`tep ui`. See the [Cookbook](docs/cookbook.md) for task recipes.
+
+## Build
+
+Once published to PyPI, `pip install tep-studio` pulls a prebuilt wheel for
+Linux, macOS, and Windows — no C compiler required. The instructions below are for
+building from a source checkout, which compiles the native extension locally.
+
+The build requires `setuptools>=68` (declared in `pyproject.toml`). The recommended
+path is an editable install, which uses build isolation to provision the correct
+build dependencies automatically:
+
+```bash
+python3 -m pip install -e .
+```
+
+If your environment blocks build isolation (for example, an offline machine), first
+ensure the build tools are current, then install without isolation:
+
+```bash
+python3 -m pip install -U "setuptools>=68" wheel cffi
+python3 -m pip install -e . --no-build-isolation
+```
+
+To build the native extension in place instead of installing, the same
+`setuptools>=68` requirement applies (older setuptools mis-places the compiled
+artifact under the `src/` layout):
+
+```bash
+python3 -m pip install -U "setuptools>=68"
+python3 setup.py build_ext --inplace
+```
+
+The compiled `_tep_native` extension is platform-specific and is not tracked in
+version control. After moving the repository to a new machine or operating system,
+rebuild it with one of the commands above before importing the package.
+
+## Smoke Test
+
+```bash
+PYTHONPATH=src python3 src/tep_studio/simulation/examples/r12_open_loop.py
+PYTHONPATH=src python3 -m pytest -q
+```
+
+The R12 open-loop example should terminate near 1.07 h with a high reactor pressure shutdown.
+
+## Validation
+
+```bash
+PYTHONPATH=src python3 -m tep_studio.simulation.validation run --suite local
+PYTHONPATH=src python3 -m tep_studio.simulation.validation run --suite steady_state
+PYTHONPATH=src python3 -m tep_studio.simulation.validation run --suite mat_states
+PYTHONPATH=src python3 -m tep_studio.simulation.validation run --suite all --solvers RK23 RK45
+PYTHONPATH=src python3 -m tep_studio.simulation.validation figures
+PYTHONPATH=src python3 -m tep_studio.simulation.validation report
+```
+
+Validation artifacts are written under `src/tep_studio/simulation/validation_outputs/`. The steady-state suite exports the Ricker (1995) Table 2/3 references, compares the simulator base case against the reported Downs and Vogel steady state, and marks optimized modes 1-6 as reference-only unless their electronic 50-state vectors are supplied. The MAT-state suite evaluates the bundled Simulink `CSTATE` vectors for Mode 1, Mode 3, and Skogestad Mode 1 and writes paper-ready comparison tables and figures. Add `--download-external` to cache public reference metadata and files where available.
+
+## Closed-Loop Control
+
+The base-case plant is open-loop unstable and trips on high reactor pressure within a few hours. The `tep_studio.control` package adds the Ricker (1996) decentralized multiloop PI strategy, which stabilizes the plant for the full horizon:
+
+```bash
+PYTHONPATH=src python3 src/tep_studio/control/examples/ricker_mode1_closed_loop.py
+```
+
+```python
+from tep_studio.control import ClosedLoopSimulation
+
+result = ClosedLoopSimulation(control_interval=0.0005, horizon=48.0).run()
+assert result.stabilized  # ran the horizon without a shutdown
+```
+
+The controller is separate from the simulator core and consumes only published measurements (no plant-state leakage). It reproduces the loop pairings and gains from Ricker's runnable `MultiLoop_mode1.mdl`, initializes bumplessly from the Mode-1 state, and emits a reproducible experiment record. See `docs/control.md` for the loop structure, overrides, disturbance rejection, and configuration flags.
+
+## Interface (Simulation Studio)
+
+An interactive Dash + Plotly web interface for running, visualizing, and exporting simulations — open/closed-loop runs, disturbance scenarios, step tests, dataset generation, run comparison, and scenario save/load:
+
+```bash
+python3 -m pip install -e ".[ui]"
+python3 -m tep_studio.ui          # or: tep-ui ; opens http://127.0.0.1:8050
+```
+
+The interface is a thin layer over a Dash-free, importable backend (`from tep_studio.ui import run_scenario, ScenarioConfig, build_dataset`), so the same runs and exports are scriptable. See `docs/ui.md`.
+
+## Online Documentation
+
+The online documentation source is in `docs/` and is configured by `mkdocs.yml`. It is written as a practical step-by-step guide for new users and is based on the simulator supplement:
+
+```bash
+python3 -m pip install -e ".[docs]"
+python3 -m mkdocs serve
+python3 -m mkdocs build --strict
+```
+
+(Append `--no-build-isolation` to the install command if your environment blocks
+build isolation, after upgrading the build tools as described under [Build](#build).)
+
+The local server defaults to <http://127.0.0.1:8000/>. Start with `docs/getting-started.md`, then run the walkthrough in `docs/first-simulation.md`.

tep_studio-0.1.0/README.md

@@ -0,0 +1,143 @@
+---
+title: TEP Studio
+emoji: 🏭
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+short_description: Interactive Tennessee Eastman Process simulation studio (Dash + Plotly)
+---
+
+# TEP Studio
+
+This repository contains a schema-driven Python implementation of the modified Tennessee Eastman Process in `temexd_mod`. Simulation code lives in `src/tep_studio/simulation/`; `src/tep_studio/__init__.py` re-exports the public API.
+
+The Python package keeps the original `temexd_mod.c` equations as the numerical source of truth by compiling a native CFFI extension, then exposes process-aware Python contracts for:
+
+- process-core use through `TennesseeEastmanProcess`
+- Gymnasium RL/control interaction through `GymTEPEnv`
+- causal trajectory datasets through `TrajectoryDataset`
+- deterministic rollout and finite-difference optimization through `OptimizationAdapter`
+- closed-loop decentralized control through `ClosedLoopSimulation` and `RickerMultiLoopController`
+- an interactive Dash + Plotly interface for runs, step tests, and dataset generation (`tep_studio.ui`)
+
+## Quickstart
+
+```bash
+pip install tep-studio            # add [ui] for the web Simulation Studio
+```
+
+```python
+import tep_studio as tep
+tep.quickstart()                                  # short closed-loop smoke run
+
+import gymnasium                                   # a registered RL environment
+env = gymnasium.make("TennesseeEastman-v0", horizon=24.0)
+
+from tep_studio import ClosedLoopSimulation     # the stabilized closed loop
+result = ClosedLoopSimulation(horizon=24.0).run()
+```
+
+Or from the terminal: `tep run --horizon 24 --idv idv_01@1.0`, `tep list disturbances`,
+`tep ui`. See the [Cookbook](docs/cookbook.md) for task recipes.
+
+## Build
+
+Once published to PyPI, `pip install tep-studio` pulls a prebuilt wheel for
+Linux, macOS, and Windows — no C compiler required. The instructions below are for
+building from a source checkout, which compiles the native extension locally.
+
+The build requires `setuptools>=68` (declared in `pyproject.toml`). The recommended
+path is an editable install, which uses build isolation to provision the correct
+build dependencies automatically:
+
+```bash
+python3 -m pip install -e .
+```
+
+If your environment blocks build isolation (for example, an offline machine), first
+ensure the build tools are current, then install without isolation:
+
+```bash
+python3 -m pip install -U "setuptools>=68" wheel cffi
+python3 -m pip install -e . --no-build-isolation
+```
+
+To build the native extension in place instead of installing, the same
+`setuptools>=68` requirement applies (older setuptools mis-places the compiled
+artifact under the `src/` layout):
+
+```bash
+python3 -m pip install -U "setuptools>=68"
+python3 setup.py build_ext --inplace
+```
+
+The compiled `_tep_native` extension is platform-specific and is not tracked in
+version control. After moving the repository to a new machine or operating system,
+rebuild it with one of the commands above before importing the package.
+
+## Smoke Test
+
+```bash
+PYTHONPATH=src python3 src/tep_studio/simulation/examples/r12_open_loop.py
+PYTHONPATH=src python3 -m pytest -q
+```
+
+The R12 open-loop example should terminate near 1.07 h with a high reactor pressure shutdown.
+
+## Validation
+
+```bash
+PYTHONPATH=src python3 -m tep_studio.simulation.validation run --suite local
+PYTHONPATH=src python3 -m tep_studio.simulation.validation run --suite steady_state
+PYTHONPATH=src python3 -m tep_studio.simulation.validation run --suite mat_states
+PYTHONPATH=src python3 -m tep_studio.simulation.validation run --suite all --solvers RK23 RK45
+PYTHONPATH=src python3 -m tep_studio.simulation.validation figures
+PYTHONPATH=src python3 -m tep_studio.simulation.validation report
+```
+
+Validation artifacts are written under `src/tep_studio/simulation/validation_outputs/`. The steady-state suite exports the Ricker (1995) Table 2/3 references, compares the simulator base case against the reported Downs and Vogel steady state, and marks optimized modes 1-6 as reference-only unless their electronic 50-state vectors are supplied. The MAT-state suite evaluates the bundled Simulink `CSTATE` vectors for Mode 1, Mode 3, and Skogestad Mode 1 and writes paper-ready comparison tables and figures. Add `--download-external` to cache public reference metadata and files where available.
+
+## Closed-Loop Control
+
+The base-case plant is open-loop unstable and trips on high reactor pressure within a few hours. The `tep_studio.control` package adds the Ricker (1996) decentralized multiloop PI strategy, which stabilizes the plant for the full horizon:
+
+```bash
+PYTHONPATH=src python3 src/tep_studio/control/examples/ricker_mode1_closed_loop.py
+```
+
+```python
+from tep_studio.control import ClosedLoopSimulation
+
+result = ClosedLoopSimulation(control_interval=0.0005, horizon=48.0).run()
+assert result.stabilized  # ran the horizon without a shutdown
+```
+
+The controller is separate from the simulator core and consumes only published measurements (no plant-state leakage). It reproduces the loop pairings and gains from Ricker's runnable `MultiLoop_mode1.mdl`, initializes bumplessly from the Mode-1 state, and emits a reproducible experiment record. See `docs/control.md` for the loop structure, overrides, disturbance rejection, and configuration flags.
+
+## Interface (Simulation Studio)
+
+An interactive Dash + Plotly web interface for running, visualizing, and exporting simulations — open/closed-loop runs, disturbance scenarios, step tests, dataset generation, run comparison, and scenario save/load:
+
+```bash
+python3 -m pip install -e ".[ui]"
+python3 -m tep_studio.ui          # or: tep-ui ; opens http://127.0.0.1:8050
+```
+
+The interface is a thin layer over a Dash-free, importable backend (`from tep_studio.ui import run_scenario, ScenarioConfig, build_dataset`), so the same runs and exports are scriptable. See `docs/ui.md`.
+
+## Online Documentation
+
+The online documentation source is in `docs/` and is configured by `mkdocs.yml`. It is written as a practical step-by-step guide for new users and is based on the simulator supplement:
+
+```bash
+python3 -m pip install -e ".[docs]"
+python3 -m mkdocs serve
+python3 -m mkdocs build --strict
+```
+
+(Append `--no-build-isolation` to the install command if your environment blocks
+build isolation, after upgrading the build tools as described under [Build](#build).)
+
+The local server defaults to <http://127.0.0.1:8000/>. Start with `docs/getting-started.md`, then run the walkthrough in `docs/first-simulation.md`.