penicillium 0.1.0a0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. penicillium-0.1.0a0/.gitignore +23 -0
  2. penicillium-0.1.0a0/CHANGELOG.md +63 -0
  3. penicillium-0.1.0a0/CITATION.cff +86 -0
  4. penicillium-0.1.0a0/LICENSE +58 -0
  5. penicillium-0.1.0a0/NOTICE +30 -0
  6. penicillium-0.1.0a0/PKG-INFO +156 -0
  7. penicillium-0.1.0a0/README.md +74 -0
  8. penicillium-0.1.0a0/docs/api.md +27 -0
  9. penicillium-0.1.0a0/docs/background.md +29 -0
  10. penicillium-0.1.0a0/docs/benchmarking.md +35 -0
  11. penicillium-0.1.0a0/docs/benchmarks.md +27 -0
  12. penicillium-0.1.0a0/docs/citing.md +40 -0
  13. penicillium-0.1.0a0/docs/cli.md +78 -0
  14. penicillium-0.1.0a0/docs/configuration.md +156 -0
  15. penicillium-0.1.0a0/docs/control.md +187 -0
  16. penicillium-0.1.0a0/docs/cookbook.md +108 -0
  17. penicillium-0.1.0a0/docs/dcs.md +148 -0
  18. penicillium-0.1.0a0/docs/differentiable.md +53 -0
  19. penicillium-0.1.0a0/docs/faq.md +121 -0
  20. penicillium-0.1.0a0/docs/faults.md +149 -0
  21. penicillium-0.1.0a0/docs/glossary.md +102 -0
  22. penicillium-0.1.0a0/docs/gymnasium.md +63 -0
  23. penicillium-0.1.0a0/docs/index.md +91 -0
  24. penicillium-0.1.0a0/docs/installation.md +74 -0
  25. penicillium-0.1.0a0/docs/licensing.md +102 -0
  26. penicillium-0.1.0a0/docs/measurements.md +218 -0
  27. penicillium-0.1.0a0/docs/model.md +299 -0
  28. penicillium-0.1.0a0/docs/process.md +112 -0
  29. penicillium-0.1.0a0/docs/quickstart.md +60 -0
  30. penicillium-0.1.0a0/docs/quirks.md +63 -0
  31. penicillium-0.1.0a0/docs/related.md +30 -0
  32. penicillium-0.1.0a0/docs/scenarios.md +170 -0
  33. penicillium-0.1.0a0/docs/solver_sensitivity.md +16 -0
  34. penicillium-0.1.0a0/docs/validation.md +70 -0
  35. penicillium-0.1.0a0/docs/validation_100_batches.md +69 -0
  36. penicillium-0.1.0a0/docs/validation_coverage.md +48 -0
  37. penicillium-0.1.0a0/docs/validation_octave.md +283 -0
  38. penicillium-0.1.0a0/docs/variables.md +101 -0
  39. penicillium-0.1.0a0/pyproject.toml +94 -0
  40. penicillium-0.1.0a0/src/penicillium/__init__.py +32 -0
  41. penicillium-0.1.0a0/src/penicillium/__main__.py +3 -0
  42. penicillium-0.1.0a0/src/penicillium/_numba.py +30 -0
  43. penicillium-0.1.0a0/src/penicillium/_paa_pls.py +220 -0
  44. penicillium-0.1.0a0/src/penicillium/_raman_reference.py +11 -0
  45. penicillium-0.1.0a0/src/penicillium/_version.py +1 -0
  46. penicillium-0.1.0a0/src/penicillium/batches.py +91 -0
  47. penicillium-0.1.0a0/src/penicillium/cli.py +151 -0
  48. penicillium-0.1.0a0/src/penicillium/constants.py +7 -0
  49. penicillium-0.1.0a0/src/penicillium/dcs/__init__.py +10 -0
  50. penicillium-0.1.0a0/src/penicillium/dcs/server.py +211 -0
  51. penicillium-0.1.0a0/src/penicillium/dcs/session.py +583 -0
  52. penicillium-0.1.0a0/src/penicillium/dcs/static/assets/index-DuCJmz0W.js +10 -0
  53. penicillium-0.1.0a0/src/penicillium/dcs/static/assets/index-DypehqXk.css +1 -0
  54. penicillium-0.1.0a0/src/penicillium/dcs/static/index.html +13 -0
  55. penicillium-0.1.0a0/src/penicillium/envs.py +327 -0
  56. penicillium-0.1.0a0/src/penicillium/jax_model.py +176 -0
  57. penicillium-0.1.0a0/src/penicillium/model.py +403 -0
  58. penicillium-0.1.0a0/src/penicillium/noise.py +203 -0
  59. penicillium-0.1.0a0/src/penicillium/raman.py +111 -0
  60. penicillium-0.1.0a0/src/penicillium/recipe.py +119 -0
  61. penicillium-0.1.0a0/src/penicillium/result.py +119 -0
  62. penicillium-0.1.0a0/src/penicillium/rng.py +18 -0
  63. penicillium-0.1.0a0/src/penicillium/scenarios.py +291 -0
  64. penicillium-0.1.0a0/src/penicillium/simulator.py +756 -0
  65. penicillium-0.1.0a0/src/penicillium/solvers.py +89 -0
  66. penicillium-0.1.0a0/tests/data/determinism_golden.json +313 -0
  67. penicillium-0.1.0a0/tests/test_cli.py +32 -0
  68. penicillium-0.1.0a0/tests/test_dcs.py +210 -0
  69. penicillium-0.1.0a0/tests/test_determinism.py +57 -0
  70. penicillium-0.1.0a0/tests/test_envs.py +116 -0
  71. penicillium-0.1.0a0/tests/test_jax_model.py +91 -0
  72. penicillium-0.1.0a0/tests/test_model_and_raman.py +86 -0
  73. penicillium-0.1.0a0/tests/test_noise.py +138 -0
  74. penicillium-0.1.0a0/tests/test_octave_v201.py +41 -0
  75. penicillium-0.1.0a0/tests/test_recipe.py +62 -0
  76. penicillium-0.1.0a0/tests/test_scenarios.py +65 -0
  77. penicillium-0.1.0a0/tests/test_simulator.py +272 -0
  78. penicillium-0.1.0a0/validation/compare_100_batches.py +389 -0
  79. penicillium-0.1.0a0/validation/indpensim_100_batches.py +135 -0
  80. penicillium-0.1.0a0/validation/solver_sensitivity.py +85 -0
  81. penicillium-0.1.0a0/validation/train_paa_pls.py +70 -0
  82. penicillium-0.1.0a0/webapp/src/App.jsx +277 -0
  83. penicillium-0.1.0a0/webapp/src/components/Displays.jsx +406 -0
  84. penicillium-0.1.0a0/webapp/src/components/Faceplate.jsx +229 -0
  85. penicillium-0.1.0a0/webapp/src/components/ProcessGraphic.jsx +421 -0
  86. penicillium-0.1.0a0/webapp/src/components/Trend.jsx +262 -0
  87. penicillium-0.1.0a0/webapp/src/format.js +35 -0
  88. penicillium-0.1.0a0/webapp/src/main.jsx +10 -0
  89. penicillium-0.1.0a0/webapp/src/styles.css +1022 -0
  90. penicillium-0.1.0a0/webapp/src/useDcs.js +127 -0
