perfusio 0.1.0__tar.gz

perfusio-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Pytest / coverage
+.pytest_cache/
+.hypothesis/
+.benchmarks/
+.coverage
+coverage.xml
+htmlcov/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# Docs build output (source stays; built HTML does not)
+docs/build/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb_checkpoints
+
+# Results (generated data, not source)
+results/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+
+# Secrets / env files
+.env
+.env.*
+!.env.example

perfusio-0.1.0/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to `perfusio` are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and the project uses [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+### Fixed
+
+- **`bed/pareto.py` — `compute_pareto_front()` strict-dominance criterion**:
+  The implementation used `(Y[i] < Y).all(dim=1)` to test whether row `j`
+  dominates row `i`, requiring `j` to be *strictly* better on **every**
+  objective. This excludes valid domination when `j` ties `i` on one objective
+  but is strictly better on another. Corrected to the standard criterion:
+  `(Y[i] <= Y).all(dim=1) & (Y[i] < Y).any(dim=1)` (j weakly better on all,
+  strictly better on at least one). Downstream `hypervolume` and `qNEHVI`
+  computations now operate on the correct Pareto front.
+
+- **`twin/digital_twin.py` — `_obs_buffer` never populated (online learning dead)**:
+  `_async_step` collected new sample measurements but never appended them to
+  `_obs_buffer`, so `_retrain` always received an empty buffer and online GP
+  retraining was completely inoperative throughout an entire experiment.
+  Fixed by appending `{"sample": sample, "day": day, "controls_tensor": ctrl_tensor}`
+  at the end of each `_async_step` call after the BED decision is available.
+
+- **`twin/digital_twin.py` — `_retrain()` wrong model reference and malformed X/Y tensors**:
+  Three bugs in the online-retraining routine:
+  (1) `model=self.hybrid.gp_model` passed the `StepwiseGP` wrapper instead of
+  the inner `MultiTaskRateGP` (ExactGP), which is the object that owns
+  `set_train_data`.
+  (2) `new_x` was constructed as `torch.arange(N).unsqueeze(-1)` (shape `(N, 1)`)
+  instead of the required indexed multi-task format `(N × n_species, 17)` with
+  columns `[species×9, controls×6, day, task_id]`.
+  (3) `new_y` was passed with shape `(N, n_species)` instead of the flat
+  `(N × n_species,)` scalar targets the GaussianLikelihood expects.
+  Complete rewrite of `_retrain` builds correct one-step pairs in indexed
+  multi-task format, using controls stored in the now-populated `_obs_buffer`.
+
+- **`embedding/transfer.py` — `embed_and_concat()` does not exist on `EntityEmbedding`**:
+  Both `TransferLearner.warm_start` and `joint_finetune` called
+  `self.embedding.embed_and_concat(train_x, clone_ids)`, a method that was never
+  defined on `EntityEmbedding` (which only exposes `forward(clone_ids)`). Would
+  raise `AttributeError` at runtime. Fixed by calling `self.embedding(clone_ids)`
+  to get the embedding tensor and then `torch.cat([train_x, clone_emb], dim=1)`
+  to augment the feature matrix in both methods.
+
+- **`cli.py` — `reproduce-figures` showed all runs as Pareto-optimal**:
+  The `reproduce_figures` command passed all 27 run endpoints directly to
+  `fig7_pareto_front(pareto_titer, pareto_vcv)` without first computing the
+  Pareto front. Every point was rendered as Pareto-optimal. Fixed by calling
+  `compute_pareto_front` on the `(27, 2)` objective matrix, passing only the
+  non-dominated subset as the front and all points as the `feasible_*`
+  background scatter.
+
+- **`mechanistic/kinetics.py` — `q_lac()` VCD scaling bug**: During the
+  metabolic-switch (lactate-consumption) branch for Clone X, the volumetric
+  lactate consumption rate was a constant (`-lac_consump_rate * 1e9`) that
+  ignored cell density. Added `vcd` parameter; rate is now correctly scaled
+  as `-lac_consump_rate * vcd * 1e9` (units: mmol L⁻¹ h⁻¹).  All other
+  volumetric rates already multiplied by VCD; this brings `q_lac` into
+  consistency. Call site in `ode_rhs` updated to pass `vcd=max(vcd, 0.0)`.
+
+- **`gp/stepwise.py` — `_rollout_mm()` wrong quantiles**: The 10th/90th
+  percentile z-scores used `math.log(0.10/0.90) ≈ −2.197` (the logit
+  function) instead of the Gaussian inverse CDF. Replaced with
+  `math.sqrt(2) * math.erfinv(2*p − 1)` giving the correct `z_10 ≈ −1.2816`.
+
+- **`simulator/cho_perfusion.py` — deprecated `asyncio.get_event_loop()`**:
+  Changed to `asyncio.get_running_loop()`, which is the correct call inside
+  an already-running event loop (Python 3.10+ deprecation).
+
+- **`twin/digital_twin.py` — deprecated `asyncio.get_event_loop()`**:
+  Replaced `get_event_loop().run_until_complete(…)` in `step()` and
+  `run_sync()` with `asyncio.run(…)`, the recommended Python 3.10+ pattern
+  for running coroutines from synchronous code.
+
+- **`hybrid/model.py` — `predict_next_state()` double-counted mechanistic
+  contribution**: The original code computed `c_{t+1} = c_t + dt*r_mech +
+  gp_mean` where `gp_mean` is the GP's direct prediction of `c_{t+1}` (not
+  a rate). This effectively added the mechanistic Euler step twice. Fixed to
+  correctly decompose: `c_{t+1} = c_mech + (gp_mean − c_mech)` where
+  `c_mech = c_t + dt*r_mech`, making the GP residual structure explicit.
+
+- **`cli.py` `train` command — `PerfusionKernel` input dimension mismatch**:
+  `PerfusionKernel(n_state_dims=15)` expects 17-dim inputs (`n_state_dims +
+  day + task_id`), but the training matrix `train_x` had only 16 columns
+  (species + controls + day, no task_id). Fixed by appending a zeros
+  `task_id` column before model construction.
+
+- **`gp/exact_gp.py` — `predict_with_ci()` device mismatch**: The `erfinv`
+  scalar tensor was created without `device=pred.mean.device`, causing a
+  CPU/GPU mismatch on non-CPU devices. Fixed by passing `device=` explicitly.
+
+- **`cli.py` `simulate` docstring**: Corrected "24-run Box-Behnken" to
+  "27-run Box-Behnken" (4-factor BBD with 3 center points = 24 + 3 = 27
+  runs).
+
+- **`viz/static.py` — `fig4_training_trajectories()` subplot bug**: The
+  computed `subset` variable was never used; both panels iterated over the
+  full `runs` list, rendering identical charts. Fixed to correctly split runs
+  by `clone_labels` (CloneX left, CloneY right) with an even index-based
+  split as fallback when labels are absent.
+
+## [0.1.0] — 2024-01-01
+
+### Added
+
+- `perfusio.mechanistic` — CHO kinetics ODEs (dual-Monod, Pirt maintenance,
+  Warburg metabolic switching, Luedeking–Piret product formation).
+- `perfusio.gp` — PerfusionKernel, JackknifeEnsemble (K=20), StepwiseGP
+  with MC and moment-matching rollout.
+- `perfusio.embedding` — EntityEmbedding (d=4), TransferLearner with
+  differential learning-rate fine-tuning.
+- `perfusio.hybrid` — HybridStateSpaceModel, `train_hybrid`, `retrain_online`,
+  `forecast_run`.
+- `perfusio.bed` — 11 acquisition functions (PI, EI, LogEI, UCB, qEI,
+  qLogEI, qUCB, qEHVI, qNEHVI, qNParEGO), Pareto front, hypervolume,
+  BEDPolicy.
+- `perfusio.simulator` — CHOSimulator, Box-Behnken / central-composite /
+  Latin hypercube DoE, NoiseModel.
+- `perfusio.twin` — DigitalTwin, AuditLogger (SHA-256), AlarmNotifier,
+  DailyScheduler.
+- `perfusio.connectors` — OPCUAConnector (asyncua, auto-reconnect, cert auth),
+  SQLStore (8-table Alembic schema), FilesystemStore (CSV/Parquet/Excel),
+  Ambr250Emulator (5-reactor ensemble).
+- `perfusio.metrics` — rRMSE horizon (Gadiyar Eqs. 5–6), PI coverage,
+  sharpness, CRPS, hypervolume indicator, IGD+, ε-indicator.
+- `perfusio.viz` — Static (Matplotlib) and interactive (Plotly/Dash)
+  visualisation; Fig. 4, 6, 7, 8 reproduction.
+- `perfusio.cli` — Typer commands: `simulate`, `train`, `run`,
+  `reproduce-figures`.
+- Full test suite: >92% line / >85% branch coverage; CI on Linux/macOS/Windows
+  × Python 3.11/3.12/3.13.
+- Sphinx documentation with MathJax theory pages.
+- Apache-2.0 licence; CITATION.cff citing all five source papers.

