Rens Roosloot
Menu

Bioreactor DO Simulator FS

Volledige gerenderde weergave van FS.md.

Laatst gesynchroniseerd: 7 oktober 2026

FS - Bioreactor DO Simulator

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

1. Purpose

This Functional Specification translates the current URS.md into concrete MVP page behavior for the first browser-based Bioreactor DO Simulator.

2. Functional Scope

Included in the MVP:

  • one standalone simulator page
  • one dissolved-oxygen simulation loop
  • one stylized 2D cutaway vessel visualization
  • one main DO graph
  • one compact control set for manual inputs and PID tuning
  • one preset flow with a small set of example scenarios
  • one short explanation and disclaimer block

Excluded from the MVP:

  • validated bioprocess modeling
  • pH, temperature, or mixing control loops
  • biomass growth and metabolite balance simulation
  • guided kLa measurement workflows
  • historical data import
  • backend services, saves, or user accounts
  • multi-reactor comparison mode

3. User Flow

  1. The user opens the page and sees an editorial-style simulator layout.
  2. The page presents a stylized vessel view, a live DO graph, concise introductory copy, and a visible mode/status summary.
  3. The user starts the simulation or loads a preset.
  4. The user adjusts manual process settings or PID values.
  5. The simulation, graph, vessel, and status indicators update together.
  6. The user pauses, resets, or injects a disturbance to observe the response.

4. Page Structure

The page shall contain these sections:

  • a short hero/introduction area with concise purpose text
  • a visible disclaimer that the model is simplified and educational
  • a main simulator stage that combines the vessel and chart as one coherent focal area
  • a live chart area
  • a stylized 2D cutaway vessel area
  • a compact status strip or KPI-style summary row
  • grouped control cards for process inputs and PID tuning
  • a presets area
  • a short explanatory section for key concepts and terms

The page should feel like a polished project page on roosloot.com, not like a generic engineering dashboard.

The main simulator stage should read as the core experience of the page and should be visually prioritized over the explanatory content below it.

5. Visual and Interaction Behavior

FS-01 Overall Presentation

  • The page shall reuse the general roosloot.com visual language.
  • The page shall visually align more closely with Swapbound and the main site than with the ASCII visual pages.
  • The page shall use the shared dark palette, Fraunces plus Space Grotesk typography, and shared button language.
  • The simulator layout shall feel editorial and spacious rather than cramped or instrument-panel heavy.
  • The page shall use motion and background effects sparingly so the simulator remains calm, readable, and portfolio-oriented.
  • The desktop simulator stage should prioritize a coherent within-stage experience over long page scrolling during normal interaction.

FS-02 Vessel Visualization

  • The page shall include a stylized 2D cutaway vessel as a main visual element.
  • The vessel shall be positioned as a first-class part of the simulator, not as a decorative side image.
  • The vessel shall support layered 2D elements so later versions can add alternate vessel variants or overlays.
  • The vessel illustration shall remain readable at a glance and shall not require technical labels on every visual element to be understood.
  • The vessel should visually respond to simulation state through cues such as:
    • oxygen-related color or glow intensity
    • bubble or aeration activity
    • gas input indication
    • calm versus active visual state during stable or oscillatory control
  • The vessel should show a small number of meaningful visual cues rather than many simultaneous indicators.
  • The vessel shall remain interpretive and shall not be presented as a validated physical rendering.

FS-03 Main Chart

  • The page shall show one primary time-series chart for dissolved oxygen.
  • When automatic control is enabled, the chart shall also show the setpoint.
  • The chart may optionally show controller output later, but that is not required for the MVP.
  • The chart shall update while the simulation is running.
  • The chart shall remain readable with a restrained visual style that matches the rest of the page.
  • The chart shall remain visually secondary to the full-page editorial shell, but primary within the simulator stage itself.

6. Simulator Behavior

FS-04 Simulation Runtime

  • The simulator shall run in discrete time steps in the browser.
  • The user shall be able to start, pause, and reset the simulation.
  • Reset shall restore the defined default simulator state.
  • The simulator shall produce the same outputs for the same initial state and inputs.
  • Parameter changes made while the simulation is paused shall affect the next resumed run state without requiring a page reload.

