6ab585bcc2
- wiki/functional-description.md: rename Overfill Protection → High-volume
Safety; tighten basin-ordering chain; relocate level-based mode
diagrams under wiki/diagrams/modes/level-based/; document the new
flow.predicted.overflow.default position (replaces the previous
child='overflow' under position 'out'); add underflowVolume +
predictedUnderflowVolume entries.
- wiki/modes/{levelbased,powerbased}.md: paragraph cleanups.
- wiki/diagrams: move level-linear basin diagram under modes/level-based/
alongside a new level-log variant.
- simulations/run.js: add max_demand_gt expectation.
- simulations/scenarios/*: minor fixture updates.
- test/basic/nodeClass-config.test.js: new config-shape coverage.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
# Diagrams
|
|
|
|
Editable source diagrams for the pumpingStation wiki. The current diagrams are **`.drawio.svg` files with the draw.io source embedded**, so anyone can edit the SVG directly in [draw.io](https://app.diagrams.net/) without touching any Markdown.
|
|
|
|
## File roles
|
|
|
|
| File | Role |
|
|
|---|---|
|
|
| `<name>.drawio` | Optional native draw.io XML source, if a diagram also keeps a standalone source file. |
|
|
| `<name>.drawio.svg` | SVG export of the same diagram (with source embedded). What the wiki actually renders, and what round-trips back into draw.io. |
|
|
|
|
An optional standalone `.drawio` file can be committed beside the SVG, but the embedded-source SVG is enough for the wiki to render and for the next editor to pick up from exactly where the last one left off.
|
|
|
|
## Editing workflow
|
|
|
|
1. **Clone** the repo (you likely already have it if you're editing):
|
|
```bash
|
|
git clone https://gitea.wbd-rd.nl/RnD/pumpingStation.git
|
|
cd pumpingStation/wiki/diagrams
|
|
```
|
|
2. **Open** the `.drawio.svg` file in draw.io:
|
|
- Web: [app.diagrams.net](https://app.diagrams.net/) → *Open Existing Diagram*, or drag-and-drop.
|
|
- Desktop: [drawio-desktop](https://github.com/jgraph/drawio-desktop/releases).
|
|
3. **Edit** — move shapes, change labels, adjust layout.
|
|
4. **Export** to SVG with the source embedded:
|
|
- `File → Export as → SVG…`
|
|
- Check **Include a copy of my diagram** ← this is what lets future edits round-trip through the SVG.
|
|
- Save next to the source as `<name>.drawio.svg` (overwrite).
|
|
5. **Commit & push** the edited SVG, plus the `.drawio` file if one exists:
|
|
```bash
|
|
git add wiki/diagrams/<name>.drawio.svg
|
|
git commit -m "Update <name>: <what changed>"
|
|
git push
|
|
```
|
|
|
|
## Referencing a diagram from a wiki page
|
|
|
|
In any Markdown page under `wiki/`:
|
|
|
|
```markdown
|
|
|
|
```
|
|
|
|
Use a descriptive `alt` text; it's the fallback if the SVG fails and it shows up in exports.
|
|
|
|
## Naming
|
|
|
|
- kebab-case, one concept per diagram.
|
|
- Current diagrams:
|
|
|
|
| Diagram | Shows |
|
|
|---|---|
|
|
| `basin-model` | Shared physical basin cross-section — walls, pipe reference heights, derived safety zones, storage/dead volumes |
|
|
| `modes/level-based/basin-mode-level-linear` | Level-based linear control curve — rising ramp starts at inlet level, falling ramp shifts to `startLevel` |
|
|
| `modes/level-based/basin-mode-level-log` | Level-based logarithmic control curve — fast early response, falling ramp shifts to `startLevel` |
|
|
| `control-zones` | Legacy vertical level axis ("thermometer") for `levelbased` mode — STOP / DEAD ZONE / RUN with demand ramp |
|
|
| `safety-rules` | Dry-run vs high-volume safety rule asymmetry — which children stop, which keep running |
|
|
|
|
## Making a brand-new diagram
|
|
|
|
1. Open draw.io, start blank.
|
|
2. Draw it.
|
|
3. `File → Export as → SVG…` with **Include a copy of my diagram** checked → save as `wiki/diagrams/<name>.drawio.svg`.
|
|
4. Reference from the wiki page with ``.
|
|
5. Add an entry to the table above.
|
|
6. Commit the new `.drawio.svg` and updated `.md` together.
|
|
|
|
## These starters are rough
|
|
|
|
Some diagrams are still rough — layout is approximate, colors and fonts may be defaults, and alignment may need refinement. They're meant to be improved in draw.io as the model settles.
|
|
|
|
Open the `.drawio.svg` in draw.io and it will load the editable model. The SVG has the draw.io XML embedded in a `content="…"` attribute on the root `<svg>` element — that's what lets draw.io re-open its own SVG exports.
|