Rens Roosloot
Menu

Bioreactor DO Simulator DS

Volledige gerenderde weergave van DS.md.

Laatst gesynchroniseerd: 7 oktober 2026

DS - Bioreactor DO Simulator

Version: 0.2.1
Date: 2026-03-18
Status: Initial concept draft

1. Purpose

This Design Specification translates the current URS.md and FS.md into a practical static-site implementation approach for the first Bioreactor DO Simulator release.

2. Implementation Strategy

  • standalone page under site/bioreactor-do-simulator/
  • browser-rendered simulation with no backend dependency
  • stylized 2D cutaway vessel rendered client-side
  • chart rendering in the browser
  • static-site compatible deployment within the existing roosloot.com structure
  • modular JavaScript implementation with clear separation between model, controller, rendering, and UI

3. Technology Direction

Recommended direction:

  • plain HTML, CSS, and JavaScript modules for runtime
  • SVG for the stylized 2D cutaway vessel
  • a lightweight chart library or restrained custom chart implementation for the DO graph
  • Node.js only for local repo tooling such as docs rendering

The runtime should avoid unnecessary framework weight and should remain understandable as a small static project.

Preferred MVP direction:

  • use SVG for the vessel visualization
  • use browser-side JavaScript modules for state and simulation logic
  • prefer one chart implementation path only for the MVP so the simulator remains easy to maintain

4. High-Level Architecture

Recommended runtime layers:

  1. page shell
  2. simulation state manager
  3. process model
  4. PID controller
  5. simulation loop / timeline
  6. vessel view renderer
  7. chart view renderer
  8. UI controls and status wiring
  9. preset and disturbance manager

5. File and Module Design

Recommended page structure:

  • site/bioreactor-do-simulator/index.html
  • site/bioreactor-do-simulator/css/bioreactor-do-simulator.css
  • site/bioreactor-do-simulator/js/main.js
  • site/bioreactor-do-simulator/js/sim-state.js
  • site/bioreactor-do-simulator/js/sim-model.js
  • site/bioreactor-do-simulator/js/pid-controller.js
  • site/bioreactor-do-simulator/js/sim-loop.js
  • site/bioreactor-do-simulator/js/vessel-view.js
  • site/bioreactor-do-simulator/js/chart-view.js
  • site/bioreactor-do-simulator/js/ui-controls.js
  • site/bioreactor-do-simulator/js/presets.js

Optional later files:

  • site/bioreactor-do-simulator/js/i18n-bioprocess.js
  • site/bioreactor-do-simulator/assets/

Suggested module responsibilities:

  • main.js
    • bootstrap the page
    • initialize default state
    • connect UI, simulation loop, chart, and vessel renderer
  • sim-state.js
    • hold default values
    • expose active mode and current parameters
    • provide reset behavior
  • sim-model.js
    • implement the simplified dissolved-oxygen response model
    • apply time-step updates
    • expose derived values used by graph and vessel views
  • pid-controller.js
    • calculate controller output from setpoint and measured DO
    • manage proportional, integral, and derivative terms
    • clamp or limit output as needed for stable browser behavior
  • sim-loop.js
    • manage play/pause/reset runtime behavior
    • separate simulation step timing from UI updates
    • maintain a short bounded history for the live chart
  • vessel-view.js
    • update SVG layers based on simulation state
    • render interpretive cues such as bubbles, glow, and gas input emphasis
  • chart-view.js
    • render the primary DO chart
    • add setpoint overlay when auto mode is enabled
    • keep updates efficient during simulation
  • ui-controls.js
    • bind sliders, numeric readouts, toggles, and buttons
    • validate user input
    • update status labels and mode indicators
  • presets.js
    • define stable, aggressive, and oscillatory presets
    • define disturbance actions or event presets

6. State Design

The active simulator state should contain:

  • mode (manual or auto)
  • simulation running flag
  • current simulated time
  • current dissolved oxygen value
  • optional controller output
  • setpoint
  • manual gas-related inputs
  • process inertia / time constant
  • reactor volume or scaling parameter
  • oxygen demand
  • PID gains
  • stability/status label
  • recent history arrays for chart rendering
  • active preset metadata where relevant

The state should be represented as a plain JavaScript object so it remains easy to inspect and extend.

7. Simulation Design

7.1 Process Model

The MVP model should remain deliberately simple.

Recommended design approach:

  • one dissolved-oxygen state variable
  • one net oxygen transfer/input influence
  • one oxygen demand term
  • one response/inertia term that smooths or delays changes
  • one optional scaling factor for reactor size or effective responsiveness
  • one controller output path that can be interpreted as gas-actuation effort for the MVP

The goal is not physical fidelity. The goal is a believable response that clearly demonstrates:

  • approach to setpoint
  • overshoot
  • settling
  • oscillation
  • disturbance recovery

The model should be intentionally simple enough that future documentation can explain it in plain language.

7.2 Controller Design

The controller should:

  • calculate error from setpoint - measured DO
  • apply P, I, and D contributions
  • update each simulation step
  • produce one controller output value used by the process model
  • be bounded to a reasonable output range so the visualization remains stable and interpretable
  • keep integral behavior simple and controlled so the MVP does not become unstable due to implementation noise alone

7.3 Runtime Timing

Recommended MVP approach:

  • fixed simulation time step
  • browser-side render updates at a practical interval
  • short retained history window for the main graph
  • deterministic reset of controller and model state

The simulation loop should support:

  • start
  • pause
  • reset
  • preset load
  • disturbance event injection