@@ -0,0 +1,23 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ .coverage
7
+ dist/
8
+ build/
9
+ notebooks/output/
10
+ .ipynb_checkpoints/
11
+
12
+ *.csv
13
+ *.zip
14
+ # Local-only material (IndPenSim MATLAB sources, not redistributed; private notes)
15
+ external/
16
+ private/
17
+ PLAN.md
18
+ IndPenSim_V2.01.zip
19
+ # Publisher PDFs of the IndPenSim papers: link them, do not redistribute
20
+ docs/*.pdf
21
+ docs/feedback/
22
+ site/
23
+ webapp/node_modules/
@@ -0,0 +1,63 @@
1
+ # Changelog
2
+
3
+ All notable changes are listed here. Versions follow [Semantic Versioning](https://semver.org/); a minor version
4
+ may change numerical output only with an entry here and an updated validation report.
5
+
6
+ ## 0.1.0a0 (2026-10-30)
7
+
8
+ First public release (alpha).
9
+
10
+ - The project is called **Penicillium**: `pip install penicillium`, `import penicillium`, command `penicillium`
11
+ (working name during development: `pypensim-next`).
12
+
13
+ ### Simulator
14
+ - Pure-Python IndPenSim simulator (NumPy, SciPy, pandas), optional Numba backend (`[fast]`), 55 channels, Raman
15
+ spectra, faults 0-8, disturbances, PRBS feeds, PAT control of PAA, offline lab measurements, batches up to 350 h.
16
+ - Follows MATLAB IndPenSim V2.01.
17
+ - `SimulationConfig(quirks="matlab" | "fixed")`: IndPenSim's controller code as written, or an alternative reading of two of its details.
18
+ - `SimulationConfig(inhibition=0 | 1 | 2)`: IndPenSim's three inhibition models.
19
+ - `BatchParameters`: the random inputs of a batch, replayable; `BatchParameters.from_matlab()` replays a batch
20
+ captured from MATLAB IndPenSim.
21
+ - Seeding: every random quantity has its own `SeedSequence` stream; the random inputs of a batch are bit-identical
22
+ on every platform (trajectories agree to ~1e-4) and independent of NumPy's global generator. The eight disturbances are independent, as in IndPenSim.
23
+ - `PAA_pred` channel: PAA predicted from the Raman spectrum with a PLS model fitted by this project.
24
+ - `metadata["growth_rate_resets"]`: samples where IndPenSim's growth-rate reset fired.
25
+ - `MeasurementNoise` and `Sensor`: sensor and assay errors (white noise, relative error, calibration offset,
26
+ drift, quantisation, bounds) added to a copy of a result; exact values kept in `BatchResult.truth`. `OUR`/`CER`
27
+ are recomputed from the measured off-gas. Preset `MeasurementNoise.typical()` (measurements only; recipe set
28
+ points stay exact); `measurement_noise=` on the
29
+ campaign builders; `penicillium generate --noise typical`. The simulator stays noise-free.
30
+
31
+ ### Ecosystem
32
+ - `penicillium.envs`: Gymnasium environments `IndPenSim-v0`, `IndPenSimFault-v0`, `IndPenSimRaman-v0`
33
+ (pass `check_env`, seeded); `collect_minari_dataset` for offline RL.
34
+ - `penicillium.scenarios`: one-call fault, soft-sensor and Goldrick-2019 campaigns in tidy form, batch-wise
35
+ splits, and a control benchmark.
36
+ - `simulate_batches` for parallel campaigns; `penicillium generate` command-line dataset generator.
37
+
38
+ ### Operator console
39
+ - `penicillium dcs` (`[dcs]` extra): one batch in real time in a DCS-style web app (FastAPI + React):
40
+ process graphic with PV and SP, faceplates with trends, CAS/AUTO modes and operator setpoints, priority alarms
41
+ with acknowledgement, event journal, offline lab results, Raman spectrum, hold/resume/abort, ×1 to ×36000 speed.
42
+ `penicillium.dcs.BatchSession` is the same logic without the web layer.
43
+
44
+ ### Differentiable model
45
+ - `penicillium.jax_model` (`[jax]` extra): the model right-hand side as a jit-compiled JAX function generated from
46
+ the same source as the NumPy/Numba versions, with exact state and parameter Jacobians; gradients through stiff
47
+ integration (e.g. diffrax) match finite differences.
48
+
49
+ ### Validation
50
+ - Line-by-line comparison with IndPenSim V2.01 (`docs/quirks.md`).
51
+ - Statistical comparison with the published 100-batch IndPenSim data set (`docs/validation.md`), with mean
52
+ differences, Welch intervals and KS power per strategy, a coverage appendix for every channel, and the method
53
+ and evidence behind the fault types inferred for published batches 91-100.
54
+ - Cross-platform determinism tests.
55
+
56
+ ### Documentation
57
+ - Changes after a review of the pre-release manual: "Limitations at a glance" on
58
+ the first page; "no significant difference detected" with KS p-values and test power instead of
59
+ "indistinguishable"; fault labels (`fault_active`) defined for process and sensor faults; the limits of the
60
+ worked examples stated (batch-level counting and Clopper-Pearson intervals in tutorial 5, sample-wise
61
+ cross-validation in tutorial 6, baselines in tutorial 7, Student's t interval in tutorial 2); reward shaping
62
+ equivalence of the Gymnasium reward; replay of the 15 Octave batches in Penicillium and MATLAB; seeding overlap
63
+ warnings; new pages on reporting a benchmark and related simulators.
@@ -0,0 +1,86 @@
1
+ cff-version: 1.2.0
2
+ message: >-
3
+ If you use Penicillium, please cite the software and the two IndPenSim papers it implements
4
+ (Goldrick et al. 2015 and 2019, listed under references). Penicillium is MIT-licensed; the parts
5
+ derived from IndPenSim are also under IndPenSim's BSD 3-Clause License (Copyright (c) 2016, Stephen Goldrick).
6
+ title: "Penicillium: a validated, pip-installable Python implementation of the IndPenSim penicillin fermentation simulator"
7
+ type: software
8
+ authors:
9
+ - family-names: Sartori
10
+ given-names: Francesco
11
+ orcid: "https://orcid.org/0000-0002-7905-5690"
12
+ version: 0.1.0a0
13
+ date-released: 2026-10-30
14
+ repository-code: "https://github.com/francesco-sartori/Penicillium"
15
+ url: "https://penicillium.readthedocs.io"
16
+ license:
17
+ - MIT
18
+ - BSD-3-Clause
19
+ keywords:
20
+ - IndPenSim
21
+ - penicillin
22
+ - fed-batch fermentation
23
+ - bioprocess simulation
24
+ - process control
25
+ - fault detection
26
+ - soft sensors
27
+ - reinforcement learning
28
+ references:
29
+ - type: article
30
+ title: The development of an industrial-scale fed-batch fermentation simulation
31
+ authors:
32
+ - family-names: Goldrick
33
+ given-names: Stephen
34
+ - family-names: Ştefan
35
+ given-names: Andrei
36
+ - family-names: Lovett
37
+ given-names: David
38
+ - family-names: Montague
39
+ given-names: Gary
40
+ - family-names: Lennox
41
+ given-names: Barry
42
+ journal: Journal of Biotechnology
43
+ volume: 193
44
+ start: 70
45
+ end: 82
46
+ year: 2015
47
+ doi: 10.1016/j.jbiotec.2014.10.029
48
+ - type: article
49
+ title: Modern day monitoring and control challenges outlined on an industrial-scale benchmark fermentation process
50
+ authors:
51
+ - family-names: Goldrick
52
+ given-names: Stephen
53
+ - family-names: Duran-Villalobos
54
+ given-names: Carlos A.
55
+ - family-names: Jankauskas
56
+ given-names: Karolis
57
+ - family-names: Lovett
58
+ given-names: David
59
+ - family-names: Farid
60
+ given-names: Suzanne S.
61
+ - family-names: Lennox
62
+ given-names: Barry
63
+ journal: Computers and Chemical Engineering
64
+ volume: 130
65
+ start: 106471
66
+ year: 2019
67
+ doi: 10.1016/j.compchemeng.2019.05.037
68
+ - type: data
69
+ title: "Data for: Modern day monitoring and control challenges outlined on an industrial-scale benchmark fermentation process"
70
+ authors:
71
+ - family-names: Goldrick
72
+ given-names: Stephen
73
+ publisher:
74
+ name: Mendeley Data
75
+ year: 2019
76
+ doi: 10.17632/pdnjz7zz5x.1
77
+ license: CC-BY-4.0
78
+ - type: software
79
+ title: "IndPenSim: Industrial-scale Penicillin Simulation"
80
+ authors:
81
+ - family-names: Goldrick
82
+ given-names: Stephen
83
+ version: "2.01"
84
+ date-released: 2019-07-09
85
+ license: BSD-3-Clause
86
+ url: https://www.mathworks.com/matlabcentral/fileexchange/49041-industrial-scale-penicillin-simulationv2
@@ -0,0 +1,58 @@
1
+ Penicillium is distributed under the MIT License (part 1). The process model, controllers, recipe tables,
2
+ fault profiles and reference Raman spectrum derive from IndPenSim, which is distributed under the BSD 3-Clause
3
+ License (part 2). Both notices apply to the parts derived from IndPenSim. See NOTICE for details.
4
+
5
+
6
+ 1. MIT License
7
+
8
+ Copyright (c) 2026 Francesco Sartori
9
+
10
+ Portions derived from PenSimPy 1.2.5:
11
+ Copyright (c) 2020 Quartic.ai Canada, Inc.
12
+
13
+ Permission is hereby granted, free of charge, to any person obtaining a copy
14
+ of this software and associated documentation files (the "Software"), to deal
15
+ in the Software without restriction, including without limitation the rights
16
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
17
+ copies of the Software, and to permit persons to whom the Software is
18
+ furnished to do so, subject to the following conditions:
19
+
20
+ The above copyright notice and this permission notice shall be included in all
21
+ copies or substantial portions of the Software.
22
+
23
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
26
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
28
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29
+ SOFTWARE.
30
+
31
+
32
+ 2. IndPenSim (BSD 3-Clause License)
33
+
34
+ Copyright (c) 2016, Stephen Goldrick
35
+ All rights reserved.
36
+
37
+ Redistribution and use in source and binary forms, with or without
38
+ modification, are permitted provided that the following conditions are met:
39
+
40
+ * Redistributions of source code must retain the above copyright notice, this
41
+ list of conditions and the following disclaimer.
42
+
43
+ * Redistributions in binary form must reproduce the above copyright notice,
44
+ this list of conditions and the following disclaimer in the documentation
45
+ and/or other materials provided with the distribution
46
+ * Neither the name of University College London nor the names of its
47
+ contributors may be used to endorse or promote products derived from this
48
+ software without specific prior written permission.
49
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
50
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
51
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
52
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
53
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
54
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
55
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
56
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
57
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
58
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,30 @@
1
+ Penicillium
2
+ Copyright (c) 2026 Francesco Sartori. Licensed under the MIT License; the parts derived from IndPenSim are
3
+ also subject to IndPenSim's BSD 3-Clause License. Both licence texts are in LICENSE.
4
+
5
+ This product includes or derives from the following works.
6
+
7
+ 1. IndPenSim (Industrial-scale Penicillin Simulation), MATLAB, version 2.01
8
+ Copyright (c) 2016, Stephen Goldrick. All rights reserved.
9
+ Distributed under the BSD 3-Clause License, reproduced in full in LICENSE (part 2).
10
+ https://www.mathworks.com/matlabcentral/fileexchange/49041-industrial-scale-penicillin-simulationv2
11
+ http://www.industrialpenicillinsimulation.com/
12
+ The process model, controllers, recipe tables, fault profiles and the reference Raman spectrum of this
13
+ package are derived from IndPenSim. Penicillium is not endorsed by Stephen Goldrick, by University
14
+ College London or by any other contributor to IndPenSim. IndPenSim is described in:
15
+ S. Goldrick, A. Stefan, D. Lovett, G. Montague, B. Lennox. The development of an industrial-scale
16
+ fed-batch fermentation simulation. Journal of Biotechnology 193 (2015) 70-82.
17
+ doi:10.1016/j.jbiotec.2014.10.029
18
+ S. Goldrick, C. A. Duran-Villalobos, K. Jankauskas, D. Lovett, S. S. Farid, B. Lennox. Modern day
19
+ monitoring and control challenges outlined on an industrial-scale benchmark fermentation process.
20
+ Computers and Chemical Engineering 130 (2019) 106471. doi:10.1016/j.compchemeng.2019.05.037
21
+ No MATLAB source file of IndPenSim is distributed with this package.
22
+
23
+ 2. PenSimPy 1.2.5, Copyright (c) 2020 Quartic.ai Canada, Inc., MIT License.
24
+ src/penicillium/model.py, simulator.py and raman.py contain portions derived from PenSimPy. Its MIT
25
+ permission notice is reproduced in LICENSE (part 1).
26
+
27
+ 3. Data. The PLS coefficients in src/penicillium/_paa_pls.py were fitted by this project on spectra it
28
+ simulated (validation/train_paa_pls.py); IndPenSim's PAA_PLS_model.mat is not used or distributed.
29
+ Comparisons with the published IndPenSim data set (Goldrick, 2019, Mendeley Data, doi:10.17632/pdnjz7zz5x.1,
30
+ CC BY 4.0) download it at run time; it is not redistributed.
@@ -0,0 +1,156 @@
1
+ Metadata-Version: 2.5
2
+ Name: penicillium
3
+ Version: 0.1.0a0
4
+ Summary: Penicillium: a Python implementation of the IndPenSim penicillin fermentation simulator
5
+ Project-URL: Documentation, https://penicillium.readthedocs.io
6
+ Project-URL: Source, https://github.com/francesco-sartori/Penicillium
7
+ Project-URL: Changelog, https://github.com/francesco-sartori/Penicillium/blob/main/CHANGELOG.md
8
+ Project-URL: Issues, https://github.com/francesco-sartori/Penicillium/issues
9
+ Author: Francesco Sartori
10
+ License-Expression: MIT AND BSD-3-Clause
11
+ License-File: LICENSE
12
+ License-File: NOTICE
13
+ Keywords: IndPenSim,Python implementation of IndPenSim,benchmark,bioprocess,fermentation,penicillin,penicillin fermentation simulator,process-control,simulation
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
25
+ Classifier: Topic :: Scientific/Engineering :: Chemistry
26
+ Requires-Python: >=3.10
27
+ Requires-Dist: numpy>=1.25
28
+ Requires-Dist: pandas>=2.0
29
+ Requires-Dist: scipy>=1.12
30
+ Provides-Extra: all
31
+ Requires-Dist: gymnasium>=1.0; extra == 'all'
32
+ Requires-Dist: numba>=0.59; extra == 'all'
33
+ Requires-Dist: pyarrow; extra == 'all'
34
+ Provides-Extra: dcs
35
+ Requires-Dist: fastapi>=0.110; extra == 'dcs'
36
+ Requires-Dist: numba>=0.59; extra == 'dcs'
37
+ Requires-Dist: uvicorn[standard]>=0.29; extra == 'dcs'
38
+ Provides-Extra: dev
39
+ Requires-Dist: diffrax; extra == 'dev'
40
+ Requires-Dist: fastapi>=0.110; extra == 'dev'
41
+ Requires-Dist: gymnasium>=1.0; extra == 'dev'
42
+ Requires-Dist: httpx; extra == 'dev'
43
+ Requires-Dist: jax>=0.4.30; extra == 'dev'
44
+ Requires-Dist: numba>=0.59; extra == 'dev'
45
+ Requires-Dist: pyarrow; extra == 'dev'
46
+ Requires-Dist: pytest-cov; extra == 'dev'
47
+ Requires-Dist: pytest>=8; extra == 'dev'
48
+ Requires-Dist: ruff>=0.6; extra == 'dev'
49
+ Requires-Dist: uvicorn[standard]>=0.29; extra == 'dev'
50
+ Provides-Extra: docs
51
+ Requires-Dist: gymnasium>=1.0; extra == 'docs'
52
+ Requires-Dist: mkdocs-jupyter<0.26,>=0.25; extra == 'docs'
53
+ Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
54
+ Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
55
+ Provides-Extra: fast
56
+ Requires-Dist: numba>=0.59; extra == 'fast'
57
+ Provides-Extra: gym
58
+ Requires-Dist: gymnasium>=1.0; extra == 'gym'
59
+ Provides-Extra: jax
60
+ Requires-Dist: jax>=0.4.30; extra == 'jax'
61
+ Provides-Extra: minari
62
+ Requires-Dist: gymnasium>=1.0; extra == 'minari'
63
+ Requires-Dist: minari[create,hdf5]>=0.5; extra == 'minari'
64
+ Requires-Dist: pillow; extra == 'minari'
65
+ Provides-Extra: notebooks
66
+ Requires-Dist: gymnasium>=1.0; extra == 'notebooks'
67
+ Requires-Dist: ipykernel; extra == 'notebooks'
68
+ Requires-Dist: jinja2; extra == 'notebooks'
69
+ Requires-Dist: matplotlib>=3.7; extra == 'notebooks'
70
+ Requires-Dist: minari[create,hdf5]>=0.5; extra == 'notebooks'
71
+ Requires-Dist: numba>=0.59; extra == 'notebooks'
72
+ Requires-Dist: pillow; extra == 'notebooks'
73
+ Requires-Dist: pyarrow; extra == 'notebooks'
74
+ Requires-Dist: scikit-learn>=1.3; extra == 'notebooks'
75
+ Provides-Extra: parquet
76
+ Requires-Dist: pyarrow; extra == 'parquet'
77
+ Provides-Extra: test
78
+ Requires-Dist: pyarrow; extra == 'test'
79
+ Requires-Dist: pytest-cov; extra == 'test'
80
+ Requires-Dist: pytest>=8; extra == 'test'
81
+ Description-Content-Type: text/markdown
82
+
83
+ # Penicillium: a Python implementation of the IndPenSim penicillin fermentation simulator
84
+
85
+ **IndPenSim for Python: validated, pip-installable, fast.** Penicillium is a maintained implementation of
86
+ IndPenSim, the industrial-scale (100 m³) fed-batch penicillin fermentation simulator of Goldrick et al. (2015,
87
+ 2019), the benchmark process for bioprocess monitoring, soft sensors, fault detection and control.
88
+
89
+ - **Installs anywhere.** Python 3.10 or later; tested on Linux, macOS and Windows with Python 3.10 to 3.14; no
90
+ compiler, no MATLAB.
91
+ - **Follows IndPenSim.** Checked line by line against IndPenSim V2.01; 14 of 15 batches of V2.01 (run in GNU
92
+ Octave) replayed within 0.1 % on yield. Against the published 100-batch data set, no significant difference
93
+ detected in the yield distributions of recipe-driven, operator-controlled and faulty batches (KS p = 0.31-0.93;
94
+ the tests have low power) ([validation](https://penicillium.readthedocs.io/en/latest/validation/)).
95
+ - **Fast.** 0.6 s per 230 h batch; about 380 batches per minute in parallel on an Intel Core i7-7700HQ
96
+ ([benchmarks](https://penicillium.readthedocs.io/en/latest/benchmarks/)).
97
+ - **Ready for ML and control.** One-call campaigns with labels and batch-wise splits, Gymnasium environments, Minari
98
+ datasets and a differentiable JAX model.
99
+ - **Reproducible.** Random inputs bit-identical and trajectories within about 1e-4 on Linux, macOS and Windows.
100
+ - **Honest about its limits.** Fixed fault windows, true values in the sensor-fault channels and the other known
101
+ limitations are listed on the first page of the documentation ([limitations](https://penicillium.readthedocs.io/en/latest/#limitations-at-a-glance)).
102
+ - **Open licence.** MIT, with the parts derived from IndPenSim also under IndPenSim's BSD 3-Clause licence;
103
+ documented provenance ([licensing](https://penicillium.readthedocs.io/en/latest/licensing/)).
104
+
105
+ > Status: alpha (0.1.0a0). The API may still change.
106
+
107
+ **Documentation: <https://penicillium.readthedocs.io>**
108
+
109
+ ## Install
110
+
111
+ ```bash
112
+ pip install "penicillium[fast]" # with the Numba backend (recommended)
113
+ ```
114
+
115
+ Other extras: `gym`, `minari`, `jax`, `dcs`, `parquet`, `notebooks`, `docs`, `dev`
116
+ ([installation](https://penicillium.readthedocs.io/en/latest/installation/)).
117
+
118
+ ## Example
119
+
120
+ ```python
121
+ from penicillium import Simulator
122
+
123
+ result = Simulator().run(seed=1) # one 230 h batch, 1150 samples of 12 min
124
+ print(result.total_yield) # harvested penicillin, kg
125
+ df = result.to_pandas() # 55 channels, indexed by time in hours
126
+ ```
127
+
128
+ ## Learn more
129
+
130
+ | | |
131
+ |---|---|
132
+ | [Tutorials](https://penicillium.readthedocs.io/en/latest/tutorials/) | Nine notebooks, one per feature: first batch, recipes and control, faults, lab data and Raman, campaigns and fault detection, soft sensors, reinforcement learning, the JAX model, the command line |
133
+ | [User guide](https://penicillium.readthedocs.io/en/latest/) | The process and the model, every option, variables and units, campaigns, the operator console, FAQ |
134
+ | [Validation](https://penicillium.readthedocs.io/en/latest/validation/) | What is checked against IndPenSim and the published data, and the results; [differences and quirks](https://penicillium.readthedocs.io/en/latest/quirks/) |
135
+ | [Case studies](https://github.com/francesco-sartori/Penicillium/tree/main/notebooks) | Replications of Goldrick et al. (2015, 2019), a comparison with the published 100-batch data, a statistical check of the noise model |
136
+
137
+ All of these are on the documentation site, <https://penicillium.readthedocs.io>.
138
+
139
+ From a clone of the repository, run the tests: `pytest -m "not slow"` (seconds) or `pytest` (adds full batches, ~4 min).
140
+
141
+ ## Citation
142
+
143
+ If you use Penicillium, cite IndPenSim and this package ([CITATION.cff](https://github.com/francesco-sartori/Penicillium/blob/main/CITATION.cff); see [citing](https://penicillium.readthedocs.io/en/latest/citing/)):
144
+
145
+ - S. Goldrick, A. Ştefan, D. Lovett, G. Montague, B. Lennox. *The development of an industrial-scale fed-batch
146
+ fermentation simulation.* Journal of Biotechnology 193 (2015) 70-82. doi:10.1016/j.jbiotec.2014.10.029
147
+ - S. Goldrick, C. A. Duran-Villalobos, K. Jankauskas, D. Lovett, S. S. Farid, B. Lennox. *Modern day monitoring and
148
+ control challenges outlined on an industrial-scale benchmark fermentation process.* Computers and Chemical
149
+ Engineering 130 (2019) 106471. doi:10.1016/j.compchemeng.2019.05.037
150
+
151
+ ## Licence
152
+
153
+ Penicillium is released under the MIT License. Its process model, controllers, recipes, fault profiles and
154
+ reference Raman spectrum derive from IndPenSim, Copyright (c) 2016, Stephen Goldrick, distributed under the BSD
155
+ 3-Clause License; that notice applies to those parts too. It is not endorsed by IndPenSim's
156
+ authors or by University College London. Full texts are in [LICENSE](https://github.com/francesco-sartori/Penicillium/blob/main/LICENSE) and [NOTICE](https://github.com/francesco-sartori/Penicillium/blob/main/NOTICE).
@@ -0,0 +1,74 @@
1
+ # Penicillium: a Python implementation of the IndPenSim penicillin fermentation simulator
2
+
3
+ **IndPenSim for Python: validated, pip-installable, fast.** Penicillium is a maintained implementation of
4
+ IndPenSim, the industrial-scale (100 m³) fed-batch penicillin fermentation simulator of Goldrick et al. (2015,
5
+ 2019), the benchmark process for bioprocess monitoring, soft sensors, fault detection and control.
6
+
7
+ - **Installs anywhere.** Python 3.10 or later; tested on Linux, macOS and Windows with Python 3.10 to 3.14; no
8
+ compiler, no MATLAB.
9
+ - **Follows IndPenSim.** Checked line by line against IndPenSim V2.01; 14 of 15 batches of V2.01 (run in GNU
10
+ Octave) replayed within 0.1 % on yield. Against the published 100-batch data set, no significant difference
11
+ detected in the yield distributions of recipe-driven, operator-controlled and faulty batches (KS p = 0.31-0.93;
12
+ the tests have low power) ([validation](https://penicillium.readthedocs.io/en/latest/validation/)).
13
+ - **Fast.** 0.6 s per 230 h batch; about 380 batches per minute in parallel on an Intel Core i7-7700HQ
14
+ ([benchmarks](https://penicillium.readthedocs.io/en/latest/benchmarks/)).
15
+ - **Ready for ML and control.** One-call campaigns with labels and batch-wise splits, Gymnasium environments, Minari
16
+ datasets and a differentiable JAX model.
17
+ - **Reproducible.** Random inputs bit-identical and trajectories within about 1e-4 on Linux, macOS and Windows.
18
+ - **Honest about its limits.** Fixed fault windows, true values in the sensor-fault channels and the other known
19
+ limitations are listed on the first page of the documentation ([limitations](https://penicillium.readthedocs.io/en/latest/#limitations-at-a-glance)).
20
+ - **Open licence.** MIT, with the parts derived from IndPenSim also under IndPenSim's BSD 3-Clause licence;
21
+ documented provenance ([licensing](https://penicillium.readthedocs.io/en/latest/licensing/)).
22
+
23
+ > Status: alpha (0.1.0a0). The API may still change.
24
+
25
+ **Documentation: <https://penicillium.readthedocs.io>**
26
+
27
+ ## Install
28
+
29
+ ```bash
30
+ pip install "penicillium[fast]" # with the Numba backend (recommended)
31
+ ```
32
+
33
+ Other extras: `gym`, `minari`, `jax`, `dcs`, `parquet`, `notebooks`, `docs`, `dev`
34
+ ([installation](https://penicillium.readthedocs.io/en/latest/installation/)).
35
+
36
+ ## Example
37
+
38
+ ```python
39
+ from penicillium import Simulator
40
+
41
+ result = Simulator().run(seed=1) # one 230 h batch, 1150 samples of 12 min
42
+ print(result.total_yield) # harvested penicillin, kg
43
+ df = result.to_pandas() # 55 channels, indexed by time in hours
44
+ ```
45
+
46
+ ## Learn more
47
+
48
+ | | |
49
+ |---|---|
50
+ | [Tutorials](https://penicillium.readthedocs.io/en/latest/tutorials/) | Nine notebooks, one per feature: first batch, recipes and control, faults, lab data and Raman, campaigns and fault detection, soft sensors, reinforcement learning, the JAX model, the command line |
51
+ | [User guide](https://penicillium.readthedocs.io/en/latest/) | The process and the model, every option, variables and units, campaigns, the operator console, FAQ |
52
+ | [Validation](https://penicillium.readthedocs.io/en/latest/validation/) | What is checked against IndPenSim and the published data, and the results; [differences and quirks](https://penicillium.readthedocs.io/en/latest/quirks/) |
53
+ | [Case studies](https://github.com/francesco-sartori/Penicillium/tree/main/notebooks) | Replications of Goldrick et al. (2015, 2019), a comparison with the published 100-batch data, a statistical check of the noise model |
54
+
55
+ All of these are on the documentation site, <https://penicillium.readthedocs.io>.
56
+
57
+ From a clone of the repository, run the tests: `pytest -m "not slow"` (seconds) or `pytest` (adds full batches, ~4 min).
58
+
59
+ ## Citation
60
+
61
+ If you use Penicillium, cite IndPenSim and this package ([CITATION.cff](https://github.com/francesco-sartori/Penicillium/blob/main/CITATION.cff); see [citing](https://penicillium.readthedocs.io/en/latest/citing/)):
62
+
63
+ - S. Goldrick, A. Ştefan, D. Lovett, G. Montague, B. Lennox. *The development of an industrial-scale fed-batch
64
+ fermentation simulation.* Journal of Biotechnology 193 (2015) 70-82. doi:10.1016/j.jbiotec.2014.10.029
65
+ - S. Goldrick, C. A. Duran-Villalobos, K. Jankauskas, D. Lovett, S. S. Farid, B. Lennox. *Modern day monitoring and
66
+ control challenges outlined on an industrial-scale benchmark fermentation process.* Computers and Chemical
67
+ Engineering 130 (2019) 106471. doi:10.1016/j.compchemeng.2019.05.037
68
+
69
+ ## Licence
70
+
71
+ Penicillium is released under the MIT License. Its process model, controllers, recipes, fault profiles and
72
+ reference Raman spectrum derive from IndPenSim, Copyright (c) 2016, Stephen Goldrick, distributed under the BSD
73
+ 3-Clause License; that notice applies to those parts too. It is not endorsed by IndPenSim's
74
+ authors or by University College London. Full texts are in [LICENSE](https://github.com/francesco-sartori/Penicillium/blob/main/LICENSE) and [NOTICE](https://github.com/francesco-sartori/Penicillium/blob/main/NOTICE).
@@ -0,0 +1,27 @@
1
+ # API reference
2
+
3
+ ::: penicillium.simulator.Simulator
4
+
5
+ ::: penicillium.simulator.SimulationConfig
6
+
7
+ ::: penicillium.simulator.BatchParameters
8
+
9
+ ::: penicillium.simulator.Fault
10
+
11
+ ::: penicillium.simulator.RamanMode
12
+
13
+ ::: penicillium.result.BatchResult
14
+
15
+ ::: penicillium.recipe.Recipe
16
+
17
+ ::: penicillium.recipe.Profile
18
+
19
+ ::: penicillium.batches
20
+
21
+ ::: penicillium.scenarios
22
+
23
+ ::: penicillium.envs.IndPenSimEnv
24
+
25
+ ::: penicillium.envs.collect_minari_dataset
26
+
27
+ ::: penicillium.jax_model
@@ -0,0 +1,29 @@
1
+ # Background: IndPenSim and PenSimPy (checked 2026-10-17)
2
+
3
+ ## IndPenSim (MATLAB)
4
+
5
+ - Reference: IndPenSim V2.01, the release on [MATLAB File Exchange](https://www.mathworks.com/matlabcentral/fileexchange/49041-industrial-scale-penicillin-simulationv2) (version 2.0.1,
6
+ 9 July 2019). Default solver `ode15s` with MATLAB's default options
7
+ (`solv = 2` in `indpensim_run.m`).
8
+ - Published 100-batch data set (Goldrick et al. 2019): compared by distribution in
9
+ [validation_100_batches.md](validation_100_batches.md). MATLAB's random streams differ from NumPy's, so
10
+ individual batches cannot be matched.
11
+
12
+ ## PenSimPy
13
+
14
+ [PenSimPy](https://pypi.org/project/pensimpy/) (Quartic.ai,
15
+ MIT) was the first Python port of IndPenSim, and Penicillium builds on it: its first version was ported from
16
+ PenSimPy 1.2.5 before being checked line by line against IndPenSim V2.01. PenSimPy's last release dates from June 2021 and its original repository (github.com/Quarticai/PenSimPy) is
17
+ no longer online. It pins NumPy 1.18, pandas 1.0 and SciPy 1.4, and its default solver path uses `fastodeint`, a
18
+ C++ extension built on Boost and OpenMP that is not published on PyPI, so `pip install pensimpy` does not complete
19
+ on current Python versions. It offers a step-by-step interface with a random-agent example, but no Gymnasium
20
+ environment.
21
+
22
+ Penicillium adds:
23
+
24
+ - an open licence (MIT, with IndPenSim's BSD 3-Clause for the parts derived from it) and documented provenance;
25
+ - pure Python on 3.10–3.14 with no compiler, tested on Linux, macOS and Windows, with an optional Numba backend;
26
+ - Gymnasium environments, Minari datasets and a differentiable JAX model;
27
+ - a browser-based DCS operator interface;
28
+ - all of IndPenSim's options, including its three inhibition models and eight faults, and statistical validation
29
+ against the published IndPenSim data set.
@@ -0,0 +1,35 @@
1
+ # Reporting a benchmark
2
+
3
+ A result obtained on simulated data can be repeated exactly by anyone, but only if the paper says how the data
4
+ were made and how the method was scored. When you publish a fault-detection, soft-sensor or control result
5
+ obtained with Penicillium, report at least the following.
6
+
7
+ | Item | Why | Where to find it |
8
+ |---|---|---|
9
+ | **Package version** | Numerical output may change between minor versions (with a changelog entry and an updated validation report) | `penicillium.__version__`, `campaign.json` |
10
+ | **Campaign seed** and campaign call | The seed fixes every batch of a campaign; the call fixes how many batches of each fault | `scenarios.fault_campaign(n_normal=..., n_per_fault=..., seed=...)` |
11
+ | **Non-default options** | Faults, Raman mode, batch length, measurement noise and so on change the data | `result.config` of any batch; `campaign.json` records only the generator, version and description |
12
+ | **Split seed** and split rule | Which batches went into training, validation and test; always split by batch | `camp.split(test_fraction=..., seed=...)`, or the list of batch ids |
13
+ | **Label used** | `fault_active` means "the cause acts" for process faults but "this batch is faulty" for sensor faults ([fault labels](scenarios.md#fault-labels-in-campaigns)); say which label each metric uses, and how you treated the sensor faults | your code |
14
+ | **Data the method saw** | Online measurements only (`camp.online()`), or also lab results, spectra or hidden states | your code |
15
+ | **Scoring rule** | Batch level or sample level; how an alarm before the fault starts is counted (a false alarm, not a detection); how delays are measured | your code |
16
+ | **Uncertainty** | With few test batches per class, give an interval for every rate (for example Clopper–Pearson for a detection rate) | your code |
17
+
18
+ Some properties of the IndPenSim faults affect what a benchmark measures:
19
+
20
+ - each fault type acts in the same fixed windows in every batch, so a classifier can learn the batch time instead
21
+ of the process, and detection delays reflect the windows ([Faults](faults.md#faults));
22
+ - under the sensor faults, `T` and `pH` hold the true broth values, which makes detection easier than on a plant
23
+ ([Faults](faults.md#sensor-faults-the-subtle-ones));
24
+ - a campaign with `seed=0` shares its batches with `Simulator().run(seed=n)` and with the default seeds of the
25
+ command line ([Campaigns](scenarios.md#ready-made-campaigns)).
26
+
27
+ Fixed seed sets, a scoring script and the list of faults that can be detected from `camp.online()` are planned, as
28
+ a versioned benchmark protocol.
29
+
30
+ A suggested sentence for the methods section, next to the one in [Citing](citing.md):
31
+
32
+ > The data were generated with Penicillium x.y.z, `scenarios.fault_campaign(n_normal=N, n_per_fault=M, seed=S)`
33
+ > with default options, and split by batch with `camp.split(test_fraction=0.3, seed=R)`. Detection was scored per
34
+ > batch on `fault`, an alarm before the first fault window counting as a false alarm, and per sample on
35
+ > `fault_active`, with sensor faults scored from 40 h.
@@ -0,0 +1,27 @@
1
+ # Speed
2
+
3
+ Measured with `benchmarks/speed.py` on an Intel Core i7-7700HQ (4 cores / 8 threads) with 16 GB RAM,
4
+ Windows 10, Python 3.14, 2026-10-02. One default 230 h batch (recipe driven, disturbances on); best of three runs.
5
+
6
+ | implementation | Raman spectra | seconds per batch | solver tolerance |
7
+ |---|---|---|---|
8
+ | Penicillium, Numba backend (`fast` extra) | no | **0.58** | rtol 1e-5 |
9
+ | Penicillium, Numba backend | yes | **0.87** | rtol 1e-5 |
10
+ | Penicillium, pure Python | no | 11.0 | rtol 1e-5 |
11
+ | Penicillium, pure Python | yes | 11.4 | rtol 1e-5 |
12
+
13
+ These timings are at Penicillium's default tolerance (LSODA, rtol 1e-5), which is not traded for speed: in the
14
+ [batch-by-batch comparison with IndPenSim V2.01](validation_octave.md), batches run with the defaults stay within
15
+ about 1e-6 (mean over the batch, relative to each variable's peak) and 5e-6 in yield of the same batches solved at
16
+ tight tolerances. IndPenSim V2.01 integrates at `ode15s`'s default RelTol 1e-3. A reference-grade run at
17
+ rtol 1e-10 takes about 2 s per batch.
18
+
19
+ Campaigns run in parallel processes (`simulate_batches`, `scenarios.*`): **200 batches in 32 s** on the same machine
20
+ (380 batches per minute), so a 1,000-batch campaign takes under 3 minutes.
21
+
22
+ Reproduce:
23
+
24
+ ```bash
25
+ pip install -e ".[fast]" # from a clone of the repository
26
+ python benchmarks/speed.py
27
+ ```