---
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. The tools here only size; they connect to nothing.
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.

---

# Reference

Use at your own risk. digitaltwin.md is provided as is, without warranty. Information here may be inaccurate, incomplete or not current, and is not verified; figures are estimates from the numbers you send and the formulas stated. Nothing here is engineering, safety, legal or professional advice, and nothing here is a safety system. digitaltwin.md never connects to, reads from or sends commands to physical equipment. Check everything yourself before you act on it. Terms: https://digitaltwin.md/terms

## Tools

Every tool below is read-only, takes GET query parameters or a POST JSON body at https://digitaltwin.md/api/v1/<tool>, and is also an MCP tool at https://digitaltwin.md/mcp. The MCP server also has note_missing, which leaves a short anonymous note and changes nothing else. Every response carries a disclaimer and the terms link.

### data_budget: Data budget: bandwidth and storage

Estimates how much data a twin moves and stores: readings per second, Mbps on the wire, GB per day and TB over the retention period, from your asset count, sensors per asset, sample rate, bytes per reading and overhead. Send one stream with the top-level fields, or several in `streams`. Compares with a bandwidth cap if you give one. Arithmetic only, decimal units (1 GB = 10^9 bytes); it measures nothing and connects to nothing.

- `assets` (integer, min 0, max 100000000): Number of assets (machines, robots, rooms...). For a single stream.
- `sensors_per_asset` (number, min 0, max 1000000): Sensors or channels per asset (an average is fine). For a single stream.
- `rate_hz` (number, min 0, max 10000000): Readings per second per sensor. For a single stream.
- `bytes_per_reading` (number, min 0, max 1000000000): Payload bytes per reading, before overhead. For a single stream.
- `streams` (array): Several streams instead of the top-level fields: [{ label, assets, sensors_per_asset, rate_hz, bytes_per_reading }].
- `overhead_pct` (number, min 0, max 1000): Headers, framing and timestamps added to each reading, in % of the payload. Applied to wire and stored bytes. Default 20.
- `retention_days` (number, min 0, max 36500): Days the raw data is kept. Default 90.
- `compression_ratio` (number, min 1, max 1000): Your expected storage compression (2 means half the size). Applied to storage only. Default 1 (none).
- `storage_copies` (integer, min 1, max 20): Stored copies (replicas or backups) to count. Default 1.
- `max_bandwidth_mbps` (number, min 0, max 10000000): Your bandwidth cap in Mbps, to compare with. Optional.

Example: `POST https://digitaltwin.md/api/v1/data_budget` with `{"assets":40,"sensors_per_asset":12,"rate_hz":10,"bytes_per_reading":16,"overhead_pct":20,"retention_days":90,"max_bandwidth_mbps":10}`, or `GET https://digitaltwin.md/api/v1/data_budget?assets=40&sensors_per_asset=12&rate_hz=10&bytes_per_reading=16&overhead_pct=20&retention_days=90&max_bandwidth_mbps=10`.

### latency_budget: Latency budget: sensor to view

Adds up the latency of each stage between a physical reading and the twin's view (sensing, edge processing, network, ingest, update, render) and compares the total with your target. Gives typical and worst-case totals, the slack, and the largest stage. Optionally adds the wait caused by the sample rate. Stage numbers are yours; arithmetic only.

- `stages` (array, required): Pipeline stages in order: [{ label, ms, max_ms }]. ms is typical; max_ms (optional) is your worst case.
- `target_ms` (number, min 0.001, max 86400000, required): Your update latency target, sensor to view, in ms.
- `sample_rate_hz` (number, min 0.0001, max 10000000): Sensor sample rate. Adds the wait for the next sample: on average half a period, at worst a full period. Optional.

Example: `POST https://digitaltwin.md/api/v1/latency_budget` with `{"stages":[{"label":"Sensor read","ms":5,"max_ms":10},{"label":"Edge filter","ms":20,"max_ms":40},{"label":"Network","ms":60,"max_ms":250},{"label":"Twin update","ms":30,"max_ms":80},{"label":"Render","ms":17,"max_ms":33}],"target_ms":250,"sample_rate_hz":10}`.

### render_budget: Render budget: 3D, AR and holographic views

Checks a twin's view against a display device's triangle budget that you enter: triangles per frame and per second (objects x triangles per object x refresh rate x views), the share of the budget used, headroom, and how many objects or what refresh rate fit your headroom target. Use views = 2 for stereo headsets and more for multi-view displays. Triangle count only; it does not measure your device.

- `objects` (integer, min 0, max 100000000): Objects drawn each frame. Ignored when `groups` is sent.
- `triangles_per_object` (number, min 0, max 1000000000): Average triangles per object, at the detail level shown. Ignored when `groups` is sent.
- `groups` (array): Several kinds of object instead: [{ label, count, triangles }], triangles per object.
- `refresh_hz` (number, min 1, max 1000, required): Frames per second the view must hold.
- `views` (integer, min 1, max 256): Views rendered per frame: 1 for a screen, 2 for stereo, more for multi-view displays. Default 1.
- `device_triangles_per_second` (number, min 1, max 1000000000000000, required): Triangles per second your device sustains, from your own test or the maker's figure you trust.
- `headroom_target_pct` (number, min 0, max 90): Share of the device budget to keep free. Default 20.

Example: `POST https://digitaltwin.md/api/v1/render_budget` with `{"objects":1200,"triangles_per_object":5000,"refresh_hz":72,"views":2,"device_triangles_per_second":1000000000,"headroom_target_pct":30}`, or `GET https://digitaltwin.md/api/v1/render_budget?objects=1200&triangles_per_object=5000&refresh_hz=72&views=2&device_triangles_per_second=1000000000&headroom_target_pct=30`.

### build_settings: Write your settings into the skill

Takes `preset` plus any setting below, and `format` (section or skill). Returns the sections, the settings as JSON, a skill link and an install line. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.

## Settings

Numbers or fixed choices only. `unset` clears an optional setting. Catalog: https://digitaltwin.md/api/v1/settings

- `actuation` (actuation, core): Actuation from the twin; never | ask | interlocks; default never
- `sim_before_change` (actuation): Simulation before changes; required | optional
- `latency_target_ms` (sync, core): Update latency target; ms, 1 to 3600000; default 1000
- `drift_check_min` (sync): Check drift every; min, 1 to 10080
- `retention_days` (data, core): Keep raw data for; days, 1 to 36500; default 90
- `max_bandwidth_mbps` (data): Max bandwidth; Mbps, 0.01 to 1000000
- `fidelity` (model): Fidelity level; schematic | approximate | survey
- `frame` (model): Coordinate frame; local_metric | enu | geodetic | ecef
- `model_versioning` (model): Version the model; every_change | release
- `render_headroom_pct` (views): Keep render headroom of at least; %, 0 to 90

## Presets

- `core`: Actuation, latency target and retention. Everything else follows the skill's defaults.
- `recommended`: A cautious start: approximate fidelity in a local metric frame, drift checks every 15 minutes, simulate before changes, version every change.
- `monitoring`: A read-only dashboard twin: schematic fidelity, frequent drift checks, versions at each release.
- `site_review`: Survey-grade geometry in a geodetic frame for walkthroughs and AR overlays, with extra render headroom for headsets.
- `strict`: Tight checks: drift every 5 minutes, a 10 Mbps cap, simulate before every change, version every change.