line-twin

Bottleneck analysis for a production line — on your measured data. Load the cycle times you actually recorded on the floor: the tool finds the constraint, validates its model against the line's real output, and quantifies what each fix is worth.

On a line of N stations in series, exactly one — the slowest — sets the pace: upstream the buffers fill, downstream the stations starve. line-twin runs a discrete-time twin on your measurements, locates the constraint, then replays the line with the bottleneck fixed to quantify the throughput you would actually gain — not a back-of-the-envelope ceiling.

This is an analysis tool, not just a simulator. The engine is a discrete-time model (validated by its invariants: parts are conserved, the bottleneck is the slowest station, throughput is capped). What is real: the inputs (measured cycle times, variability, observed throughput) and the outputs (the constraint, the model validated against the line, a quantified ROI). A digital twin is a model; this one works on real data and checks itself against reality.

Quick start

pip install -e .
python -m linetwin analyze examples/line.json      # measured record + observed throughput

line: 4 stations, buffer 5 - 600s simulated on measured cycle times

station     cycle    util    made
Load         1.8s     54%     174
Weld         2.4s     68%     168
Inspect      3.6s     99%     162  <-- BOTTLENECK
Pack         2.0s     56%     162

throughput   16.2 parts/min   (ceiling 16.7)   efficiency 97%   WIP 13

model vs line   observed 15.2 -> modeled 16.2  (+6.6%)  [OK] model matches the line

what to fix:
  - parallelise Inspect (2 machines -> 1.80s)  ->  24.3 parts/min (+50.0%), new bottleneck Weld
  - speed Inspect to the 2nd-slowest cycle (2.40s)  ->  24.1 parts/min (+48.8%), new bottleneck Weld

Your line, in CSV (one row per station, cv optional), with the observed output:

station,cycle_s,cv
Load,1.8,0.10
Weld,2.4,0.15
Inspect,3.6,0.08
Pack,2.0,0.12

python -m linetwin analyze my_line.csv --observed 15.2 --json

What it does

• Ingests measured data — CSV or JSON describing your stations (cycle time, variability cv, buffer size, the line's observed throughput).
• Finds the bottleneck — effective load = cycle time × utilisation, which is robust rather than just "the biggest number".
• Validates the model — compares modeled throughput against the line's real output, so you know whether to trust the twin before acting on it.
• Quantifies ROI — replays the line with the bottleneck parallelised or sped up and reports the throughput actually gained, not a theoretical ceiling.
• Pure stdlib, zero dependencies, everything JSON-serialisable (--json).

From Python:

from linetwin import load, analyze

spec = load("examples/line.json")
report = analyze(spec, duration=600)
print(report["bottleneck"], report["recommendations"][0])

Need a raw simulation from cycle times, with no file? python -m linetwin run --cycles 2,2,3.5,2 --duration 600.

Architecture

Module	Role
loader.py	Loads a measured record (CSV/JSON) and builds the twin on top of it
analysis.py	Bottleneck + model validation vs observed throughput + quantified recommendations (what-if by replay)
line.py	Station (state machine) + ProductionLine (the model engine)
metrics.py	bottleneck detection, throughput, efficiency, WIP, JSON snapshot
cli.py	linetwin analyze <file> · linetwin run

Tests

pytest -q          # 12 passed

The engine's invariants (parts conserved, bottleneck = slowest station, throughput capped, upstream saturating / downstream starving) and the analysis tool: CSV/JSON loading, validation against observed output, and the fact that fixing a bottleneck really does raise modeled throughput.

Stack

Python 3.9+ · zero dependencies · pytest.

---

MIT · an honest, testable line-analysis tool — the engine is a validated model, the inputs are measured and the verdicts are real.

---

Part of the HiddenGrid edge stack

Eight small repos, one chain: control → transport → hub → supervision. Each one stands alone and runs offline; together they are a working local-first stack with no cloud account anywhere in it.

	Repo	What it does
Control	greenhouse	ESP32/MicroPython greenhouse controller — light, aeration, heat and pulse irrigation. Safety lives in firmware.
Control	coopilot	ESP32/MicroPython coop controller — pop-hole door with anti-pinch, overcurrent and timeout interlocks.
Transport	gorilla-tsc	Lossless Gorilla time-series compression — the codec the edge→hub link stores with.
Hub	plexus	MQTT ingest → compressed store → drift & stuck-sensor detection → one dashboard. Stdlib only.
Product	serra	Multi-site supervision for greenhouses & aquaponics, built on plexus.
Industry	industrial-retrofit	Real Modbus-TCP off a legacy PLC → clean telemetry, anomalies, live OEE.
Industry →	line-twin	Measured cycle times → the bottleneck → the ROI of fixing it.
Industry	kiln-retrofit	Type-K thermocouple → PID ramp/soak → heatwork & pyrometric cones.

You are here: line-twin.