Repository navigation
Development
Developer knowledge (how each part works, why, and the gotchas) lives in CLAUDE.md. Plans and work in progress are in ROADMAP.md: propose an idea there, or claim an item before you start, so people and agents working in parallel don't collide.
| Path | What |
|---|---|
common/iomap.py |
Modbus register map, shared by plant and DCS |
plant/ |
Process model, Modbus server, instructor station |
dcs/ |
DCS configuration, control logic, historian, OPC UA server, operator console |
nodered/, nodered_data/flows.json
|
Node-RED image and flow |
tools/ |
Offline simulator, inventory generator, wiki publisher |
inventory/ |
Generated interface inventory |
tests/ |
The test suite |
wiki/ |
The source of this wiki |
After any code or web change: docker compose up -d --build (files are copied into the images).
tools/offline_sim.py couples the plant model and the DCS control layer directly, without
containers or I/O, and runs hours of plant time in seconds:
docker run --rm -v "$PWD":/w -w /w python:3.12-slim python tools/offline_sim.py \
--hours 1.5 --every 300 --scenario eo_demand_step@600 --cmd sp:FIC-101=160@1800--seed 7 makes a run repeatable. --site port-arden (or vadhana) runs another
site.
The model will keep growing, and the systems around it must keep agreeing. The tests guard consistent behaviour and stable interfaces: no tag, register, OPC UA node or API field goes missing or changes without anyone noticing. They are not there to prove the physics is perfect.
docker compose run --rm tests # everything, ~1 min (builds the test image once)
docker compose run --rm tests python -m pytest -m "not e2e" # without the end-to-end part
docker compose run --rm tests python tools/inventory.py # after an intended interface changeThe test container mounts the working tree, so there is nothing to rebuild after a code change. It does not touch the running stack. The tests come in five parts:
| File | What it checks | Time |
|---|---|---|
tests/test_inventory.py |
The committed interface inventory still matches the code | 5 s |
tests/test_contracts.py |
Every name a layer uses exists in the layer it comes from: Modbus map ↔ plant model ↔ DCS config ↔ OPC UA ↔ operator console, instructor station, Node-RED flow and docs (including this wiki). Hidden faults never reach the DCS side | 8 s |
tests/test_behaviour.py |
Plant model + DCS, faster than real time: steady state in spec with no P1/P2 alarm; a signature for every instructor scenario; the restart procedures; permissives, I/O loss, checkpoint, ESD, PPU time compression | 30 s |
tests/test_sites.py |
The other sites: each site's configuration and field I/O; its OPC UA address space = the table the mapping comes from; the mapping covers every published value and converts it correctly; steady state at Port Arden and Vadhana, the standby-pump changeover, a Vadhana restart | 10 s |
tests/test_e2e.py |
The real plant and DCS programs over real Modbus: HTTP API, OPC UA browse / values / HistoryRead and the raw registers against the inventory; Bad quality when the plant goes away. For Port Arden and Vadhana: the live address space, setpoints through the mapping, Vadhana's timestamps, and a DCS refusing another site's plant | 40 s |
When a test fails:
- The inventory test: an interface changed. If you intended the change, regenerate the inventory and commit it with the change. The PR then shows exactly which tags, nodes or registers changed.
- A behaviour test: cause and effect changed. Either fix the regression, or, if the new behaviour is right, update the test and say why in the PR.
-
New instructor scenario: add its expected effect to
SIGNATURESintests/test_behaviour.py. A test fails until you do. A scenario only another site has (Port Arden'slox_pump_trip) is tested intests/test_sites.py. -
New DCS tag: the inventory generator fails until
dataops/uns_model.pygives it a standard point.
The behaviour tests use a fixed seed. Their limits are meant to hold for any seed (seeds 1–44 pass except 37, see CLAUDE.md), so check another one after retuning:
docker compose run --rm -e HCW_TEST_SEED=3 tests python -m pytest tests/test_behaviour.pyThe wiki's source is the wiki/
folder in the repository, reviewed in pull requests like code. Don't edit pages on GitHub: the next
publish overwrites them. Screenshots live in wiki/images/, so image links work in the repo and in the wiki alike.
Publishing is automatic: when a change to wiki/ is merged into main, a
GitHub Action (.github/workflows/wiki.yml) runs tools/publish_wiki.py. By hand, from an
up-to-date main:
python tools/publish_wiki.py --dry-run # show what would change
python tools/publish_wiki.py # copy wiki/ (pages and images) to the wiki repo, commit, pushPages link to each other by page name ([Architecture](Architecture)), and to repository files by
full GitHub URL.
Start
Understand
Global DataOps
Use
Contribute