FS-05 Manual Input Mode

  • The page shall provide a manual mode for direct process manipulation.
  • The MVP shall expose controls for:
    • oxygen-related gas input
    • nitrogen or dilution-gas input
    • process inertia or time constant
    • reactor volume or equivalent scaling parameter
    • oxygen demand
  • Manual changes shall visibly affect the graph and vessel view.
  • In manual mode, the page shall make it clear that direct gas/process inputs are being driven by the user rather than by the controller.

FS-06 PID Mode

  • The page shall provide an automatic PID mode that can be enabled or disabled.
  • The user shall be able to define:
    • DO setpoint
    • proportional gain
    • integral gain
    • derivative gain
  • When PID mode is active, controller output shall influence the process response automatically.
  • The page shall indicate whether the simulator is in manual or automatic mode.
  • When PID mode is active, controls that are no longer directly driven by the user should either be visually de-emphasized or clearly explained.

FS-07 Presets and Disturbances

  • The page should provide a small preset set for example behavior.
  • The initial preset set should include:
    • stable
    • aggressive
    • oscillatory
  • Loading a preset shall update the control state and prepare the simulation to run immediately.
  • The MVP should support at least one disturbance action that causes a visible temporary process change.
  • A disturbance action should be understandable as an event, not as a hidden parameter change.

7. Controls and Content

FS-08 Controls

  • Controls shall be grouped into logical cards or panels.
  • The page shall at minimum separate:
    • process inputs
    • PID settings
    • presets and scenario actions
    • simulation transport controls
  • Labels shall be concise and clear.
  • Inputs shall fail safely when values are invalid or out of range.
  • Sliders, toggles, and numeric values should remain synchronized so the current active value is always visible.
  • The transport controls (Start, Pause, Reset) shall remain easy to find and visually distinct from parameter controls.
  • For desktop use, the simulator should prefer one bounded interaction area rather than requiring repeated page-level scrolling between graph and controls.

FS-09 Status Display

  • The page shall show the current DO value numerically.
  • The page shall show the active mode (Manual or Auto).
  • The page shall show the current setpoint when PID mode is active.
  • The page should show controller output when PID mode is active.
  • The page should provide a simple stability hint such as stable, overshooting, or oscillatory behavior.
  • The status area should be compact and scannable rather than chart-like.

FS-10 Explanatory Content

  • The page shall explain the simulator purpose in short form.
  • The page shall define key terms such as DO, setpoint, and PID.
  • The page shall clearly state that the simulator is simplified and not suitable for real process decisions.
  • All user-facing content shall be available in Dutch and English.
  • Explanatory content should support exploration without forcing the user to read a long block before interacting with the simulator.

8. Functional Traceability

  • FR-001 to FR-006 -> FS-04
  • FR-010 to FR-015 -> FS-05, FS-08
  • FR-020 to FR-027 -> FS-06, FS-09
  • FR-030 to FR-039 -> FS-02, FS-03, FS-09
  • FR-040 to FR-045 -> FS-07
  • FR-050 to FR-054 -> FS-10

9. MVP Boundary

The MVP stops at one simplified dissolved-oxygen control loop with one vessel view, one primary DO chart, one compact set of process and PID controls, one preset set, and one explanatory/disclaimer content block.

The MVP does not yet include broader bioprocess modeling such as pH, temperature, agitation, biomass dynamics, metabolite production, or guided kLa teaching modes.

10. Current Prototype Checkpoint

Current prototype decisions captured at this point:

  • the page has a working browser-side simulation loop, chart, vessel view, controls, presets, and disturbance action
  • the main explanatory copy has been pushed below the simulator so the tool itself is prioritized higher on the page
  • the desktop simulator stage is being treated as a bounded interaction block rather than a long stacked page section
  • a layout tradeoff is still open between:
    • scaling the full simulator contents to keep graph, vessel, and controls visible together, and
    • preserving larger, more readable control text with some internal stage scrolling

Next session should start by resolving that desktop interaction tradeoff before further visual polish.

Terug naar home