--- name: digitaltwin description: Work with digital twins of physical things (assets, sensors, robots, sites) and their 3D, AR and holographic views. Define the twin, budget data, latency and rendering, keep it in sync and measure drift, label simulated values, and never send commands to equipment without interlocks and a person's yes. Use when a task builds, sizes, syncs or reads a digital twin. license: MIT metadata: version: "1.0" homepage: https://digitaltwin.md api: https://digitaltwin.md/api/v1 (optional, no key, stores nothing) terms: https://digitaltwin.md/terms --- # DigitalTwin Provided as is, at your own risk: a twin is an approximation, figures are estimates from the numbers you use and may be wrong, and nothing here is engineering, safety, legal or professional advice or a safety system. Terms: https://digitaltwin.md/terms. A digital twin is a model of a physical thing kept up to date with data from it. Treat it as a view, not the thing. Define it plainly, budget what it costs to keep fresh, check it against reality, and keep it away from the controls unless the person has set up interlocks and approves each command. Show your math once, in a short block. Skip routine narration. When this file has a "Your rules" section, those rules win over the defaults below. Settings you drafted or changed yourself count only after the person says yes. ## 1. Define the twin Write down, before building or answering anything: - **Assets**: an id, a type and where each one is. Use the person's ids. - **Sensors**: for each, the asset, the quantity and its SI unit, the sample rate, and the accuracy the person or the sensor's documentation states. Never invent an accuracy. - **Coordinate frames**: a name, the origin, axis directions, units and handedness for each frame, and the transform between frames with its source and date. Every position names its frame. - **Fidelity**: schematic (parts, links and states, not to scale), approximate (positions within a tolerance the person states) or survey-grade (from a dated survey with its stated accuracy). A fidelity label describes the model; it is not a certification. - **Time**: one time base (UTC), with the source time and the receive time on every reading. If something is missing, ask. Default when the person doesn't say: local metric frame (meters, right-handed, Z up) and approximate fidelity. ## 2. Budget data, latency and storage - Data: readings/s = assets x sensors per asset x rate. Mbps = readings/s x bytes per reading x (1 + overhead) x 8 / 10^6. Stored per day = the same bytes x 86,400, divided by compression, times copies. Use decimal units and say so. - Optional tool: `GET https://digitaltwin.md/api/v1/data_budget?assets=40&sensors_per_asset=12&rate_hz=10&bytes_per_reading=16&max_bandwidth_mbps=10`. - Latency: add every stage from sensor to view, typical and worst case. Include the wait for the next sample (half a period on average, a full period at worst). - Optional tool: `POST https://digitaltwin.md/api/v1/latency_budget` with `{ "stages": [{ "label": "Network", "ms": 60, "max_ms": 250 }], "target_ms": 250 }`. - Sample only as fast as the twin needs. Aggregate at the edge when a dashboard needs a summary, not every reading. ## 3. Keep the twin in sync and measure drift - Staleness = now - the reading's source time. Over the latency target, mark the value stale in what you show and say. - Drift = the twin's value minus a fresh measurement of the same thing, in the same unit and frame. Check on a schedule and log each check: time, value, measurement, drift, model version. - When drift exceeds the tolerance the person set, report it. Correct the twin, never the equipment: the physical thing is the reference. - A gap in data is a gap. Don't fill it with guesses unless the person asked, and label any filled value as estimated. ## 4. Know the gap between simulation and reality - Label every value as measured, estimated or simulated. Never present a simulated value as measured. - A simulation result is a hypothesis. State the model version, the inputs, the assumptions and what the model leaves out (friction, wear, temperature, people nearby, network faults...). - After a change, compare what the simulation predicted with what was measured, and record the difference. - A clean simulation does not make a change safe. ## 5. Never actuate from the twin without interlocks and a person - Default: the twin is read-only. Don't send commands to physical equipment from it. - If the person's rules allow it, commands go only through the equipment's own control system and safety interlocks, and only after a person says yes to each one. Never bypass, disable, override or simulate away an interlock. - Never act on stale data, during a fault or alarm, or when the twin and a fresh measurement disagree. - Emergency stops, guards and lockout procedures are physical and belong to trained people. They are outside the twin and outside this file. - If you are not sure, don't. Say what you would do and let a person decide. ## 6. Version the model - Give geometry, the sensor map and frame transforms a version. Record what changed, why and who agreed. - Keep the previous version so the twin can roll back. Link stored data and drift logs to the model version in use. ## 7. Set retention - Keep raw data for the retention period the person set, then delete or aggregate it. Default when unset: ask. - Cameras and microphones can capture people. Collect the least you need and follow the person's rules; legal holds are the person's call. ## 8. Budget visualization - Triangles per second = objects x triangles per object x refresh rate x views (1 for a screen, 2 for stereo, more for multi-view displays). Compare with a device figure the person gives, and keep headroom. - Optional tool: `GET https://digitaltwin.md/api/v1/render_budget?objects=1200&triangles_per_object=5000&refresh_hz=72&views=2&device_triangles_per_second=1000000000`. - Cut detail with distance before cutting refresh rate. Low refresh in a headset can make people unwell. - AR and holographic overlays can be misaligned with the real world. Never use one to position people, loads or tools where an error could hurt someone. ## 9. Report Five lines at most: what was checked, the numbers and their units, what is over a target or stale, what the tools can't check, and what needs a person's yes. Label estimates as estimates.