perfusio-0.1.0/CITATION.cff

@@ -0,0 +1,78 @@
+cff-version: 1.2.0
+message: "If you use perfusio, please cite the following works."
+title: "perfusio: Self-Driving Perfusion Bioprocess Reference Implementation"
+version: "0.1.0"
+date-released: "2026-05-10"
+license: Apache-2.0
+repository-code: "https://github.com/lynchaos/perfusio"
+url: "https://lynchaos.github.io/perfusio"
+contact:
+  - email: support@yaylali.uk
+    name: Kemal Yaylali
+authors:
+  - family-names: Yaylali
+    given-names: Kemal
+    email: kemal.yaylali@gmail.com
+    orcid: ""
+    website: "https://kemal.yaylali.uk"
+abstract: >
+  perfusio is an open-source Python library providing a peer-reviewable
+  reference implementation of the self-driving perfusion methodology of
+  Gadiyar et al. (2026), including stepwise GP hybrid models, entity-embedding
+  transfer learning, and 11 Bayesian experimental design acquisitions.
+
+references:
+  - type: article
+    authors:
+      - family-names: Gadiyar
+        given-names: Chiraag J.
+    title: "Self-Driving Development of Perfusion Processes for Monoclonal Antibody Production"
+    journal: "Biotechnology and Bioengineering"
+    year: 2026
+    volume: 123
+    issue: 2
+    start: 391
+    end: 405
+    doi: "10.1002/bit.28631"
+
+  - type: article
+    authors:
+      - family-names: Hutter
+        given-names: Simone
+    title: "Clone selection in cell culture development using multi-objective Bayesian optimisation with entity-embedding transfer learning"
+    journal: "Computers & Chemical Engineering"
+    year: 2021
+    volume: 151
+    pages: "107373"
+    doi: "10.1016/j.compchemeng.2021.107373"
+
+  - type: article
+    authors:
+      - family-names: Cruz-Bournazou
+        given-names: Mariano N.
+    title: "Online model-based experimental design in bioprocess development"
+    journal: "Digital Chemical Engineering"
+    year: 2022
+    volume: 1
+    pages: "100005"
+
+  - type: article
+    authors:
+      - family-names: Liu
+        given-names: Yang
+      - family-names: Gunawan
+        given-names: Rudiyanto
+    title: "Bioprocess optimization under uncertainty using ensemble modeling"
+    journal: "Journal of Biotechnology"
+    year: 2017
+    volume: 244
+    start: 34
+    end: 44
+
+  - type: report
+    authors:
+      - family-names: Mione
+        given-names: Mattia
+    title: "Perfusion digital twin: a framework for online model-based control"
+    institution: "ETH Zürich"
+    year: 2024

