PetroGrid
A live simulation of a chemical supply chain. When something fails, PetroGrid shows what fails next, when,
and what it costs.
The network is a typical Gulf-Coast-style chain: 22 sites (oil and gas fields, a salt mine, a gas plant, a
refinery, two steam crackers, chlor-alkali, four polymer plants, and their customers and ports) joined by
pipelines, roads, river lanes and sea lanes, with 82 trucks, barges and ships. Every plant is modelled down to
its process units with mass and energy balances. Nothing is scripted: each tank decides when to order and each
plant how fast to run from a few simple signals, so the network reacts to an upset on its own.
What it does
- Break something and watch it spread. Trip a cracker compressor, take down the refinery's crude unit,
halve the gas field, close a river lane, a sea lane or a road, or send a hurricane or a water restriction
across the whole network. The plant or route turns red and the consequences follow.
- See inside any plant. Click a site for its process flow diagram with every stream's live flow, each
unit's trains and load, and its tanks. The Economics tab draws the model's rules as curves and marks where
that site sits on each one.
- Follow a vehicle. Click a truck, barge or ship to see what it carries, from where to where, and its
route.
- Put a number on it. The Economy window runs the next 30 days twice, once as things are and once as if
nothing had broken, and prices the difference. It lists what stops next and when, and for any tank that has
lost its supplier, who else can deliver and at what price.
- Switch the market on. With Market on, prices come from how full tanks are and everything reacts to
them: buyers stock up when a chemical is cheap and wait when it is dear, customers buy less as prices rise,
and plants pass feed costs down the chain.
- Go back in time. Runs are exactly repeatable, so the whole simulation can jump back to any earlier
moment.
- Redraw the map. The map builder moves sites and redraws roads, lanes, pipelines and water, then runs
the result.
- Run it together. A host opens a session and shows a QR code. Everyone joins on a phone, takes a plant,
and cuts its rate, takes units down or stops trading with a neighbour. At the end, a damage summary compares
the session with the same run in which nothing was changed: what broke, which prices moved, and who caused
what.
The economic engine
Prices are not typed in anywhere. They come out of the physical state of the network, and in the market world
the network then reacts to them. docs/MODEL.md has every rule and constant; this is the short version.
How a price forms. Every chemical has a base price. Each side of a trade moves away from it by one number
of its own:
asking price = base × (1 + 0.5 × (1 − 2 × how full the seller's tank is)) full tank: −50%, empty: +50%
bid = base × (1 + 0.5 × the buyer's urgency) calm: base, nearly out: +50%
price paid = halfway between the two
Who a buyer buys from. Once an hour, each tank that is running short compares every seller and vehicle that
can physically make the delivery, and takes the lowest delivered cost:
delivered cost per tonne = asking price + freight rate × distance + urgency × $0.50 × trip hours
The market rules (the Market switch; world erwin-market-v1):
| Rule | What it does |
|---|
| Price-aware buying | A buyer orders early and fills to 90% when the best offer is 10% under base, and waits and fills to 50% when it is 10% over. Below one delivery time of stock it buys at any price. |
| Demand reacts to price | A customer wants normal demand × (price paid ÷ base)^−0.2, kept between 60% and 120% of normal. |
| Margin and cost pass-through | A plant whose margin falls to nothing turns down to its minimum rate. A rise in feed cost is added to its asking prices, so it moves down the chain a stage at a time. |
What a disruption costs. The same moment is run forward 30 days twice, once as it is and once as if nothing
had broken:
cost = extra lost sales + stock run down + extra energy + extra freight
Stock is counted because customers live off existing stock at first; without it a week-long outage would look
like an energy saving.
Damage in a shared session. The server keeps a second run in which nobody changed anything, and one run per
player that leaves out that player's moves. Damage is the customer sales lost in the session beyond that run:
product not delivered, plus demand priced out.
Known limits. The market is closed (no imports or exports), every trade is a spot trade, and nothing is
calibrated against real prices. A bid is never below base, so prices settle somewhat above base even when
nothing is wrong: read the changes, not the level.
How it is built
| Part | Where | What it is |
|---|
| Engine | engine/ | A C++20 simulation in 15-minute steps: tank signals, plant control, production, ordering, dispatch, transport, pipelines and the market rules. The same inputs give the same run, bit for bit. |
| Catalog | engine/data/catalog/ | Materials, 13 plant processes with 36 units, customers and sources, vehicle types. |
| Worlds | engine/data/worlds/ | erwin-world-v1 is the standard world; erwin-market-v1 is the same map with the market rules on. Both are built from the hand-drawn map in design/worlds/ by tools/worlds/build_erwin_world.py. |
| Server | apps/server/ | The engine behind an HTTP API: private sessions for the demo and shared rooms for group sessions. It also serves the web app. |
| Web app | web/ | TypeScript, React and three.js: the 3D map, the windows and charts, the host screen (/host/) and the phone screen (/play/). |
| Map builder | web/public/editor/ | A static page with no build step. |
| Project site | site/ | The page at petrogrid.xyz. |
| Deployment | deploy/ | The Docker image and the Fly.io setup. |
Run it locally
Needs a C++20 compiler, CMake 3.28 or newer with Ninja, and Node 20 or newer.
cmake --preset native-release
cmake --build --preset native-release
ctest --preset native-release # engine, server and the 60-day checks
cd web && npm ci && npm run build && cd ..
./build/native-release/crx-server --port 8080 --web-dir web/dist
Open http://localhost:8080 and press Start simulation. The host screen is at /host/ and the map builder
at /editor/.
Two tools help when changing a world:
python3 tools/worlds/build_erwin_world.py # size plants, tanks and fleet; writes the standard world
python3 tools/worlds/build_erwin_world.py --market # the same, with the market rules on
./build/native-release/crx-report --config '{"seed":42,"world":"erwin-world-v1"}' --days 60
crx-report runs a world for a number of days and prints customers, plants, tanks, orders, lanes and fleet use.
Its verdict is what the tests check: service at or above 95% at days 7, 30 and 60, every customer above 90%, and
no plant starved of feed.
What the model is, and is not
The physical side is the strong part: tonnes are tracked through recipes, tanks, pipelines and vehicles, so what
stops, in what order and after how long follows from capacities and stock. The dollar figures price that at
each chemical's base price.
It is not a model of a real company's network. The plants are typical ones sized so the network balances, and
the prices and response sizes are realistic in scale, not fitted to data. The market is closed (no imports or
exports) and every trade is a spot trade. Loading real plant data and prices is the next step; the engine is
the same.
More
docs/MODEL.md: the complete model, every rule and constant in the order the engine applies them.deploy/README.md: the Docker image, Fly.io and the domains.design/: the design system and the hand-drawn map.docs/OUTLINE.md: the original technical outline. The engine's rules follow it; the interface and the
default world have moved on from what it describes.