8. Visualization Design

8.1 Editorial Page Shell

  • keep the shared site background language, but tuned toward a biotech/editorial mood
  • maintain the dark palette and existing typography pairing
  • treat the simulator stage as a premium project module rather than a generic dashboard block
  • keep explanatory copy concise and close to the top of the page
  • keep controls visually subordinate to the simulator stage rather than making the page feel slider-dominated

8.2 Vessel Design

The vessel should be an SVG-based stylized 2D cutaway.

Recommended layered elements:

  • vessel outer shell
  • liquid volume
  • gas headspace
  • inlet or sparging region
  • bubble layer
  • probe or sensor hint
  • optional agitator or mixing hint
  • optional glow/overlay layer for oxygen intensity
  • optional mode badge or small overlay for manual/auto state

Recommended design rules:

  • each layer should be independently controllable in code
  • the vessel should remain visually clean and readable
  • labels should be minimal
  • the vessel should respond to state with a few strong cues, not many weak ones
  • vessel cues should map to simulator meaning consistently, for example more aeration activity should not visually suggest lower actuation

Recommended dynamic mappings:

  • DO value -> liquid tone, oxygen glow, or calmness of the vessel
  • controller output -> gas/aeration emphasis
  • disturbance event -> temporary visible shift in vessel activity
  • stable versus oscillatory behavior -> calmer versus more active motion language

8.3 Chart Design

The chart should:

  • show dissolved oxygen as the primary trace
  • show setpoint when relevant
  • use restrained line weights and grid styling
  • remain readable at the same visual quality level as the rest of the page

The chart does not need to dominate the whole page. It should work in balance with the vessel.

Recommended MVP chart choice:

  • one compact time-series chart
  • DO as the main trace
  • setpoint as a lighter secondary trace in auto mode
  • optional controller-output readout outside the chart rather than a second graph in the MVP

9. Interaction Design

The page should support these interaction groups:

  • transport controls (Start, Pause, Reset)
  • manual process input controls
  • auto-mode PID controls
  • preset selection
  • disturbance action

Interaction rules:

  • mode changes should be immediately visible
  • parameter changes should update readouts clearly
  • controls not currently active should be visually explained, de-emphasized, or disabled
  • the page should never leave the user uncertain whether the simulator is in manual or automatic mode
  • the first interactive actions should be understandable without reading detailed help text

10. Validation and Safety Messaging

  • numeric controls should be bounded to sensible ranges
  • invalid values should fail safely and visibly
  • the page should always display the simplified-model disclaimer
  • wording should avoid implying that the simulator is suitable for real bioprocess operation or regulated decision-making
  • defaults should start in a calm, demonstrable state rather than a chaotic one

11. Performance and Maintainability Notes

  • keep the runtime lightweight and static-hosting friendly
  • prefer SVG and DOM updates over heavy rendering stacks
  • avoid unnecessary dependencies
  • separate model, controller, view, and UI logic so later features such as pH, temperature, agitation, biomass, lactate, or kLa teaching content can be added without rewriting the MVP core
  • keep the vessel renderer data-driven so new vessel variants or overlays can be introduced later with limited changes outside the rendering layer

12. Suggested Implementation Sequence

  1. create page shell and hero/disclaimer layout
  2. build the static vessel SVG
  3. implement the simplified DO model
  4. implement the PID controller
  5. wire start/pause/reset and parameter controls
  6. render the primary DO chart
  7. add status strip and mode indicators
  8. connect vessel visual cues to live simulation state
  9. add presets and disturbance handling
  10. polish layout, bilingual content, and reduced-motion behavior

13. Traceability

  • URS simulation and control requirements -> Sections 6, 7, 9
  • URS vessel and visualization requirements -> Section 8
  • URS static-site and security constraints -> Sections 2, 3, 10, 11
  • FS page structure and visual behavior -> Sections 5, 8, 9
  • FS runtime and controls -> Sections 6, 7, 9, 10

14. Current Implementation Checkpoint

Current implemented files:

  • site/bioreactor-do-simulator/index.html
  • site/bioreactor-do-simulator/css/bioreactor-do-simulator.css
  • site/bioreactor-do-simulator/js/main.js
  • site/bioreactor-do-simulator/js/sim-state.js
  • site/bioreactor-do-simulator/js/sim-model.js
  • site/bioreactor-do-simulator/js/pid-controller.js
  • site/bioreactor-do-simulator/js/sim-loop.js
  • site/bioreactor-do-simulator/js/vessel-view.js
  • site/bioreactor-do-simulator/js/chart-view.js
  • site/bioreactor-do-simulator/js/ui-controls.js
  • site/bioreactor-do-simulator/js/presets.js

Current implemented behavior:

  • browser-side DO simulation, chart, vessel visualization, transport controls, presets, disturbance injection, and bilingual page copy are functional
  • the desktop simulator stage currently uses a bounded viewport-height module
  • the implementation includes a runtime desktop fitting step in main.js that scales the inner simulator stage to stay within the defined block
  • a readability floor is also applied so the scale does not collapse indefinitely
  • when the readability floor prevents a full fit, the simulator stage itself may scroll internally

Current unresolved design issue:

  • the desktop layout still needs a final decision on the balance between:
    • one fully visible scaled simulator composition, and
    • larger readable text with limited internal stage scrolling

Recommended next-session starting point:

  1. review the current desktop simulator block at a typical laptop viewport
  2. decide the preferred tradeoff between scaling and internal scrolling
  3. simplify control density or stage composition if needed before further polish
Terug naar home