perfusio-0.1.0/LICENSE

@@ -0,0 +1,170 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text file
+          distributed as part of the Derivative Works; within the Source
+          form or documentation, if provided along with the Derivative
+          Works; or, within a display generated by the Derivative Works,
+          if and wherever such third-party notices normally appear. The
+          contents of the NOTICE file are for informational purposes only
+          and do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+   You may add Your own license statement to Your modifications and
+   may provide additional grant of rights to use, copy, modify, merge,
+   publish, distribute, sublicense, and/or sell copies of Your
+   modifications, and to provide to whom the Your modifications are
+   furnished to do so, subject to the following conditions:
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

perfusio-0.1.0/LIMITATIONS.md

@@ -0,0 +1,46 @@
+# Limitations
+
+This document explicitly lists what `perfusio` does **not** model or support.
+
+## Out-of-Scope Biology
+
+- **Critical Quality Attributes (CQAs)** — No modelling of glycoforms,
+  charge variants, aggregates, HCP, or other product quality attributes.
+  The model tracks titer (mg/L) only.
+- **Medium composition** — The medium formulation is hard-coded to a generic
+  CHO basal medium. Proprietary feed and basal media are not supported.
+- **Cell line specifics** — Only two virtual cell lines (CloneX, CloneY) are
+  provided. Real cell-line parameters require calibration.
+- **3D fluid dynamics** — The model is zero-dimensional (perfectly mixed).
+  Spatial gradients in ambr®250 microbioreactors are not captured.
+- **Viral clearance** — No modelling of virus removal steps or biosafety
+  considerations.
+
+## Out-of-Scope Engineering
+
+- **Dissolved oxygen control** — DO is tracked as a state variable but
+  control (sparge rate, agitation) is not modelled.
+- **pH control** — pH is not a state variable in this implementation.
+- **Temperature ramping** — Temperature is a fixed parameter; dynamic
+  temperature shift protocols are not supported.
+- **Fed-batch mode** — The model assumes continuous perfusion; fed-batch
+  and perfusion-start transitions are not implemented.
+
+## Regulatory / Quality
+
+- **GMP validation** — `perfusio` is not validated under 21 CFR Part 11,
+  EU Annex 11, or any GxP framework. See
+  `docs/source/regulatory-considerations.md`.
+- **Electronic signatures** — `AuditLogger` produces audit records but not
+  compliant electronic signatures.
+- **CSV injection** — The `FilesystemStore` does not sanitise CSV fields
+  for spreadsheet-formula injection; do not open output CSVs in untrusted
+  spreadsheet applications.
+
+## Performance
+
+- **Wall-clock speed** — Training 27 Box-Behnken runs × 28 days on CPU
+  takes approximately 2–5 minutes. GPU acceleration is available but
+  not CI-tested.
+- **Scalability** — The SQL schema and SQLite backend are not intended for
+  multi-site or high-throughput deployments (> 100 concurrent reactors).