{ "openapi": "3.1.1", "info": { "title": "Twinworks Factory Simulation API", "version": "1.0.0", "summary": "Simulate a production line: throughput, lead time, WIP, OEE and the bottleneck, with CIs.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://twinworkssimulate.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Simulate a production line: throughput, lead time, WIP, OEE and the bottleneck, with CIs.", "description": "Runs the Twinworks discrete-event simulation on a factory model (sources, buffers, machines with failures and setups, assembly, conveyors, quality checks, operators and shift calendars). Returns throughput per hour, lead time, WIP with a Little’s-law check, per-station states and OEE, the bottleneck and a cost per good part, with Student-t confidence intervals across seeded replications.\n\nMethodology:\n- Discrete-event simulation with a binary-heap event calendar; ties are processed in (time, priority, insertion order) so every run is reproducible.\n- Parts are pushed downstream with blocking after service: a machine that cannot hand its part on is “blocked”; a machine without parts is “starved/idle”.\n- Each random quantity (arrivals, cycle times, failures, routing choices) has its own seeded stream, so scenario changes do not shift other random numbers (common random numbers).\n- Statistics are reset after the warm-up. Replications use derived seeds; intervals are Student-t intervals of the replication means.\n- Little’s law is checked as L (time-average WIP) versus λ·W (departure rate × mean time in system); differences above 5 % signal a non-stationary system or too short a run.\n- OEE = availability × performance × quality with planned time = time on shift minus planned maintenance; availability losses = breakdowns + setups; performance = ideal cycle time × parts ÷ run time (starving and blocking reduce it); quality = good ÷ processed.\n- Bottleneck: active-period method (Roser et al.) — at each moment the station with the longest uninterrupted active period (working, setup, repair, maintenance, waiting for an operator) is the bottleneck; overlaps between consecutive bottlenecks count as shifting.\n\nA simulation is only as good as its input data. Validate cycle times, failure data and routings against your shop floor before making investment decisions.", "tags": [ "apps" ], "x-mcp-tool": "twinworks_simulate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwinworksSimulateInput" }, "examples": { "example1": { "summary": "3-station line template, 5 replications", "value": { "template": "three-station-line", "replications": 5 } }, "example2": { "summary": "Own model: two machines and a buffer, deterministic", "value": { "model": "{\"name\":\"Two machines\",\"settings\":{\"horizon\":7200,\"warmup\":600},\"nodes\":[{\"id\":\"S\",\"type\":\"source\",\"arrival\":\"saturated\"},{\"id\":\"M1\",\"type\":\"machine\",\"cycle\":{\"type\":\"constant\",\"value\":30}},{\"id\":\"B\",\"type\":\"buffer\",\"capacity\":3},{\"id\":\"M2\",\"type\":\"machine\",\"cycle\":{\"type\":\"constant\",\"value\":40}},{\"id\":\"OUT\",\"type\":\"sink\"}],\"links\":[{\"from\":\"S\",\"to\":\"M1\"},{\"from\":\"M1\",\"to\":\"B\"},{\"from\":\"B\",\"to\":\"M2\"},{\"from\":\"M2\",\"to\":\"OUT\"}]}", "replications": 1 } }, "example3": { "summary": "Line with failures over 2 days, 3 replications", "value": { "template": "line-with-failures", "horizonHours": 48, "warmupMinutes": 120, "replications": 3 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwinworksSimulateResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "TwinworksSimulateInput": { "type": "object", "additionalProperties": false, "properties": { "model": { "title": "Model or project JSON", "description": "A Twinworks project (.twinworks.json, format \"twinworks-project\") or a bare model with \"nodes\" and \"links\". Times in seconds, lengths in metres. Leave empty and pick a template instead.", "type": "string", "maxLength": 400000 }, "template": { "title": "Or start from a template", "type": "string", "enum": [ "", "three-station-line", "line-with-failures", "assembly-two-feeders", "job-shop-routings", "bottleneck-buffer-sizing", "conveyor-packaging", "mm1-validation" ], "default": "" }, "horizonHours": { "title": "Run length per replication", "description": "Overrides the model setting (includes the warm-up).", "type": "number", "minimum": 0.01, "maximum": 2400, "x-unit": "h" }, "warmupMinutes": { "title": "Warm-up", "description": "Statistics are reset after the warm-up. Overrides the model setting.", "type": "number", "minimum": 0, "maximum": 144000, "x-unit": "min" }, "seed": { "title": "Random seed", "description": "Same seed → same result. Replication r uses a seed derived from it.", "type": "integer", "minimum": 0, "maximum": 4294967295 }, "replications": { "title": "Replications", "description": "Independent runs with different seeds; used for the confidence intervals.", "type": "integer", "minimum": 1, "maximum": 30 }, "confidence": { "title": "Confidence level", "type": "string", "enum": [ "", "0.9", "0.95", "0.99" ], "default": "" } }, "required": [] }, "TwinworksSimulateResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "required": [ "modelName", "replications", "confidence", "horizonSeconds", "warmupSeconds", "throughputPerHour", "leadTime", "wip", "little", "good", "scrap", "stations", "bottleneck", "cost" ], "properties": { "modelName": { "type": "string" }, "replications": { "type": "integer" }, "confidence": { "type": "number" }, "horizonSeconds": { "type": "number" }, "warmupSeconds": { "type": "number" }, "seeds": { "type": "array", "items": { "type": "integer" } }, "throughputPerHour": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } }, "leadTime": { "type": "object", "required": [ "mean", "p50", "p90", "p95", "max", "meanCi" ], "properties": { "mean": { "type": "number" }, "p50": { "type": "number" }, "p90": { "type": "number" }, "p95": { "type": "number" }, "max": { "type": "number" }, "meanCi": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } } } }, "wip": { "type": "object", "required": [ "avg", "max", "avgCi" ], "properties": { "avg": { "type": "number" }, "max": { "type": "number" }, "avgCi": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } } } }, "little": { "type": "object", "required": [ "L", "lambdaPerHour", "W", "lambdaW", "relError", "ok" ], "properties": { "L": { "type": "number" }, "lambdaPerHour": { "type": "number" }, "W": { "type": "number" }, "lambdaW": { "type": "number" }, "relError": { "type": "number" }, "ok": { "type": "boolean" } } }, "good": { "type": "integer" }, "scrap": { "type": "integer" }, "scrapPct": { "type": "number" }, "stations": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "servers", "processed", "throughputPerHour", "utilization", "states", "availability", "performance", "quality", "oee" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "servers": { "type": "integer" }, "processed": { "type": "integer" }, "throughputPerHour": { "type": "number" }, "utilization": { "type": "number" }, "utilizationCi": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } }, "states": { "type": "object", "additionalProperties": { "type": "number" } }, "availability": { "type": "number" }, "performance": { "type": "number" }, "quality": { "type": "number" }, "oee": { "type": "number" }, "oeeCi": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } }, "failures": { "type": "integer" }, "setups": { "type": "integer" } } } }, "buffers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "capacity": { "type": [ "integer", "null" ] }, "avgContents": { "type": "number" }, "maxContents": { "type": "number" }, "avgWait": { "type": "number" } } } }, "bottleneck": { "type": "object", "required": [ "primary", "ranking", "recommendations" ], "properties": { "primary": { "type": [ "string", "null" ] }, "ranking": { "type": "array" }, "recommendations": { "type": "array", "items": { "type": "string" } }, "votes": { "type": "object" } } }, "cost": { "type": "object", "required": [ "currency", "total", "costPerGoodPart" ], "properties": { "currency": { "type": "string" }, "total": { "type": "number" }, "costPerGoodPart": { "type": "number" }, "costPerGoodPartCi": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } }, "scrapCost": { "type": "number" }, "labour": { "type": "number" }, "machineTime": { "type": "number" }, "material": { "type": "number" }, "variable": { "type": "number" }, "overhead": { "type": "number" }, "revenue": { "type": "number" }, "profit": { "type": "number" } } }, "openInAppUrl": { "type": [ "string", "null" ] } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }